@hivehub/rulebook 5.4.1 → 5.5.0

package/templates/hooks/check-context-and-handoff.ps1

@@ -1,58 +1,58 @@
-# Claude Code Stop hook — context freshness monitor (PowerShell).
-# See check-context-and-handoff.sh for the full design rationale.
-
-$ErrorActionPreference = 'Stop'
-
-# Read hook input from stdin to get the actual project cwd
-$hookInput = [Console]::In.ReadToEnd()
-$ProjectRoot = $null
-if ($hookInput) {
-    try { $ProjectRoot = ($hookInput | ConvertFrom-Json).cwd } catch {}
-}
-if (-not $ProjectRoot) { $ProjectRoot = $env:CLAUDE_PROJECT_DIR }
-if (-not $ProjectRoot) { $ProjectRoot = (Get-Location).Path }
-
-$ConfigFile = Join-Path $ProjectRoot '.rulebook/rulebook.json'
-$HandoffDir = Join-Path $ProjectRoot '.rulebook/handoff'
-
-$WarnPct = 75
-$ForcePct = 90
-$MaxContextChars = 1600000
-
-if (Test-Path $ConfigFile) {
-    try {
-        $cfg = Get-Content $ConfigFile -Raw | ConvertFrom-Json
-        if ($cfg.handoff.warnThresholdPct) { $WarnPct = $cfg.handoff.warnThresholdPct }
-        if ($cfg.handoff.forceThresholdPct) { $ForcePct = $cfg.handoff.forceThresholdPct }
-    } catch {}
-}
-
-$TranscriptSize = 0
-$ClaudeDir = Join-Path $env:USERPROFILE '.claude/projects'
-if (Test-Path $ClaudeDir) {
-    $latest = Get-ChildItem $ClaudeDir -Recurse -Filter '*.jsonl' -File |
-        Sort-Object LastWriteTime -Descending | Select-Object -First 1
-    if ($latest) { $TranscriptSize = $latest.Length }
-}
-
-if ($TranscriptSize -eq 0) {
-    Write-Output '{}'
-    exit 0
-}
-
-$Pct = [math]::Floor($TranscriptSize * 100 / $MaxContextChars)
-
-if ($Pct -ge $ForcePct) {
-    if (-not (Test-Path $HandoffDir)) { New-Item -ItemType Directory -Path $HandoffDir -Force | Out-Null }
-    New-Item -ItemType File -Path (Join-Path $HandoffDir '.urgent') -Force | Out-Null
-    $msg = "CONTEXT AT ${Pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW."
-    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
-    Write-Output $out
-} elseif ($Pct -ge $WarnPct) {
-    $msg = "Context at ${Pct}%. Recommended: invoke /handoff to save session state."
-    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
-    Write-Output $out
-} else {
-    Write-Output '{}'
-}
-exit 0
+# Claude Code Stop hook — context freshness monitor (PowerShell).
+# See check-context-and-handoff.sh for the full design rationale.
+
+$ErrorActionPreference = 'Stop'
+
+# Read hook input from stdin to get the actual project cwd
+$hookInput = [Console]::In.ReadToEnd()
+$ProjectRoot = $null
+if ($hookInput) {
+    try { $ProjectRoot = ($hookInput | ConvertFrom-Json).cwd } catch {}
+}
+if (-not $ProjectRoot) { $ProjectRoot = $env:CLAUDE_PROJECT_DIR }
+if (-not $ProjectRoot) { $ProjectRoot = (Get-Location).Path }
+
+$ConfigFile = Join-Path $ProjectRoot '.rulebook/rulebook.json'
+$HandoffDir = Join-Path $ProjectRoot '.rulebook/handoff'
+
+$WarnPct = 75
+$ForcePct = 90
+$MaxContextChars = 1600000
+
+if (Test-Path $ConfigFile) {
+    try {
+        $cfg = Get-Content $ConfigFile -Raw | ConvertFrom-Json
+        if ($cfg.handoff.warnThresholdPct) { $WarnPct = $cfg.handoff.warnThresholdPct }
+        if ($cfg.handoff.forceThresholdPct) { $ForcePct = $cfg.handoff.forceThresholdPct }
+    } catch {}
+}
+
+$TranscriptSize = 0
+$ClaudeDir = Join-Path $env:USERPROFILE '.claude/projects'
+if (Test-Path $ClaudeDir) {
+    $latest = Get-ChildItem $ClaudeDir -Recurse -Filter '*.jsonl' -File |
+        Sort-Object LastWriteTime -Descending | Select-Object -First 1
+    if ($latest) { $TranscriptSize = $latest.Length }
+}
+
+if ($TranscriptSize -eq 0) {
+    Write-Output '{}'
+    exit 0
+}
+
+$Pct = [math]::Floor($TranscriptSize * 100 / $MaxContextChars)
+
+if ($Pct -ge $ForcePct) {
+    if (-not (Test-Path $HandoffDir)) { New-Item -ItemType Directory -Path $HandoffDir -Force | Out-Null }
+    New-Item -ItemType File -Path (Join-Path $HandoffDir '.urgent') -Force | Out-Null
+    $msg = "CONTEXT AT ${Pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW."
+    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
+    Write-Output $out
+} elseif ($Pct -ge $WarnPct) {
+    $msg = "Context at ${Pct}%. Recommended: invoke /handoff to save session state."
+    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
+    Write-Output $out
+} else {
+    Write-Output '{}'
+}
+exit 0

