Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.252, published 11 hours after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+34added
Lines−28removed
From line
348
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits114to this page, all time
The whole hunk
from line 348, 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 348
348348Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a `query()` call would see before invoking one.
349349
350350<Note>
351 This function is alpha and its API may change before stabilization. It reads MDM sources, including macOS plist and Windows HKLM/HKCU, for parity with CLI startup, but does not execute the admin-configured `policyHelper` subprocess. The `permissions.defaultMode` field is returned as-is from all tiers including project settings. In a live session, the CLI [ignores `defaultMode: 'auto'` from project and local settings](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); `resolveSettings()` skips that check, so an `auto` from those tiers appears here even though a session would ignore it.
351 This function is alpha and its API may change before stabilization.
352352</Note>
353353
354The snapshot differs from what a live `query()` session applies:
355
356* **`policyHelper`**: `resolveSettings()` reads MDM sources, including macOS plist and Windows HKLM/HKCU, but doesn't execute the admin-configured `policyHelper` subprocess.
357* **Server-managed settings**: `resolveSettings()` doesn't fetch [server-managed settings](/docs/en/server-managed-settings#fetch-and-caching-behavior). Pass them as `options.serverManagedSettings` to include them.
358* **`defaultMode`**: the snapshot returns `permissions.defaultMode` as-is from every tier. A live session [ignores `defaultMode: 'auto'` from project and local settings](/docs/en/permission-modes#eliminate-prompts-with-auto-mode), so an `auto` from those tiers appears in the snapshot even though a session would ignore it.
359
354360```typescript theme={null}
355361function resolveSettings(
356362 options?: ResolveSettingsOptions
from line 367
361367
362368`resolveSettings()` accepts a single options object. All fields are optional.
363369
364| Parameter | Type | Default | Description |
365| :------------------------------ | :------------------------------------ | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
366| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to |
367| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads in all cases. Server-managed settings are taken from `serverManagedSettings` when the host passes it, or read from the CLI's on-disk cache otherwise; the snapshot does not fetch them from the network |
368| `options.managedSettings` | `Settings` | `undefined` | Policy-tier settings supplied by the embedding host. Follows the same rules as [`managedSettings` in `Options`](#options), except that `resolveSettings()` doesn't execute a configured [`policyHelper`](/docs/en/settings-reference#policyhelper), so the snapshot can include settings that a live session drops |
369| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered |
370| Parameter | Type | Default | Description |
371| :------------------------------ | :------------------------------------ | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
372| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to |
373| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. [Endpoint-managed policy](/docs/en/managed-settings#delivery-mechanisms) loads in all cases. `resolveSettings()` includes server-managed settings only when you pass `options.serverManagedSettings` |
374| `options.managedSettings` | `Settings` | `undefined` | Policy-tier settings supplied by the embedding host. Follows the same rules as [`managedSettings` in `Options`](#options), except that `resolveSettings()` doesn't execute a configured [`policyHelper`](/docs/en/settings-reference#policyhelper), so the snapshot can include settings that a live session drops |
375| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered |
370376
371377#### Return type: `ResolvedSettings`
372378
from line 840
834840};
835841```
836842
837| Field | Required | Description |
838| :------------------------------------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
839| `description` | Yes | Natural language description of when to use this agent |
840| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |
841| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |
842| `prompt` | Yes | The agent's system prompt |
843| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model |
844| `mcpServers` | No | MCP server specifications for this agent |
845| `skills` | No | Array of skill names to preload into the agent context |
846| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent |
847| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping |
848| `background` | No | Run this agent as a non-blocking background task when invoked |
849| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` |
850| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |
851| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) |
852| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |
843| Field | Required | Description |
844| :------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
845| `description` | Yes | Natural language description of when to use this agent |
846| `tools` | No | Array of allowed tool names. If omitted, inherits every [tool available to subagents](/docs/en/sub-agents#available-tools). To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |
847| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |
848| `prompt` | Yes | The agent's system prompt |
849| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. `'inherit'` uses the main model. If omitted, the agent uses the default subagent model ([`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables)) when one is configured, otherwise the main model |
850| `mcpServers` | No | MCP server specifications for this agent |
851| `skills` | No | Array of skill names to preload into the agent context |
852| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main thread agent |
853| `maxTurns` | No | Maximum number of agentic turns (API round-trips) before stopping |
854| `background` | No | Run this agent as a non-blocking background task when invoked |
855| `memory` | No | Memory source for this agent: `'user'`, `'project'`, or `'local'` |
856| `effort` | No | Reasoning effort level for this agent. Accepts a named level or an integer |
857| `permissionMode` | No | Permission mode for tool execution within this agent. See [`PermissionMode`](#permissionmode) |
858| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Critical reminder added to the system prompt |
853859
854860### `AgentMcpServerSpec`
855861
from line 3658
36523658| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36533659| `status` | `"async_launched" \| "remote_launched"` | The tool accepted the invocation. `"async_launched"` for in-process runs, `"remote_launched"` for runs dispatched to a remote session instead of running in-process |
36543660| `taskId` | `string` | Background task identifier for the run |
3655| `taskType` | `"local_workflow" \| "remote_agent"` | Task type of the registered background task, matching the `status` arm |
3656| `workflowName` | `string` | The `meta.name` from the workflow script |
3657| `runId` | `string` | Workflow run identifier to pass as `resumeFromRunId` on a later invocation. Absent for `remote_launched` runs, where the cloud session URL is the resume handle |
3658| `summary` | `string` | One-line description of what the workflow does |
3659| `transcriptDir` | `string` | Directory where subagent transcripts are written during execution |
3660| `scriptPath` | `string` | Path to the persisted workflow script for this run. Edit it and pass back as `scriptPath` to rerun without resending the script |
3661| `sessionUrl` | `string` | Cloud session URL, set when `status` is `"remote_launched"` |
3662| `warning` | `string` | Non-blocking heads-up, such as local git state diverging from the pushed branch a cloud session will clone |
3663| `error`
3661| `taskType` | `"local_workflow" \| "remote_agent"` | Task type of the registered background t
No line in this hunk matches that.