← Patterns

Running agents
AI helps us move at lightspeed. There's no time to write everything up. So I've used my personal voice and based this on my actual work, to be able to share in real time what I'm doing with the teams I work with.

Running agents

Agents say how they stopped

Every turn an agent takes, one stretch of work from being asked to stopping, ends with one label from a closed list, saying what it asks of you, or that it asks nothing. An unlabelled stop is sent back once. It is a large part of how Fibers, the tool I use to run many agents at once, decides which of them need me.

One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.

An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.

The problem

When several coding agents work at once, each one works for a while and then stops. A stopped agent may be finished, waiting on an automated check, wanting you to choose, wanting you to merge, or leaving you a manual step. On a list of sessions they all look the same: idle.

The agent did say which, in prose, at the end of a long message, in a tab you have not opened. When I read the final messages of the 40 most recent sessions that showed as idle, 17 had left me something real, such as a decision, a review or a manual step. The list showed all of them as idle.

I'd also given agents a way to mark themselves as blocked, which they could use if they chose to. Of the 11 asks that actually stopped the work, one was marked.

The idea

Why the agent stopped is the one fact only the agent can state. Everything else about a session, the commands it ran and the files it changed, a script can record. So make the agent state it, from a closed list, at the end of every turn.

The enforcement is a stop hook, a small script the agent's runtime calls when the agent stops, which can refuse the stop with a reason. If the turn has no label, it refuses once, with the whole list in the reason. It never refuses twice in a row, so an agent can't get stuck in a loop.

How Fibers does it

Fibers is a tool I made to keep track of many AI coding agents at once. Each agent session registers itself when it starts, and Fibers lists them all in lanes: needs you, active, blocked and idle. The lane is what I read first. Before the labels, a session that had stopped to ask me something sat in idle with the rest.

Fibers plugs into the agent tool through hooks, small scripts the tool runs at set moments. When a session stops, the stop hook looks for a label on that turn. If there is none, it refuses the stop once. The agent then runs one command, fibers turn, with the label and a one-line note, and stops again. A label that asks something moves the session into the needs-you lane, and the note is the line I read there.

An agent can also flag itself part-way through a turn, with fibers log blocked, which puts it in the same lane. Every refusal is logged on the machine, and fibers turn stats prints the cost per day: refused stops, and the time and tokens the extra step added. The figures under Trade-offs come from that log.

The agent tools are starting to do part of this themselves. The Claude Code desktop app now writes a short summary after each turn, with a question when something waits on you. In my sample of 40 sessions, that summary plus a check for a closing question mark caught 13 of the 17 that needed me. The four it missed were all manual steps written as statements.

Fibers also has hooks for Codex and Cursor, so the same lanes can cover their sessions. I haven't checked which of those tools say by themselves how a turn ended.

It is still a trial. The labels are switched on for my own machines only, and I haven't decided whether they stay.

A version small enough to read

Eight labels, in two groups. Five ask a person something: merge-ready, choose (pick between options), go-ahead (an offer waiting for a yes), manual-step and stuck. Three ask nothing: stopping (finished), still-working, and waiting (on a check, a queue or another session). An asking label needs a one-line note, and two of them need a flag saying whether the work is blocked until you act.

stop-labels/stop.ts
// A closed set of labels for how an agent's turn ended, and a stop hook that
// refuses an unlabelled stop once. Run: bun stop.ts
const ASKS = ["merge-ready", "choose", "go-ahead", "manual-step", "stuck"] as const;
const QUIET = ["stopping", "still-working", "waiting"] as const;
const NEEDS_BLOCKS = ["choose", "manual-step"];
const STALE_MS = 30 * 60 * 1000;
type Label = { label: string; note?: string; blocks?: boolean; at: number };
// The command an agent runs to label its turn. Returns an error, or null.
export function check(l: Label): string | null {
const all: readonly string[] = [...ASKS, ...QUIET];
if (!all.includes(l.label)) return `Unknown label "${l.label}". Use one of: ${all.join(", ")}.`;
const asks = (ASKS as readonly string[]).includes(l.label);
if (asks && !l.note) return `"${l.label}" asks something of a person, so add a one-line note saying what.`;
if (NEEDS_BLOCKS.includes(l.label) && l.blocks === undefined) return `"${l.label}" needs --blocks yes or no.`;
return null;
}
// The stop hook. `raw` is whatever the label file holds; `afterRefusal` is set
// by the runtime when this stop follows a refusal.
export function stop(raw: string | undefined, afterRefusal: boolean, now: number): string {
if (afterRefusal) return "allow"; // never refuse twice
let l: Label | undefined;
try {
l = raw ? JSON.parse(raw) : undefined;
} catch {
return "allow"; // a broken file must not trap the agent
}
if (l && now - l.at > STALE_MS) l = undefined; // left over from an earlier turn
if (l && check(l) === null) return "allow";
return `refuse: label this turn, then stop. Asks a person: ${ASKS.join(", ")}. Asks nothing: ${QUIET.join(", ")}.`;
}
if (import.meta.main) {
const now = Date.now();
const cases: [string, string | undefined, boolean][] = [
["no label", undefined, false],
["no label, second stop", undefined, true],
["labelled merge-ready with a note", JSON.stringify({ label: "merge-ready", note: "PR 12 is green", at: now }), false],
["labelled choose, no blocks flag", JSON.stringify({ label: "choose", note: "A or B?", at: now }), false],
["label from an hour ago", JSON.stringify({ label: "stopping", at: now - 3_600_000 }), false],
["label file is broken", "{not json", false],
];
for (const [name, raw, after] of cases) console.log(`${name.padEnd(34)} ${stop(raw, after, now).split(":")[0]}`);
console.log(`\nThe refusal says:\n ${stop(undefined, false, now)}`);
console.log(`\nlabel "done":\n ${check({ label: "done", at: now })}`);
console.log(`label "stuck" with no note:\n ${check({ label: "stuck", at: now })}`);
}

