Extensions

Build extensions, choose hooks, and manage request-scoped state.

Read the walkthrough before consulting individual signatures.

Public interfaces

Interface	Purpose
AgentsMdExtension	Inject AGENTS.md files discovered from the working directory.
AskUserEvent	CUSTOM AgentEvent requesting user input from a streaming client.
AskUserExtension	Register ask_user and suspend its execution until accept() receives a reply.
AskUserRequest	Validated question rendered by a UI for one ask_user tool call.
AskUserResult	Accepted external response returned to the model as a tool result.
AsyncSubAgentExtension	Run subagents in the background and let the model manage them with tools.
SubAgentTask	One background task owned by an AsyncSubAgentExtension.
SubAgentTaskInfo	Model-facing snapshot of one background task.
SubAgentTaskStatus	Lifecycle of one background subagent task.
AgentEventHooksMixin	Hooks for internal notifications and external input.
AgentExtension	Combine all optional hooks for the model-tool request lifecycle.
AgentModelHooksMixin	Hooks immediately before and after each primary model invocation.
AgentRunHooksMixin	Hooks around one complete request and its terminal outcome.
AgentSetupHooksMixin	Hooks that prepare request-scoped tools and conversation context.
AgentToolHooksMixin	Hooks immediately before and after each requested tool invocation.
AgentTurnHooksMixin	Hooks around one model/tool turn inside a request.
MiddlewareHook	Wrap provider requests and local tool handlers for one extension.
BashExtension	Register the bash tool and nothing else.
CodingExtension	Register writable filesystem tools followed by shell execution.
CompactionExtension	Summarize older dialogue before a model step when context exceeds a limit.
ExternalEvent	Provider-neutral envelope whose payload protocol belongs to its receiver.
ExternalEventExtension	Base class for extensions that suspend until an external response arrives.
DeleteFileExtension	Register delete_file to remove one regular file.
EditExtension	Register edit to change an existing file by exact-text replacement.
FileSystemExtension	Register filesystem tools with an optional read-only boundary.
GlobExtension	Register glob to find paths by pattern.
GrepExtension	Register grep to search file contents by regular expression.
ReadExtension	Register read, which returns UTF-8 text or a local image.
ReadFileExtension	Register read_file, which returns a line range of a UTF-8 text file.
ViewImageExtension	Register view_image for local images and HTTP(S) image URLs.
WriteFileExtension	Register write_file to create or replace a whole text file.
GoalEvaluation	Structured decision reported by the private evaluator Agent.
GoalExtension	Continue externally selected Goal Mode requests until verification passes.
default_goal_subagent	Build the standard goal evaluator with complete coding workspace access.
InternalMessageExtension	Receive internal instructions from publish() or external event delivery.
JSONLExtension	Append each complete Agent turn as one line in a session JSONL file.
McpClient	Small client surface consumed by McpExtension.
McpConfiguration	Validated MCP servers loaded from a JSON configuration document.
McpExtension	Discover and register namespaced tools from configured MCP servers.
McpHttpServer	Configure one MCP server reached through Streamable HTTP.
McpStdioServer	Configure one local MCP server launched as a child process.
InMemoryMessageAccumulator	Retain replayable conversation messages for reuse by later requests.
ModelRequestTrace	Exact tool metadata supplied to one provider request.
ModelRequestTraceExtension	Persist exact tool definitions through the assistant response attributes.
ServerToolDefinitionTrace	JSON-safe provider-hosted tool definition persisted beside one response.
ToolDefinitionTrace	JSON-safe local tool definition persisted beside one model response.
model_request_trace	Return the exact local and provider tool definitions sent to the model.
EnterPlanModeEvent	CUSTOM event asking a streaming UI to confirm model-proposed Plan Mode.
EnterPlanModeRequest	Validated rationale displayed before the user approves Plan Mode.
EnterPlanModeResponse	Strict external response correlated with one pending Tool Call.
EnterPlanModeResult	Decision returned to the model after external confirmation.
ExitPlanModeEvent	CUSTOM event asking a streaming UI to approve the submitted plan.
ExitPlanModeRequest	Validated final plan displayed before the user approves exiting.
ExitPlanModeResponse	Strict external response correlated with one pending exit Tool Call.
ExitPlanModeResult	Decision returned to the model after external exit confirmation.
PlanModeEnteredEvent	CUSTOM event notifying a streaming UI that Plan Mode is now active.
PlanModeExitedEvent	CUSTOM event notifying a streaming UI that normal mode is restored.
PlanModeExtension	Require user approval for model-proposed entry and exit transitions.
AnthropicServerToolExtension	Declare one versioned tool executed by Anthropic.
ServerToolExtension	Register one or more provider-hosted tools for every request.
DeepSeekServerToolExtension	Declare one DeepSeek Responses API hosted tool.
GoogleServerToolExtension	Declare one server-executed Gemini tool.
OpenAIServerToolExtension	Declare one OpenAI Responses API hosted tool.
OpenRouterServerToolExtension	Declare one tool hosted by an OpenRouter-compatible endpoint.
ShellApprovalExtension	Intercept bash and pause until a trusted external decision arrives.
ShellApprovalMode	Persisted approval policy for one Agent session.
ShellApprovalRequestedEvent	CUSTOM event asking a UI to approve or abort one shell command.
ShellApprovalResponse	External decision for one pending shell command.
ShellApprovalStorage	Persistence boundary for session policy and remembered commands.
ShellCommandAborted	Raised into normal tool failure handling when the user aborts a command.
SkillDefinition	Validated metadata for one discovered SKILL.md file.
SkillExtension	Advertise valid local skills and register a tool that reads one in full.
SkillFileParser	Validate and parse one Agent Skills-compatible SKILL.md file.
SteeringExtension	Agent-owned urgent user inbox, checked after each model and tool call.
RefusalReplay	What later requests do with an assistant message that was refused.
RefusalReplayExtension	Decide whether the model reads its own refused answers on later turns.
SubAgentDefinition	Configure one isolated agent exposed through the task tool.
SubAgentExtension	Register a task tool that runs one configured subagent in a child session.
SubAgentResult	Final report and durable child-session identity returned to the parent.
default_subagents	Return built-in profiles with their complete extension configuration.
subagent_report	Return a subagent’s report, with a leading notice when it did not finish.
TodoItem	One ordered task in the request-scoped list submitted through todo_write.
TodoStatus	Allowed lifecycle states for one ordered todo item.
TodoWriteExtension	Register todo_write and enforce strictly sequential task progress.
TodoWriteResult	Validated list state returned to the model after each update.
ToolExtension	Register exactly one tool for every request.
ToolGuidancePlacement	Where a tool’s snippet and guidelines are shown to the model.
ToolGuidelinesExtension	Show registered tool snippets and guidelines to the model.
BM25Search	Rank a set of tools with BM25 over their names and descriptions.
ToolCatalogPlacement	Where the list of searchable tools is shown to the model.
ToolSearchExtension	Search registered local tools with BM25 through the Responses or Anthropic API.
ToolSearchStorage	Async key/value boundary used to remember one session’s sent definitions.
render_tool_catalog	Render the deferred tools a model can search for, one entry per tool.
ModelUsageActivityDay	Aggregated model usage for one UTC calendar day.
ModelUsageActivityRecord	One completed model request recorded for activity visualization.
ModelUsageActivityStorage	Persistence boundary consumed by UsageActivityExtension.
UsageActivityExtension	Record every completed model request through an injected storage adapter.