Hooks and Background Tasks: Lifecycle Hooks, Deterministic Checks, and Notifications That Don't Interrupt the Conversation

A rule you can settle with one if does not belong to the model

Start with the criterion, because everything below grows out of it: if you can decide a rule with a single if, it should not be something the model has to remember.

A prompt makes the model usually right; a hook makes it always right, and the distance between those two words is the entire reason this machinery exists. The price is just as clear: a hook can only express what can be written as code, and "is this code any good" never will be. So the two are not substitutes but a division of labor — prompts own judgment, hooks own discipline. Day sixteen phrased it as "the craft card owns judgment, code owns discipline"; today is the same criterion landing a second time.

It also needs a clean line drawn against day five's permission rules, because the two look alike. Permission rules answer "who is allowed to do this"; a hook answers "is doing it right, right now." A permission rule is a static table matched on tool name and path: it can express "do not edit files under the test directory," and it cannot express "has this file been read in this session" — that depends on the state of the conversation at this instant. Any check whose criterion depends on state, or on the content being written, can only be a hook.

Four trigger points, and only one of them can say no

A session does not have many natural boundaries. This course takes four:

flowchart TD
  A[session starts: session_start] --> B[the user says something]
  B --> C[the model wants a tool]
  C --> D[before the tool: pre_tool]
  D -->|allow| E[the tool actually runs]
  D -->|veto| F[the tool never ran<br/>feed back a failed result]
  E --> G[after the tool: post_tool]
  G --> H[the result goes back to the model]
  F --> H
  H --> I[session ends: session_end]

Of the four, only pre_tool can veto, and that has to stick. A veto means "this did not happen," and once a tool has finished, the file is already edited and the command has already run. Saying "no" at that point is a lie you tell yourself.

Which means post_tool blocking is a different thing entirely: it undoes nothing, it marks the call failed so day six's self-correction machinery takes over. What the model sees is not "success" but a concrete failure report, and it goes back and cleans up on its own. Today's test-running hook works exactly this way: the model put the guard on the wrong condition, the file really was changed, the call was marked failed, the test output came back verbatim, and its next step got it right. Conflating the two kinds of blocking is the most common mistake in hook protocol design — do it and you end up with a mechanism you believe can undo a write, which in fact undoes nothing.

The protocol: what goes in, and whose failure it is

One detail in a hook's input is worth naming: the arguments handed to it are an already-parsed object, not raw JSON text. Letting every hook parse them again copies day three's "the arguments might not be valid JSON" problem into every hook, each handling it differently.

The output has two bits that are easy to mix up: whether the hook itself succeeded, and whether this call should be stopped, are separate questions. A formatting hook that found nothing to format has failed, and that should stop nothing; stopping is decided by the hook's declared blocking flag. Two more things must be caught by the execution layer, and both surface only when a hook is written badly:

async function runOne(hook: HookDef, input: HookInput) {
  const startedAt = Date.now()
  // A timeout counts as failure, never as a pass: treating a check that cannot
  // finish as a pass quietly disables it exactly when it is needed most —
  // on a workspace large enough that the check does not finish
  const timeout = new Promise<HookOutcome>((resolve) => {
    setTimeout(() => resolve({ ok: false, note: 'timed out' }), hook.timeoutMs).unref()
  })
  try {
    return { outcome: await Promise.race([hook.run(input), timeout]), ms: Date.now() - startedAt }
  } catch (error) {
    // A hook that throws is still just "this hook failed"; the loop needs no change
    const message = error instanceof Error ? error.message : String(error)
    return { outcome: { ok: false, note: `hook threw: ${message}` }, ms: Date.now() - startedAt }
  }
}

async def run_one(hook: HookDef, data: HookInput) -> tuple[HookOutcome, int]:
    started = time.monotonic()
    try:
        # wait_for really cancels the coroutine on timeout, which is cleaner than a race
        outcome = await asyncio.wait_for(hook.run(data), hook.timeout_ms / 1000)
    except asyncio.TimeoutError:
        outcome = HookOutcome(ok=False, note="timed out")
    except Exception as error:  # catch everything: a bad hook must not topple the loop
        outcome = HookOutcome(ok=False, note=f"hook threw: {error}")
    return outcome, int((time.monotonic() - started) * 1000)

One point deserves emphasis: Promise.race stops nothing. JavaScript cannot cut short a function that is already awaiting, so that timeout only guarantees the caller stops waiting. What actually stops is the timeout the hook passes to its own child process — both of today's slow hooks run child processes, so they really do stop. Python's wait_for does cancel the coroutine, which is cleaner, but a coroutine waiting on a child process still needs a timeout on that child. Catching exceptions comes from the same discipline: when one part breaks, the worst outcome should be one part missing — day fifteen said it about a dropped server, day sixteen about a broken skill package.

