Chapter 17 · 4 min read · Updated
Building the Full Mini-Harness
A working mini coding-agent harness that assembles the loop, layered prompts, approval-gated tools, and memory into one terminal agent.
Prefer one idea per screen? Read it as 11 slides →
17.1
What we are building
Time to assemble. Every MVP from Chapters 2 through 14 was a real part of one system, and this chapter snaps them together into mininharness, a small but genuine terminal coding agent. It runs the loop, builds layered prompts, manages context and budget, runs tools behind an approval gate, loads project memory and skills, and can delegate to a subagent. It is a few hundred lines, small enough to read in a sitting, and shaped like the production systems this guide dissects. The only thing it does not ship with is a real model; you drop in an API call (Anthropic, OpenAI, or a local model) in one place, and everything else is the harness, which, as Chapter 1 promised, is 95% of the work.
17.2
Architecture overview
The pieces and where they came from:
+-------------------+
user request -----> | agent loop | <-- Chapter 2 (the spine)
+---------+---------+
|
+---------------------+----------------------+
| | |
+------v------+ +-------v-------+ +--------v--------+
| PromptBuilder| | ContextMgr | | Budget+Hooks |
| Ch 3 + Ch 9 | | Ch 4 + Ch 5 | | Ch 4 + Ch 12 |
| (instr+memory| | (tokens, | | (cost/turn caps,|
| +skills) | | compaction) | | PreToolUse) |
+------+-------+ +-------+-------+ +--------+--------+
| | |
+----------+----------+----------+-----------+
| |
+------v------+ +-------v-------+
| ToolRegistry| | ApprovalPolicy|
| Ch 6 | <--- | Ch 7 | every call is gated
| (+ MCP Ch10)| | (+ guardian) |
+------+------+ +---------------+
|
+------v------+
| subagents | <-- Chapter 11 (delegate, isolate context)
| Ch 11 |
+-------------+
The loop is the spine. Each turn it asks the ContextManager to compact if needed, asks the PromptBuilder to assemble the request (with memory and skills folded in), calls the model, and for any tool call runs it through Budget and Hooks and the ApprovalPolicy before the ToolRegistry executes it. When the model returns plain text, the turn ends. Optional extras: a planner and CodeAct action mode (Chapter 14), a review subagent (Chapters 11 and 13).
17.3
File structure
minharness/
__init__.py
model.py # the ONE place you plug in a real model (Ch 2)
prompt.py # PromptBuilder + structured-item helpers (Ch 3)
context.py # estimate_tokens, CostModel, Compactor (Ch 4, 5)
tools.py # ToolRegistry, shell tool, truncation (Ch 6)
approvals.py # ApprovalPolicy, gated_call, Checkpointer (Ch 7)
parallel.py # run_tools (Ch 8)
memory.py # MemoryLoader (Ch 9)
skills.py # SkillLoader + mini MCP (Ch 10)
subagents.py # spawn_subagent, orchestrate (Ch 11)
control.py # HookManager, Budget (Ch 12)
agent.py # the loop that wires it all together (Ch 2 + everything)
main.py # CLI entry point
Each file is essentially the MVP from its chapter, lightly cleaned so the imports line up. Below is the integration layer, agent.py, which is the new code: the glue that turns eleven separate demos into one agent.
17.4
Step 1: the model seam
Everything depends on one function. This is the only place that talks to a real model, so it is the only place you change to go from toy to real.
# minharness/model.py
"""The single seam between the harness and a real model.
Swap the body of call_model for an Anthropic / OpenAI / local call.
It must return one of:
{"type": "text", "content": "..."} -> turn ends
{"type": "tool_calls", "calls": [{"call_id","name","args"}, ...]}
"""
def call_model(request: dict) -> dict:
# request has keys: instructions (str), tools (list), input (list) [Chapter 3]
#
# REAL VERSION (Anthropic example, pseudocode):
# resp = anthropic.messages.create(
# system=request["instructions"], tools=request["tools"],
# messages=to_messages(request["input"]), model="claude-sonnet-4-6")
# return parse(resp)
#
# For a runnable demo without an API key, we script a tiny behavior:
history = request["input"]
ran_tool = any(it.get("type") == "tool_result" for it in history)
if not ran_tool:
return {"type": "tool_calls", "calls": [
{"call_id": "c1", "name": "shell", "args": {"command": "ls"}}]}
return {"type": "text", "content": "Done. I listed the directory."}
17.5
Step 2: wire the loop
agent.py brings every component together. Read it top to bottom; the comments name the chapter each piece comes from.
# minharness/agent.py
"""The integration layer: one agent loop wiring every chapter together."""
from .model import call_model
from .prompt import PromptBuilder, user_msg, tool_call, tool_result
from .context import Compactor, estimate_items_tokens
from .tools import ToolRegistry, Tool, shell_handler
from .approvals import ApprovalPolicy, gated_call
from .parallel import run_tools
from .memory import MemoryLoader
from .skills import SkillLoader
from .control import HookManager, Budget, BudgetExceeded
from .subagents import spawn_subagent, VERIFIER
class MiniHarness:
def __init__(self, project_root: str, mode: str = "default"):
# --- Chapter 6: the tool registry (the agent's hands) ---
self.registry = ToolRegistry()
self.registry.register(Tool(
name="shell", description="Run a shell command",
parameters={"type": "object",
"properties": {"command": {"type": "string"}},
"required": ["command"]},
handler=shell_handler))
# --- Chapter 7: the safety gate in front of every tool ---
self.policy = ApprovalPolicy(allowlist=[r"^ls", r"^cat", r"^pytest"], mode=mode)
# --- Chapter 9 + 10: project memory and skills feed the prompt ---
self.memory = MemoryLoader(project_root)
self.skills = SkillLoader(f"{project_root}/.skills")
# --- Chapter 3 + 9 + 10: the prompt assembler ---
self.prompt = PromptBuilder(
base_instructions="You are minharness, a careful coding agent.",
project_instructions=self.memory.load_instructions(project_root),
skills_summary=self.skills.summary(),
cwd=project_root,
tools=self.registry.schemas())
# --- Chapter 4 + 5: context management ---
self.compactor = Compactor(max_tokens=8000, keep_recent=6)
# --- Chapter 12: deterministic control + budget kill switch ---
self.hooks = HookManager()
self.hooks.register("PreToolUse", _block_dangerous)
self.budget = Budget(max_turns=25, max_cost=5.0)
def _execute_call(self, call: dict) -> str:
"""One tool call: hooks -> approval -> registry (Ch 12, 7, 6)."""
veto = self.hooks.fire("PreToolUse", call)
if veto.get("block"):
return f"Exit code: 126\nBlocked by hook: {veto['reason']}"
return gated_call(self.registry, self.policy, call["name"], call["args"],
unattended=(self.policy.mode == "full-auto"))
def run(self, user_request: str) -> str:
history = [user_msg(user_request)] # Chapter 3
while True:
history = self.compactor.compact(history) # Chapter 5
request = self.prompt.build_request(history) # Chapter 3
try:
self.budget.charge(str(request), "") # Chapter 12
except BudgetExceeded as e:
return f"Stopped: {e}"
response = call_model(request) # Chapter 2
if response["type"] == "text": # turn ends
return response["content"]
# one or more tool calls: run them (parallel-safe) -> append results
calls = response["calls"] # Chapter 8
for c in calls:
history.append(tool_call(c["call_id"], c["name"], c["args"]))
results = run_tools(calls, lambda c: self._execute_call(c))
for r in results:
history.append(tool_result(r["call_id"], r["output"]))
def review(self, claim: str): # Chapters 11, 13
"""Optional: delegate an independent check to a verifier subagent."""
return spawn_subagent(VERIFIER, f"Verify: {claim}",
lambda h, m: "VERIFIED (stub)", self.registry)
def _block_dangerous(payload): # Chapter 12 hook
cmd = payload.get("args", {}).get("command", "")
if any(x in cmd for x in ("rm -rf", "git push", "curl")):
return {"block": True, "reason": f"dangerous command: {cmd!r}"}
17.6
Step 3: the entry point
# minharness/main.py
import sys
from .agent import MiniHarness
def main():
project = sys.argv[1] if len(sys.argv) > 1 else "."
agent = MiniHarness(project_root=project, mode="default")
print("minharness ready. Type a request (Ctrl-C to quit).")
try:
while True:
request = input("\n> ")
print(agent.run(request))
except KeyboardInterrupt:
print("\nbye")
if __name__ == "__main__":
main()
17.7
Step 4: run it
# from the directory that contains the minharness/ package
python -m minharness.main /path/to/your/project
With the scripted call_model, you will see the agent take a request, ask to run ls (gated by the approval policy and the hook), feed the result back, and finish with a text message. Replace the body of call_model with a real API call and the same harness becomes a real coding agent: now the model decides what to run, and every safety, memory, context, and budget mechanism you built is already wrapped around it.
17.8
How the chapters show up at runtime
Trace one real turn through the assembled system to see the whole guide working at once:
- You type a request. The loop wraps it as a structured
user_msg(Chapter 3). Compactorchecks the token count and summarizes old turns if the history is too big (Chapters 4, 5).PromptBuilderassembles instructions (withAGENTS.mdmemory from Chapter 9 and skill descriptions from Chapter 10), the tool schemas (Chapter 6), and the structured history, stable content first for caching (Chapter 5).Budget.chargechecks you have not blown the turn or cost cap (Chapters 4, 12).call_modelruns inference (Chapter 2). It returns a tool call.- The
PreToolUsehook (Chapter 12) and theApprovalPolicy(Chapter 7) both get a veto before theToolRegistry(Chapter 6) executes anything. Multiple calls run throughrun_tools(Chapter 8). - Results are appended with
call_idlinkage (Chapter 3) and the loop repeats. - Eventually the model returns text; the turn ends. For a risky claim, you can call
review()to spin up a verifier subagent (Chapters 11, 13).
That is the entire guide, running.
17.9
Where to take it next
The mini-harness is a foundation, not a finish line. Natural extensions, each pointing back to a chapter:
- Real sandboxing. Replace the bare
subprocesscall with an actual sandbox (containers, or the OS mechanisms from Chapter 7). This is the single most important hardening step before running it on anything you care about. - CodeAct mode. Add Chapter 14's code-action executor as an alternative to discrete tool calls, plus a
Plannerthat writes atodo.md. - MCP servers. Register external tools through the Chapter 10 MCP client to connect real systems.
- A real review pass. Wire Chapter 13's two-tier review (LLM plus a deterministic check) into
review(). - Budgets and observability for production. Persist a session log (Chapter 12), expose
max_budget_usdproperly (Chapter 16), and run it headless in CI with a human gate. - Deep research mode. Add Chapter 15's MasterAgent/SubAgent/ReviewAgent flow for sourced reports.
17.10
Connecting to the bigger picture
This is the payoff of the whole guide. Chapter 1 claimed the harness is the product and the loop is the small part; you just built a harness where the loop is maybe twenty lines and everything else, the prompt, the context management, the tools, the safety, the memory, the budgets, is the substance. Every component is a recognizable, simplified version of what Claude Code, Codex, Cursor, and Manus run in production. The ideas scale; the structure does not change.
17.11
Key takeaways
- The capstone is the eleven MVPs wired together: a loop (Ch 2) that builds prompts (Ch 3, 9, 10), manages context and budget (Ch 4, 5, 12), and runs tools (Ch 6) through an approval gate (Ch 7), in parallel (Ch 8), with optional subagents (Ch 11).
- There is exactly one seam to a real model (
call_model); swapping it turns the demo into a working agent, proving Chapter 1's point that the harness is the bulk of the work. - Safety is structural: every tool call passes a hook and an approval policy before executing, and a budget caps runaway loops.
- The architecture is small enough to read and faithful enough to scale; the production systems differ in polish and robustness, not in shape.
- Harden it next with real sandboxing, then extend with CodeAct, MCP, a two-tier review, observability, and research mode.
0 of 11 slides completed
Your learning progress stays in this browser.
Self-check · 10 questions
01 / 10
In the mini-harness, what is the significance of call_model?