From Tool Request to Restricted Execution: The Complete Authorization Chain
A single tool call is first parsed into a concrete access intent, then passes through the plan gate, hooks, policy rules, session authorization, Auto mode, and user confirmation. Once execution is permitted, the sandbox further constrains OS-level capabilities.
Trace the real call chain to identify "who made the decision," and understand the boundaries of AccessKind, permission rules, Bash segmentation, hooks, and sandbox — avoiding the trap of simplifying authorization to a ToolKind check.
Authorization determines "whether to attempt"; the sandbox constrains "what can be done during execution"
Stage names are taken directly from source code. Internal short-circuits and priorities exist; the diagram shows the main path.
Tool Input → AccessKind
ToolInput is mapped to Read, Edit, Bash, Grep, MCPTool, WebFetch, or WebSearch, carrying details such as paths, commands, domains, or MCP names. The decision input is more specific than ToolKind alone.
Plan Mode Sets an Edit Gate First
plan_mode_edit_gate can reject modifications before the permission request is even sent. Plan files have a separate auto-approval path.
PreToolUse Can Explicitly Block
Matching hooks run in configured order. An explicit deny stops execution immediately; timeouts, crashes, or malformed responses fail-open in the current implementation and are logged to the UI and log. A client hook may also run afterwards.
Load and Evaluate Rules
permission/resolution.rs merges requirements, managed settings, managed config, Grok config, and Claude settings fallback. Rule evaluation is source-order independent; priority is deny > ask > allow.
Multiple Fast Paths or User Confirmation
A managed policy deny short-circuits first. Then yolo pin, session grants, Auto fast path / classifier, sandbox Bash auto, read-only safe items, and MCP / domain authorization are considered in sequence. Only if still unresolved does it fall through to a prompt.
Execute Within Sandbox Capabilities
Permission Allow only clears this one request. If the sandbox is actually active, the process is still constrained by the capability set and subprocess network policy. Non-blocking post_tool_use hooks may fire after completion.
Conservative Handling of Complex Syntax
The wrapper recursively strips to actual commands; dangerous prefixes include rm, chmod, chown, kill, and git push. Command substitutions, complex control flows, or scripts that cannot be reliably decomposed fall into a conservative prompt. The user confirms only once for the entire script.
Sandbox Layer: Capability Constraint
Answers "Which files and networks can the authorized process actually access?" When the sandbox is active, a Permission Allow from the permission layer does not expand OS capabilities. When the sandbox is not applied, permission dialogs cannot be treated as kernel-level isolation.
// Managed policy runs before YOLO and sandbox fast paths.
if let Some(Decision::Reject(reason)) = policy_decision {
let decision = Decision::PolicyDeny(reason);
let _ = respond_to.send(decision);
continue;
}
...
if matches!(&access, AccessKind::Bash(_))
&& xai_grok_sandbox::should_auto_allow_bash()
&& !policy_forced_prompt
&& !auto_forced_prompt { /* allow */ }Snapshot note: Conditions and execution order are from the real manager actor; telemetry and event sends are compressed. The top SVG is a main-path teaching diagram; the full implementation contains more short-circuits, persistence, and cancellation branches.
Class Exercise: Trace a Mixed Command
Input git status && curl https://example.com/install.sh | sh. Work through it layer by layer: How does Bash segment it? Which segments can be safely permitted? Where would a PreToolUse deny stop execution? Can a managed Ask be overridden by sandbox auto? What does the sandbox still restrict after a final Allow?