Should a hook's output be fed back to the model

This is today's second judgment call. A hook has something to say when it finishes. Does that go to the user's screen, or also into the tool result the model reads?

There is exactly one criterion: would the model's next decision be different if it knew.

A formatting hook stripping trailing spaces changes nothing the model would do — but the moment it modifies file content it has to say so, or the next exact replacement will try to match text that no longer exists. A red test suite it must know about, or it walks on believing the fix is in. A session-start check reporting "the workspace looks fine" is pure noise.

The feedback needs no protocol change: append the hook's words to the body of the tool result. ToolResult.content was always "text fed back to the model," and a hook's output belongs there.

const result = await tool.run(args, ctx)
const post = await runHooks(selectHooks(state.hooks, 'post_tool', tool.name), {
  event: 'post_tool',
  tool: tool.name,
  args,
  result,
  cwd: ctx.cwd,
})
if (post.feed.length === 0) return result
return {
  ...result,
  // A failed blocking hook marks the call failed. It undoes nothing; it only lets
  // the model know that move did not land, so it can go back and clean up
  ok: post.denied ? false : result.ok,
  content: `${result.content}\n\nHook results:\n${post.feed.join('\n')}`,
}

result = await tool.run(args, ctx)
post = await run_hooks(select_hooks(state.hooks, "post_tool", tool.name), HookInput(
    event="post_tool", tool=tool.name, args=args, result=result, cwd=ctx.cwd,
))
if not post.feed:
    return result
# dataclasses.replace: swap only the two fields that change, carry the rest through
return replace(
    result,
    ok=False if post.denied else result.ok,
    content=result.content + "\n\nHook results:\n" + "\n".join(post.feed),
)

The lab shows this feedback genuinely changing behavior: the hook ran the tests on the model's behalf and fed back "all four cases green, you do not need to run them again," and in that turn it never called run_command a second time. Drop that sentence and the tool list grows one fully redundant test run.

The veto branch's failure message has its own requirement: it must say plainly that retrying unchanged produces the same result. Day six taught the model "if it fails, try again," and a deterministic rule answers identically ten thousand times. Leave that sentence out and you watch it walk into the same wall three times before the loop detector picks it up.

Where to hang it: three options, and the dullest one wins

Option one is to change the loop, splicing something in around tool execution. Rejected: the loop already owns backoff, limits, loop detection and approval; a fifth job and it stops being a loop and becomes the file that does everything. Option two is two new event types in the event protocol. Also rejected: the rendering layer has no need to know how hooks run — the same call day five made when approvals stayed out of the protocol.

Option three is to decorate the tool definition itself. What a hook does is "a little more work around a tool running," and the run inside a tool definition is exactly "a tool runs." Pick it and the day's wiring is one line, plus a free bonus: remote tools, scripts shipped with a skill, yesterday's subagent-dispatching tool, and any tool added later pick up hooks with no change at all — they were always the same interface.

Background tasks: the process, the log, the status query

Different subject. Some commands simply take a long time — a full end-to-end suite, an install, a build — and running one in the foreground parks the whole conversation.

Background tasks need three pieces and cannot skip one. The process has to be its own process group, with the parent not waiting on it. The log has to hit disk, because nobody is watching and the output may be tens of thousands of lines or may not arrive for half an hour. The status needs a queryable table — the piece most often forgotten, and without it a background task is something you start and can never find again, which the user experiences as "it apparently did nothing."

The tool exposed to the model is called run_background, and two sentences in its description are mandatory: what comes back is an acknowledgment, not a result; and do not claim success until the system says it finished. Nearly every tool the model has seen hands back an answer on return, so say nothing and it will take a receipt and tell the user the tests have passed.

Progress travels a separate road: the lab starts a tiny receiver bound to localhost only (port 3118), and a task reports to it whenever it wants. Why not parse its standard output? Because standard output is a log for humans, not a protocol for programs — parsing progress from it means agreeing on a prefix and writing a parser, and one unrelated line of output fools the whole thing. One more ruling: progress is pulled, completion is pushed. Push a notification for three progress reports per second and the terminal is unusable. Today covers processes and notifications only; whether two tasks step on each other belongs to yesterday's isolation section.

How a notification gets back to a terminal that is waiting for input

This is today's harder half. A background task speaks at an arbitrary moment, and the terminal is single-threaded — at any instant it is in one of three states, and whether interrupting is allowed differs in each:

So the queue's default action is to hold, releasing at two safe moments only: after a turn ends, and at the instant of "waiting for input with an empty line."

push(notice: Notice): void {
  this.forModel.push(notice)
  // If we may interrupt, print now and repaint the prompt; otherwise hold it
  if (this.sink?.canInterrupt()) {
    this.sink.out(`\n${notice.text}`)
    this.sink.redraw()
    return
  }
  this.pending.push(notice)
}

