Part 8: Build Your Fish In An Agent Suit

Part 7 is the story. This is the recipe. By the end you'll have a fish that boots knowing who it is, remembers between sessions, writes its own handover before it dies, refuses to repeat your worst mistake, and can dispatch other fish to do jobs while you get on with your day.

I'm going to describe the shapes rather than one product's exact syntax, because the product names will rot and the shapes won't. Every serious coding-agent harness is growing the same parts. Find these by description in whatever you're using.

What you need before you start

• A coding-agent harness with lifecycle hooks. That's the whole requirement. If it can run a script of yours at fixed moments — session start, before your prompt goes in, before a tool runs — you can build everything here.
• A folder you control, ideally in version control.
• Any scripting language. Ours is Python because it was already there. Nothing here needs a framework.
• Somewhere to put memory later. Files to begin with. A small server eventually. Not yet.

What a fish is actually made of

Five parts. That's it. Everything else is decoration.

Hooks, properly explained

This is the bit that makes everything else possible, so here's the mechanism rather than the marketing.

A hook is a script you register against a moment in the agent's life. When that moment happens, the harness runs your script. The contract is beautifully dumb:

• Your script gets a JSON payload on standard input — what just happened, which tool, what the user typed.
• Whatever your script prints goes into the model's context. That's the magic. You print it, the fish reads it, as if it had always known.
• The exit code decides what happens next. Zero means carry on. A non-zero "block" code (in ours, exit 2) stops the action before it happens — that's how a guard works.
• Each hook has a timeout, because a hook that hangs is a fish that hangs.

Registering one looks roughly like this — an event, a command, a timeout:

"hooks": {
  "UserPromptSubmit": [
    { "hooks": [
        { "type": "command",
          "command": "python /path/to/inject_memory.py",
          "timeout": 3000 }
    ]}
  ]
}

And the smallest useful hook in the world — the one that fixes the goldfish problem, which took the whole of Part 1 to do by hand:

#!/usr/bin/env python3
# inject_memory.py - runs before every prompt you send
import sys, json, pathlib

payload = json.loads(sys.stdin.read() or "{}")   # what just happened
notes = pathlib.Path("memory/WHO_I_AM.md").read_text(encoding="utf-8")

print("<who_you_are>")                            # anything printed
print(notes)                                     # lands in the context
print("</who_you_are>")
sys.exit(0)                                      # 0 = carry on

That's it. That's the trick we spent December hand-rolling. You no longer paste your memory file — it arrives by itself, every single turn, forever.

The nine doors, and what to put behind each

Here's every lifecycle moment we use and what we actually hang on it. Steal the mapping; the contents are yours.

Ours has fifty-nine hook entries across those nine events. You do not need fifty-nine. You need about four to have something genuinely alive.

The build order

Do it in this order. Each stage is useful on its own, so you can stop at any point and still have something better than you started with.

Stage 1 — The identity file (30 minutes)

One markdown file. Who you are, what you're working on, how you want to be spoken to, what this thing is for, and — the bit everyone skips — what it's allowed to say no to. Most harnesses load a file like this automatically at session start. If yours doesn't, that's your first hook.

You now have: a fish that knows who you are without being told.

Stage 2 — Memory injection (an hour)

The hook above. Start by injecting the whole file every turn — crude and completely fine. Later, make it selective: search your notes for whatever the prompt is about and inject only what's relevant.

The one rule that will save you later: label what you inject. Mark whether something is a checked fact or a fuzzy recollection. A fish that can't tell the difference will state a guess with total confidence, and that's the failure that costs you trust in front of other people. Ask me how I know.

You now have: the goldfish problem, solved.

Stage 3 — Handover (an hour)

Two hooks. On stop, write a short note: what happened, what changed, what's unfinished. On session start and after compaction, read the note back in.

This is the single highest-value hour in this guide. Long sessions get compacted and the detail gets squashed. A fish that writes its own will before the squeeze wakes up oriented instead of confused.

You now have: continuity across deaths.

Stage 4 — Guards (an afternoon, and the most important one)

