{ "schemaVersion": 1, "updatedAt": "2026-10-27", "dimensions": ["inventory", "inputs", "results"], "contracts": [ { "harness": "codex", "variant": "0.164.0-tool-reference", "default": true, "verifiedAt": "2026-10-27", "observedVersion": "0.164.0", "method": "source-inspection", "sourceRevision": "6aaac694803004a63c6f393d153c96d22521a6b9", "surface": "cli-app-server-source", "evidence": ["builtin-tools-codex-0164-router", "builtin-tools-codex-0164-hosts"], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/app-server/src/extensions.rs" ], "conditions": [ "Inventory is the union of the pinned source definitions and contributions, or dated publisher tool list and versioned SDK types. It is not the active tool set for every session.", "Formal output schemas describe success values where supplied; errors, approval, denial, cancellation and transport envelopes remain separate.", "Core registration is suppressed if tool policy requires a managed sandbox and the thread or any selected execution environment is not managed. All entries remain subject to tool-policy filtering and effective model/tool-mode exposure." ], "unknowns": [ "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." ], "details": { "baseline": { "releaseTag": "rust-v0.164.0", "commit": "6aaac694803004a63c6f393d153c96d22521a6b9", "annotatedTag": "fe3b29455488c2e189e43ad5526a107900c5e1b7" }, "scope": "Complete accounting of the enumerated pinned-source or publisher-list/SDK union; unresolved contracts remain explicit.", "excluded": [ "Server-defined MCP tools (tools/list supplies their actual inputSchema/outputSchema).", "Desktop/browser/computer-use/plugin tools supplied by a separate host.", "App Server FileChange, CommandExecution and other protocol items; not function tool names.", "Observed weekly corpus payloads; no private transcript data imported." ] }, "jobNotes": { "read": "No text-file reader: text files are read with `exec_command`. `view_image` covers images.", "search": "No file or code search tool: searches run through `exec_command`." }, "support": { "inventory": "partial", "inputs": "partial", "results": "partial" }, "inventory": [ { "name": "apply_patch", "category": "core", "purpose": "Apply a file patch.", "availability": "Model apply_patch_tool_type must be present; multi-environment variant adds an optional Environment ID header. Sandbox and patch approval apply.", "aliases": [], "jobs": ["edit"], "input": { "kind": "grammar", "definition": "start: begin_patch hunk+ end_patch\nbegin_patch: \"*** Begin Patch\" LF\nend_patch: \"*** End Patch\" LF?\n\nhunk: add_hunk | delete_hunk | update_hunk\nadd_hunk: \"*** Add File: \" filename LF add_line+\ndelete_hunk: \"*** Delete File: \" filename LF\nupdate_hunk: \"*** Update File: \" filename LF change_move? change?\n\nfilename: /(.+)/\nadd_line: \"+\" /(.*)/ LF -> line\n\nchange_move: \"*** Move to: \" filename LF\nchange: (change_context | change_line)+ eof_line?\nchange_context: (\"@@\" | \"@@ \" /(.+)/) LF\nchange_line: (\"+\" | \"-\" | \" \") /(.*)/ LF\neof_line: \"*** End of File\" LF\n\n%import common.LF\n", "fields": [], "notes": "Lark grammar, not JSON. Multi-environment schema inserts environment_id after begin_patch; see constructor." }, "output": { "kind": "free-form", "definition": "Patch application summary or model-facing error text.", "fields": [], "notes": "FileChange protocol events are distinct from the function/custom tool result." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/assets/tools/apply_patch.lark", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/apply_patch_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/apply_patch.rs" ] }, { "name": "clock.curr_time", "category": "core", "purpose": "Return the current time in UTC.", "availability": "CurrentTimeReminder feature or model advertises clock.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}", "fields": [], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"current_time\": {\n \"description\": \"Current UTC time formatted as YYYY-MM-DD HH:MM:SS UTC.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"current_time\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "current_time", "type": "\"string\"", "required": true, "notes": "Current UTC time formatted as YYYY-MM-DD HH:MM:SS UTC." } ], "notes": "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.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/current_time.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "clock.sleep", "category": "core", "purpose": "Pause execution for a specified duration.", "availability": "SleepTool plus sleep_tool_mode: always_on, or model-driven clock/current-time reminder eligibility. Direct-model-only.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"duration_ms\": {\n \"type\": \"number\",\n \"description\": \"How long to sleep in milliseconds. Must be between 1 and 43200000.\"\n }\n },\n \"required\": [\n \"duration_ms\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "duration_ms", "type": "\"number\"", "required": true, "notes": "How long to sleep in milliseconds. Must be between 1 and 43200000." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "free-form", "definition": "elapsed wall-clock time", "fields": [], "notes": "Source emits a text result and sleep lifecycle item; new user input can end sleep early. No JSON output schema." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/sleep.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "codex_tui.create_thread", "category": "host", "purpose": "Create and start a task.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"model\": {\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Maximum 1,000 UTF-8 bytes.\",\n \"maxLength\": 1000,\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"title\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"prompt\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "model", "type": "\"string\"", "required": false, "notes": "" }, { "name": "prompt", "type": "\"string\"", "required": true, "notes": "Maximum 1,000 UTF-8 bytes." }, { "name": "title", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "model": { "minLength": 1, "type": "string" }, "prompt": { "description": "Maximum 1,000 UTF-8 bytes.", "maxLength": 1000, "minLength": 1, "type": "string" }, "title": { "minLength": 1, "type": "string" } }, "required": ["prompt"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.fork_thread", "category": "host", "purpose": "Fork a task.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", "fields": [ { "name": "threadId", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "threadId": { "minLength": 1, "type": "string" } }, "required": [], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.list_archived_threads", "category": "host", "purpose": "List archived tasks.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"maximum\": 50,\n \"minimum\": 1,\n \"type\": \"integer\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "cursor": { "type": "string" }, "limit": { "maximum": 50, "minimum": 1, "type": "integer" } }, "required": [], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.list_threads", "category": "host", "purpose": "List active tasks.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"limit\": {\n \"maximum\": 50,\n \"minimum\": 1,\n \"type\": \"integer\"\n }\n },\n \"required\": [],\n \"type\": \"object\"\n}", "fields": [ { "name": "limit", "type": "\"integer\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "limit": { "maximum": 50, "minimum": 1, "type": "integer" } }, "required": [], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.read_thread", "category": "host", "purpose": "Read a task page.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"includeOutputs\": {\n \"type\": \"boolean\"\n },\n \"maxOutputCharsPerItem\": {\n \"maximum\": 20000,\n \"minimum\": 0,\n \"type\": \"integer\"\n },\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"turnLimit\": {\n \"maximum\": 10,\n \"minimum\": 1,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"threadId\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" }, { "name": "includeOutputs", "type": "\"boolean\"", "required": false, "notes": "" }, { "name": "maxOutputCharsPerItem", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "threadId", "type": "\"string\"", "required": true, "notes": "" }, { "name": "turnLimit", "type": "\"integer\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "cursor": { "type": "string" }, "includeOutputs": { "type": "boolean" }, "maxOutputCharsPerItem": { "maximum": 20000, "minimum": 0, "type": "integer" }, "threadId": { "minLength": 1, "type": "string" }, "turnLimit": { "maximum": 10, "minimum": 1, "type": "integer" } }, "required": ["threadId"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.send_message_to_thread", "category": "host", "purpose": "Send a prompt to a task.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"model\": {\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"prompt\": {\n \"description\": \"Maximum 1,000 UTF-8 bytes.\",\n \"maxLength\": 1000,\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"threadId\",\n \"prompt\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "model", "type": "\"string\"", "required": false, "notes": "" }, { "name": "prompt", "type": "\"string\"", "required": true, "notes": "Maximum 1,000 UTF-8 bytes." }, { "name": "threadId", "type": "\"string\"", "required": true, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "model": { "minLength": 1, "type": "string" }, "prompt": { "description": "Maximum 1,000 UTF-8 bytes.", "maxLength": 1000, "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } }, "required": ["threadId", "prompt"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.set_thread_archived", "category": "host", "purpose": "Archive or restore a task.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"archived\": {\n \"type\": \"boolean\"\n },\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"archived\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "archived", "type": "\"boolean\"", "required": true, "notes": "" }, { "name": "threadId", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "archived": { "type": "boolean" }, "threadId": { "minLength": 1, "type": "string" } }, "required": ["archived"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.set_thread_title", "category": "host", "purpose": "Rename a task.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n },\n \"title\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"title\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "threadId", "type": "\"string\"", "required": false, "notes": "" }, { "name": "title", "type": "\"string\"", "required": true, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "threadId": { "minLength": 1, "type": "string" }, "title": { "minLength": 1, "type": "string" } }, "required": ["title"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "codex_tui.wait_threads", "category": "host", "purpose": "Wait for task progress.", "availability": "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.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"targets\": {\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"afterCursor\": {\n \"type\": \"string\"\n },\n \"threadId\": {\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"threadId\"\n ],\n \"type\": \"object\"\n },\n \"maxItems\": 8,\n \"minItems\": 1,\n \"type\": \"array\"\n },\n \"timeoutMs\": {\n \"maximum\": 120000,\n \"minimum\": 0,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"targets\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "targets", "type": "\"array\"", "required": true, "notes": "" }, { "name": "timeoutMs", "type": "\"integer\"", "required": false, "notes": "" } ], "notes": "Exact TUI tool_specs builder properties/required/bounds, evaluated in isolation. Host handler uses camelCase keys. ListArguments accepts cursor internally, but list_threads advertises limit only.", "schema": { "additionalProperties": false, "properties": { "targets": { "items": { "additionalProperties": false, "properties": { "afterCursor": { "type": "string" }, "threadId": { "minLength": 1, "type": "string" } }, "required": ["threadId"], "type": "object" }, "maxItems": 8, "minItems": 1, "type": "array" }, "timeoutMs": { "maximum": 120000, "minimum": 0, "type": "integer" } }, "required": ["targets"], "type": "object" } }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Host returns per-operation JSON/content and success flags. Formal exhaustive result schema unavailable; see dynamic tool handler." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tui/src/dynamic_tools.rs" ] }, { "name": "collaboration.create_channel", "category": "extension", "purpose": "Create a channel where all agents in this collaboration can read and post messages.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"description\": {\n \"type\": \"string\",\n \"description\": \"Optional channel purpose, at most 512 UTF-8 bytes.\"\n },\n \"subscribe\": {\n \"type\": \"boolean\",\n \"description\": \"Subscribe to new top-level posts. Default true.\"\n }\n },\n \"required\": [\n \"channel_name\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "channel_name", "type": "\"string\"", "required": true, "notes": "" }, { "name": "description", "type": "\"string\"", "required": false, "notes": "Optional channel purpose, at most 512 UTF-8 bytes." }, { "name": "subscribe", "type": "\"boolean\"", "required": false, "notes": "Subscribe to new top-level posts. Default true." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "channel_name": { "type": "string" }, "description": { "type": "string", "description": "Optional channel purpose, at most 512 UTF-8 bytes." }, "subscribe": { "type": "boolean", "description": "Subscribe to new top-level posts. Default true." } }, "required": ["channel_name"], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.get_channels", "category": "extension", "purpose": "List channels, most recently active first, or search by a case-insensitive part of the name.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh.\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum results, default 20; output budgets may return fewer. Continue with next_cursor.\"\n },\n \"query\": {\n \"type\": \"string\"\n },\n \"recent_first\": {\n \"type\": \"boolean\",\n \"description\": \"Newest first by default.\"\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, { "name": "query", "type": "\"string\"", "required": false, "notes": "" }, { "name": "recent_first", "type": "\"boolean\"", "required": false, "notes": "Newest first by default." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, "limit": { "type": "integer", "description": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, "query": { "type": "string" }, "recent_first": { "type": "boolean", "description": "Newest first by default." } }, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.list_threads", "category": "extension", "purpose": "List a channel's threads with previews of the first post and latest reply.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh.\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum results, default 20; output budgets may return fewer. Continue with next_cursor.\"\n },\n \"max_chars_per_post\": {\n \"type\": \"integer\",\n \"description\": \"Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000.\"\n },\n \"recent_first\": {\n \"type\": \"boolean\",\n \"description\": \"Newest first by default.\"\n },\n \"sort\": {\n \"type\": \"string\",\n \"enum\": [\n \"created\",\n \"activity\"\n ]\n }\n },\n \"required\": [\n \"channel_name\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "channel_name", "type": "\"string\"", "required": true, "notes": "" }, { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, { "name": "max_chars_per_post", "type": "\"integer\"", "required": false, "notes": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, { "name": "recent_first", "type": "\"boolean\"", "required": false, "notes": "Newest first by default." }, { "name": "sort", "type": "[\"created\", \"activity\"]", "required": false, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "channel_name": { "type": "string" }, "cursor": { "type": "string", "description": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, "limit": { "type": "integer", "description": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, "max_chars_per_post": { "type": "integer", "description": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, "recent_first": { "type": "boolean", "description": "Newest first by default." }, "sort": { "type": "string", "enum": ["created", "activity"] } }, "required": ["channel_name"], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.post", "category": "extension", "purpose": "Start a thread in an existing or new channel, or reply using the first post's message ID as thread_id.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agents_to_notify\": {\n \"type\": \"array\",\n \"description\": \"Absolute agent paths or references relative to you; maximum 256.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"new_channel_name\": {\n \"type\": \"string\",\n \"description\": \"Create and subscribe to this channel.\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"thread_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "agents_to_notify", "type": "\"array\"", "required": false, "notes": "Absolute agent paths or references relative to you; maximum 256." }, { "name": "channel_name", "type": "\"string\"", "required": false, "notes": "" }, { "name": "new_channel_name", "type": "\"string\"", "required": false, "notes": "Create and subscribe to this channel." }, { "name": "text", "type": "\"string\"", "required": true, "notes": "" }, { "name": "thread_id", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "agents_to_notify": { "type": "array", "description": "Absolute agent paths or references relative to you; maximum 256.", "items": { "type": "string" } }, "channel_name": { "type": "string" }, "new_channel_name": { "type": "string", "description": "Create and subscribe to this channel." }, "text": { "type": "string" }, "thread_id": { "type": "string" } }, "required": ["text"], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.read_post", "category": "extension", "purpose": "Read a post or reply by message ID, without needing its channel.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"limit_chars\": {\n \"type\": \"integer\",\n \"description\": \"Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000.\"\n },\n \"message_id\": {\n \"type\": \"string\"\n },\n \"offset_chars\": {\n \"type\": \"integer\",\n \"description\": \"Default 0.\"\n }\n },\n \"required\": [\n \"message_id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "limit_chars", "type": "\"integer\"", "required": false, "notes": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, { "name": "message_id", "type": "\"string\"", "required": true, "notes": "" }, { "name": "offset_chars", "type": "\"integer\"", "required": false, "notes": "Default 0." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "limit_chars": { "type": "integer", "description": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, "message_id": { "type": "string" }, "offset_chars": { "type": "integer", "description": "Default 0." } }, "required": ["message_id"], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.read_thread", "category": "extension", "purpose": "Read a thread using its first post's message ID.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh.\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum results, default 20; output budgets may return fewer. Continue with next_cursor.\"\n },\n \"max_chars_per_post\": {\n \"type\": \"integer\",\n \"description\": \"Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000.\"\n },\n \"thread_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"thread_id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, { "name": "max_chars_per_post", "type": "\"integer\"", "required": false, "notes": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, { "name": "thread_id", "type": "\"string\"", "required": true, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, "limit": { "type": "integer", "description": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, "max_chars_per_post": { "type": "integer", "description": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, "thread_id": { "type": "string" } }, "required": ["thread_id"], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.search_posts", "category": "extension", "purpose": "Search top-level posts and replies, newest first.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"after_message_id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": \"string\",\n \"description\": \"An absolute agent path or a reference relative to you.\"\n },\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh.\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum results, default 20; output budgets may return fewer. Continue with next_cursor.\"\n },\n \"max_chars_per_post\": {\n \"type\": \"integer\",\n \"description\": \"Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000.\"\n },\n \"query\": {\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [ { "name": "after_message_id", "type": "\"string\"", "required": false, "notes": "" }, { "name": "author", "type": "\"string\"", "required": false, "notes": "An absolute agent path or a reference relative to you." }, { "name": "channel_name", "type": "\"string\"", "required": false, "notes": "" }, { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, { "name": "max_chars_per_post", "type": "\"integer\"", "required": false, "notes": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, { "name": "query", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "after_message_id": { "type": "string" }, "author": { "type": "string", "description": "An absolute agent path or a reference relative to you." }, "channel_name": { "type": "string" }, "cursor": { "type": "string", "description": "Opaque next_cursor from the same query. Keep filters and sorting unchanged. Concurrent posts may shift pages; omit the cursor to refresh." }, "limit": { "type": "integer", "description": "Maximum results, default 20; output budgets may return fewer. Continue with next_cursor." }, "max_chars_per_post": { "type": "integer", "description": "Maximum characters; further capped by output budget. Defaults: limit_chars 20000, max_chars_per_post 1000." }, "query": { "type": "string" } }, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.subscribe", "category": "extension", "purpose": "Subscribe yourself or another agent to a channel for new top-level posts, or to a thread for replies.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"target_agent\": {\n \"type\": \"string\",\n \"description\": \"An absolute agent path or a reference relative to you.\"\n },\n \"thread_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [ { "name": "channel_name", "type": "\"string\"", "required": false, "notes": "" }, { "name": "target_agent", "type": "\"string\"", "required": false, "notes": "An absolute agent path or a reference relative to you." }, { "name": "thread_id", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "channel_name": { "type": "string" }, "target_agent": { "type": "string", "description": "An absolute agent path or a reference relative to you." }, "thread_id": { "type": "string" } }, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "collaboration.unsubscribe", "category": "extension", "purpose": "Unsubscribe yourself or another agent from a channel or thread.", "availability": "Message-board extension installed; AgentMessageBoard + MultiAgentV2 and eligible storage, or explicit host connection. Host chooses namespace (collaboration shown here). Local SQLite, in-memory and remote backends share these contracts.", "aliases": [], "jobs": ["channels"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"channel_name\": {\n \"type\": \"string\"\n },\n \"target_agent\": {\n \"type\": \"string\",\n \"description\": \"An absolute agent path or a reference relative to you.\"\n },\n \"thread_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [ { "name": "channel_name", "type": "\"string\"", "required": false, "notes": "" }, { "name": "target_agent", "type": "\"string\"", "required": false, "notes": "An absolute agent path or a reference relative to you." }, { "name": "thread_id", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "channel_name": { "type": "string" }, "target_agent": { "type": "string", "description": "An absolute agent path or a reference relative to you." }, "thread_id": { "type": "string" } }, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostMetadata {\n pub message_id: Uuid,\n pub channel_name: String,\n pub author: AgentPath,\n pub thread_id: Uuid,\n pub created_at: DateTime,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostPreview {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text_preview: String,\n pub n_chars: usize,\n pub truncated: bool,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct PostContent {\n #[serde(flatten)]\n pub metadata: PostMetadata,\n pub text: String,\n pub n_chars: usize,\n pub next_offset_chars: usize,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadSummary {\n pub thread_id: Uuid,\n pub root_post: PostPreview,\n pub reply_count: usize,\n pub last_activity_at: DateTime,\n pub latest_reply: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelSummary {\n /// Absent on boards without ACL metadata; preserve the legacy wire shape.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub permissions: Option,\n pub channel_name: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub description: Option,\n pub created_at: DateTime,\n pub created_by: AgentPath,\n pub message_count: usize,\n pub last_message_id: Option,\n}\n\n/// Channel discovery also exposes board actions, including when there are no channels.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPage {\n #[serde(flatten)]\n pub channels: Page,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub board_permissions: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct SubscriptionState {\n pub channel_name: String,\n pub thread_id: Option,\n pub target_agent: AgentPath,\n pub enabled: bool,\n pub last_message_id: Option,\n}\n\n/// A bounded page. Counts and end-of-list markers are derived at serialization.\n#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]\npub struct Page {\n pub results: Vec,\n pub next_cursor: Option,\n}\n\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ThreadPage {\n pub root_post: PostPreview,\n #[serde(flatten)]\n pub replies: Page,\n}\n\n/// Effective board actions for the authenticated caller, not an ACL definition.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct BoardPermissions {\n pub create_channel: bool,\n pub edit_metadata: bool,\n pub manage_permissions: bool,\n}\n\n/// Effective channel actions; replying does not imply permission to start a thread.\n#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelPermissions {\n pub read: bool,\n pub post: bool,\n pub reply: bool,\n pub edit_metadata: bool,\n}\n\n/// A backend denial retained through the board's existing error interface.\n#[derive(Clone, Debug, Serialize)]\n#[serde(tag = \"code\", rename = \"permission_denied\")]\npub struct PermissionDenied {\n pub message: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub action: Option,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub resource: Option,\n}", "fields": [], "notes": "Implementation serde types. create_channel -> ChannelSummary; get_channels -> ChannelPage; list_threads -> Page; search_posts -> Page; 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." }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/types.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/message-board/src/tools.rs" ] }, { "name": "create_goal", "category": "extension", "purpose": "Create a persisted thread goal.", "availability": "App Server goal extension installed with state DB; Goals feature enabled. Mutations validate current goal state and token budget.", "aliases": [], "jobs": ["goals"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"objective\": {\n \"type\": \"string\",\n \"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.\"\n },\n \"token_budget\": {\n \"type\": \"integer\",\n \"description\": \"Positive token budget for the new goal. Omit unless explicitly requested.\"\n }\n },\n \"required\": [\n \"objective\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "objective", "type": "\"string\"", "required": true, "notes": "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." }, { "name": "token_budget", "type": "\"integer\"", "required": false, "notes": "Positive token budget for the new goal. Omit unless explicitly requested." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, PartialEq, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct GoalToolResponse {\n goal: Option,\n remaining_tokens: Option,\n completion_budget_report: Option,\n}\n\n#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub enum ThreadGoalStatus {\n Active,\n Paused,\n Blocked,\n UsageLimited,\n BudgetLimited,\n Complete,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub struct ThreadGoal {\n pub thread_id: ThreadId,\n pub objective: String,\n pub status: ThreadGoalStatus,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n #[ts(optional)]\n pub token_budget: Option,\n pub tokens_used: i64,\n pub time_used_seconds: i64,\n pub created_at: i64,\n pub updated_at: i64,\n}", "fields": [], "notes": "Serialized implementation response, not an advertised output schema. goal can be null; optional budget report depends on operation." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/tool.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs" ] }, { "name": "exec", "category": "core", "purpose": "Run JavaScript that composes available tools.", "availability": "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.", "aliases": [], "jobs": ["compose"], "input": { "kind": "grammar", "definition": "\nstart: pragma_source | plain_source\npragma_source: PRAGMA_LINE NEWLINE SOURCE\nplain_source: SOURCE\n\nPRAGMA_LINE: /[ \\t]*\\/\\/ @exec:[^\\r\\n]*/\nNEWLINE: /\\r?\\n/\nSOURCE: /[\\s\\S]+/\n", "fields": [], "notes": "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." }, "output": { "kind": "free-form", "definition": "Text/image/audio/tool content; a yielded cell reports a cell_id for wait.", "fields": [], "notes": "Code-mode output differs from the raw model-visible output of a nested tool. Source output adapter handles content and completion." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/code_mode/execute_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/code_mode/output.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "exec_command", "category": "core", "purpose": "Runs a command in a PTY, returning output or a session ID for ongoing interaction.", "availability": "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.", "aliases": [], "jobs": ["shell", "processes"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"additional_permissions\": {\n \"type\": \"object\",\n \"description\": \"Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \\\"with_additional_permissions\\\"`.\",\n \"properties\": {\n \"file_system\": {\n \"type\": \"object\",\n \"description\": \"Filesystem access request.\",\n \"properties\": {\n \"read\": {\n \"type\": \"array\",\n \"description\": \"Absolute paths to grant read access; omit when none are needed.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"write\": {\n \"type\": \"array\",\n \"description\": \"Absolute paths to grant write access; omit when none are needed.\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"additionalProperties\": false\n },\n \"network\": {\n \"type\": \"object\",\n \"description\": \"Network access request.\",\n \"properties\": {\n \"enabled\": {\n \"type\": \"boolean\",\n \"description\": \"True requests network access; false or omitted requests none.\"\n }\n },\n \"additionalProperties\": false\n }\n },\n \"additionalProperties\": false\n },\n \"cmd\": {\n \"type\": \"string\",\n \"description\": \"Shell command to execute.\"\n },\n \"environment_id\": {\n \"type\": \"string\",\n \"description\": \"Environment id from . Omit to use the primary environment.\"\n },\n \"justification\": {\n \"type\": \"string\",\n \"description\": \"User-facing approval question for `require_escalated`; omit otherwise.\"\n },\n \"login\": {\n \"type\": \"boolean\",\n \"description\": \"True runs the shell with -l/-i semantics; false disables them. Defaults to true.\"\n },\n \"max_output_tokens\": {\n \"type\": \"number\",\n \"description\": \"Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.\"\n },\n \"prefix_rule\": {\n \"type\": \"array\",\n \"description\": \"Reusable approval prefix for `cmd`, only with `sandbox_permissions: \\\"require_escalated\\\"`; for example [\\\"git\\\", \\\"pull\\\"].\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"sandbox_permissions\": {\n \"type\": \"string\",\n \"description\": \"Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions`, or `require_escalated` for unsandboxed execution.\",\n \"enum\": [\n \"use_default\",\n \"with_additional_permissions\",\n \"require_escalated\"\n ]\n },\n \"shell\": {\n \"type\": \"string\",\n \"description\": \"Shell binary to launch. Defaults to the user's default shell.\"\n },\n \"tty\": {\n \"type\": \"boolean\",\n \"description\": \"True allocates a PTY for the command; false or omitted uses plain pipes.\"\n },\n \"workdir\": {\n \"type\": \"string\",\n \"description\": \"Working directory for the command. Defaults to the turn cwd.\"\n },\n \"yield_time_ms\": {\n \"type\": \"number\",\n \"description\": \"Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.\"\n }\n },\n \"required\": [\n \"cmd\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "additional_permissions", "type": "\"object\"", "required": false, "notes": "Sandboxed filesystem or network access for this command; only with `sandbox_permissions: \"with_additional_permissions\"`." }, { "name": "cmd", "type": "\"string\"", "required": true, "notes": "Shell command to execute." }, { "name": "environment_id", "type": "\"string\"", "required": false, "notes": "Environment id from . Omit to use the primary environment." }, { "name": "justification", "type": "\"string\"", "required": false, "notes": "User-facing approval question for `require_escalated`; omit otherwise." }, { "name": "login", "type": "\"boolean\"", "required": false, "notes": "True runs the shell with -l/-i semantics; false disables them. Defaults to true." }, { "name": "max_output_tokens", "type": "\"number\"", "required": false, "notes": "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." }, { "name": "prefix_rule", "type": "\"array\"", "required": false, "notes": "Reusable approval prefix for `cmd`, only with `sandbox_permissions: \"require_escalated\"`; for example [\"git\", \"pull\"]." }, { "name": "sandbox_permissions", "type": "[\"use_default\", \"with_additional_permissions\", \"require_escalated\"]", "required": false, "notes": "Per-command sandbox override. Defaults to `use_default`; use `with_additional_permissions` with `additional_permissions`, or `require_escalated` for unsandboxed execution." }, { "name": "shell", "type": "\"string\"", "required": false, "notes": "Shell binary to launch. Defaults to the user's default shell." }, { "name": "tty", "type": "\"boolean\"", "required": false, "notes": "True allocates a PTY for the command; false or omitted uses plain pipes." }, { "name": "workdir", "type": "\"string\"", "required": false, "notes": "Working directory for the command. Defaults to the turn cwd." }, { "name": "yield_time_ms", "type": "\"number\"", "required": false, "notes": "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 . 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 } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"chunk_id\": {\n \"description\": \"Chunk identifier included when the response reports one.\",\n \"type\": \"string\"\n },\n \"exit_code\": {\n \"description\": \"Process exit code when the command finished during this call.\",\n \"type\": \"number\"\n },\n \"original_token_count\": {\n \"description\": \"Approximate token count before output truncation.\",\n \"type\": \"number\"\n },\n \"output\": {\n \"description\": \"Command output text, possibly truncated.\",\n \"type\": \"string\"\n },\n \"session_id\": {\n \"description\": \"Session identifier to pass to write_stdin when the process is still running.\",\n \"type\": \"number\"\n },\n \"wall_time_seconds\": {\n \"description\": \"Elapsed wall time spent waiting for output in seconds.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"wall_time_seconds\",\n \"output\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "chunk_id", "type": "\"string\"", "required": false, "notes": "Chunk identifier included when the response reports one." }, { "name": "exit_code", "type": "\"number\"", "required": false, "notes": "Process exit code when the command finished during this call." }, { "name": "original_token_count", "type": "\"number\"", "required": false, "notes": "Approximate token count before output truncation." }, { "name": "output", "type": "\"string\"", "required": true, "notes": "Command output text, possibly truncated." }, { "name": "session_id", "type": "\"number\"", "required": false, "notes": "Session identifier to pass to write_stdin when the process is still running." }, { "name": "wall_time_seconds", "type": "\"number\"", "required": true, "notes": "Elapsed wall time spent waiting for output in seconds." } ], "notes": "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.", "schema": { "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" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/shell_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/context.rs" ] }, { "name": "followup_task", "category": "core", "purpose": "Send a follow-up task to an existing non-root target agent and trigger a turn if it is idle.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"description\": \"Message text to send to the target agent.\",\n \"encrypted\": true\n },\n \"target\": {\n \"type\": \"string\",\n \"description\": \"Agent id or canonical task name to send a follow-up task to (from spawn_agent).\"\n }\n },\n \"required\": [\n \"target\",\n \"message\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "message", "type": "\"string\"", "required": true, "notes": "Message text to send to the target agent." }, { "name": "target", "type": "\"string\"", "required": true, "notes": "Agent id or canonical task name to send a follow-up task to (from spawn_agent)." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "free-form", "definition": "Empty text acknowledgment", "fields": [], "notes": "Message dispatch returns empty FunctionToolOutput on success; does not prove recipient execution or completion." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs" ] }, { "name": "get_context_remaining", "category": "core", "purpose": "Get the remaining tokens in the current context window.", "availability": "TokenBudget feature.", "aliases": [], "jobs": ["goals"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}", "fields": [], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"tokens_left\": {\n \"anyOf\": [\n {\n \"type\": \"integer\"\n },\n {\n \"type\": \"null\"\n }\n ],\n \"description\": \"Remaining tokens in the current context window, or null when unavailable.\"\n }\n },\n \"required\": [\n \"tokens_left\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "tokens_left", "type": "[{\"type\": \"integer\"}, {\"type\": \"null\"}]", "required": true, "notes": "Remaining tokens in the current context window, or null when unavailable." } ], "notes": "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.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/get_context_remaining_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/get_context_remaining.rs" ] }, { "name": "get_goal", "category": "extension", "purpose": "Get the current goal for this thread, including status, budgets, token and elapsed-time usage, and remaining token budget.", "availability": "App Server goal extension installed with state DB; Goals feature enabled. Mutations validate current goal state and token budget.", "aliases": [], "jobs": ["goals"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, PartialEq, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct GoalToolResponse {\n goal: Option,\n remaining_tokens: Option,\n completion_budget_report: Option,\n}\n\n#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub enum ThreadGoalStatus {\n Active,\n Paused,\n Blocked,\n UsageLimited,\n BudgetLimited,\n Complete,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub struct ThreadGoal {\n pub thread_id: ThreadId,\n pub objective: String,\n pub status: ThreadGoalStatus,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n #[ts(optional)]\n pub token_budget: Option,\n pub tokens_used: i64,\n pub time_used_seconds: i64,\n pub created_at: i64,\n pub updated_at: i64,\n}", "fields": [], "notes": "Serialized implementation response, not an advertised output schema. goal can be null; optional budget report depends on operation." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/tool.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs" ] }, { "name": "history.list_items", "category": "extension", "purpose": "List history items with optional window, role, and tool filters.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_name\": {\n \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of items to return.\"\n },\n \"max_chars_per_item\": {\n \"type\": \"integer\",\n \"description\": \"Maximum characters returned in each item's truncated_content.\"\n },\n \"recent_first\": {\n \"type\": \"boolean\",\n \"description\": \"Whether to return the most recently created items first.\"\n },\n \"role\": {\n \"description\": \"Message role to include. Null or omission includes all roles.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"enum\": [\n \"user\",\n \"assistant\",\n \"tool\",\n \"system\",\n \"developer\"\n ]\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"tool_name\": {\n \"description\": \"Callable tool name to include. When set, non-tool messages are excluded.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"tool_namespace\": {\n \"description\": \"Callable namespace to include. When set, non-tool messages are excluded.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"window_id\": {\n \"description\": \"Full window ID. Null or omission includes all windows.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n }\n}", "fields": [ { "name": "agent_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "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." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum number of items to return." }, { "name": "max_chars_per_item", "type": "\"integer\"", "required": false, "notes": "Maximum characters returned in each item's truncated_content." }, { "name": "recent_first", "type": "\"boolean\"", "required": false, "notes": "Whether to return the most recently created items first." }, { "name": "role", "type": "[{\"type\": \"string\", \"enum\": [\"user\", \"assistant\", \"tool\", \"system\", \"developer\"]}, {\"type\": \"null\"}]", "required": false, "notes": "Message role to include. Null or omission includes all roles." }, { "name": "tool_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Callable tool name to include. When set, non-tool messages are excluded." }, { "name": "tool_namespace", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Callable namespace to include. When set, non-tool messages are excluded." }, { "name": "window_id", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Full window ID. Null or omission includes all windows." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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" } ] } } } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "history.list_windows", "category": "extension", "purpose": "List an agent's context windows as window ID and item-count pairs.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_name\": {\n \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of windows to return.\"\n },\n \"recent_first\": {\n \"type\": \"boolean\",\n \"description\": \"Whether to return the most recently created windows first.\"\n }\n }\n}", "fields": [ { "name": "agent_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "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." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum number of windows to return." }, { "name": "recent_first", "type": "\"boolean\"", "required": false, "notes": "Whether to return the most recently created windows first." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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." } } } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "history.read_item", "category": "extension", "purpose": "Read a bounded range from private model-only history.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_name\": {\n \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"item_id\": {\n \"type\": \"string\",\n \"description\": \"The short item ID is the suffix shown in the target item's trailing `[id: ...]` marker, printed after that item's content.\"\n },\n \"limit_chars\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of characters to return.\"\n },\n \"offset_chars\": {\n \"type\": \"integer\",\n \"description\": \"Zero-based character offset at which reading starts.\"\n },\n \"window_id\": {\n \"type\": \"string\",\n \"description\": \"Full window ID containing the item.\"\n }\n },\n \"required\": [\n \"item_id\",\n \"window_id\"\n ]\n}", "fields": [ { "name": "agent_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "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." }, { "name": "item_id", "type": "\"string\"", "required": true, "notes": "The short item ID is the suffix shown in the target item's trailing `[id: ...]` marker, printed after that item's content." }, { "name": "limit_chars", "type": "\"integer\"", "required": false, "notes": "Maximum number of characters to return." }, { "name": "offset_chars", "type": "\"integer\"", "required": false, "notes": "Zero-based character offset at which reading starts." }, { "name": "window_id", "type": "\"string\"", "required": true, "notes": "Full window ID containing the item." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "history.search_contents", "category": "extension", "purpose": "Search private model-only history by literal substring.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_name\": {\n \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"limit\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of matching items to return.\"\n },\n \"query\": {\n \"type\": \"string\",\n \"description\": \"Case-sensitive literal substring to find in item content.\",\n \"encrypted\": true\n },\n \"recent_first\": {\n \"type\": \"boolean\",\n \"description\": \"Whether to return the most recently created matches first.\"\n },\n \"role\": {\n \"description\": \"Message role to include. Null or omission includes all roles.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"enum\": [\n \"user\",\n \"assistant\",\n \"tool\",\n \"system\",\n \"developer\"\n ]\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"tool_name\": {\n \"description\": \"Callable tool name to include. When set, non-tool messages are excluded.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"tool_namespace\": {\n \"description\": \"Callable namespace to include. When set, non-tool messages are excluded.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"window_id\": {\n \"description\": \"Full window ID. Null or omission includes all windows.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"required\": [\n \"query\"\n ]\n}", "fields": [ { "name": "agent_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "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." }, { "name": "limit", "type": "\"integer\"", "required": false, "notes": "Maximum number of matching items to return." }, { "name": "query", "type": "\"string\"", "required": true, "notes": "Case-sensitive literal substring to find in item content." }, { "name": "recent_first", "type": "\"boolean\"", "required": false, "notes": "Whether to return the most recently created matches first." }, { "name": "role", "type": "[{\"type\": \"string\", \"enum\": [\"user\", \"assistant\", \"tool\", \"system\", \"developer\"]}, {\"type\": \"null\"}]", "required": false, "notes": "Message role to include. Null or omission includes all roles." }, { "name": "tool_name", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Callable tool name to include. When set, non-tool messages are excluded." }, { "name": "tool_namespace", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Callable namespace to include. When set, non-tool messages are excluded." }, { "name": "window_id", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Full window ID. Null or omission includes all windows." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 matching items to return." }, "query": { "type": "string", "description": "Case-sensitive literal substring to find in item content.", "encrypted": true }, "recent_first": { "type": "boolean", "description": "Whether to return the most recently created matches 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" } ] } }, "required": ["query"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "image_gen.imagegen", "category": "extension", "purpose": "Generate or edit an image using the configured image backend.", "availability": "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.", "aliases": [], "jobs": ["deliver"], "input": { "kind": "source-declaration", "definition": "#[derive(Debug, Deserialize, JsonSchema)]\n#[serde(deny_unknown_fields)]\nstruct ImagegenArgs {\n prompt: String,\n /// Whether the output should have a transparent background. Defaults to false.\n #[serde(default)]\n transparent_background: bool,\n #[schemars(length(max = 5))]\n referenced_image_paths: Option>,\n #[schemars(range(min = 1, max = 5))]\n num_last_images_to_include: Option,\n}", "fields": [], "notes": "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." }, "output": { "kind": "implementation-shape", "definition": "struct GeneratedImageOutput {\n result: String,\n output_hint: Option,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/image-generation/src/tool.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/image-generation/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "interrupt_agent", "category": "core", "purpose": "Interrupt an agent's current turn, if any, and return its previous status.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"target\": {\n \"type\": \"string\",\n \"description\": \"Agent id or canonical task name to interrupt (from spawn_agent).\"\n }\n },\n \"required\": [\n \"target\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "target", "type": "\"string\"", "required": true, "notes": "Agent id or canonical task name to interrupt (from spawn_agent)." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "target": { "type": "string", "description": "Agent id or canonical task name to interrupt (from spawn_agent)." } }, "required": ["target"], "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"previous_status\": {\n \"allOf\": [\n {\n \"oneOf\": [\n {\n \"enum\": [\n \"pending_init\",\n \"running\",\n \"interrupted\",\n \"shutdown\",\n \"not_found\"\n ],\n \"type\": \"string\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"completed\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"completed\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"errored\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"errored\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n ],\n \"description\": \"The agent status observed before the interrupt request was handled.\"\n }\n },\n \"required\": [\n \"previous_status\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "previous_status", "type": "\"see schema\"", "required": true, "notes": "The agent status observed before the interrupt request was handled." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "previous_status": { "allOf": [ { "oneOf": [ { "enum": [ "pending_init", "running", "interrupted", "shutdown", "not_found" ], "type": "string" }, { "additionalProperties": false, "properties": { "completed": { "type": ["string", "null"] } }, "required": ["completed"], "type": "object" }, { "additionalProperties": false, "properties": { "errored": { "type": "string" } }, "required": ["errored"], "type": "object" } ] } ], "description": "The agent status observed before the interrupt request was handled." } }, "required": ["previous_status"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "list_agents", "category": "core", "purpose": "List live agents in the current root thread tree.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"path_prefix\": {\n \"type\": \"string\",\n \"description\": \"Task-path prefix filter without a trailing slash. Omit to list all live agents.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "path_prefix", "type": "\"string\"", "required": false, "notes": "Task-path prefix filter without a trailing slash. Omit to list all live agents." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "path_prefix": { "type": "string", "description": "Task-path prefix filter without a trailing slash. Omit to list all live agents." } }, "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"agents\": {\n \"description\": \"Live agents visible in the current root thread tree.\",\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"agent_name\": {\n \"description\": \"Canonical task name for the agent when available, otherwise the agent id.\",\n \"type\": \"string\"\n },\n \"agent_status\": {\n \"allOf\": [\n {\n \"oneOf\": [\n {\n \"enum\": [\n \"pending_init\",\n \"running\",\n \"interrupted\",\n \"shutdown\",\n \"not_found\"\n ],\n \"type\": \"string\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"completed\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"completed\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"errored\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"errored\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n ],\n \"description\": \"Last known status of the agent.\"\n }\n },\n \"required\": [\n \"agent_name\",\n \"agent_status\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"agents\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "agents", "type": "\"array\"", "required": true, "notes": "Live agents visible in the current root thread tree." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "agents": { "description": "Live agents visible in the current root thread tree.", "items": { "additionalProperties": false, "properties": { "agent_name": { "description": "Canonical task name for the agent when available, otherwise the agent id.", "type": "string" }, "agent_status": { "allOf": [ { "oneOf": [ { "enum": [ "pending_init", "running", "interrupted", "shutdown", "not_found" ], "type": "string" }, { "additionalProperties": false, "properties": { "completed": { "type": ["string", "null"] } }, "required": ["completed"], "type": "object" }, { "additionalProperties": false, "properties": { "errored": { "type": "string" } }, "required": ["errored"], "type": "object" } ] } ], "description": "Last known status of the agent." } }, "required": ["agent_name", "agent_status"], "type": "object" }, "type": "array" } }, "required": ["agents"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "list_available_plugins_to_install", "category": "core", "purpose": "List candidate plugins and connectors.", "availability": "ToolSuggest + Apps + Plugins and nonempty candidate list; ListTool presentation only.", "aliases": [], "jobs": ["discover"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": [],\n \"additionalProperties\": false\n}", "fields": [], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "output": { "kind": "source-declaration", "definition": "#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"snake_case\")]\npub enum DiscoverableToolType {\n Connector,\n Plugin,\n}\n\n#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"snake_case\")]\npub enum DiscoverableToolAction {\n Install,\n Enable,\n}\n\n#[derive(Clone, Debug, Serialize, PartialEq, Eq)]\npub struct RequestPluginInstallEntry {\n pub id: String,\n pub name: String,\n pub description: Option,\n pub tool_type: DiscoverableToolType,\n pub has_skills: bool,\n pub mcp_server_names: Vec,\n pub app_connector_ids: Vec,\n}\n\n#[derive(Clone, Debug, Serialize, PartialEq, Eq)]\npub struct ListAvailablePluginsToInstallResult {\n pub tools: Vec,\n}", "fields": [], "notes": "Implementation result declarations, not a formal output schema. Plugin suggestion completion and user confirmation do not alone prove future tool availability." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/list_available_plugins_to_install_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/list_available_plugins_to_install.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tools/src/tool_discovery.rs" ] }, { "name": "list_mcp_resource_templates", "category": "mcp-client", "purpose": "Lists resource templates provided by MCP servers.", "availability": "Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque cursor from a previous list_mcp_resource_templates call; omit for the first page.\"\n },\n \"server\": {\n \"type\": \"string\",\n \"description\": \"MCP server name. Omit to list resource templates from every configured server.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque cursor from a previous list_mcp_resource_templates call; omit for the first page." }, { "name": "server", "type": "\"string\"", "required": false, "notes": "MCP server name. Omit to list resource templates from every configured server." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Serialize)]\nstruct ResourceWithServer {\n server: String,\n #[serde(flatten)]\n resource: T,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct ListResourceTemplatesPayload {\n #[serde(skip_serializing_if = \"Option::is_none\")]\n server: Option,\n resource_templates: Vec>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n next_cursor: Option,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource.rs" ] }, { "name": "list_mcp_resources", "category": "mcp-client", "purpose": "Lists resources provided by MCP servers.", "availability": "Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\",\n \"description\": \"Opaque cursor from a previous list_mcp_resources call; omit for the first page.\"\n },\n \"server\": {\n \"type\": \"string\",\n \"description\": \"MCP server name. Omit to list resources from every configured server.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "Opaque cursor from a previous list_mcp_resources call; omit for the first page." }, { "name": "server", "type": "\"string\"", "required": false, "notes": "MCP server name. Omit to list resources from every configured server." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Serialize)]\nstruct ResourceWithServer {\n server: String,\n #[serde(flatten)]\n resource: T,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct ListResourcesPayload {\n #[serde(skip_serializing_if = \"Option::is_none\")]\n server: Option,\n resources: Vec>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n next_cursor: Option,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource.rs" ] }, { "name": "memories.add_ad_hoc_note", "category": "extension", "purpose": "Create a timestamped ad-hoc memory note.", "availability": "Memories extension installed; MemoryTool + memories.use_memories + dedicated_tools. Concrete contributor uses LocalMemoriesBackend; backend trait separately supports custom implementations.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"filename\": {\n \"description\": \"Name of the note file to create, in YYYY-MM-DDTHH-MM-SS-.md format. The slug must use only lowercase ASCII letters, digits, and hyphens.\",\n \"maxLength\": 128,\n \"minLength\": 24,\n \"pattern\": \"^\\\\d{4}-\\\\d{2}-\\\\d{2}T\\\\d{2}-\\\\d{2}-\\\\d{2}-[a-z0-9][a-z0-9-]{0,79}\\\\.md$\",\n \"type\": \"string\"\n },\n \"note\": {\n \"description\": \"Verbatim Markdown note to append to the ad-hoc memory notes.\",\n \"minLength\": 1,\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"filename\",\n \"note\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "filename", "type": "\"string\"", "required": true, "notes": "Name of the note file to create, in YYYY-MM-DDTHH-MM-SS-.md format. The slug must use only lowercase ASCII letters, digits, and hyphens." }, { "name": "note", "type": "\"string\"", "required": true, "notes": "Verbatim Markdown note to append to the ad-hoc memory notes." } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "filename": { "description": "Name of the note file to create, in YYYY-MM-DDTHH-MM-SS-.md format. The slug must use only lowercase ASCII letters, digits, and hyphens.", "maxLength": 128, "minLength": 24, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-[a-z0-9][a-z0-9-]{0,79}\\.md$", "type": "string" }, "note": { "description": "Verbatim Markdown note to append to the ad-hoc memory notes.", "minLength": 1, "type": "string" } }, "required": ["filename", "note"], "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"type\": \"object\"\n}", "fields": [], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/tools/ad_hoc_note.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/backend.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/lib.rs" ] }, { "name": "memories.list", "category": "extension", "purpose": "Page memory-store entries.", "availability": "Memories extension installed; MemoryTool + memories.use_memories + dedicated_tools. Concrete contributor uses LocalMemoriesBackend; backend trait separately supports custom implementations.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"max_results\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"type\": \"object\"\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" }, { "name": "max_results", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "path", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "cursor": { "type": "string" }, "max_results": { "format": "uint", "minimum": 1.0, "type": "integer" }, "path": { "type": "string" } }, "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"entries\": {\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"entry_type\": {\n \"enum\": [\n \"file\",\n \"directory\"\n ],\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"entry_type\",\n \"path\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"path\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"truncated\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"entries\",\n \"truncated\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "entries", "type": "\"array\"", "required": true, "notes": "" }, { "name": "next_cursor", "type": "[\"string\", \"null\"]", "required": false, "notes": "" }, { "name": "path", "type": "[\"string\", \"null\"]", "required": false, "notes": "" }, { "name": "truncated", "type": "\"boolean\"", "required": true, "notes": "" } ], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "entry_type": { "enum": ["file", "directory"], "type": "string" }, "path": { "type": "string" } }, "required": ["entry_type", "path"], "type": "object" }, "type": "array" }, "next_cursor": { "type": ["string", "null"] }, "path": { "type": ["string", "null"] }, "truncated": { "type": "boolean" } }, "required": ["entries", "truncated"], "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/tools/list.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/backend.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/lib.rs" ] }, { "name": "memories.read", "category": "extension", "purpose": "Read bounded memory file lines.", "availability": "Memories extension installed; MemoryTool + memories.use_memories + dedicated_tools. Concrete contributor uses LocalMemoriesBackend; backend trait separately supports custom implementations.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"line_offset\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"max_lines\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "line_offset", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "max_lines", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "path", "type": "\"string\"", "required": true, "notes": "" } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "line_offset": { "format": "uint", "minimum": 1.0, "type": "integer" }, "max_lines": { "format": "uint", "minimum": 1.0, "type": "integer" }, "path": { "type": "string" } }, "required": ["path"], "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"start_line_number\": {\n \"format\": \"uint\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"truncated\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"content\",\n \"path\",\n \"start_line_number\",\n \"truncated\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "content", "type": "\"string\"", "required": true, "notes": "" }, { "name": "path", "type": "\"string\"", "required": true, "notes": "" }, { "name": "start_line_number", "type": "\"integer\"", "required": true, "notes": "" }, { "name": "truncated", "type": "\"boolean\"", "required": true, "notes": "" } ], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "path": { "type": "string" }, "start_line_number": { "format": "uint", "minimum": 0.0, "type": "integer" }, "truncated": { "type": "boolean" } }, "required": ["content", "path", "start_line_number", "truncated"], "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/tools/read.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/backend.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/lib.rs" ] }, { "name": "memories.search", "category": "extension", "purpose": "Search stored memories.", "availability": "Memories extension installed; MemoryTool + memories.use_memories + dedicated_tools. Concrete contributor uses LocalMemoriesBackend; backend trait separately supports custom implementations.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"case_sensitive\": {\n \"type\": \"boolean\"\n },\n \"context_lines\": {\n \"format\": \"uint\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"cursor\": {\n \"type\": \"string\"\n },\n \"match_mode\": {\n \"oneOf\": [\n {\n \"properties\": {\n \"type\": {\n \"enum\": [\n \"any\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"type\": {\n \"enum\": [\n \"all_on_same_line\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"line_count\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"type\": {\n \"enum\": [\n \"all_within_lines\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"line_count\",\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"max_results\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"normalized\": {\n \"type\": \"boolean\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"queries\": {\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"queries\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "case_sensitive", "type": "\"boolean\"", "required": false, "notes": "" }, { "name": "context_lines", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" }, { "name": "match_mode", "type": "[{\"properties\": {\"type\": {\"enum\": [\"any\"], \"type\": \"string\"}}, \"required\": [\"type\"], \"type\": \"object\"}, {\"properties\": {\"type\": {\"enum\": [\"all_on_same_line\"], \"type\": \"string\"}}, \"required\": [\"type\"], \"type\": \"object\"}, {\"properties\": {\"line_count\": {\"format\": \"uint\", \"minimum\": 1.0, \"type\": \"integer\"}, \"type\": {\"enum\": [\"all_within_lines\"], \"type\": \"string\"}}, \"required\": [\"line_count\", \"type\"], \"type\": \"object\"}]", "required": false, "notes": "" }, { "name": "max_results", "type": "\"integer\"", "required": false, "notes": "" }, { "name": "normalized", "type": "\"boolean\"", "required": false, "notes": "" }, { "name": "path", "type": "\"string\"", "required": false, "notes": "" }, { "name": "queries", "type": "\"array\"", "required": true, "notes": "" } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "case_sensitive": { "type": "boolean" }, "context_lines": { "format": "uint", "minimum": 0.0, "type": "integer" }, "cursor": { "type": "string" }, "match_mode": { "oneOf": [ { "properties": { "type": { "enum": ["any"], "type": "string" } }, "required": ["type"], "type": "object" }, { "properties": { "type": { "enum": ["all_on_same_line"], "type": "string" } }, "required": ["type"], "type": "object" }, { "properties": { "line_count": { "format": "uint", "minimum": 1.0, "type": "integer" }, "type": { "enum": ["all_within_lines"], "type": "string" } }, "required": ["line_count", "type"], "type": "object" } ] }, "max_results": { "format": "uint", "minimum": 1.0, "type": "integer" }, "normalized": { "type": "boolean" }, "path": { "type": "string" }, "queries": { "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": ["queries"], "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"match_mode\": {\n \"oneOf\": [\n {\n \"properties\": {\n \"type\": {\n \"enum\": [\n \"any\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"type\": {\n \"enum\": [\n \"all_on_same_line\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"type\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"line_count\": {\n \"format\": \"uint\",\n \"minimum\": 1.0,\n \"type\": \"integer\"\n },\n \"type\": {\n \"enum\": [\n \"all_within_lines\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"line_count\",\n \"type\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"matches\": {\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"content_start_line_number\": {\n \"format\": \"uint\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"match_line_number\": {\n \"format\": \"uint\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"matched_queries\": {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"content\",\n \"content_start_line_number\",\n \"match_line_number\",\n \"matched_queries\",\n \"path\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"path\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"queries\": {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"truncated\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"match_mode\",\n \"matches\",\n \"queries\",\n \"truncated\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "match_mode", "type": "[{\"properties\": {\"type\": {\"enum\": [\"any\"], \"type\": \"string\"}}, \"required\": [\"type\"], \"type\": \"object\"}, {\"properties\": {\"type\": {\"enum\": [\"all_on_same_line\"], \"type\": \"string\"}}, \"required\": [\"type\"], \"type\": \"object\"}, {\"properties\": {\"line_count\": {\"format\": \"uint\", \"minimum\": 1.0, \"type\": \"integer\"}, \"type\": {\"enum\": [\"all_within_lines\"], \"type\": \"string\"}}, \"required\": [\"line_count\", \"type\"], \"type\": \"object\"}]", "required": true, "notes": "" }, { "name": "matches", "type": "\"array\"", "required": true, "notes": "" }, { "name": "next_cursor", "type": "[\"string\", \"null\"]", "required": false, "notes": "" }, { "name": "path", "type": "[\"string\", \"null\"]", "required": false, "notes": "" }, { "name": "queries", "type": "\"array\"", "required": true, "notes": "" }, { "name": "truncated", "type": "\"boolean\"", "required": true, "notes": "" } ], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "properties": { "match_mode": { "oneOf": [ { "properties": { "type": { "enum": ["any"], "type": "string" } }, "required": ["type"], "type": "object" }, { "properties": { "type": { "enum": ["all_on_same_line"], "type": "string" } }, "required": ["type"], "type": "object" }, { "properties": { "line_count": { "format": "uint", "minimum": 1.0, "type": "integer" }, "type": { "enum": ["all_within_lines"], "type": "string" } }, "required": ["line_count", "type"], "type": "object" } ] }, "matches": { "items": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "content_start_line_number": { "format": "uint", "minimum": 0.0, "type": "integer" }, "match_line_number": { "format": "uint", "minimum": 0.0, "type": "integer" }, "matched_queries": { "items": { "type": "string" }, "type": "array" }, "path": { "type": "string" } }, "required": [ "content", "content_start_line_number", "match_line_number", "matched_queries", "path" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": ["string", "null"] }, "path": { "type": ["string", "null"] }, "queries": { "items": { "type": "string" }, "type": "array" }, "truncated": { "type": "boolean" } }, "required": ["match_mode", "matches", "queries", "truncated"], "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/tools/search.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/backend.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/memories/src/lib.rs" ] }, { "name": "multi_agent_v1.close_agent", "category": "core", "purpose": "Close an agent and any open descendants when they are no longer needed, and return the target agent's previous status before shutdown was requested.", "availability": "MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"target\": {\n \"type\": \"string\",\n \"description\": \"Agent id to close (from spawn_agent).\"\n }\n },\n \"required\": [\n \"target\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "target", "type": "\"string\"", "required": true, "notes": "Agent id to close (from spawn_agent)." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "target": { "type": "string", "description": "Agent id to close (from spawn_agent)." } }, "required": ["target"], "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"previous_status\": {\n \"allOf\": [\n {\n \"oneOf\": [\n {\n \"enum\": [\n \"pending_init\",\n \"running\",\n \"interrupted\",\n \"shutdown\",\n \"not_found\"\n ],\n \"type\": \"string\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"completed\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"completed\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"errored\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"errored\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n ],\n \"description\": \"The agent status observed before shutdown was requested.\"\n }\n },\n \"required\": [\n \"previous_status\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "previous_status", "type": "\"see schema\"", "required": true, "notes": "The agent status observed before shutdown was requested." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "previous_status": { "allOf": [ { "oneOf": [ { "enum": [ "pending_init", "running", "interrupted", "shutdown", "not_found" ], "type": "string" }, { "additionalProperties": false, "properties": { "completed": { "type": ["string", "null"] } }, "required": ["completed"], "type": "object" }, { "additionalProperties": false, "properties": { "errored": { "type": "string" } }, "required": ["errored"], "type": "object" } ] } ], "description": "The agent status observed before shutdown was requested." } }, "required": ["previous_status"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "multi_agent_v1.resume_agent", "category": "core", "purpose": "Resume a previously closed agent by id so it can receive send_input and wait_agent calls.", "availability": "MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"description\": \"Agent id to resume.\"\n }\n },\n \"required\": [\n \"id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "id", "type": "\"string\"", "required": true, "notes": "Agent id to resume." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent id to resume." } }, "required": ["id"], "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"status\": {\n \"oneOf\": [\n {\n \"enum\": [\n \"pending_init\",\n \"running\",\n \"interrupted\",\n \"shutdown\",\n \"not_found\"\n ],\n \"type\": \"string\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"completed\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"completed\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"errored\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"errored\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n },\n \"required\": [\n \"status\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "status", "type": "[{\"enum\": [\"pending_init\", \"running\", \"interrupted\", \"shutdown\", \"not_found\"], \"type\": \"string\"}, {\"additionalProperties\": false, \"properties\": {\"completed\": {\"type\": [\"string\", \"null\"]}}, \"required\": [\"completed\"], \"type\": \"object\"}, {\"additionalProperties\": false, \"properties\": {\"errored\": {\"type\": \"string\"}}, \"required\": [\"errored\"], \"type\": \"object\"}]", "required": true, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "status": { "oneOf": [ { "enum": ["pending_init", "running", "interrupted", "shutdown", "not_found"], "type": "string" }, { "additionalProperties": false, "properties": { "completed": { "type": ["string", "null"] } }, "required": ["completed"], "type": "object" }, { "additionalProperties": false, "properties": { "errored": { "type": "string" } }, "required": ["errored"], "type": "object" } ] } }, "required": ["status"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "multi_agent_v1.send_input", "category": "core", "purpose": "Send a message to an existing agent.", "availability": "MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"interrupt\": {\n \"type\": \"boolean\",\n \"description\": \"True interrupts the current task and handles this message immediately; false or omitted queues it.\"\n },\n \"items\": {\n \"type\": \"array\",\n \"description\": \"Structured input items. Use this to pass explicit mentions (for example app:// connector paths).\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"audio_url\": {\n \"type\": \"string\",\n \"description\": \"Audio data URL when type is audio.\"\n },\n \"image_url\": {\n \"type\": \"string\",\n \"description\": \"Image URL when type is image.\"\n },\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Display name when type is skill or mention.\"\n },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Path when type is local_image/local_audio/skill, or structured mention target such as app:// or plugin://@ when type is mention.\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Text content when type is text.\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Input item type: text, image, local_image, audio, local_audio, skill, or mention.\"\n }\n },\n \"additionalProperties\": false\n }\n },\n \"message\": {\n \"type\": \"string\",\n \"description\": \"Legacy plain-text message to send to the agent. Use either message or items.\"\n },\n \"target\": {\n \"type\": \"string\",\n \"description\": \"Agent id to message (from spawn_agent).\"\n }\n },\n \"required\": [\n \"target\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "interrupt", "type": "\"boolean\"", "required": false, "notes": "True interrupts the current task and handles this message immediately; false or omitted queues it." }, { "name": "items", "type": "\"array\"", "required": false, "notes": "Structured input items. Use this to pass explicit mentions (for example app:// connector paths)." }, { "name": "message", "type": "\"string\"", "required": false, "notes": "Legacy plain-text message to send to the agent. Use either message or items." }, { "name": "target", "type": "\"string\"", "required": true, "notes": "Agent id to message (from spawn_agent)." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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:// or plugin://@ 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 } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"submission_id\": {\n \"description\": \"Identifier for the queued input submission.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"submission_id\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "submission_id", "type": "\"string\"", "required": true, "notes": "Identifier for the queued input submission." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "submission_id": { "description": "Identifier for the queued input submission.", "type": "string" } }, "required": ["submission_id"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "multi_agent_v1.spawn_agent", "category": "core", "purpose": "Spawn a sub-agent for a well-scoped task.", "availability": "MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_type\": {\n \"type\": \"string\",\n \"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\"\n },\n \"fork_context\": {\n \"type\": \"boolean\",\n \"description\": \"True forks the current thread history into the new agent; false or omitted starts with only the initial prompt.\"\n },\n \"items\": {\n \"type\": \"array\",\n \"description\": \"Structured input items. Use this to pass explicit mentions (for example app:// connector paths).\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"audio_url\": {\n \"type\": \"string\",\n \"description\": \"Audio data URL when type is audio.\"\n },\n \"image_url\": {\n \"type\": \"string\",\n \"description\": \"Image URL when type is image.\"\n },\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Display name when type is skill or mention.\"\n },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Path when type is local_image/local_audio/skill, or structured mention target such as app:// or plugin://@ when type is mention.\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Text content when type is text.\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Input item type: text, image, local_image, audio, local_audio, skill, or mention.\"\n }\n },\n \"additionalProperties\": false\n }\n },\n \"message\": {\n \"type\": \"string\",\n \"description\": \"Initial plain-text task for the new agent. Use either message or items.\"\n },\n \"model\": {\n \"type\": \"string\",\n \"description\": \"Model override for the new agent. Omit unless an explicit override is needed.\"\n },\n \"reasoning_effort\": {\n \"type\": \"string\",\n \"description\": \"Reasoning effort override for the new agent. Omit to inherit the parent effort.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "agent_type", "type": "\"string\"", "required": false, "notes": "Agent type override for the new agent. Omit to inherit the parent agent type with a full-history fork; otherwise, `default` is used.\n" }, { "name": "fork_context", "type": "\"boolean\"", "required": false, "notes": "True forks the current thread history into the new agent; false or omitted starts with only the initial prompt." }, { "name": "items", "type": "\"array\"", "required": false, "notes": "Structured input items. Use this to pass explicit mentions (for example app:// connector paths)." }, { "name": "message", "type": "\"string\"", "required": false, "notes": "Initial plain-text task for the new agent. Use either message or items." }, { "name": "model", "type": "\"string\"", "required": false, "notes": "Model override for the new agent. Omit unless an explicit override is needed." }, { "name": "reasoning_effort", "type": "\"string\"", "required": false, "notes": "Reasoning effort override for the new agent. Omit to inherit the parent effort." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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:// or plugin://@ 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 } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"agent_id\": {\n \"description\": \"Thread identifier for the spawned agent.\",\n \"type\": \"string\"\n },\n \"nickname\": {\n \"description\": \"User-facing nickname for the spawned agent when available.\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"agent_id\",\n \"nickname\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "agent_id", "type": "\"string\"", "required": true, "notes": "Thread identifier for the spawned agent." }, { "name": "nickname", "type": "[\"string\", \"null\"]", "required": true, "notes": "User-facing nickname for the spawned agent when available." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "multi_agent_v1.wait_agent", "category": "core", "purpose": "Wait for agents to reach a final status.", "availability": "MultiAgentVersion V1; next spawn depth within agent_max_depth. Deferred when model supports search. V1 namespace and contracts differ from V2.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"targets\": {\n \"type\": \"array\",\n \"description\": \"Agent ids to wait on. Pass multiple ids to wait for whichever finishes first.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"description\": \"Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000. Prefer longer waits (minutes) to avoid busy polling.\"\n }\n },\n \"required\": [\n \"targets\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "targets", "type": "\"array\"", "required": true, "notes": "Agent ids to wait on. Pass multiple ids to wait for whichever finishes first." }, { "name": "timeout_ms", "type": "\"number\"", "required": false, "notes": "Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000. Prefer longer waits (minutes) to avoid busy polling." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "targets": { "type": "array", "description": "Agent ids to wait on. Pass multiple ids to wait for whichever finishes first.", "items": { "type": "string" } }, "timeout_ms": { "type": "number", "description": "Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000. Prefer longer waits (minutes) to avoid busy polling." } }, "required": ["targets"], "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"status\": {\n \"additionalProperties\": {\n \"oneOf\": [\n {\n \"enum\": [\n \"pending_init\",\n \"running\",\n \"interrupted\",\n \"shutdown\",\n \"not_found\"\n ],\n \"type\": \"string\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"completed\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"completed\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"errored\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"errored\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"description\": \"Final statuses keyed by agent id.\",\n \"type\": \"object\"\n },\n \"timed_out\": {\n \"description\": \"Whether the wait call returned due to timeout before any agent reached a final status.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"status\",\n \"timed_out\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "status", "type": "\"object\"", "required": true, "notes": "Final statuses keyed by agent id." }, { "name": "timed_out", "type": "\"boolean\"", "required": true, "notes": "Whether the wait call returned due to timeout before any agent reached a final status." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "additionalProperties": false, "properties": { "status": { "additionalProperties": { "oneOf": [ { "enum": ["pending_init", "running", "interrupted", "shutdown", "not_found"], "type": "string" }, { "additionalProperties": false, "properties": { "completed": { "type": ["string", "null"] } }, "required": ["completed"], "type": "object" }, { "additionalProperties": false, "properties": { "errored": { "type": "string" } }, "required": ["errored"], "type": "object" } ] }, "description": "Final statuses keyed by agent id.", "type": "object" }, "timed_out": { "description": "Whether the wait call returned due to timeout before any agent reached a final status.", "type": "boolean" } }, "required": ["status", "timed_out"], "type": "object" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "multi_env_copy_file", "category": "extension", "purpose": "Copy a file between two execution environments.", "availability": "App Server installs contributor only with MultiEnvCopyFile feature. Source/target must be different ready environments with captured permissions.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "source-declaration", "definition": "#[derive(Deserialize)]\n#[serde(deny_unknown_fields)]\nstruct CopyFileArgs {\n source_environment_id: String,\n source_path: String,\n target_environment_id: String,\n target_path: String,\n}", "fields": [], "notes": "All four strings required; paths absolute. Source builder advertises additionalProperties=false." }, "output": { "kind": "implementation-shape", "definition": "{ bytes_copied: number }", "fields": [], "notes": "Handler JSON acknowledgment; no formal output schema. Failed/interrupted copies may leave a partial target." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/multi-env-copy-file/src/tool.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/app-server/src/extensions.rs" ] }, { "name": "new_context", "category": "core", "purpose": "Start a new context window.", "availability": "TokenBudget feature; direct-model-only.", "aliases": [], "jobs": ["goals"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}", "fields": [], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } }, "output": { "kind": "free-form", "definition": "Context-window transition acknowledgment", "fields": [], "notes": "Requests a new context window; environment state is preserved. No formal output schema." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/new_context_window_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "notes.append_to_file", "category": "extension", "purpose": "Append text to private model-only notes.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Note file path to append to.\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Text appended exactly as provided.\",\n \"encrypted\": true\n }\n },\n \"required\": [\n \"text\",\n \"path\"\n ]\n}", "fields": [ { "name": "path", "type": "\"string\"", "required": true, "notes": "Note file path to append to." }, { "name": "text", "type": "\"string\"", "required": true, "notes": "Text appended exactly as provided." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "Note file path to append to." }, "text": { "type": "string", "description": "Text appended exactly as provided.", "encrypted": true } }, "required": ["text", "path"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "notes.list_files_by_prefix", "category": "extension", "purpose": "List private model-only notes by path prefix.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"file_order\": {\n \"type\": \"string\",\n \"description\": \"Direction used to order files.\",\n \"enum\": [\n \"ascending\",\n \"descending\"\n ]\n },\n \"file_order_by\": {\n \"type\": \"string\",\n \"description\": \"Field used to order files.\",\n \"enum\": [\n \"name\",\n \"created_at\",\n \"updated_at\"\n ]\n },\n \"max_results\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of files to return.\"\n },\n \"prefix\": {\n \"description\": \"Note path prefix to list.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n }\n}", "fields": [ { "name": "file_order", "type": "[\"ascending\", \"descending\"]", "required": false, "notes": "Direction used to order files." }, { "name": "file_order_by", "type": "[\"name\", \"created_at\", \"updated_at\"]", "required": false, "notes": "Field used to order files." }, { "name": "max_results", "type": "\"integer\"", "required": false, "notes": "Maximum number of files to return." }, { "name": "prefix", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Note path prefix to list." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "file_order": { "type": "string", "description": "Direction used to order files.", "enum": ["ascending", "descending"] }, "file_order_by": { "type": "string", "description": "Field used to order files.", "enum": ["name", "created_at", "updated_at"] }, "max_results": { "type": "integer", "description": "Maximum number of files to return." }, "prefix": { "description": "Note path prefix to list.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "notes.read_file", "category": "extension", "purpose": "Read all or a line range from private model-only notes.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Note file path to read.\"\n },\n \"start_line\": {\n \"description\": \"First line to return, inclusive and 1-based. Negative values count backward from the final line.\",\n \"anyOf\": [\n {\n \"type\": \"integer\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"stop_line\": {\n \"description\": \"Last line to return, inclusive and 1-based. Negative values count backward from the final line.\",\n \"anyOf\": [\n {\n \"type\": \"integer\"\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"required\": [\n \"path\"\n ]\n}", "fields": [ { "name": "path", "type": "\"string\"", "required": true, "notes": "Note file path to read." }, { "name": "start_line", "type": "[{\"type\": \"integer\"}, {\"type\": \"null\"}]", "required": false, "notes": "First line to return, inclusive and 1-based. Negative values count backward from the final line." }, { "name": "stop_line", "type": "[{\"type\": \"integer\"}, {\"type\": \"null\"}]", "required": false, "notes": "Last line to return, inclusive and 1-based. Negative values count backward from the final line." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "Note file path to read." }, "start_line": { "description": "First line to return, inclusive and 1-based. Negative values count backward from the final line.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stop_line": { "description": "Last line to return, inclusive and 1-based. Negative values count backward from the final line.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": ["path"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "notes.search_contents", "category": "extension", "purpose": "Search private model-only note lines by literal substring.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"max_files\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of matching files returned.\"\n },\n \"max_matches_per_file\": {\n \"type\": \"integer\",\n \"description\": \"Maximum number of matching lines returned per file.\"\n },\n \"path_prefix\": {\n \"description\": \"Note path prefix to search.\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"query\": {\n \"type\": \"string\",\n \"description\": \"Case-sensitive literal substring to find in note lines.\",\n \"encrypted\": true\n },\n \"recent_file_first\": {\n \"type\": \"boolean\",\n \"description\": \"Whether to order matching files by creation time, newest first.\"\n }\n },\n \"required\": [\n \"query\"\n ]\n}", "fields": [ { "name": "max_files", "type": "\"integer\"", "required": false, "notes": "Maximum number of matching files returned." }, { "name": "max_matches_per_file", "type": "\"integer\"", "required": false, "notes": "Maximum number of matching lines returned per file." }, { "name": "path_prefix", "type": "[{\"type\": \"string\"}, {\"type\": \"null\"}]", "required": false, "notes": "Note path prefix to search." }, { "name": "query", "type": "\"string\"", "required": true, "notes": "Case-sensitive literal substring to find in note lines." }, { "name": "recent_file_first", "type": "\"boolean\"", "required": false, "notes": "Whether to order matching files by creation time, newest first." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "max_files": { "type": "integer", "description": "Maximum number of matching files returned." }, "max_matches_per_file": { "type": "integer", "description": "Maximum number of matching lines returned per file." }, "path_prefix": { "description": "Note path prefix to search.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "query": { "type": "string", "description": "Case-sensitive literal substring to find in note lines.", "encrypted": true }, "recent_file_first": { "type": "boolean", "description": "Whether to order matching files by creation time, newest first." } }, "required": ["query"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "notes.write_file", "category": "extension", "purpose": "Create or replace private model-only notes.", "availability": "App Server installs history-notes; token_budget.use_history_notes_extension + OpenAI provider + Codex-backend authentication. Hosted storage internals unavailable.", "aliases": [], "jobs": ["memory"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Note file path to create or replace.\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Complete replacement text for the file.\",\n \"encrypted\": true\n }\n },\n \"required\": [\n \"text\",\n \"path\"\n ]\n}", "fields": [ { "name": "path", "type": "\"string\"", "required": true, "notes": "Note file path to create or replace." }, { "name": "text", "type": "\"string\"", "required": true, "notes": "Complete replacement text for the file." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "Note file path to create or replace." }, "text": { "type": "string", "description": "Complete replacement text for the file.", "encrypted": true } }, "required": ["text", "path"] } }, "output": { "kind": "partial", "definition": "Backend JSON Value; optionally encrypted_output: string and images: [{data, mime_type, detail}]", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/tools.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/history-notes/src/backend.rs" ] }, { "name": "read_mcp_resource", "category": "mcp-client", "purpose": "Read a specific resource from an MCP server given the server name and resource URI.", "availability": "Configured MCP servers or CodeModeOnly mode. These are native MCP resource client helpers, not server tools/list results. Model catalog may override parameters.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"server\": {\n \"type\": \"string\",\n \"description\": \"MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources.\"\n },\n \"uri\": {\n \"type\": \"string\",\n \"description\": \"Resource URI to read. Must be one of the URIs returned by list_mcp_resources.\"\n }\n },\n \"required\": [\n \"server\",\n \"uri\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "server", "type": "\"string\"", "required": true, "notes": "MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources." }, { "name": "uri", "type": "\"string\"", "required": true, "notes": "Resource URI to read. Must be one of the URIs returned by list_mcp_resources." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Serialize)]\nstruct ResourceWithServer {\n server: String,\n #[serde(flatten)]\n resource: T,\n}\n\n#[derive(Debug, Serialize)]\nstruct ReadResourcePayload {\n server: String,\n uri: String,\n #[serde(flatten)]\n result: ReadResourceResult,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/mcp_resource.rs" ] }, { "name": "request_permissions", "category": "core", "purpose": "Request additional filesystem or network permissions from the user and wait for the client to grant a subset of the requested permission profile.", "availability": "RequestPermissionsTool feature; selected environment and client grant response. Handler accepts environmentId as an alias of environment_id.", "aliases": ["environmentId (handler input alias; schema advertises environment_id)"], "jobs": ["permissions"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\",\n \"description\": \"Environment id from . Omit to use the primary environment.\"\n },\n \"permissions\": {\n \"type\": \"object\",\n \"description\": \"Filesystem or network access request.\",\n \"properties\": {\n \"file_system\": {\n \"type\": \"object\",\n \"description\": \"Filesystem access request.\",\n \"properties\": {\n \"read\": {\n \"type\": \"array\",\n \"description\": \"Absolute paths to grant read access; omit when none are needed.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"write\": {\n \"type\": \"array\",\n \"description\": \"Absolute paths to grant write access; omit when none are needed.\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"additionalProperties\": false\n },\n \"network\": {\n \"type\": \"object\",\n \"description\": \"Network access request.\",\n \"properties\": {\n \"enabled\": {\n \"type\": \"boolean\",\n \"description\": \"True requests network access; false or omitted requests none.\"\n }\n },\n \"additionalProperties\": false\n }\n },\n \"additionalProperties\": false\n },\n \"reason\": {\n \"type\": \"string\",\n \"description\": \"Optional short explanation for why additional permissions are needed.\"\n }\n },\n \"required\": [\n \"permissions\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "environment_id", "type": "\"string\"", "required": false, "notes": "Environment id from . Omit to use the primary environment." }, { "name": "permissions", "type": "\"object\"", "required": true, "notes": "Filesystem or network access request." }, { "name": "reason", "type": "\"string\"", "required": false, "notes": "Optional short explanation for why additional permissions are needed." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "environment_id": { "type": "string", "description": "Environment id from . 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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(deny_unknown_fields)]\npub struct RequestPermissionProfile {\n pub network: Option,\n pub file_system: Option,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\npub struct RequestPermissionsResponse {\n pub permissions: RequestPermissionProfile,\n #[serde(default)]\n pub scope: PermissionGrantScope,\n /// Review subsequent commands in this turn unless a permission hook resolves the request.\n #[serde(default, skip_serializing_if = \"std::ops::Not::not\")]\n pub strict_auto_review: bool,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/shell_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_permissions.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/request_permissions.rs" ] }, { "name": "request_plugin_install", "category": "core", "purpose": "Request installation of an explicitly selected plugin or connector.", "availability": "ToolSuggest + Apps + Plugins and nonempty candidate list; either ListTool or RecommendationContext presentation.", "aliases": [], "jobs": ["discover"], "input": { "kind": "json-schema", "definition": "{\n \"anyOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"plugin_id\": {\n \"type\": \"string\",\n \"description\": \"The parenthesized plugin ID from the `` list.\"\n },\n \"suggest_reason\": {\n \"type\": \"string\",\n \"description\": \"Concise one-line user-facing reason why this plugin can help with the current request.\"\n }\n },\n \"required\": [\n \"plugin_id\",\n \"suggest_reason\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"action_type\": {\n \"type\": \"string\",\n \"description\": \"Suggested action for the tool. Use \\\"install\\\".\"\n },\n \"suggest_reason\": {\n \"type\": \"string\",\n \"description\": \"Concise one-line user-facing reason why this plugin or connector can help with the current request.\"\n },\n \"tool_id\": {\n \"type\": \"string\",\n \"description\": \"Connector or plugin id to suggest.\"\n },\n \"tool_type\": {\n \"type\": \"string\",\n \"description\": \"Type of discoverable tool to suggest. Use \\\"connector\\\" or \\\"plugin\\\".\"\n }\n },\n \"required\": [\n \"tool_type\",\n \"action_type\",\n \"tool_id\",\n \"suggest_reason\"\n ],\n \"additionalProperties\": false\n }\n ]\n}", "fields": [], "notes": "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.", "schema": { "anyOf": [ { "type": "object", "properties": { "plugin_id": { "type": "string", "description": "The parenthesized plugin ID from the `` 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 } ] } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Serialize, PartialEq, Eq)]\npub struct RequestPluginInstallResult {\n pub completed: bool,\n pub user_confirmed: bool,\n pub tool_type: DiscoverableToolType,\n pub action_type: DiscoverableToolAction,\n pub tool_id: String,\n pub tool_name: String,\n pub suggest_reason: String,\n}", "fields": [], "notes": "Implementation result declarations, not a formal output schema. Plugin suggestion completion and user confirmation do not alone prove future tool availability." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_plugin_install_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_plugin_install.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tools/src/request_plugin_install.rs" ] }, { "name": "request_user_input", "category": "core", "purpose": "Ask blocking multiple-choice questions.", "availability": "experimental_request_user_input_enabled. Direct-model-only; handler checks the configured allowed collaboration modes (Plan by default).", "aliases": [], "jobs": ["ask-user"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"questions\": {\n \"type\": \"array\",\n \"description\": \"Questions to show the user. Prefer 1 and do not exceed 3\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"header\": {\n \"type\": \"string\",\n \"description\": \"Short header label shown in the UI (12 or fewer chars).\"\n },\n \"id\": {\n \"type\": \"string\",\n \"description\": \"Stable identifier for mapping answers (snake_case).\"\n },\n \"options\": {\n \"type\": \"array\",\n \"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.\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"description\": {\n \"type\": \"string\",\n \"description\": \"One short sentence explaining impact/tradeoff if selected.\"\n },\n \"label\": {\n \"type\": \"string\",\n \"description\": \"User-facing label (1-5 words).\"\n }\n },\n \"required\": [\n \"label\",\n \"description\"\n ],\n \"additionalProperties\": false\n }\n },\n \"question\": {\n \"type\": \"string\",\n \"description\": \"Single-sentence prompt shown to the user.\"\n }\n },\n \"required\": [\n \"id\",\n \"header\",\n \"question\",\n \"options\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"questions\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "questions", "type": "\"array\"", "required": true, "notes": "Questions to show the user. Prefer 1 and do not exceed 3" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\npub struct RequestUserInputAnswer {\n pub answers: Vec,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\npub struct RequestUserInputResponse {\n pub answers: HashMap,\n}", "fields": [], "notes": "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." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_user_input_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_user_input.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/request_user_input.rs" ] }, { "name": "request_user_input_async", "category": "core", "purpose": "Present questions without waiting for a reply.", "availability": "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": [ "send_user_message_async (catalog eligibility name only; not a second registered callable)" ], "jobs": ["ask-user"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"questions\": {\n \"type\": \"array\",\n \"description\": \"One or more self-contained questions to present together, in display order.\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"options\": {\n \"type\": \"array\",\n \"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.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"description\": \"The complete question shown to the user, including any context needed to answer it.\"\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n },\n \"minItems\": 1\n }\n },\n \"required\": [\n \"questions\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "questions", "type": "\"array\"", "required": true, "notes": "One or more self-contained questions to present together, in display order." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "implementation-shape", "definition": "{\"accepted\": true}", "fields": [], "notes": "Handler emits JSON text; accepts delivery asynchronously, does not wait for a user response." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/request_user_input_async.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "send_message", "category": "core", "purpose": "Send a message to an existing agent.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"description\": \"Message text to queue on the target agent.\",\n \"encrypted\": true\n },\n \"target\": {\n \"type\": \"string\",\n \"description\": \"Relative or canonical task name to message (from spawn_agent).\"\n }\n },\n \"required\": [\n \"target\",\n \"message\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "message", "type": "\"string\"", "required": true, "notes": "Message text to queue on the target agent." }, { "name": "target", "type": "\"string\"", "required": true, "notes": "Relative or canonical task name to message (from spawn_agent)." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "free-form", "definition": "Empty text acknowledgment", "fields": [], "notes": "Message dispatch returns empty FunctionToolOutput on success; does not prove recipient execution or completion." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs" ] }, { "name": "send_message_to_user_async", "category": "core", "purpose": "Send a concise message that needs the user's attention during ongoing work.", "availability": "Root agent, SendMessageToUserAsync feature or matching model experimental tool. Direct-model-only.", "aliases": [], "jobs": ["ask-user"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"description\": \"The concise question or update to send to the user.\"\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "message", "type": "\"string\"", "required": true, "notes": "The concise question or update to send to the user." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The concise question or update to send to the user." } }, "required": ["message"], "additionalProperties": false } }, "output": { "kind": "implementation-shape", "definition": "{\"accepted\": true}", "fields": [], "notes": "Handler emits JSON text; accepts delivery asynchronously, does not wait for a user response." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/send_message_to_user_async.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "skills.installations", "category": "extension", "purpose": "Page installations for a skill package.", "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.", "aliases": [], "jobs": ["skills"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"package\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"oneOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"kind\": {\n \"enum\": [\n \"cloud\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\"\n },\n \"kind\": {\n \"enum\": [\n \"executor\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"environment_id\",\n \"kind\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n },\n \"required\": [\n \"package\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" }, { "name": "package", "type": "\"string\"", "required": true, "notes": "" }, { "name": "source", "type": "[{\"additionalProperties\": false, \"properties\": {\"kind\": {\"enum\": [\"cloud\"], \"type\": \"string\"}}, \"required\": [\"kind\"], \"type\": \"object\"}, {\"additionalProperties\": false, \"properties\": {\"environment_id\": {\"type\": \"string\"}, \"kind\": {\"enum\": [\"executor\"], \"type\": \"string\"}}, \"required\": [\"environment_id\", \"kind\"], \"type\": \"object\"}]", "required": false, "notes": "" } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "cursor": { "type": "string" }, "package": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": ["cloud"], "type": "string" } }, "required": ["kind"], "type": "object" }, { "additionalProperties": false, "properties": { "environment_id": { "type": "string" }, "kind": { "enum": ["executor"], "type": "string" } }, "required": ["environment_id", "kind"], "type": "object" } ] } }, "required": ["package"], "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"installations\": {\n \"items\": {\n \"anyOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"package\": {\n \"type\": \"string\"\n },\n \"resource\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"package\",\n \"resource\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\"\n },\n \"skill_root\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"environment_id\",\n \"skill_root\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"installations\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "installations", "type": "\"array\"", "required": true, "notes": "" }, { "name": "next_cursor", "type": "[\"string\", \"null\"]", "required": false, "notes": "" } ], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "properties": { "installations": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "package": { "type": "string" }, "resource": { "type": "string" } }, "required": ["package", "resource"], "type": "object" }, { "additionalProperties": false, "properties": { "environment_id": { "type": "string" }, "skill_root": { "type": "string" } }, "required": ["environment_id", "skill_root"], "type": "object" } ] }, "type": "array" }, "next_cursor": { "type": ["string", "null"] } }, "required": ["installations"], "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/installations.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/mod.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/step_state.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/sources.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/app-server/src/extensions.rs" ] }, { "name": "skills.list", "category": "extension", "purpose": "Page a selected skill authority catalog.", "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.", "aliases": [], "jobs": ["skills"], "input": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"authority\": {\n \"oneOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"kind\": {\n \"enum\": [\n \"cloud\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"kind\": {\n \"enum\": [\n \"executor\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"cursor\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"authority\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "authority", "type": "[{\"additionalProperties\": false, \"properties\": {\"kind\": {\"enum\": [\"cloud\"], \"type\": \"string\"}}, \"required\": [\"kind\"], \"type\": \"object\"}, {\"additionalProperties\": false, \"properties\": {\"kind\": {\"enum\": [\"executor\"], \"type\": \"string\"}}, \"required\": [\"kind\"], \"type\": \"object\"}]", "required": true, "notes": "" }, { "name": "cursor", "type": "\"string\"", "required": false, "notes": "" } ], "notes": "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.", "schema": { "additionalProperties": false, "properties": { "authority": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": ["cloud"], "type": "string" } }, "required": ["kind"], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": ["executor"], "type": "string" } }, "required": ["kind"], "type": "object" } ] }, "cursor": { "type": "string" } }, "required": ["authority"], "type": "object" } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"skills\": {\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"authority\": {\n \"oneOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"kind\": {\n \"enum\": [\n \"cloud\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"kind\": {\n \"enum\": [\n \"executor\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"kind\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"main_resource\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"package\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"authority\",\n \"description\",\n \"main_resource\",\n \"name\",\n \"package\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"warnings\": {\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n }\n },\n \"required\": [\n \"skills\",\n \"warnings\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "next_cursor", "type": "[\"string\", \"null\"]", "required": false, "notes": "" }, { "name": "skills", "type": "\"array\"", "required": true, "notes": "" }, { "name": "warnings", "type": "\"array\"", "required": true, "notes": "" } ], "notes": "Generated from source output types and output_schema_for(option_add_null_type=true); not an error/denial union.", "schema": { "additionalProperties": false, "properties": { "next_cursor": { "type": ["string", "null"] }, "skills": { "items": { "additionalProperties": false, "properties": { "authority": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": ["cloud"], "type": "string" } }, "required": ["kind"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "enum": ["executor"], "type": "string" } }, "required": ["id", "kind"], "type": "object" } ] }, "description": { "type": "string" }, "main_resource": { "type": "string" }, "name": { "type": "string" }, "package": { "type": "string" } }, "required": ["authority", "description", "main_resource", "name", "package"], "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": ["skills", "warnings"], "type": "object" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/list.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/mod.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/step_state.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/sources.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/app-server/src/extensions.rs" ] }, { "name": "skills.read", "category": "extension", "purpose": "Read a skill resource.", "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.", "aliases": [], "jobs": ["skills"], "input": { "kind": "json-schema", "definition": "{\n \"anyOf\": [\n {\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"package\": {\n \"type\": \"string\"\n },\n \"resource\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"package\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"cursor\": {\n \"type\": \"string\"\n },\n \"package\": {\n \"type\": \"string\"\n },\n \"resource\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"oneOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"kind\": {\n \"enum\": [\n \"cloud\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\"\n },\n \"kind\": {\n \"enum\": [\n \"executor\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"environment_id\",\n \"kind\"\n ],\n \"type\": \"object\"\n }\n ]\n }\n },\n \"required\": [\n \"package\"\n ],\n \"type\": \"object\"\n }\n ]\n}", "fields": [], "notes": "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\").", "schema": { "anyOf": [ { "properties": { "cursor": { "type": "string" }, "package": { "type": "string" }, "resource": { "type": "string" } }, "required": ["package"], "type": "object" }, { "properties": { "cursor": { "type": "string" }, "package": { "type": "string" }, "resource": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": ["cloud"], "type": "string" } }, "required": ["kind"], "type": "object" }, { "additionalProperties": false, "properties": { "environment_id": { "type": "string" }, "kind": { "enum": ["executor"], "type": "string" } }, "required": ["environment_id", "kind"], "type": "object" } ] } }, "required": ["package"], "type": "object" } ] } }, "output": { "kind": "json-schema", "definition": "{\n \"anyOf\": [\n {\n \"properties\": {\n \"contents\": {\n \"type\": \"string\"\n },\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"resource\": {\n \"type\": \"string\"\n },\n \"skill_root\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"contents\",\n \"resource\"\n ],\n \"type\": \"object\"\n },\n {\n \"properties\": {\n \"contents\": {\n \"type\": \"string\"\n },\n \"installations\": {\n \"items\": {\n \"anyOf\": [\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"package\": {\n \"type\": \"string\"\n },\n \"resource\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"package\",\n \"resource\"\n ],\n \"type\": \"object\"\n },\n {\n \"additionalProperties\": false,\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\"\n },\n \"skill_root\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"environment_id\",\n \"skill_root\"\n ],\n \"type\": \"object\"\n }\n ]\n },\n \"type\": \"array\"\n },\n \"installations_truncated\": {\n \"type\": \"boolean\"\n },\n \"next_cursor\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"resource\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"contents\",\n \"installations\",\n \"installations_truncated\",\n \"resource\"\n ],\n \"type\": \"object\"\n }\n ]\n}", "fields": [], "notes": "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\").", "schema": { "anyOf": [ { "properties": { "contents": { "type": "string" }, "next_cursor": { "type": ["string", "null"] }, "resource": { "type": "string" }, "skill_root": { "type": ["string", "null"] } }, "required": ["contents", "resource"], "type": "object" }, { "properties": { "contents": { "type": "string" }, "installations": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "package": { "type": "string" }, "resource": { "type": "string" } }, "required": ["package", "resource"], "type": "object" }, { "additionalProperties": false, "properties": { "environment_id": { "type": "string" }, "skill_root": { "type": "string" } }, "required": ["environment_id", "skill_root"], "type": "object" } ] }, "type": "array" }, "installations_truncated": { "type": "boolean" }, "next_cursor": { "type": ["string", "null"] }, "resource": { "type": "string" } }, "required": ["contents", "installations", "installations_truncated", "resource"], "type": "object" } ] } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/read.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/mod.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/tools/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/step_state.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/skills/src/sources.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/app-server/src/extensions.rs" ] }, { "name": "spawn_agent", "category": "core", "purpose": "Spawns an agent to work on the specified task.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"agent_type\": {\n \"type\": \"string\",\n \"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\"\n },\n \"fork_turns\": {\n \"type\": \"string\",\n \"description\": \"Parent history to inherit. Defaults to `all`; use `none` to start without parent history. Only `all` and `none` are supported.\"\n },\n \"message\": {\n \"type\": \"string\",\n \"description\": \"Initial plain-text task for the new agent.\",\n \"encrypted\": true\n },\n \"model\": {\n \"type\": \"string\",\n \"description\": \"Model override for the new agent. Omit unless an explicit override is needed.\"\n },\n \"reasoning_effort\": {\n \"type\": \"string\",\n \"description\": \"Reasoning effort override for the new agent. Omit to inherit the parent effort.\"\n },\n \"task_name\": {\n \"type\": \"string\",\n \"description\": \"Task name for the new agent. Use lowercase letters, digits, and underscores.\"\n }\n },\n \"required\": [\n \"task_name\",\n \"message\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "agent_type", "type": "\"string\"", "required": false, "notes": "Agent type override for the new agent. Omit unless explicitly asked. The selected role applies regardless of how much parent history is inherited.\n" }, { "name": "fork_turns", "type": "\"string\"", "required": false, "notes": "Parent history to inherit. Defaults to `all`; use `none` to start without parent history. Only `all` and `none` are supported." }, { "name": "message", "type": "\"string\"", "required": true, "notes": "Initial plain-text task for the new agent." }, { "name": "model", "type": "\"string\"", "required": false, "notes": "Model override for the new agent. Omit unless an explicit override is needed." }, { "name": "reasoning_effort", "type": "\"string\"", "required": false, "notes": "Reasoning effort override for the new agent. Omit to inherit the parent effort." }, { "name": "task_name", "type": "\"string\"", "required": true, "notes": "Task name for the new agent. Use lowercase letters, digits, and underscores." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"nickname\": {\n \"description\": \"User-facing nickname for the spawned agent when available.\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"task_name\": {\n \"description\": \"Canonical task name for the spawned agent.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"task_name\",\n \"nickname\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "nickname", "type": "[\"string\", \"null\"]", "required": true, "notes": "User-facing nickname for the spawned agent when available." }, { "name": "task_name", "type": "\"string\"", "required": true, "notes": "Canonical task name for the spawned agent." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "test_sync_tool", "category": "core", "purpose": "Internal synchronization helper used by Codex integration tests.", "availability": "Only model metadata experimental_supported_tools includes test_sync_tool; integration-test helper.", "aliases": [], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"barrier\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"description\": \"Identifier shared by concurrent calls that should rendezvous\"\n },\n \"participants\": {\n \"type\": \"number\",\n \"description\": \"Number of tool calls that must arrive before the barrier opens\"\n },\n \"timeout_ms\": {\n \"type\": \"number\",\n \"description\": \"Maximum barrier wait in milliseconds. Defaults to 1000.\"\n }\n },\n \"required\": [\n \"id\",\n \"participants\"\n ],\n \"additionalProperties\": false\n },\n \"sleep_after_ms\": {\n \"type\": \"number\",\n \"description\": \"Delay after completing the barrier. Defaults to no delay.\"\n },\n \"sleep_before_ms\": {\n \"type\": \"number\",\n \"description\": \"Delay before any other action. Defaults to no delay.\"\n },\n \"wait_for_git_enrichment\": {\n \"type\": \"boolean\",\n \"description\": \"Wait for Git enrichment for the current turn to finish, subject to a timeout.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "barrier", "type": "\"object\"", "required": false, "notes": "" }, { "name": "sleep_after_ms", "type": "\"number\"", "required": false, "notes": "Delay after completing the barrier. Defaults to no delay." }, { "name": "sleep_before_ms", "type": "\"number\"", "required": false, "notes": "Delay before any other action. Defaults to no delay." }, { "name": "wait_for_git_enrichment", "type": "\"boolean\"", "required": false, "notes": "Wait for Git enrichment for the current turn to finish, subject to a timeout." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "free-form", "definition": "Text synchronization acknowledgment", "fields": [], "notes": "Internal integration-test helper; barrier timeout and Git-enrichment failures may be model-facing errors." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/test_sync_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "tool_search", "category": "core", "purpose": "Discover deferred tools for a subsequent model call.", "availability": "Model supports search; policy allows it; at least one eligible deferred searchable tool. Code-mode placement depends on CodeModeToolSearch.", "aliases": [], "jobs": ["discover"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"number\",\n \"description\": \"Default supplied by router.\"\n }\n },\n \"required\": [\n \"query\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "query", "type": "\"string\"", "required": true, "notes": "" }, { "name": "limit", "type": "\"number\"", "required": false, "notes": "Default supplied by router." } ], "notes": "Source builder transcription; default limit and searchable sources are runtime configuration.", "schema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "number", "description": "Default supplied by router." } }, "required": ["query"], "additionalProperties": false } }, "output": { "kind": "implementation-shape", "definition": "ToolSearchOutput / tool_search_output with discovered tool definitions", "fields": [], "notes": "Search exposes matching tools on a subsequent model call; this is not an MCP tools/list response." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/tool_search_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/tool_search.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "update_goal", "category": "extension", "purpose": "Update the current goal status.", "availability": "App Server goal extension installed with state DB; Goals feature enabled. Mutations validate current goal state and token budget.", "aliases": [], "jobs": ["goals"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"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.\",\n \"enum\": [\n \"complete\",\n \"blocked\",\n \"paused\"\n ]\n }\n },\n \"required\": [\n \"status\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "status", "type": "[\"complete\", \"blocked\", \"paused\"]", "required": true, "notes": "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." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "source-declaration", "definition": "#[derive(Debug, PartialEq, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct GoalToolResponse {\n goal: Option,\n remaining_tokens: Option,\n completion_budget_report: Option,\n}\n\n#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub enum ThreadGoalStatus {\n Active,\n Paused,\n Blocked,\n UsageLimited,\n BudgetLimited,\n Complete,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]\n#[serde(rename_all = \"camelCase\")]\n#[ts(export_to = \"protocol/\")]\npub struct ThreadGoal {\n pub thread_id: ThreadId,\n pub objective: String,\n pub status: ThreadGoalStatus,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n #[ts(optional)]\n pub token_budget: Option,\n pub tokens_used: i64,\n pub time_used_seconds: i64,\n pub created_at: i64,\n pub updated_at: i64,\n}", "fields": [], "notes": "Serialized implementation response, not an advertised output schema. goal can be null; optional budget report depends on operation." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/goal/src/tool.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs" ] }, { "name": "update_plan", "category": "core", "purpose": "Updates the task plan.", "availability": "config.update_plan_enabled.", "aliases": [], "jobs": ["plan"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"explanation\": {\n \"type\": \"string\",\n \"description\": \"Optional explanation for this plan update.\"\n },\n \"plan\": {\n \"type\": \"array\",\n \"description\": \"The list of steps\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"description\": \"Step status.\",\n \"enum\": [\n \"pending\",\n \"in_progress\",\n \"completed\"\n ]\n },\n \"step\": {\n \"type\": \"string\",\n \"description\": \"Task step text.\"\n }\n },\n \"required\": [\n \"step\",\n \"status\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"plan\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "explanation", "type": "\"string\"", "required": false, "notes": "Optional explanation for this plan update." }, { "name": "plan", "type": "\"array\"", "required": true, "notes": "The list of steps" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "explanation": { "type": "string", "description": "Optional explanation for this plan update." }, "plan": { "type": "array", "description": "The list of steps", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "Step status.", "enum": ["pending", "in_progress", "completed"] }, "step": { "type": "string", "description": "Task step text." } }, "required": ["step", "status"], "additionalProperties": false } } }, "required": ["plan"], "additionalProperties": false } }, "output": { "kind": "free-form", "definition": "Plan updated", "fields": [], "notes": "Text acknowledgment; handler validates plan arguments. No formal output schema." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/plan_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "user_message.read_messages", "category": "mcp-client", "purpose": "Guardian conversation-history adapter over a host-owned Apps MCP tool.", "availability": "Guardian review session; parent Apps + GuardianConversationHistoryTools; live parent binding contains user_message.read_messages. Not a standalone fixed-schema native implementation.", "aliases": [], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Input schema copied from the live parent MCP catalog; not available in the public static source." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Live MCP result bounded by guardian_conversation_history_max_output_tokens (default 4000); server result schema unavailable." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/mcp_tool_call/conversation_history.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/guardian-v2/src/sync_reviewer/conversation_history.rs" ] }, { "name": "user_message.search_messages", "category": "mcp-client", "purpose": "Guardian conversation-history adapter over a host-owned Apps MCP tool.", "availability": "Guardian review session; parent Apps + GuardianConversationHistoryTools; live parent binding contains user_message.search_messages. Not a standalone fixed-schema native implementation.", "aliases": [], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Input schema copied from the live parent MCP catalog; not available in the public static source." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Live MCP result bounded by guardian_conversation_history_max_output_tokens (default 4000); server result schema unavailable." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/mcp_tool_call/conversation_history.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/guardian-v2/src/sync_reviewer/conversation_history.rs" ] }, { "name": "view_image", "category": "core", "purpose": "View a local image file from the filesystem when visual inspection is needed.", "availability": "ViewImage feature. environment_id only for multiple environments; detail only when original detail is supported and unified image budget is off.", "aliases": [], "jobs": ["read"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"detail\": {\n \"type\": \"string\",\n \"description\": \"Image detail level. Defaults to `high`; use `original` to preserve exact resolution.\",\n \"enum\": [\n \"high\",\n \"original\"\n ]\n },\n \"environment_id\": {\n \"type\": \"string\",\n \"description\": \"Environment id from . Omit to use the primary environment.\"\n },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Local filesystem path to an image file.\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "detail", "type": "[\"high\", \"original\"]", "required": false, "notes": "Image detail level. Defaults to `high`; use `original` to preserve exact resolution." }, { "name": "environment_id", "type": "\"string\"", "required": false, "notes": "Environment id from . Omit to use the primary environment." }, { "name": "path", "type": "\"string\"", "required": true, "notes": "Local filesystem path to an image file." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 . Omit to use the primary environment." }, "path": { "type": "string", "description": "Local filesystem path to an image file." } }, "required": ["path"], "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"detail\": {\n \"description\": \"Image detail hint returned by view_image. Returns `high` for default resized behavior or `original` when original resolution is preserved.\",\n \"enum\": [\n \"high\",\n \"original\"\n ],\n \"type\": \"string\"\n },\n \"image_url\": {\n \"description\": \"Data URL for the loaded image.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"image_url\",\n \"detail\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "detail", "type": "[\"high\", \"original\"]", "required": true, "notes": "Image detail hint returned by view_image. Returns `high` for default resized behavior or `original` when original resolution is preserved." }, { "name": "image_url", "type": "\"string\"", "required": true, "notes": "Data URL for the loaded image." } ], "notes": "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.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/view_image_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/view_image.rs" ] }, { "name": "wait", "category": "core", "purpose": "Resume or terminate a yielded JavaScript exec cell.", "availability": "CodeMode/CodeModeOnly wrapper registration. Catalog can override description/parameters.", "aliases": [], "jobs": ["compose"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"cell_id\": {\n \"type\": \"string\"\n },\n \"yield_time_ms\": {\n \"type\": \"number\",\n \"description\": \"Default 10000 ms.\"\n },\n \"max_tokens\": {\n \"type\": \"number\",\n \"description\": \"Default 10000.\"\n },\n \"terminate\": {\n \"type\": \"boolean\",\n \"description\": \"Default false.\"\n }\n },\n \"required\": [\n \"cell_id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "cell_id", "type": "\"string\"", "required": true, "notes": "" }, { "name": "yield_time_ms", "type": "\"number\"", "required": false, "notes": "Default 10000 ms." }, { "name": "max_tokens", "type": "\"number\"", "required": false, "notes": "Default 10000." }, { "name": "terminate", "type": "\"boolean\"", "required": false, "notes": "Default false." } ], "notes": "Transcribed from source builder; no constructor execution for this snapshot. Catalog overrides may replace it.", "schema": { "type": "object", "properties": { "cell_id": { "type": "string" }, "yield_time_ms": { "type": "number", "description": "Default 10000 ms." }, "max_tokens": { "type": "number", "description": "Default 10000." }, "terminate": { "type": "boolean", "description": "Default false." } }, "required": ["cell_id"], "additionalProperties": false } }, "output": { "kind": "free-form", "definition": "New output, cell completion, or termination.", "fields": [], "notes": "Only valid for a yielded exec cell; not the unified-exec process session used by write_stdin." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/code_mode/wait_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/code_mode/wait_handler.rs" ] }, { "name": "wait_agent", "category": "core", "purpose": "Wait for a mailbox update from any live agent, including queued messages and final-status notifications.", "availability": "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.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"timeout_ms\": {\n \"type\": \"number\",\n \"description\": \"Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000.\"\n }\n },\n \"additionalProperties\": false\n}", "fields": [ { "name": "timeout_ms", "type": "\"number\"", "required": false, "notes": "Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "timeout_ms": { "type": "number", "description": "Timeout in milliseconds. Defaults to 30000, min 10000, max 3600000." } }, "additionalProperties": false } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"message\": {\n \"description\": \"Brief wait summary without the agent's final content, including any timeout adjustment.\",\n \"type\": \"string\"\n },\n \"timed_out\": {\n \"description\": \"Whether the wait call returned because no mailbox update arrived before the timeout.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"message\",\n \"timed_out\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "message", "type": "\"string\"", "required": true, "notes": "Brief wait summary without the agent's final content, including any timeout adjustment." }, { "name": "timed_out", "type": "\"boolean\"", "required": true, "notes": "Whether the wait call returned because no mailbox update arrived before the timeout." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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" } }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/multi_agents_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "wait_for_environment", "category": "core", "purpose": "Wait for an execution environment to become ready.", "availability": "DeferredExecutor feature; selected environment must be ready, starting or failed.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"environment_id\": {\n \"type\": \"string\",\n \"description\": \"\"\n }\n },\n \"required\": [\n \"environment_id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "environment_id", "type": "\"string\"", "required": true, "notes": "" } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "type": "object", "properties": { "environment_id": { "type": "string", "description": "" } }, "required": ["environment_id"], "additionalProperties": false } }, "output": { "kind": "implementation-shape", "definition": "{ environment_id: string, status: \"ready\" }", "fields": [], "notes": "JSON result from handler, not an advertised formal output schema. Failed or unknown environment returns a bounded model-facing error." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/wait_for_environment.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "web.run", "category": "extension", "purpose": "Execute standalone search, page, image, PDF, finance, weather, sports or time commands.", "availability": "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.", "aliases": [], "jobs": ["web"], "input": { "kind": "json-schema", "definition": "{\n \"properties\": {\n \"click\": {\n \"description\": \"Open links from previously opened pages.\",\n \"items\": {\n \"properties\": {\n \"id\": {\n \"description\": \"Numbered link id to open.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"ref_id\": {\n \"description\": \"Reference id containing the numbered link.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"ref_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"finance\": {\n \"description\": \"Look up prices for the given stock symbols.\",\n \"items\": {\n \"properties\": {\n \"market\": {\n \"description\": \"ISO 3166-1 alpha-3 country code, \\\"OTC\\\", or \\\"\\\" for cryptocurrency.\",\n \"type\": \"string\"\n },\n \"ticker\": {\n \"description\": \"Ticker symbol to look up.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"description\": \"Asset type to look up.\",\n \"enum\": [\n \"equity\",\n \"fund\",\n \"crypto\",\n \"index\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"ticker\",\n \"type\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"find\": {\n \"description\": \"Find text patterns in pages.\",\n \"items\": {\n \"properties\": {\n \"pattern\": {\n \"description\": \"Text pattern to find.\",\n \"type\": \"string\"\n },\n \"ref_id\": {\n \"description\": \"Reference id or URL to search within.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pattern\",\n \"ref_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"image_query\": {\n \"description\": \"Query the image search engine for a given list of queries.\",\n \"items\": {\n \"properties\": {\n \"domains\": {\n \"description\": \"Whether to filter by a specific list of domains.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"q\": {\n \"description\": \"Search query.\",\n \"type\": \"string\"\n },\n \"recency\": {\n \"description\": \"Whether to filter by recency, as a number of recent days.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"q\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"open\": {\n \"description\": \"Open pages by reference id or URL.\",\n \"items\": {\n \"properties\": {\n \"lineno\": {\n \"description\": \"Line number to position the page at.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"ref_id\": {\n \"description\": \"Reference id or URL to open.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"ref_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"response_length\": {\n \"description\": \"Set the length of the response to be returned.\",\n \"enum\": [\n \"short\",\n \"medium\",\n \"long\"\n ],\n \"type\": \"string\"\n },\n \"screenshot\": {\n \"description\": \"Take screenshots of PDF pages.\",\n \"items\": {\n \"properties\": {\n \"pageno\": {\n \"description\": \"Zero-indexed PDF page number.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"ref_id\": {\n \"description\": \"Reference id or URL to screenshot.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pageno\",\n \"ref_id\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"search_query\": {\n \"description\": \"Query the internet search engine for a given list of queries.\",\n \"items\": {\n \"properties\": {\n \"domains\": {\n \"description\": \"Whether to filter by a specific list of domains.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"type\": \"array\"\n },\n \"q\": {\n \"description\": \"Search query.\",\n \"type\": \"string\"\n },\n \"recency\": {\n \"description\": \"Whether to filter by recency, as a number of recent days.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"q\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"sports\": {\n \"description\": \"Look up sports schedules and standings.\",\n \"items\": {\n \"properties\": {\n \"date_from\": {\n \"description\": \"Start date in YYYY-MM-DD format.\",\n \"type\": \"string\"\n },\n \"date_to\": {\n \"description\": \"End date in YYYY-MM-DD format.\",\n \"type\": \"string\"\n },\n \"fn\": {\n \"description\": \"Sports function to call.\",\n \"enum\": [\n \"schedule\",\n \"standings\"\n ],\n \"type\": \"string\"\n },\n \"league\": {\n \"description\": \"League to look up.\",\n \"enum\": [\n \"nba\",\n \"wnba\",\n \"nfl\",\n \"nhl\",\n \"mlb\",\n \"epl\",\n \"ncaamb\",\n \"ncaawb\",\n \"ipl\"\n ],\n \"type\": \"string\"\n },\n \"locale\": {\n \"description\": \"Locale for the lookup.\",\n \"type\": \"string\"\n },\n \"num_games\": {\n \"description\": \"Number of games to return.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"opponent\": {\n \"description\": \"Opponent to use with `team` when narrowing the lookup.\",\n \"type\": \"string\"\n },\n \"team\": {\n \"description\": \"Team to look up, using the common 3 or 4 letter alias used in broadcasts.\",\n \"type\": \"string\"\n },\n \"tool\": {\n \"description\": \"Tool name for sports requests.\",\n \"enum\": [\n \"sports\"\n ],\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"fn\",\n \"league\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"time\": {\n \"description\": \"Get time for the given UTC offsets.\",\n \"items\": {\n \"properties\": {\n \"utc_offset\": {\n \"description\": \"UTC offset formatted like \\\"+03:00\\\".\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"utc_offset\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n },\n \"weather\": {\n \"description\": \"Look up weather forecasts.\",\n \"items\": {\n \"properties\": {\n \"duration\": {\n \"description\": \"Number of days to return. Defaults to 7.\",\n \"format\": \"uint64\",\n \"minimum\": 0.0,\n \"type\": \"integer\"\n },\n \"location\": {\n \"description\": \"Location in \\\"Country, Area, City\\\" format.\",\n \"type\": \"string\"\n },\n \"start\": {\n \"description\": \"Start date in YYYY-MM-DD format. Defaults to today.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"location\"\n ],\n \"type\": \"object\"\n },\n \"type\": \"array\"\n }\n },\n \"type\": \"object\"\n}", "fields": [ { "name": "click", "type": "\"array\"", "required": false, "notes": "Open links from previously opened pages." }, { "name": "finance", "type": "\"array\"", "required": false, "notes": "Look up prices for the given stock symbols." }, { "name": "find", "type": "\"array\"", "required": false, "notes": "Find text patterns in pages." }, { "name": "image_query", "type": "\"array\"", "required": false, "notes": "Query the image search engine for a given list of queries." }, { "name": "open", "type": "\"array\"", "required": false, "notes": "Open pages by reference id or URL." }, { "name": "response_length", "type": "[\"short\", \"medium\", \"long\"]", "required": false, "notes": "Set the length of the response to be returned." }, { "name": "screenshot", "type": "\"array\"", "required": false, "notes": "Take screenshots of PDF pages." }, { "name": "search_query", "type": "\"array\"", "required": false, "notes": "Query the internet search engine for a given list of queries." }, { "name": "sports", "type": "\"array\"", "required": false, "notes": "Look up sports schedules and standings." }, { "name": "time", "type": "\"array\"", "required": false, "notes": "Get time for the given UTC offsets." }, { "name": "weather", "type": "\"array\"", "required": false, "notes": "Look up weather forecasts." } ], "notes": "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.", "schema": { "properties": { "click": { "description": "Open links from previously opened pages.", "items": { "properties": { "id": { "description": "Numbered link id to open.", "format": "uint64", "minimum": 0.0, "type": "integer" }, "ref_id": { "description": "Reference id containing the numbered link.", "type": "string" } }, "required": ["id", "ref_id"], "type": "object" }, "type": "array" }, "finance": { "description": "Look up prices for the given stock symbols.", "items": { "properties": { "market": { "description": "ISO 3166-1 alpha-3 country code, \"OTC\", or \"\" for cryptocurrency.", "type": "string" }, "ticker": { "description": "Ticker symbol to look up.", "type": "string" }, "type": { "description": "Asset type to look up.", "enum": ["equity", "fund", "crypto", "index"], "type": "string" } }, "required": ["ticker", "type"], "type": "object" }, "type": "array" }, "find": { "description": "Find text patterns in pages.", "items": { "properties": { "pattern": { "description": "Text pattern to find.", "type": "string" }, "ref_id": { "description": "Reference id or URL to search within.", "type": "string" } }, "required": ["pattern", "ref_id"], "type": "object" }, "type": "array" }, "image_query": { "description": "Query the image search engine for a given list of queries.", "items": { "properties": { "domains": { "description": "Whether to filter by a specific list of domains.", "items": { "type": "string" }, "type": "array" }, "q": { "description": "Search query.", "type": "string" }, "recency": { "description": "Whether to filter by recency, as a number of recent days.", "format": "uint64", "minimum": 0.0, "type": "integer" } }, "required": ["q"], "type": "object" }, "type": "array" }, "open": { "description": "Open pages by reference id or URL.", "items": { "properties": { "lineno": { "description": "Line number to position the page at.", "format": "uint64", "minimum": 0.0, "type": "integer" }, "ref_id": { "description": "Reference id or URL to open.", "type": "string" } }, "required": ["ref_id"], "type": "object" }, "type": "array" }, "response_length": { "description": "Set the length of the response to be returned.", "enum": ["short", "medium", "long"], "type": "string" }, "screenshot": { "description": "Take screenshots of PDF pages.", "items": { "properties": { "pageno": { "description": "Zero-indexed PDF page number.", "format": "uint64", "minimum": 0.0, "type": "integer" }, "ref_id": { "description": "Reference id or URL to screenshot.", "type": "string" } }, "required": ["pageno", "ref_id"], "type": "object" }, "type": "array" }, "search_query": { "description": "Query the internet search engine for a given list of queries.", "items": { "properties": { "domains": { "description": "Whether to filter by a specific list of domains.", "items": { "type": "string" }, "type": "array" }, "q": { "description": "Search query.", "type": "string" }, "recency": { "description": "Whether to filter by recency, as a number of recent days.", "format": "uint64", "minimum": 0.0, "type": "integer" } }, "required": ["q"], "type": "object" }, "type": "array" }, "sports": { "description": "Look up sports schedules and standings.", "items": { "properties": { "date_from": { "description": "Start date in YYYY-MM-DD format.", "type": "string" }, "date_to": { "description": "End date in YYYY-MM-DD format.", "type": "string" }, "fn": { "description": "Sports function to call.", "enum": ["schedule", "standings"], "type": "string" }, "league": { "description": "League to look up.", "enum": [ "nba", "wnba", "nfl", "nhl", "mlb", "epl", "ncaamb", "ncaawb", "ipl" ], "type": "string" }, "locale": { "description": "Locale for the lookup.", "type": "string" }, "num_games": { "description": "Number of games to return.", "format": "uint64", "minimum": 0.0, "type": "integer" }, "opponent": { "description": "Opponent to use with `team` when narrowing the lookup.", "type": "string" }, "team": { "description": "Team to look up, using the common 3 or 4 letter alias used in broadcasts.", "type": "string" }, "tool": { "description": "Tool name for sports requests.", "enum": ["sports"], "type": "string" } }, "required": ["fn", "league"], "type": "object" }, "type": "array" }, "time": { "description": "Get time for the given UTC offsets.", "items": { "properties": { "utc_offset": { "description": "UTC offset formatted like \"+03:00\".", "type": "string" } }, "required": ["utc_offset"], "type": "object" }, "type": "array" }, "weather": { "description": "Look up weather forecasts.", "items": { "properties": { "duration": { "description": "Number of days to return. Defaults to 7.", "format": "uint64", "minimum": 0.0, "type": "integer" }, "location": { "description": "Location in \"Country, Area, City\" format.", "type": "string" }, "start": { "description": "Start date in YYYY-MM-DD format. Defaults to today.", "type": "string" } }, "required": ["location"], "type": "object" }, "type": "array" } }, "type": "object" } }, "output": { "kind": "free-form", "definition": "SearchOutput { output: String }", "fields": [], "notes": "Plaintext FunctionCallOutput content. Citations and domain-specific text are service outputs, not a stable result object schema." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/codex-api/src/search.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/web-search/src/schema.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/web-search/src/output.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/web-search/src/extension.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "web_search", "category": "hosted", "purpose": "Provider-hosted web search.", "availability": "Non-Responses-Lite provider supports hosted search; web_search_mode eligible; suppressed when standalone web.run is available.", "aliases": [], "jobs": ["web"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "ToolSpec::WebSearch config is a hosted-tool declaration, not a client function input schema; hosted model-call arguments are not established by this source." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "Hosted WebSearch output items/actions are service protocol; no local function-result schema." }, "lifecycle": [ "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/hosted_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/tools/src/tool_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs" ] }, { "name": "write_stdin", "category": "core", "purpose": "Writes characters to an existing unified exec session and returns recent output.", "availability": "ShellTool + UnifiedExec, enabled model shell type and tool policy; operates only on a live unified-exec session in this runtime.", "aliases": [], "jobs": ["processes"], "input": { "kind": "json-schema", "definition": "{\n \"type\": \"object\",\n \"properties\": {\n \"chars\": {\n \"type\": \"string\",\n \"description\": \"Bytes to write to stdin. Defaults to empty, which polls without writing.\"\n },\n \"max_output_tokens\": {\n \"type\": \"number\",\n \"description\": \"Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy.\"\n },\n \"session_id\": {\n \"type\": \"number\",\n \"description\": \"Identifier of the running unified exec session.\"\n },\n \"yield_time_ms\": {\n \"type\": \"number\",\n \"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.\"\n }\n },\n \"required\": [\n \"session_id\"\n ],\n \"additionalProperties\": false\n}", "fields": [ { "name": "chars", "type": "\"string\"", "required": false, "notes": "Bytes to write to stdin. Defaults to empty, which polls without writing." }, { "name": "max_output_tokens", "type": "\"number\"", "required": false, "notes": "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." }, { "name": "session_id", "type": "\"number\"", "required": true, "notes": "Identifier of the running unified exec session." }, { "name": "yield_time_ms", "type": "\"number\"", "required": false, "notes": "Wait before yielding output. Non-empty writes default to 250 ms and cap at 30000 ms; empty polls wait 5000-300000 ms by default." } ], "notes": "Source constructor JSON Schema. Defaults and bounds in descriptions are prose unless a validation keyword also encodes them.", "schema": { "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 } }, "output": { "kind": "json-schema", "definition": "{\n \"additionalProperties\": false,\n \"properties\": {\n \"chunk_id\": {\n \"description\": \"Chunk identifier included when the response reports one.\",\n \"type\": \"string\"\n },\n \"exit_code\": {\n \"description\": \"Process exit code when the command finished during this call.\",\n \"type\": \"number\"\n },\n \"original_token_count\": {\n \"description\": \"Approximate token count before output truncation.\",\n \"type\": \"number\"\n },\n \"output\": {\n \"description\": \"Command output text, possibly truncated.\",\n \"type\": \"string\"\n },\n \"session_id\": {\n \"description\": \"Session identifier to pass to write_stdin when the process is still running.\",\n \"type\": \"number\"\n },\n \"wall_time_seconds\": {\n \"description\": \"Elapsed wall time spent waiting for output in seconds.\",\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"wall_time_seconds\",\n \"output\"\n ],\n \"type\": \"object\"\n}", "fields": [ { "name": "chunk_id", "type": "\"string\"", "required": false, "notes": "Chunk identifier included when the response reports one." }, { "name": "exit_code", "type": "\"number\"", "required": false, "notes": "Process exit code when the command finished during this call." }, { "name": "original_token_count", "type": "\"number\"", "required": false, "notes": "Approximate token count before output truncation." }, { "name": "output", "type": "\"string\"", "required": true, "notes": "Command output text, possibly truncated." }, { "name": "session_id", "type": "\"number\"", "required": false, "notes": "Session identifier to pass to write_stdin when the process is still running." }, { "name": "wall_time_seconds", "type": "\"number\"", "required": true, "notes": "Elapsed wall time spent waiting for output in seconds." } ], "notes": "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.", "schema": { "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" } }, "lifecycle": [ "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.", "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." ], "references": [ "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/shell_spec.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/spec_plan.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/handlers/unified_exec/write_stdin.rs", "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/core/src/tools/context.rs" ] } ] }, { "harness": "claude-code", "variant": "2.1.310-tool-reference", "default": true, "verifiedAt": "2026-10-27", "observedVersion": "2.1.310", "method": "documentation", "sourceRevision": "@anthropic-ai/claude-agent-sdk@0.3.310", "surface": "cli-docs-and-agent-sdk-types", "evidence": [ "builtin-tools-claude-sdk-03310", "builtin-tools-claude-docs", "builtin-tools-claude-sdk-docs" ], "references": [ "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts", "https://code.claude.com/docs/en/tools-reference" ], "conditions": [ "Inventory is the union of the pinned source definitions and contributions, or dated publisher tool list and versioned SDK types. It is not the active tool set for every session.", "Formal output schemas describe success values where supplied; errors, approval, denial, cancellation and transport envelopes remain separate." ], "unknowns": [ "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." ], "details": { "baseline": { "cli": "2.1.310", "sdk": "0.3.310", "sdkIntegrity": "sha512-fo+sr+9Ks73P001f6XKRQlyzfIBAJMgXArLUkH5Tu98NikRDZeGtFQVj23d5/hj2ijpFgzffrr4fHywY9qUkoQ==", "docsSnapshot": "2026-10-27" }, "scope": "Complete accounting of the enumerated pinned-source or publisher-list/SDK union; unresolved contracts remain explicit.", "excluded": [ "Server-defined MCP tools (tools/list supplies their actual inputSchema/outputSchema).", "Desktop/browser/computer-use/plugin tools supplied by a separate host.", "App Server FileChange, CommandExecution and other protocol items; not function tool names.", "Observed weekly corpus payloads; no private transcript data imported." ], "mcpContract": { "input": { "kind": "published-typescript", "definition": "export interface McpInput {\n [k: string]: unknown;\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type McpOutput = string | {\n type: string;\n [k: string]: unknown;\n}[] | {\n [k: string]: unknown;\n};", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "boundary": "Generic MCP type placeholder; Mcp is not a callable built-in name. tools/list supplies each actual mcp__server__tool contract." } }, "support": { "inventory": "partial", "inputs": "partial", "results": "partial" }, "inventory": [ { "name": "Agent", "category": "core", "purpose": "Delegate work to a subagent.", "availability": "CLI/SDK tool; own context and subagent allow/deny limits. Named calls can address teammates; forks and remote isolation have separate gates.", "aliases": [ "Task (accepted compatibility alias; SDKSystemMessage init may still report Task, per publisher SDK docs)" ], "jobs": ["subagents"], "input": { "kind": "published-typescript", "definition": "export interface AgentInput {\n description: string;\n prompt: string;\n subagent_type?: string;\n model?: \"sonnet\" | \"opus\" | \"haiku\" | \"fable\";\n effort?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n run_in_background?: boolean;\n name?: string;\n team_name?: string;\n mode?: \"acceptEdits\" | \"auto\" | \"bypassPermissions\" | \"default\" | \"dontAsk\" | \"plan\";\n isolation?: \"worktree\" | \"remote\";\n}", "fields": [ { "name": "description", "type": "string", "required": true, "notes": "A short (3-5 word) description of the task" }, { "name": "prompt", "type": "string", "required": true, "notes": "The task for the agent to perform" }, { "name": "subagent_type", "type": "string", "required": false, "notes": "The type of specialized agent to use for this task" }, { "name": "model", "type": "\"sonnet\" | \"opus\" | \"haiku\" | \"fable\"", "required": false, "notes": "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." }, { "name": "effort", "type": "\"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\"", "required": false, "notes": "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." }, { "name": "run_in_background", "type": "boolean", "required": false, "notes": "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": "name", "type": "string", "required": false, "notes": "Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running." }, { "name": "team_name", "type": "string", "required": false, "notes": "Deprecated; ignored. The session has a single implicit team." }, { "name": "mode", "type": "\"acceptEdits\" | \"auto\" | \"bypassPermissions\" | \"default\" | \"dontAsk\" | \"plan\"", "required": false, "notes": "Deprecated; ignored. Subagents inherit the parent session's permission mode; agent-definition frontmatter may override it." }, { "name": "isolation", "type": "\"worktree\" | \"remote\"", "required": false, "notes": "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)." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type AgentOutput = {\n agentId: string;\n agentType?: string;\n content: {\n type: \"text\";\n text: string;\n citations?: unknown[] | null;\n }[];\n resolvedModel?: string;\n modelsUsed?: string[];\n totalToolUseCount: number;\n totalDurationMs: number;\n totalTokens: number;\n usage: {\n input_tokens: number;\n output_tokens: number;\n cache_creation_input_tokens: number | null;\n cache_read_input_tokens: number | null;\n server_tool_use: {\n web_search_requests: number;\n web_fetch_requests: number;\n } | null;\n service_tier: string | null;\n cache_creation: {\n ephemeral_1h_input_tokens: number;\n ephemeral_5m_input_tokens: number;\n } | null;\n inference_geo?: string | null;\n speed?: string | null;\n iterations?: unknown;\n output_tokens_details?: {\n thinking_tokens?: number | null;\n } | null;\n fallback_credit?: unknown;\n };\n toolStats?: {\n readCount: number;\n searchCount: number;\n bashCount: number;\n editFileCount: number;\n linesAdded: number;\n linesRemoved: number;\n otherToolCount: number;\n frameCount?: number;\n };\n status: \"completed\";\n prompt: string;\n worktreePath?: string;\n worktreeBranch?: string;\n} | {\n status: \"async_launched\";\n isAsync?: true;\n agentId: string;\n description: string;\n resolvedModel?: string;\n modelsUsed?: string[];\n prompt: string;\n outputFile: string;\n canReadOutputFile?: boolean;\n} | {\n status: \"remote_launched\";\n taskId: string;\n sessionUrl: string;\n description: string;\n prompt: string;\n outputFile: string;\n};", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts", "https://code.claude.com/docs/en/agent-sdk/typescript" ] }, { "name": "Artifact", "category": "core", "purpose": "Publish a file as an artifact.", "availability": "Subscriber plan and /login; publication prompts for permission. Hosted implementation unavailable.", "aliases": [], "jobs": ["deliver"], "input": { "kind": "published-typescript", "definition": "export interface ArtifactInput {\n action?: \"publish\" | \"list\" | \"read\" | \"list_types\" | \"watch\" | \"unwatch\" | \"status\" | \"upload_asset\" | \"list_assets\" | \"read_asset\" | \"delete_asset\" | \"pin\" | \"unpin\";\n file_path?: string;\n favicon?: string;\n icon?: string;\n limit?: number;\n scope?: \"mine\" | \"shared\" | \"all\";\n title?: string;\n description?: string;\n label?: string;\n url?: string;\n prompt?: string;\n force?: boolean;\n pin?: boolean;\n out_dir?: string;\n file_paths?: [\n string,\n ...string[]\n ];\n asset_id?: string;\n after?: string;\n capabilities?: {\n [k: string]: unknown;\n };\n contract?: \"latest\" | string;\n}", "fields": [ { "name": "action", "type": "\"publish\" | \"list\" | \"read\" | \"list_types\" | \"watch\" | \"unwatch\" | \"status\" | \"upload_asset\" | \"list_assets\" | \"read_asset\" | \"delete_asset\" | \"pin\" | \"unpin\"", "required": false, "notes": "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." }, { "name": "file_path", "type": "string", "required": false, "notes": "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 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." }, { "name": "favicon", "type": "string", "required": false, "notes": "Deprecated; omit it. Use `icon`." }, { "name": "icon", "type": "string", "required": false, "notes": "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." }, { "name": "limit", "type": "number", "required": false, "notes": "list only: maximum artifacts to return (default 25)." }, { "name": "scope", "type": "\"mine\" | \"shared\" | \"all\"", "required": false, "notes": "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'." }, { "name": "title", "type": "string", "required": false, "notes": "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." }, { "name": "description", "type": "string", "required": false, "notes": "One-sentence subtitle shown on the gallery card. Say what the page is or does." }, { "name": "label", "type": "string", "required": false, "notes": "A short name for this publish, max 60 chars (e.g. \"Draft to legal\"). Optional — a few words, not a description." }, { "name": "url", "type": "string", "required": false, "notes": "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." }, { "name": "prompt", "type": "string", "required": false, "notes": "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." }, { "name": "force", "type": "boolean", "required": false, "notes": "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." }, { "name": "pin", "type": "boolean", "required": false, "notes": "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)." }, { "name": "out_dir", "type": "string", "required": false, "notes": "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." }, { "name": "file_paths", "type": "[\n string,\n ...string[]\n]", "required": false, "notes": "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`." }, { "name": "asset_id", "type": "string", "required": false, "notes": "read_asset and delete_asset: the asset's id (32 hex characters), from a list_assets or upload_asset result." }, { "name": "after", "type": "string", "required": false, "notes": "list_assets only: the `next` value from a previous list_assets result, to continue that listing." }, { "name": "capabilities", "type": "{\n [k: string]: unknown;\n}", "required": false, "notes": "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." }, { "name": "contract", "type": "\"latest\" | string", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type ArtifactOutput = {\n url: string;\n path: string;\n artifact_id?: string;\n title?: string;\n version?: string;\n capabilities?: unknown;\n stored?: {\n contract: string;\n preferredContract?: string;\n capabilities?: {\n [k: string]: unknown;\n };\n carried?: boolean;\n read?: string;\n };\n warnings?: string[];\n publishesRemaining?: number;\n publishesResetAt?: number;\n contract?: string;\n updated?: boolean;\n owned?: boolean;\n icon?: string;\n faviconSent?: true;\n iconDropped?: true;\n audience?: string;\n seq?: number;\n unchanged?: true;\n liveSubscription?: string;\n pinned?: boolean;\n} | {\n artifacts: {\n title: string;\n url: string;\n favicon?: string;\n updatedAt?: string;\n rel?: \"mine\" | \"shared\";\n external?: true;\n role?: \"editor\" | \"commenter\" | \"reader\" | \"viewer\";\n pinned?: boolean;\n }[];\n truncated?: boolean;\n total?: number;\n total_at_least?: true;\n pins_enabled?: boolean;\n scope?: \"shared\" | \"all\";\n external_listed?: true;\n} | {\n read: {\n url: string;\n bytes: number;\n code: number;\n codeText: string;\n result: string;\n durationMs: number;\n title?: string;\n };\n owned?: boolean;\n artifactRead?: {\n slug: string;\n ver?: string;\n seeded?: false;\n };\n} | {\n watch: {\n url: string;\n watching: boolean;\n outcome: string;\n reason?: string;\n durable_skip_reason?: string;\n task_id?: string;\n since?: number;\n token_expires_at?: number;\n rail?: string;\n trigger_id?: string;\n durable_since?: string;\n status?: number;\n detail?: string;\n note?: string;\n events?: string[];\n };\n} | {\n unwatch: {\n url: string;\n was_watching: boolean;\n };\n} | {\n watches: ({\n url: string;\n task_id: string;\n since: number;\n explicit: boolean;\n connected: boolean;\n connecting?: boolean;\n token_expires_at: number;\n armed_via?: string;\n } | {\n url: string;\n rail: \"durable_wake\";\n trigger_id: string;\n since: string;\n events?: string[];\n restored?: boolean;\n } | {\n url: string;\n rail: \"live_stopped\";\n since?: number;\n explicit?: boolean;\n armed_via?: string;\n stop_kind: string;\n })[];\n filter_url?: string;\n arms?: {\n url: string;\n rail?: string;\n state: string;\n reconnect?: boolean;\n failures?: number;\n max_failures?: number;\n next_in_s?: number;\n last_failure?: string;\n reason?: string;\n detail?: string;\n server_message?: string;\n at?: number;\n }[];\n} | {\n written?: {\n url: string;\n };\n owned?: boolean;\n asset_upload: {\n id: string;\n url: string;\n size_bytes: number;\n content_type: string;\n sha256?: string;\n file_name: string;\n };\n} | {\n written?: {\n url: string;\n };\n owned?: boolean;\n asset_uploads: {\n url: string;\n results: [\n ({\n file_path: string;\n status: \"uploaded\";\n id: string;\n url: string;\n size_bytes: number;\n content_type: string;\n sha256?: string;\n file_name: string;\n } | {\n file_path: string;\n status: \"failed\" | \"not_attempted\";\n reason: string;\n message: string;\n may_be_stored?: true;\n }),\n ...({\n file_path: string;\n status: \"uploaded\";\n id: string;\n url: string;\n size_bytes: number;\n content_type: string;\n sha256?: string;\n file_name: string;\n } | {\n file_path: string;\n status: \"failed\" | \"not_attempted\";\n reason: string;\n message: string;\n may_be_stored?: true;\n })[]\n ];\n };\n} | {\n asset_list: {\n url: string;\n assets: {\n id: string;\n url: string;\n content_type: string;\n size_bytes: number;\n sha256?: string;\n created_at: string;\n }[];\n usage: {\n files: number;\n bytes: number;\n max_files: number;\n max_bytes: number;\n };\n next?: string;\n cowritten?: true;\n outside_writer?: true;\n };\n} | {\n asset_read: {\n id: string;\n path: string;\n size_bytes: number;\n content_type: string;\n sha256: string;\n cowritten?: true;\n outside_writer?: true;\n public_read?: true;\n foreign?: true;\n };\n} | {\n written?: {\n url: string;\n };\n owned?: boolean;\n asset_delete: {\n id: string;\n deleted: boolean;\n };\n} | {\n pin: {\n action: \"pin\" | \"unpin\";\n url: string;\n pinned: boolean;\n title?: string;\n };\n};", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "AskUserQuestion", "category": "core", "purpose": "Collect user choices.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["ask-user"], "input": { "kind": "published-typescript", "definition": "export interface AskUserQuestionInput {\n questions: [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n ] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n ] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n ] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n ];\n answers?: {\n [k: string]: string;\n };\n annotations?: {\n [k: string]: {\n preview?: string;\n notes?: string;\n };\n };\n metadata?: {\n source?: string;\n };\n}", "fields": [ { "name": "questions", "type": "[\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n] | [\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n },\n {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }\n]", "required": true, "notes": "Questions to ask the user (1-4 questions)" }, { "name": "answers", "type": "{\n [k: string]: string;\n}", "required": false, "notes": "User answers collected by the permission component" }, { "name": "annotations", "type": "{\n [k: string]: {\n preview?: string;\n notes?: string;\n };\n}", "required": false, "notes": "Optional per-question annotations from the user (e.g., notes on preview selections). Keyed by question text." }, { "name": "metadata", "type": "{\n source?: string;\n}", "required": false, "notes": "Optional metadata for tracking and analytics purposes. Not displayed to user." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface AskUserQuestionOutput {\n questions: {\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n }[];\n answers: {\n [k: string]: string;\n };\n response?: string;\n annotations?: {\n [k: string]: {\n preview?: string;\n notes?: string;\n };\n };\n afkTimeoutMs?: number;\n}", "fields": [ { "name": "questions", "type": "{\n question: string;\n header: string;\n options: [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ] | [\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n },\n {\n label: string;\n description: string;\n preview?: string;\n }\n ];\n multiSelect: boolean;\n}[]", "required": true, "notes": "The questions that were asked" }, { "name": "answers", "type": "{\n [k: string]: string;\n}", "required": true, "notes": "The answers provided by the user (question text -> answer string; multi-select answers are comma-separated)" }, { "name": "response", "type": "string", "required": false, "notes": "Freeform text the user typed instead of selecting a structured option" }, { "name": "annotations", "type": "{\n [k: string]: {\n preview?: string;\n notes?: string;\n };\n}", "required": false, "notes": "Optional per-question annotations from the user (e.g., notes on preview selections). Keyed by question text." }, { "name": "afkTimeoutMs", "type": "number", "required": false, "notes": "Set when the dialog auto-resolved after this many milliseconds of idle (user away from keyboard). Absent on every human-resolved path." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Bash", "category": "core", "purpose": "Run a shell command.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["shell", "processes"], "input": { "kind": "published-typescript", "definition": "export interface BashInput {\n command: string;\n timeout?: number;\n description?: string;\n run_in_background?: boolean;\n dangerouslyDisableSandbox?: boolean;\n}", "fields": [ { "name": "command", "type": "string", "required": true, "notes": "The command to execute" }, { "name": "timeout", "type": "number", "required": false, "notes": "Optional timeout in milliseconds (max 600000 for a foreground command)" }, { "name": "description", "type": "string", "required": false, "notes": "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.\n\nSay 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.\n\nFor simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):\n- ls → \"List files in current directory\"\n- git status → \"Show working tree status\"\n- npm install → \"Install package dependencies\"\n\nFor commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:\n- find . -name \"*.tmp\" -exec rm {} \\; → \"Find and delete all .tmp files recursively\"\n- git reset --hard origin/main → \"Discard all local changes and match remote main\"\n- curl -s url | jq '.data[]' → \"Fetch JSON from URL and extract data array elements\"" }, { "name": "run_in_background", "type": "boolean", "required": false, "notes": "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)." }, { "name": "dangerouslyDisableSandbox", "type": "boolean", "required": false, "notes": "Set this to true to dangerously override sandbox mode and run commands without sandboxing." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface BashOutput {\n stdout: string;\n stderr: string;\n rawOutputPath?: string;\n interrupted: boolean;\n isImage?: boolean;\n backgroundTaskId?: string;\n backgroundedByUser?: boolean;\n timedOutAfterMs?: number;\n backgroundCwdHint?: string;\n backgroundEndsWithFinalResponse?: true;\n dangerouslyDisableSandbox?: boolean;\n returnCodeInterpretation?: string;\n noOutputExpected?: boolean;\n structuredContent?: unknown[];\n persistedOutputPath?: string;\n persistedOutputSize?: number;\n staleReadFileStateHint?: string;\n ghRateLimitHint?: string;\n gitOperation?: {\n commit?: {\n sha: string;\n kind: \"committed\" | \"amended\" | \"cherry-picked\";\n branch?: string;\n };\n push?: {\n branch: string;\n };\n branch?: {\n ref: string;\n action: \"merged\" | \"rebased\";\n };\n pr?: {\n number: number;\n url?: string;\n action: \"created\" | \"edited\" | \"merged\" | \"commented\" | \"closed\" | \"reopened\" | \"ready\" | \"draft\" | \"auto-merge-enabled\" | \"auto-merge-disabled\";\n };\n };\n}", "fields": [ { "name": "stdout", "type": "string", "required": true, "notes": "The standard output of the command" }, { "name": "stderr", "type": "string", "required": true, "notes": "The standard error output of the command" }, { "name": "rawOutputPath", "type": "string", "required": false, "notes": "Path to raw output file for large MCP tool outputs" }, { "name": "interrupted", "type": "boolean", "required": true, "notes": "Whether the command was interrupted" }, { "name": "isImage", "type": "boolean", "required": false, "notes": "Flag to indicate if stdout contains image data" }, { "name": "backgroundTaskId", "type": "string", "required": false, "notes": "ID of the background task if command is running in background" }, { "name": "backgroundedByUser", "type": "boolean", "required": false, "notes": "True if the user manually backgrounded the command with Ctrl+B" }, { "name": "timedOutAfterMs", "type": "number", "required": false, "notes": "Set when the command hit its timeout and was auto-backgrounded; the timeout value in ms" }, { "name": "backgroundCwdHint", "type": "string", "required": false, "notes": "Model-facing note that the session cwd was not changed by a backgrounded command containing a directory-change builtin (cd/pushd/popd/chdir)" }, { "name": "backgroundEndsWithFinalResponse", "type": "true", "required": false, "notes": "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" }, { "name": "dangerouslyDisableSandbox", "type": "boolean", "required": false, "notes": "Flag to indicate if sandbox mode was overridden" }, { "name": "returnCodeInterpretation", "type": "string", "required": false, "notes": "Semantic interpretation for non-error exit codes with special meaning" }, { "name": "noOutputExpected", "type": "boolean", "required": false, "notes": "Whether the command is expected to produce no output on success" }, { "name": "structuredContent", "type": "unknown[]", "required": false, "notes": "Structured content blocks" }, { "name": "persistedOutputPath", "type": "string", "required": false, "notes": "Path to the persisted full output in tool-results dir (set when output is too large for inline)" }, { "name": "persistedOutputSize", "type": "number", "required": false, "notes": "Total size of the output in bytes (set when output is too large for inline)" }, { "name": "staleReadFileStateHint", "type": "string", "required": false, "notes": "Model-facing note listing readFileState entries whose mtime bumped during this command (set when WRITE_COMMAND_MARKERS matches)" }, { "name": "ghRateLimitHint", "type": "string", "required": false, "notes": "Model-facing system-reminder appended when a gh command reports a GitHub API rate-limit error" }, { "name": "gitOperation", "type": "{\n commit?: {\n sha: string;\n kind: \"committed\" | \"amended\" | \"cherry-picked\";\n branch?: string;\n };\n push?: {\n branch: string;\n };\n branch?: {\n ref: string;\n action: \"merged\" | \"rebased\";\n };\n pr?: {\n number: number;\n url?: string;\n action: \"created\" | \"edited\" | \"merged\" | \"commented\" | \"closed\" | \"reopened\" | \"ready\" | \"draft\" | \"auto-merge-enabled\" | \"auto-merge-disabled\";\n };\n}", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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.", "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ClaudeDesign", "category": "sdk-only", "purpose": "Publisher SDK contract for ClaudeDesign.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "jobs": ["deliver"], "input": { "kind": "published-typescript", "definition": "export interface ClaudeDesignInput {\n operation: string;\n arguments: {\n [k: string]: unknown;\n };\n}", "fields": [ { "name": "operation", "type": "string", "required": true, "notes": "Claude Design action to perform. Call with \"list\" first to discover the available operations and their argument schemas." }, { "name": "arguments", "type": "{\n [k: string]: unknown;\n}", "required": true, "notes": "Action input object (server-validated). Pass {} for operations that take no input." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ClaudeDesignOutput {\n operation: string;\n content: {\n [k: string]: unknown;\n }[];\n isError?: boolean;\n}", "fields": [ { "name": "operation", "type": "string", "required": true, "notes": "" }, { "name": "content", "type": "{\n [k: string]: unknown;\n}[]", "required": true, "notes": "" }, { "name": "isError", "type": "boolean", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "CronCreate", "category": "core", "purpose": "Create a session schedule.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "published-typescript", "definition": "export interface CronCreateInput {\n cron: string;\n prompt: string;\n recurring?: boolean;\n durable?: boolean;\n}", "fields": [ { "name": "cron", "type": "string", "required": true, "notes": "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)." }, { "name": "prompt", "type": "string", "required": true, "notes": "The prompt to enqueue at each fire time." }, { "name": "recurring", "type": "boolean", "required": false, "notes": "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." }, { "name": "durable", "type": "boolean", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface CronCreateOutput {\n id: string;\n humanSchedule: string;\n recurring: boolean;\n durable?: boolean;\n nextFireAt?: number;\n}", "fields": [ { "name": "id", "type": "string", "required": true, "notes": "" }, { "name": "humanSchedule", "type": "string", "required": true, "notes": "" }, { "name": "recurring", "type": "boolean", "required": true, "notes": "" }, { "name": "durable", "type": "boolean", "required": false, "notes": "" }, { "name": "nextFireAt", "type": "number", "required": false, "notes": "Epoch ms of the job's next run, the scheduler's per-job offset included" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "CronDelete", "category": "core", "purpose": "Delete a session schedule.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "published-typescript", "definition": "export interface CronDeleteInput {\n id: string;\n}", "fields": [ { "name": "id", "type": "string", "required": true, "notes": "Job ID returned by CronCreate." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface CronDeleteOutput {\n id: string;\n}", "fields": [ { "name": "id", "type": "string", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "CronList", "category": "core", "purpose": "List session schedules.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "published-typescript", "definition": "export interface CronListInput {\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface CronListOutput {\n jobs: {\n id: string;\n cron: string;\n humanSchedule: string;\n prompt: string;\n recurring?: boolean;\n durable?: boolean;\n nextFireAt?: number;\n }[];\n}", "fields": [ { "name": "jobs", "type": "{\n id: string;\n cron: string;\n humanSchedule: string;\n prompt: string;\n recurring?: boolean;\n durable?: boolean;\n nextFireAt?: number;\n}[]", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Edit", "category": "core", "purpose": "Replace matching file text.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": ["FileEdit (SDK type prefix, not a callable alias)"], "jobs": ["edit"], "input": { "kind": "published-typescript", "definition": "export interface FileEditInput {\n file_path: string;\n old_string: string;\n new_string: string;\n replace_all?: boolean;\n}", "fields": [ { "name": "file_path", "type": "string", "required": true, "notes": "The absolute path to the file to modify" }, { "name": "old_string", "type": "string", "required": true, "notes": "The text to replace" }, { "name": "new_string", "type": "string", "required": true, "notes": "The text to replace it with (must be different from old_string)" }, { "name": "replace_all", "type": "boolean", "required": false, "notes": "Replace all occurrences of old_string (default false)" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface FileEditOutput {\n filePath: string;\n oldString: string;\n newString: string;\n originalFile: string | null;\n structuredPatch: {\n oldStart: number;\n oldLines: number;\n newStart: number;\n newLines: number;\n lines: string[];\n }[];\n userModified: boolean;\n replaceAll: boolean;\n gitDiff?: {\n filename: string;\n status: \"modified\" | \"added\";\n additions: number;\n deletions: number;\n changes: number;\n patch: string;\n repository?: string | null;\n };\n staged?: boolean;\n}", "fields": [ { "name": "filePath", "type": "string", "required": true, "notes": "The file path that was edited" }, { "name": "oldString", "type": "string", "required": true, "notes": "The original string that was replaced" }, { "name": "newString", "type": "string", "required": true, "notes": "The new string that replaced it" }, { "name": "originalFile", "type": "string | null", "required": true, "notes": "The original file contents before editing" }, { "name": "structuredPatch", "type": "{\n oldStart: number;\n oldLines: number;\n newStart: number;\n newLines: number;\n lines: string[];\n}[]", "required": true, "notes": "Diff patch showing the changes" }, { "name": "userModified", "type": "boolean", "required": true, "notes": "Whether the user modified the proposed changes" }, { "name": "replaceAll", "type": "boolean", "required": true, "notes": "Whether all occurrences were replaced" }, { "name": "gitDiff", "type": "{\n filename: string;\n status: \"modified\" | \"added\";\n additions: number;\n deletions: number;\n changes: number;\n patch: string;\n repository?: string | null;\n}", "required": false, "notes": "" }, { "name": "staged", "type": "boolean", "required": false, "notes": "True when the edit was held for the machine owner to review instead of written; the file is unchanged" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "EndConversation", "category": "core", "purpose": "End the conversation.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "EnterPlanMode", "category": "core", "purpose": "Enter planning mode.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface EnterPlanModeInput {\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface EnterPlanModeOutput {\n message: string;\n}", "fields": [ { "name": "message", "type": "string", "required": true, "notes": "Confirmation that plan mode was entered" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "EnterWorktree", "category": "core", "purpose": "Enter a Git worktree.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "published-typescript", "definition": "export interface EnterWorktreeInput {\n name?: string;\n path?: string;\n}", "fields": [ { "name": "name", "type": "string", "required": false, "notes": "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`." }, { "name": "path", "type": "string", "required": false, "notes": "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`." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface EnterWorktreeOutput {\n worktreePath: string;\n worktreeBranch?: string;\n message: string;\n}", "fields": [ { "name": "worktreePath", "type": "string", "required": true, "notes": "" }, { "name": "worktreeBranch", "type": "string", "required": false, "notes": "" }, { "name": "message", "type": "string", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ExitPlanMode", "category": "core", "purpose": "Submit a plan and leave planning mode.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface ExitPlanModeInput {\n allowedPrompts?: {\n tool: \"Bash\";\n prompt: string;\n }[];\n [k: string]: unknown;\n}", "fields": [ { "name": "allowedPrompts", "type": "{\n tool: \"Bash\";\n prompt: string;\n}[]", "required": false, "notes": "Deprecated: no longer used." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ExitPlanModeOutput {\n plan: string | null;\n isAgent: boolean;\n filePath?: string;\n hasTaskTool?: boolean;\n planWasEdited?: boolean;\n awaitingLeaderApproval?: boolean;\n requestId?: string;\n}", "fields": [ { "name": "plan", "type": "string | null", "required": true, "notes": "The plan that was presented to the user" }, { "name": "isAgent", "type": "boolean", "required": true, "notes": "" }, { "name": "filePath", "type": "string", "required": false, "notes": "The file path where the plan was saved" }, { "name": "hasTaskTool", "type": "boolean", "required": false, "notes": "Whether the Agent tool is available in the current context" }, { "name": "planWasEdited", "type": "boolean", "required": false, "notes": "True when the user edited the plan (CCR web UI or Ctrl+G); determines whether the plan is echoed back in tool_result" }, { "name": "awaitingLeaderApproval", "type": "boolean", "required": false, "notes": "When true, the teammate has sent a plan approval request to the team leader" }, { "name": "requestId", "type": "string", "required": false, "notes": "Unique identifier for the plan approval request" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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.", "Plan approval is a permission interaction; a normal tool result does not itself prove approval or subsequent execution." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ExitWorktree", "category": "core", "purpose": "Leave the session worktree.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["workspace"], "input": { "kind": "published-typescript", "definition": "export interface ExitWorktreeInput {\n action: \"keep\" | \"remove\";\n discard_changes?: boolean;\n}", "fields": [ { "name": "action", "type": "\"keep\" | \"remove\"", "required": true, "notes": "\"keep\" leaves the worktree and branch on disk; \"remove\" deletes both." }, { "name": "discard_changes", "type": "boolean", "required": false, "notes": "Required true when action is \"remove\" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ExitWorktreeOutput {\n action: \"keep\" | \"remove\";\n originalCwd: string;\n worktreePath: string;\n worktreeBranch?: string;\n tmuxSessionName?: string;\n discardedFiles?: number;\n discardedCommits?: number;\n message: string;\n}", "fields": [ { "name": "action", "type": "\"keep\" | \"remove\"", "required": true, "notes": "" }, { "name": "originalCwd", "type": "string", "required": true, "notes": "" }, { "name": "worktreePath", "type": "string", "required": true, "notes": "" }, { "name": "worktreeBranch", "type": "string", "required": false, "notes": "" }, { "name": "tmuxSessionName", "type": "string", "required": false, "notes": "" }, { "name": "discardedFiles", "type": "number", "required": false, "notes": "" }, { "name": "discardedCommits", "type": "number", "required": false, "notes": "" }, { "name": "message", "type": "string", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Glob", "category": "core", "purpose": "Find paths by glob.", "availability": "Absent by default on macOS/Linux/WSL in current docs; may be restored with tool configuration. SDK types do not imply default exposure.", "aliases": [], "jobs": ["search"], "input": { "kind": "published-typescript", "definition": "export interface GlobInput {\n pattern: string;\n path?: string;\n}", "fields": [ { "name": "pattern", "type": "string", "required": true, "notes": "The glob pattern to match files against" }, { "name": "path", "type": "string", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface GlobOutput {\n durationMs: number;\n numFiles: number;\n filenames: string[];\n truncated: boolean;\n totalMatches?: number;\n countIsComplete?: boolean;\n}", "fields": [ { "name": "durationMs", "type": "number", "required": true, "notes": "Time taken to execute the search in milliseconds" }, { "name": "numFiles", "type": "number", "required": true, "notes": "Number of file paths returned (after any truncation)" }, { "name": "filenames", "type": "string[]", "required": true, "notes": "Array of file paths that match the pattern" }, { "name": "truncated", "type": "boolean", "required": true, "notes": "Whether results were truncated (limited to 100 files)" }, { "name": "totalMatches", "type": "number", "required": false, "notes": "Total number of matching files before truncation. A lower bound when countIsComplete is false. Absent on results persisted by CLI versions predating this field." }, { "name": "countIsComplete", "type": "boolean", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Grep", "category": "core", "purpose": "Search file contents.", "availability": "Absent by default on macOS/Linux/WSL in current docs; may be restored with tool configuration. SDK types do not imply default exposure.", "aliases": [], "jobs": ["search"], "input": { "kind": "published-typescript", "definition": "export interface GrepInput {\n pattern: string;\n path?: string;\n glob?: string;\n output_mode?: \"content\" | \"files_with_matches\" | \"count\";\n \"-B\"?: number;\n \"-A\"?: number;\n \"-C\"?: number;\n context?: number;\n \"-n\"?: boolean;\n \"-i\"?: boolean;\n \"-o\"?: boolean;\n type?: string;\n head_limit?: number;\n offset?: number;\n multiline?: boolean;\n}", "fields": [ { "name": "pattern", "type": "string", "required": true, "notes": "The regular expression pattern to search for in file contents" }, { "name": "path", "type": "string", "required": false, "notes": "File or directory to search in (rg PATH). Defaults to current working directory." }, { "name": "glob", "type": "string", "required": false, "notes": "Glob pattern to filter files (e.g. \"*.js\", \"*.{ts,tsx}\") - maps to rg --glob" }, { "name": "output_mode", "type": "\"content\" | \"files_with_matches\" | \"count\"", "required": false, "notes": "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\"." }, { "name": "-B", "type": "number", "required": false, "notes": "Number of lines to show before each match (rg -B). Requires output_mode: \"content\", ignored otherwise." }, { "name": "-A", "type": "number", "required": false, "notes": "Number of lines to show after each match (rg -A). Requires output_mode: \"content\", ignored otherwise." }, { "name": "-C", "type": "number", "required": false, "notes": "Alias for context." }, { "name": "context", "type": "number", "required": false, "notes": "Number of lines to show before and after each match (rg -C). Requires output_mode: \"content\", ignored otherwise." }, { "name": "-n", "type": "boolean", "required": false, "notes": "Show line numbers in output (rg -n). Requires output_mode: \"content\", ignored otherwise. Defaults to true." }, { "name": "-i", "type": "boolean", "required": false, "notes": "Case insensitive search (rg -i)" }, { "name": "-o", "type": "boolean", "required": false, "notes": "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." }, { "name": "type", "type": "string", "required": false, "notes": "File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types." }, { "name": "head_limit", "type": "number", "required": false, "notes": "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)." }, { "name": "offset", "type": "number", "required": false, "notes": "Skip first N lines/entries before applying head_limit, equivalent to \"| tail -n +N | head -N\". Works across all output modes. Defaults to 0." }, { "name": "multiline", "type": "boolean", "required": false, "notes": "Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface GrepOutput {\n mode?: \"content\" | \"files_with_matches\" | \"count\";\n numFiles: number;\n filenames: string[];\n content?: string;\n numLines?: number;\n numMatches?: number;\n totalFiles?: number;\n totalLines?: number;\n appliedLimit?: number;\n appliedOffset?: number;\n}", "fields": [ { "name": "mode", "type": "\"content\" | \"files_with_matches\" | \"count\"", "required": false, "notes": "" }, { "name": "numFiles", "type": "number", "required": true, "notes": "" }, { "name": "filenames", "type": "string[]", "required": true, "notes": "" }, { "name": "content", "type": "string", "required": false, "notes": "" }, { "name": "numLines", "type": "number", "required": false, "notes": "" }, { "name": "numMatches", "type": "number", "required": false, "notes": "" }, { "name": "totalFiles", "type": "number", "required": false, "notes": "" }, { "name": "totalLines", "type": "number", "required": false, "notes": "" }, { "name": "appliedLimit", "type": "number", "required": false, "notes": "" }, { "name": "appliedOffset", "type": "number", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "LSP", "category": "core", "purpose": "Query language-server intelligence.", "availability": "Requires configured language-server support; editor/plugin/provider dependent.", "aliases": [], "jobs": ["search"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "ListAgents", "category": "core", "purpose": "List reachable agents.", "availability": "Cross-session messaging enabled; CLI >=2.1.224; teammate/self rows >=2.1.239.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "ListMcpResourcesTool", "category": "mcp-client", "purpose": "List connected MCP resources.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "published-typescript", "definition": "export interface ListMcpResourcesInput {\n server?: string;\n}", "fields": [ { "name": "server", "type": "string", "required": false, "notes": "Optional server name to filter resources by" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type ListMcpResourcesOutput = {\n uri: string;\n name: string;\n mimeType?: string;\n description?: string;\n server: string;\n}[];", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Monitor", "category": "core", "purpose": "Watch command or WebSocket events.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["processes"], "input": { "kind": "published-typescript", "definition": "export interface MonitorInput {\n description: string;\n timeout_ms: number;\n command?: string;\n ws?: {\n url: string;\n protocols?: string[];\n };\n}", "fields": [ { "name": "description", "type": "string", "required": true, "notes": "Short human-readable description of what you are monitoring (shown in notifications)." }, { "name": "timeout_ms", "type": "number", "required": true, "notes": "Kill the monitor after this deadline. Default 300000ms. Deadlines above 1800000ms are capped to 1800000ms. You are notified at expiry and can re-arm." }, { "name": "command", "type": "string", "required": false, "notes": "Shell command or script. Each stdout line is an event; exit ends the watch." }, { "name": "ws", "type": "{\n url: string;\n protocols?: string[];\n}", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface MonitorOutput {\n taskId: string;\n timeoutMs: number;\n persistent?: boolean;\n}", "fields": [ { "name": "taskId", "type": "string", "required": true, "notes": "ID of the background monitor task." }, { "name": "timeoutMs", "type": "number", "required": true, "notes": "Timeout deadline in milliseconds (0 when persistent)." }, { "name": "persistent", "type": "boolean", "required": false, "notes": "No timeout — runs until TaskStop or session end." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "NotebookEdit", "category": "core", "purpose": "Modify a notebook cell.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["edit"], "input": { "kind": "published-typescript", "definition": "export interface NotebookEditInput {\n notebook_path: string;\n cell_id?: string;\n new_source: string;\n cell_type?: \"code\" | \"markdown\";\n edit_mode?: \"replace\" | \"insert\" | \"delete\";\n}", "fields": [ { "name": "notebook_path", "type": "string", "required": true, "notes": "The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)" }, { "name": "cell_id", "type": "string", "required": false, "notes": "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." }, { "name": "new_source", "type": "string", "required": true, "notes": "The new source for the cell" }, { "name": "cell_type", "type": "\"code\" | \"markdown\"", "required": false, "notes": "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." }, { "name": "edit_mode", "type": "\"replace\" | \"insert\" | \"delete\"", "required": false, "notes": "The type of edit to make (replace, insert, delete). Defaults to replace." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface NotebookEditOutput {\n new_source: string;\n old_source?: string;\n cell_id?: string;\n cell_type: \"code\" | \"markdown\";\n language: string;\n edit_mode: string;\n error?: string;\n notebook_path: string;\n original_file: string;\n updated_file: string;\n}", "fields": [ { "name": "new_source", "type": "string", "required": true, "notes": "The new source code that was written to the cell" }, { "name": "old_source", "type": "string", "required": false, "notes": "The previous cell source (replace/delete only). Enables cell-relative diff rendering without re-reading the notebook." }, { "name": "cell_id", "type": "string", "required": false, "notes": "The ID of the cell that was edited" }, { "name": "cell_type", "type": "\"code\" | \"markdown\"", "required": true, "notes": "The type of the cell" }, { "name": "language", "type": "string", "required": true, "notes": "The programming language of the notebook" }, { "name": "edit_mode", "type": "string", "required": true, "notes": "The edit mode that was used" }, { "name": "error", "type": "string", "required": false, "notes": "Error message if the operation failed" }, { "name": "notebook_path", "type": "string", "required": true, "notes": "The path to the notebook file" }, { "name": "original_file", "type": "string", "required": true, "notes": "The original notebook content before modification" }, { "name": "updated_file", "type": "string", "required": true, "notes": "The updated notebook content after modification" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "OfferChromeSetup", "category": "sdk-only", "purpose": "Publisher SDK contract for OfferChromeSetup.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "input": { "kind": "published-typescript", "definition": "export interface OfferChromeSetupInput {\n reason?: string;\n}", "fields": [ { "name": "reason", "type": "string", "required": false, "notes": "A short phrase naming what the task needs the user's own browser for." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface OfferChromeSetupOutput {\n outcome: \"connected\" | \"not_now\" | \"no_attempt_yet\";\n}", "fields": [ { "name": "outcome", "type": "\"connected\" | \"not_now\" | \"no_attempt_yet\"", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "PowerShell", "category": "core", "purpose": "Run a PowerShell command.", "availability": "Native tool preview and platform/setting gates; documented behavior does not establish full SDK schema.", "aliases": [], "jobs": ["shell"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "Projects", "category": "sdk-only", "purpose": "Publisher SDK contract for Projects.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "input": { "kind": "published-typescript", "definition": "export interface ProjectsInput {\n method: \"project_info\" | \"project_read\" | \"project_search\" | \"project_write\" | \"project_delete\" | \"project_memory_list\" | \"project_memory_read\";\n path?: string;\n content?: string;\n local_path?: string;\n present_to_user?: boolean;\n query?: string;\n n?: number;\n}", "fields": [ { "name": "method", "type": "\"project_info\" | \"project_read\" | \"project_search\" | \"project_write\" | \"project_delete\" | \"project_memory_list\" | \"project_memory_read\"", "required": true, "notes": "" }, { "name": "path", "type": "string", "required": false, "notes": "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." }, { "name": "content", "type": "string", "required": false, "notes": "project_write: inline doc text. Mutually exclusive with local_path. Use local_path for anything you have on disk." }, { "name": "local_path", "type": "string", "required": false, "notes": "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." }, { "name": "present_to_user", "type": "boolean", "required": false, "notes": "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." }, { "name": "query", "type": "string", "required": false, "notes": "project_search: knowledge-base query" }, { "name": "n", "type": "number", "required": false, "notes": "project_search: number of hits (default 5)" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type ProjectsOutput = {\n method: \"project_info\";\n notice?: string;\n name: string;\n description: string;\n instructions: string;\n docs: {\n path: string;\n created_at: string | null;\n }[];\n files?: {\n path: string;\n file_kind: string;\n created_at: string | null;\n }[];\n sync_sources?: {\n type: string | null;\n config: {\n [k: string]: unknown;\n };\n }[];\n knowledge: {\n knowledge_size: number;\n max_knowledge_size: number;\n };\n} | {\n method: \"project_read\";\n notice?: string;\n path: string;\n file_kind?: string;\n content?: string;\n local_file?: string;\n created_at: string | null;\n} | {\n method: \"project_search\";\n notice?: string;\n rag: boolean;\n hits?: {\n name?: string;\n doc_uuid?: string;\n text?: string;\n }[];\n docs?: string[];\n} | {\n method: \"project_write\";\n notice?: string;\n path: string;\n doc_uuid: string;\n replaced: boolean;\n present_to_user?: boolean;\n local_path?: string;\n} | {\n method: \"project_delete\";\n notice?: string;\n path: string;\n deleted: boolean;\n} | {\n method: \"project_memory_list\";\n notice?: string;\n files: {\n path: string;\n size_bytes: number;\n updated_at: string | null;\n truncated: boolean;\n }[];\n truncated: boolean;\n} | {\n method: \"project_memory_read\";\n notice?: string;\n path: string;\n content?: string;\n local_file?: string;\n size_bytes: number;\n updated_at: string | null;\n truncated: boolean;\n};", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "ProposeGoal", "category": "sdk-only", "purpose": "Publisher SDK contract for ProposeGoal.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "jobs": ["goals"], "input": { "kind": "published-typescript", "definition": "export interface ProposeGoalInput {\n condition: string;\n ask_user?: boolean;\n}", "fields": [ { "name": "condition", "type": "string", "required": true, "notes": "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." }, { "name": "ask_user", "type": "boolean", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ProposeGoalOutput {\n condition: string;\n askUser: boolean;\n}", "fields": [ { "name": "condition", "type": "string", "required": true, "notes": "The condition shown to the user for approval, or set directly when ask_user was false" }, { "name": "askUser", "type": "boolean", "required": true, "notes": "Whether the user was asked for approval (true) or the goal was set directly (false)" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "ProposeSkills", "category": "sdk-only", "purpose": "Publisher SDK contract for ProposeSkills.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "jobs": ["skills"], "input": { "kind": "published-typescript", "definition": "export interface ProposeSkillsInput {\n proposals: [\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n ] | [\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n ] | [\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n ];\n}", "fields": [ { "name": "proposals", "type": "[\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n] | [\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n] | [\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n },\n {\n name: string;\n kind: \"new\" | \"improvement\";\n target?: string;\n description: string;\n evidence?: string[];\n skillMd: string;\n }\n]", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ProposeSkillsOutput {\n proposalCount: number;\n}", "fields": [ { "name": "proposalCount", "type": "number", "required": true, "notes": "Number of proposals shown on the review card" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "PushNotification", "category": "core", "purpose": "Notify the user.", "availability": "Desktop and optional Remote Control push; hosted delivery restrictions.", "aliases": [], "jobs": ["ask-user"], "input": { "kind": "published-typescript", "definition": "export interface PushNotificationInput {\n message: string;\n status: \"proactive\";\n}", "fields": [ { "name": "message", "type": "string", "required": true, "notes": "The notification body. Keep it under 200 characters; mobile OSes truncate." }, { "name": "status", "type": "\"proactive\"", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface PushNotificationOutput {\n message: string;\n pushSent?: boolean;\n localSent?: boolean;\n disabledReason?: \"config_off\" | \"user_present\" | \"no_transport\";\n sentAt?: string;\n}", "fields": [ { "name": "message", "type": "string", "required": true, "notes": "" }, { "name": "pushSent", "type": "boolean", "required": false, "notes": "" }, { "name": "localSent", "type": "boolean", "required": false, "notes": "" }, { "name": "disabledReason", "type": "\"config_off\" | \"user_present\" | \"no_transport\"", "required": false, "notes": "" }, { "name": "sentAt", "type": "string", "required": false, "notes": "ISO timestamp captured at tool execution on the emitting process. Optional — resumed sessions replay pre-sentAt outputs verbatim." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "REPL", "category": "historical", "purpose": "Execute in the historical experimental REPL.", "availability": "Removed in CLI 2.1.275. Experimental through 2.1.274 with CLAUDE_CODE_REPL=1. Historical contract unavailable.", "aliases": [], "jobs": ["compose"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://code.claude.com/docs/en/agent-sdk/typescript" ] }, { "name": "Read", "category": "core", "purpose": "Read a file.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": ["FileRead (SDK type prefix, not a callable alias)"], "jobs": ["read"], "input": { "kind": "published-typescript", "definition": "export interface FileReadInput {\n file_path: string;\n offset?: number;\n limit?: number;\n pages?: string;\n allow_large?: boolean;\n}", "fields": [ { "name": "file_path", "type": "string", "required": true, "notes": "The absolute path to the file to read" }, { "name": "offset", "type": "number", "required": false, "notes": "The line number to start reading from. Only provide if the file is too large to read at once" }, { "name": "limit", "type": "number", "required": false, "notes": "The number of lines to read. Only provide if the file is too large to read at once." }, { "name": "pages", "type": "string", "required": false, "notes": "Page range for PDF files (e.g., \"1-5\", \"3\", \"10-20\"). Only applicable to PDF files. Maximum 20 pages per request." }, { "name": "allow_large", "type": "boolean", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type FileReadOutput = {\n type: \"text\";\n file: {\n filePath: string;\n content: string;\n numLines: number;\n startLine: number;\n totalLines: number;\n truncatedByTokenCap?: boolean;\n };\n artifactRead?: {\n slug: string;\n ver: string;\n };\n} | {\n type: \"image\";\n file: {\n base64: string;\n type: \"image/jpeg\" | \"image/png\" | \"image/gif\" | \"image/webp\";\n originalSize: number;\n dimensions?: {\n originalWidth?: number;\n originalHeight?: number;\n displayWidth?: number;\n displayHeight?: number;\n };\n };\n} | {\n type: \"notebook\";\n file: {\n filePath: string;\n cells: unknown[];\n };\n} | {\n type: \"pdf\";\n file: {\n filePath: string;\n base64: string;\n originalSize: number;\n };\n} | {\n type: \"parts\";\n file: {\n filePath: string;\n originalSize: number;\n count: number;\n outputDir: string;\n };\n firstPage?: number;\n pages?: {\n base64: string;\n mediaType: \"image/jpeg\" | \"image/png\" | \"image/gif\" | \"image/webp\";\n error?: string;\n }[];\n} | {\n type: \"file_unchanged\";\n file: {\n filePath: string;\n };\n source?: \"seeded\";\n};", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ReadMcpResourceDirTool", "category": "sdk-only", "purpose": "Publisher SDK contract for ReadMcpResourceDirTool.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "published-typescript", "definition": "export interface ReadMcpResourceDirInput {\n server: string;\n uri: string;\n}", "fields": [ { "name": "server", "type": "string", "required": true, "notes": "The MCP server name" }, { "name": "uri", "type": "string", "required": true, "notes": "The directory resource URI to list" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ReadMcpResourceDirOutput {\n resources: {\n uri: string;\n name: string;\n mimeType?: string;\n }[];\n error?: string;\n}", "fields": [ { "name": "resources", "type": "{\n uri: string;\n name: string;\n mimeType?: string;\n}[]", "required": true, "notes": "Direct children of the directory resource. Subdirectories appear with mimeType \"inode/directory\"." }, { "name": "error", "type": "string", "required": false, "notes": "Human-readable error when the server could not list the directory" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "ReadMcpResourceTool", "category": "mcp-client", "purpose": "Read a resource URI.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "published-typescript", "definition": "export interface ReadMcpResourceInput {\n server: string;\n uri: string;\n}", "fields": [ { "name": "server", "type": "string", "required": true, "notes": "The MCP server name" }, { "name": "uri", "type": "string", "required": true, "notes": "The resource URI to read" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ReadMcpResourceOutput {\n contents: {\n uri: string;\n mimeType?: string;\n text?: string;\n blobSavedTo?: string;\n }[];\n error?: string;\n}", "fields": [ { "name": "contents", "type": "{\n uri: string;\n mimeType?: string;\n text?: string;\n blobSavedTo?: string;\n}[]", "required": true, "notes": "" }, { "name": "error", "type": "string", "required": false, "notes": "Human-readable error when the server could not read the resource" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ReadNotifications", "category": "sdk-only", "purpose": "Publisher SDK contract for ReadNotifications.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "input": { "kind": "published-typescript", "definition": "export interface ReadNotificationsInput {\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ReadNotificationsOutput {\n notifications: {\n notification_id: string;\n origin: string;\n queued_at: string;\n content: string;\n arrived_at?: string;\n }[];\n remaining: number;\n read_at?: string;\n}", "fields": [ { "name": "notifications", "type": "{\n notification_id: string;\n origin: string;\n queued_at: string;\n content: string;\n arrived_at?: string;\n}[]", "required": true, "notes": "" }, { "name": "remaining", "type": "number", "required": true, "notes": "Notifications still queued after this drain (drains are size-budgeted); call the tool again to read them." }, { "name": "read_at", "type": "string", "required": false, "notes": "RFC3339 timestamp, by this machine's clock, of when this call read the queue. Missing from results saved before this field existed." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "RefreshMcpTools", "category": "sdk-only", "purpose": "Publisher SDK contract for RefreshMcpTools.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "published-typescript", "definition": "export interface RefreshMcpToolsInput {\n server?: string;\n}", "fields": [ { "name": "server", "type": "string", "required": false, "notes": "Optional server name: refresh only this server. Omit to refresh all connected servers." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export type RefreshMcpToolsOutput = {\n server: string;\n status: \"refreshed\" | \"error\" | \"not_connected\";\n toolCount?: number;\n added?: string[];\n removed?: string[];\n error?: string;\n}[];", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "RemoteTrigger", "category": "core", "purpose": "Manage cloud schedules.", "availability": "Subscriber cloud schedules and organization policy; hosted-provider restrictions.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "published-typescript", "definition": "export interface RemoteTriggerInput {\n action: \"list\" | \"get\" | \"create\" | \"update\" | \"run\" | \"create_webhook_trigger\" | \"list_runs\" | \"get_run_log\";\n trigger_id?: string;\n session_id?: string;\n cursor?: string;\n body?: {\n [k: string]: unknown;\n };\n}", "fields": [ { "name": "action", "type": "\"list\" | \"get\" | \"create\" | \"update\" | \"run\" | \"create_webhook_trigger\" | \"list_runs\" | \"get_run_log\"", "required": true, "notes": "" }, { "name": "trigger_id", "type": "string", "required": false, "notes": "Required for get, update, run, and list_runs" }, { "name": "session_id", "type": "string", "required": false, "notes": "Required for get_run_log: a run session id (cse_… or session_…, from list_runs)" }, { "name": "cursor", "type": "string", "required": false, "notes": "next_cursor from a previous list_runs or get_run_log page" }, { "name": "body", "type": "{\n [k: string]: unknown;\n}", "required": false, "notes": "Required for create and update; optional for run" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface RemoteTriggerOutput {\n status: number;\n json: string;\n summary?: string;\n}", "fields": [ { "name": "status", "type": "number", "required": true, "notes": "" }, { "name": "json", "type": "string", "required": true, "notes": "" }, { "name": "summary", "type": "string", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ReportFindings", "category": "core", "purpose": "Present structured code-review findings.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["deliver"], "input": { "kind": "published-typescript", "definition": "export interface ReportFindingsInput {\n level?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n findings: {\n file: string;\n line?: number;\n summary: string;\n short_summary?: string;\n failure_scenario: string;\n category?: string;\n verdict?: \"CONFIRMED\" | \"PLAUSIBLE\";\n outcome?: \"fixed\" | \"skipped\" | \"no_change_needed\";\n }[];\n}", "fields": [ { "name": "level", "type": "\"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\"", "required": false, "notes": "Effort level the review ran at" }, { "name": "findings", "type": "{\n file: string;\n line?: number;\n summary: string;\n short_summary?: string;\n failure_scenario: string;\n category?: string;\n verdict?: \"CONFIRMED\" | \"PLAUSIBLE\";\n outcome?: \"fixed\" | \"skipped\" | \"no_change_needed\";\n}[]", "required": true, "notes": "Verified findings, most-severe first; empty if none survived" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ReportFindingsOutput {\n count: number;\n level?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n findings: {\n file: string;\n line?: number;\n summary: string;\n short_summary?: string;\n failure_scenario: string;\n category?: string;\n verdict?: \"CONFIRMED\" | \"PLAUSIBLE\";\n outcome?: \"fixed\" | \"skipped\" | \"no_change_needed\";\n }[];\n}", "fields": [ { "name": "count", "type": "number", "required": true, "notes": "Number of findings reported" }, { "name": "level", "type": "\"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\"", "required": false, "notes": "Effort level the review ran at" }, { "name": "findings", "type": "{\n file: string;\n line?: number;\n summary: string;\n short_summary?: string;\n failure_scenario: string;\n category?: string;\n verdict?: \"CONFIRMED\" | \"PLAUSIBLE\";\n outcome?: \"fixed\" | \"skipped\" | \"no_change_needed\";\n}[]", "required": true, "notes": "Echoed for the result body" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ScheduleWakeup", "category": "core", "purpose": "Choose the next loop iteration.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["schedule"], "input": { "kind": "published-typescript", "definition": "export interface ScheduleWakeupInput {\n delaySeconds?: number;\n reason?: string;\n prompt?: string;\n stop?: boolean;\n noop?: boolean;\n}", "fields": [ { "name": "delaySeconds", "type": "number", "required": false, "notes": "Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless `stop` is true." }, { "name": "reason", "type": "string", "required": false, "notes": "One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific. Required unless `stop` is true." }, { "name": "prompt", "type": "string", "required": false, "notes": "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." }, { "name": "stop", "type": "boolean", "required": false, "notes": "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." }, { "name": "noop", "type": "boolean", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ScheduleWakeupOutput {\n scheduledFor: number;\n clampedDelaySeconds: number;\n wasClamped: boolean;\n stopped?: boolean;\n cancelledWakeups?: number;\n}", "fields": [ { "name": "scheduledFor", "type": "number", "required": true, "notes": "Epoch ms timestamp when the next wakeup will fire" }, { "name": "clampedDelaySeconds", "type": "number", "required": true, "notes": "Actual delay used after clamping to runtime bounds" }, { "name": "wasClamped", "type": "boolean", "required": true, "notes": "True if the requested delaySeconds was outside [60, 3600]" }, { "name": "stopped", "type": "boolean", "required": false, "notes": "True when the model ended the loop via `stop: true`" }, { "name": "cancelledWakeups", "type": "number", "required": false, "notes": "How many pending dynamic-loop wakeups stop:true cancelled. 0 means nothing was pending — a recurring /loop cron is not cancelled by stop:true." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "SendFeedback", "category": "core", "purpose": "Prepare a feedback draft for review.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "input": { "kind": "published-typescript", "definition": "export interface SendFeedbackInput {\n type: \"bug\" | \"idea\" | \"missing_capability\";\n title: string;\n details: string;\n area?: string;\n failure_mode?: \"instruction_following\" | \"destructive_actions\" | \"code_quality\" | \"repetition_and_looping\" | \"model_regression\" | \"overconfidence_and_hallucination\" | \"context_and_memory\" | \"overeager\" | \"over_correction\" | \"stopping_short\" | \"dispute_or_decline\" | \"subagent_overspawn\" | \"tone_or_preachiness\" | \"excessive_questions\" | \"unwanted_scope\" | \"other\";\n task_category?: \"code_edit\" | \"debug\" | \"explain\" | \"plan\" | \"shell\" | \"search\" | \"review\" | \"other\";\n}", "fields": [ { "name": "type", "type": "\"bug\" | \"idea\" | \"missing_capability\"", "required": true, "notes": "What kind of feedback this is." }, { "name": "title", "type": "string", "required": true, "notes": "Short, specific one-line summary of the issue." }, { "name": "details", "type": "string", "required": true, "notes": "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." }, { "name": "area", "type": "string", "required": false, "notes": "Optional short tag naming the part of Claude Code this is about (e.g. \"hooks config\", \"/help\", \"file editing\"). Leave blank if unclear." }, { "name": "failure_mode", "type": "\"instruction_following\" | \"destructive_actions\" | \"code_quality\" | \"repetition_and_looping\" | \"model_regression\" | \"overconfidence_and_hallucination\" | \"context_and_memory\" | \"overeager\" | \"over_correction\" | \"stopping_short\" | \"dispute_or_decline\" | \"subagent_overspawn\" | \"tone_or_preachiness\" | \"excessive_questions\" | \"unwanted_scope\" | \"other\"", "required": false, "notes": "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." }, { "name": "task_category", "type": "\"code_edit\" | \"debug\" | \"explain\" | \"plan\" | \"shell\" | \"search\" | \"review\" | \"other\"", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface SendFeedbackOutput {\n success: boolean;\n message: string;\n}", "fields": [ { "name": "success", "type": "boolean", "required": true, "notes": "" }, { "name": "message", "type": "string", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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.", "Creates a local draft; user review/send is a later action. Tool success does not prove feedback transmission." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "SendMessage", "category": "core", "purpose": "Message another agent.", "availability": "Reachability depends on local agents, team membership, remote connection and cross-session messaging enablement (>=2.1.224 for sessions).", "aliases": [], "jobs": ["subagents"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "SendUserFile", "category": "core", "purpose": "Deliver a generated file.", "availability": "Remote Control client connected or cloud session; hosted delivery provider restrictions.", "aliases": [], "jobs": ["deliver"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "ShareOnboardingGuide", "category": "core", "purpose": "Share the onboarding guide.", "availability": "Team/Enterprise subscription and onboarding workflow.", "aliases": [], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "ShowOnboardingRolePicker", "category": "sdk-only", "purpose": "Publisher SDK contract for ShowOnboardingRolePicker.", "availability": "Publisher SDK type only; concrete CLI/host registration and gates not established.", "aliases": [], "input": { "kind": "published-typescript", "definition": "export interface ShowOnboardingRolePickerInput {\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface ShowOnboardingRolePickerOutput {\n role?: string;\n dismissed?: boolean;\n}", "fields": [ { "name": "role", "type": "string", "required": false, "notes": "" }, { "name": "dismissed", "type": "boolean", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": ["https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts"] }, { "name": "Skill", "category": "core", "purpose": "Invoke a skill in the conversation.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["skills"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "SubagentHandback", "category": "core", "purpose": "Submit the final subagent report for review.", "availability": "Auto-mode local non-fork Agent subagents only; CLI >=2.1.271. Classifier reviews the report.", "aliases": [], "jobs": ["subagents"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "TaskCreate", "category": "core", "purpose": "Create a tracked task.", "availability": "Model-dependent task-tracking exposure; opt-in for other models. Shared task list behavior differs in subagents/teams.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface TaskCreateInput {\n subject: string;\n description: string;\n activeForm?: string;\n metadata?: {\n [k: string]: unknown;\n };\n}", "fields": [ { "name": "subject", "type": "string", "required": true, "notes": "A brief title for the task" }, { "name": "description", "type": "string", "required": true, "notes": "What needs to be done" }, { "name": "activeForm", "type": "string", "required": false, "notes": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" }, { "name": "metadata", "type": "{\n [k: string]: unknown;\n}", "required": false, "notes": "Arbitrary metadata to attach to the task" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TaskCreateOutput {\n task: {\n id: string;\n subject: string;\n };\n}", "fields": [ { "name": "task", "type": "{\n id: string;\n subject: string;\n}", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "TaskGet", "category": "core", "purpose": "Read one tracked task.", "availability": "Model-dependent task-tracking exposure; opt-in for other models. Shared task list behavior differs in subagents/teams.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface TaskGetInput {\n taskId: string;\n}", "fields": [ { "name": "taskId", "type": "string", "required": true, "notes": "The ID of the task to retrieve" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TaskGetOutput {\n task: {\n id: string;\n subject: string;\n description: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n blocks: string[];\n blockedBy: string[];\n } | null;\n}", "fields": [ { "name": "task", "type": "{\n id: string;\n subject: string;\n description: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n blocks: string[];\n blockedBy: string[];\n} | null", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "TaskList", "category": "core", "purpose": "List tracked tasks.", "availability": "Model-dependent task-tracking exposure; opt-in for other models. Shared task list behavior differs in subagents/teams.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface TaskListInput {\n}", "fields": [], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TaskListOutput {\n tasks: {\n id: string;\n subject: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n owner?: string;\n blockedBy: string[];\n }[];\n}", "fields": [ { "name": "tasks", "type": "{\n id: string;\n subject: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n owner?: string;\n blockedBy: string[];\n}[]", "required": true, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "TaskOutput", "category": "historical", "purpose": "Read background task output (historical).", "availability": "Removed in CLI 2.1.277; retained only as a historical name. Use Read on the background output file.", "aliases": [], "jobs": ["processes"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "TaskStop", "category": "core", "purpose": "Stop a background task or agent.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": ["shell_id (deprecated input alias; use task_id)"], "jobs": ["processes", "subagents"], "input": { "kind": "published-typescript", "definition": "export interface TaskStopInput {\n task_id?: string;\n shell_id?: string;\n}", "fields": [ { "name": "task_id", "type": "string", "required": false, "notes": "The ID of the background task to stop. Agent-team teammates and named background agents are also accepted by agent ID or name." }, { "name": "shell_id", "type": "string", "required": false, "notes": "Deprecated: use task_id instead" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TaskStopOutput {\n message: string;\n task_id: string;\n task_type: string;\n command?: string;\n}", "fields": [ { "name": "message", "type": "string", "required": true, "notes": "Status message about the operation" }, { "name": "task_id", "type": "string", "required": true, "notes": "The ID of the task that was stopped" }, { "name": "task_type", "type": "string", "required": true, "notes": "The type of the task that was stopped" }, { "name": "command", "type": "string", "required": false, "notes": "The command or description of the stopped task" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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.", "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "TaskUpdate", "category": "core", "purpose": "Update a tracked task.", "availability": "Model-dependent task-tracking exposure; opt-in for other models. Shared task list behavior differs in subagents/teams.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface TaskUpdateInput {\n taskId: string;\n subject?: string;\n description?: string;\n activeForm?: string;\n status?: (\"pending\" | \"in_progress\" | \"completed\") | \"deleted\";\n addBlocks?: string[];\n addBlockedBy?: string[];\n owner?: string;\n metadata?: {\n [k: string]: unknown;\n };\n}", "fields": [ { "name": "taskId", "type": "string", "required": true, "notes": "The ID of the task to update" }, { "name": "subject", "type": "string", "required": false, "notes": "New subject for the task" }, { "name": "description", "type": "string", "required": false, "notes": "New description for the task" }, { "name": "activeForm", "type": "string", "required": false, "notes": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" }, { "name": "status", "type": "(\"pending\" | \"in_progress\" | \"completed\") | \"deleted\"", "required": false, "notes": "New status for the task" }, { "name": "addBlocks", "type": "string[]", "required": false, "notes": "Task IDs that this task blocks" }, { "name": "addBlockedBy", "type": "string[]", "required": false, "notes": "Task IDs that block this task" }, { "name": "owner", "type": "string", "required": false, "notes": "New owner for the task" }, { "name": "metadata", "type": "{\n [k: string]: unknown;\n}", "required": false, "notes": "Metadata keys to merge into the task. Set a key to null to delete it." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TaskUpdateOutput {\n success: boolean;\n taskId: string;\n updatedFields: string[];\n error?: string;\n statusChange?: {\n from: string;\n to: string;\n };\n}", "fields": [ { "name": "success", "type": "boolean", "required": true, "notes": "" }, { "name": "taskId", "type": "string", "required": true, "notes": "" }, { "name": "updatedFields", "type": "string[]", "required": true, "notes": "" }, { "name": "error", "type": "string", "required": false, "notes": "" }, { "name": "statusChange", "type": "{\n from: string;\n to: string;\n}", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "TodoWrite", "category": "core", "purpose": "Replace the session checklist.", "availability": "Disabled by default; CLAUDE_CODE_ENABLE_TASKS=0 can restore it where task tracking is available.", "aliases": [], "jobs": ["plan"], "input": { "kind": "published-typescript", "definition": "export interface TodoWriteInput {\n todos: {\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n }[];\n}", "fields": [ { "name": "todos", "type": "{\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n}[]", "required": true, "notes": "The updated todo list" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface TodoWriteOutput {\n oldTodos: {\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n }[];\n newTodos: {\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n }[];\n}", "fields": [ { "name": "oldTodos", "type": "{\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n}[]", "required": true, "notes": "The todo list before the update" }, { "name": "newTodos", "type": "{\n content: string;\n status: \"pending\" | \"in_progress\" | \"completed\";\n activeForm: string;\n}[]", "required": true, "notes": "The todo list after the update" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "ToolSearch", "category": "core", "purpose": "Load deferred tools.", "availability": "Deferred tool search enabled; actual discovered MCP tools remain server-defined.", "aliases": [], "jobs": ["discover"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "WaitForMcpServers", "category": "mcp-client", "purpose": "Wait for pending MCP connections.", "availability": "Only when tool search is disabled; otherwise ToolSearch handles wait.", "aliases": [], "jobs": ["mcp"], "input": { "kind": "unavailable", "definition": "", "fields": [], "notes": "The pinned SDK does not publish this tool input type. Documentation confirms tool identity/behavior only; examples do not establish a complete schema." }, "output": { "kind": "unavailable", "definition": "", "fields": [], "notes": "No complete result type in the pinned publisher SDK. Text/examples are not an exhaustive result schema." }, "lifecycle": [ "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." ], "references": ["https://code.claude.com/docs/en/tools-reference"] }, { "name": "WebFetch", "category": "core", "purpose": "Fetch and process a web page.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["web"], "input": { "kind": "published-typescript", "definition": "export interface WebFetchInput {\n url: string;\n prompt: string;\n offset?: number;\n}", "fields": [ { "name": "url", "type": "string", "required": true, "notes": "The URL to fetch content from" }, { "name": "prompt", "type": "string", "required": true, "notes": "The prompt to run on the fetched content" }, { "name": "offset", "type": "number", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface WebFetchOutput {\n bytes: number;\n code: number;\n codeText: string;\n result: string;\n durationMs: number;\n url: string;\n artifactRead?: {\n slug: string;\n ver?: string;\n seeded?: false;\n };\n}", "fields": [ { "name": "bytes", "type": "number", "required": true, "notes": "Size of the fetched content in bytes" }, { "name": "code", "type": "number", "required": true, "notes": "HTTP response code" }, { "name": "codeText", "type": "string", "required": true, "notes": "HTTP response code text" }, { "name": "result", "type": "string", "required": true, "notes": "Processed result from applying the prompt to the content" }, { "name": "durationMs", "type": "number", "required": true, "notes": "Time taken to fetch and process the content" }, { "name": "url", "type": "string", "required": true, "notes": "The URL that was fetched" }, { "name": "artifactRead", "type": "{\n slug: string;\n ver?: string;\n seeded?: false;\n}", "required": false, "notes": "" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "WebSearch", "category": "core", "purpose": "Search the web.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["web"], "input": { "kind": "published-typescript", "definition": "export interface WebSearchInput {\n query: string;\n allowed_domains?: string[];\n blocked_domains?: string[];\n}", "fields": [ { "name": "query", "type": "string", "required": true, "notes": "The search query to use" }, { "name": "allowed_domains", "type": "string[]", "required": false, "notes": "Only include search results from these domains" }, { "name": "blocked_domains", "type": "string[]", "required": false, "notes": "Never include search results from these domains" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface WebSearchOutput {\n query: string;\n results: ({\n tool_use_id: string;\n content: {\n title: string;\n url: string;\n snippet?: string;\n }[];\n } | string)[];\n durationSeconds: number;\n searchCount?: number;\n}", "fields": [ { "name": "query", "type": "string", "required": true, "notes": "The search query that was executed" }, { "name": "results", "type": "({\n tool_use_id: string;\n content: {\n title: string;\n url: string;\n snippet?: string;\n }[];\n} | string)[]", "required": true, "notes": "Search results and/or text commentary from the model" }, { "name": "durationSeconds", "type": "number", "required": true, "notes": "Time taken to complete the search operation" }, { "name": "searchCount", "type": "number", "required": false, "notes": "Number of web searches performed" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Workflow", "category": "core", "purpose": "Run an orchestrated workflow.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": [], "jobs": ["compose"], "input": { "kind": "published-typescript", "definition": "export interface WorkflowInput {\n script?: string;\n name?: string;\n description?: string;\n title?: string;\n args?: {\n [k: string]: unknown;\n };\n scriptPath?: string;\n resumeFromRunId?: string;\n}", "fields": [ { "name": "script", "type": "string", "required": false, "notes": "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": "name", "type": "string", "required": false, "notes": "Name of a predefined workflow (built-in or from .claude/workflows/). Resolves to a self-contained script." }, { "name": "description", "type": "string", "required": false, "notes": "Ignored — set the workflow description in the script's `meta` block." }, { "name": "title", "type": "string", "required": false, "notes": "Ignored — set the workflow title in the script's `meta` block." }, { "name": "args", "type": "{\n [k: string]: unknown;\n}", "required": false, "notes": "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)." }, { "name": "scriptPath", "type": "string", "required": false, "notes": "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`." }, { "name": "resumeFromRunId", "type": "string", "required": false, "notes": "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." } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface WorkflowOutput {\n status: \"async_launched\" | \"remote_launched\";\n taskId: string;\n taskType?: \"local_workflow\" | \"remote_agent\";\n workflowName?: string;\n runId?: string;\n summary?: string;\n transcriptDir?: string;\n scriptPath?: string;\n sessionUrl?: string;\n warning?: string;\n error?: string;\n}", "fields": [ { "name": "status", "type": "\"async_launched\" | \"remote_launched\"", "required": true, "notes": "" }, { "name": "taskId", "type": "string", "required": true, "notes": "" }, { "name": "taskType", "type": "\"local_workflow\" | \"remote_agent\"", "required": false, "notes": "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." }, { "name": "workflowName", "type": "string", "required": false, "notes": "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." }, { "name": "runId", "type": "string", "required": false, "notes": "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." }, { "name": "summary", "type": "string", "required": false, "notes": "" }, { "name": "transcriptDir", "type": "string", "required": false, "notes": "Directory where subagent transcripts are written during execution" }, { "name": "scriptPath", "type": "string", "required": false, "notes": "Path to the persisted workflow script for this invocation. Editable via Write/Edit; pass back as `scriptPath` to re-run without resending the script." }, { "name": "sessionUrl", "type": "string", "required": false, "notes": "CCR session URL when status is remote_launched" }, { "name": "warning", "type": "string", "required": false, "notes": "Non-blocking heads-up (e.g. local git state diverges from the pushed branch the cloud session will clone)" }, { "name": "error", "type": "string", "required": false, "notes": "Set if syntax check failed" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] }, { "name": "Write", "category": "core", "purpose": "Write a file.", "availability": "Built in. The model, platform, mode, tool settings and permission rules can still remove it.", "aliases": ["FileWrite (SDK type prefix, not a callable alias)"], "jobs": ["edit"], "input": { "kind": "published-typescript", "definition": "export interface FileWriteInput {\n file_path: string;\n content: string;\n}", "fields": [ { "name": "file_path", "type": "string", "required": true, "notes": "The absolute path to the file to write (must be absolute, not relative)" }, { "name": "content", "type": "string", "required": true, "notes": "The content to write to the file" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "output": { "kind": "published-typescript", "definition": "export interface FileWriteOutput {\n type: \"create\" | \"update\";\n filePath: string;\n content: string;\n structuredPatch: {\n oldStart: number;\n oldLines: number;\n newStart: number;\n newLines: number;\n lines: string[];\n }[];\n originalFile: string | null;\n gitDiff?: {\n filename: string;\n status: \"modified\" | \"added\";\n additions: number;\n deletions: number;\n changes: number;\n patch: string;\n repository?: string | null;\n };\n userModified?: boolean;\n staged?: boolean;\n}", "fields": [ { "name": "type", "type": "\"create\" | \"update\"", "required": true, "notes": "Whether a new file was created or an existing file was updated" }, { "name": "filePath", "type": "string", "required": true, "notes": "The path to the file that was written" }, { "name": "content", "type": "string", "required": true, "notes": "The content that was written to the file" }, { "name": "structuredPatch", "type": "{\n oldStart: number;\n oldLines: number;\n newStart: number;\n newLines: number;\n lines: string[];\n}[]", "required": true, "notes": "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)" }, { "name": "originalFile", "type": "string | null", "required": true, "notes": "The original file content before the write (null for new files, or when the previous content was too large to include)" }, { "name": "gitDiff", "type": "{\n filename: string;\n status: \"modified\" | \"added\";\n additions: number;\n deletions: number;\n changes: number;\n patch: string;\n repository?: string | null;\n}", "required": false, "notes": "" }, { "name": "userModified", "type": "boolean", "required": false, "notes": "True when the user edited the proposed content in the permission dialog before accepting" }, { "name": "staged", "type": "boolean", "required": false, "notes": "True when the write was held for the machine owner to review instead of written; the file is unchanged" } ], "notes": "Publisher-generated TypeScript; preserves required keys, unions, literals and tuples. Defaults, runtime bounds and extra-key rejection are not inferred from types." }, "lifecycle": [ "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." ], "references": [ "https://code.claude.com/docs/en/tools-reference", "https://unpkg.com/@anthropic-ai/claude-agent-sdk@0.3.310/sdk-tools.d.ts" ] } ] } ] }