Documentation
¶
Overview ¶
Command behalf-hook is the executable Claude Code runs on every hook event — behalf's demo companion capture surface, scoped to that one client (D4, Q44).
behalf-hook capture [--state DIR] [--spool DIR] [--policy FILE] [--chain FILE] behalf-hook install [--settings PATH] [--state DIR] [--print] [--uninstall] behalf-hook uninstall [--settings PATH] behalf-hook recover [--state DIR] [--session ID] [--older-than 1h]
`capture` reads ONE hook payload on stdin, writes a signed receipt to the spool, and exits. It is also what a bare `behalf-hook` with no subcommand does, so a hand-written settings entry naming only the binary still works.
The spool is moved into the log by the shipped drain, unchanged:
behalf-log drain --spool ~/.behalf/hook-spool --dir LOGDIR --state ~/.behalf
Exit 0, always, on the capture path ¶
This differs from behalf-proxy deliberately, and the difference is the whole posture of the surface.
The proxy aborts when it cannot record: it sits between a client and a server, it has the forwarded request in its hands, and a recorder that cannot record must not let the call through unrecorded (Q45). Failing closed there costs one tool call.
A hook is not in that position. Claude Code reads this process's exit status: a non-zero exit is an error surfaced to the user, and exit 2 blocks the tool outright. Failing closed here does not protect a crossing — the crossing happens anyway or does not happen at all — it breaks the user's editor session because a spool write failed. behalf is a recorder, not a runtime (Q47), and a recorder that takes the editor down with it will be uninstalled by lunchtime, which records nothing at all.
So every capture failure exits 0 and says what happened on stderr. The loss is not silent: it is silence in the log plus a hole in the per-emitter counter sequence, which is precisely what Q48 stamps the counter for. That is a worse guarantee than the proxy's and it is the honest one for this surface.
The other subcommands are not on the agent's hot path and exit non-zero on failure like any ordinary tool.
Source Files