Start with the operation
Nia, the fictional desk operator, receives two reports: “the tool was blocked” and “the tool did not ask.” Before changing a setting, she asks what operation each report actually describes.
That question prevents a common repair mistake. A missing tool cannot be enabled by approving a call. An explicit policy denial is not an unanswered question. A successful approval cannot make an unwritable file writable. Each failure belongs to a different boundary.
Five gates that must not be collapsed
The following is a diagnostic map, not a promise that every host implements five checks in this exact order.
| Gate | Question it answers | What passing it does not establish |
|---|---|---|
| Tool availability | Is this capability enabled and reachable through the current session’s actual tool surface? | That any particular invocation is approved. |
| Approval policy | Does the applicable declaration, user policy, and effective wrapper mode allow, prompt, or deny this call? | A domain grant, provider acknowledgement, or OS privilege. |
| Domain authority | Does the application permit this action on this object and revision? | That host approval or filesystem access will succeed. |
| Provider safety | Are applicable provider requirements satisfied, including pending computer safety checks handled by the wrapper? | That the operation is correct or allowed by the OS. |
| OS or host authority | Can the actual process or client perform the requested effect at the actual destination? | That the effect was wanted, completed, or correctly reported. |
The distinction between availability and presentation is especially important. A discoverable tool can be enabled without appearing as a top-level schema. The supplied xd:// implementation can reach enabled mounted tools and enabled top-level tools through its canonical map. Conversely, a name in old conversation text does not establish present availability.
ToolLoadMode in packages/agent/src/types.ts describes presentation. resolveXdevTool() in packages/coding-agent/src/tools/xdev.ts checks the enabled union before returning a tool. Neither is a grant for an arbitrary operation. The SDK’s restricted-session options are also separate construction controls; do not treat a familiar launch flag or a displayed name as a complete inventory of every runtime path.
Predict two different refusals
Inspect these inputs from Boundary Desk as data:
{
"case": "boundary-no-ui",
"approval": "exec",
"args": { "action": "publish" },
"mode": "always-ask",
"ui": false
}
Now compare boundary-deny-before-handler. Its declaration includes policy: "deny", its original action is blocked, and its proposed handler replacement is inspect.
Prediction: will either case display a selection? Will the replacement rescue the denied call?
Recorded answer: neither displayed a selection and neither reached the inert executor. Their traces nevertheless differed. boundary-no-ui recorded one tool_call, then approval requested and approval resolved false with reason no interactive UI available. boundary-deny-before-handler recorded no tool_call and no approval lifecycle pair: the direct wrapper’s original-input policy denial stopped before its handler could supply a replacement.
Thus zero prompts does not mean automatic approval. It can mean that the call was denied before prompting, that prompting was required but unavailable, or that policy admitted the call without a prompt. The decision and execution evidence distinguish those cases.
Make a small decision record
For a blocked or unexpectedly unprompted call, begin with the exact observed tool name, call ID if available, arguments, path or device address, and current session/cwd scope. Then identify the effective mode, applicable policy key, tool declaration, and host UI capability. Finally, record whether the underlying operation executed and what effect was actually inspected.
For this workbook, those facts come from the supplied cases and recorded outcomes—not from a request to an agent to investigate your installation. In later operational work, keep complete sensitive arguments and diagnostics private.
Paper checkpoint: explain why boundary-no-ui is not an OS permission-denied file write. Worked answer: it stops in ExtensionToolWrapper.execute() before the inert tool runs; no file primitive is involved. An OS denial belongs to a later operation, such as the separate fallback case studied at Boundary Desk.
Failure boundary: the private scenario report uses a structural runner adapter and explicitly instrumented executors. It is not a record of a provider choosing a tool, a real person answering, or every possible dispatch path.
Source anchors: packages/agent/src/types.ts — AgentTool, ToolLoadMode, ToolApprovalDecision; packages/coding-agent/src/sdk.ts — createAgentSessionScoped; packages/coding-agent/src/tools/xdev.ts — resolveXdevTool; packages/coding-agent/src/extensibility/extensions/wrapper.ts — ExtensionToolWrapper.execute.
Tool permissions and approvals · Source chapter: permissions/start-with-the-operation. Original evidence remains scoped to its recorded snapshot.