Module tools 

Tools the agent can call.

A Tool is a named capability with a JSON-Schema input and an async execute. The ToolRegistry holds the set offered to a model; built-ins cover file read/write/edit, directory listing, glob, content search, and shell execution. Every tool can be disabled or re-described per crate::Config, so the capability surface is entirely yours to shape.

Modules

clock

BP-3 (catalog row “Clock / sleep tools”, cc§1 ScheduleWakeup variant / cx§1 clock+sleep features): the two tools that let a model read the wall clock and pace itself.

context_budget

BP-3 (catalog row “Context-budget tools”, cx§1’s token_budget feature): get_context_remaining and new_context, the MODEL’s doors onto two mechanisms the agent already owns.

convert

BP-2: document conversion for the read and web tools — the “returns it in a form the model can actually use” half of three catalog rows:

image_gen

BP-3 (catalog row “Image generation tool”, cx§1’s image_gen feature): a client-issued call to the PROVIDER’s image endpoint.

plan_mode

BP-3 (§2 module 8 plan_mode, catalog rows “Plan-mode enter/exit tools” and “Plan mode (read-only research phase)”): the model-invocable restriction mode.

question

BP-3 (§2 module 6 tools.question, catalog row “Structured user-question tool”): the tool a model uses to ask the USER a multiple-choice or free-text question mid-run, and wait for the answer.

Structs

ApplyPatchTool

Apply a Codex-style apply_patch envelope — Codex’s primary edit mechanism, richer than edit_file’s single string replace. Supports Add File, Delete File, and Update File (with -/+/context hunks and an optional *** Move to: rename) in one atomic-ish call.

AskUserTool

The structured user-question tool. name is the registered spelling — ASK_USER under cc-parity, additionally REQUEST_USER_INPUT under cx-parity.

BashTool

Run a shell command via sh -c.

ContextBudget

The shared context accounting the two tools read and write.

CurrentTimeTool

current_time — the wall clock, ISO-8601 plus timezone.

EditFileTool

Replace an exact substring in a file.

EnterPlanModeTool

enter_plan_mode — start the read-only research phase.

ExitPlanModeTool

exit_plan_mode — present the plan for approval and, if approved, leave the read-only phase.

GetContextRemainingTool

get_context_remaining — how much of the context window is left.

GlobTool

Match files by glob pattern.

ImageGenTool

image_gen — generate an image through the session’s own provider.

ListDirTool

List directory entries.

NetworkPolicy

P4c (S2 module 5 tools.web, S2.1 dep “network sandbox rules”, S17): the network-domain policy a caller (SDK embedder) may install on a ToolContext so crate::tools::WebFetchTool/crate::tools::WebSearchTool respect it — see ToolContext::check_network. None on the context (the default) means no policy is configured, matching today’s honest gap (no P5 capabilities.permissions.sandbox.network engine exists yet, C3 — tracked, not hidden).

NewContextRequest

One parked fresh-window request, as the model stated it. The fields are exactly Agent::new_context’s parameters — this type carries a request across the tool/agent boundary, it does not add semantics of its own.

NewContextTool

new_context — continue in a fresh window seeded with an objective and the curated recent tail.

PersistentShellTool

A long-lived shell whose state (working directory, environment variables, shell functions) persists across calls — unlike the one-shot BashTool. Also supports write_stdin to feed raw input to the shell, for driving interactive programs. This is the analog of Codex’s persistent exec session.

PlanModeState

The shared plan-mode state: whether the read-only research phase is active, and the plan accumulated so far.

Question

One question in an AskUserTool call.

QuestionOption

One selectable answer.

ReadFileTool

Read a UTF-8 text file.

SearchTool

Regex search file contents (respecting .gitignore).

SkillTool

Load a discovered skill package’s body on demand.

SleepTool

sleep — pause this turn for a bounded number of seconds.

ToolApprovalHandler

BP-3: an approval handler reachable from inside a Tool::execute (today, exit_plan_mode’s plan approval). A newtype purely so ToolContext can stay Debug — the same shape, and the same reason, as crate::sandbox::SandboxApprovalHandler.

ToolContext

Ambient context passed to every tool invocation.

ToolRegistry

An ordered set of tools offered to the model.

UpdatePlanTool

A simple plan / task tracker. The model calls it to record or update a checklist of steps (the analog of Codex update_plan / Claude’s plan mode).

UserQuestionHandler

The handler ask_user asks through, wrapped so ToolContext can stay Debug — the same newtype shape (and the same reason) as crate::tools::ToolApprovalHandler.

ViewImageTool

P4c (S1.2 view_image, SPLIT CX row view_image, catalog:28): a dedicated image-input tool, distinct from read_file’s multimodal mode — needed as an image pathway when read_file itself is disabled (cx-parity, S12). NOT registered by default; only reachable as the optional fifth name in [core.tools] enabled (see ToolRegistry::from_config).

WebFetchTool

P4c (S2 module 5 tools.web, S4a “trivially addable… single tool each, no loop changes”): fetch a URL and return it AS MARKDOWN (BP-2, catalog:44 “Fetch a URL, convert to markdown, return to model”), served from an on-disk cache within [WEB_FETCH_TTL_SECS] of the last fetch — CC’s WebFetch is markdown-converting and cached, and a model that re-fetches the same page mid-task should not pay for it twice. NOT registered by default — only reached via [capabilities.tools_web] (module 5), off by default (§3.1). SECURITY (S2.1 S17): honors ToolContext::network_policy when one is configured (see ToolContext::check_network) — a caller (SDK embedder) that has set up a sandbox/network policy on the context gets it enforced here too; with no policy configured (today’s honest default), the fetch is unrestricted, same posture as every other network-capable path in this crate today (C3).

