The goal

Stage 1 gave the model one toy tool and a while (true) loop. Stage 2 makes the hands real — and safe. Three things arrive together:

1. A machine-readable spec per tool. Each tool ships a JSON input_schema the model reads before it ever calls: the schema is how the model learns what arguments a tool needs. That is the 规格牌 nailed beside each port.
2. A validate-before-run boundary. Before any file is written or any shell command runs, the harness measures the model's proposed arguments against the spec. Wrong shape → the side effect never fires. That is the 卡尺.
3. Every failure becomes a tool_result the model can read. Unknown tool, malformed input, or a genuine crash inside the tool body — each is caught and returned as an is_error result, not thrown. The loop survives every failure and the model gets a chance to repair. That is the 接盘.

The whole point: side effects are dangerous, and the model "is not great at generating valid input." Stage 2 puts one small gate between the model's guess and the real world.

Build it

The unit is a ToolDef — a spec the model reads, a validate that gates, and a run that acts (tutorial/02-tools/tools.ts):

export interface ToolDef {
  spec: Anthropic.Tool;
  validate(input: Record<string, unknown>): string | null; // null = OK
  run(input: Record<string, unknown>): string;
}

The spec is the caliper's readable face — a real JSON schema declaring the required fields and their types. Here is bash:

spec: {
  name: 'bash',
  description: 'Run a shell command; returns stdout (stderr is included when the command fails; 30s timeout).',
  input_schema: {
    type: 'object',
    properties: { command: { type: 'string', description: 'the command to run' } },
    required: ['command'],
  },
},
validate: (i) => (typeof i.command === 'string' && i.command.trim() !== '' ? null : 'command must be a non-empty string'),

The whole safety story lives in one function — executeTool. It is the wall:

export function executeTool(name: string, input: Record<string, unknown>): { content: string; isError: boolean } {
  const def = toolRegistry[name];
  if (!def) return { content: `invalid input: unknown tool "${name}"`, isError: true };
  const problem = def.validate(input);
  if (problem) return { content: `invalid input: ${problem}`, isError: true };
  try {
    return { content: def.run(input) || '(no output)', isError: false };
  } catch (e: any) {
    return { content: `tool error: ${e.message}`, isError: true };
  }
}

Read it top to bottom: unknown tool → is_error (no lookup crash); validate returns a message → is_error before run is ever entered; only a null from validate lets control reach run; and even then a throw inside run is caught and turned into an is_error. Three failure classes, one boundary, zero uncaught exceptions.

The loop (tutorial/02-tools/agent.ts) hands each tool_use block to that boundary and feeds the verdict straight back to the model:

const { content, isError } = executeTool(tu.name, input);
if (isError) console.log(`  ✗ ${content}`);
return { type: 'tool_result', tool_use_id: tu.id, content, is_error: isError };

The tools the model sees are literally Object.values(toolRegistry).map((d) => d.spec) — the same specs the caliper validates against are the ones sent to the API. Beyond the tool wiring, the loop carries only two deliberate micro-changes from stage 1: max_tokens grows 1024 → 2048, and stage 1's closing [N messages in the transcript — every tool round added 2] log is dropped.

Run it

ANTHROPIC_API_KEY=… bun run tutorial/02-tools/agent.ts "create hello.txt saying hi"

Expected transcript (the model reads the specs, then reaches through the ports):

I'll create the file.
  ⚙ write_file({"path":"hello.txt","content":"hi\n"})
Done — hello.txt now contains "hi".

Now feed it something that fails inside the tool — "read the file /nope/ghost.txt". The read_file spec validates (a non-empty string path), run throws ENOENT, the boundary catches it, and the model gets a repairable error instead of a dead process:

  ⚙ read_file({"path":"/nope/ghost.txt"})
  ✗ tool error: ENOENT: no such file or directory, open '/nope/ghost.txt'
That path doesn't exist — did you mean ./ghost.txt in the project root?

对照 the real one

The 80 lines above are the toy of a boundary Claude Code implements at scale.

• The spec / the caliper's face. Our ToolDef.spec.input_schema is the toy of the real Tool contract's readonly inputSchema (claude-code/src/Tool.ts:394), one field of the full Tool type (claude-code/src/Tool.ts:362). Claude Code uses a Zod schema rather than a hand-written validate, but the role is identical: the declared shape the model's arguments are measured against.
• Validate before run — the one chokepoint. Our executeTool runs def.validate(input) before def.run(input). The real harness routes every tool_use through checkPermissionsAndCallTool (claude-code/src/services/tools/toolExecution.ts:599), whose first act is tool.inputSchema.safeParse(input) (claude-code/src/services/tools/toolExecution.ts:615) — annotated in the source with the reason: "the model is not great at generating valid input."
• A failure is a message to the model, not a throw. Our { isError: true } branch mirrors the real early-return that hands back a tool_result carrying <tool_use_error>InputValidationError: …</tool_use_error> (claude-code/src/services/tools/toolExecution.ts:670) — a precise, model-readable rejection naming the offending field.
• The layered ordering. Our $validate → run$ is the real $inputSchema.safeParse → validateInput → checkPermissions → call$ chain: the tool's own validateInput (claude-code/src/Tool.ts:489), then checkPermissions which by contract "is only called after validateInput() passes" (claude-code/src/Tool.ts:500), then finally await tool.call(...) (claude-code/src/services/tools/toolExecution.ts:1207). Each guard runs only once the cheaper one before it has passed — exactly our unknown-tool → validate → run order.

Read the full boundary — schema parse, InputValidationError, the run-only-after-validate ordering — in the deep-dive: /stories/tools/1/.

What breaks without it

Stage 1's tutorial/01-loop/agent.ts had no spec and no boundary — just a bare dispatch:

function runTool(name: string, input: Record<string, unknown>): string {
  if (name === 'list_files') return readdirSync(String(input.path ?? '.')).join('\n');
  return `unknown tool: ${name}`;
}

Two things break. First, a crash-inducing input kills the whole process. readdirSync('/does-not-exist') throws ENOENT; nothing catches it; the exception escapes runTool, escapes the .map, escapes the while (true) — the agent dies mid-conversation and the model never learns why. Stage 2's outer try/catch in executeTool turns that same throw into { content: 'tool error: …', isError: true } and the loop keeps going.

Second, failure is invisible to the model. An unknown tool returns the plain string unknown tool: … as an ordinary (non-is_error) result, so the model can't distinguish "it worked" from "it failed" — no is_error flag exists to set. And with no schema at all, malformed arguments flow straight into the tool body, where they either crash far from their cause or "succeed" on garbage. Stage 2's spec + validate stop the wrong-shaped hand at the port, and its is_error flag tells the model exactly which failure it hit — so it can fix the call and retry.