5.1. Tool execution harness
client/harness/ holds the tool execution harness. Six of its modules are
the security and command-execution substrate: tool_primitives.py (modes,
capabilities, ToolResult), command_policy.py, workspace.py,
sandbox.py, resource_control.py and tool_runtime.py
(CommandRunner, AuditLogger). The others sit above it: the control
plane in front of the coding core (control_plane.py, target_policy.py,
refusal_breaker.py, host_commands.py); the tool lifecycle
(tool_registry.py, tool_router.py, tool_exposure.py,
tool_selection.py); checkpoint.py and approval_binding.py; the
external-capability gateway (capabilities.py, capability_gateway.py,
mcp_provider.py); and web_fetch.py. None imports rag_chat, and the
substrate is testable on its own.
5.1.1. Two tool surfaces
The registry serves two vocabularies, and a turn sees exactly one of them:
The coding core’s six tools (Implementation mode) — on every
request with no standard engaged, and in the implementation pass of a
MIXED request (it needs an OpenAI-compatible endpoint). The core reaches
the harness through SpearHost (control_plane.py), which
calls the same router authorization, workspace resolution, target
policy, command policy and sandbox described below. External capabilities and
workspace knowledge add no tool (The control plane in front of the coding core).
The normative runtime’s tools — the standard.* tools, the file and
command tools of that runtime, search_corpus, and the web pair — in a
session where a standard is engaged, filtered further by what the turn asks
about: a purely normative question is offered no tool that reaches a working
tree.
Neither surface sees the other’s tools, and the coding core never sees a normative one.
5.1.2. The web pair
search_internet finds pages; fetch_url reads one, or saves it with
save_as. Both run in the chat process rather than the sandboxed shell, so
reading works in SAFE; saving is a mutation and takes the ordinary write
authorization. A long PDF comes back in slices and each names the pages
range that continues it — told only that the answer was truncated, a model
re-fetches the same url.
Their exposure follows web_enabled alone, never the wording of the
request: a tool the model cannot see is one it narrates instead of using.
Fig. 5.1 The control plane in front of the coding core, and the three layers of the substrate: what may run, where it runs, how it is confined.
5.1.3. The control plane and three layers
A coding-core call first crosses the control plane, SpearHost (The control plane in front of the coding core): workspace resolution, the router’s hard gates and the target policy, and the two host commands it answers itself. Below it, the substrate is organised as three layers with a one-way dependency: the decision layer never knows how confinement works, and the execution layer never knows why a command was allowed.
5.1.3.1. Decision layer — what may run at all
Type |
Role |
|---|---|
|
|
|
Immutable per-mode capability set. |
|
Classifies a command into a |
|
The outcome: the granted capabilities, or a terminal |
|
The pure execution contract derived from granted capabilities:
|
5.1.3.2. Boundary layer — where it runs
WorkspaceA canonical set of roots that every filesystem tool path must resolve inside.
resolve()rejects traversal, host absolute paths into the launch directory (unless explicitly allowed) and — importantly — symlink escapes, by resolving the whole path including the parent of a not-yet-existing file before checking containment.CommandRunnerOwns the resource contracts (
resource_limits,cgroup_limits) and the sandbox instance. This is the ownership boundary:rag_chatknows nothing aboutMemoryMax,TasksMax,CPUQuota,systemd-runor unit names.AuditLoggerAppend-only, metadata only.
KEY=valueassignments that look like secrets are redacted, and leading environment assignments are stripped before the executable summary is derived.
5.1.3.3. Execution layer — how it is confined
BubblewrapSandboxbuild_argv()composes the structured bwrap argv;run()executes the closed-network path;_run_with_slirp()executes the network path.ResourceLimits/CgroupLimitsTwo orthogonal resource contracts. See Resource control for why there are two and why neither replaces the other.
SystemdScopeRunnerKnows systemd and nothing else. Given an argv and a
CgroupLimitsit produces a wrapped argv; it has no idea what a capability is.ToolResultThe single result type:
status, a required one-linesummary,stdout,stderr,exit_codeandchanged_paths.statusis one ofok,denied,cancelled,invalid_path,not_found,timeout,failed.
5.1.4. Life of a tool call
ToolExposurePolicysupplies the role’s model-visible registry view.The model proposes a tool call and
ToolRoutervalidates its schema.The router’s hard gates run: the request scope and the target policy (sibling targets, generated and snapshot targets, what a shell command writes, searches outside the project), then the execution modes the tool’s spec declares (
execution_modes).The router invokes the registered handler and observer hooks.
CommandPolicy.classify()classifies the command.The classification is intersected with the capabilities the current mode grants. Anything not granted ends here.
In
ASKmode a confirmation is requested for mutating or network work.CommandRunner.ensure_sandbox()preflights Bubblewrap — once, cached — and for network work also preflights the full slirp path.BubblewrapSandbox.run()checks, before spawning anything: the bwrap binary,prlimitif resource limits are active, the cgroup mechanism if cgroup limits are active, and for network work the slirp helper plus its pinned-namespace support.The command runs, wrapped as described in Sandbox.
The substrate returns a
ToolResult; the router normalizes it as aToolResultEnvelope.Large safe output is kept in
ResultStorewhile only a bounded preview is rendered into model context.Grounded mutations update
WorkingStateand mutating attempts are recorded byAuditLogger.
Every one of the step-9 checks returns a failed ToolResult rather than
proceeding in a degraded mode (The fail-closed rule in practice).
A refusal of the target policy attaches to the file, not to the tool (The control plane in front of the coding core).
5.1.5. Repeated refusals
A refusal is deterministic, so asking again cannot change it. When a turn
asks for the same refused operation five times – the same tool, target and
refusal once spacing, quoting, a leading ./ and trailing slashes are set
aside – it is stopped with an answer that names the refusal, and the stop is
emitted as a repeated_refusal_stopped trace event, kept when tracing is on
(SPEAR_TRACE). SPEAR_REFUSAL_REPEATS sets the limit, and
SPEAR_RESPONSE_MAX_TOKENS bounds a single model response
(Configuration reference).
The core’s terminal has bounds of its own: a call runs for 180 s unless
it asks for another timeout, and one above 600 s is refused; its output is
cut to 50 000 characters, keeping the head and the tail (agent/tools.py).
The timeout replaces the sandbox’s own default (45 s) for that call only.
5.1.6. Once the sandbox is known to be down
The checks above decide one command at a time. One conclusion outlives the
command that reached it: when a command’s output reports the sandbox missing,
_registered_command (the normative runtime’s command handler) records it on
the turn’s cache, and every later file write or deletion in that turn is
refused explicitly instead of performed — the coding core’s write and delete
ports read the same mark.
The reason is not sandbox purity but verifiability. Without the sandbox
nothing the model writes can be read back, compiled or run, so an edit made
from retrieved context alone is a change nobody can check — and the answer the
user needs is that the sandbox is down, not a plausible patch. DENIED and
not FAILED: the tool did not break, it declined.
The guard lives in the router’s file handlers (tool_handlers.py).
execute_tool in tool_routing.py is a legacy compatibility facade over
the same router, not a separate path that could bypass it.
5.1.7. Preflight caching
What preflight runs is described in Sandbox. Results are cached on the sandbox instance, and terminal failures
(ABSENT, INEXECUTABLE, REFUSED) are remembered so a broken
environment is not re-probed on every call. The network preflight is cached
per (sandbox, workspace) pair and invalidated when either changes.
5.1.8. Containment poisoning
The network path has one failure mode that must never be retried blindly: the harness asked the sandbox child to die, and could not confirm that it did.
If _wait_pidfd_exit() cannot observe the child’s termination, the sandbox
sets network_containment_failed and every subsequent network request is
refused for the lifetime of that sandbox object. A namespace whose death is
unverified may still hold a network namespace that a helper is attached to;
continuing would mean starting a second helper against unknown state.
5.1.9. Why the pidfd
Every place the harness signals or observes the sandbox child, it does so through a pidfd, never a numeric PID:
signal.pidfd_send_signal(pidfd, signal.SIGKILL) # not os.kill(pid, ...)
A numeric PID can be reused between the moment it is read and the moment it is
signalled. On a machine that spawns processes as fast as a build does, that is
not a theoretical concern. _stop_namespace_child() retries once through
the same pidfd and has deliberately no os.kill fallback.
The pidfd and the namespace handles introduced in Network backend have distinct roles that are worth keeping straight:
Handle |
Identity it pins |
|---|---|
pidfd |
the process — liveness and safe signalling |
|
the namespaces — stable targets for the network helper |
Neither substitutes for the other, and the code does not conflate them.