AgentLayer▸docs
Reference

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.

HookCommandTimeoutWhat it does
SessionStartsession-start15sBefore setup: the setup banner. After: the banner with any notices, plus the per-session context in What loads at session start
SessionEndsession-capture --mode=session-end30sAppends the transcript to knowledge/raw/sessions/YYYY-MM-DD.md, redacted
PreCompactsession-capture --mode=pre-compact30sThe same capture before the host compacts, so mid-session context is not lost
PreToolUse (Bash)guard5sRefuses 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.

RefusedExampleThe fix it givesHosts
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 lnecho x > reports/note.md after a cd into a repoThe absolute path under the home, or cd back first. A repo with its own folder of that name is left aloneBoth
Scratch files found by pattern in the shared temp foldercat $TMPDIR/build-*/out.logUse the exact path mktemp printedBoth
A hand-picked name in $TMPDIRecho x > $TMPDIR/notes.txtThe same. mktemp itself passes, and a single-quoted '$TMPDIR' is plain textBoth
Git that rewrites or hides historygit commit --amend, a merge with the ours strategyA new commit on top; a merge that keeps the other sideBoth
Any git stash but list and showgit stash pushStage 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 repoBoth
A commit, merge or push that runs even when the check before it failspnpm test; git commit …, or pnpm test | tail before a commitJoin every step from the check to the git command with &&. A piped check needs set -o pipefail firstBoth
A cd that leaves the session outside the homecd ~/code/acme-app && git statusgit -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 && lsThe same command wrapped in a subshell, ready to runClaude Code
Any command, once the session already sits outside the homeAfter you ran ! cd yourselfcd back to the home firstClaude Code

Notes on the table:

  • A check is a test, lint, typecheck, build or format step: tsc, eslint, prettier, vitest and the like, or a runner such as pnpm, bun, make or cargo with one of those words.
  • The cd rules are Claude Code only, and only for a session launched in the home. There a cd carries over to every later command; Codex starts each command in the workspace. A cd back to the home and a cd inside ( … ) always pass, and cd $HOME reads like cd ~.
  • 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.

FileHolds
knowledge/raw/sessions/YYYY-MM-DD.mdThe 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.jsonThe 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:

PassCatchesReplaced with
Exact matchEvery value of 12 characters or more in .state/secrets/.env<REDACTED:KEY_NAME>
Key formatsKeys 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 blobsPasted 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.

On this page