WebSearchTool

P4c (S2 module 5 tools.web): perform a web search.

WriteFileTool

Create or overwrite a file.

WriteObserverChain

P5-11 (§2 modules 28/29, D-5 “shared write-path interception seam”): an ORDERED chain of WriteObservers installed as a single ToolContext::write_observer, so the ONE seam P5-9 built keeps supporting exactly one call site per tool while now composing multiple concerns. Order is caller-determined (crate::agent::build_tool_context builds it checkpoint → formatters → lsp, design’s own required ordering: checkpoint must capture the PRE-image before anything mutates the file; formatters must run before lsp so diagnostics reflect the FINAL, formatted file, not the model’s pre-format draft). before_write runs every observer in order; after_write runs every observer in order too and joins any non-empty annotations with a blank line, so a formatter’s diff-back and an LSP diagnostics block can both appear in one tool result without one silently discarding the other.

Enums

ReadState

BP-2 (catalog:32 “Edit refuses unless file was read (and unchanged) this conversation”): how a path stands relative to the model’s own most recent read of it — see ToolContext::read_state.

SandboxPolicy

Filesystem confinement applied to write-capable tools — the analog of Codex’s read-only / workspace-write / danger-full-access sandbox modes.

SchemaTier

How verbose an advertised tool schema is. Full is today’s behavior — byte-identical to the tool’s own description()/parameters(). Builtins default to Full (small, load-bearing); the win target is fat activated MCP tools (set via the global knob or a per-tool override, see crate::Config::tool_schema_tier / crate::config::ToolOverride::schema_tier).

Constants

ASK_USER

Registered name of the question tool (Claude Code’s AskUserQuestion).

CURRENT_TIME

Registered name of the clock tool.

DEFAULT_WEB_SEARCH_URL

BP-2: the backend used when no operator endpoint is configured.

ENTER_PLAN_MODE

Registered name of the enter tool (Claude Code’s EnterPlanMode).

EXIT_PLAN_MODE

Registered name of the exit tool (Claude Code’s ExitPlanMode).

GET_CONTEXT_REMAINING

Registered name of the remaining-budget tool.

IMAGE_EXTENSIONS

P4c (S1.2 core.tools.read_file.multimodal / view_image): recognized image file extensions (lowercase, no dot) — the same set CC/pi treat as “images” for multimodal read (catalog D1 row 2’s ✓*/✓* variants).

IMAGE_GEN

Registered name of the image tool (Codex’s own spelling).

MAX_SLEEP_SECS

The longest a single sleep call may pause the turn: four hours, the “pause up to hours” the catalog row describes, with a hard ceiling so a runaway loop cannot park a session forever.

MULTIMODAL_IMAGE_MARKER

P4c (COMPOSABLE-HARNESS-DESIGN.md S1.2/S3.1 core.tools.read_file multimodal, S1.2 view_image): the sentinel prefix a tool’s plain String result carries when it is actually an image data URL rather than ordinary text — Agent::run_loop detects this prefix (before cap_tool_output ever sees it) and builds a content_parts image block instead of a plain-text tool result. Using a control character (\u{1}, SOH) as part of the marker keeps a false-positive collision with real tool output astronomically unlikely without requiring a new Tool::execute return type across all ten built-ins (an L-sized trait-signature change this S-sized catalog item does not call for).

NEW_CONTEXT

Registered name of the fresh-window tool.

NOTEBOOK_EXTENSION

P4c (S1.2 core.tools.edit_file.notebook_aware): the extension that gates EditFileTool’s Jupyter cell-surgery branch.

REQUEST_USER_INPUT

Codex’s experimental spelling for the same capability (cx§1 request_user_input), registered as an alias under cx-parity.

SKILL_TOOL

The registered name of the skill-invocation tool.

SLEEP

Registered name of the sleep tool.

WEB_CACHE_DIR_ENV

BP-2: directory override for the fetch cache (tests, and an operator who wants it somewhere specific).

WEB_SEARCH_URL_ENV

Environment variable naming the search endpoint WebSearchTool queries.

Traits

Tool

A callable capability.

WriteObserver

P5-9 (design §2 module 20 checkpoint, §2.1 D-5 “write-path interception seam shared with formatters”): the ONE well-defined interception point around every file-mutating built-in tool (write_file/edit_file/apply_patch) — installed on ToolContext::write_observer, None by default. Both hooks fire AFTER ToolContext::check_write has already approved the call (so an observer never sees a write the sandbox itself refused) and BEFORE/AFTER the actual mutation:

Functions

image_mime_for

The image/<subtype> MIME type for a recognized image extension, for the data: URL — falls back to png for anything is_image_path didn’t already gate (defensive; never actually hit through is_image_path’s own extension list).

is_image_path

Whether path’s extension is a recognized image type (case-insensitive).

minify_tool_schema

Apply tier to a tool’s advertised description/parameters, returning the (possibly) minified pair. Deterministic and LLM-free: the same inputs always produce the same output.

shell_sandbox_unenforceable

True when the requested sandbox policy cannot be enforced for shell subprocesses: a confining policy, a platform without an OS sandbox primitive wired up (only macOS/seatbelt is, via sandbox-exec), and at least one shell tool ("bash" or "shell") enabled.