The goal

Stage 0 was a single messages.create call: it talks, it cannot act. Stage 1 makes the smallest change that turns talks into acts — it wraps that one-shot call in a loop. Each pass: hand the model a tool, read its stop_reason, run whatever tool it asked for, append the tool_result back onto the transcript, and call again — repeating until the model stops asking (stop_reason: end_turn). About 40 lines. Deliberately nothing else: no permission gate, no real filesystem hands beyond one toy tool, no compaction — those are stages 2–4. This stage isolates the one idea every agent is built on: the feedback loop that splices a tool's output back into the conversation that produced the request.

Build it

Walk tutorial/01-loop/agent.ts top to bottom. The transcript is a plain array, seeded with the user's task — it will grow as the loop runs:

const messages: Anthropic.MessageParam[] = [
  { role: 'user', content: process.argv[2] ?? 'What files are in this project? Look before you answer.' },
];

One toy tool, declared as a JSON schema so the model knows it exists (real hands arrive in stage 2):

const tools: Anthropic.Tool[] = [
  {
    name: 'list_files',
    description: 'List the files in a directory of the current project.',
    input_schema: {
      type: 'object',
      properties: { path: { type: 'string', description: 'directory to list, e.g. "."' } },
      required: ['path'],
    },
  },
];

Then the whole engine — a bare while (true):

while (true) {
  const res = await client.messages.create({ model: MODEL, max_tokens: 1024, messages, tools });
  messages.push({ role: 'assistant', content: res.content });

  for (const b of res.content) if (b.type === 'text') console.log(b.text);

  if (res.stop_reason !== 'tool_use') break; // the model stopped asking — we're done

  const results: Anthropic.ToolResultBlockParam[] = res.content
    .filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use')
    .map((tu) => {
      console.log(`  ⚙ turn ${++turn}: ${tu.name}(${JSON.stringify(tu.input)})`);
      return { type: 'tool_result', tool_use_id: tu.id, content: runTool(tu.name, tu.input as Record<string, unknown>) };
    });
  messages.push({ role: 'user', content: results });
}

Five phases per pass: ① call the model with the full transcript; ② push the assistant reply onto the transcript (print any text); ③ read stop_reason — if it is not tool_use, break (the model gave a final answer); ④ run each tool_use block through runTool, wrapping the output as a tool_result that carries the matching tool_use_id; ⑤ push those results back as a user-role message and loop. Two details are load-bearing: the tool_result must reference the request's tool_use_id, and results re-enter as a user turn — that is literally the hand passing the fetched item back through the window. Every tool round adds exactly two messages (one assistant, one user), which is why the closing line prints messages.length.

Run it

ANTHROPIC_API_KEY=… MODEL=claude-sonnet-5 bun run tutorial/01-loop/agent.ts "what files are here?"

A one-round transcript looks like:

I'll look before I answer.
  ⚙ turn 1: list_files({"path":"."})
Here are the files in this project: agent.ts, package.json, README.md, tsconfig.json.

[4 messages in the transcript — every tool round added 2]

Read the message count: seed user (1) → model asks for the tool, assistant pushed (2) → tool_result fed back, user pushed (3) → model answers with stop_reason: end_turn, assistant pushed (4) → break. One tool round, four messages.

对照 the real one

Each line of the toy loop has a direct counterpart in Claude Code's queryLoop:

• Our while (true) ↔ the real bare while (true) (claude-code/src/query.ts:307). Both are infinite loops exited only from inside.
• Our client.messages.create({ messages, tools }) ↔ the streamed model call deps.callModel({ ... }) (claude-code/src/query.ts:659).
• Our res.content.filter(b => b.type === 'tool_use') ↔ the collection step that pushes assistant messages and flips needsFollowUp = true the instant any tool_use block appears (claude-code/src/query.ts:826-844).
• Our if (res.stop_reason !== 'tool_use') break ↔ the branch if (!needsFollowUp) (claude-code/src/query.ts:1062) leading to return { reason: 'completed' } (claude-code/src/query.ts:1357). Note the difference: the real loop returns a Terminal rather than breaking, and it branches on a boolean accumulated during streaming rather than reading stop_reason directly.
• Our runTool(tu.name, tu.input) for each block ↔ runTools(toolUseBlocks, …) (or a concurrent streaming executor) (claude-code/src/query.ts:1380-1382).
• Our { type: 'tool_result', tool_use_id, content } collection ↔ the loop that normalizes each update and pushes it into toolResults (claude-code/src/query.ts:1384-1400).
• Our messages.push({ role: 'user', content: results }) — the feed-back — ↔ rebuilding the next state's messages as [...messagesForQuery, ...assistantMessages, ...toolResults] (claude-code/src/query.ts:1716).

Where our loop has exactly one path back to the top, the real one has seven (prompt-too-long recovery, reactive compaction, max-output-token escalation, stop-hooks, token-budget nudges…). The full turn cycle is dissected in 故事 · loop/1; those seven re-entry paths and the control machinery around them in 故事 · loop/2.

What breaks without it

Stage 0 (tutorial/00-bare-model/agent.ts) is the same messages.create call with no loop and no tools. Ask it "fix the failing test" and it answers from imagination — one assistant message, stop_reason: end_turn, conversation over. It never sees your repo because there is no phase that runs a tool and folds the result back in. The loop is the single addition that converts a monologue into an investigation. Crucially, without the loop it is pointless to even give the model a tool: a stop_reason: tool_use would be a dead end — the model would ask list_files(".") and nobody would ever run it, so the result never returns and the model stays exactly as blind as before. The while is what makes tool_use mean something.