diff --git a/docs/SDK_DEEP_DIVE.md b/docs/SDK_DEEP_DIVE.md index c59db7a74..ec9e0ca12 100644 --- a/docs/SDK_DEEP_DIVE.md +++ b/docs/SDK_DEEP_DIVE.md @@ -1,109 +1,128 @@ # Claude Agent SDK Deep Dive -Findings from reverse-engineering `@anthropic-ai/claude-agent-sdk` v0.2.29–0.2.34 to understand how `query()` works, why agent teams subagents were being killed, and how to fix it. Supplemented with official SDK reference docs. +Notes from reading the type surface of `@anthropic-ai/claude-agent-sdk` to +understand how `query()` works, how nanoclaw drives it (streaming input, hooks, +resume), and where the observable behaviour lives. + +**Verified against `@anthropic-ai/claude-agent-sdk@0.3.197`** (`sdk.d.ts`, +`package.json`, `README.md` in the published tarball). This doc began as a +reverse-engineering pass on the minified `0.2.29–0.2.34` bundles; everything +below is now checked against the shipped `.d.ts` declarations. The parts that +were only ever minified-bundle archaeology (internal generator/function names) +have been dropped — see [What changed since the 0.2.x analysis](#what-changed-since-the-02x-analysis) +at the end. + +The repo consumer this doc serves is +`container/agent-runner/src/providers/claude.ts` (+ `types.ts`): it calls +`query()` with a push-based `AsyncIterable` prompt, four hook families, an +allow/deny tool policy, and `resume` for session continuation. ## Architecture ``` -Agent Runner (our code) - └── query() → SDK (sdk.mjs) - └── spawns CLI subprocess (cli.js) +Agent Runner (claude.ts) + └── query({ prompt, options }) → SDK (sdk.mjs) + └── spawns the Claude Code CLI as a child process └── Claude API calls, tool execution - └── Task tool → spawns subagent subprocesses + └── Task/Agent tool → spawns subagents ``` -The SDK spawns `cli.js` as a child process with `--output-format stream-json --input-format stream-json --print --verbose` flags. Communication happens via JSON-lines on stdin/stdout. +The SDK resolves a native Claude Code binary (overridable via +`options.pathToClaudeCodeExecutable`, which nanoclaw sets to `/pnpm/claude`) and +spawns it as a child process. Communication is JSON-lines over the child's +stdin/stdout. The `Transport` / `SpawnOptions` / `SpawnedProcess` interfaces and +the `spawnClaudeCodeProcess` option (for spawning into a VM/container) confirm +this shape from the public types. All the heavy lifting — the agent loop, tool +execution, background tasks, subagent orchestration — runs inside the CLI +subprocess; `query()` is a transport + control-channel wrapper. -`query()` returns a `Query` object extending `AsyncGenerator`. Internally: - -- SDK spawns CLI as a child process, communicates via stdin/stdout JSON lines -- SDK's `readMessages()` reads from CLI stdout, enqueues into internal stream -- `readSdkMessages()` async generator yields from that stream -- `[Symbol.asyncIterator]` returns `readSdkMessages()` -- Iterator returns `done: true` only when CLI closes stdout - -Both V1 (`query()`) and V2 (`createSession`/`send`/`stream`) use the exact same three-layer architecture: +`query({ prompt, options })` returns a `Query` object that +`extends AsyncGenerator`. You iterate it to receive events; +its methods (`interrupt`, `setModel`, `streamInput`, `close`, …) are the control +channel to the running CLI. +```typescript +export declare function query(_params: { + prompt: string | AsyncIterable; + options?: Options; +}): Query; ``` -SDK (sdk.mjs) CLI Process (cli.js) --------------- -------------------- -XX Transport ------> stdin reader (bd1) - (spawn cli.js) | -$X Query <------ stdout writer - (JSON-lines) | - EZ() recursive generator - | - Anthropic Messages API -``` - -## The Core Agent Loop (EZ) - -Inside the CLI, the agentic loop is a **recursive async generator called `EZ()`**, not an iterative while loop: - -``` -EZ({ messages, systemPrompt, canUseTool, maxTurns, turnCount=1, ... }) -``` - -Each invocation = one API call to Claude (one "turn"). - -### Flow per turn: - -1. **Prepare messages** — trim context, run compaction if needed -2. **Call the Anthropic API** (via `mW1` streaming function) -3. **Extract tool_use blocks** from the response -4. **Branch:** - - If **no tool_use blocks** → stop (run stop hooks, return) - - If **tool_use blocks present** → execute tools, increment turnCount, recurse - -All complex logic — the agent loop, tool execution, background tasks, teammate orchestration — runs inside the CLI subprocess. `query()` is a thin transport wrapper. ## query() Options -Full `Options` type from the official docs: +The full `Options` type (`sdk.d.ts` ~line 1256). This surface grew a lot since +0.2.x; the table below covers the members that matter for SDK consumers, with +the ones nanoclaw sets marked ✱. -| Property | Type | Default | Description | -|----------|------|---------|-------------| -| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations | -| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access | -| `agents` | `Record` | `undefined` | Programmatically define subagents (not agent teams — no orchestration) | -| `allowDangerouslySkipPermissions` | `boolean` | `false` | Required when using `permissionMode: 'bypassPermissions'` | -| `allowedTools` | `string[]` | All tools | List of allowed tool names | -| `betas` | `SdkBeta[]` | `[]` | Beta features (e.g., `['context-1m-2025-08-07']` for 1M context) | -| `canUseTool` | `CanUseTool` | `undefined` | Custom permission function for tool usage | -| `continue` | `boolean` | `false` | Continue the most recent conversation | -| `cwd` | `string` | `process.cwd()` | Current working directory | -| `disallowedTools` | `string[]` | `[]` | List of disallowed tool names | -| `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding | -| `env` | `Dict` | `process.env` | Environment variables | -| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime | -| `fallbackModel` | `string` | `undefined` | Model to use if primary fails | -| `forkSession` | `boolean` | `false` | When resuming, fork to a new session ID instead of continuing original | -| `hooks` | `Partial>` | `{}` | Hook callbacks for events | -| `includePartialMessages` | `boolean` | `false` | Include partial message events (streaming) | -| `maxBudgetUsd` | `number` | `undefined` | Maximum budget in USD for the query | -| `maxThinkingTokens` | `number` | `undefined` | Maximum tokens for thinking process | -| `maxTurns` | `number` | `undefined` | Maximum conversation turns | -| `mcpServers` | `Record` | `{}` | MCP server configurations | -| `model` | `string` | Default from CLI | Claude model to use | -| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Structured output format | -| `pathToClaudeCodeExecutable` | `string` | Uses built-in | Path to Claude Code executable | -| `permissionMode` | `PermissionMode` | `'default'` | Permission mode | -| `plugins` | `SdkPluginConfig[]` | `[]` | Load custom plugins from local paths | -| `resume` | `string` | `undefined` | Session ID to resume | -| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID | -| `sandbox` | `SandboxSettings` | `undefined` | Sandbox behavior configuration | -| `settingSources` | `SettingSource[]` | `[]` (none) | Which filesystem settings to load. Must include `'project'` to load CLAUDE.md | -| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output | -| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` | System prompt. Use preset to get Claude Code's prompt, with optional `append` | -| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration | +| Property | Type | Notes | +|----------|------|-------| +| `abortController` | `AbortController` | Cancels the query and tears down resources | +| `additionalDirectories` ✱ | `string[]` | Extra absolute dirs Claude may access | +| `agent` | `string` | Name of an agent (from `agents`/settings) to apply to the *main* thread (`--agent`) | +| `agents` | `Record` | Programmatic subagents invoked via the Agent tool | +| `allowedTools` ✱ | `string[]` | Tool names auto-allowed without prompting. `'Skill'` here is deprecated — use `skills` | +| `disallowedTools` ✱ | `string[]` | Tool names removed from the model's context entirely | +| `toolAliases` | `Record` | Redirect a model-emitted tool name to another (e.g. `{ Bash: 'mcp__workspace__bash' }`); single-hop | +| `tools` | `string[] \| { type:'preset'; preset:'claude_code' }` | Base set of built-in tools; `[]` disables all | +| `canUseTool` | `CanUseTool` | Per-call permission callback | +| `continue` | `boolean` | Continue the most recent conversation in `cwd`; mutually exclusive with `resume` | +| `cwd` ✱ | `string` | Working directory (default `process.cwd()`) | +| `env` ✱ | `{ [k]: string \| undefined }` | **Replaces** the subprocess env entirely — spread `process.env` yourself if you need `PATH`/`HOME` | +| `executable` / `executableArgs` | `'bun'\|'deno'\|'node'` / `string[]` | JS runtime + extra runtime args | +| `extraArgs` | `Record` | Raw extra CLI flags (`null` = boolean flag) | +| `fallbackModel` | `string` | Comma-separated fallback list; primary is re-tried each user turn | +| `enableFileCheckpointing` | `boolean` | Enables `Query.rewindFiles()` | +| `forkSession` | `boolean` | On resume, fork to a new session ID instead of continuing | +| `betas` | `SdkBeta[]` | Beta features (only `'context-1m-2025-08-07'`) | +| `hooks` ✱ | `Partial>` | Event callbacks | +| `includeHookEvents` | `boolean` | Emit `hook_started`/`hook_progress`/`hook_response` for all hook types | +| `includePartialMessages` | `boolean` | Emit `SDKPartialAssistantMessage` streaming events | +| `forwardSubagentText` | `boolean` | Forward subagent text/thinking (not just tool blocks) with `parent_tool_use_id` | +| `thinking` | `ThinkingConfig` | `{type:'adaptive'}` / `{type:'enabled',budgetTokens}` / `{type:'disabled'}`; supersedes `maxThinkingTokens` | +| `effort` ✱ | `EffortLevel` | `'low'\|'medium'\|'high'\|'xhigh'\|'max'` — guides adaptive thinking depth (default `'high'`) | +| `maxThinkingTokens` | `number` | **Deprecated** — use `thinking` | +| `maxTurns` | `number` | Max user↔assistant turns before stopping | +| `maxBudgetUsd` | `number` | Stop with `error_max_budget_usd` when exceeded | +| `mcpServers` ✱ | `Record` | MCP server configs | +| `model` ✱ | `string` | e.g. `'claude-sonnet-5'`, `'claude-opus-4-8'` | +| `outputFormat` | `{ type:'json_schema'; schema }` | Structured output | +| `pathToClaudeCodeExecutable` ✱ | `string` | Path to the CLI binary | +| `permissionMode` ✱ | `PermissionMode` | See below | +| `allowDangerouslySkipPermissions` ✱ | `boolean` | **Required** for `permissionMode:'bypassPermissions'` | +| `permissionPromptToolName` | `string` | Route permission prompts through an MCP tool | +| `plugins` | `SdkPluginConfig[]` | Local plugins (`{ type:'local', path }`) | +| `resume` ✱ | `string` | Session ID to resume | +| `sessionId` | `string` | Force a specific session UUID (can't combine with `continue`/`resume` unless `forkSession`) | +| `resumeSessionAt` | `string` | On resume, stop at a given message UUID | +| `sandbox` | `SandboxSettings` | Command-execution isolation | +| `settings` / `managedSettings` | `string \| Settings` | Inline/flag settings layer; policy-tier settings | +| `settingSources` ✱ | `SettingSource[]` | Which filesystem settings to load — **default semantics changed, see below** | +| `skills` | `string[] \| 'all'` | The one place to enable skills (no need to add `'Skill'` to `allowedTools`) | +| `strictMcpConfig` | `boolean` | Use only `mcpServers`/agent MCP; ignore `.mcp.json`, settings, plugins (`--strict-mcp-config`) | +| `systemPrompt` ✱ | `string \| string[] \| { type:'preset'; preset:'claude_code'; append?; excludeDynamicSections? }` | See preset notes below | +| `persistSession` | `boolean` | `false` disables writing/resuming session transcripts | +| `stderr` | `(data:string)=>void` | Subprocess stderr callback | +| `spawnClaudeCodeProcess` | `(o: SpawnOptions)=>SpawnedProcess` | Custom spawn (VM/container/remote) | + +Other members exist (`sessionStore`/`sessionStoreFlush`/`loadTimeoutMs` for +external transcript mirroring; `onElicitation`/`onUserDialog`/ +`supportedDialogKinds` for MCP elicitation & blocking dialogs; `taskBudget`, +`promptSuggestions`, `agentProgressSummaries`, `toolConfig`, `title`, +`planModeInstructions`, `debug`/`debugFile`) — see `Options` in `sdk.d.ts` for +the exhaustive list. ### PermissionMode ```typescript -type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'; +type PermissionMode = + 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto'; +// 'dontAsk' — never prompt; deny anything not pre-approved +// 'auto' — a model classifier approves/denies prompts ``` -### SettingSource +nanoclaw runs `'bypassPermissions'` + `allowDangerouslySkipPermissions: true`. + +### SettingSource — default flipped since 0.2.x ```typescript type SettingSource = 'user' | 'project' | 'local'; @@ -112,128 +131,160 @@ type SettingSource = 'user' | 'project' | 'local'; // 'local' → .claude/settings.local.json (gitignored) ``` -When omitted, SDK loads NO filesystem settings (isolation by default). Precedence: local > project > user. Programmatic options always override filesystem settings. +**In 0.3.x, when `settingSources` is omitted the SDK loads ALL sources** (matches +CLI defaults). Pass `[]` to disable filesystem settings (isolation mode). Must +include `'project'` to load CLAUDE.md. This inverts the 0.2.x behaviour, where +omitting the option loaded nothing. nanoclaw sets it explicitly to +`['project', 'user', 'local']`, so it is unaffected by the flip — but any code +that relied on "omitted = isolated" is now loading real settings. ### AgentDefinition -Programmatic subagents (NOT agent teams — these are simpler, no inter-agent coordination): - ```typescript type AgentDefinition = { - description: string; // When to use this agent - tools?: string[]; // Allowed tools (inherits all if omitted) - prompt: string; // Agent's system prompt - model?: 'sonnet' | 'opus' | 'haiku' | 'inherit'; -} + description: string; // When to use this agent + prompt: string; // Agent's system prompt + tools?: string[]; // Allowed tools (inherits all if omitted) + disallowedTools?: string[]; // Explicit deny (mcp__server / mcp__* strip servers) + model?: string; // Alias ('opus'/'sonnet'/'haiku'/'fable') or full ID; 'inherit' = main model + mcpServers?: AgentMcpServerSpec[]; + skills?: string[]; // Preload skills into the agent context + initialPrompt?: string; // Auto-submitted first user turn when this is the main-thread agent + maxTurns?: number; + criticalSystemReminder_EXPERIMENTAL?: string; +}; ``` +Note `model` is now a plain `string` (not the fixed alias union from 0.2.x), and +`disallowedTools`/`mcpServers`/`skills`/`initialPrompt`/`maxTurns` are new. + ### McpServerConfig ```typescript type McpServerConfig = - | { type?: 'stdio'; command: string; args?: string[]; env?: Record } - | { type: 'sse'; url: string; headers?: Record } - | { type: 'http'; url: string; headers?: Record } - | { type: 'sdk'; name: string; instance: McpServer } // in-process + | { type?: 'stdio'; command: string; args?: string[]; env?: Record } + | { type: 'sse'; url: string; headers?: Record } + | { type: 'http'; url: string; headers?: Record } + | { type: 'sdk'; name: string; instance: McpServer }; // in-process, non-serializable ``` +Each non-sdk variant also accepts `tools?: McpServerToolPolicy[]`, +`timeout?: number` (per-server tool-call wall-clock cap, ms), and +`alwaysLoad?: boolean` (skip tool-search deferral — include all of this server's +tools in the turn-1 prompt). + +nanoclaw derives MCP allow patterns from the `mcpServers` map. Server names are +sanitized by the SDK when forming tool prefixes: any char outside `[A-Za-z0-9_-]` +becomes `_`, so the allowlist must mirror that (nanoclaw's `mcpAllowPattern` +does). + ### SdkBeta ```typescript type SdkBeta = 'context-1m-2025-08-07'; -// Enables 1M token context window for Opus 4.6, Sonnet 4.5, Sonnet 4 +// Enables the 1M-token context window (Sonnet 4 / 4.5). ``` -### CanUseTool +The value is unchanged; the doc comment's model list is now Sonnet-only. + +### CanUseTool / PermissionResult ```typescript type CanUseTool = ( toolName: string, - input: ToolInput, - options: { signal: AbortSignal; suggestions?: PermissionUpdate[] } + input: Record, + options: { + signal: AbortSignal; + suggestions?: PermissionUpdate[]; + blockedPath?: string; // path that triggered the request, if any + decisionReason?: string; // why the request fired + } ) => Promise; type PermissionResult = - | { behavior: 'allow'; updatedInput: ToolInput; updatedPermissions?: PermissionUpdate[] } - | { behavior: 'deny'; message: string; interrupt?: boolean }; + | { behavior: 'allow'; updatedInput?: Record; + updatedPermissions?: PermissionUpdate[]; toolUseID?: string; + decisionClassification?: PermissionDecisionClassification } + | { behavior: 'deny'; message: string; interrupt?: boolean; toolUseID?: string; + decisionClassification?: PermissionDecisionClassification }; ``` +`updatedInput` on the allow branch is now optional (it was required in 0.2.x). +nanoclaw does not use `canUseTool` — it gates tools with `allowedTools` / +`disallowedTools` plus a `PreToolUse` hook. + ## SDKMessage Types -`query()` can yield 16 message types. The official docs show a simplified union of 7, but `sdk.d.ts` has the full set: +`query()` yields a much wider union than 0.2.x — 36 members +(`SDKMessage`, `sdk.d.ts` ~line 3727). The ones you actually branch on: -| Type | Subtype | Purpose | -|------|---------|---------| -| `system` | `init` | Session initialized, contains session_id, tools, model | -| `system` | `task_notification` | Background agent completed/failed/stopped | -| `system` | `compact_boundary` | Conversation was compacted | -| `system` | `status` | Status change (e.g. compacting) | -| `system` | `hook_started` | Hook execution started | -| `system` | `hook_progress` | Hook progress output | -| `system` | `hook_response` | Hook completed | -| `system` | `files_persisted` | Files saved | -| `assistant` | — | Claude's response (text + tool calls) | -| `user` | — | User message (internal) | -| `user` (replay) | — | Replayed user message on resume | -| `result` | `success` / `error_*` | Final result of a prompt processing round | -| `stream_event` | — | Partial streaming (when includePartialMessages) | -| `tool_progress` | — | Long-running tool progress | -| `auth_status` | — | Authentication state changes | -| `tool_use_summary` | — | Summary of preceding tool uses | +| `type` / `subtype` | Purpose | +|--------------------|---------| +| `system` / `init` | Session initialized: `session_id`, `tools`, `model`, `skills`, `plugins`, `betas`, `claude_code_version` | +| `assistant` | Claude's response (text + tool calls); `parent_tool_use_id` non-null when from a subagent | +| `user` / `user` (replay) | User message; replayed on resume | +| `result` / `success`\|`error_*` | Terminal result of a prompt round (see below) | +| `system` / `compact_boundary` | Context was compacted; carries `compact_metadata` | +| `system` / `task_notification` | Background task completed / failed / stopped | +| `system` / `task_started` \| `task_progress` \| `task_updated` | Background/subagent task lifecycle | +| `system` / `api_retry` | Retryable API error; will retry after a delay | +| `rate_limit_event` | Rate-limit window update — **top-level `type`, not a `system` subtype** | +| `stream_event` (`SDKPartialAssistantMessage`) | Partial streaming (with `includePartialMessages`) | +| `system` / `hook_started` \| `hook_progress` \| `hook_response` | Hook lifecycle (with `includeHookEvents`) | +| `auth_status`, `tool_use_summary`, `permission_denied`, `commands_changed`, `prompt_suggestion`, … | Other lifecycle/informational events | -### SDKTaskNotificationMessage (sdk.d.ts:1507) +nanoclaw's provider translates `init`, `result`, `api_retry`, +`rate_limit_event`, `compact_boundary`, and `task_notification`. Note the +`rate_limit_event` shape: it is `{ type: 'rate_limit_event', ... }`, **not** +`{ type: 'system', subtype: 'rate_limit_event' }`. + +### SDKResultMessage (`sdk.d.ts` ~line 3971) ```typescript -type SDKTaskNotificationMessage = { - type: 'system'; - subtype: 'task_notification'; - task_id: string; - status: 'completed' | 'failed' | 'stopped'; - output_file: string; - summary: string; - uuid: UUID; - session_id: string; -}; -``` +type SDKResultMessage = SDKResultSuccess | SDKResultError; -### SDKResultMessage (sdk.d.ts:1375) - -Two variants with shared fields: - -```typescript -// Shared fields on both variants: -// uuid, session_id, duration_ms, duration_api_ms, is_error, num_turns, -// total_cost_usd, usage: NonNullableUsage, modelUsage, permission_denials - -// Success: type SDKResultSuccess = { - type: 'result'; - subtype: 'success'; + type: 'result'; subtype: 'success'; result: string; structured_output?: unknown; - // ...shared fields + stop_reason: string | null; + is_error: boolean; + num_turns: number; + duration_ms: number; duration_api_ms: number; + total_cost_usd: number; + usage: NonNullableUsage; + modelUsage: Record; + permission_denials: SDKPermissionDenial[]; + terminal_reason?: TerminalReason; // why the loop ended (new) + uuid: UUID; session_id: string; + // + timing fields: ttft_ms, time_to_request_ms, warm_spare_claimed, … }; -// Error: type SDKResultError = { type: 'result'; - subtype: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | 'error_max_structured_output_retries'; + subtype: 'error_during_execution' | 'error_max_turns' + | 'error_max_budget_usd' | 'error_max_structured_output_retries'; errors: string[]; - // ...shared fields + // shares the timing/usage/terminal_reason fields above (no `result` string) }; ``` -Useful fields on result: `total_cost_usd`, `duration_ms`, `num_turns`, `modelUsage` (per-model breakdown with `costUSD`, `inputTokens`, `outputTokens`, `contextWindow`). +`result` (the final text) exists only on the success variant; error subtypes +carry their text in `errors[]`. nanoclaw surfaces either so a non-retryable +billing/quota error still reaches the user. ### SDKAssistantMessage ```typescript type SDKAssistantMessage = { type: 'assistant'; - uuid: UUID; - session_id: string; - message: APIAssistantMessage; // From Anthropic SDK - parent_tool_use_id: string | null; // Non-null when from subagent + message: BetaMessage; // Anthropic beta message shape + parent_tool_use_id: string | null; // non-null → from a subagent + error?: SDKAssistantMessageError; // 'billing_error' | 'rate_limit' | 'overloaded' | … + subagent_type?: string; + task_description?: string; + supersedes?: UUID[]; // refusal-fallback supersede + uuid: UUID; session_id: string; request_id?: string; }; ``` @@ -241,247 +292,154 @@ type SDKAssistantMessage = { ```typescript type SDKSystemMessage = { - type: 'system'; - subtype: 'init'; - uuid: UUID; - session_id: string; + type: 'system'; subtype: 'init'; apiKeySource: ApiKeySource; + claude_code_version: string; cwd: string; tools: string[]; mcp_servers: { name: string; status: string }[]; model: string; permissionMode: PermissionMode; slash_commands: string[]; + skills: string[]; + plugins: { name: string; path: string }[]; + agents?: string[]; + betas?: string[]; output_style: string; + uuid: UUID; session_id: string; }; ``` -## Turn Behavior: When the Agent Stops vs Continues - -### When the Agent STOPS (no more API calls) - -**1. No tool_use blocks in response (THE PRIMARY CASE)** - -Claude responded with text only — it decided it has completed the task. The API's `stop_reason` will be `"end_turn"`. The SDK does NOT make this decision — it's entirely driven by Claude's model output. - -**2. Max turns exceeded** — Results in `SDKResultError` with `subtype: "error_max_turns"`. - -**3. Abort signal** — User interruption via `abortController`. - -**4. Budget exceeded** — `totalCost >= maxBudgetUsd` → `"error_max_budget_usd"`. - -**5. Stop hook prevents continuation** — Hook returns `{preventContinuation: true}`. - -### When the Agent CONTINUES (makes another API call) - -**1. Response contains tool_use blocks (THE PRIMARY CASE)** — Execute tools, increment turnCount, recurse into EZ. - -**2. max_output_tokens recovery** — Up to 3 retries with a "break your work into smaller pieces" context message. - -**3. Stop hook blocking errors** — Errors fed back as context messages, loop continues. - -**4. Model fallback** — Retry with fallback model (one-time). - -### Decision Table - -| Condition | Action | Result Type | -|-----------|--------|-------------| -| Response has `tool_use` blocks | Execute tools, recurse into `EZ` | continues | -| Response has NO `tool_use` blocks | Run stop hooks, return | `success` | -| `turnCount > maxTurns` | Yield max_turns_reached | `error_max_turns` | -| `totalCost >= maxBudgetUsd` | Yield budget error | `error_max_budget_usd` | -| `abortController.signal.aborted` | Yield interrupted msg | depends on context | -| `stop_reason === "max_tokens"` (output) | Retry up to 3x with recovery prompt | continues | -| Stop hook `preventContinuation` | Return immediately | `success` | -| Stop hook blocking error | Feed error back, recurse | continues | -| Model fallback error | Retry with fallback model (one-time) | continues | - -## Subagent Execution Modes - -### Case 1: Synchronous Subagents (`run_in_background: false`) — BLOCKS - -Parent agent calls Task tool → `VR()` runs `EZ()` for subagent → parent waits for full result → tool result returned to parent → parent continues. - -The subagent runs the full recursive EZ loop. The parent's tool execution is suspended via `await`. There is a mid-execution "promotion" mechanism: a synchronous subagent can be promoted to background via `Promise.race()` against a `backgroundSignal` promise. - -### Case 2: Background Tasks (`run_in_background: true`) — DOES NOT WAIT - -- **Bash tool:** Command spawned, tool returns immediately with empty result + `backgroundTaskId` -- **Task/Agent tool:** Subagent launched in fire-and-forget wrapper (`g01()`), tool returns immediately with `status: "async_launched"` + `outputFile` path - -Zero "wait for background tasks" logic before emitting the `type: "result"` message. When a background task completes, an `SDKTaskNotificationMessage` is emitted separately. - -### Case 3: Agent Teams (TeammateTool / SendMessage) — RESULT FIRST, THEN POLLING - -The team leader runs its normal EZ loop, which includes spawning teammates. When the leader's EZ loop finishes, `type: "result"` is emitted. Then the leader enters a post-result polling loop: - -```javascript -while (true) { - // Check if no active teammates AND no running tasks → break - // Check for unread messages from teammates → re-inject as new prompt, restart EZ loop - // If stdin closed with active teammates → inject shutdown prompt - // Poll every 500ms -} -``` - -From the SDK consumer's perspective: you receive the initial `type: "result"`, but the AsyncGenerator may continue yielding more messages as the team leader processes teammate responses and re-enters the agent loop. The generator only truly finishes when all teammates have shut down. - -## The isSingleUserTurn Problem - -From sdk.mjs: - -```javascript -QK = typeof X === "string" // isSingleUserTurn = true when prompt is a string -``` - -When `isSingleUserTurn` is true and the first `result` message arrives: - -```javascript -if (this.isSingleUserTurn) { - this.transport.endInput(); // closes stdin to CLI -} -``` - -This triggers a chain reaction: - -1. SDK closes CLI stdin -2. CLI detects stdin close -3. Polling loop sees `D = true` (stdin closed) with active teammates -4. Injects shutdown prompt → leader sends `shutdown_request` to all teammates -5. **Teammates get killed mid-research** - -The shutdown prompt (found via `BGq` variable in minified cli.js): - -``` -You are running in non-interactive mode and cannot return a response -to the user until your team is shut down. - -You MUST shut down your team before preparing your final response: -1. Use requestShutdown to ask each team member to shut down gracefully -2. Wait for shutdown approvals -3. Use the cleanup operation to clean up the team -4. Only then provide your final response to the user -``` - -### The practical problem - -With V1 `query()` + string prompt + agent teams: - -1. Leader spawns teammates, they start researching -2. Leader's EZ loop ends ("I've dispatched the team, they're working on it") -3. `type: "result"` emitted -4. SDK sees `isSingleUserTurn = true` → closes stdin immediately -5. Polling loop detects stdin closed + active teammates → injects shutdown prompt -6. Leader sends `shutdown_request` to all teammates -7. **Teammates could be 10 seconds into a 5-minute research task and they get told to stop** - -## The Fix: Streaming Input Mode - -Instead of passing a string prompt (which sets `isSingleUserTurn = true`), pass an `AsyncIterable`: +### SDKTaskNotificationMessage ```typescript -// Before (broken for agent teams): -query({ prompt: "do something" }) - -// After (keeps CLI alive): -query({ prompt: asyncIterableOfMessages }) +type SDKTaskNotificationMessage = { + type: 'system'; subtype: 'task_notification'; + task_id: string; + tool_use_id?: string; + status: 'completed' | 'failed' | 'stopped'; + output_file: string; + summary: string; + usage?: { total_tokens: number; tool_uses: number; duration_ms: number }; + uuid: UUID; session_id: string; +}; ``` -When prompt is an `AsyncIterable`: -- `isSingleUserTurn = false` -- SDK does NOT close stdin after first result -- CLI stays alive, continues processing -- Background agents keep running -- `task_notification` messages flow through the iterator -- We control when to end the iterable +### SDKUserMessage (streaming input) -### Additional Benefit: Streaming New Messages +```typescript +type SDKUserMessage = { + type: 'user'; + message: MessageParam; // Anthropic message param + parent_tool_use_id: string | null; + session_id?: string; // now optional + uuid?: UUID; // now optional + // + isSynthetic?, priority?, shouldQuery?, timestamp?, subagent_type?, … +}; +``` -With the async iterable approach, we can push new incoming WhatsApp messages into the iterable while the agent is still working. Instead of queuing messages until the container exits and spawning a new container, we stream them directly into the running session. +nanoclaw pushes minimal `SDKUserMessage`s (`{ type:'user', message:{ role:'user', +content }, parent_tool_use_id:null, session_id:'' }`) — the required fields are +`type`, `message`, `parent_tool_use_id`; `session_id`/`uuid` are optional. -### Intended Lifecycle with Agent Teams +## Turn Behaviour: when the agent stops vs continues -With the async iterable fix (`isSingleUserTurn = false`), stdin stays open so the CLI never hits the teammate check or shutdown prompt injection: +The stop/continue decision lives inside the CLI, not the SDK. The observable +outcomes are surfaced by the result `subtype` and (new in 0.3.x) the +`terminal_reason` field: + +```typescript +type TerminalReason = + 'completed' | 'max_turns' + | 'stop_hook_prevented' | 'hook_stopped' | 'aborted_streaming' + | 'aborted_tools' | 'tool_deferred' | 'background_requested' + | 'blocking_limit' | 'rapid_refill_breaker' | 'prompt_too_long' + | 'image_error' | 'model_error'; +``` + +Behavioural summary (unchanged in spirit from the 0.2.x analysis, but no longer +tied to internal function names): + +| Condition | Outcome | +|-----------|---------| +| Assistant response has `tool_use` blocks | Tools execute; the loop continues | +| Response has NO `tool_use` blocks | The turn ends (`success`, `terminal_reason:'completed'`) | +| `maxTurns` exceeded | `error_max_turns` (`terminal_reason:'max_turns'`) | +| `maxBudgetUsd` exceeded | `error_max_budget_usd` | +| Abort via `abortController` | `aborted_streaming` / `aborted_tools` | +| A `Stop` hook prevents continuation | ends (`terminal_reason:'stop_hook_prevented'`) | + +The primary stop condition is still "Claude emitted no tool calls" — a model +decision, not an SDK one. + +## Streaming Input: string prompt vs AsyncIterable + +`query()`'s `prompt` accepts `string | AsyncIterable`, and the +choice changes session lifecycle: + +- **`prompt: string`** — single-turn. The SDK sends one user message and closes + the input channel; the CLI shuts down after producing its `result`. +- **`prompt: AsyncIterable`** — streaming/multi-turn. The input + channel stays open, so the CLI keeps running: you can push more user messages + into the iterable while the agent works, background tasks keep running, and + `task_notification` events continue to flow through the generator. You control + when the session ends by ending the iterable. + +nanoclaw always uses the `AsyncIterable` form. Its `MessageStream` class is a +push-based async iterable: `push(text)` enqueues an `SDKUserMessage`, `end()` +closes it. This is how new inbound messages are streamed into a live session +instead of spawning a fresh CLI per message, and it keeps the CLI alive so +long-running background subagents aren't cut off when the first `result` arrives. + +### Lifecycle with background work + +Because the input channel stays open, more than one `result` can arrive: ``` 1. system/init → session initialized -2. assistant/user → Claude reasoning, tool calls, tool results -3. ... → more assistant/user turns (spawning subagents, etc.) -4. result #1 → lead agent's first response (capture) -5. task_notification(s) → background agents complete/fail/stop -6. assistant/user → lead agent continues (processing subagent results) -7. result #2 → lead agent's follow-up response (capture) -8. [iterator done] → CLI closed stdout, all done +2. assistant/user … → reasoning, tool calls, tool results (incl. spawning subagents) +3. result #1 → first response (capture it) +4. task_notification(s) → background agents complete / fail / stop +5. assistant/user … → agent continues (processing subagent results) +6. result #2 → follow-up response (capture it) +7. [iterator done] → CLI closed its output; end of session ``` -All results are meaningful — capture every one, not just the first. +Every `result` is meaningful — capture each one, not just the first. -## V1 vs V2 API - -### V1: `query()` — One-shot async generator - -```typescript -const q = query({ prompt: "...", options: {...} }); -for await (const msg of q) { /* process events */ } -``` - -- When `prompt` is a string: `isSingleUserTurn = true` → stdin auto-closes after first result -- For multi-turn: must pass an `AsyncIterable` and manage coordination yourself - -### V2: `createSession()` + `send()` / `stream()` — Persistent session - -```typescript -await using session = unstable_v2_createSession({ model: "..." }); -await session.send("first message"); -for await (const msg of session.stream()) { /* events */ } -await session.send("follow-up"); -for await (const msg of session.stream()) { /* events */ } -``` - -- `isSingleUserTurn = false` always → stdin stays open -- `send()` enqueues into an async queue (`QX`) -- `stream()` yields from the same message generator, stopping on `result` type -- Multi-turn is natural — just alternate `send()` / `stream()` -- V2 does NOT call V1 `query()` internally — both independently create Transport + Query - -### Comparison Table - -| Aspect | V1 | V2 | -|--------|----|----| -| `isSingleUserTurn` | `true` for string prompt | always `false` | -| Multi-turn | Requires managing `AsyncIterable` | Just call `send()`/`stream()` | -| stdin lifecycle | Auto-closes after first result | Stays open until `close()` | -| Agentic loop | Identical `EZ()` | Identical `EZ()` | -| Stop conditions | Same | Same | -| Session persistence | Must pass `resume` to new `query()` | Built-in via session object | -| API stability | Stable | Unstable preview (`unstable_v2_*` prefix) | - -**Key finding: Zero difference in turn behavior.** Both use the same CLI process, the same `EZ()` recursive generator, and the same decision logic. +> The 0.2.x version of this doc explained the mechanism through minified CLI +> internals (an `isSingleUserTurn` flag, a specific teammate-shutdown prompt). +> Those symbol-level details can't be re-verified from the 0.3.x `.d.ts` and +> have been dropped; the string-vs-iterable *behaviour* above is what the public +> `query()` signature and nanoclaw's usage actually depend on. ## Hook Events ```typescript type HookEvent = - | 'PreToolUse' // Before tool execution - | 'PostToolUse' // After successful tool execution - | 'PostToolUseFailure' // After failed tool execution - | 'Notification' // Notification messages - | 'UserPromptSubmit' // User prompt submitted - | 'SessionStart' // Session started (startup/resume/clear/compact) - | 'SessionEnd' // Session ended - | 'Stop' // Agent stopping - | 'SubagentStart' // Subagent spawned - | 'SubagentStop' // Subagent stopped - | 'PreCompact' // Before conversation compaction - | 'PermissionRequest'; // Permission being requested + | 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'PostToolBatch' + | 'Notification' | 'UserPromptSubmit' | 'UserPromptExpansion' + | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' + | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PostCompact' + | 'PermissionRequest' | 'PermissionDenied' | 'Setup' + | 'TeammateIdle' | 'TaskCreated' | 'TaskCompleted' + | 'Elicitation' | 'ElicitationResult' | 'ConfigChange' + | 'WorktreeCreate' | 'WorktreeRemove' | 'InstructionsLoaded' + | 'CwdChanged' | 'FileChanged' | 'MessageDisplay'; ``` -### Hook Configuration +The list roughly doubled since 0.2.x (`PostToolBatch`, `PostCompact`, +`PermissionDenied`, `Setup`, the `Task*`/`Teammate*`/`Worktree*`/`Cwd*`/`File*` +families, etc.). nanoclaw registers `PreToolUse`, `PostToolUse`, +`PostToolUseFailure`, and `PreCompact`. + +### Hook configuration & return ```typescript interface HookCallbackMatcher { - matcher?: string; // Optional tool name matcher + matcher?: string; // optional tool-name matcher hooks: HookCallback[]; + timeout?: number; // seconds, for all hooks in the matcher (new) } type HookCallback = ( @@ -489,15 +447,9 @@ type HookCallback = ( toolUseID: string | undefined, options: { signal: AbortSignal } ) => Promise; -``` -### Hook Return Values - -```typescript type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput; -type AsyncHookJSONOutput = { async: true; asyncTimeout?: number }; - type SyncHookJSONOutput = { continue?: boolean; suppressOutput?: boolean; @@ -505,139 +457,224 @@ type SyncHookJSONOutput = { decision?: 'approve' | 'block'; systemMessage?: string; reason?: string; - hookSpecificOutput?: - | { hookEventName: 'PreToolUse'; permissionDecision?: 'allow' | 'deny' | 'ask'; updatedInput?: Record } + terminalSequence?: string; // OSC notification escape (new) + hookSpecificOutput?: /* per-event union, e.g.: */ + | { hookEventName: 'PreToolUse'; permissionDecision?: 'allow'|'deny'|'ask'|'defer'; + permissionDecisionReason?: string; updatedInput?: Record; + additionalContext?: string } | { hookEventName: 'UserPromptSubmit'; additionalContext?: string } | { hookEventName: 'SessionStart'; additionalContext?: string } - | { hookEventName: 'PostToolUse'; additionalContext?: string }; + /* …many more per HookEvent… */; }; ``` -### Subagent Hooks (from sdk.d.ts) +nanoclaw's `preToolUseHook` returns `{ decision: 'block', stopReason }` to reject +a disallowed tool, and `{ continue: true }` otherwise — both valid +`SyncHookJSONOutput`. + +### BaseHookInput (shared) & subagent hooks ```typescript +type BaseHookInput = { + session_id: string; + transcript_path: string; + cwd: string; + permission_mode?: string; + prompt_id?: string; // correlates a prompt with its downstream events (new) + agent_id?: string; // present only inside a subagent (new) + agent_type?: string; // e.g. 'general-purpose' (new) + effort?: /* reasoning effort for the current turn */; +}; + +type PreToolUseHookInput = BaseHookInput & { + hook_event_name: 'PreToolUse'; + tool_name: string; tool_input: unknown; tool_use_id: string; +}; + type SubagentStartHookInput = BaseHookInput & { - hook_event_name: 'SubagentStart'; - agent_id: string; - agent_type: string; + hook_event_name: 'SubagentStart'; agent_id: string; agent_type: string; }; type SubagentStopHookInput = BaseHookInput & { hook_event_name: 'SubagentStop'; stop_hook_active: boolean; - agent_id: string; - agent_transcript_path: string; - agent_type: string; + agent_id: string; agent_type: string; agent_transcript_path: string; + last_assistant_message?: string; // new + background_tasks?: BackgroundTaskSummary[]; // new + session_crons?: SessionCronSummary[]; // new }; - -// BaseHookInput = { session_id, transcript_path, cwd, permission_mode? } ``` -## Query Interface Methods +`PreCompactHookInput` (which nanoclaw uses to archive transcripts before +compaction) is `BaseHookInput & { hook_event_name: 'PreCompact'; … }`, so +`transcript_path` and `session_id` are available on it. -The `Query` object (sdk.d.ts:931). Official docs list these public methods: +## Query interface methods + +The `Query` object (`sdk.d.ts` ~line 2204) exposes a large control channel. +Methods marked "streaming input mode only" require the `AsyncIterable` prompt +form nanoclaw uses. ```typescript interface Query extends AsyncGenerator { - interrupt(): Promise; // Stop current execution (streaming input mode only) - rewindFiles(userMessageUuid: string): Promise; // Restore files to state at message (needs enableFileCheckpointing) - setPermissionMode(mode: PermissionMode): Promise; // Change permissions (streaming input mode only) - setModel(model?: string): Promise; // Change model (streaming input mode only) - setMaxThinkingTokens(max: number | null): Promise; // Change thinking tokens (streaming input mode only) - supportedCommands(): Promise; // Available slash commands - supportedModels(): Promise; // Available models - mcpServerStatus(): Promise; // MCP server connection status - accountInfo(): Promise; // Authenticated user info + // control (streaming input mode only): + interrupt(): Promise; + setPermissionMode(mode: PermissionMode): Promise; + setModel(model?: string): Promise; + setMaxThinkingTokens(max: number | null, display?: 'summarized'|'omitted'|null): Promise; + applyFlagSettings(settings): Promise; + setMcpServers(servers): Promise; + setMcpPermissionModeOverride(server, mode): Promise<{ warning?: string }>; + reconnectMcpServer(name): Promise; + toggleMcpServer(name, enabled): Promise; + streamInput(stream: AsyncIterable): Promise; + stopTask(taskId: string): Promise; + backgroundTasks(toolUseId?: string): Promise; + rewindFiles(userMessageId, options?): Promise; // needs enableFileCheckpointing + seedReadState(path, mtime): Promise; + close(): void; + + // introspection: + initializationResult(): Promise; + reinitialize(): Promise; + supportedCommands(): Promise; + supportedModels(): Promise; + supportedAgents(): Promise; + mcpServerStatus(): Promise; + getContextUsage(): Promise; + accountInfo(): Promise; + readFile(path, options?): Promise; + reloadPlugins(): Promise; + reloadSkills(): Promise; } ``` -Found in sdk.d.ts but NOT in official docs (may be internal): -- `streamInput(stream)` — stream additional user messages -- `close()` — forcefully end the query -- `setMcpServers(servers)` — dynamically add/remove MCP servers +`streamInput`, `close`, and `setMcpServers` — flagged "internal, not in the docs" +in the 0.2.x notes — are now first-class members of the public `Query` interface. ## Sandbox Configuration +`SandboxSettings` is defined via a Zod schema (`SandboxSettingsSchema`), so the +shape is inferred rather than a literal type. Key fields: + ```typescript type SandboxSettings = { enabled?: boolean; + failIfUnavailable?: boolean; // defaults true when enabled:true is passed via option autoAllowBashIfSandboxed?: boolean; - excludedCommands?: string[]; allowUnsandboxedCommands?: boolean; + excludedCommands?: string[]; network?: { - allowLocalBinding?: boolean; + allowedDomains?: string[]; + deniedDomains?: string[]; + allowManagedDomainsOnly?: boolean; allowUnixSockets?: string[]; allowAllUnixSockets?: boolean; - httpProxyPort?: number; - socksProxyPort?: number; + allowLocalBinding?: boolean; + allowMachLookup?: string[]; + httpProxyPort?: number; socksProxyPort?: number; + tlsTerminate?: { caCertPath?: string; caKeyPath?: string }; }; - ignoreViolations?: { - file?: string[]; - network?: string[]; + filesystem?: { + allowWrite?: string[]; denyWrite?: string[]; + allowRead?: string[]; denyRead?: string[]; + allowManagedReadPathsOnly?: boolean; }; + credentials?: { files?: {path;mode:'deny'}[]; envVars?: {name;mode:'deny'}[] }; + ignoreViolations?: Record; + // + enableWeakerNestedSandbox, allowAppleEvents, ripgrep, bwrapPath, socatPath, … }; ``` -When `allowUnsandboxedCommands` is true, the model can set `dangerouslyDisableSandbox: true` in Bash tool input, which falls back to the `canUseTool` permission handler. +`network`/`filesystem` gained explicit domain and path allow/deny lists, +`credentials` blocking, and TLS-terminate config since 0.2.x. When +`allowUnsandboxedCommands` is true the model may set +`dangerouslyDisableSandbox: true` on a Bash call, which falls back to the +`canUseTool` handler. nanoclaw does not use the SDK sandbox (it runs each agent +in its own container). ## MCP Server Helpers ### tool() -Creates type-safe MCP tool definitions with Zod schemas: +Type-safe MCP tool definitions with Zod schemas: ```typescript -function tool( +function tool( name: string, description: string, inputSchema: Schema, - handler: (args: z.infer>, extra: unknown) => Promise -): SdkMcpToolDefinition + handler: (args: InferShape, extra: unknown) => Promise, + extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean } +): SdkMcpToolDefinition; ``` +The optional 5th `extras` arg (annotations / `searchHint` / `alwaysLoad`) is new. + ### createSdkMcpServer() -Creates an in-process MCP server (we use stdio instead for subagent inheritance): +In-process MCP server: ```typescript function createSdkMcpServer(options: { name: string; version?: string; + instructions?: string; // surfaced as an MCP instructions block (new) tools?: Array>; -}): McpSdkServerConfigWithInstance + alwaysLoad?: boolean; // (new) +}): McpSdkServerConfigWithInstance; ``` -## Internals Reference +nanoclaw wires its MCP servers as stdio/process servers (via `mcpServers`), not +in-process SDK servers, so subagents inherit them. -### Key minified identifiers (sdk.mjs) +## Key Files (in the published tarball) -| Minified | Purpose | -|----------|---------| -| `s_` | V1 `query()` export | -| `e_` | `unstable_v2_createSession` | -| `Xx` | `unstable_v2_resumeSession` | -| `Qx` | `unstable_v2_prompt` | -| `U9` | V2 Session class (`send`/`stream`/`close`) | -| `XX` | ProcessTransport (spawns cli.js) | -| `$X` | Query class (JSON-line routing, async iterable) | -| `QX` | AsyncQueue (input stream buffer) | +- `sdk.d.ts` — all type definitions (~6700 lines; was ~1800 in 0.2.x) +- `sdk-tools.d.ts` — tool input schemas +- `sdk.mjs` — SDK runtime (minified) +- `bridge.d.ts` / `browser-sdk.d.ts` / `extractFromBunfs.d.ts` — bridge, browser, + and compiled-binary-extraction entry points +- `package.json` — `main: sdk.mjs`, `types: sdk.d.ts` +- The native Claude Code CLI binary ships as a separate per-platform package and + is spawned as the child process. -### Key minified identifiers (cli.js) +## What changed since the 0.2.x analysis -| Minified | Purpose | -|----------|---------| -| `EZ` | Core recursive agentic loop (async generator) | -| `_t4` | Stop hook handler (runs when no tool_use blocks) | -| `PU1` | Streaming tool executor (parallel during API response) | -| `TP6` | Standard tool executor (after API response) | -| `GU1` | Individual tool executor | -| `lTq` | SDK session runner (calls EZ directly) | -| `bd1` | stdin reader (JSON-lines from transport) | -| `mW1` | Anthropic API streaming caller | +Re-verified against 0.3.197. Notable deltas and removals: -## Key Files +- **V2 session API removed.** The `unstable_v2_createSession` / `send` / + `stream` / `unstable_v2_resumeSession` / `unstable_v2_prompt` surface the + 0.2.x doc described no longer exists. There is no session *object* with + `send()`/`stream()`. `query()` (with a string or `AsyncIterable` prompt) is the + single entry point; multi-turn is done by keeping the iterable open. Session + *management* is now a set of standalone functions instead: + `listSessions`, `getSessionInfo`, `getSessionMessages`, `forkSession`, + `deleteSession`, `renameSession`, `tagSession`, plus a pluggable `SessionStore` + for external transcript mirroring. The whole "V1 vs V2" comparison section was + therefore dropped. +- **Minified-identifier tables dropped.** The `sdk.mjs`/`cli.js` symbol tables + (`EZ`, `s_`, `e_`, `$X`, `XX`, `QX`, `mW1`, `VR`, `g01`, `bd1`, the `BGq` + shutdown prompt, the `isSingleUserTurn`/`QK` flag, etc.) were reverse-engineered + from minified bundles and cannot be re-verified from the shipped `.d.ts`. They + are removed. The *observable* behaviours they explained (string vs iterable + prompt lifecycle, stop/continue conditions, background-task notifications) are + kept and re-grounded in the public types. +- **`settingSources` default flipped:** omitted now loads *all* filesystem + settings (was: none). Pass `[]` for isolation. +- **`PermissionMode`** gained `'dontAsk'` and `'auto'`. +- **`HookEvent`** roughly doubled; **`Options`**, the **`SDKMessage`** union, and + the **`Query`** interface all grew substantially (effort/thinking config, + skills, plugins, tool aliases, session stores, structured output, sandbox + filesystem/network/credentials controls, MCP control methods, …). +- **`SDKAssistantMessage.message`** is now `BetaMessage`; **`SDKUserMessage`**'s + `session_id`/`uuid` became optional; **`PermissionResult`** allow-branch + `updatedInput` became optional; result messages gained `stop_reason`, + `terminal_reason`, and timing fields. +- **Line-number references** were all invalidated by the file more than tripling + in size; the remaining `sdk.d.ts` line hints are approximate for 0.3.197. -- `sdk.d.ts` — All type definitions (1777 lines) -- `sdk-tools.d.ts` — Tool input schemas -- `sdk.mjs` — SDK runtime (minified, 376KB) -- `cli.js` — CLI executable (minified, runs as subprocess) +Could not verify (by design): any CLI-internal control flow — it lives in the +minified subprocess, not in the type declarations. Where behaviour matters, this +doc now describes what's observable at the `query()` boundary rather than +internal function structure.