package/templates/hooks/check-context-and-handoff.sh

@@ -1,76 +1,76 @@
-#!/usr/bin/env bash
-# Claude Code Stop hook — context freshness monitor.
-#
-# Runs after every model turn. Estimates the current context usage
-# from the JSONL transcript and, when it exceeds the configured
-# threshold, emits additionalContext instructing the model to invoke
-# the /handoff skill and tell the user to type /clear.
-#
-# Thresholds are read from .rulebook/rulebook.json `handoff` section.
-# Defaults: warn=75, force=90 (percentage of estimated max context).
-
-set -euo pipefail
-
-# Read the hook input from stdin (Claude Code passes it as JSON)
-input="$(cat)"
-
-# Resolve project root from hook input cwd, NOT $(pwd) — the hook may be
-# invoked from a sub-directory the user is currently editing.
-PROJECT_ROOT=""
-if [[ -n "$input" ]] && command -v jq &>/dev/null; then
-  PROJECT_ROOT="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
-fi
-[[ -z "$PROJECT_ROOT" ]] && PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
-
-CONFIG_FILE="${PROJECT_ROOT}/.rulebook/rulebook.json"
-HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
-
-# Defaults
-WARN_PCT=75
-FORCE_PCT=90
-MAX_CONTEXT_CHARS=1600000  # ~400k tokens ≈ 1.6M chars (rough 1:4 ratio)
-
-# Override from config if available
-if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
-  WARN_PCT=$(jq -r '.handoff.warnThresholdPct // 75' "$CONFIG_FILE" 2>/dev/null || echo 75)
-  FORCE_PCT=$(jq -r '.handoff.forceThresholdPct // 90' "$CONFIG_FILE" 2>/dev/null || echo 90)
-fi
-
-# Try to find the transcript path from the session
-# Claude Code stores transcripts as JSONL in ~/.claude/projects/<hash>/
-# The hook input may or may not contain session info; we fall back to
-# estimating from the input itself.
-transcript_size=0
-
-# Strategy 1: check the most recent JSONL in the project-specific Claude dir
-CLAUDE_PROJECTS_DIR="${HOME}/.claude/projects"
-if [[ -d "$CLAUDE_PROJECTS_DIR" ]]; then
-  latest_jsonl=$(find "$CLAUDE_PROJECTS_DIR" -name "*.jsonl" -type f -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -1 | awk '{print $2}' || true)
-  if [[ -n "$latest_jsonl" && -f "$latest_jsonl" ]]; then
-    transcript_size=$(stat -c%s "$latest_jsonl" 2>/dev/null || stat -f%z "$latest_jsonl" 2>/dev/null || echo 0)
-  fi
-fi
-
-# If we couldn't get transcript size, emit nothing (no-op)
-if [[ "$transcript_size" -eq 0 ]]; then
-  printf '%s' '{}'
-  exit 0
-fi
-
-# Estimate context percentage
-pct=$(( transcript_size * 100 / MAX_CONTEXT_CHARS ))
-
-if [[ "$pct" -ge "$FORCE_PCT" ]]; then
-  # Force mode: write urgent sentinel + emit strong instruction
-  mkdir -p "$HANDOFF_DIR"
-  touch "${HANDOFF_DIR}/.urgent"
-  msg="⚠️ CONTEXT AT ${pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW to save session state to .rulebook/handoff/_pending.md. After it succeeds, tell the user: '>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<'. Do NOT continue working until the user has typed /clear."
-  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
-elif [[ "$pct" -ge "$WARN_PCT" ]]; then
-  msg="⚠️ Context at ${pct}%. Recommended: invoke /handoff to save session state. After it succeeds, tell the user to type /clear for a fresh session."
-  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
-else
-  # Below threshold — no-op
-  printf '%s' '{}'
-fi
-exit 0
+#!/usr/bin/env bash
+# Claude Code Stop hook — context freshness monitor.
+#
+# Runs after every model turn. Estimates the current context usage
+# from the JSONL transcript and, when it exceeds the configured
+# threshold, emits additionalContext instructing the model to invoke
+# the /handoff skill and tell the user to type /clear.
+#
+# Thresholds are read from .rulebook/rulebook.json `handoff` section.
+# Defaults: warn=75, force=90 (percentage of estimated max context).
+
+set -euo pipefail
+
+# Read the hook input from stdin (Claude Code passes it as JSON)
+input="$(cat)"
+
+# Resolve project root from hook input cwd, NOT $(pwd) — the hook may be
+# invoked from a sub-directory the user is currently editing.
+PROJECT_ROOT=""
+if [[ -n "$input" ]] && command -v jq &>/dev/null; then
+  PROJECT_ROOT="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+fi
+[[ -z "$PROJECT_ROOT" ]] && PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+CONFIG_FILE="${PROJECT_ROOT}/.rulebook/rulebook.json"
+HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
+
+# Defaults
+WARN_PCT=75
+FORCE_PCT=90
+MAX_CONTEXT_CHARS=1600000  # ~400k tokens ≈ 1.6M chars (rough 1:4 ratio)
+
+# Override from config if available
+if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
+  WARN_PCT=$(jq -r '.handoff.warnThresholdPct // 75' "$CONFIG_FILE" 2>/dev/null || echo 75)
+  FORCE_PCT=$(jq -r '.handoff.forceThresholdPct // 90' "$CONFIG_FILE" 2>/dev/null || echo 90)
+fi
+
+# Try to find the transcript path from the session
+# Claude Code stores transcripts as JSONL in ~/.claude/projects/<hash>/
+# The hook input may or may not contain session info; we fall back to
+# estimating from the input itself.
+transcript_size=0
+
+# Strategy 1: check the most recent JSONL in the project-specific Claude dir
+CLAUDE_PROJECTS_DIR="${HOME}/.claude/projects"
+if [[ -d "$CLAUDE_PROJECTS_DIR" ]]; then
+  latest_jsonl=$(find "$CLAUDE_PROJECTS_DIR" -name "*.jsonl" -type f -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -1 | awk '{print $2}' || true)
+  if [[ -n "$latest_jsonl" && -f "$latest_jsonl" ]]; then
+    transcript_size=$(stat -c%s "$latest_jsonl" 2>/dev/null || stat -f%z "$latest_jsonl" 2>/dev/null || echo 0)
+  fi
+fi
+
+# If we couldn't get transcript size, emit nothing (no-op)
+if [[ "$transcript_size" -eq 0 ]]; then
+  printf '%s' '{}'
+  exit 0
+fi
+
+# Estimate context percentage
+pct=$(( transcript_size * 100 / MAX_CONTEXT_CHARS ))
+
+if [[ "$pct" -ge "$FORCE_PCT" ]]; then
+  # Force mode: write urgent sentinel + emit strong instruction
+  mkdir -p "$HANDOFF_DIR"
+  touch "${HANDOFF_DIR}/.urgent"
+  msg="⚠️ CONTEXT AT ${pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW to save session state to .rulebook/handoff/_pending.md. After it succeeds, tell the user: '>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<'. Do NOT continue working until the user has typed /clear."
+  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
+elif [[ "$pct" -ge "$WARN_PCT" ]]; then
+  msg="⚠️ Context at ${pct}%. Recommended: invoke /handoff to save session state. After it succeeds, tell the user to type /clear for a fresh session."
+  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
+else
+  # Below threshold — no-op
+  printf '%s' '{}'
+fi
+exit 0

