Tools & the execution environment.

Tools are how a "brain in a jar" grows hands. A tool is two things: a schema (a contract telling the model what it can call and with what arguments) and an implementation (the code the harness runs when the model calls it). This module covers the tool contract for the canonical set — read, write, edit, bash, search — how to stream tool calls into a live terminal UI, the permission gates that make an agent safe to run on your machine, and the blast-radius problem that sandboxing solves. You build real file and shell tools wired into your loop, so your harness edits actual code — safely.

Module 1 ended with a loop that could call one toy tool. That's the skeleton. This module puts real muscle on it: the tools that let an agent actually do things — read your files, write new ones, edit in place, run shell commands, search a codebase. This is the layer where an agent stops being a clever chatbot and starts being dangerous in the useful sense: it can change the state of your machine. Which means this is also the layer where safety stops being optional.

Tool schemas as contracts

A tool is a contract between the model and your code. The model never runs anything itself — it emits a structured request ("call edit with these arguments"), and your harness fulfills that request. The schema is the contract that makes this reliable: it tells the model exactly what tools exist, what each does, and what arguments each expects, in a machine-checkable form.

{
  "name": "edit",
  "description": "Replace an exact string in a file with a new string. "
                 "The old_string must match exactly once, including whitespace.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path":       {"type": "string", "description": "file to edit"},
      "old_string": {"type": "string", "description": "exact text to replace"},
      "new_string": {"type": "string", "description": "replacement text"}
    },
    "required": ["path", "old_string", "new_string"]
  }
}

Three things make a tool schema good, and they're where most tool bugs actually live:

• The description is a prompt. The model decides when and how to use a tool almost entirely from its description. "Replace an exact string… must match exactly once" teaches the model the tool's contract and failure mode in advance. A vague description ("edits a file") produces sloppy calls. The description is the highest-leverage prose in your whole harness — treat it like the critical prompt it is.
• The schema is a guardrail. required fields and types are validated before your code runs, so a malformed call is rejected structurally rather than crashing your implementation. The schema turns "the model might send garbage" into "the model gets a clear error and retries."
• Return values are observations. Whatever the tool returns goes straight back into the model's context as the result of its action. So tool output is prompt too — it should be concise, informative, and, on failure, tell the model how to fix its call (Module 3 goes deep on keeping these outputs small).

The canonical tool set

Across harnesses, a small set of tools recurs because it's sufficient for an astonishing range of work. pi's entire thesis is that a coding agent needs just four: read, write, edit, bash. Most others add search (grep/glob) as a distinct tool for efficiency. What each is for:

Streaming tool calls into a terminal UI

A harness that only shows the final answer feels dead during long tasks. Real harnesses stream: as the model generates, tokens flow to the terminal live, and — critically — the harness surfaces each tool call the moment it's parsed, not after the whole turn. The user watches the agent think ("I'll read the config first…"), sees the tool call render, sees the result, and sees the next thought. That live feedback is most of what makes an agent feel alive and trustworthy.

Mechanically, the model API returns a stream of events: text deltas, tool-call starts, argument deltas, and tool-call completions. Your harness consumes that stream, prints text as it arrives, and — when a tool call is fully assembled — pauses generation, executes the tool, appends the result, and continues the loop. Streaming is a UX layer over the same loop from Module 1; it changes nothing about correctness, but everything about whether a human will actually sit with the agent.

Permission gates and approval modes

Now the sharp edge. Your agent can run bash. That means it can run rm -rf, git push --force, curl … | sh. The model is usually well-behaved, but "usually" is not a security model. This is why Claude Code asks before destructive actions — a permission gate sits between the model's tool request and its execution.

The design has two parts. First, a classifier: reads are safe (auto-allow), writes and edits are moderate (ask, or auto-allow within the project), and bash is risky (ask, or match against allow/deny lists — git status fine, rm -rf / never). Second, an approval mode that sets the default posture:

• Manual / plan mode — the agent proposes; the human approves every action. Maximum safety, minimum autonomy. Right for unfamiliar tasks or production systems.
• Auto-edit — file edits within the project run without asking; shell commands and anything outside the project still prompt. The common daily-driver mode.
• Full-auto — nothing is asked. Only safe inside a sandbox where the blast radius is contained (next section), because you've removed the human tripwire.

pi, notably, ships without permission popups by design — its answer is "run it in a container or build a permission gate as an extension." That's a legitimate choice: it pushes the safety decision to you rather than baking in a default. Claude Code makes the opposite choice and asks by default. Neither is wrong; the point is that permission handling is a first-class harness decision, not an afterthought — you must choose a posture deliberately.

Sandboxing and the blast-radius problem

Permission gates rely on a human being present to say yes or no. But autonomous agents run unattended, and even attended ones, a human clicking "approve" fifty times stops reading carefully. The deeper protection is to shrink the blast radius — the maximum damage a tool call can do — so that even a bad action is survivable.

