Hooks

A hook is how bee gets a word in. The agent runtime calls bee at a defined moment, bee prints what it has to say, and the runtime folds that into the model’s context.

bee hook install --harness claude --scope project   # or codex, or hermes

hook install writes the right configuration for the runtime you name, including flags that are easy to get wrong — see the table below for why they differ.

The three moments

when	what arrives in the agent’s context
session start	who it is (its SOUL), the standing rules, the last few facts
every prompt	rules + the memories that match what was just asked
on a file write	the rules that govern that file

Run them by hand to see exactly what they emit:

bee hook session-start
echo '{"prompt":"fix the failing datasource test"}' | bee hook prompt
echo '{"file_path":"src/Catalog/Data/ProductDataSource.cs"}' | bee hook pre-tool

What each runtime actually supports

runtime	session start	every prompt	before a write
Claude Code	✅	✅	✅ — needs --emit claude-pretool
Codex	✅	✅	not wired
Hermes	rides the first prompt	✅ --emit context-json	not wired

Every ✅ was produced by running the real runtime against bee’s own generated configuration and asking the model to quote what it received. The gaps are not “not done yet” — each one is a property of the runtime:

Claude Code discards plain stdout at the pre-write event. Only a hookSpecificOutput.additionalContext payload survives. Measured both ways: with plain text the model reported receiving nothing; with the structured payload it quoted the rule verbatim.

Codex has no Write tool — it edits files by running shell commands, so the pre-write event carries a command line rather than a file path, and there is nothing to look a rule up by.

Hermes consumes a returned payload at one event only (pre_llm_call). The other two run bee and throw the output away, so binding them would look wired and do nothing.

Codex needs hook trust

Codex requires hook trust, which is separate from project trust and granted interactively once. Without it Codex silently runs no hooks at all — no error, no output, nothing. bee hook install tells you this when you install for Codex.

A whole round of “Codex doesn’t fire pre-tool hooks” turned out to be a Codex running no hooks, measured against an untrusted config.

Timing, stated honestly

The pre-write hook runs before the write, but its context reaches the model with the tool result — so the first write does not comply, and the model corrects it. With a rule saying every .cs file must open with a licence line:

1. Write   "public class Thing"    ← the rule had not arrived yet
2. Edit    "// LICENCE-7"          ← corrected after seeing it

One extra edit, and the file ends up right. It produces a correction, not a prevention. Calling it “before the write” would overstate it.