Skip to main content

Hooks

Prompts guide; hooks enforce. A hook is a plain Node.js script wired to a Claude Code lifecycle event through plugins/asterweave/hooks/hooks.json. Asterweave ships three enforcement hooks, plus one opt-in reminder on the same Stop event.

hooks/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [{"type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-guard.mjs\"", "timeout": 10}]
      },
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [{"type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/completion-guard.mjs\"", "timeout": 10}]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {"type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-stop-gate.mjs\"", "timeout": 10},
          {"type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-handoff-reminder.mjs\"", "timeout": 10}
        ]
      }
    ]
  }
}

:::note Only these hooks exist Asterweave does not ship a PostToolUse or SessionStart hook. If a repository needs enforcement at those events, that would be a repository-level addition — see Repository scaffolding for why Asterweave's scaffolder deliberately avoids proposing hooks by default. :::

The hooks​

HookEventPurpose
Destructive-command guardPreToolUse, matching Bash/PowerShellBlocks a fixed list of known high-impact shell commands before they run.
Workstream ownership guardPreToolUse, matching Edit/Write/NotebookEditBlocks a /asterweave:complete-project worker from writing outside its assigned module boundary. Inert in every other session.
Evidence stop gateStopKeeps an active Asterweave workflow moving instead of letting the turn end mid-flight.
Handoff reminderStopOpt-in. When recorded context usage reaches a configured threshold, it asks once for a handoff refresh. Inert by default.

Defense in depth, not a complete safety system​

The destructive-command hook is not a complete shell parser or a substitute for Claude Code permissions and sandboxing. It blocks a known, fixed set of high-impact operations, and is not meant to be disabled to work around an implementation problem. Continue to use Claude Code permissions, sandboxing, branch protection, required checks, CODEOWNERS, and human review alongside it.

Repository scaffolding explains why Asterweave's own scaffolder avoids proposing a second, competing hook for enforcement it already provides.