package/templates/hooks/enforce-team-for-background-agents.ps1

@@ -1,63 +1,63 @@
-# Claude Code PreToolUse hook for the Agent tool (PowerShell variant).
-#
-# Policy enforced by @hivehub/rulebook v5.3.0:
-#   - A single Agent call is fine (foreground or background).
-#   - Spawning multiple standalone background Agents is FORBIDDEN.
-#     Parallel multi-agent work MUST go through a Team so agents can
-#     communicate via SendMessage.
-#
-# Block any Agent invocation with run_in_background=true UNLESS it
-# targets subagent_type=team-lead or provides a team_name. This forces
-# background parallel work through a Team.
-
-$ErrorActionPreference = 'Stop'
-
-$input = [Console]::In.ReadToEnd()
-$data = $null
-try { $data = $input | ConvertFrom-Json } catch {}
-
-$toolName = $null
-if ($data -and $data.PSObject.Properties.Name -contains 'tool_name') { $toolName = $data.tool_name }
-
-if ($toolName -ne 'Agent') {
-    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-    exit 0
-}
-
-$runInBackground = $false
-$subagentType = ''
-$teamName = ''
-if ($data.tool_input) {
-    if ($data.tool_input.PSObject.Properties.Name -contains 'run_in_background') {
-        $runInBackground = [bool]$data.tool_input.run_in_background
-    }
-    if ($data.tool_input.PSObject.Properties.Name -contains 'subagent_type') {
-        $subagentType = [string]$data.tool_input.subagent_type
-    }
-    if ($data.tool_input.PSObject.Properties.Name -contains 'team_name') {
-        $teamName = [string]$data.tool_input.team_name
-    }
-}
-
-if (-not $runInBackground) {
-    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-    exit 0
-}
-
-if ($subagentType -eq 'team-lead' -or $teamName) {
-    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-    exit 0
-}
-
-$reason = 'POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy.'
-
-$out = @{
-    hookSpecificOutput = @{
-        hookEventName            = 'PreToolUse'
-        permissionDecision       = 'deny'
-        permissionDecisionReason = $reason
-    }
-} | ConvertTo-Json -Compress -Depth 4
-
-Write-Output $out
-exit 0
+# Claude Code PreToolUse hook for the Agent tool (PowerShell variant).
+#
+# Policy enforced by @hivehub/rulebook v5.3.0:
+#   - A single Agent call is fine (foreground or background).
+#   - Spawning multiple standalone background Agents is FORBIDDEN.
+#     Parallel multi-agent work MUST go through a Team so agents can
+#     communicate via SendMessage.
+#
+# Block any Agent invocation with run_in_background=true UNLESS it
+# targets subagent_type=team-lead or provides a team_name. This forces
+# background parallel work through a Team.
+
+$ErrorActionPreference = 'Stop'
+
+$input = [Console]::In.ReadToEnd()
+$data = $null
+try { $data = $input | ConvertFrom-Json } catch {}
+
+$toolName = $null
+if ($data -and $data.PSObject.Properties.Name -contains 'tool_name') { $toolName = $data.tool_name }
+
+if ($toolName -ne 'Agent') {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+$runInBackground = $false
+$subagentType = ''
+$teamName = ''
+if ($data.tool_input) {
+    if ($data.tool_input.PSObject.Properties.Name -contains 'run_in_background') {
+        $runInBackground = [bool]$data.tool_input.run_in_background
+    }
+    if ($data.tool_input.PSObject.Properties.Name -contains 'subagent_type') {
+        $subagentType = [string]$data.tool_input.subagent_type
+    }
+    if ($data.tool_input.PSObject.Properties.Name -contains 'team_name') {
+        $teamName = [string]$data.tool_input.team_name
+    }
+}
+
+if (-not $runInBackground) {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+if ($subagentType -eq 'team-lead' -or $teamName) {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+$reason = 'POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy.'
+
+$out = @{
+    hookSpecificOutput = @{
+        hookEventName            = 'PreToolUse'
+        permissionDecision       = 'deny'
+        permissionDecisionReason = $reason
+    }
+} | ConvertTo-Json -Compress -Depth 4
+
+Write-Output $out
+exit 0

package/templates/hooks/enforce-team-for-background-agents.sh

@@ -1,55 +1,55 @@
-#!/usr/bin/env bash
-# Claude Code PreToolUse hook for the Agent tool.
-#
-# Policy enforced by @hivehub/rulebook v5.3.0:
-#   - A single Agent call is fine (foreground or background).
-#   - Spawning multiple standalone Agents for parallel work is FORBIDDEN.
-#     Parallel multi-agent work MUST go through a Team so agents can
-#     communicate via SendMessage.
-#
-# Enforcement strategy:
-#   Block any Agent invocation with `run_in_background: true` UNLESS it
-#   targets `subagent_type: team-lead` or provides a `team_name`. This
-#   forces background parallel work to be coordinated through a Team.
-#
-# The hook reads the tool input JSON from stdin and emits a permission
-# decision JSON on stdout, per Claude Code's PreToolUse hook contract.
-
-set -euo pipefail
-
-input="$(cat)"
-
-tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
-if [[ "$tool_name" != "Agent" ]]; then
-  # Not our concern — allow.
-  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-  exit 0
-fi
-
-run_in_background="$(printf '%s' "$input" | jq -r '.tool_input.run_in_background // false' 2>/dev/null || echo false)"
-subagent_type="$(printf '%s' "$input" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null || true)"
-team_name="$(printf '%s' "$input" | jq -r '.tool_input.team_name // empty' 2>/dev/null || true)"
-
-# Foreground single agent → always allowed.
-if [[ "$run_in_background" != "true" ]]; then
-  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-  exit 0
-fi
-
-# Background agents must be part of a team OR be the team-lead coordinator.
-if [[ "$subagent_type" == "team-lead" ]] || [[ -n "$team_name" ]]; then
-  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
-  exit 0
-fi
-
-# Block standalone background agent.
-reason="POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy."
-
-jq -nc --arg reason "$reason" '{
-  hookSpecificOutput: {
-    hookEventName: "PreToolUse",
-    permissionDecision: "deny",
-    permissionDecisionReason: $reason
-  }
-}'
-exit 0
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook for the Agent tool.
+#
+# Policy enforced by @hivehub/rulebook v5.3.0:
+#   - A single Agent call is fine (foreground or background).
+#   - Spawning multiple standalone Agents for parallel work is FORBIDDEN.
+#     Parallel multi-agent work MUST go through a Team so agents can
+#     communicate via SendMessage.
+#
+# Enforcement strategy:
+#   Block any Agent invocation with `run_in_background: true` UNLESS it
+#   targets `subagent_type: team-lead` or provides a `team_name`. This
+#   forces background parallel work to be coordinated through a Team.
+#
+# The hook reads the tool input JSON from stdin and emits a permission
+# decision JSON on stdout, per Claude Code's PreToolUse hook contract.
+
+set -euo pipefail
+
+input="$(cat)"
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+if [[ "$tool_name" != "Agent" ]]; then
+  # Not our concern — allow.
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+run_in_background="$(printf '%s' "$input" | jq -r '.tool_input.run_in_background // false' 2>/dev/null || echo false)"
+subagent_type="$(printf '%s' "$input" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null || true)"
+team_name="$(printf '%s' "$input" | jq -r '.tool_input.team_name // empty' 2>/dev/null || true)"
+
+# Foreground single agent → always allowed.
+if [[ "$run_in_background" != "true" ]]; then
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Background agents must be part of a team OR be the team-lead coordinator.
+if [[ "$subagent_type" == "team-lead" ]] || [[ -n "$team_name" ]]; then
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Block standalone background agent.
+reason="POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy."
+
+jq -nc --arg reason "$reason" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: $reason
+  }
+}'
+exit 0

