How a coding agent works.

2.1 Anatomy of an agent call

Modern coding agents such as Claude Code, OpenAI Codex, Gemini CLI, Aider or the Kimi CLI are command-line programs. They connect a language model (usually over the network at the provider, sometimes locally) with tools on your machine. When you start such an agent, roughly the following happens:

1. The program assembles a starting context: a built-in system instruction from the vendor (“You are a coding assistant, you have these tools…”), possibly configuration files from your home directory and from the project, and your task.
2. It sends the context to the model and receives either text or a tool call in return.
3. It checks whether the tool call is allowed (permissions), executes it and appends the result to the context.
4. It repeats steps 2 and 3 until the model considers the task done, a limit kicks in or an error occurs.
5. It emits a final message — depending on the mode as text or as structured JSON with result, token usage and possibly a cost estimate.

Open full-size graphicOpen full-size graphic

The prompt is more than your task

When people talk about “the prompt”, they often mean only the sentence they type. In fact, an agent’s context consists of several layers:

The second layer is treacherous: many agents load configuration automatically — from your home directory (personal settings, plugins, connected services) and from the project directory. What is convenient when you work alone on your own code becomes a problem when an agent runs in someone else’s repository or on a shared machine: then someone else has a say in what the agent knows and may do. How the factory handles this is shown below in the practice box “Ephemeral HOME” and in detail in Chapter 8.

2.2 Tools and permissions

In Chapter 1 you learned: an agent can do everything its tools can do. Permissions are the layer that determines which tool calls are actually executed. They are the most important dial between usefulness and risk.

Typical permission models

• Ask on every action: The agent shows every write or execution step and waits for your confirmation. Safe, but tedious in everyday work — and useless without a human at the terminal.
• Allowlists: Certain tools or command patterns are allowed in advance, such as “edit files” or “mvn with any arguments”. Everything else is rejected or requires a confirmation.
• Denylists: Certain tools are explicitly blocked, such as writing for a pure review agent.
• Allow everything: Many agents have a mode that turns off all checks. It is meant for throwaway environments (a virtual machine that is deleted afterwards) — not for a machine with credentials, SSH keys and access to the corporate network.

The principle of least privilege

An agent should get exactly the permissions its task requires, and no more. For an agent that writes and tests code, that means, for example: read and write files in the project, run build and test tools, read-only Git commands. Not needed, on the other hand: arbitrary network access (curl, wget), deleting outside the project, git push. Commit and push are better handled by the surrounding system — then they are controlled and traceable.

A review agent (reviewer) needs even less: it should read and judge, but change nothing. This is exactly where a hard technical block is worth more than a friendly request in the prompt: “Please don’t change anything” is an instruction a model can misunderstand; a blocked write tool is a fact.

2.3 Headless: agents without a human at the terminal

In everyday work, many developers use agents interactively: you open a session in the terminal, enter a task, watch, answer questions, confirm actions. For automated workflows — CI pipelines, scripts, a control plane like the factory — you need headless operation: the agent receives its task as an argument, works through it and exits with a result.

In Claude Code the switch for this is --print (short -p); other CLIs have equivalents such as codex exec, gemini -p or, for Aider, --message together with --yes. What they all have in common:

• No follow-up questions possible. Nobody answers. The agent has to deal with ambiguity on its own — good instructions tell it how (record assumptions, choose the most conservative interpretation, clearly flag deviations).
• Permissions must be fixed in advance. An agent waiting for a confirmation that never comes either does nothing or asks for permission in its text output.
• Structured output. With an output format such as JSON, the result can be evaluated by machine: success or failure, token usage, possibly the CLI’s cost estimate.
• Time limits. A headless run needs an upper bound so that a hanging agent does not run forever.

claude --print --output-format json \
       --permission-mode acceptEdits \
       --allowedTools "Read,Glob,Grep,Bash(mvn *)" \
       "Read PROJECT.md and INSTRUCTIONS.md and start the implementation. ..."

2.4 Sessions and memory

A session is an agent’s continuous working history — everything that belongs together in one context window. Many agents can save sessions and resume them later. For reproducible, traceable work, however, this is of limited help: the content of a session is hard to inspect, is tied to one machine and one tool, and grows with every step.

It is more robust to keep persistent knowledge in files that live in the repository and are re-read on every run:

• Project description — what is being built and why.
• Working instructions — conventions, build commands, prohibitions.
• Memory — decisions and insights from earlier runs.
• The code itself and its Git history — the most reliable source for what has happened so far.

That way every run starts with a fresh, defined context, and the “memory” is human-readable, versioned and reviewable. The factory follows this strategy too: every run is a new headless call; whatever should persist between runs lives in the workspace (artifacts, MEMORY.md, code). Details in Chapter 3.

2.5 Models: which brain for which task?

Behind every agent there is a model, and most agents let you choose between several models. Without naming specific products — which change constantly — a few lasting criteria can be stated:

• Capability: Larger models are usually better at planning, architecture questions and hard bugs.
• Cost: They are also more expensive per token and often slower.
• Speed: Smaller models are suited to mechanical work and quick checks.
• Context window: How much fits into one call?
• Data residency and location: Where does the model run? May the code leave the company? For some environments only a locally operated model is an option.

A proven rule of thumb is: plan strong, implement cheap, review fast. Planning a project is rare but consequential — a strong model pays off here. The mechanical implementation of a clear plan also works with a mid-sized model. For reviews with a clear question, a small, fast model is often enough. How the factory maps this ranking (routing, team preference, role default) is covered in Chapter 10.

2.6 Why an agent run needs a lifecycle

