Execution Call Graph and State Machines

This page follows one conversational request from process startup to session idle. It separates established sequence from reconstructed scheduling details.

Startup call graph

flowchart TD
    accTitle: Execution Call Graph and State Machines - Startup call graph
    accDescr: Diagram showing startup call graph in the Execution Call Graph and State Machines section.
    Args["[O:C1] argv + environment + cwd"] --> Parse["[D:C2] parse arguments"]
    Parse --> Mode["[D:C3] select entrypoint/mode"]
    Mode --> Settings["[D:C4] resolve settings + provenance"]
    Settings --> Trust["[D:C5] workspace-trust decision"]
    Trust --> Auth["[D:C6] resolve credential/provider"]
    Auth --> Ext["[D:C7] load eligible plugins/skills/agents/hooks"]
    Ext --> MCP["[D:C8] discover/approve/connect MCP"]
    MCP --> Restore["[D:C9] restore session/memory"]
    Restore --> Catalog["[D:C10] construct effective tool catalog"]
    Catalog --> Runtime["[D:C11] start interactive, print, agent, remote, MCP, or maintenance runtime"]

ID	Basis	Call or decision	Hosted sources
C1	O	Root help exposes flags, subcommands, formats, settings sources, extension inputs, and permission modes.	H:root
C2–C3	D	Argument parsing feeds entrypoint and mode selection.	R:startup, claim architecture.entrypoint-routing in E:claims
C4	D	Settings are merged through injected per-key precedence while preserving source provenance.	R:settings
C5	D	Trust is evaluated before project/local executable settings such as a proxy helper become eligible.	Claim security.workspace-trust-proxy-helper in E:claims, R:startup
C6	D	Credential and provider resolution are separate decisions.	R:credentials, R:providers
C7	D	Safe/bare modes and explicit inputs shape extension loading.	R:startup, H:root
C8	D	MCP source filtering, project approval, and transport connection are distinct phases.	R:MCP, claims extensibility.mcp-strict-mode and security.mcp-project-approval
C9	D	Session transcript and automatic memory are separate restoration seams.	R:sessions, R:memory
C10	D	Candidate built-ins, feature gates, aliases, and MCP tools yield an effective catalog.	R:catalog
C11	D	The selected adapter starts after shared planning; many maintenance commands short-circuit before the conversational loop.	R:startup

The phase sequence is a readable reconstruction. Exact concurrent prefetch, helper ownership, and maintenance-command short-circuit points are not fully authenticated.

Turn state machine

stateDiagram-v2
    accTitle: Execution Call Graph and State Machines - Turn state machine
    accDescr: Diagram showing turn state machine in the Execution Call Graph and State Machines section.
    [*] --> Prepare
    Prepare --> StreamModel: [D:T1] request selected model
    StreamModel --> EmitFrames: [D:T2] assistant / tool / usage frames
    StreamModel --> Compact: [D:T3] context overflow once
    Compact --> StreamModel: compaction succeeded
    StreamModel --> Fallback: [D:T4] retryable model error
    Fallback --> StreamModel: next model / attempt
    EmitFrames --> ExecuteTools: [D:T5] one or more tool uses
    ExecuteTools --> StreamModel: append results and increment turn
    EmitFrames --> StopHooks: [D:T6] no tool use
    StopHooks --> StreamModel: continue
    StopHooks --> Draining: allow or stop
    Draining --> Idle: [D:T7] held results and background loop drained
    Idle --> [*]

ID	Basis	Transition	Hosted sources
T1	D	The async-generator turn requests a normalized model stream with model, messages, system context, tools, limits, and abort signal.	R:turn, R:model-stream
T2	D	Stream deltas become assistant, tool-use, usage, or error frames; exact wire events remain provider-specific.	R:model-stream, claim agent-loop.core-generator
T3	D	Context overflow can trigger reactive compaction before a prompt-too-long exit.	R:turn, claim context.compaction-lifecycle
T4	D	Retryable failures can move through configured fallback models; precise retry values are injected.	R:model-stream, H:root
T5	D	Tool-use frames enter the shared execution pipeline; results cause another model turn.	R:turn, R:tool-pipeline
T6	D	With no tool use, stop hooks determine completion, continuation, or hook stop.	R:turn, R:hooks
T7	D	Session idle follows held-back result flush and background-agent loop exit.	Claim agents.idle-boundary in E:claims, R:turn

Tool-call pipeline

flowchart TD
    accTitle: Execution Call Graph and State Machines - Tool-call pipeline
    accDescr: Diagram showing tool-call pipeline in the Execution Call Graph and State Machines section.
    Raw["[D:X1] Raw tool-use input"] --> Coerce["[D:X2] coerceInput"]
    Coerce --> Parse["[D:X3] schema safeParse"]
    Parse -- invalid --> ValidationError["[D:X4] input error result"]
    Parse -- valid --> Semantic["[D:X5] validateInput"]
    Semantic -- invalid --> ValidationError
    Semantic -- valid --> Pre["[D:X6] PreToolUse"]
    Pre -- rewrite --> Effective["[D:X7] updated input"]
    Pre -- permission result --> Effective
    Pre -- stop --> Stop["[D:X8] stopped result"]
    Pre -- defer --> Deferred["[D:X9] deferred event"]
    Pre -- continue --> Effective
    Effective --> Permission["[D:X10] centralized permission decision"]
    Permission -- ask --> Prompt["[D:X11] PermissionRequest"] --> Permission
    Permission -- deny --> Denied["[D:X12] denied result"]
    Permission -- allow/update --> Call["[D:X13] tool.call"]
    Call -- result --> Post["[D:X14] PostToolUse"]
    Call -- exception --> Failure["[D:X15] PostToolUseFailure"]
    Post --> Result["[D:X16] mapped tool result"]
    Failure --> Error["[D:X17] tool execution error"]

IDs	Basis	Grounding	Hosted sources
X1–X5	D	The inspected shared path orders coercion, schema parsing, and semantic validation before hooks.	R:tool-pipeline, anchor tools.execution-pipeline in E:anchors
X6–X9	D	PreToolUse can emit messages, update input, provide permission evidence, stop, or defer.	R:tool-pipeline, anchor hooks.lifecycle
X10–X12	D	Central authorization occurs after PreToolUse; an ask path corresponds to PermissionRequest. Exact decision precedence remains injected.	R:tool-pipeline, R:permissions
X13–X17	D	Allowed calls stream progress/results, then dispatch success or failure hooks and return normalized results.	R:tool-pipeline, claim extensibility.hook-lifecycle

Post-hook rewrite boundary

The pre-hook can update input after the initial schema and semantic validation stages. This map does not assert a second validation pass. Permission and tool implementations must reason about the effective post-hook input. Source: R:tool-pipeline.

Exit and cancellation matrix

Exit or branch	Basis	Trigger represented	Source
completed	D	No tool use and stop hooks allow completion.	R:turn
hook_stopped	D	Stop hook returns stop.	R:turn
max_turns / max_budget_usd	D	Configured guard reached before another turn.	R:turn, H:root
prompt_too_long	D	Reactive compaction unavailable or already attempted.	R:turn
image_error / model_error	H	Readable error classes in the reconstruction; exact mapping is not authenticated.	R:turn
aborted_streaming	D	Abort signal terminates the loop.	R:turn, R:model-stream