4.1. Implementation mode
A request to change, build or inspect a working tree — with no standard engaged — is an IMPLEMENTATION request. It runs on the coding core, a standalone agentic loop, behind SpearHost, the control plane that decides what each of its calls may do and records what each one did. Without a standard engaged, requests that name no subject at all (GENERAL) take the same path.
request ──► coding core ──► SpearHost ──► sandbox / workspace
▲ │
└── results ◄───┴──► canonical execution evidence
│
▼
implementation evidence (the verdict)
The split is the point. The coding core decides what to try next; it does not decide whether it may, and it does not decide whether it succeeded. SpearHost holds the first, and the evidence plane (Evidence and verdicts) holds the second.
4.1.1. The coding core
The coding core is a conventional tool-calling loop: the model reads, searches, edits and runs commands until it answers. It sees exactly six tools:
Tool |
Arguments |
What it does |
|---|---|---|
|
|
a numbered window of a file; a binary file is described, not dumped |
|
|
search file contents or file names, ripgrep-backed |
|
|
replace an exact (or whitespace-tolerant) occurrence; ambiguity is refused rather than guessed |
|
|
create or overwrite a file |
|
|
delete one file or one symbolic link — the link itself, never what it points at |
|
|
run a shell command in the sandbox; output is capped at 50 000 characters |
Nothing else is offered on an implementation turn: no standard tools, no retrieval tool, no web tool, no memory tool. A tool the model cannot see is a tool it cannot misuse, and every schema left out is context the model keeps.
External capabilities and workspace knowledge are reached through the
terminal with the spear-capability and spear-knowledge host commands,
which SpearHost answers itself, so the surface stays six tools
(External capabilities, Workspace knowledge).
The loop ends when the model answers without calling a tool, when the round or
tool budget runs out (--max-tool-rounds, --max-commands), or when the
conversation reaches half of the context window — the loop does not compact; it
stops and asks for a summary instead. It also stops a turn that is going
nowhere: a call repeated without progress trips the core’s tool-call guardrail,
and an operation refused again and again is stopped by the host’s refusal
breaker (Repeated refusals). Both end the turn as STALLED.
The core sends no sampling parameters, so the server’s own sampling applies
and --temp and --max-tokens serve the other paths, not this one. Its
output reservation is its own, and every model response it requests is bounded
by SPEAR_RESPONSE_MAX_TOKENS (Configuration reference), so one runaway
reply cannot consume the turn.
Note
The coding core talks to an OpenAI-compatible endpoint. The Anthropic backend serves the normative and general paths; it does not yet implement the message interface the coding core uses.
The coding core’s request is built from the workspace’s own context (Projects and corpora) — its rules, project metadata, skills and active knowledge, and the external capabilities it admits — not from the retrieval corpus: an implementation turn reads the tree it is changing, through its tools. That context is selected deterministically, by workspace and request class, never by resemblance to the request; nothing scoped to another project reaches the turn, and every eligible skill is offered (What a turn is shown).
4.1.2. SpearHost — the execution boundary
Every call the coding core makes crosses SpearHost, whichever tool made it:
authorizethe session’s permission mode (
--safe,--ask,--auto), read-only and advisory turns, the write scope of the request, and the command policy.resolveevery path — read, write, delete, or a command’s
workdir— must resolve inside the workspace. Symbolic links are followed before the check, so a link cannot point a write outside it.write/deletethe protected-target policy (generated output, snapshot and third-party copies), the confirmation the mode requires, and the checkpoint that makes
/undopossible.run_commandthe command policy (what may run, what it may write, whether it may reach the network) and the sandbox.
spear-capabilityandspear-knowledgeare answered here and never run.after_toolthe audit record, the canonical evidence of the call, and the count of repeated refusals.
A refusal (a denied result, The control plane in front of the coding core) comes back to the model
as a one-line reason in the coding core’s own vocabulary (refused: …), so
the model is pointed at a tool it actually has.
4.1.2.1. Scope: what a turn may change
Workspace containment. A path that resolves outside the workspace’s roots is refused, for reading as for writing; which roots the workspace has is described in Security model.
Write scope. A request that names a target confines writes to that target and what genuinely belongs to it; a sibling file of the same family is not written because it resembles the one asked for.
Terminal writes are held to the same scope. A shell command’s destinations
— a redirection, the target of cp, mv or install, an in-place
sed — are judged exactly as a write_file to the same path would be. A
change the file tools would refuse cannot be made through the terminal instead.
Protected and generated paths. Generated output and snapshot or third-party copies are refused to every tool, the terminal included, with a pointer to the source to change (target policy, The control plane in front of the coding core).
Advisory and read-only turns. A turn that asks only to be told something, or is told not to change anything, keeps its reading tools and loses every write — including the terminal’s ability to write.
4.1.2.2. Terminal working directory
Where a terminal call runs is decided in this order:
an explicit
workdirargument — resolved, when relative, from the directory the previous command finished in;otherwise the directory the terminal session last recorded (a
cdin an earlier command is remembered, as in an interactive shell);otherwise the workspace root.
A workdir outside the workspace is refused before anything runs. Commands
run in the Bubblewrap sandbox (Sandbox); network access follows the
session’s permission mode (Security model).
4.1.2.3. Canonical execution evidence
Each call is recorded as structured evidence from the tool’s own result — which files it changed, which command it ran, how that command ended, whether it was refused or timed out — never from the text the model was shown. The verdict at the end of the turn (Evidence and verdicts) is computed from this record alone.
4.1.3. One repair after a failed project validation
When the coding pass ends and the project’s own validation – its declared or
probed build or test command (declared and probed commands) – then runs
on the final state and fails, the coding core gets exactly one more pass. It is
given that validation as SPEAR ran it: the kind and origin of the command, the
command, its exit status, the bounded output and the source epoch it judged.
Whatever the repair pass leaves is validated again at its own epoch; a failure
then, a validation that could not run, or a repair pass that stopped before
finishing is UNVERIFIED. There is no second repair, and a pass that changes
nothing ends the turn with the same failure.
The repair is not offered when the validation did not run, nor to a turn stopped by its budget, a repeated refusal, a truncation or the operator. A MIXED implementation pass never receives it: MIXED owns its own single repair and its adjudication (Mixed mode).
4.1.4. Example
A synthetic project; the request names a target and how it will be proved.
> Fix the off-by-one in ring_next() in src/ring.c, then build it.
Read src/ring.c
Update src/ring.c
Terminal make
ring_next() wrapped at size + 1; it now wraps at size. `make` succeeds.
The turn changed src/ring.c and ran a build after the change, so its
implementation evidence is VERIFIED. Had the turn edited the file again
after make, the same answer would be reported UNVERIFIED: the build
proved a tree that no longer exists. Evidence and verdicts explains why.
See also
Evidence and verdicts · Security model · Tool execution harness