def push(self, notice: Notice) -> None:
    self.for_model.append(notice)
    # Same decision, written with the walrus operator: grab the sink and ask it in one step
    if (sink := self.sink) is not None and sink.can_interrupt():
        sink.out("\n" + notice.text)
        sink.redraw()
        return
    self.pending.append(notice)

That forModel is the second road and cannot be dropped: notices for the human and notices for the model are queued separately. Characters on a screen are not in the message array, so the model cannot see them. Without it the user hits a genuinely strange moment — they read "task finished," ask the model, and are told it is still running. The implementation is three lines: attach the held status as one message at the start of the next turn.

What this costs: it slows down every single edit

A mechanism is only fully explained once its cost is on the table. A hook's cost is unambiguous: it slows down every tool call, and that bill is multiplied by the number of calls.

The lab's test-running hook takes a bit over a hundred milliseconds on a sandbox repo with four cases (that number is not reproducible — it differs on every machine and every run; read the order of magnitude only). One edit paying that is nothing; twenty edits is two or three seconds. Move to a real repo whose full suite takes three minutes and the same hook makes this Agent unusable.

So in a real project it changes shape: either it runs only the files that were touched, or it moves to the pre-commit trigger point — twenty edits, one check. That arithmetic belongs in the choice of trigger point: the closer to every tool call, the more timely the check and the higher the cost. Which is why each hook's duration must be printed on screen — otherwise the user just feels that "this thing is slow today." A cost nobody can see is a cost nobody manages.

Source Reading

Hands-On Lab

The lab hangs six hooks across the four trigger points: a read-before-edit recorder paired with its guard, formatting, test running, a session-start environment check, and a shutdown reminder. The background side has a task table, logs, a progress receiver and two slash commands. All five exercises sit where things "run without it, are trustworthy only with it": timeouts and caught exceptions, veto semantics, feedback, logs on disk, notification queuing. The starter passes five of fourteen unmodified.

1. Add timeouts and exception catching to hooks, and watch checks two and three go green — remember a timeout counts as failure, never as a pass.
2. Wire up the veto that is computed and then ignored, and watch the model's edit-from-memory get stopped with the file unchanged, byte for byte.
3. Feed hook output into the tool result and mark the call failed when blocking, then watch the model go back and get it right on its own.
4. Route a background task's output to a log file, and watch /tasks with a task number read that output back.
5. Change notifications from "print on arrival" to queued, run MOCK=1 SELFTEST=1 pnpm start for all fourteen checks, then use the README's pipe commands to see the three behaviors.

Acceptance is five ticks: fourteen of fourteen self-test checks pass; an edit without a prior read is stopped with the file unchanged; after a wrong edit that call is marked failed with the test output fed back; the background task reports three of three progress steps through 3118 and its log reads back; and the end-to-end turn's three tool calls contain no run_command, because the hook ran the tests instead.

Interview Questions

Three questions today, on the division between deterministic and probabilistic constraints and on how an asynchronous mechanism finishes — not on "what is a hook":

1. Which constraints belong in a hook and which in the prompt? What is the criterion?
2. How is a hook designed so it can veto without deadlocking the Agent?
3. With a long-running command in the background, how do its status and result return to the conversation?

Full prompts, analyses and key points are in this course's day-eighteen question bank. Question two discriminates most: most people get as far as "add a timeout," and few lay out all three layers — a timeout counts as failure, blocking needs a declared default posture, and the failure message must say that retrying is pointless.

Checklist and Tomorrow

• I can state the criterion "a rule you can settle with one if should not be the model's to remember," and the line between hooks and day five's permission rules
• I can say why, of the four trigger points, only the one before tool execution may veto
• I can explain what blocking after a tool actually means, and what it cannot undo
• I can say why a veto returns a failed result instead of throwing, and what the failure message must contain
• I can state the criterion for feeding hook output back to the model, with one example on each side
• I can say why a hook timeout counts as failure, and what a race actually fails to stop
• I can explain why hooks decorate the tool definition rather than changing the loop or extending the event protocol
• I can name the three pieces of a background task, and what breaks when the status query is the missing one
• I can state the terminal's three states, and why a notification may only interrupt in one of them
• I can explain why notices for the human and notices for the model are queued separately
• I can do the arithmetic on a hook's cost, and say why an earlier trigger point costs more

Tomorrow is D19, "Multimodal Input: Pasting Screenshots, Image Validation, and Fixing Code From a Screenshot." Today gave mca a layer of discipline that does not argue; tomorrow gives it another sense — and the first trap on that road is this: a model that cannot see images does not raise an error, it invents an answer.