State

Five kinds of state

Halfway through fixing the auth test, Patch has a conversation, a step counter, files on disk, and a saved checkpoint. It also builds a fresh input for each model call. These are five kinds of state, and they differ in who holds them and how long they last:

World state
(files, databases, services)
   │ tools read it and change it
   ▼
Conversation + runtime state
(held by the runtime)
   │ save ──▶ Persistent state
   │          (checkpoints, logs)
   │ build context
   ▼
Context (one call's view)
   │
   ▼
Model

Conversation

After one tool call, Patch's conversation looks like this:

messages = [
    {"role": "user", "content": "The auth test fails. Fix it."},
    {"role": "assistant", "tool_calls": [
        {"id": "call_1", "name": "run_command",
         "arguments": {"cmd": "pytest tests/test_auth.py"}}]},
    {"role": "tool", "tool_call_id": "call_1",
     "content": "FAILED test_login_expired_token ... 1 failed, 11 passed"},
]

The conversation is the log of messages. It holds the user's request, the model's replies and tool calls, and the tool results, each tagged with its call id. New entries go on the end. Usually your runtime keeps this list, although some provider APIs can store it for you (chapter 0).

The conversation is not the same as the context. Early in a run they look identical, because the runtime sends everything. They drift apart once the log no longer fits in one model call, or once the runtime starts choosing what to send.

Context: a view rebuilt for every call

Before each model call, Patch's runtime runs a function like this:

def build_context(state, budget):
    parts = [system_prompt(), tool_definitions()]
    parts += render_task(state)                  # status, plan, last test result
    parts += recent_messages(state["messages"], budget)
    return parts                                 # a view, not a copy

The context is exactly what one model call receives. Your runtime builds it from state, sends it, and then discards it, much like a database view that is computed when you query it. So the same state can produce different contexts. A summary can stand in for old messages, and a large file can appear as a short preview plus a path.

If something is not in the context, the model cannot use it on that call. Chapter 4 is about choosing what goes in.

Runtime state

Halfway through a run, Patch's runtime holds variables like these:

state = {
    "messages": [...],
    "status": "running",        # running | waiting_for_approval | done | failed
    "step": 7, "max_steps": 30, # one counter for the whole run
    "cost_usd": 0.42, "max_cost_usd": 2.00,
    "todo": [{"task": "fix the expiry check", "status": "in_progress"}],
    "pending_approval": None,
    "files_read": {"auth/session.py": "sha:9f2c41"},   # path -> hash of the version read
    "files_changed": ["auth/session.py"],
    "last_edit_step": 5,
    "last_test": {"cmd": "pytest tests/test_auth.py", "exit": 0, "after_step": 6},
}

Runtime state is what the loop itself keeps track of. Some fields steer the loop, such as the step count, the budgets, and a pending approval. Almost every agent has these. Some record evidence, such as the files changed and the last test run. These come from the agent's done check, so they differ from agent to agent. Patch is judged by its tests, so it tracks the last test run. An expense agent would track the receipt, the policy check, and the filing instead. Some fields exist for the model: the todo list, for example, gets copied into each context.

The model never writes this object directly. It asks for tool calls, and your runtime updates state from what the tools returned, not from what the model claims happened. You can still give the model fields of its own. A todo tool lets it rewrite its list, and a notes or file tool lets it save anything under names it picks. Your runtime stores what the model writes there, but never treats it as evidence. If the model could set last_test, it could mark its own tests as passed.

The three file fields show why evidence fields exist. Each one lets your code check something instead of trusting it:

• files_read maps each file the model has seen to a hash of the version it saw. Before an edit, your code compares that hash with the file on disk. If the model never read the file, or the file changed after the read, your code refuses the edit and asks the model to read it again. Otherwise the model would edit from an old copy.
• files_changed lists the files this run edited. The reviewer and the pull request need that list. Scope checks read it, such as "no test file changed" (chapter 6), and so does the undo step that restores the originals.
• last_edit_step records the step of the latest edit to any file, because an edit anywhere can break a test. A passing test counts only if it ran after that step, as the done check below shows. This works for Patch because only edit_file changes code. If shell commands can change files too, save a hash of the workspace with each test run instead.

The message log holds the same facts, but in a form code cannot easily use. Compaction can summarize old reads away, and your code should not have to search a conversation to enforce a rule.

External world state

At step 3, Patch reads auth/session.py. At step 6, a teammate pushes a change to the same file. Patch's copy is now out of date, and nothing tells it so.

World state is everything the agent acts on: files, databases, tickets, and deployed services. It exists without the agent, and other people change it too. The agent only ever holds observations of it, taken at some moment through its tools. Even a write tool's report, such as "1 replacement made", is a claim that a later read can confirm.

Persistent state

If Patch's process crashes at step 7, only what it saved survives: the session log of the conversation, a checkpoint, and saved files such as the full test output.

Persistent state is whatever outlives the process. A checkpoint is a snapshot of runtime state written after a step, so the run can continue where it stopped. Around actions with side effects, such as sending an email, record the intent before the action and the outcome after it. A crash between the two then leaves an "outcome unknown" record you can check, instead of no record at all (chapter 12).

Which copy is true?

Patch's done check reads last_test, which says the tests passed at step 6. But Patch edited auth/session.py again at step 8, so that result no longer proves anything.

The same fact often lives in several places: the file on disk, an old read in the conversation, a line in a summary. A good default is that the world is the source of truth for facts about the world, and runtime state is the source of truth for facts about the run. Everything in the context is a copy that can go stale. So re-read a file before editing it, and record which step produced each result:

def tests_still_pass(state):
    t = state["last_test"]
    last_edit = state["last_edit_step"] or 0
    return t is not None and t["exit"] == 0 and t["after_step"] > last_edit

This check refuses "done" when the last edit came after the last passing test run.

The check uses step numbers instead of clock times because it needs only the order of events. Your loop owns the step counter, so the counter never jumps, and it moves with the checkpoint when another worker resumes the run. A clock can be reset, and two machines' clocks can disagree. Changes from outside the run, such as a teammate's push, never get a step number, so files_read compares hashes instead.

Events and reducers

This function updates Patch's state from one event at a time:

def apply(state, event):                   # old state + one event -> new state
    if event.type == "file_edited":
        if event.path not in state["files_changed"]:
            state["files_changed"].append(event.path)
        state["last_edit_step"] = event.step
    elif event.type == "tests_ran":
        state["last_test"] = {"cmd": event.cmd, "exit": event.exit_code,
                              "after_step": event.step}
    elif event.type == "approval_decided":
        state["approvals"].append((event.call_id, event.decision))
    return state

state = reduce(apply, events, initial_state())   # replay to rebuild

A dependable runtime records events like these and computes the current state by applying them in order. Front-end developers call such a function a reducer, and backend developers call the pattern event sourcing. Because the log keeps everything, your runtime can replay it after a crash, and you can step through it to debug a bad run.

State in a coding agent

For a coding agent, state usually includes these items:

So the model sees what changes its next decision. Your runtime keeps what it needs to run the loop, enforce rules, and check results.

What the model sees, and what it does not

Patch's state includes a cost counter and an API token for the issue tracker. Neither helps the model choose its next step, and the token would be dangerous in its context.

So decide, for each field, whether to show it, summarize it, point to it, or keep it out. Show what changes the next decision, such as the request, recent results, and the plan. Summarize old turns. Point to big files by path instead of pasting them: a path costs a few tokens, and a tool can fetch the file when needed. Keep out what your runtime enforces, and above all keep out credentials. A secret in the context can end up in a log, a commit message, or a reply (chapter 10).

Budgets are a judgment call. Showing "step 27 of 30" can help the model wrap up, but it can also make it rush.

The kinds overlap. A checkpoint is a saved copy of runtime state, and files on disk survive restarts too. So for each item below, pick the role it plays here:

State vs memory

Patch's step counter matters only during this run. The fact "this project uses PostgreSQL" matters next week too.

State serves the current run, and it is done when the run ends, although you may keep it for audits. Memory is information you choose to keep for future runs, along with a way to find it again. The two overlap: a saved session is persistent state, and when a later run searches it for a similar bug, it works as memory (chapter 5).

Running example: Patch gets a state object

Patch version 3 keeps a state object next to its message list. Its runtime fills it from tool results, and its done check now reads evidence from it: a passing test run that came after the last edit.

# Patch v2: the message list was the only state
- messages = [...]
# Patch v3: a state object the runtime owns
+ state = {
+     "messages": [...],
+     "status": "running",          # running | waiting_for_approval | done | failed
+     "step": 0, "max_steps": 30,
+     "files_read": {}, "files_changed": [],   # {path: hash}, [paths]
+     "last_edit_step": None,
+     "last_test": None,            # {"cmd", "exit", "after_step"}
+     "approvals": [],
+ }

Patch still sends the whole message list on every call, which stops fitting as runs get longer. Chapter 4 gives it a context builder.

What goes wrong

You decide, AI builds

Check yourself

Takeaways

• Keep anything that must survive in runtime state or storage, never only in the context.
• The world is the truth for world facts. Re-read before you write, and treat old results as stale once something changes.
• Show the model what changes its next decision. Keep control, enforcement, and secrets in your code.

Going deeper

• Scaling Managed Agents: Decoupling the brain from the hands (Anthropic, April 2026). The session is "the append-only log of everything that happened", kept outside the context and the loop, so a crashed loop restarts from it.
• Effective harnesses for long-running agents (Anthropic, November 2025). Each session starts with no memory, so the harness keeps state in a progress file, a feature list, and git, which the next session reads first.