package/templates/hooks/on-compact-reinject.sh

@@ -1,34 +1,34 @@
-#!/usr/bin/env bash
-# Claude Code SessionStart hook (matcher: "compact").
-#
-# Re-injects critical architectural context after a conversation
-# compaction. Claude Code already re-loads CLAUDE.md on compact, so
-# this hook is defense-in-depth: it outputs a short, always-fresh
-# cheat sheet from `.rulebook/COMPACT_CONTEXT.md` so the model has
-# the load-bearing reminders immediately available without waiting
-# for the CLAUDE.md re-read.
-#
-# The file is user-editable. Rulebook seeds it during `init` from a
-# stack-specific template and never overwrites it afterward.
-
-set -euo pipefail
-
-PROJECT_ROOT="$(pwd)"
-CONTEXT_FILE="${PROJECT_ROOT}/.rulebook/COMPACT_CONTEXT.md"
-
-if [[ ! -f "$CONTEXT_FILE" ]]; then
-  # Nothing to inject — emit a benign empty additionalContext.
-  printf '%s' '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":""}}'
-  exit 0
-fi
-
-content="$(cat "$CONTEXT_FILE")"
-
-# Emit as additionalContext via jq so we correctly escape newlines/quotes.
-jq -nc --arg ctx "$content" '{
-  hookSpecificOutput: {
-    hookEventName: "SessionStart",
-    additionalContext: $ctx
-  }
-}'
-exit 0
+#!/usr/bin/env bash
+# Claude Code SessionStart hook (matcher: "compact").
+#
+# Re-injects critical architectural context after a conversation
+# compaction. Claude Code already re-loads CLAUDE.md on compact, so
+# this hook is defense-in-depth: it outputs a short, always-fresh
+# cheat sheet from `.rulebook/COMPACT_CONTEXT.md` so the model has
+# the load-bearing reminders immediately available without waiting
+# for the CLAUDE.md re-read.
+#
+# The file is user-editable. Rulebook seeds it during `init` from a
+# stack-specific template and never overwrites it afterward.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(pwd)"
+CONTEXT_FILE="${PROJECT_ROOT}/.rulebook/COMPACT_CONTEXT.md"
+
+if [[ ! -f "$CONTEXT_FILE" ]]; then
+  # Nothing to inject — emit a benign empty additionalContext.
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":""}}'
+  exit 0
+fi
+
+content="$(cat "$CONTEXT_FILE")"
+
+# Emit as additionalContext via jq so we correctly escape newlines/quotes.
+jq -nc --arg ctx "$content" '{
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: $ctx
+  }
+}'
+exit 0