All writing
AIAgentsDeveloper ToolsWorkflow Design

Pick Your Hooks by When They Fire

Every agent framework ships hooks. The design is in the event you attach to. In June that choice kept a capture hook from running on every turn, and kept a reasonable-looking fix from leaving whole days uncompiled.

Max KellyJuly 12, 20263 min read
Pick Your Hooks by When They Fire

In May I wrote that a stop hook can propose updates to an agent's rules "while the session is still fresh." In June, when my starter kit's hooks were wired into Codex, Stop was left out on purpose.

Stop fires when the agent finishes a turn, not when the session ends, in Claude Code and Codex alike. That means after every response.

That's the part of hooks a framework hides. June brought new harness frameworks, the Astro team's first Flue 1.0 beta and Vercel's eve, and Cursor 3.9 put hooks next to skills and MCP servers on one Customize page. Registering a hook is the easy part. The design is which event you attach to, and what that event means in the agent you're actually running.

The moment before context is lost

The job was easy to state. arc-starter, my public starter kit for agent-maintained notes, captures what matters from a session before it's forgotten. On Codex there were three candidate events, and each meant something different:

  • Stop fires after every turn. Capturing there means running capture on every response, which is cost and noise.
  • SessionEnd is the obvious choice, and Claude Code has it. Codex didn't.
  • PreCompact fires just before the context window is compressed, which is the moment information is actually about to be lost.

So the June upgrade wired PreCompact into the existing capture path. The transcript parser already handled Codex's format, so the change lifted a skip rather than adding new code. The pull request says plainly that the path is "correct-by-docs but not yet verified against a live Codex compaction," because there was no live session to test it on.

One script, three triggers

The harder bug was downstream. The same capture script runs from three places: a session ending, a pre-compaction flush and a manual flush. After capturing, it can compile the day's notes, and the code promised an end-of-day gate: a constant called COMPILE_AFTER_HOUR, set to 18, and a docstring about waiting for the compile hour. Nothing enforced it.

An automated reviewer flagged the missing gate. The obvious fix is to return early before 6 PM, and a second review pass caught what that would do. Compile only ever runs from a flush. There's no cron behind it. If every session in a day ended before 6 PM, that day would never compile.

So the fix passes the trigger into the script instead of inferring intent from the clock. A session end compiles at any hour, because nothing else is coming. Pre-compaction and manual flushes wait for the compile hour. The tests cover the whole matrix. On Codex, which has no session-end event, that still leaves a gap for a day whose only sessions end early, and the pull request is explicit about which events Codex lacks.

When one script serves several events, pass the event through. A hook's name tells you where it's wired. Only the trigger tells the script what it means.

The same question at session start

Session start has the opposite problem. The old hook injected the full context at the start of every session, which is how context rot begins. The upgrade replaced it with a navigation layer of about 7,000 characters in place of the full dump.

What carries over

Flue is built on Pi, which I've written about before. The capture and compile logic lives in plain scripts, so only the wiring is specific to a harness, and each harness's table of events decides where it attaches.