#### `startup_failure_reason` ### `McpServerProvenance`
The whole hunk
from line 984, old and new numbered
/
lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 984
984984 signal: AbortSignal;
985985 suggestions?: PermissionUpdate[];
986986 blockedPath?: string;
987 mcpServer?: { name: string; source: string };
987988 decisionReason?: string;
988989 toolUseID: string;
989990 agentID?: string;
from line 998
997998| `signal` | `AbortSignal` | Signaled if the operation should be aborted |
998999| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Suggested permission updates so the user is not prompted again for this tool. Bash prompts include a suggestion with the `localSettings` [destination](#permissionupdatedestination), so returning it in `updatedPermissions` writes the rule to `.claude/settings.local.json` and persists across sessions. |
9991000| `blockedPath` | `string` | The file path that triggered the permission request, if applicable |
1001| `mcpServer` | `{ name: string; source: string }` | For an `mcp__*` tool, the MCP server that serves it and where that server's definition came from, with the fields of [`McpServerProvenance`](#mcpserverprovenance). Absent for other tools. Requires Agent SDK v0.3.274 or later |
10001002| `decisionReason` | `string` | Explains why this permission request was triggered |
10011003| `toolUseID` | `string` | Unique identifier for this specific tool call within the assistant message |
10021004| `agentID` | `string` | If running within a sub-agent, the sub-agent's ID |
from line 1325
13231325 permission_denials: SDKPermissionDenial[];
13241326 queued_turn_count?: number;
13251327 errors: string[];
1328 startup_failure_reason?: SDKStartupFailureReason;
13261329 user_message_uuid?: string;
13271330 user_message_uuids?: string[];
13281331 terminal_reason?: TerminalReason;
from line 1349
13461349* `modelUsage`: per-model totals for every model call made through the query pipeline during this `query()` call, including the main loop, subagents, and internal calls such as compaction and Workflow agents. Helper calls outside that pipeline, such as the permission classifier and token-counting requests, are excluded. In streaming-input sessions the totals are cumulative across turns, so read the latest result rather than summing across results. See [Track costs in streaming input mode](/docs/en/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) for resets and [Recover totals after a session crash](/docs/en/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) for zeroed results.
13471350* `total_cost_usd`: cumulative estimated cost in USD for this `query()` call, covering the same calls as `modelUsage` and reset at the same points. It is an estimate, not a billing statement. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats.
13481351* `queued_turn_count`: the number of messages you sent with `origin: { kind: "human" }` that are still waiting when Claude Code produced the result. See [`queued_turn_count`](#queued_turn_count) for what `0` and an absent field tell you.
1352* `startup_failure_reason`: why Claude Code refused to start, on the `error_during_execution` result it writes before exiting on a known startup failure. See [`startup_failure_reason`](#startup_failure_reason) for the values and which failures carry it. Requires Agent SDK v0.3.274 or later.
13491353* `terminal_reason`: why the loop ended. One of `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, or `"turn_setup_failed"`.
13501354* `fast_mode_state`: one of `"on"`, `"off"`, or `"cooldown"`.
13511355* `fast_mode_disabled_reason`: why [fast mode](/docs/en/fast-mode) isn't available right now. Absent when nothing blocks fast mode, though a request may still run at standard speed. During the cooldown after a fast mode rate limit, Claude Code reports `fast_mode_state: "cooldown"` with no reason code and re-enables fast mode when the cooldown expires. Requires Claude Code v2.1.219 or later.
from line 1419
14151419* **`0`**: Claude Code doesn't count messages you sent without that `origin`, and doesn't count task notifications, so a turn can still follow.
14161420* **Absent**: the final result that Claude Code emits after a crash or fatal startup error omits the field, and [may carry zeroed totals](/docs/en/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).
14171421
1422#### `startup_failure_reason`
1423
1424Why Claude Code refused to start, so your application can offer the fix instead of a retry. Claude Code sets it on the `error_during_execution` result it writes before exiting on a known startup failure. That result carries zeroed totals, and its `errors` array carries the same text as stderr. The field is absent on every other result. Requires Agent SDK v0.3.274 or later.
1425
1426Set `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` to `1` in [`env`](#options) to receive this result for every `SDKStartupFailureReason` value. Without that variable, Claude Code writes the result only for these failures, and the rest end with stderr output, a non-zero exit, and no result message:
1427
1428* A resume that Claude Code stops because it [can't return the session to its worktree](/docs/en/worktrees#the-session-resumes-outside-its-worktree), with `worktree_unverified` or `worktree_resume_refused`. That section says which error carries which value.
1429* A refused [`continue`](#options) of a conversation that a background session holds, with `session_held_by_background`. For a refused [`resume`](#options) of such a conversation, Claude Code writes the result only when the variable is set.
1430
1431```typescript theme={null}
1432type SDKStartupFailureReason =
1433 | "org_pin_api_key_conflict"
1434 | "org_verify_failed"
1435 | "org_pin_mismatch"
1436 | "managed_settings_invalid"
1437 | "remote_settings_required_unavailable"
1438 | "gateway_signin_required"
1439 | "gateway_access_denied"
1440 | "proxy_invalid"
1441 | "temp_dir_unusable"
1442 | "cwd_unavailable"
1443 | "shell_tool_missing"
1444 | "session_held_by_background"
1445 | "worktree_resume_refused"
1446 | "worktree_unverified"
1447 | "cli_version_too_old"
1448 | "bypass_root";
1449```
1450
1451Each value names one refusal:
1452
1453| Value | What stopped the session |
1454| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1455| `org_pin_api_key_conflict` | Managed settings [require a first-party or Cloud gateway sign-in](/docs/en/authentication#restrict-login-to-your-organization), and an Anthropic API key, auth token, or `apiKeyHelper` is configured instead |
1456| `org_verify_failed` | The sign-in's organization couldn't be verified against the pin, for example because of a network failure or a revoked token |
1457| `org_pin_mismatch` | The sign-in belongs to an organization the pin doesn't allow |
1458| `managed_settings_invalid` | Managed policy settings couldn't be read, or the pin names no organization |
1459| `remote_settings_required_unavailable` | Managed settings that the organization requires couldn't be loaded |
1460| `gateway_signin_required` | The [Cloud gateway](/docs/en/claude-apps-gateway) ended this sign-in |
1461| `gateway_access_denied` | The managed settings request to the Cloud gateway came back with a 403, which the gateway's [troubleshooting table](/docs/en/claude-apps-gateway-deploy#troubleshooting) covers |
1462| `proxy_invalid` | A proxy setting isn't a complete URL |
1463| `temp_dir_unusable` | The per-user temporary directory is unsafe or couldn't be created |
1464| `cwd_unavailable` | The working directory was deleted, moved, or can't be read |
1465| `shell_tool_missing` | On Windows, no shell tool is available: Git Bash is missing, and PowerShell is missing or turned off with `CLAUDE_CODE_USE_POWERSHELL_TOOL` |
1466| `session_held_by_background` | The conversation to resume or continue is running as a [background session](/docs/en/agent-view) |
1467| `worktree_resume_refused` | The session's worktree failed its safety checks, or the resume was launched from inside it. `errors` says whether running the same resume again continues without the worktree |
1468| `worktree_unverified` | The session's worktree couldn't be verified right now, and retrying may succeed |
1469| `cli_version_too_old` | This Claude Code version is below the minimum Anthropic requires |
1470| `bypass_root` | Bypass permissions mode was requested while running as root |
1471
14181472### `SDKSystemMessage`
14191473
14201474System initialization message.
from line 1488
14341488 mcp_servers: {
14351489 name: string;
14361490 status: string;
1491 source?: string;
14371492 }[];
14381493 model: string;
14391494 permissionMode: PermissionMode;
from line 1508
14531508
14541509`terminal_slash_commands` names the entries in `slash_commands` whose interface is bound to the local terminal, such as `exit`. You can send them like any other entry in `slash_commands`; the field exists so a remote or mobile client can hide them from its command menus. The field is present only when non-empty, and requires Agent SDK v0.3.229 or later.
14551510
1511* `source` on each `mcp_servers` entry: where the server's definition came from, with the same values as [`McpServerStatus`](#mcpserverstatus)'s `source`. Requires Agent SDK v0.3.274 or later.
14561512* `effort`: the [effort level](/docs/en/model-config#adjust-effort-level) Claude Code sends on the session's next request, or `null` when it sends none. Claude Code sets the field only on the init message it sends to [Remote Control](/docs/en/remote-control) clients, and omits it from the init message your application reads. Requires Agent SDK v0.3.234 or later.
14571513
14581514The `capabilities` array names the protocol behaviors this CLI implements, so you can feature-detect instead of comparing `claude_code_version` strings. It is an open set: ignore values you don't recognize, and check for the specific capability whose behavior you rely on. The field requires Claude Code v2.1.205 or later and is absent on earlier CLIs.
from line 1931
18751931 tool_name: string;
18761932 tool_input: unknown;
18771933 tool_use_id: string;
1934 mcp_server?: McpServerProvenance;
18781935};
18791936```
18801937
1938`mcp_server` is present when the tool comes from an MCP server; see [`McpServerProvenance`](#mcpserverprovenance). The `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, and `PermissionDenied` inputs carry the same field. The field requires Agent SDK v0.3.274 or later.
1939
18811940#### `PostToolUseHookInput`
18821941
18831942```typescript theme={null}
from line 1947
18881947 tool_response: unknown;
18891948 tool_use_id: string;
18901949 duration_ms?: number;
1950 mcp_server?: McpServerProvenance;
18911951};
18921952```
18931953
from line 1962
19021962 error: string;
19031963 is_interrupt?: boolean;
19041964 duration_ms?: number;
1965 mcp_server?: McpServerProvenance;
19051966};
19061967```
19071968
from line 1993
19321993 tool_input: unknown;
19331994 tool_use_id: string;
19341995 reason: string;
1996 mcp_server?: McpServerProvenance;
19351997};
19361998```
19371999
from line 2185
21232185 tool_name: string;
21242186 tool_input: unknown;
21252187 permission_suggestions?: PermissionUpdate[];
2188 mcp_server?: McpServerProvenance;
21262189};
21272190```
21282191
from line 2844
27812844
27822845Runs a [dynamic workflow](/docs/en/workflows): a script that orchestrates many subagents in the background and returns one consolidated result. The `Workflow` tool is available in Agent SDK v0.3.149 and later. At least one of `script`, `name`, or `scriptPath` is required.
27832846
2784| Field | Type | Description |
2785| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2786| `script` | `string` | Inline workflow script. Must begin with `export const meta = { name, description }` as a literal, followed by the script body using `agent()`, `parallel()`, `pipeline()`, and `phase()`. An optional `phases` array in `meta` groups agents under named stages in the progress view |
2787| `name` | `string` | Name of a built-in workflow or one saved in `.claude/workflows/`. Resolved to a script |
2788| `scriptPath` | `string` | Path to a workflow script file on disk. Takes precedence over `script` and `name`. Claude Code persists every invocation's script and returns the path in the result, so you can edit that file and re-invoke with the same `scriptPath` to iterate |
2789| `args` | `unknown` | Input value exposed to the script as the global `args`, for parameterized named workflows such as a research question or a list of file paths. Pass arrays and objects as actual JSON values, not as a JSON-encoded string |
2790| `resumeFromRunId` | `string` | Run ID of a prior `Workflow` invocation to resume. Completed `agent()` calls with unchanged inputs usually return cached results; the rest run live. [Resume after a pause](/docs/en/workflows#resume-after-a-pause) covers which completed calls re-run. Same session only |
2791| `title` | `string` | Ignored; the script's `meta` block sets the title |
2792| `description` | `string` | Ignored; the script's `meta` block sets the description |
2793
2794### TodoWrite
2795
2796**Tool name:** `TodoWrite`
2797
2798```typescript theme={null}
2799type TodoWriteInput = {
2800 todos: Array<{
2801 content: string;
2802 status: "pending" | "in_progress" | "completed";
2803 activeForm: string;
2804 }>;
2805};
2806```
2807
2808Creates and manages a structured task list for tracking progress.
2809
2810<Note>
2811 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:
2812
2813 * `TodoWrite`
2814 * `TaskCreate`
2815 * `TaskGet`
2816 * `TaskUpdate`
2817 * `TaskList`
2818
2819 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
2820
2821 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
2822
2823 See [Model availability](/docs/en/agent-sdk/todo-tracking#model-availability) to opt in.
2824</Note>
2825
2826### TaskCreate
2827
2828**Tool name:** `TaskCreate`
2829
2830```typescript theme={null}
2831type TaskCreateInput = {
2832 subject: string;
2833 description: string;
2834 activeForm?: string;
2835 metadata?: Record<string, unknown>;
2836};
2837```
2838
2839Creates a single task and returns its assigned ID.
2840
2841### TaskUpdate
2842
2843**Tool name:** `TaskUpdate`
2844
2845```typescript theme={null}
2846type TaskUpdateInput = {
2847 taskId: string;
2848 status?: "pending" | "in_progress" | "completed" | "deleted";
2849 subject?: string;
2850 description?: string;
2851 activeForm?: string;
2852 addBlocks?: string[];
2853 addBlockedBy?: string[];
2854 owner?: string;
2855 metadata?: Record<string, unknown>;
2856};
2857```
2858
2859Patches one task by ID. Set `status` to `"deleted"` to remove it.
2860
2861### TaskGet
2862
2863**Tool name:** `TaskGet`
2864
2865```typescript theme={null}
2866type TaskGetInput = {
2867 taskId: string;
2868};
2869```
2870
2871Returns full details for one task, or `null` when the ID is not found.
2872
2873### TaskList
2874
2875**Tool name:** `TaskList`
2876
2877```typescript theme={null}
2878type TaskListInput = {};
2879```
2880
2881Returns a snapshot of all tasks in the current list.
2882
2883### ExitPlanMode
2884
2885**Tool name:** `ExitPlanMode`
2886
2887```typescript theme={null}
2888type ExitPlanModeInput = {
2889 /** Deprecated: no longer used. */
2890 allowedPrompts?: Array<{
2891 tool: "Bash";
2892 prompt: string;
2893 }>;
2894 [k: string]: unknown;
2895};
2896```
2897
2898Exits plan mode. The `allowedPrompts` field is deprecated and ignored; Claude Code still accepts it so existing callers and transcripts validate. Before v2.1.205, it requested prompt-based Bash permissions for implementing the plan.
2899
2900### ListMcpResources
2901
2902**Tool name:** `ListMcpResourcesTool`
2903
2904```typescript theme={null}
2905type ListMcpResourcesInput = {
2906 server?: string;
2907};
2908```
2909
2910Lists available MCP resources from connected servers.
2911
2912### ReadMcpResource
2913
2914**Tool name:** `ReadMcpResourceTool`
2915
2916```typescript theme={null}
2917type ReadMcpResourceInput = {
2918 server: string;
2919 uri: string;
2920};
2921```
2922
2923Reads a specific MCP resource from a server.
2924
2925### EnterWorktree
2926
2927**Tool name:** `EnterWorktree`
2928
2929```typescript theme={null}
2930type EnterWorktreeInput = {
2931 name?: string;
2932 path?: string;
2933};
2934```
2935
2936Creates and enters a temporary git worktree for isolated work. Pass `path` to switch into an existing worktree instead of creating a new one. On first entry the target must be a registered worktree of the current repository or, in a multi-repo workspace, of a repository nested inside it; from within a worktree session it must be under `.claude/worktrees/` of the session's repository. `name` and `path` are mutually exclusive.
2937
2938### ExitWorktree
2939
2940**Tool name:** `ExitWorktree`
2941
2942```typescript theme={null}
2943type ExitWorktreeInput = {
2944 action: "keep" | "remove";
2945 discard_changes?: boolean;
2946};
2947```
2948
2949Exits the current git worktree and returns to the original working directory. The `keep` action leaves the worktree and branch on disk, while `remove` deletes both. `discard_changes` must be `true` when removing a worktree that has uncommitted files or unmerged commits.
2950
2951### EnterPlanMode
2952
2953**Tool name:** `EnterPlanMode`
2954
2955```typescript theme={null}
2956type EnterPlanModeInput = {};
2957```
2958
2959Enters plan mode, where Claude researches and presents a plan before making changes.
2960
2961### CronCreate
2962
2963**Tool name:** `CronCreate`
2964
2965```typescript theme={null}
2966type CronCreateInput = {
2967 cron: string;
2968 prompt: string;
2969 recurring?: boolean;
2970 durable?: boolean;
2971};
2972```
2973
2974Schedules a prompt to run on a 5-field cron schedule in local time. Set `recurring` to `false` to fire once at the next match. Jobs are session-scoped by default: starting a fresh conversation clears them, and resuming with `--resume` or `--continue` restores jobs that haven't expired. See [Scheduled tasks](/docs/en/scheduled-tasks).
2975
2976Setting `durable` to `true` requests persistence to `.claude/scheduled_tasks.json` so the job survives restarts. Durable scheduling isn't available in every session: when it isn't, Claude Code accepts `durable: true` but creates the job session-only. Read the output's `durable` field to see whether the job persisted.
2977
2978##
2847| Field | Type | Description