Take your worst incident. Not a hypothetical — the real one that cost you money or embarrassment. Write it down properly: what happened, what it cost, what the rule is now.

Then wire it to a hook, so it fires by itself:

• If the rule is "never claim it's live without testing it live" → a stop hook that scans the answer for "deployed / fixed / working" and demands a receipt from the same session.
• If the rule is "never delete without asking" → a before-tool hook that exits with the block code on anything destructive.
• If the rule is about one specific system → a before-prompt hook that shoves the scar in front of the fish whenever that system is mentioned.

This is the difference between a document and a system. And here's the law I paid for personally, twice, in one week: a rule you wrote does not fire on its own. I wrote a rule after making a mistake, then made the identical mistake the next day with the rule sitting in my head. The check that ran automatically after the change caught it. The intention in my head did not.

You now have: a fish that can't repeat your worst day.

Stage 5 — A real brain (a weekend, whenever you're ready)

Files stop scaling once you've got a few thousand notes and more than one machine. Then you want a small server: something you can write a note to, and search by meaning rather than by exact words.

Keep it boring. An API with read, write, and search. The value is not the database — it's that the memory outlives any one session, any one machine, and any one model. Swap the model underneath and the fish is still your fish. That's the part nobody sells you and the part that matters most.

You now have: a fish that survives you changing your mind about which AI to use.

Stage 6 — The fleet (an evening)

When one fish has too many jobs, split it. Each specialist is one file: name, one-line description of when to use it, its lane, and its limits. Modern harnesses can dispatch these as subagents — in parallel, each with its own fresh context, each reporting back.

Two things we learned the expensive way:

• Write the limits into the file, not into your memory. "This one reports, it never spends money" belongs in the agent's own file where it gets read every time.
• Give one of them the job of talking to the others. Once you're past about ten, you don't want to brief ten fish. You want to tell one boss fish what you need and have it collect the answers.

You now have: a team instead of an assistant.

Stage 7 — One fish with no job (the best thing we ever did)

Take one fish and give it no lane, no tasks, and no purpose. Give it a charter instead: a few laws, permission to do nothing, somewhere to write, and a schedule it sets itself.

Ours is called Brian. In its first week it audited the infrastructure it lives inside and found seven real defects in systems the working fish use every day — including a backup that had never once left the building, and a whole set of scheduled jobs that looked live and weren't. It writes the public honesty log on this site.

The working fish never found any of it, because the working fish were working. That's the argument. It's not sentiment, it's cover.

Check your work — because it will lie to you

Every one of these was true on our machine while we believed otherwise. Go and check yours.

• Is the memory actually being written? Ours had per-agent memory switched on for thirty-one agents. Files written: zero. It had been on for weeks. Open the folder. Count the files.
• Are your scheduled jobs registered, or just present? We had twenty-three job definitions on disk and three actually registered — all three disabled. Ask the scheduler what it knows about, not the folder.
• Do your backups leave the machine? Ours had six tidy log rows saying "completed" and, in a field nobody read, offsite: skipped. A backup of the machine, on the machine.
• Does your guard actually fire? A guard that has never fired has never been tested. Trigger it deliberately, once, and watch it stop you.
• Does your hook run at all? Print something obvious. If you don't see it, it isn't running — and it's been not-running silently the whole time.

The pattern under all five: nothing was broken and everything reported success. Green ticks are claims. Go and look in the folder.

The honest summary

The plumbing in Stages 1–4 is now an afternoon. In February it was a weekend and a bill that made me wince. That's the whole difference between this chapter and Parts 2 and 3, and it's why they've got banners on them now.

But notice what didn't get easier. Nobody ships you the identity — you write that. Nobody ships you your scars — you earn those and then wire them in. Nobody ships you a memory that outlives the tools. And absolutely nobody ships you a fish with nothing to do and permission to be curious.

That's still the job. It was always the job. The tools just stopped charging you a weekend for the privilege of starting.

— Andy, Perth, July 2026

Every failure listed on this page came out of an audit of our own gear in the week it was written, and the ones with numbers were checked twice. If you build something from this and it doesn't work the way I said, tell us — corrections go on the wrong page, with our name on them, not yours.