How Claude Code Works: Inside the Agent Loop

A plain chat LLM session is a sequence of independent calls: you send text, the model predicts more text, and the only thing that persists between turns is the growing transcript you both keep re-reading. It has no filesystem, no shell, no way to check whether the code it suggested actually compiles. If the answer is wrong, you find out later, manually.

Claude Code wraps the same kind of model in a harness: a program that gives the model a defined set of tools (read a file, edit a file, run a shell command, search a codebase) and a loop that keeps calling the model, executing whatever it asks for, and feeding the result back in, until the model produces a plain-text answer with no further tool requests. The model still only predicts tokens — the harness is what turns some of those tokens into real filesystem writes and real subprocess execution, and what decides which of those writes are allowed to happen without asking you first.

Running example for this article: a Claude Code session in payments-api is asked to fix PAY-217 — a refund webhook that processes the same Stripe refund twice when Stripe retries a failed acknowledgment. We'll carry that ticket through the loop, the tool calls, the context that accumulates while investigating it, the permission check that fires when the agent goes looking for a secret, and a subagent spawned to search for other call sites with the same bug.

Every turn of the loop starts the same way: the harness assembles a context window from the system prompt, any loaded memory files (CLAUDE.md), and the transcript so far — the user's messages plus every prior tool call and its result. It sends that window to the model and asks for the next step.

The model's response is one of two shapes: plain text, which ends the loop and shows the reply to you, or a tool call — a structured request naming a tool and its input, such as Read with a file path, or Bash with a shell command. There is no separate "planner" module deciding what to do next; the plan is whatever the model reasons through in its own output, sometimes made visible by writing a checklist with a TodoWrite-style tool. When the model emits a tool call, the harness — not the model — executes it, captures the result (file contents, command stdout/stderr, a diff, or an error), and appends that result to the transcript as the next turn's input. Then the loop repeats.

For PAY-217, a typical loop looks like: read the webhook handler → grep for refund across payments-api to find related call sites → read the Stripe SDK's retry documentation the team keeps in /docs → propose an idempotency-key check → edit the handler → run the test suite → read the failure output → adjust → run again → report the fix. Each arrow in that chain is one full turn: model requests a tool, harness executes it, result comes back, model reads the result and decides the next step.

Claude Code ships a fixed catalog of built-in tools: file tools (Read, Write, Edit, Glob, Grep), an execution tool (Bash), web tools (WebFetch, WebSearch), a delegation tool (Task, covered below), and a few smaller utility tools. Each one is described to the model as a name, a short natural-language description, and an input schema — the model conditions on that description the same way it conditions on any other text, which is why vague tool descriptions produce vague, wrong tool calls just as vague prompts produce vague answers.

Bash is the one that matters most for how Claude Code touches your real project: it is a literal shell, running in your actual working directory. Git is not a separate "git tool" with its own logic — git status, git diff, and git commit are just Bash commands the model already knows how to type, which is also why permission rules can restrict individual git subcommands (Bash(git push:*)) without the harness needing any git-specific code. The same is true of test runners, linters, and build tools: the agent's ability to "run your tests" is entirely the model knowing your project's test command and the harness letting Bash execute it.

Before any tool actually runs, the harness checks it against the permission system (next section) — a tool call is a request, not an automatic action. File tools also enforce a smaller rule of their own: Edit typically refuses to modify a file the session hasn't Read yet in that same session, so the model can't blind-edit a file it never actually looked at, even if it remembers the file from an earlier unrelated task.

Every tool result becomes part of the context window for the rest of the session, whether or not it turns out to matter. Reading the webhook handler is a few hundred tokens; grepping refund across payments-api and reading every match to check relevance can be thousands. On a long PAY-217 investigation — read handler, grep repo, read Stripe docs, run tests three times, read three failure logs — the transcript keeps growing, and a full context window degrades answer quality well before it's technically exhausted, a mechanism covered in more depth in Context Rot in AI Agents.

