Hooks
The four moments the plugin hooks into on either host, what the shell guard refuses, and what capture redacts.
A hook is a program your host runs at a fixed moment. The plugin has four, and each one runs the plugin's CLI with a --hook-protocol=<host> flag. Claude Code runs them from the plugin's hooks/claude.json, as bun "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" <command> --hook-protocol=claude. Codex runs the same entry points from a per-home .codex/hooks.json, with --hook-protocol=codex and the home passed as --home=. See Hosts.
| Hook | Command | Timeout | What it does |
|---|---|---|---|
SessionStart | session-start | 15s | Before setup: the setup banner. After: the banner with any notices, plus the per-session context in What loads at session start |
SessionEnd | session-capture --mode=session-end | 30s | Appends the transcript to knowledge/raw/sessions/YYYY-MM-DD.md, redacted |
PreCompact | session-capture --mode=pre-compact | 30s | The same capture before the host compacts, so mid-session context is not lost |
PreToolUse (Bash) | guard | 5s | Refuses a shell command that breaks one of the guard's rules |
Under Claude Code, hooks/claude.json also loads the plugin's mods, a module that runs inside the host instead of as a program.
What the guard refuses
The guard reads each shell command the agent is about to run. It never edits a command: it refuses with the reason and the fix, and the agent sends a corrected one. Commands you type yourself are not checked, and outside an agent home the guard does nothing.
| Refused | Example | The fix it gives | Hosts |
|---|---|---|---|
A write to a home folder from outside the home: a relative knowledge/, projects/ or reports/ path, written by a redirect or by mkdir, touch, tee, cp, mv, install, rsync or ln | echo x > reports/note.md after a cd into a repo | The absolute path under the home, or cd back first. A repo with its own folder of that name is left alone | Both |
| Scratch files found by pattern in the shared temp folder | cat $TMPDIR/build-*/out.log | Use the exact path mktemp printed | Both |
A hand-picked name in $TMPDIR | echo x > $TMPDIR/notes.txt | The same. mktemp itself passes, and a single-quoted '$TMPDIR' is plain text | Both |
| Git that rewrites or hides history | git commit --amend, a merge with the ours strategy | A new commit on top; a merge that keeps the other side | Both |
Any git stash but list and show | git stash push | Stage exactly what the commit needs; set work aside on a temp branch or a scratch copy. The stash is shared by every worktree and session on the repo | Both |
| A commit, merge or push that runs even when the check before it fails | pnpm test; git commit …, or pnpm test | tail before a commit | Join every step from the check to the git command with &&. A piped check needs set -o pipefail first | Both |
A cd that leaves the session outside the home | cd ~/code/acme-app && git status | git -C <repo> and absolute paths, or a subshell: ( cd <repo> && … ) | Claude Code |
Any other top-level cd that moves the session: into a folder inside the home, or to a target the shell works out (cd "$DIR", cd -, popd) | cd projects && ls | The same command wrapped in a subshell, ready to run | Claude Code |
| Any command, once the session already sits outside the home | After you ran ! cd yourself | cd back to the home first | Claude Code |
Notes on the table:
- A check is a test, lint, typecheck, build or format step:
tsc,eslint,prettier,vitestand the like, or a runner such aspnpm,bun,makeorcargowith one of those words. - The
cdrules are Claude Code only, and only for a session launched in the home. There acdcarries over to every later command; Codex starts each command in the workspace. Acdback to the home and acdinside( … )always pass, andcd $HOMEreads likecd ~. - On native Windows under Codex only the first rule applies, since Codex runs PowerShell there.
- The Monitor tool's commands are checked too under Claude Code. See Claude Code.
Scope
Each host runs the hooks only for sessions started in the home: Claude Code because the plugin is enabled there, Codex because the hooks are wired there. So a session is only ever captured by the agent it launched in, and two agents on one machine cannot write into each other's memory. The cost: a session started outside a home is not captured at all. See The one convention.
Session files
Capture appends to one file per day.
| File | Holds |
|---|---|
knowledge/raw/sessions/YYYY-MM-DD.md | The day's transcripts. Each block header carries the session id, the host and model that produced it, and the turn range, so a resumed session appends a continuation block instead of a new file |
knowledge/raw/sessions/index.json | The session index: where capture stopped in each session, and what compile continues from. It can be rebuilt from the day-file headers |
Redaction
Capture scrubs the transcript before it writes anything, in three passes:
| Pass | Catches | Replaced with |
|---|---|---|
| Exact match | Every value of 12 characters or more in .state/secrets/.env | <REDACTED:KEY_NAME> |
| Key formats | Keys pasted before they were saved: sk-ant-, sk-, pplx-, AIza, gh[pousa]_, a connection string with a password in it, and api_key=, token= or bearer followed by a long value | <REDACTED:…> with the kind of key |
| Base64 blobs | Pasted images and PDFs: data: URIs and runs of 200 or more base64 characters | <REDACTED:BASE64> |
A key saved in the secrets store is always scrubbed. settings.local.json is not scanned, because it holds no secrets: keys belong in .state/secrets/.env. See Privacy.