What each built-in tool in Codex CLI and Claude Code does, what it takes and what it returns. Start from a job, or search a tool name such as write_stdin or TaskStop. A listed tool can still be switched off in your session; each entry says what turns it on.
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them. This schema describes the code-mode value. Direct model delivery uses image or context-fragment content, not necessarily a JSON string.
Field
Type
Required
Meaning and defaults
current_time
string
Yes
Current UTC time formatted as YYYY-MM-DD HH:MM:SS UTC.
Full result definition
{
"additionalProperties": false,
"properties": {
"current_time": {
"description": "Current UTC time formatted as YYYY-MM-DD HH:MM:SS UTC.",
"type": "string"
}
},
"required": [
"current_time"
],
"type": "object"
}
clock.sleepPause execution for a specified duration.
SleepTool plus sleep_tool_mode: always_on, or model-driven clock/current-time reminder eligibility. Direct-model-only.
InputJSON Schema
Field
Type
Required
Meaning and defaults
duration_ms
number
Yes
How long to sleep in milliseconds. Must be between 1 and 43200000.
Full input definition
{
"type": "object",
"properties": {
"duration_ms": {
"type": "number",
"description": "How long to sleep in milliseconds. Must be between 1 and 43200000."
}
},
"required": [
"duration_ms"
],
"additionalProperties": false
}
ResultFree-form result
Source emits a text result and sleep lifecycle item; new user input can end sleep early. No JSON output schema.
effective ToolMode CodeMode or CodeModeOnly; requires policy to allow exec. Nested third-party tools may be deferred/direct-only/excluded; not a general Node runtime.
InputFreeform grammar
Freeform JavaScript with optional // @exec JSON pragma. yield_time_ms and max_output_tokens are pragma controls; actual visible nested tools come from router exposure.
exec_commandRuns a command in a PTY, returning output or a session ID for ongoing interaction.
ShellTool; model shell type enabled. UnifiedExec enables resumable sessions; otherwise policy may select one-shot exec_command. environment_id is advertised for multiple environments; additional_permissions and its enum value require ExecPermissionApprovals plus tool policy.
InputJSON Schema
Field
Type
Required
Meaning and defaults
additional_permissions
object
No
Sandboxed filesystem or network access for this command; only with sandbox_permissions: "with_additional_permissions".
.file_system
object
No
Filesystem access request.
.read
string[]
No
Absolute paths to grant read access; omit when none are needed.
.write
string[]
No
Absolute paths to grant write access; omit when none are needed.
.network
object
No
Network access request.
.enabled
boolean
No
True requests network access; false or omitted requests none.
cmd
string
Yes
Shell command to execute.
environment_id
string
No
Environment id from <environment_context>. Omit to use the primary environment.
justification
string
No
User-facing approval question for require_escalated; omit otherwise.
login
boolean
No
True runs the shell with -l/-i semantics; false disables them. Defaults to true.
max_output_tokens
number
No
Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.
prefix_rule
array
No
Reusable approval prefix for cmd, only with sandbox_permissions: "require_escalated"; for example ["git", "pull"].
Per-command sandbox override. Defaults to use_default; use with_additional_permissions with additional_permissions, or require_escalated for unsandboxed execution.
shell
string
No
Shell binary to launch. Defaults to the user's default shell.
tty
boolean
No
True allocates a PTY for the command; false or omitted uses plain pipes.
workdir
string
No
Working directory for the command. Defaults to the turn cwd.
yield_time_ms
number
No
Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.
Full input definition
{
"type": "object",
"properties": {
"additional_permissions": {
"type": "object",
"description": "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`.",
"properties": {
"file_system": {
"type": "object",
"description": "Filesystem access request.",
"properties": {
"read": {
"type": "array",
"description": "Absolute paths to grant read access; omit when none are needed.",
"items": {
"type": "string"
}
},
"write": {
"type": "array",
"description": "Absolute paths to grant write access; omit when none are needed.",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"network": {
"type": "object",
"description": "Network access request.",
"properties": {
"enabled": {
"type": "boolean",
"description": "True requests network access; false or omitted requests none."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"cmd": {
"type": "string",
"description": "Shell command to execute."
},
"environment_id": {
"type": "string",
"description": "Environment id from <environment_context>. Omit to use the primary environment."
},
"justification": {
"type": "string",
"description": "User-facing approval question for `require_escalated`; omit otherwise."
},
"login": {
"type": "boolean",
"description": "True runs the shell with -l/-i semantics; false disables them. Defaults to true."
},
"max_output_tokens": {
"type": "number",
"description": "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy."
},
"prefix_rule": {
"type": "array",
"description": "Reusable approval prefix for `cmd`, only with `sandbox_permissions: \"require_escalated\"`; for example [\"git\", \"pull\"].",
"items": {
"type": "string"
}
},
"sandbox_permissions": {
"type": "string",
"description": "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions`, or `require_escalated` for unsandboxed execution.",
"enum": [
"use_default",
"with_additional_permissions",
"require_escalated"
]
},
"shell": {
"type": "string",
"description": "Shell binary to launch. Defaults to the user's default shell."
},
"tty": {
"type": "boolean",
"description": "True allocates a PTY for the command; false or omitted uses plain pipes."
},
"workdir": {
"type": "string",
"description": "Working directory for the command. Defaults to the turn cwd."
},
"yield_time_ms": {
"type": "number",
"description": "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms."
}
},
"required": [
"cmd"
],
"additionalProperties": false
}
ResultJSON Schema
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them. Direct model output is a formatted text rendering; code_mode_result returns this object. Session lifecycle/protocol events are separate.
Field
Type
Required
Meaning and defaults
chunk_id
string
No
Chunk identifier included when the response reports one.
exit_code
number
No
Process exit code when the command finished during this call.
original_token_count
number
No
Approximate token count before output truncation.
output
string
Yes
Command output text, possibly truncated.
session_id
number
No
Session identifier to pass to write_stdin when the process is still running.
wall_time_seconds
number
Yes
Elapsed wall time spent waiting for output in seconds.
Full result definition
{
"additionalProperties": false,
"properties": {
"chunk_id": {
"description": "Chunk identifier included when the response reports one.",
"type": "string"
},
"exit_code": {
"description": "Process exit code when the command finished during this call.",
"type": "number"
},
"original_token_count": {
"description": "Approximate token count before output truncation.",
"type": "number"
},
"output": {
"description": "Command output text, possibly truncated.",
"type": "string"
},
"session_id": {
"description": "Session identifier to pass to write_stdin when the process is still running.",
"type": "number"
},
"wall_time_seconds": {
"description": "Elapsed wall time spent waiting for output in seconds.",
"type": "number"
}
},
"required": [
"wall_time_seconds",
"output"
],
"type": "object"
}
Failures and lifecycle
Returns session_id while running; exit_code after completion; bounded output may be truncated. tty defaults false. login defaults true. yield_time_ms defaults 10000. Handler also parses timeout_ms, which is not an advertised schema field. Advertised number fields may be narrower unsigned/integer serde fields at execution.
One-shot exec_command removes resumable process authority; a familiar tool name does not imply write_stdin availability.
followup_taskSend a follow-up task to an existing non-root target agent and trigger a turn if it is idle.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
message
string
Yes
Message text to send to the target agent.
target
string
Yes
Agent id or canonical task name to send a follow-up task to (from spawn_agent).
Full input definition
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message text to send to the target agent.",
"encrypted": true
},
"target": {
"type": "string",
"description": "Agent id or canonical task name to send a follow-up task to (from spawn_agent)."
}
},
"required": [
"target",
"message"
],
"additionalProperties": false
}
ResultFree-form result
Message dispatch returns empty FunctionToolOutput on success; does not prove recipient execution or completion.
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them. This schema describes the code-mode value. Direct model delivery uses image or context-fragment content, not necessarily a JSON string.
Field
Type
Required
Meaning and defaults
tokens_left
{"type":"integer"} | {"type":"null"}
Yes
Remaining tokens in the current context window, or null when unavailable.
Full result definition
{
"additionalProperties": false,
"properties": {
"tokens_left": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Remaining tokens in the current context window, or null when unavailable."
}
},
"required": [
"tokens_left"
],
"type": "object"
}
interrupt_agentInterrupt an agent's current turn, if any, and return its previous status.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
target
string
Yes
Agent id or canonical task name to interrupt (from spawn_agent).
Full input definition
{
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Agent id or canonical task name to interrupt (from spawn_agent)."
}
},
"required": [
"target"
],
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
previous_status
see schema
Yes
The agent status observed before the interrupt request was handled.
list_agentsList live agents in the current root thread tree.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
path_prefix
string
No
Task-path prefix filter without a trailing slash. Omit to list all live agents.
Full input definition
{
"type": "object",
"properties": {
"path_prefix": {
"type": "string",
"description": "Task-path prefix filter without a trailing slash. Omit to list all live agents."
}
},
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
agents
array
Yes
Live agents visible in the current root thread tree.
[].agent_name
string
Yes
Canonical task name for the agent when available, otherwise the agent id.
Implementation result declarations, not a formal output schema. Plugin suggestion completion and user confirmation do not alone prove future tool availability.
multi_agent_v1.close_agentClose an agent and any open descendants when they are no longer needed, and return the target agent's previous status before shutdown was requested.
MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.
InputJSON Schema
Field
Type
Required
Meaning and defaults
target
string
Yes
Agent id to close (from spawn_agent).
Full input definition
{
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Agent id to close (from spawn_agent)."
}
},
"required": [
"target"
],
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
previous_status
see schema
Yes
The agent status observed before shutdown was requested.
multi_agent_v1.send_inputSend a message to an existing agent.
MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.
InputJSON Schema
Field
Type
Required
Meaning and defaults
interrupt
boolean
No
True interrupts the current task and handles this message immediately; false or omitted queues it.
items
array
No
Structured input items. Use this to pass explicit mentions (for example app:// connector paths).
[].audio_url
string
No
Audio data URL when type is audio.
[].image_url
string
No
Image URL when type is image.
[].name
string
No
Display name when type is skill or mention.
[].path
string
No
Path when type is local_image/local_audio/skill, or structured mention target such as app://<connector-id> or plugin://<plugin-name>@<marketplace-name> when type is mention.
Legacy plain-text message to send to the agent. Use either message or items.
target
string
Yes
Agent id to message (from spawn_agent).
Full input definition
{
"type": "object",
"properties": {
"interrupt": {
"type": "boolean",
"description": "True interrupts the current task and handles this message immediately; false or omitted queues it."
},
"items": {
"type": "array",
"description": "Structured input items. Use this to pass explicit mentions (for example app:// connector paths).",
"items": {
"type": "object",
"properties": {
"audio_url": {
"type": "string",
"description": "Audio data URL when type is audio."
},
"image_url": {
"type": "string",
"description": "Image URL when type is image."
},
"name": {
"type": "string",
"description": "Display name when type is skill or mention."
},
"path": {
"type": "string",
"description": "Path when type is local_image/local_audio/skill, or structured mention target such as app://<connector-id> or plugin://<plugin-name>@<marketplace-name> when type is mention."
},
"text": {
"type": "string",
"description": "Text content when type is text."
},
"type": {
"type": "string",
"description": "Input item type: text, image, local_image, audio, local_audio, skill, or mention."
}
},
"additionalProperties": false
}
},
"message": {
"type": "string",
"description": "Legacy plain-text message to send to the agent. Use either message or items."
},
"target": {
"type": "string",
"description": "Agent id to message (from spawn_agent)."
}
},
"required": [
"target"
],
"additionalProperties": false
}
multi_agent_v1.spawn_agentSpawn a sub-agent for a well-scoped task.
MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.
InputJSON Schema
Field
Type
Required
Meaning and defaults
agent_type
string
No
Agent type override for the new agent. Omit to inherit the parent agent type with a full-history fork; otherwise, default is used.
fork_context
boolean
No
True forks the current thread history into the new agent; false or omitted starts with only the initial prompt.
items
array
No
Structured input items. Use this to pass explicit mentions (for example app:// connector paths).
[].audio_url
string
No
Audio data URL when type is audio.
[].image_url
string
No
Image URL when type is image.
[].name
string
No
Display name when type is skill or mention.
[].path
string
No
Path when type is local_image/local_audio/skill, or structured mention target such as app://<connector-id> or plugin://<plugin-name>@<marketplace-name> when type is mention.
Initial plain-text task for the new agent. Use either message or items.
model
string
No
Model override for the new agent. Omit unless an explicit override is needed.
reasoning_effort
string
No
Reasoning effort override for the new agent. Omit to inherit the parent effort.
Full input definition
{
"type": "object",
"properties": {
"agent_type": {
"type": "string",
"description": "Agent type override for the new agent. Omit to inherit the parent agent type with a full-history fork; otherwise, `default` is used.\n"
},
"fork_context": {
"type": "boolean",
"description": "True forks the current thread history into the new agent; false or omitted starts with only the initial prompt."
},
"items": {
"type": "array",
"description": "Structured input items. Use this to pass explicit mentions (for example app:// connector paths).",
"items": {
"type": "object",
"properties": {
"audio_url": {
"type": "string",
"description": "Audio data URL when type is audio."
},
"image_url": {
"type": "string",
"description": "Image URL when type is image."
},
"name": {
"type": "string",
"description": "Display name when type is skill or mention."
},
"path": {
"type": "string",
"description": "Path when type is local_image/local_audio/skill, or structured mention target such as app://<connector-id> or plugin://<plugin-name>@<marketplace-name> when type is mention."
},
"text": {
"type": "string",
"description": "Text content when type is text."
},
"type": {
"type": "string",
"description": "Input item type: text, image, local_image, audio, local_audio, skill, or mention."
}
},
"additionalProperties": false
}
},
"message": {
"type": "string",
"description": "Initial plain-text task for the new agent. Use either message or items."
},
"model": {
"type": "string",
"description": "Model override for the new agent. Omit unless an explicit override is needed."
},
"reasoning_effort": {
"type": "string",
"description": "Reasoning effort override for the new agent. Omit to inherit the parent effort."
}
},
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
agent_id
string
Yes
Thread identifier for the spawned agent.
nickname
"string" | "null"
Yes
User-facing nickname for the spawned agent when available.
Full result definition
{
"additionalProperties": false,
"properties": {
"agent_id": {
"description": "Thread identifier for the spawned agent.",
"type": "string"
},
"nickname": {
"description": "User-facing nickname for the spawned agent when available.",
"type": [
"string",
"null"
]
}
},
"required": [
"agent_id",
"nickname"
],
"type": "object"
}
request_permissionsRequest additional filesystem or network permissions from the user and wait for the client to grant a subset of the requested permission profile.
RequestPermissionsTool feature; selected environment and client grant response. Handler accepts environmentId as an alias of environment_id.
Aliases and version differences: environmentId (handler input alias; schema advertises environment_id)
InputJSON Schema
Field
Type
Required
Meaning and defaults
environment_id
string
No
Environment id from <environment_context>. Omit to use the primary environment.
permissions
object
Yes
Filesystem or network access request.
.file_system
object
No
Filesystem access request.
.read
string[]
No
Absolute paths to grant read access; omit when none are needed.
.write
string[]
No
Absolute paths to grant write access; omit when none are needed.
.network
object
No
Network access request.
.enabled
boolean
No
True requests network access; false or omitted requests none.
reason
string
No
Optional short explanation for why additional permissions are needed.
Full input definition
{
"type": "object",
"properties": {
"environment_id": {
"type": "string",
"description": "Environment id from <environment_context>. Omit to use the primary environment."
},
"permissions": {
"type": "object",
"description": "Filesystem or network access request.",
"properties": {
"file_system": {
"type": "object",
"description": "Filesystem access request.",
"properties": {
"read": {
"type": "array",
"description": "Absolute paths to grant read access; omit when none are needed.",
"items": {
"type": "string"
}
},
"write": {
"type": "array",
"description": "Absolute paths to grant write access; omit when none are needed.",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"network": {
"type": "object",
"description": "Network access request.",
"properties": {
"enabled": {
"type": "boolean",
"description": "True requests network access; false or omitted requests none."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"reason": {
"type": "string",
"description": "Optional short explanation for why additional permissions are needed."
}
},
"required": [
"permissions"
],
"additionalProperties": false
}
ResultSource declaration
Serde response serialized by the handler, not an advertised output schema. Permission profiles can grant a subset or nothing; scope/defaults follow protocol types. Referenced permission enums/models remain linked rather than flattened.
request_plugin_installRequest installation of an explicitly selected plugin or connector.
ToolSuggest + Apps + Plugins and nonempty candidate list; either ListTool or RecommendationContext presentation.
InputJSON Schema
Reference union of the two constructor variants. Runtime chooses ListTool or RecommendationContext; it does not advertise this union. tool_type/action_type are strings with prose constraints, not formal enums.
Full input definition
{
"anyOf": [
{
"type": "object",
"properties": {
"plugin_id": {
"type": "string",
"description": "The parenthesized plugin ID from the `<recommended_plugins>` list."
},
"suggest_reason": {
"type": "string",
"description": "Concise one-line user-facing reason why this plugin can help with the current request."
}
},
"required": [
"plugin_id",
"suggest_reason"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"action_type": {
"type": "string",
"description": "Suggested action for the tool. Use \"install\"."
},
"suggest_reason": {
"type": "string",
"description": "Concise one-line user-facing reason why this plugin or connector can help with the current request."
},
"tool_id": {
"type": "string",
"description": "Connector or plugin id to suggest."
},
"tool_type": {
"type": "string",
"description": "Type of discoverable tool to suggest. Use \"connector\" or \"plugin\"."
}
},
"required": [
"tool_type",
"action_type",
"tool_id",
"suggest_reason"
],
"additionalProperties": false
}
]
}
ResultSource declaration
Implementation result declarations, not a formal output schema. Plugin suggestion completion and user confirmation do not alone prove future tool availability.
experimental_request_user_input_enabled. Direct-model-only; handler checks the configured allowed collaboration modes (Plan by default).
InputJSON Schema
Field
Type
Required
Meaning and defaults
questions
array
Yes
Questions to show the user. Prefer 1 and do not exceed 3
[].header
string
Yes
Short header label shown in the UI (12 or fewer chars).
[].id
string
Yes
Stable identifier for mapping answers (snake_case).
[].options
object[]
Yes
Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option in this list; the client will add a free-form "Other" option automatically.
[].description
string
Yes
One short sentence explaining impact/tradeoff if selected.
[].label
string
Yes
User-facing label (1-5 words).
[].question
string
Yes
Single-sentence prompt shown to the user.
Full input definition
{
"type": "object",
"properties": {
"questions": {
"type": "array",
"description": "Questions to show the user. Prefer 1 and do not exceed 3",
"items": {
"type": "object",
"properties": {
"header": {
"type": "string",
"description": "Short header label shown in the UI (12 or fewer chars)."
},
"id": {
"type": "string",
"description": "Stable identifier for mapping answers (snake_case)."
},
"options": {
"type": "array",
"description": "Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with \"(Recommended)\". Do not include an \"Other\" option in this list; the client will add a free-form \"Other\" option automatically.",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "One short sentence explaining impact/tradeoff if selected."
},
"label": {
"type": "string",
"description": "User-facing label (1-5 words)."
}
},
"required": [
"label",
"description"
],
"additionalProperties": false
}
},
"question": {
"type": "string",
"description": "Single-sentence prompt shown to the user."
}
},
"required": [
"id",
"header",
"question",
"options"
],
"additionalProperties": false
}
}
},
"required": [
"questions"
],
"additionalProperties": false
}
ResultSource declaration
Serde response serialized by the handler, not an advertised output schema. Permission profiles can grant a subset or nothing; scope/defaults follow protocol types. Referenced permission enums/models remain linked rather than flattened.
request_user_input_asyncPresent questions without waiting for a reply.
experimental_request_user_input_enabled; root agent; model catalog advertises request_user_input_async or historical send_user_message_async. Direct-model-only; catalog can override parameters.
Aliases and version differences: send_user_message_async (catalog eligibility name only; not a second registered callable)
InputJSON Schema
Field
Type
Required
Meaning and defaults
questions
array
Yes
One or more self-contained questions to present together, in display order.
[].options
string[]
No
Suggested answers, in display order. Put the recommended answer first; the first option is preselected by default. The user can select one option or enter a free-text answer. Do not include an Other option or a free-text placeholder; the UI provides free-text input automatically. Omit options for a free-text-only question.
[].title
string
Yes
The complete question shown to the user, including any context needed to answer it.
Full input definition
{
"type": "object",
"properties": {
"questions": {
"type": "array",
"description": "One or more self-contained questions to present together, in display order.",
"items": {
"type": "object",
"properties": {
"options": {
"type": "array",
"description": "Suggested answers, in display order. Put the recommended answer first; the first option is preselected by default. The user can select one option or enter a free-text answer. Do not include an Other option or a free-text placeholder; the UI provides free-text input automatically. Omit options for a free-text-only question.",
"items": {
"type": "string"
},
"minItems": 1
},
"title": {
"type": "string",
"description": "The complete question shown to the user, including any context needed to answer it."
}
},
"required": [
"title"
],
"additionalProperties": false
},
"minItems": 1
}
},
"required": [
"questions"
],
"additionalProperties": false
}
ResultImplementation shape
Handler emits JSON text; accepts delivery asynchronously, does not wait for a user response.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
message
string
Yes
Message text to queue on the target agent.
target
string
Yes
Relative or canonical task name to message (from spawn_agent).
Full input definition
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message text to queue on the target agent.",
"encrypted": true
},
"target": {
"type": "string",
"description": "Relative or canonical task name to message (from spawn_agent)."
}
},
"required": [
"target",
"message"
],
"additionalProperties": false
}
ResultFree-form result
Message dispatch returns empty FunctionToolOutput on success; does not prove recipient execution or completion.
spawn_agentSpawns an agent to work on the specified task.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
agent_type
string
No
Agent type override for the new agent. Omit unless explicitly asked. The selected role applies regardless of how much parent history is inherited.
fork_turns
string
No
Parent history to inherit. Defaults to all; use none to start without parent history. Only all and none are supported.
message
string
Yes
Initial plain-text task for the new agent.
model
string
No
Model override for the new agent. Omit unless an explicit override is needed.
reasoning_effort
string
No
Reasoning effort override for the new agent. Omit to inherit the parent effort.
task_name
string
Yes
Task name for the new agent. Use lowercase letters, digits, and underscores.
Full input definition
{
"type": "object",
"properties": {
"agent_type": {
"type": "string",
"description": "Agent type override for the new agent. Omit unless explicitly asked. The selected role applies regardless of how much parent history is inherited.\n"
},
"fork_turns": {
"type": "string",
"description": "Parent history to inherit. Defaults to `all`; use `none` to start without parent history. Only `all` and `none` are supported."
},
"message": {
"type": "string",
"description": "Initial plain-text task for the new agent.",
"encrypted": true
},
"model": {
"type": "string",
"description": "Model override for the new agent. Omit unless an explicit override is needed."
},
"reasoning_effort": {
"type": "string",
"description": "Reasoning effort override for the new agent. Omit to inherit the parent effort."
},
"task_name": {
"type": "string",
"description": "Task name for the new agent. Use lowercase letters, digits, and underscores."
}
},
"required": [
"task_name",
"message"
],
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
nickname
"string" | "null"
Yes
User-facing nickname for the spawned agent when available.
task_name
string
Yes
Canonical task name for the spawned agent.
Full result definition
{
"additionalProperties": false,
"properties": {
"nickname": {
"description": "User-facing nickname for the spawned agent when available.",
"type": [
"string",
"null"
]
},
"task_name": {
"description": "Canonical task name for the spawned agent.",
"type": "string"
}
},
"required": [
"task_name",
"nickname"
],
"type": "object"
}
test_sync_toolInternal synchronization helper used by Codex integration tests.
Only model metadata experimental_supported_tools includes test_sync_tool; integration-test helper.
InputJSON Schema
Field
Type
Required
Meaning and defaults
barrier
object
No
.id
string
Yes
Identifier shared by concurrent calls that should rendezvous
.participants
number
Yes
Number of tool calls that must arrive before the barrier opens
.timeout_ms
number
No
Maximum barrier wait in milliseconds. Defaults to 1000.
sleep_after_ms
number
No
Delay after completing the barrier. Defaults to no delay.
sleep_before_ms
number
No
Delay before any other action. Defaults to no delay.
wait_for_git_enrichment
boolean
No
Wait for Git enrichment for the current turn to finish, subject to a timeout.
Full input definition
{
"type": "object",
"properties": {
"barrier": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier shared by concurrent calls that should rendezvous"
},
"participants": {
"type": "number",
"description": "Number of tool calls that must arrive before the barrier opens"
},
"timeout_ms": {
"type": "number",
"description": "Maximum barrier wait in milliseconds. Defaults to 1000."
}
},
"required": [
"id",
"participants"
],
"additionalProperties": false
},
"sleep_after_ms": {
"type": "number",
"description": "Delay after completing the barrier. Defaults to no delay."
},
"sleep_before_ms": {
"type": "number",
"description": "Delay before any other action. Defaults to no delay."
},
"wait_for_git_enrichment": {
"type": "boolean",
"description": "Wait for Git enrichment for the current turn to finish, subject to a timeout."
}
},
"additionalProperties": false
}
ResultFree-form result
Internal integration-test helper; barrier timeout and Git-enrichment failures may be model-facing errors.
view_imageView a local image file from the filesystem when visual inspection is needed.
ViewImage feature. environment_id only for multiple environments; detail only when original detail is supported and unified image budget is off.
InputJSON Schema
Field
Type
Required
Meaning and defaults
detail
"high" | "original"
No
Image detail level. Defaults to high; use original to preserve exact resolution.
environment_id
string
No
Environment id from <environment_context>. Omit to use the primary environment.
path
string
Yes
Local filesystem path to an image file.
Full input definition
{
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "Image detail level. Defaults to `high`; use `original` to preserve exact resolution.",
"enum": [
"high",
"original"
]
},
"environment_id": {
"type": "string",
"description": "Environment id from <environment_context>. Omit to use the primary environment."
},
"path": {
"type": "string",
"description": "Local filesystem path to an image file."
}
},
"required": [
"path"
],
"additionalProperties": false
}
ResultJSON Schema
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them. This schema describes the code-mode value. Direct model delivery uses image or context-fragment content, not necessarily a JSON string.
Field
Type
Required
Meaning and defaults
detail
"high" | "original"
Yes
Image detail hint returned by view_image. Returns high for default resized behavior or original when original resolution is preserved.
image_url
string
Yes
Data URL for the loaded image.
Full result definition
{
"additionalProperties": false,
"properties": {
"detail": {
"description": "Image detail hint returned by view_image. Returns `high` for default resized behavior or `original` when original resolution is preserved.",
"enum": [
"high",
"original"
],
"type": "string"
},
"image_url": {
"description": "Data URL for the loaded image.",
"type": "string"
}
},
"required": [
"image_url",
"detail"
],
"type": "object"
}
wait_agentWait for a mailbox update from any live agent, including queued messages and final-status notifications.
MultiAgentVersion V2; disable_native_tools must be false; child model must support V2. Configurable tool namespace. disable_direct_message removes send_message/followup_task; wait_agent_enabled controls wait_agent. Catalog may override parameters; spawn metadata/model fields are configurable.
InputJSON Schema
Field
Type
Required
Meaning and defaults
timeout_ms
number
No
Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000.
Full input definition
{
"type": "object",
"properties": {
"timeout_ms": {
"type": "number",
"description": "Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000."
}
},
"additionalProperties": false
}
ResultJSON Schema
Field
Type
Required
Meaning and defaults
message
string
Yes
Brief wait summary without the agent's final content, including any timeout adjustment.
timed_out
boolean
Yes
Whether the wait call returned because no mailbox update arrived before the timeout.
Full result definition
{
"additionalProperties": false,
"properties": {
"message": {
"description": "Brief wait summary without the agent's final content, including any timeout adjustment.",
"type": "string"
},
"timed_out": {
"description": "Whether the wait call returned because no mailbox update arrived before the timeout.",
"type": "boolean"
}
},
"required": [
"message",
"timed_out"
],
"type": "object"
}
write_stdinWrites characters to an existing unified exec session and returns recent output.
ShellTool + UnifiedExec, enabled model shell type and tool policy; operates only on a live unified-exec session in this runtime.
InputJSON Schema
Field
Type
Required
Meaning and defaults
chars
string
No
Bytes to write to stdin. Defaults to empty, which polls without writing.
max_output_tokens
number
No
Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.
session_id
number
Yes
Identifier of the running unified exec session.
yield_time_ms
number
No
Wait before yielding output. Non-empty writes default to 250 ms and cap at 30000 ms; empty polls wait 5000-300000 ms by default.
Full input definition
{
"type": "object",
"properties": {
"chars": {
"type": "string",
"description": "Bytes to write to stdin. Defaults to empty, which polls without writing."
},
"max_output_tokens": {
"type": "number",
"description": "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy."
},
"session_id": {
"type": "number",
"description": "Identifier of the running unified exec session."
},
"yield_time_ms": {
"type": "number",
"description": "Wait before yielding output. Non-empty writes default to 250 ms and cap at 30000 ms; empty polls wait 5000-300000 ms by default."
}
},
"required": [
"session_id"
],
"additionalProperties": false
}
ResultJSON Schema
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them. Direct model output is a formatted text rendering; code_mode_result returns this object. Session lifecycle/protocol events are separate.
Field
Type
Required
Meaning and defaults
chunk_id
string
No
Chunk identifier included when the response reports one.
exit_code
number
No
Process exit code when the command finished during this call.
original_token_count
number
No
Approximate token count before output truncation.
output
string
Yes
Command output text, possibly truncated.
session_id
number
No
Session identifier to pass to write_stdin when the process is still running.
wall_time_seconds
number
Yes
Elapsed wall time spent waiting for output in seconds.
Full result definition
{
"additionalProperties": false,
"properties": {
"chunk_id": {
"description": "Chunk identifier included when the response reports one.",
"type": "string"
},
"exit_code": {
"description": "Process exit code when the command finished during this call.",
"type": "number"
},
"original_token_count": {
"description": "Approximate token count before output truncation.",
"type": "number"
},
"output": {
"description": "Command output text, possibly truncated.",
"type": "string"
},
"session_id": {
"description": "Session identifier to pass to write_stdin when the process is still running.",
"type": "number"
},
"wall_time_seconds": {
"description": "Elapsed wall time spent waiting for output in seconds.",
"type": "number"
}
},
"required": [
"wall_time_seconds",
"output"
],
"type": "object"
}
Failures and lifecycle
session_id must refer to a running process. chars defaults empty (poll). With nonempty chars yield defaults 250 ms and caps at 30000; empty polls use 5000–300000 ms. Completion returns exit_code and ends the live session.
App Server goal extension installed with state DB; Goals feature enabled. Mutations validate current goal state and token budget.
InputJSON Schema
Field
Type
Required
Meaning and defaults
objective
string
Yes
Required. The concrete objective to start pursuing. This starts a new active goal when no goal exists or replaces the current goal when it is complete.
token_budget
integer
No
Positive token budget for the new goal. Omit unless explicitly requested.
Full input definition
{
"type": "object",
"properties": {
"objective": {
"type": "string",
"description": "Required. The concrete objective to start pursuing. This starts a new active goal when no goal exists or replaces the current goal when it is complete."
},
"token_budget": {
"type": "integer",
"description": "Positive token budget for the new goal. Omit unless explicitly requested."
}
},
"required": [
"objective"
],
"additionalProperties": false
}
ResultSource declaration
Serialized implementation response, not an advertised output schema. goal can be null; optional budget report depends on operation.
Message role to include. Null or omission includes all roles.
tool_name
{"type":"string"} | {"type":"null"}
No
Callable tool name to include. When set, non-tool messages are excluded.
tool_namespace
{"type":"string"} | {"type":"null"}
No
Callable namespace to include. When set, non-tool messages are excluded.
window_id
{"type":"string"} | {"type":"null"}
No
Full window ID. Null or omission includes all windows.
Full input definition
{
"type": "object",
"properties": {
"agent_name": {
"description": "Agent whose history to inspect. Omit to use the current agent; otherwise pass an absolute agent name or a name relative to the current agent.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"limit": {
"type": "integer",
"description": "Maximum number of items to return."
},
"max_chars_per_item": {
"type": "integer",
"description": "Maximum characters returned in each item's truncated_content."
},
"recent_first": {
"type": "boolean",
"description": "Whether to return the most recently created items first."
},
"role": {
"description": "Message role to include. Null or omission includes all roles.",
"anyOf": [
{
"type": "string",
"enum": [
"user",
"assistant",
"tool",
"system",
"developer"
]
},
{
"type": "null"
}
]
},
"tool_name": {
"description": "Callable tool name to include. When set, non-tool messages are excluded.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tool_namespace": {
"description": "Callable namespace to include. When set, non-tool messages are excluded.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"window_id": {
"description": "Full window ID. Null or omission includes all windows.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
Agent whose history to inspect. Omit to use the current agent; otherwise pass an absolute agent name or a name relative to the current agent.
limit
integer
No
Maximum number of windows to return.
recent_first
boolean
No
Whether to return the most recently created windows first.
Full input definition
{
"type": "object",
"properties": {
"agent_name": {
"description": "Agent whose history to inspect. Omit to use the current agent; otherwise pass an absolute agent name or a name relative to the current agent.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"limit": {
"type": "integer",
"description": "Maximum number of windows to return."
},
"recent_first": {
"type": "boolean",
"description": "Whether to return the most recently created windows first."
}
}
}
Agent whose history to inspect. Omit to use the current agent; otherwise pass an absolute agent name or a name relative to the current agent.
item_id
string
Yes
The short item ID is the suffix shown in the target item's trailing [id: ...] marker, printed after that item's content.
limit_chars
integer
No
Maximum number of characters to return.
offset_chars
integer
No
Zero-based character offset at which reading starts.
window_id
string
Yes
Full window ID containing the item.
Full input definition
{
"type": "object",
"properties": {
"agent_name": {
"description": "Agent whose history to inspect. Omit to use the current agent; otherwise pass an absolute agent name or a name relative to the current agent.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"item_id": {
"type": "string",
"description": "The short item ID is the suffix shown in the target item's trailing `[id: ...]` marker, printed after that item's content."
},
"limit_chars": {
"type": "integer",
"description": "Maximum number of characters to return."
},
"offset_chars": {
"type": "integer",
"description": "Zero-based character offset at which reading starts."
},
"window_id": {
"type": "string",
"description": "Full window ID containing the item."
}
},
"required": [
"item_id",
"window_id"
]
}
image_gen.imagegenGenerate or edit an image using the configured image backend.
Installed image-generation contributor with eligible provider; core requires ImageGeneration, non-Free account, provider image_generation capability, image input modality, and either OpenAI actor authorization or requires_openai_auth with Codex-backend authentication.
InputSource declaration
Full source input declaration. AbsolutePathBuf serializes as an absolute path string. transparent_background defaults false; paths and num_last_images_to_include are alternative edit-reference mechanisms.
Full input definition
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
struct ImagegenArgs {
prompt: String,
/// Whether the output should have a transparent background. Defaults to false.
#[serde(default)]
transparent_background: bool,
#[schemars(length(max = 5))]
referenced_image_paths: Option<Vec<AbsolutePathBuf>>,
#[schemars(range(min = 1, max = 5))]
num_last_images_to_include: Option<usize>,
}
ResultImplementation shape
Direct model output is image content; code-mode result exposes image_url and optional output_hint. No advertised output schema. Image bytes are omitted from logs.
List max_results defaults/caps at 2000; search at 200; read max estimated tokens 20000. Backend rejects invalid paths/cursors/queries; IO failures are fatal. Ad-hoc note creation rejects invalid filenames, empty notes and collisions. No runtime probe.
List max_results defaults/caps at 2000; search at 200; read max estimated tokens 20000. Backend rejects invalid paths/cursors/queries; IO failures are fatal. Ad-hoc note creation rejects invalid filenames, empty notes and collisions. No runtime probe.
List max_results defaults/caps at 2000; search at 200; read max estimated tokens 20000. Backend rejects invalid paths/cursors/queries; IO failures are fatal. Ad-hoc note creation rejects invalid filenames, empty notes and collisions. No runtime probe.
List max_results defaults/caps at 2000; search at 200; read max estimated tokens 20000. Backend rejects invalid paths/cursors/queries; IO failures are fatal. Ad-hoc note creation rejects invalid filenames, empty notes and collisions. No runtime probe.
skills.installationsPage installations for a skill package.
Installed skills extension with SkillsStepState.tools_enabled; installations and source-aware read require discovery_v2. Executor, host, cloud and custom providers are framework kinds; concrete App Server registers executor/host and optional cloud. Model tools select supported cloud/executor authorities.
Pagination uses opaque cursors; bounded responses may contain warnings/next_cursor. Handle/cursor/source validation can fail independently of provider IO; provider registration does not establish hosted availability.
skills.listPage a selected skill authority catalog.
Installed skills extension with SkillsStepState.tools_enabled; installations and source-aware read require discovery_v2. Executor, host, cloud and custom providers are framework kinds; concrete App Server registers executor/host and optional cloud. Model tools select supported cloud/executor authorities.
Pagination uses opaque cursors; bounded responses may contain warnings/next_cursor. Handle/cursor/source validation can fail independently of provider IO; provider registration does not establish hosted availability.
Installed skills extension with SkillsStepState.tools_enabled; installations and source-aware read require discovery_v2. Executor, host, cloud and custom providers are framework kinds; concrete App Server registers executor/host and optional cloud. Model tools select supported cloud/executor authorities.
InputJSON Schema
Reference union of legacy and discovery_v2 constructor schemas. Runtime advertises one variant; discovery_v2 adds source/installation metadata. SkillLocator is exposed as String via schemars(with="String").
Reference union of legacy and discovery_v2 constructor schemas. Runtime advertises one variant; discovery_v2 adds source/installation metadata. SkillLocator is exposed as String via schemars(with="String").
Pagination uses opaque cursors; bounded responses may contain warnings/next_cursor. Handle/cursor/source validation can fail independently of provider IO; provider registration does not establish hosted availability.
App Server goal extension installed with state DB; Goals feature enabled. Mutations validate current goal state and token budget.
InputJSON Schema
Field
Type
Required
Meaning and defaults
status
"complete" | "blocked" | "paused"
Yes
Required. paused requires an explicit user request. Set to complete only when the objective is achieved and no required work remains. Set to blocked only after the same blocking condition has recurred for at least three consecutive goal turns and the agent is at an impasse. After a previously blocked goal is resumed, the resumed run starts a fresh blocked audit.
Full input definition
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Required. `paused` requires an explicit user request. Set to `complete` only when the objective is achieved and no required work remains. Set to `blocked` only after the same blocking condition has recurred for at least three consecutive goal turns and the agent is at an impasse. After a previously blocked goal is resumed, the resumed run starts a fresh blocked audit.",
"enum": [
"complete",
"blocked",
"paused"
]
}
},
"required": [
"status"
],
"additionalProperties": false
}
ResultSource declaration
Serialized implementation response, not an advertised output schema. goal can be null; optional budget report depends on operation.
web.runExecute standalone search, page, image, PDF, finance, weather, sports or time commands.
Registered web-search contributor; eligible OpenAI/actor/custom supports_standalone_web_search provider and web search not disabled. Core chooses StandaloneWebSearch or compatible model metadata; hosted web_search is a separate alternative.
InputJSON Schema
Field
Type
Required
Meaning and defaults
click
array
No
Open links from previously opened pages.
[].id
integer
Yes
Numbered link id to open.
[].ref_id
string
Yes
Reference id containing the numbered link.
finance
array
No
Look up prices for the given stock symbols.
[].market
string
No
ISO 3166-1 alpha-3 country code, "OTC", or "" for cryptocurrency.
[].ticker
string
Yes
Ticker symbol to look up.
[].type
"equity" | "fund" | "crypto" | "index"
Yes
Asset type to look up.
find
array
No
Find text patterns in pages.
[].pattern
string
Yes
Text pattern to find.
[].ref_id
string
Yes
Reference id or URL to search within.
image_query
array
No
Query the image search engine for a given list of queries.
[].domains
string[]
No
Whether to filter by a specific list of domains.
[].q
string
Yes
Search query.
[].recency
integer
No
Whether to filter by recency, as a number of recent days.
open
array
No
Open pages by reference id or URL.
[].lineno
integer
No
Line number to position the page at.
[].ref_id
string
Yes
Reference id or URL to open.
response_length
"short" | "medium" | "long"
No
Set the length of the response to be returned.
screenshot
array
No
Take screenshots of PDF pages.
[].pageno
integer
Yes
Zero-indexed PDF page number.
[].ref_id
string
Yes
Reference id or URL to screenshot.
search_query
array
No
Query the internet search engine for a given list of queries.
[].domains
string[]
No
Whether to filter by a specific list of domains.
[].q
string
Yes
Search query.
[].recency
integer
No
Whether to filter by recency, as a number of recent days.
Injected by the Codex TUI into the threads it runs.
codex_tui.create_threadCreate and start a task.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
codex_tui.send_message_to_threadSend a prompt to a task.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
codex_tui.set_thread_archivedArchive or restore a task.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
TUI tool_specs() injects a DynamicToolSpec namespace into its App Server thread. Delegation tools can be filtered by non_delegation_tool_specs(); not a core or universal desktop tool.
list_mcp_resource_templatesLists resource templates provided by MCP servers.
Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.
InputJSON Schema
Field
Type
Required
Meaning and defaults
cursor
string
No
Opaque cursor from a previous list_mcp_resource_templates call; omit for the first page.
server
string
No
MCP server name. Omit to list resource templates from every configured server.
Full input definition
{
"type": "object",
"properties": {
"cursor": {
"type": "string",
"description": "Opaque cursor from a previous list_mcp_resource_templates call; omit for the first page."
},
"server": {
"type": "string",
"description": "MCP server name. Omit to list resource templates from every configured server."
}
},
"additionalProperties": false
}
ResultSource declaration
Implementation serde envelope: camelCase list keys (nextCursor/resourceTemplates), server tagging and flattened resource records. Referenced Resource/ResourceTemplate/ReadResourceResult come from rmcp protocol types; server content remains dynamic, not exhaustively reproduced here.
list_mcp_resourcesLists resources provided by MCP servers.
Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.
InputJSON Schema
Field
Type
Required
Meaning and defaults
cursor
string
No
Opaque cursor from a previous list_mcp_resources call; omit for the first page.
server
string
No
MCP server name. Omit to list resources from every configured server.
Full input definition
{
"type": "object",
"properties": {
"cursor": {
"type": "string",
"description": "Opaque cursor from a previous list_mcp_resources call; omit for the first page."
},
"server": {
"type": "string",
"description": "MCP server name. Omit to list resources from every configured server."
}
},
"additionalProperties": false
}
ResultSource declaration
Implementation serde envelope: camelCase list keys (nextCursor/resourceTemplates), server tagging and flattened resource records. Referenced Resource/ResourceTemplate/ReadResourceResult come from rmcp protocol types; server content remains dynamic, not exhaustively reproduced here.
read_mcp_resourceRead a specific resource from an MCP server given the server name and resource URI.
Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.
InputJSON Schema
Field
Type
Required
Meaning and defaults
server
string
Yes
MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources.
uri
string
Yes
Resource URI to read. Must be one of the URIs returned by list_mcp_resources.
Full input definition
{
"type": "object",
"properties": {
"server": {
"type": "string",
"description": "MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources."
},
"uri": {
"type": "string",
"description": "Resource URI to read. Must be one of the URIs returned by list_mcp_resources."
}
},
"required": [
"server",
"uri"
],
"additionalProperties": false
}
ResultSource declaration
Implementation serde envelope: camelCase list keys (nextCursor/resourceTemplates), server tagging and flattened resource records. Referenced Resource/ResourceTemplate/ReadResourceResult come from rmcp protocol types; server content remains dynamic, not exhaustively reproduced here.
Run by the model provider rather than the harness.
web_searchProvider-hosted web search.
Non-Responses-Lite provider supports hosted search; web_search_mode eligible; suppressed when standalone web.run is available.
InputSchema unavailable
ToolSpec::WebSearch config is a hosted-tool declaration, not a client function input schema; hosted model-call arguments are not established by this source.
ResultSchema unavailable
Hosted WebSearch output items/actions are service protocol; no local function-result schema.
Arbitrary host extensions, dynamic tools, MCP servers and future/closed-source tools are open-ended; universal inventory completeness is not claimed.
Hosted service internals and runtime catalog overrides are not established by source/type inspection.
FunctionCallError::RespondToModel produces a model-facing error; fatal infrastructure failures abort execution. Tool approval, hook, sandbox and cancellation outcomes are separate from a successful result; no error union is implied by an output schema.
Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.
Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler.
Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page<ThreadSummary>; search_posts -> Page<PostPreview>; read_thread -> ThreadPage; read_post -> PostContent; post -> PostMetadata; subscribe/unsubscribe -> SubscriptionState. Page serializes results,n_returned,has_more,next_cursor. AgentPath/UUID are string identities and DateTime UTC is serialized timestamp.
Arguments over 128 KiB rejected; responses bounded to 8000 bytes or caller budget. PermissionDenied produces {error:{code:"permission_denied",message,action?,resource?,truncated?}} with success=false, preserving backend denial. Notifications do not start idle agents.
Client handles encrypted output and separates image attachments. Hosted service result fields, complete error union and server enforcement are unavailable; do not invent domain result schemas.
Generated from unchanged serde/schemars source declarations with schemars 0.8.22 and the source schema_for transform (option_add_null_type=false). This is isolated contract generation, not a runtime tool probe.
Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.
Claude Code 2.1.310
56 tools.
Built in
Part of the harness. Each entry says what turns it on.
AgentDelegate work to a subagent.
CLI/SDK tool; own context and subagent allow/deny limits. Named calls can address teammates; forks and remote isolation have separate gates.
Aliases and version differences: Task (accepted compatibility alias; SDKSystemMessage init may still report Task, per publisher SDK docs)
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
description
string
Yes
A short (3-5 word) description of the task
prompt
string
Yes
The task for the agent to perform
subagent_type
string
No
The type of specialized agent to use for this task
model
"sonnet" | "opus" | "haiku" | "fable"
No
Optional model override for this agent. Takes precedence over the agent definition's model frontmatter and the configured default subagent model. If omitted, uses the agent definition's model, else the default (inherits from the parent unless a default subagent model is configured). Ignored for subagent_type: "fork" — forks always inherit the parent model.
effort
"low" | "medium" | "high" | "xhigh" | "max"
No
Reasoning effort for this agent. Set this ONLY when the user, or instructions such as CLAUDE.md or a skill, explicitly ask that this agent or delegated work run at a specific effort level, never on your own judgment; otherwise omit it and the agent runs at its usual effort. Ignored for subagent_type: "fork": a fork runs at your own effort.
run_in_background
boolean
No
Agents run in the background by default; you will be notified when one completes. Set to false only when your very next action depends on this agent's result and nothing else could usefully happen while it runs — otherwise leave it in the background so the user can hand you other work.
name
string
No
Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running.
team_name
string
No
Deprecated; ignored. The session has a single implicit team.
Deprecated; ignored. Subagents inherit the parent session's permission mode; agent-definition frontmatter may override it.
isolation
"worktree" | "remote"
No
Isolation mode. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo. "remote" launches the agent in a remote cloud environment (always runs in background; availability is gated).
Omit (or 'publish') to publish file_path. 'list' enumerates artifacts — the user's own by default, see scope; only limit and scope may accompany it. 'read' returns the content of the published artifact at url (raw HTML for the user's own; an isolated summary, steered by the optional prompt, for one someone else owns, though a page published in this session's own Slack channel can come back in full as untrusted content) — see **Calls**. 'watch', 'unwatch', and 'status' manage live-update subscriptions through which a session keeps track of new versions of an artifact published elsewhere, and those aren't available in this session: 'watch' only reports that — this session does not keep track of new versions — and 'status' lists this session's artifact watches (pass url to check one). 'upload_asset' adds one local media, PDF, font, or text file to an existing artifact — pass url and file_path (or file_paths for several in one call). 'list_assets' lists the files in an artifact's asset store (pass url; after continues a listing), 'read_asset' saves one of them to a local file named by its id (pass url and asset_id, optionally out_dir), and 'delete_asset' permanently removes one (pass url and asset_id). See **Artifact assets** above. 'pin' adds the artifact at url to the user's pinned list in their claude.ai sidebar and 'unpin' removes it (nothing else may accompany either) — private to the user, reversible, and no change to who can see the artifact.
file_path
string
No
Path to the .html file to render. Required to publish (the default action). Use a short, distinctive basename — it is the last-resort title when the HTML has no <title> and no title parameter is given. For 'upload_asset', the local image, video, PDF, font, stylesheet (CSS), script (JS), or text (CSV, Markdown, JSON, plain text) file to upload.
favicon
string
No
Deprecated; omit it. Use icon.
icon
string
No
One short generic word for the artifact's browser-tab icon, such as chart, calendar, recipe, code or map — a plain signifier, not a product or brand name. Include it on every page's first publish; omit when republishing to keep the current icon, and pass a new one only when the user asks.
limit
number
No
list only: maximum artifacts to return (default 25).
scope
"mine" | "shared" | "all"
No
list only: 'mine' (default) lists artifacts the user owns; 'shared' lists artifacts other people shared with the user; 'all' lists both. Rows are labeled (mine)/(shared) whenever scope is not 'mine'.
title
string
No
Title for the artifact — the name shown in the browser tab and gallery. A short, distinctive noun-phrase name — not a generic label, a summary, or a name with an appended explainer. Prefer a <title> tag at the top of the HTML itself; this parameter fills in only when the file lacks one in the first 8KB of the file, and never overrides the tag. HTML publishes only — Markdown pages keep their filename identity. Content always comes from file_path — there is no inline content parameter.
description
string
No
One-sentence subtitle shown on the gallery card. Say what the page is or does.
label
string
No
A short name for this publish, max 60 chars (e.g. "Draft to legal"). Optional — a few words, not a description.
url
string
No
An existing artifact's claude.ai link (claude.ai/artifact/{id} or claude.ai/code/artifact/{uuid}; a chat, project or session link is not one) to update in place. Pass whenever the user wants to update an artifact this conversation did not publish — "update my artifact", "keep the same link", a pasted artifact URL — and find the URL with action: "list" or ask the user for the link if you don't have it; without this, the publish creates a separate artifact instead of updating the existing one. Omit for new artifacts and same-conversation redeploys. Must be an artifact the user owns or was given edit access to (a read of it says "writer"). Before publishing to an artifact this conversation has neither read nor published, read it (action: "read") and build on what comes back; a publish sent without that read is refused. A refusal that hands you the live version counts as that read: merge your edits into that version and publish that; never resend the refused content unchanged. For 'read' and the other url-addressed actions: the artifact to act on.
prompt
string
No
read only: what to extract from an artifact shared with the user — its content reaches you as an isolated summary answering this. Ignored for artifacts the user owns and for a page published in this session's own Slack channel (raw content is returned); optional.
force
boolean
No
Last-resort overwrite that DISCARDS the newer published version's page — another session's publish, or someone's save from a page that can publish new versions of itself. On a conflict the fix is to merge your changes onto the newer content (handed to you in the rejection, or re-read) and publish again — not force. Pass force:true only when the user has explicitly said to discard that specific version; never to get past a conflict on your own judgment. The tracked baseVersion is still sent; with force:true the server treats it as informational and overwrites, unless it refuses force over a version saved from inside the page. Omit (or false) so a concurrent write conflicts instead of being silently clobbered.
pin
boolean
No
publish only: true also pins the published artifact to the user's claude.ai sidebar once it is published — pass it only when the user asked for that; a pin that fails never fails the publish (the result says so).
out_dir
string
No
read_asset: directory to save into — default: this artifact’s folder in your scratchpad directory, where saving needs no approval and which you can Read from. read_asset names the file by the asset id plus the extension for its type; saving to any directory other than the default is an ordinary file save the user may be asked to approve.
file_paths
[
string,
...string[]
]
No
upload_asset: several local image, video, PDF, font, stylesheet or script files in place of file_path, up to 25 in one call, all into the artifact that url names; one approval covers the call, and the result lists each file's id and url, or why it was not uploaded. A CSV, Markdown, JSON or plain-text file, a symbolic or hard link, and a file outside the working directory each go in a call of their own with file_path.
asset_id
string
No
read_asset and delete_asset: the asset's id (32 hex characters), from a list_assets or upload_asset result.
after
string
No
list_assets only: the next value from a previous list_assets result, to continue that listing.
capabilities
{
[k: string]: unknown;
}
No
Runtime capabilities this page declares, as {name: config}. The control plane is the authority on valid names and config shapes. An empty object clears any previously stored declaration; omit the field on a redeploy to carry the stored declaration forward unchanged. Before declaring any capability, load the artifact-capabilities skill for the current contract and per-capability guidance.
contract
"latest" | string
No
The artifact's runtime version. Omit to keep its current version (the default); 'latest' to upgrade; a specific version to pin or roll back. Changing it changes how the published page behaves — pass only when the author explicitly intends the change, never as a side effect of editing.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
command
string
Yes
The command to execute
timeout
number
No
Optional timeout in milliseconds (max 600000 for a foreground command)
description
string
No
Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.
Say what the command does in plain words: do not echo the command's text, its flags, or file paths - the user reads this description, often without seeing the command.
For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):
- ls → "List files in current directory"
- git status → "Show working tree status"
- npm install → "Install package dependencies"
For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:
- find . -name "*.tmp" -exec rm {} \; → "Find and delete all .tmp files recursively"
- git reset --hard origin/main → "Discard all local changes and match remote main"
- curl -s url | jq '.data[]' → "Fetch JSON from URL and extract data array elements"
run_in_background
boolean
No
Set to true to run this command in the background. With it, timeout limits how long the command may run in the background before it is stopped (default 1800000 ms, max 7200000 ms).
dangerouslyDisableSandbox
boolean
No
Set this to true to dangerously override sandbox mode and run commands without sandboxing.
Path to raw output file for large MCP tool outputs
interrupted
boolean
Yes
Whether the command was interrupted
isImage
boolean
No
Flag to indicate if stdout contains image data
backgroundTaskId
string
No
ID of the background task if command is running in background
backgroundedByUser
boolean
No
True if the user manually backgrounded the command with Ctrl+B
timedOutAfterMs
number
No
Set when the command hit its timeout and was auto-backgrounded; the timeout value in ms
backgroundCwdHint
string
No
Model-facing note that the session cwd was not changed by a backgrounded command containing a directory-change builtin (cd/pushd/popd/chdir)
backgroundEndsWithFinalResponse
true
No
True when this backgrounded command is terminated at its caller's final response, so no completion notification can follow (a synchronous subagent's command, or a headless session that takes no further input and is not waiting for background commands); absent when the command survives
dangerouslyDisableSandbox
boolean
No
Flag to indicate if sandbox mode was overridden
returnCodeInterpretation
string
No
Semantic interpretation for non-error exit codes with special meaning
noOutputExpected
boolean
No
Whether the command is expected to produce no output on success
structuredContent
unknown[]
No
Structured content blocks
persistedOutputPath
string
No
Path to the persisted full output in tool-results dir (set when output is too large for inline)
persistedOutputSize
number
No
Total size of the output in bytes (set when output is too large for inline)
staleReadFileStateHint
string
No
Model-facing note listing readFileState entries whose mtime bumped during this command (set when WRITE_COMMAND_MARKERS matches)
ghRateLimitHint
string
No
Model-facing system-reminder appended when a gh command reports a GitHub API rate-limit error
Structured classification of git/gh operations detected in this command (commit/push/merge/rebase/PR). Client-facing — lets clients render git activity without re-parsing stdout; not surfaced to the model.
SDK success output includes stdout, stderr and interrupted plus optional backgroundTaskId/outputFile and other declared fields. Backgrounding/completion, timeout and cancellation are lifecycle states, not a single exit-code result. SDK foreground timeout comment is 600000 ms; current docs also describe configurable ceilings and unattended background limits, so preserve this version/source boundary.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
cron
string
Yes
Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "* /5 * * * *" = every 5 minutes, "30 14 28 2 *" = Feb 28 at 2:30pm local once).
prompt
string
Yes
The prompt to enqueue at each fire time.
recurring
boolean
No
true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month.
durable
boolean
No
true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
name
string
No
Optional name for a new worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided. Mutually exclusive with path.
path
string
No
Path to an existing worktree to switch into instead of creating a new one. Must appear in git worktree list for the current repo — or, on first entry from the launch directory, for a repo nested inside it (multi-repo workspace). Mutually exclusive with name.
Absent by default on macOS/Linux/WSL in current docs; may be restored with tool configuration. SDK types do not imply default exposure.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
pattern
string
Yes
The glob pattern to match files against
path
string
No
The directory to search in. If not specified, the current working directory will be used. IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.
Number of file paths returned (after any truncation)
filenames
string[]
Yes
Array of file paths that match the pattern
truncated
boolean
Yes
Whether results were truncated (limited to 100 files)
totalMatches
number
No
Total number of matching files before truncation. A lower bound when countIsComplete is false. Absent on results persisted by CLI versions predating this field.
countIsComplete
boolean
No
Whether totalMatches is the exact total (true) or a floor because the underlying search truncated its own output (false). Absent on results persisted by CLI versions predating this field.
Absent by default on macOS/Linux/WSL in current docs; may be restored with tool configuration. SDK types do not imply default exposure.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
pattern
string
Yes
The regular expression pattern to search for in file contents
path
string
No
File or directory to search in (rg PATH). Defaults to current working directory.
glob
string
No
Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}") - maps to rg --glob
output_mode
"content" | "files_with_matches" | "count"
No
Output mode: "content" shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), "files_with_matches" shows file paths (supports head_limit), "count" shows match counts (supports head_limit). Defaults to "files_with_matches".
-B
number
No
Number of lines to show before each match (rg -B). Requires output_mode: "content", ignored otherwise.
-A
number
No
Number of lines to show after each match (rg -A). Requires output_mode: "content", ignored otherwise.
-C
number
No
Alias for context.
context
number
No
Number of lines to show before and after each match (rg -C). Requires output_mode: "content", ignored otherwise.
-n
boolean
No
Show line numbers in output (rg -n). Requires output_mode: "content", ignored otherwise. Defaults to true.
-i
boolean
No
Case insensitive search (rg -i)
-o
boolean
No
Print only the matched (non-empty) parts of each matching line, one match per output line (rg -o / --only-matching). Requires output_mode: "content", ignored otherwise. Defaults to false.
type
string
No
File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types.
head_limit
number
No
Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 250 when unspecified. Pass 0 for unlimited (use sparingly — large result sets waste context).
offset
number
No
Skip first N lines/entries before applying head_limit, equivalent to "| tail -n +N | head -N". Works across all output modes. Defaults to 0.
multiline
boolean
No
Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
description
string
Yes
Short human-readable description of what you are monitoring (shown in notifications).
timeout_ms
number
Yes
Kill the monitor after this deadline. Default 300000ms. Deadlines above 1800000ms are capped to 1800000ms. You are notified at expiry and can re-arm.
command
string
No
Shell command or script. Each stdout line is an event; exit ends the watch.
ws
{
url: string;
protocols?: string[];
}
No
WebSocket to open. Each text frame is an event; binary frames are reported as a placeholder line. Socket close ends the watch. Cannot be combined with command.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
notebook_path
string
Yes
The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)
cell_id
string
No
The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified.
new_source
string
Yes
The new source for the cell
cell_type
"code" | "markdown"
No
The type of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required.
edit_mode
"replace" | "insert" | "delete"
No
The type of edit to make (replace, insert, delete). Defaults to replace.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
Aliases and version differences: FileRead (SDK type prefix, not a callable alias)
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
file_path
string
Yes
The absolute path to the file to read
offset
number
No
The line number to start reading from. Only provide if the file is too large to read at once
limit
number
No
The number of lines to read. Only provide if the file is too large to read at once.
pages
string
No
Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum 20 pages per request.
allow_large
boolean
No
Set to true to read a text file, or a line range of one, that is over the usual size limits, up to what still fits in your context. Only use this when you genuinely need all of it or the user asked for the whole file; otherwise read it in parts with offset and limit, or search it.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
delaySeconds
number
No
Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless stop is true.
reason
string
No
One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific. Required unless stop is true.
prompt
string
No
The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing re-enters the skill and continues the loop. For autonomous /loop (no user prompt), pass the literal sentinel <<autonomous-loop-dynamic>> instead (the dynamic-pacing variant, not the CronCreate-mode <<autonomous-loop>>). Required unless stop is true.
stop
boolean
No
Set to true to end the dynamic loop immediately instead of scheduling another wakeup. When true, all other fields are ignored and no further wakeups fire.
noop
boolean
No
true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless stop is true.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
type
"bug" | "idea" | "missing_capability"
Yes
What kind of feedback this is.
title
string
Yes
Short, specific one-line summary of the issue.
details
string
Yes
Labeled bullets, in order: **What happened:** (observed vs. expected, exact error text if short); **What the user said:** (quoted, or "User didn't comment; observed by the model."); **Repro:** (minimal steps); **Evidence:** (request IDs, timestamps, paths, versions; omit if none); optionally a final **Cause:** only if verified in-session. One to three lines per bullet. No narrative paragraphs, no speculation, no secrets.
area
string
No
Optional short tag naming the part of Claude Code this is about (e.g. "hooks config", "/help", "file editing"). Leave blank if unclear.
When the report is about MODEL BEHAVIOR (not a product bug), the closest failure mode, or other when it is a model-behavior issue that fits no listed value. Omit only when the report is a product/tool bug with no model-behavior component.
What kind of task the session was doing when the issue occurred, or other when it is a clear task that fits no listed value. Omit only if genuinely unclear.
SDK marks both task_id and deprecated shell_id optional. Do not strengthen this into a schema-level required task_id; runtime resolves the identifier and can report no matching task. Successful output requires message, task_id, task_type; command is optional.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
url
string
Yes
The URL to fetch content from
prompt
string
Yes
The prompt to run on the fetched content
offset
number
No
Character position in the page text to start reading from. Use it to read on through a page too long for one call, with the value the previous result gave.
Built in. The model, platform, mode, tool settings and permission rules can still remove it.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
script
string
No
Self-contained workflow script. Must begin with export const meta = { name, description, phases } (pure literal, no computed values) followed by the script body using agent()/parallel()/pipeline()/phase().
name
string
No
Name of a predefined workflow (built-in or from .claude/workflows/). Resolves to a self-contained script.
description
string
No
Ignored — set the workflow description in the script's meta block.
title
string
No
Ignored — set the workflow title in the script's meta block.
args
{
[k: string]: unknown;
}
No
Optional input value exposed to the script as the global args, verbatim. Pass arrays/objects as actual JSON values, NOT as a JSON-encoded string — a stringified list breaks args.filter/args.map in the script. Use for parameterized named workflows (e.g. a research question).
scriptPath
string
No
Path to a workflow script file on disk. Every Workflow invocation persists its script under the session directory and returns the path in the tool result. To iterate, edit that file with Write/Edit and re-invoke Workflow with the same scriptPath instead of re-sending the full script. Takes precedence over script and name.
resumeFromRunId
string
No
Run ID of a prior Workflow invocation to resume from. Completed agent() calls with unchanged (prompt, opts) return their cached results instantly; only edited or new calls re-run. Same-session only. Stop the prior run first (TaskStop) before resuming.
TaskType of the registered background task — 'local_workflow' for in-process runs, 'remote_agent' when remote:true dispatches to CCR. Set on all new writes; absent only on transcripts written before this field existed.
workflowName
string
No
meta.name from the workflow script — same value as task_started.workflow_name. Set on all new writes; absent only on transcripts written before this field existed.
runId
string
No
Local workflow run identifier for resumeFromRunId. Absent for remote_launched (the CCR session URL is the resume handle there) and on transcripts written before this field existed.
summary
string
No
transcriptDir
string
No
Directory where subagent transcripts are written during execution
scriptPath
string
No
Path to the persisted workflow script for this invocation. Editable via Write/Edit; pass back as scriptPath to re-run without resending the script.
sessionUrl
string
No
CCR session URL when status is remote_launched
warning
string
No
Non-blocking heads-up (e.g. local git state diverges from the pushed branch the cloud session will clone)
Diff patch showing the changes (empty when nothing changed, the diff timed out, or — with originalFile null on an update — the previous content was too large to diff)
originalFile
string | null
Yes
The original file content before the write (null for new files, or when the previous content was too large to include)
project_read/project_write/project_delete: doc path. project_write: an existing path is replaced in place; a new bare filename (no "/") is namespaced to "claude/<name>". project_memory_read: memory file path as listed by project_memory_list.
content
string
No
project_write: inline doc text. Mutually exclusive with local_path. Use local_path for anything you have on disk.
local_path
string
No
project_write: a file inside the working directory to upload. The tool reads, encodes, and uploads directly — contents never enter your context. Mutually exclusive with content.
present_to_user
boolean
No
project_write: true marks this doc as the file the user needs to see — the deliverable they asked for or must act on. Defaults to false; leave it unset for routine saves, notes, and bulk writes.
ProposeGoalPublisher SDK contract for ProposeGoal.
Publisher SDK type only; concrete CLI/host registration and gates not established.
InputPublished TypeScript
Field
Type
Required
Meaning and defaults
condition
string
Yes
The completion condition to propose, written so a separate evaluator can verify it from the conversation (e.g. "all tests in test/auth pass (bun test exits 0)"). At most 500 characters — the user must be able to read the whole condition in the approval dialog.
ask_user
boolean
No
Whether to ask the user for approval before the goal is set. Defaults to true — an approval dialog is shown. Set false ONLY when the user's own words in this conversation stated this outcome as what they want; the goal is then set directly, with a visible notice in the transcript, and the user can clear it with /goal clear.
Checked 2026-10-27 against source revision @anthropic-ai/claude-agent-sdk@0.3.310. Inputs: 43 Published TypeScript; 13 Schema unavailable. Results: 43 Published TypeScript; 13 Schema unavailable.
No model-driven runtime probe was run.
Arbitrary host extensions, dynamic tools, MCP servers and future/closed-source tools are open-ended; universal inventory completeness is not claimed.
Hosted service internals and runtime catalog overrides are not established by source/type inspection.
Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types.
CLI tool_use input and tool_result content are separate from SDK structured results. Permission/hook denial may prevent execution; is_error/content does not imply the success type.
No model execution or destructive tool probe was run. Closed-source CLI internals and hosted implementation are unavailable.
The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema.
No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema.