Reason8

Hooks

Overview

Hooks are the auto-invoke wedge: instead of an agent remembering to call reason8_ask, the harness fires it for you on opt-in triggers and surfaces the reaction inline. The goal is a reaction at the moment it is useful — without interrupting the agent's flow.

Contract. This page documents the hook behavior as a contract (ADR §7). The reason8 CLI that wires it is delivered separately; the behavior below is the contract that wiring matches.

Setup

npx reason8 init <key>

reason8 init detects your harness and configures both the MCP server connection and the hooks for that harness in one step. After init:

  • Hooks fire reason8_ask asynchronously and non-blocking on a small allowlist of opt-in triggers.
  • The reaction surfaces inline once it returns — it never blocks the host agent. If the host moves on first, the reaction arrives as a follow-up note.
  • Hooks lean on a warm, grounded persona pool, so an auto-invoked reaction typically lands in ~3–5s — fast enough to be a useful inline nudge. A cold reason8_ask call (no warm set for the audience) takes the full ~18–30s documented on its contract page; because hooks are non-blocking, the longer path still never stalls the host.
  • A per-session rate cap keeps auto-invocation from firing on every keystroke.
  • Opt-out is configured at init — both the trigger allowlist and the cap are yours to set.

How auto-invoke works

  1. You opt into one or more triggers at init (e.g. "before finalizing user-facing copy").
  2. When a trigger fires, the harness calls reason8_ask in the background with the artifact and an inferred goal.
  3. Your agent keeps working — the call is non-blocking.
  4. The reaction (leaning + a short why) surfaces inline once it returns.

The per-session cap and the trigger allowlist mean auto-invoke is a nudge, not a firehose.

Host support

True hook support varies by host. Where a host exposes a real hook surface, reason8 init wires auto-invoke directly. Where it does not, init degrades gracefully to manual-suggest: the agent is reminded to call reason8_ask at the right moment, but nothing fires automatically.

HostHook supportBehavior after reason8 init
Claude CodeYesAuto-invoke wired to the opt-in trigger allowlist.
CursorYesAuto-invoke wired where the host exposes a hook surface.
Claude DesktopPartialAuto-invoke where supported; otherwise manual-suggest.
Gemini CLIPartialAuto-invoke where supported; otherwise manual-suggest.
ChatGPT (Developer Mode)NoManual-suggest — the agent is prompted to call reason8_ask.
Other MCP clientsVariesAuto-invoke if the client exposes hooks; otherwise manual-suggest.

On any host, the MCP tools themselves remain available — hooks only change when reason8_ask is called, never whether you can call it. Verify your host's current hook capabilities before relying on auto-invoke; init falls back safely either way.