That's sandboxing: run the agent's tools in an isolated environment where the damage is contained. Levels, from loose to strict:

The key insight: sandboxing lets you turn up autonomy. A full-auto agent is terrifying on your bare laptop and perfectly reasonable inside a network-isolated container with a mounted working copy — because the worst case is "the container is broken, throw it away." Sandboxing and approval modes are the two dials of the same control: approval keeps a human in the loop; sandboxing removes the need for one by capping the damage. Production autonomous harnesses lean on sandboxing precisely so they can run without a human clicking approve.

Code-mode vs tool-mode

A newer distinction worth understanding. In the classic tool-mode, the model makes one structured tool call at a time — call read, see the result, call edit, see the result. Clean and observable, but chatty: each action is a full round-trip through the model.

In code-mode, the harness gives the model a single powerful tool — a code interpreter (often just bash with a language runtime) — and the model writes a script that does several actions at once: read five files, transform them, write the results, all in one block of code the harness executes. This is more token-efficient (one round-trip does the work of many), lets the model use loops and conditionals the tool interface can't express, and often matches how the model "wants" to think. The cost is observability and safety: a script is a bigger, more opaque action than a single typed tool call, so code-mode leans even harder on sandboxing.

You build — real file and shell tools

Extend the Module 1 harness. The loop is unchanged; we swap the toy tool for a real tool set and insert a gate before execution.

import subprocess, pathlib

ROOT = pathlib.Path.cwd().resolve()          # working-dir scope (blast radius)

def _safe(path):                              # keep edits inside ROOT
    p = (ROOT / path).resolve()
    if not str(p).startswith(str(ROOT)):
        raise ValueError(f"path escapes working dir: {path}")
    return p

def read(path):
    lines = _safe(path).read_text().splitlines()
    return "\n".join(f"{i+1:>4} {l}" for i, l in enumerate(lines[:200]))  # numbered window

def write(path, content):
    _safe(path).write_text(content); return f"wrote {path} ({len(content)} bytes)"

def edit(path, old_string, new_string):
    p = _safe(path); text = p.read_text()
    if text.count(old_string) != 1:           # the exact-match contract
        return f"ERROR: old_string must match exactly once (found {text.count(old_string)})"
    p.write_text(text.replace(old_string, new_string)); return f"edited {path}"

def bash(command):
    r = subprocess.run(command, shell=True, cwd=ROOT, capture_output=True, text=True, timeout=60)
    return f"exit={r.returncode}\nstdout:\n{r.stdout[:4000]}\nstderr:\n{r.stderr[:2000]}"

TOOL_IMPL = {"read": read, "write": write, "edit": edit, "bash": bash}

# ---- the permission gate ----
SAFE = {"read"}                               # auto-allow
def gate(name, args):
    if name in SAFE:
        return True
    verb = "RUN" if name == "bash" else name.upper()
    print(f"\n  ⚠ {verb}: {args}")            # show the exact action
    return input("  approve? [y/N] ").strip().lower() == "y"

def run_tool(name, args):
    if not gate(name, args):
        return "DENIED by user"               # denial is an observation, not a crash
    try:
        return TOOL_IMPL[name](**args)
    except Exception as e:
        return f"ERROR: {e}"                  # errors feed back so the model self-corrects

Drop these read/write/edit/bash schemas into the TOOLS array from Module 1, point run_tool at this version, and your loop is now a real coding agent. Ask it to "add a docstring to foo() in utils.py and run the tests" and watch it read the file (auto-allowed), propose an edit (it asks — you approve), and bash the tests (it asks — you approve). Every safety idea from this module is in those ~30 lines: the schema contract, the _safe working-dir scope (blast radius), the gate with allow/ask, denial-as-observation, and error-as-observation.

FAQ

Takeaways

• A tool = a schema (contract) + an implementation. The description is a prompt; the schema is a guardrail; the return value is an observation.
• The canonical set is small — read, write, edit, bash (+ search). bash is the general-purpose escape hatch and the most dangerous tool.
• Stream tokens and tool calls live; it's a UX layer over the same loop and it's what makes an agent feel alive.
• Permission gates classify each call (allow/ask/deny) and an approval mode sets the default posture; also your defense against prompt injection.
• Sandboxing shrinks the blast radius so you can safely turn autonomy up — approval and sandbox are the two dials of the same control.
• Code-mode vs tool-mode: general code execution is efficient and composable; typed tools are legible and gate-able. Use both, per action.

References & further reading

• pi coding-agent README — the four-tool thesis and tool allow/block lists.
• LangChain — Anatomy of an Agent Harness — code execution, sandboxes, allow-listing.
• Anthropic — Tool use — schemas, tool_use / tool_result mechanics, streaming.
• Firecrawl — What Is an Agent Harness? — execution environment and sandboxing.
• Model Context Protocol — a standard way to expose external tools to a harness (Module 5).