Documentation

Reference

Agent hooks

Hooks deliver installed context at native client events. They are not a background service or a replacement for the task's loading rule.

Claude uses .claude/settings.json; Codex uses .codex/hooks.json. Generic and OpenCode use their instruction integration without these registered session hooks.

Sources: registration implementation and native hook behavior.

Events and payloads

Registered Claude and Codex events
EventCommandBehavior
SessionStartcumaru hooks sessionMatches startup, resume, clear, compact and fork. Prints the discipline index, remaining bodies in C-locale path order, then the root tree projection.
UserPromptSubmitcumaru hooks promptPrints the kernel summary followed by the installed discipline digest before each prompt.
PreToolUsecumaru hooks pretoolUses the Bash matcher. Reads native tool-call JSON from stdin and redirects recognized whole-file shell reads of Cumaru Markdown to map/get.

cumaru hooks disciplines also prints the discipline-only digest. The current per-prompt registration uses prompt so the kernel summary is included.

Ordering, limits and failure behavior

The digest lists cumaru-first first, then disciplines by descending strictness and path-byte order for ties. The session payload instead puts the index first and bodies in C path order. Every installed discipline is delivered; applicability still depends on its trigger.

The native implementation limits the prompt digest to 32,768 bytes and the complete session payload to 65,536 bytes. The digest validates required metadata; the session loader checks safe readable files and its output budget. Payload preparation failures produce a single diagnostic rather than partially emitting the prepared context.

The commands read local installed files and do not download models or call a remote service. Outside an installation, context payload commands are silent. Hook outcomes exit 0, including diagnostic outcomes, so exit success alone does not prove valid context was emitted.

The read redirect

The pre-tool hook recognizes cat, head, tail, and non-in-place sed reading a spelled .cumaru/ Markdown path. It returns a native deny decision with directions to outline using cumaru map and read the selected range using cumaru get.

Malformed input, unrecognized tool input, in-place sed and other commands pass without that decision. This is a bounded navigation guard, not a complete security sandbox or an authorization mechanism for arbitrary tool calls. A permitted read still has to respect the loading rule.

Generated registration

This is the common event shape. Let install or explicit adapter update merge the generated entries rather than replacing your settings with this example.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume|clear|compact|fork",
      "hooks": [{ "type": "command", "command": "cumaru hooks session" }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{ "type": "command", "command": "cumaru hooks prompt" }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "cumaru hooks pretool" }]
    }]
  }
}

Codex additionally receives additionalContextLimit: 0 on session and prompt context hooks, not on PreToolUse. Reapplying registration strips and replaces Cumaru-owned commands while keeping unrelated commands. Invalid native configuration blocks the merge instead of being silently overwritten.

Related contract: agent context bootstrap. Implementation details above are audited against src/adapter.rs and src/commands/hooks.rs at upstream revision 37ad79f.

Verify output and client execution separately

  1. Confirm the expected hook configuration exists for the chosen adapter and the commands match the generated registration.
  2. In the adopter root, run the two read-only diagnostic commands below. Inspect their actual output for context or a diagnostic.
  3. Start or reload a native client context according to its own behavior and trust requirements. Confirm that it receives the session context and subsequent prompt digest.
  4. If context is missing, inspect the client event configuration and local command availability. Follow any hook diagnostic; do not infer success from doctor or an exit code alone.
cumaru hooks prompt
cumaru hooks session

Doctor checks the tree and instruction surface, not actual native event execution. The kernel's fallback requires reading the index and discipline bodies when the expected injected context is missing.

Agent adapters ยท Hook CLI options