Hook-added context

Some advice only makes sense at the moment it applies: right after a push is rejected, or the first time an agent runs git. A hook can add that advice beside the result of the call that needed it, and then get out of the way.

Know hooks that add context already? Skip to In Terrarium.

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts instead."
  }
}

In Terrarium

Besides the hooks that set up a session and land its log, Terrarium's hooks are guards and hints. A guard runs before a call and can deny it. A hint runs after a call, or after a prompt, and only adds context. The roster in docs/agents/guards.md lists every hint beside the guards, and .claude/settings.json wires each one in.

Each hint watches for one situation. For example:

• scripts/hooks/stale-push-hint.ts waits for a git push that git rejects as "stale info", and adds that the remote branch was probably deleted when its PR merged, with the fix.
• scripts/hooks/read-first-hint.ts waits for the first call of a kind that CLAUDE.md or a RuleA short instruction in .claude/rules/ that reaches an agent on its own, at session start, when it works on the files the rule names, or when it runs the Skill the rule names.GLOSSARY.md ties to a doc, such as a session's first GitHub call or its first git command other than status, diff, show, ls-tree, cat-file, grep or ls-files. It names that doc, with a closing line that a late read which clears the call is not a FrictionOne thing that went wrong in a session or cost it needless effort, which its agent records in the session log with a possible fix and a severity.GLOSSARY.md. After the main session opens a PR, it also says to invoke the close-session SkillA folder of instructions for one repeatable job, committed with the code, that a session runs when the job comes up.GLOSSARY.md.
• scripts/hooks/adr-read-hint.ts runs after an Edit, a Write or a Bash git commit and points to each ADRAn architecture decision record, a short file stating one decision, why it was made, and the alternatives it rejected. whose rule matches a file written, or that the change names, unless the agent has already read it in full.

The stale-push hint makes its decision in one function: a Bash git push, then git's own rejection line anywhere in the output.

32export function staleInfoHint(payload: unknown): string | null {
33  const command = field(field(payload, 'tool_input'), 'command')
34  if (field(payload, 'tool_name') !== 'Bash') return null
35  if (typeof command !== 'string' || !GIT_PUSH.test(command)) return null
36  // PostToolUse carries `tool_response`; PostToolUseFailure carries `error`.
37  const response = field(payload, 'tool_response')
38  const output = [field(response, 'stdout'), field(response, 'stderr'), field(payload, 'error')]
39  return output.some((s) => typeof s === 'string' && STALE_REJECTION.test(s)) ? HINT : null
40}

The hint is wired on both PostToolUse and PostToolUseFailure, and prints the JSON above with whichever event called it as hookEventName.

A guard almost always fails closed: if it crashes, the call is blocked. A hint fails open. Each one is wired as … || true, and runGuard in scripts/hooks/hook-io.ts returns silently when a hint crashes: a broken hint adds nothing and the session carries on.

A hint also says each thing once. The read-first hint stays silent once the session's transcript shows the doc was read or the pointer was already given, and the ADR hint skips an ADR the agent already read in full or was already pointed to.

Where next

• LessonClaude Code hooks
• LessonBlocking hooks
• LessonCLAUDE.md
• LessonPath-specific rules
• JournalFriction Ledger