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.

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.

BashTool

Run a shell command via sh -c.

EditFileTool

Replace an exact substring in a file.

GlobTool

Match files by glob pattern.

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).

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.

ReadFileTool

Read a UTF-8 text file.

SearchTool

Regex search file contents (respecting .gitignore).

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). The plan is held in the tool so it persists across calls within a session.

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 its response body (capped, text-decoded lossily). 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. supercode bundles no search provider of its own (S4a “single tool… no loop changes” scope — not a search-engine implementation); a configured search endpoint (SUPERCODE_WEB_SEARCH_URL, queried as <url>?q=<query>) is required, same “bring your own credential/endpoint” posture Config::base_url already has for the model provider itself. Absent that, the tool returns a clear configuration error rather than silently no-op’ing.

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

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

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).

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).

NOTEBOOK_EXTENSION

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

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.