Claude Code's answer is compaction: when the transcript approaches a threshold of the available context window, the harness summarizes the older portion of the session into a condensed digest — what files were touched, what was decided, what's still open — and replaces the verbose raw tool output with that summary, freeing headroom to keep working. You can also trigger it manually with /compact. This is a different mechanism from the subagent isolation covered next: compaction shrinks one window in place, mid-session; a subagent gets an entirely separate window from the start and never grows the parent's context at all (see Subagents Explained for that mechanism specifically).

Compaction is lossy by construction, which has a practical consequence: a constraint mentioned once early in a long session ("never touch legacy/", "the staging webhook secret rotates weekly") can get summarized away if it wasn't reinforced. That's the mechanism behind advice you'll see elsewhere to put durable rules in CLAUDE.md rather than only stating them mid-chat — CLAUDE.md is reloaded fresh each session rather than surviving as compressible transcript. For the general discipline of deciding what belongs in the window at all, see Context Engineering.

Every tool call is checked against a permission rule before it executes — matched by tool name and input pattern, such as Bash(git *) (allow) or Read(.env*) (deny). A call that matches neither an allow nor a deny rule falls back to the session's mode: default mode asks before edits and shell commands but lets reads run freely; plan mode blocks all side effects so the model can only read and propose, useful for a first pass before you've seen what it intends to touch; auto-accept edits skips the file-edit prompt for a faster loop while still gating Bash; and a bypass-permissions mode runs everything without asking, meant only for isolated, sandboxed environments where a wrong command can't reach anything you care about.

This matters because the model's own judgment is not the safety boundary — permission rules are enforced by the harness outside the model's reasoning, which is the point. A model can be wrong, or steered by content it read (a prompt-injection risk covered in Jailbreaking vs Prompt Injection), but a deny rule on Read(.env*) blocks the read regardless of what the model concluded it needed. Hooks (PreToolUse) add a further layer: a deterministic script that runs before the tool executes and can block it by exit code, independent of both the model and the static permission rules — see Claude Code Workflow for hook configuration in depth.

Back to PAY-217: while debugging why Stripe's signature check on the retried webhook fails, the agent reasons it needs the Stripe webhook signing secret and requests Read(.env). The rule set denies any .env* read outright. The tool call fails with a permission_denied result — not a crash, just another observation — and the model reads that denial, changes approach, and asks the user to paste the variable name it needs (STRIPE_WEBHOOK_SECRET) rather than its value, so it can grep for where that name is already referenced in code instead of ever seeing the secret.

Three mechanisms extend what a Claude Code session can do, and it's worth keeping them separate because they solve different problems. A subagent, spawned through the Task tool, is a second agent invocation with its own fresh context window and its own tool-call budget, given one bounded task and returning a compressed result rather than a transcript. For PAY-217, once the fix works in the webhook handler, the parent can spawn a subagent to fan out across payments-api searching for every other place that processes a Stripe event without an idempotency check — the search noise (dozens of files, hundreds of lines) stays in the subagent's disposable window; only a short list of file paths and line numbers crosses back. The full mechanism, including the tool-budget cutoff and why fan-out beats sequential search for independent slices, is covered in Subagents Explained.

MCP (Model Context Protocol) solves a different problem: giving the agent tools it doesn't ship with. Claude Code acts as an MCP host, connecting to MCP servers — local processes or remote endpoints — that expose additional tools, resources, or prompts, registered in .mcp.json or via claude mcp add. A Stripe MCP server, for example, could expose a list_recent_events tool that queries Stripe's API directly instead of the agent trying to reconstruct that from webhook logs. Once connected, an MCP tool behaves exactly like a built-in one inside the loop from section two — same request/permission/execute/observe cycle, just a larger tool catalog. See MCP vs A2A vs ACP for how MCP compares to adjacent agent protocols.

Skills solve a third, unrelated problem: packaging procedural knowledge, not adding capability. A skill is a markdown file with a description Claude matches against natural language to auto-invoke — "how this team writes commit messages," "how to run the payments-api migration checklist" — and it steers how existing tools get used rather than granting any new one. Confusing a skill with an MCP server is a common mistake: a skill can't call an external API on its own; it can only tell the model, in prose, how to use the tools it already has. See Claude Code Workflow for how to author one.