If you simply call an agent in the terminal, there are exactly two states: running or done. That is not enough for controlled software development. You want to know: Is the working environment prepared? Is the run waiting for an approval? Is the check running right now? Has it failed, been cancelled, got stuck in a timeout? And you want to be able to intervene at certain points: pause, cancel, approve.

An explicit lifecycle with phases and statuses turns an agent run into a controllable process. Each phase has a clear task; each status change is an event that can be logged, evaluated and secured. This is the prerequisite for everything that follows in later chapters: approvals, quality gates, correction loops, evidence.

2.7 Separating planning from building

A common mistake when working with agents is to mix planning and implementation in a single run: “Figure out what makes sense next and implement it right away.” The agent then makes consequential decisions without you being able to see them beforehand, and the result is hard to review because intent and execution merge.

A separation is better: a planning run analyses the current state and proposes steps without changing production code. A human reviews the proposals, selects, prioritises. Only then does an implementation run carry out a selected step. The plan thus becomes a reviewable intermediate result — and the yardstick against which the implementation can be measured.

2.8 Access to the model: subscription or API key

A coding agent needs access to its model. There are basically two ways:

• API key: You get a key from the provider and pay by usage, typically per million input and output tokens. Transparent, good for teams and automation, but costs grow with usage.
• Subscription: Many providers let you use their coding agent with a personal subscription. You log in once interactively; the CLI stores the credentials locally. Billing is via the subscription and its usage limits, not per token.

Which terms apply to subscription use — especially for automated, headless use and for use by several people — is determined by the respective provider, and they change. Check them for your specific case before you use it. One important technical trap applies generally, though: if an API key is also set in the environment, the CLI may silently choose the paid API path even though you wanted to use the subscription.

Summary

• A coding agent is a CLI program: context (system prompt, configuration, task, history) + tools + permissions + model.
• Least privilege: keep write and execute permissions narrow, make review agents technically read-only, “allow everything” only in throwaway environments.
• Headless means: no follow-up questions, permissions in advance, structured output, time limit.
• Persistent knowledge belongs in files in the repository, not in sessions.
• The factory calls agents via execution adapters and takes every run through seven phases with clear statuses, approval gate and inline diff.
• PLAN runs propose, BUILD runs implement.
• In subscription mode the factory strips API keys, reports costs as an estimate and isolates every run with an ephemeral HOME.

Chapter questions

1. Which layers make up the context of a coding agent, and which of them is particularly sensitive in terms of security?

   Model answer

   The vendor’s system prompt, automatically loaded configuration and memory files (home directory, project), the task and the working history. The sensitive one is the automatically loaded configuration: it can come from external sources (personal plugins, connected services, settings of an imported repository) and then has a say in what the agent knows and may do.

2. Why is it not enough to tell a review agent in the prompt that it should not change anything? How does the factory solve this?

   Model answer

   An instruction in the prompt can be misunderstood or ignored; a technical block cannot. The factory starts Claude Code reviews with --permission-mode dontAsk and --disallowedTools for Edit, Write and Bash — the reviewers are thus technically read-only.

3. What changes when an agent runs headless instead of interactively? Name at least three points.

   Model answer

   Nobody answers follow-up questions, so the agent has to deal with ambiguity itself (record assumptions). Permissions must be fixed in advance, otherwise the agent writes nothing or merely asks for permission in its text. The output should be structured (e.g. JSON) so it can be evaluated by machine. And it needs a time limit.

4. Why does the factory reject --dangerously-skip-permissions, even though it could make the agent more productive?

   Model answer

   Because the agent CLI runs on the host and not in a throwaway VM. Without permission checks, the agent could execute arbitrary commands — delete files, access the network, read credentials. Instead, the factory uses acceptEdits with a narrow allowlist.

5. Name the seven phases of a run in the correct order and explain in which phase the build gate runs.

   Model answer

   INTAKE, PROMPT_ASSEMBLY, WORKSPACE_PREPARATION, EXECUTION, VALIDATION, CORRECTION, COMPLETION. The build gate (mvn verify) runs in VALIDATION; if it fails, CORRECTION follows with automatic feedback (up to two attempts).

6. You use Claude subscription mode but forgot that ANTHROPIC_API_KEY is still set in your shell. What happens in a factory run, and what would happen without the factory?

   Model answer

   In subscription mode the factory actively removes the key from the subprocess; the run goes through the subscription. Without this measure, the CLI could prefer the key and silently bill via the paid API. It is still cleaner not to have the key in the environment in the first place.

7. What is the purpose of separating PLAN and BUILD runs?

   Model answer

   The PLAN run produces reviewable proposals (plans/NNNN-*.md with scope and acceptance criteria) without changing production code. A human selects and prioritises; only the BUILD run implements. This makes consequential decisions visible before they become code, and gives the implementation a yardstick.

8. A colleague is surprised that the MCP server he set up personally is not available in factory runs. Is that a bug?

   Model answer

   No, it is intentional. Every agent call gets a fresh, empty HOME; only the credentials are carried over. Personal MCP servers, plugins, hooks and settings have no effect (MCP null state, ADR-0017). Approved, read-only MCP tools can be provided selectively via the MCP gateway (Chapter 8).

9. Transfer: Your team wants to use a local model instead of a cloud provider in future. What changes in the factory process, and what stays the same?

   Model answer

   What mainly changes is the adapter configuration (local-llm with an OpenAI-compatible backend such as Ollama or vLLM) and possibly the model’s expected quality and speed. What stays the same are project artifacts, guardrails, run lifecycle, branch per run, build gate, quality gate, approvals and audit — that is exactly the point of the adapter layer.