Run with Bun, a JavaScript runtime, it prints:

What the hook says
no label refuse
no label, second stop allow
labelled merge-ready with a note allow
labelled choose, no blocks flag refuse
label from an hour ago refuse
label file is broken allow
The refusal says:
refuse: label this turn, then stop. Asks a person: merge-ready, choose, go-ahead, manual-step, stuck. Asks nothing: stopping, still-working, waiting.
label "done":
Unknown label "done". Use one of: merge-ready, choose, go-ahead, manual-step, stuck, stopping, still-working, waiting.
label "stuck" with no note:
"stuck" asks something of a person, so add a one-line note saying what.

Where the plain form falls short

The plain form is a closing message and an optional way for the agent to mark itself blocked. These are the gaps I found in it.

  • An optional flag is mostly left unset. One in eleven, above. With the label required and a refusal behind it, 84% of stops were labelled first time, and nearly all the rest on the second try.
  • Some asks block and some can wait. Agents end on questions by habit, and many are offers. The flag for whether the work is blocked separates "nothing moves until you answer" from "shall I also do this?".
  • An ask can erase itself. I saw an agent mark itself blocked and then end its turn a minute later, and the ordinary end-of-turn update cleared the ask. Labelling the turn itself, at the moment it ends, avoids that.
  • A guard that traps the agent is worse than no guard. So the hook fails open. An unreadable label file lets the stop through, and so does a second stop, a stop by a sub-agent, a helper the main agent starts for one task, or any error in the hook.
  • A label from an earlier turn is not about this one. A label older than the turn could be is dropped.

Trade-offs

  • Refusals cost tokens. A refused agent re-reads its context to add the label, and tokens, the units of text a model is billed for, are spent on that. On one machine, over the first 17 days, 1,566 of 9,682 stops were refused, which is 16%, and each refusal added a median of 9.3 seconds. The rate fell from 53% on the first day to about 13% by the end, and a line at the start of each session now tells the agent the rule.
  • A label is a claim. It is true when written and may be stale when you read it. If accuracy matters, have a second reader label the same turns without seeing the first label, and count how often they agree.
  • One label per turn is sometimes not enough. When I tried labelling old sessions by hand, about a fifth needed two. I've kept one, with a note.

When to use it, and when not to

It suits anyone running several agent sessions at once who looks at a list to decide where to go next. With one agent in one window, the closing message is right in front of you, and the label adds cost for nothing. It also needs a runtime that lets a script refuse a stop.

Example. The labels and the stop hook, on GitHub

A draft skill for this pattern

A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/stop-labels/. It is a draft, and I haven't tried it on anyone else's project yet.

stop-labels/SKILL.md
---
name: stop-labels
description: Use when running several coding agents at once and a person has to tell, from outside, which stopped sessions need them. Every turn ends with one label from a closed list, and an unlabelled stop is refused once.
---
# Stop labels
When an agent stops, it has finished, or it is waiting on something, or it
wants a person to decide, merge or do a manual step. From outside these all
look idle. The agent is the only one who knows which, so make it say so.
## The labels
Use a closed list. The one this skill was written from has eight:
- Asks a person: `merge-ready`, `choose`, `go-ahead`, `manual-step`, `stuck`.
- Asks nothing: `stopping`, `still-working`, `waiting`.
Before you build anything, take the last 40 stopped sessions, read each
final message, and try to give each one label. Add or merge labels until most
fit one. Expect some that need two.
## Build it
1. A command the agent runs to label its turn. It refuses an unknown label
and lists the real ones.
2. Every label that asks a person needs a one-line note saying what is asked.
3. Where a label can either block the work or not (a choice with a safe
default, say), require a yes or no flag for "this blocks".
4. A stop hook (a script the agent runtime runs when the agent stops). If
the turn has no valid label, refuse the stop once and put the whole list
of labels in the reason. Never refuse a stop that follows a refusal.
5. Fail open. A broken label file, an error in the hook, or a sub-agent's
stop lets the stop through. Drop a label older than the turn could be.
6. Show the labels where the person looks, sorted into "needs you, blocks",
"needs you, can wait" and "nothing needed".
## Measure the cost
Log every refusal: time added and extra model calls. A refusal makes the
model re-read its context, so it is not free. Tell the agent the rule at the
start of each session and the refusal rate should fall.
## What it does not do
A label is a claim. It is true when written and may be stale when read. If
accuracy matters, have a second reader label the same turns blind and count
how often they agree.