Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.283, published 5 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 26 Sep 2026 00:04 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 26 Sep 2026 00:07 UTC.
Upstream edited
Recorded here
Lines+37added
Lines−18removed
From line
1,585
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits58to this page, all time
The whole hunk
from line 1585, old and new numbered
/
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 1585
15851585
15861586Each value names one refusal:
15871587
1588| Value | What stopped the session |
1589| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1590| `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 |
1591| `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 |
1592| `org_pin_mismatch` | The sign-in belongs to an organization the pin doesn't allow |
1593| `managed_settings_invalid` | Managed policy settings couldn't be read, or the pin names no organization |
1594| `remote_settings_required_unavailable` | Managed settings that the organization requires couldn't be loaded |
1595| `gateway_signin_required` | The [Cloud gateway](/docs/en/claude-apps-gateway) ended this sign-in |
1596| `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 |
1597| `proxy_invalid` | A proxy setting isn't a complete URL |
1598| `temp_dir_unusable` | The per-user temporary directory is unsafe or couldn't be created |
1599| `cwd_unavailable` | The working directory was deleted, moved, or can't be read |
1600| `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` |
1601| `session_held_by_background` | The conversation to resume or continue is running as a [background session](/docs/en/agent-view) |
1602| `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 |
1603| `worktree_unverified` | The session's worktree couldn't be verified right now, and retrying may succeed |
1604| `cli_version_too_old` | This Claude Code version is below the minimum Anthropic requires |
1605| `bypass_root` | Bypass permissions mode was requested while running as root |
1588| Value | What stopped the session |
1589| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1590| `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 |
1591| `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 |
1592| `org_pin_mismatch` | The sign-in belongs to an organization the pin doesn't allow |
1593| `managed_settings_invalid` | Managed policy settings couldn't be read, the pin names no organization, or [managed model restrictions](/docs/en/errors#managed-settings-block-the-default-model) leave no permitted model for the Default option |
1594| `remote_settings_required_unavailable` | Managed settings that the organization requires couldn't be loaded |
1595| `gateway_signin_required` | The [Cloud gateway](/docs/en/claude-apps-gateway) ended this sign-in |
1596| `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 |
1597| `proxy_invalid` | A proxy setting isn't a complete URL |
1598| `temp_dir_unusable` | The per-user temporary directory is unsafe or couldn't be created |
1599| `cwd_unavailable` | The working directory was deleted, moved, or can't be read |
1600| `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` |
1601| `session_held_by_background` | The conversation to resume or continue is running as a [background session](/docs/en/agent-view) |
1602| `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 |
1603| `worktree_unverified` | The session's worktree couldn't be verified right now, and retrying may succeed |
1604| `cli_version_too_old` | This Claude Code version is below the minimum Anthropic requires |
1605| `bypass_root` | Bypass permissions mode was requested while running as root |
16061606
16071607### `SDKSystemMessage`
16081608
from line 1632
16321632 output_style: string;
16331633 skills: string[];
16341634 plugins: { name: string; path: string }[];
1635 plugin_errors?: {
1636 plugin: string;
1637 type: string;
1638 message: string;
1639 path?: string;
1640 }[];
16351641 fast_mode_state?: FastModeState;
16361642 fast_mode_disabled_reason?: FastModeDisabledReason;
16371643 effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
from line 1659
16531659| `interrupt_receipt_v1` | [`interrupt()`](#query-object) resolves with an [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) receipt listing the messages that were pending when the interrupt arrived |
16541660| `interrupt_cancel_queued_v1` | The `interrupt` control request honors `cancel_queued: true`, cancelling the messages the receipt would otherwise list under `still_queued` and listing them under `cancelled` instead. See [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Requires Claude Code v2.1.219 or later |
16551661
1662The `plugin_errors` array lists plugin load failures. An entry describes either a plugin that didn't load and is absent from `plugins`, or a plugin that loaded without one of its parts, such as its hooks file. The key is omitted when nothing failed. `SDKSystemMessage` declares `plugin_errors` in Agent SDK v0.3.283 or later.
1663
1664When a directory or archive from your [`plugins` option](#options) itself fails to load, the entry's `plugin` field holds a positional tag such as `inline[0]` instead of a plugin name. This happens, for example, when the path doesn't exist or the manifest is invalid. Match such an entry to your option by its `path` field.
1665
1666The table below lists the fields of each `plugin_errors` entry.
1667
1668| Field | Type | Description |
1669| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1670| `plugin` | `string` | The failing plugin's ID, or a positional tag such as `inline[0]` when the plugin directory or archive itself failed to load |
1671| `type` | `string` | Error category from an open set, such as `path-not-found` or `manifest-validation-error`. Treat a value you don't recognize as a generic failure |
1672| `message` | `string` | Display text describing the failure |
1673| `path` | `string` | Present only when the plugin directory or archive itself failed to load. Its absolute path, with a relative path from your `plugins` option resolved against the [`cwd`](#options) option |
1674
16561675### `SDKPartialAssistantMessage`
16571676
16581677Streaming partial message (only when `includePartialMessages` is true). The `parent_tool_use_id` field is always `null`: stream events are emitted for the main session only. For subagent attribution, use complete messages, which carry `parent_tool_use_id`, or enable [`forwardSubagentText`](#options) to receive subagent text and thinking as complete messages.
from line 2284
22652284
22662285```typescript theme={null}
22672286type PreCompactHookInput = BaseHookInput & {
2268 hook_event_name: "PreCompact";
2269 trigger: "manual" | "auto";
2270 custom_instructions: string | null;
2271};
2272```
2273
2274#### `PostCompactHookInput`
2275
2276```typescript theme={null}
2277type PostCompactHookInput = BaseHookInput & {
2278 hook_event_name: "PostCompact";
2279 trigger: "manual" | "auto";
2280 compact_summary: string;
2281};
2282```
2283
2284#### `PreModelSwitchHookInput`
2285
2286Fires before a requested model switch takes effect. `context_tokens` and the fields after it estimate what re-sending the conversation to the new model costs. For the full field descriptions and blocking semantics, see [PreModelSwitch](/docs/en/hooks#premodelswitch).
2287
2288```typescript theme={null}
2289type PreModelSwitchHookInput = BaseHookInput & {
2290 hook_event_name: "PreModelSwitch";
2291 from_model: string;
2292 to_model: string;
2293 requested_model: string | null;
2294 source: "command" | "picker" | "sdk";
2295 context_tokens: number;
2296 prompt_cache_warm: boolean;
2297 cache_ttl: "5m" | "1h";
2298 estimated_cache_write_usd: number;
2299 pricing: "configured" | "catalog" | "default";
2300};
2301```
2302
2303#### `PostModelSwitchHookInput`
2304
2305Fires after the session's model changes. It carries the same fields as `PreModelSwitchHookInput`, with two more `source` values. See [PostModelSwitch](/docs/en/hooks#postmodelswitch).
2306
2307```typescript theme={null}
2308type PostModelSwitchHookInput = BaseHookInput & {
2309 hook_event_name: "PostModelSwitch";
2310 from_model: string;
2311 to_model: string;
2312 requested_model: string | null;
2313 source: "command" | "picker" | "sdk" | "auto" | "resume";
2314 context_tokens: number;
2315 prompt_cache_warm: boolean;
2316 cache_ttl: "5m" | "1h";
2317 estimated_cache_write_usd: number;
2318 pricing: "configured" | "catalog" | "default";
2319};
2320```
2321
2322#### `PermissionRequestHookInput`
2323
2324```typescript theme={null}
2325type PermissionRequestHookInput = BaseHookInput & {
2326 hook_event_name: "PermissionRequest";
2327 tool_name: string;
2328 tool_input: unknown;
2329 permission_suggestions?: PermissionUpdate[];
2330 mcp_server?: McpServerProvenance;
2331};
2332```
2333
2334#### `SetupHookInput`
2335
2336```typescript theme={null}
2337type SetupHookInput = BaseHookInput & {
2338 hook_event_name: "Setup";
2339 trigger: "init" | "maintenance";
2340};
2341```
2342
2343#### `TeammateIdleHookInput`
2344
2345```typescript theme={null}
2346type TeammateIdleHookInput = BaseHook
2287 hook_ev
No line in this hunk matches that.