Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

What the agent sees (Claude Code)

ingrain init adds one hook command per event to .claude/settings.json (ingrain hook <event>). Each is a no-op for teammates who don’t have ingrain installed, and all of them fail open.

HookWhat happens
SessionStartRepo-wide decisions go into the session, plus how to propose a new one
PreToolUse on Edit / Write / MultiEdit / NotebookEditThe edit is simulated first. If an added line breaks a decision’s check, the edit is denied with the decision and the way out. An edit that adds an ingrain-ignore / decisions-ignore comment asks the person first. Otherwise the decisions scoped to that file are shown, each once per session
PreToolUse on BashA command that could write accepted decisions, rules or .corrections/config.yml (sed -i, >, mv, rm, …), or that accepts, rejects or retunes them (ingrain rules mode, ingrain decisions accept, …), or git commit --no-verify, asks the person first
PostToolUse on Edit / Write / MultiEdit / NotebookEdit / BashLearned rules run on the edited file, or on the files the shell command changed (decisions too, since a command can’t be simulated). Warn: a note to the agent. Block: the agent must fix it, with the past human fix shown
StopRules and decisions are re-checked on the files this session edited. Something broken sends the turn back, up to stop_max_attempts times; after that the turn ends and the person is told

Agents can’t edit accepted decisions, rules or .corrections/config.yml (a broken config falls back to the defaults in hooks, so it can’t switch them off); they propose with ingrain decisions add --propose or ingrain decisions supersede, and a person accepts. The one exception is first setup: until a commit on any branch holds a decision, rule or ingrain config, the agent setting ingrain up may accept proposals and commit them, so “set up ingrain in this repo” finishes in a headless session too. People review that commit like any other; --no-verify is still asked.

The same protection covers the local and global stores, with no first-setup exception: they are never committed, so nobody would review an agent’s accept. ingrain init --local writes these hooks to .claude/settings.local.json, and ingrain init --global writes them to your own ~/.claude/settings.json, where they behave like the plugin’s.

Tested live with Claude Code 2.1.322: asked to write raw fetch in src/billing/, the write was denied before the file changed, and the agent explained the decision instead of working around it.