# Subagents, hooks, and building something small

AI for Software Engineers, part 4.3 (10 of 22)

> A subagent is a separate conversation with the model that does the exploring in its own context and returns only a short summary, so your main context stays clean. Hooks are deterministic scripts the harness runs at fixed points, which makes them the place for rules that must hold every time.

If you use Claude Code, GitHub Copilot or Codex on a real repository, you've probably seen this. You ask for something, and before it touches any code the agent says it's exploring the codebase. Sometimes it says it's starting a subagent. A minute later it comes back with a neat paragraph about where things live, and only then starts the work.

Most people I talk to think subagents are about specialisation. A testing agent, a docs agent, a security agent, each one an expert. Or delegation, because agents can delegate. Both are true, and neither is the most important reason. Let me explain with an example.

Say you have a good codebase, a few hundred files, and you ask your coding agent to fix a bug in the payment retry logic. Before it can change anything, it needs context. It has to find the right modules, open files, follow calls from one place to another. You'd do the same on your first day.

Now, if it does all that reading in the same conversation you're talking to it in, every file it opens lands in your context. Twenty files, a few searches, some test output. By the time it understands the bug, it has used up a big chunk of your context window on exploration, and most of what it read was a dead end.

So it does something else. It starts a separate conversation with the model, a subagent, with a task like "find where payment retries are handled and explain how they work". The subagent reads as many files as it needs in its own context. When it's done, it sends back a short summary. Your main conversation only ever sees that summary, not the twenty files behind it. Claude Code's docs describe it the same way.

![The main chat sends a task to a subagent. The subagent reads twenty files in its own context and sends back only a short summary.](assets/04c-subagent-summary.svg)

*What does the main conversation actually see?*

So here's my question. Why do I say this is the main reason, and not specialisation?

Think back to the context articles. The model remembers nothing, so everything it knows about your task has to sit in the context window. That window is finite and quality drops well before it's full. Context is the scarcest thing your agent has. Specialisation makes an agent somewhat better at a job. Isolation decides whether your main conversation stays clean enough to do the job at all. OpenAI's Codex docs name the two problems directly, context pollution (useful information buried under noisy output) and context rot (quality dropping as the chat fills up). This is the "isolate" move from the context article.

If you've designed systems, this should feel familiar. You don't load a whole table into your service when you only need a count. You push the work to where the data is and bring back the aggregate.

Once you see it that way, the other benefits follow. Subagents can run in parallel, so three of them can explore three areas at once. Each one can get only the tools it needs, so an explorer can be read-only. That's least privilege. Claude Code's built-in Explore subagent works this way, and GitHub Copilot lets you restrict a custom agent's tools too. And yes, each one can also be specialised with its own instructions.

When shouldn't you use one?

When the task is small. For a change to one function, a subagent starts from zero and just adds a round trip. When the detail matters. The summary is lossy, and if the main agent needs the exact line or the exact error, a summary can drop the one thing that mattered. When the work needs a lot of back-and-forth with you, or several steps share the same context. And when cost matters. Each subagent does its own model calls, and Codex's docs say plainly that subagent workflows use more tokens than a single agent doing the same job.

Now three smaller pieces, briefly.

**Hooks** are your own scripts that the harness runs at fixed points in the loop, such as before a tool call, after a file edit, or when the agent stops. The important word is deterministic. A line in your instructions saying "never edit .env" is a suggestion the model may or may not follow. A hook that runs before every edit and blocks anything touching `.env` always runs. Claude Code, GitHub Copilot and Codex all document a pre-tool hook that can deny the call. If a rule must hold every time, don't leave it to the prompt. Put it in a hook or a permission setting. As we saw earlier, the model proposes and the harness decides what executes. A hook is you plugging into that decision. Deep dive: I describe the points where you can plug into a harness in [The Two Layers That Decide Whether Your Agent Survives](https://www.allsrc.dev/posts/agent-harness-and-governance-the-two-layers-that-decide/).

**Commands** are the slash commands you type, like `/review`. They're saved prompts you run on purpose. In Claude Code, custom commands have now been folded into skills, so a skill can be run as a command too.

**Plugins** are how you share all of this. A plugin bundles skills, subagents, hooks and MCP servers into one thing you install, often from a marketplace. Be careful, though. What a plugin runs, it runs as you, so read it like any dependency before you install it.

Step back for a moment and look at what your coding agent actually is. There's a loop that calls the model, tools it can use, a context it manages and compacts, subagents to keep that context clean, permissions and hooks that decide what's allowed to run, and checkpoints so you can undo. Every one of those is a harness decision, and a coding agent is the one harness most of us watch working every day. Notice what it does when it's confused, when it asks for permission, and when it compacts. You'll be making the same decisions yourself soon. And if you've heard of spec-driven development for coding agents, I come back to it in Part 5, right after the agent loop.

So now I want you to build something small.

Take an agent you already use. Pick one real API you care about, maybe your team's issue tracker or the GitHub API, and connect it through an MCP server, an existing one or a tiny one you write. Add some knowledge, a markdown file with your team's conventions or a short description of what the API's fields mean. Then give it one real task, like "summarise the open bugs assigned to my team and tell me which ones touch the payments module", and see what it does. Turn on a subagent for the exploring part and compare how much of your context is left afterwards.

Before you start, write down five prompts and what a good answer looks like for each, and run them before and after every change. That small list is your first test set for an agent, and we'll grow it later.

I haven't run this exact setup, so treat it as a sketch. The details depend on your tool and your API.

Up to now we've been using someone else's harness. Next, we look at what it takes to build your own.

## Common questions

### What are Claude subagents for?

Mainly for keeping your main context clean. A subagent is a separate conversation with the model that does the exploring in its own context, reading as many files as it needs, and sends back only a short summary. Running in parallel, read-only tools and specialised instructions follow from that.

### Claude skills vs agents vs commands: how do they fit together?

Commands are slash commands like /review, saved prompts you run on purpose, and in Claude Code custom commands have been folded into skills, so a skill can be run as a command too. A subagent is a separate conversation that works in its own context and returns a summary. Plugins bundle skills, subagents, hooks and MCP servers into one thing you install; skills themselves are covered in [Part 4.1](/learn/ai-for-software-engineers/instructions-skills-tools/).

### What are Claude Code hooks?

Hooks are your own scripts that the harness runs at fixed points in the loop, such as before a tool call, after a file edit or when the agent stops. They are deterministic: a hook that blocks edits to .env runs every time, while a line in your instructions is a suggestion the model may or may not follow. If a rule must hold every time, put it in a hook or a permission setting.