Skip to main content

Hooks reference

Auto-generated. Do not edit by hand. Run pnpm capabilities or commit a hook change β€” scripts/build-capability-index.mjs regenerates this from the hook headers and .claude/hooks/hooks.json.

Hooks are the always-on machinery the platform ships through the Claude Code plugin. Unlike agents, skills, and commands β€” which you invoke β€” hooks fire automatically at fixed points in a session. Each entry shows when it fires and what it is responsible for; click the name for the source.

SessionStart​

Fires once when a Claude session starts.

  • active-context-validate β€” Validates the local AI Context cache (parses .claude/session/active-context.json, checks fields, verifies branch). Warns on mismatch, never blocks.
  • capability-awareness β€” SessionStart hook. Teaches Claude to surface existing capabilities for free-language intent (instead of silently doing the work), and to escalate to a concrete /new-artifact recommendation when the same uncovered task recurs.
  • conversation-language β€” SessionStart hook. Reads the developer's conversation-language preference (~/.bewith/config.json, resolved via bewith-config.sh) and injects a directive to converse in that language β€” while keeping ALL written artifacts in English regardless. Mirrors the role hook. Fail-open.
  • git-hooks-sync β€” SessionStart hook. Points the machine-global git core.hooksPath at the plugin's CURRENT git-hooks/ (self-healing across always-latest updates). Safe-by-default β€” no-op on non-bewith repos, never clobbers a custom hooksPath.
  • mcp-availability-check β€” SessionStart hook. Surveys MCP servers declared in .mcp.json + settings.json, reports which are reachable. Never blocks β€” informational.
  • onboard-offer β€” SessionStart hook. The first time a developer opens an un-initialized bewith-dev repo, offers /claude-init (scaffold CLAUDE.md + CI, reviewable PR, never merges). No-op on non-bewith repos, the platform repo, already-initialized repos, and after offering once per clone.
  • session-register β€” SessionStart hook. Registers this session in a local per-machine registry with its branch, cwd, git baseline and a heartbeat β€” the basis for same-machine concurrent-session awareness. Archives stale entries (never deletes); never blocks.
  • session-state-awareness β€” SessionStart hook. Teaches Claude to verify checkable references in memory (PRs, branches, files, tasks) before acting on them, and surfaces sibling git worktrees on the cwd repo so the session knows concurrent work is in flight.
  • team-rule-prompt β€” SessionStart hook. Injects the team-rule discrimination guidance into Claude's additionalContext so it knows when to propose a team rule vs. save a personal memory.
  • team-rules-inject β€” SessionStart hook. Injects the ACCEPTED team rules (.claude/rules/team/*.md) from the plugin so they apply in EVERY repo β€” not just inside bewith-docs, where Claude Code auto-loads .claude/rules/ natively. Closes the consumer gap left by the repo-relative @-imports.

UserPromptSubmit​

Fires each time you send a message, before Claude acts on it.

  • capability-trace β€” PostToolUse + UserPromptSubmit trace hook. Records which capabilities a turn selected β€” agents (Task), skills (Skill), and platform artifacts/files touched (Edit/Write) β€” to a per-session append-only trace that the statusLine and /sessions read. Deterministic, fail-open, never blocks.
  • session-drift-check β€” UserPromptSubmit hook. On each message, detects whether the world drifted since this session's baseline β€” origin/master advanced or the branch HEAD moved β€” and injects a one-shot reminder to re-verify context before acting. Never blocks.

PreToolUse​

Fires before a tool runs β€” the matcher says which tools.

  • approve-safe-bash (on Bash) β€” PreToolUse hook for Bash. Auto-approves (permissionDecision allow) a SINGLE, metacharacter-free command whose program+args match safe-envelope.json; stays silent (normal prompt) on anything else. Never denies. Ships dry-run by default until a follow-up flips it live.
  • block-dangerous-bash (on Bash) β€” PreToolUse hook for Bash. Reads tool call from stdin, blocks commands matching patterns in dangerous-patterns.json. Prevents accidental destructive shell calls.
  • block-dangerous-git (on Bash) β€” PreToolUse hook for Bash. Blocks dangerous git operations (force-push to shared branches, hard reset, etc.) before they execute.
  • block-edit-on-master (on Edit|Write|NotebookEdit) β€” PreToolUse hook for Edit/Write/NotebookEdit. Blocks file edits when HEAD is on master/main, forcing the developer to a feature branch first.
  • branch-intent-warn (on Edit|Write|NotebookEdit) β€” PreToolUse hook for Edit/Write/NotebookEdit. WARNS (never blocks) when a write lands in a repo's primary worktree on a branch that contradicts the session's recorded task branch (active-context.json). Complements block-edit-on-master, which hard-blocks shared branches. Fail-open.
  • playwright-snapshot-warn (on mcp__playwright__browser_snapshot) β€” PreToolUse hook on mcp__playwright__browser_snapshot. Emits an "ask" permissionDecision nudging toward browser_evaluate / browser_network_requests or wrapping the session in a subagent. Never blocks; fail-open.
  • prefer-infra-mcp (on Bash) β€” PreToolUse hook for Bash. On a raw host DB/cache CLI (mysql/psql/mongo/mongosh/redis-cli) at a command position, returns permissionDecision "ask" pointing to the matching infra-MCP tool. Never blocks; never fires on docker exec, node scripts, or the CLI used as an argument.
  • safety-snapshot (on Edit|Write|NotebookEdit) β€” PreToolUse hook for Edit/Write. Before each edit, captures a non-destructive snapshot of the full working tree to refs/bewith-safety/, so uncommitted code an edit might clobber is recoverable via /restore. Debounced, auto-pruned, fail-open β€” never blocks or touches your tree.
  • session-guard (on Edit|Write|NotebookEdit) β€” PreToolUse hook for Edit/Write/NotebookEdit. Records this session's heartbeat + touched file, then checks the local registry β€” WARNS if another live session touched the same file, BLOCKS only when another owns the same branch+working-dir, with guidance to continue safely. Fail-open.
  • worktree-mutation-warn (on Bash) β€” PreToolUse hook for Bash. Soft warning when Claude attempts a git mutation on the primary worktree of a repo that has sibling worktrees β€” a likely concurrent-session collision. Warns to stderr; never blocks.

PostToolUse​

Fires after a tool runs.

  • capability-trace (on Task|Agent|Skill|Edit|Write|NotebookEdit) β€” PostToolUse + UserPromptSubmit trace hook. Records which capabilities a turn selected β€” agents (Task), skills (Skill), and platform artifacts/files touched (Edit/Write) β€” to a per-session append-only trace that the statusLine and /sessions read. Deterministic, fail-open, never blocks.
  • post-pr-create-memory-nudge (on Bash) β€” PostToolUse hook for Bash. When gh pr create succeeds, emits a one-line nudge reminding Claude to check whether MEMORY.md references the work the new PR captures. High-signal moment; never blocks.

Notification​

Fires on a Claude notification (e.g. when Claude is waiting on you).

  • notify-attention β€” Notification hook. When a session needs the developer, pushes a one-line alert (ntfy.sh / Slack / macOS fallback) with surfaceΒ·branchΒ·cwdΒ·reason + a claude --resume <id> hint, and records wait_state so /sessions shows which session is blocked. Debounced, fail-open.

Stop​

Fires when Claude finishes a response.

  • session-stop β€” Stop hook. Marks this session "idle" (finished its turn, awaiting your input) in the registry, so /sessions and the menu bar tell a working session apart from one that's done. Bumps the heartbeat; clears any wait_state. Fail-open, never blocks.

SessionEnd​

Fires when the session ends.

  • session-end β€” SessionEnd hook. Marks this session "ended" with its end reason (clear/logout/exit/other) in the registry, so /sessions and the menu bar show it closed rather than just aging into "stale". Fail-open, never blocks.