@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/core/harnesses/claude/hooks/lib.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+# lib.sh — shared constants and helpers for session lifecycle hooks
+#
+# Usage: source "$(dirname "$0")/lib.sh"
+#
+# All hooks must:
+#   1. source this file at the top
+#   2. call require_jq immediately after
+#   3. capture stdin once: INPUT=$(cat)
+#   4. use: json_field "$INPUT" ".field_name"
+#
+# Deployment:
+#   This file is installed by the doflow CLI and overwritten on update — do
+#   not edit an installed copy directly.
+
+set -euo pipefail
+
+# ── State directories ────────────────────────────────────────────────────────
+
+# XDG-compliant, agent-agnostic store shared by Claude Code, Codex, Gemini, etc.
+DOFLOW_HOME="${XDG_CONFIG_HOME:-$HOME/.config}/doflow"
+STATE_DIR="$DOFLOW_HOME/session-env"
+SESSION_DIR="$STATE_DIR/sessions"
+PROJECTS_DIR="$STATE_DIR/projects"
+# shellcheck disable=SC2034  # used by session-start.sh and session-end.sh which source this file
+SESSIONS_LOG="$DOFLOW_HOME/sessions.log"
+
+# Identifies which agent is running. Override via env var for non-Claude agents.
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude-code}"
+
+# ── canonicalize_path ─────────────────────────────────────────────────────────
+
+# Print an absolute, symlink-resolved form of <path> to stdout when <path>
+# exists; otherwise print <path> unchanged.
+#
+# Replaces `realpath -e "$1" 2>/dev/null || echo "$1"`, which already fails
+# silently on stock macOS (BSD realpath has no -e flag there) and falls back
+# to an uncanonicalized path. Uses only primitives present on every target
+# (cd, pwd -P, dirname, basename) — no GNU-only flag, no assumed Homebrew
+# coreutils.
+#
+# Hardening notes:
+#   - `CDPATH=` resets CDPATH for the internal `cd` so a user's exported
+#     CDPATH can't redirect it to an unrelated directory of the same name
+#     (and can't make `cd` echo a stray "found via CDPATH" line to stdout).
+#   - `--` guards `dirname`/`basename`/`cd` against a path that begins with
+#     `-` being parsed as an option.
+#   - if the internal `cd` fails for any reason, `||` falls through to the
+#     uncanonicalized-path branch instead of aborting under this file's
+#     `set -e` (matching the old `realpath ... || echo "$1"` degrade path).
+#   - a root-level parent directory ("/") is special-cased so the result
+#     never gets a leading `//`, which POSIX leaves undefined and which
+#     Cygwin/MSYS2 (a DoFlow target platform) interprets as a UNC path.
+canonicalize_path() {
+  local path="$1" dir base
+  if [[ -e "$path" ]] \
+    && dir=$(CDPATH= cd -P -- "$(dirname -- "$path")" 2>/dev/null && pwd -P); then
+    base=$(basename -- "$path")
+    if [[ "$dir" == "/" ]]; then
+      printf '/%s\n' "$base"
+    else
+      printf '%s/%s\n' "$dir" "$base"
+    fi
+  else
+    printf '%s\n' "$path"
+  fi
+}
+
+# ── cwd_hash ─────────────────────────────────────────────────────────────────
+
+# Derive a stable 16-char hash of an absolute directory path.
+# Used to namespace per-project state (compact summaries, warnings).
+# Normalizes symlinks and ../ components so equivalent paths hash identically.
+#
+# For a path that is (or resolves to) an existing directory — the case this
+# function exists for — fully resolves it, including a symlink at the path's
+# own leaf component, via `(cd "$1" && pwd -P)`, so equivalent directories
+# always hash identically. Callers that ever pass a non-directory or
+# nonexistent path fall back to the general-purpose canonicalize_path, which
+# — being usable by any file or missing path, not just directories — only
+# resolves symlinks in the parent chain, not the leaf itself.
+#
+# Hash fallback chain: sha256sum (Linux, Git Bash) -> shasum -a 256 (macOS,
+# every release since 10.6) -> cksum (last resort). The cksum branch is
+# normalized via printf '%016x' to the same 16-lowercase-hex-char contract
+# every other branch provides (raw cksum output is decimal and shorter).
+# Collision risk from the cksum fallback is acceptable here — this is only a
+# cache-key namespace, not security-relevant.
+cwd_hash() {
+  local canonical
+  if [ -d "$1" ]; then
+    canonical=$(cd "$1" && pwd -P)
+  else
+    canonical=$(canonicalize_path "$1")
+  fi
+  if command -v sha256sum &>/dev/null; then
+    echo "$canonical" | sha256sum | cut -c1-16
+  elif command -v shasum &>/dev/null; then
+    echo "$canonical" | shasum -a 256 | cut -c1-16
+  else
+    printf '%016x\n' "$(echo "$canonical" | cksum | cut -d' ' -f1)"
+  fi
+}
+
+# ── with_file_lock / release_file_lock ────────────────────────────────────────
+
+# Cross-platform mutual exclusion via atomic `mkdir` (atomic on every
+# filesystem DoFlow runs on, including NTFS via MSYS2). Replaces
+# `flock -x -w 5 200`, which is entirely absent on stock macOS (util-linux
+# only, causing the session-end log-trimming block to silently no-op today).
+#
+# Usage (caller acquires, then is responsible for releasing — including on
+# failure paths, ideally via `trap`):
+#
+#   if with_file_lock "$LOCK_FILE" 5; then
+#     trap 'release_file_lock "$LOCK_FILE"' EXIT
+#     ...critical section...
+#     release_file_lock "$LOCK_FILE"
+#   fi
+#
+# Polls for the lock (creating "<lockfile>.d" as the lock token) until
+# acquired or until <timeout_seconds> elapses. Returns 0 once acquired
+# (lock held), or 1 on timeout — callers should treat a timeout the same
+# way the old `flock -w 5 200 || exit 0` did: skip the guarded section
+# rather than block indefinitely.
+#
+# Stale-lock recovery: unlike `flock`, an `mkdir` lock is not released
+# automatically if the holder is killed or crashes — a leftover lockdir
+# would otherwise wedge every future acquisition permanently. To guard
+# against that, the holder's PID is written to "<lockfile>.d/pid" at
+# acquire time; when this function finds the lockdir already taken, it
+# checks whether that PID is still alive (`kill -0`) and, if not, treats
+# the lock as abandoned and reclaims it immediately instead of waiting out
+# the full timeout. This is a best-effort check (a PID can in principle be
+# reused by an unrelated process before we look), not a hard guarantee —
+# acceptable here because the guarded sections this protects are idempotent
+# log/state maintenance, not a correctness-critical resource.
+with_file_lock() {
+  local lockfile="$1"
+  local timeout_seconds="$2"
+  local lockdir="${lockfile}.d"
+  local pidfile="${lockdir}/pid"
+  local waited=0 holder_pid
+  while true; do
+    if mkdir "$lockdir" 2>/dev/null; then
+      echo "$$" >"$pidfile" 2>/dev/null || true
+      return 0
+    fi
+    # Someone else holds the lock (or a stale one was left behind) — check
+    # whether the recorded holder is still alive before waiting on it.
+    holder_pid=$(cat "$pidfile" 2>/dev/null || echo "")
+    if [[ -n "$holder_pid" ]] && ! kill -0 "$holder_pid" 2>/dev/null; then
+      rm -rf "$lockdir" 2>/dev/null || true
+      continue
+    fi
+    if (( waited >= timeout_seconds )); then
+      return 1
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+}
+
+# Companion release for with_file_lock. Idempotent — safe to call even if
+# the lock was never acquired or was already released.
+release_file_lock() {
+  local lockfile="$1"
+  local lockdir="${lockfile}.d"
+  rm -f "${lockdir}/pid" 2>/dev/null || true
+  rmdir "$lockdir" 2>/dev/null || true
+}
+
+# ── run_with_timeout ─────────────────────────────────────────────────────────
+
+# Run <command...>, terminating it if it exceeds <seconds>. When no
+# GNU-compatible timeout-enforcing binary (`timeout`/`gtimeout`) is on
+# PATH — stock macOS lacks GNU coreutils' `timeout` unless Homebrew is
+# installed — runs <command...> directly with no enforced budget rather
+# than failing (a soft safety net, not a correctness requirement; NFR-002
+# forbids requiring a new dependency).
+#
+# GNU-ness check: on Git Bash, PATH includes Windows' System32, which ships
+# its own `timeout.exe` — an interactive countdown/delay command with
+# incompatible syntax, not GNU coreutils' `timeout`. If it resolved first
+# and were trusted blindly, `timeout 5 git status` would fail on argument
+# parsing and the wrapped command would never run at all — strictly worse
+# than the no-timeout-found fallback below. So a candidate binary is only
+# trusted after `<bin> --version` succeeds (GNU coreutils understands
+# `--version`; Windows' `timeout.exe` does not and errors out), otherwise
+# the next candidate is tried and, failing that, the command runs directly.
+#
+# Usage: run_with_timeout 5 -- git status
+run_with_timeout() {
+  local seconds="$1"
+  shift
+  if [[ "${1:-}" == "--" ]]; then
+    shift
+  fi
+  local timeout_bin=""
+  if command -v timeout &>/dev/null && timeout --version >/dev/null 2>&1; then
+    timeout_bin="timeout"
+  elif command -v gtimeout &>/dev/null && gtimeout --version >/dev/null 2>&1; then
+    timeout_bin="gtimeout"
+  fi
+  if [[ -n "$timeout_bin" ]]; then
+    "$timeout_bin" "$seconds" "$@"
+  else
+    "$@"
+  fi
+}
+
+# ── Git state helpers ────────────────────────────────────────────────────────
+#
+# Thin wrappers around `git -C <cwd> ...` with the project's standard 1s
+# timeout. Each echoes git's own output (or nothing/0 on failure) and leaves
+# stderr suppressed -- callers keep their own `|| echo <fallback>` around a
+# call for a script-specific default, exactly as the inline git calls these
+# replace did (022-hooks-remaining-duplication). Kept in this per-harness
+# copy rather than moved to the canonical lib.sh's sourcing path: this
+# script's own with_file_lock/other APIs have not been reconciled with the
+# canonical copy, so repointing the `source` line is a separate, larger
+# change this refactor does not make.
+
+is_git_worktree() {
+  run_with_timeout 1 -- git -C "$1" rev-parse --is-inside-work-tree &>/dev/null
+}
+
+git_branch_of() {
+  run_with_timeout 1 -- git -C "$1" branch --show-current 2>/dev/null
+}
+
+git_short_sha_of() {
+  run_with_timeout 1 -- git -C "$1" rev-parse --short HEAD 2>/dev/null
+}
+
+git_uncommitted_count_of() {
+  run_with_timeout 1 -- git -C "$1" status --porcelain 2>/dev/null | wc -l | tr -d ' '
+}
+
+has_uncommitted_changes() {
+  run_with_timeout 1 -- git -C "$1" status --porcelain 2>/dev/null | grep -q .
+}
+
+# ── Directory helpers ─────────────────────────────────────────────────────────
+
+# Create and return the session-scoped state directory for a given session_id.
+# Safe to call multiple times (mkdir -p is idempotent).
+ensure_session_dir() {
+  local session_id="$1"
+  mkdir -p "$SESSION_DIR/$session_id"
+  echo "$SESSION_DIR/$session_id"
+}
+
+# Create and return the project-scoped state directory for a given cwd.
+# Shared across all sessions in the same directory.
+ensure_project_dir() {
+  local cwd="$1"
+  local hash
+  hash=$(cwd_hash "$cwd")
+  mkdir -p "$PROJECTS_DIR/$hash"
+  echo "$PROJECTS_DIR/$hash"
+}
+
+# ── JSON helpers ──────────────────────────────────────────────────────────────
+
+# Extract a field from a JSON string.
+# Usage: json_field "$INPUT" ".field_name"
+# Returns empty string if field is null or jq fails.
+json_field() {
+  local json="$1"
+  local query="$2"
+  echo "$json" | jq -r "$query // empty" 2>/dev/null || echo ""
+}
+
+# ── Dependency guard ──────────────────────────────────────────────────────────
+
+# Verify jq is available at runtime. If absent, emit a diagnostic to stderr
+# and exit 0 (never block Claude Code — degraded operation is preferable to failure).
+require_jq() {
+  if ! command -v jq &>/dev/null; then
+    echo "[hooks] jq not found — install jq to enable session lifecycle hooks (apt install jq / brew install jq)" >&2
+    exit 0
+  fi
+}
+
+# ── Session role ──────────────────────────────────────────────────────────────
+
+# Print `main` or `worker` for this session, read from DOFLOW_SESSION_ROLE (matched
+# case-insensitively). Unset or empty is `main`; a value that is neither `main` nor
+# `worker` is `worker` and writes one line to stderr. A worker never writes or claims the
+# project's compact summary or warning. Always returns 0. bash 3.2 safe (no ${var,,}).
+doflow_session_role() {
+  local role
+  role=$(printf '%s' "${DOFLOW_SESSION_ROLE:-}" | tr '[:upper:]' '[:lower:]') || role=""
+  case "$role" in
+    ""|main) printf 'main\n' ;;
+    worker) printf 'worker\n' ;;
+    *)
+      echo "[doflow] unknown DOFLOW_SESSION_ROLE; treating session as worker" >&2
+      printf 'worker\n'
+      ;;
+  esac
+  return 0
+}

package/core/harnesses/claude/hooks/mcp-tool-guard.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Claude front door: delegates the mcp-tool-guard decision to the Canonical Policy
+# Library, then translates it into Claude Code's verified deny contract.
+#
+# Schema verified (Phase 8.3, 2026-04-17): hookSpecificOutput.permissionDecision
+# "deny" is correctly recognized by Claude Code and blocks execution — exit code
+# alone is not sufficient here, so this front door is a translator, not a bare
+# exec (unlike session-context/stop-check, which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/mcp-tool-guard.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-MCP tool call blocked by mcp-tool-guard}"
+exit 0

package/core/harnesses/claude/hooks/permission-audit.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# permission-audit.sh — PermissionDenied hook (pure observability, no deny path)
+#
+# The decision has already been made by the time this fires; there is nothing to
+# block. Its purpose is completeness of the audit trail: without it the record
+# shows only what was permitted, which makes "this agent never tried X" and "this
+# agent was refused X" indistinguishable after the fact.
+#
+# subagent-audit.sh deliberately does NOT serve this event: it records
+# agent_type/agent_id, which a permission decision does not carry, and would
+# write empty rows into the log it exists to keep meaningful.
+#
+# Appends {timestamp, session_id, event, tool_name, reason} to a session-scoped
+# log. Fields beyond the common envelope are best-effort — an absent key yields
+# empty rather than failing the hook.
+#
+# Multi-session safe: writes only to sessions/{session_id}/permission-audit.log.
+# Must complete in <20ms. Must never exit non-zero.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+EVENT=$(json_field "$INPUT" ".hook_event_name")
+TOOL_NAME=$(json_field "$INPUT" ".tool_name")
+REASON=$(json_field "$INPUT" ".permission_decision_reason")
+TIMESTAMP=$(date -u +%FT%TZ)
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+jq -nc \
+  --arg ts "$TIMESTAMP" \
+  --arg session "$SESSION_ID" \
+  --arg event "$EVENT" \
+  --arg tool "$TOOL_NAME" \
+  --arg reason "$REASON" \
+  '{timestamp: $ts, session_id: $session, event: $event, tool_name: $tool, reason: $reason}' \
+  >> "$SESSION_PATH/permission-audit.log" 2>/dev/null || true
+
+exit 0

package/core/harnesses/claude/hooks/post-compact.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# post-compact.sh — PostCompact hook
+#
+# Saves the AI-generated compact_summary (from stdin JSON) to a project-scoped
+# file. user-prompt-submit.sh reads and injects it directly on the next session's
+# first prompt — no manual restore command required.
+#
+# Atomic write: mktemp → populate → mv ensures readers never see partial content.
+# Multi-session safe: project directory is keyed by cwd hash, not session_id.
+# Must complete in <200ms. Must never exit non-zero or block.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+
+# A worker session never writes the project's summary or metadata: they belong to the main session.
+if [[ "$(doflow_session_role || echo main)" == "worker" ]]; then
+  exit 0
+fi
+
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+CWD=$(json_field "$INPUT" ".cwd")
+TRIGGER=$(json_field "$INPUT" ".trigger")
+COMPACT_SUMMARY=$(json_field "$INPUT" ".compact_summary")
+
+# Guard: nothing useful to save if we don't know where we are
+[[ -z "$CWD" ]] && exit 0
+
+# Guard: an empty summary would write a frontmatter-only file that would be
+# injected as empty context on the next session's first prompt — useless noise, skip it.
+[[ -z "$COMPACT_SUMMARY" ]] && exit 0
+
+PROJECT_DIR=$(ensure_project_dir "$CWD")
+
+# Read current branch for frontmatter metadata (best-effort, empty is fine)
+BRANCH=$(run_with_timeout 5 -- git -C "$CWD" branch --show-current 2>/dev/null || echo "")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Single cleanup function covers both temp files — a second trap() call would
+# silently replace the first, leaving the earlier temp file unguarded on failure.
+TMP=""
+META_TMP=""
+_cleanup() { rm -f "$TMP" "$META_TMP" 2>/dev/null || true; }
+trap _cleanup EXIT
+
+# Atomic write: write to a temp file then rename.
+TMP=$(mktemp "$PROJECT_DIR/.last-compact-summary.XXXXXX")
+cat > "$TMP" <<EOF
+---
+compacted_at: ${TIMESTAMP}
+session_id: ${SESSION_ID:-unknown}
+trigger: ${TRIGGER:-unknown}
+branch: ${BRANCH:-unknown}
+role: main
+---
+
+${COMPACT_SUMMARY}
+EOF
+mv "$TMP" "$PROJECT_DIR/last-compact-summary.md"
+TMP=""  # already moved; _cleanup should not attempt to rm it
+
+# Update meta.json compacted_at (field-merge — do not overwrite other fields)
+if [[ -f "$PROJECT_DIR/meta.json" ]]; then
+  META_TMP=$(mktemp "$PROJECT_DIR/.meta.XXXXXX")
+  if jq --arg ts "$TIMESTAMP" '.compacted_at = $ts' "$PROJECT_DIR/meta.json" > "$META_TMP"; then
+    mv "$META_TMP" "$PROJECT_DIR/meta.json"
+    META_TMP=""  # already moved; _cleanup should not attempt to rm it
+  fi
+fi
+
+exit 0

package/core/harnesses/claude/hooks/post-edit-lint.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# post-edit-lint.sh — PostToolUse(Edit|Write) hook
+#
+# Pure collector: appends the edited/written file_path to a session-scoped
+# list. The actual lint work happens in stop-check.sh at the end of each
+# Claude turn, where all paths can be batched by extension in one pass.
+#
+# Multi-session safe: writes only to sessions/{session_id}/edited-files.txt.
+# Must complete in <20ms. Must never exit non-zero or produce unexpected output.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+TOOL_NAME=$(json_field "$INPUT" ".tool_name")
+
+# Only handle Edit and Write events
+[[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]] && exit 0
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+FILE_PATH=$(json_field "$INPUT" ".tool_input.file_path")
+
+# Skip if no file_path (e.g., field absent from input)
+[[ -z "$FILE_PATH" ]] && exit 0
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+# Append path (one per line) — stop-check.sh reads this list atomically
+echo "$FILE_PATH" >> "$SESSION_PATH/edited-files.txt"
+
+exit 0

package/core/harnesses/claude/hooks/post-tool-failure.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# post-tool-failure.sh — PostToolUse*Failure* hook (pure observability, no deny path)
+#
+# A failed tool call is the one outcome no other hook records. post-edit-lint.sh
+# deliberately does NOT serve this event: it queues a path for end-of-turn linting,
+# and on a failure the file was never written — queuing it would lint content that
+# does not exist. This hook is the separate handler that failure case needs.
+#
+# Appends {timestamp, session_id, event, tool_name, file_path, error} to a
+# session-scoped log. Fields beyond the common envelope (session_id,
+# hook_event_name, tool_name) are best-effort: json_field yields empty for any
+# absent key, so a payload shape change degrades to a thinner record rather than
+# a broken hook.
+#
+# Multi-session safe: writes only to sessions/{session_id}/tool-failures.log.
+# Must complete in <20ms. Must never exit non-zero or block the turn.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+EVENT=$(json_field "$INPUT" ".hook_event_name")
+TOOL_NAME=$(json_field "$INPUT" ".tool_name")
+FILE_PATH=$(json_field "$INPUT" ".tool_input.file_path")
+ERROR=$(json_field "$INPUT" ".tool_response.error")
+TIMESTAMP=$(date -u +%FT%TZ)
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+jq -nc \
+  --arg ts "$TIMESTAMP" \
+  --arg session "$SESSION_ID" \
+  --arg event "$EVENT" \
+  --arg tool "$TOOL_NAME" \
+  --arg file "$FILE_PATH" \
+  --arg error "$ERROR" \
+  '{timestamp: $ts, session_id: $session, event: $event, tool_name: $tool, file_path: $file, error: $error}' \
+  >> "$SESSION_PATH/tool-failures.log" 2>/dev/null || true
+
+exit 0

package/core/harnesses/claude/hooks/pre-bash-guard.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Claude front door: delegates the pre-bash-guard decision to the Canonical Policy
+# Library, then translates it into Claude Code's verified deny contract.
+#
+# Schema verified (Phase 8.3, 2026-04-17): hookSpecificOutput.permissionDecision
+# "deny" is correctly recognized by Claude Code and blocks execution — exit code
+# alone is not sufficient here, so this front door is a translator, not a bare
+# exec (unlike session-context/stop-check, which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-bash-guard.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-Command blocked by pre-bash-guard}"
+exit 0

package/core/harnesses/claude/hooks/pre-compact.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# pre-compact.sh — PreCompact hook
+#
+# Outputs a plain string to stdout that Claude Code passes as custom_instructions
+# to the compaction LLM call. This enriches the compact summary with git state
+# so the summary preserves branch/commit context for the next session.
+#
+# Output is a plain string — NOT JSON.
+# Must be under ~500 chars (Claude Code may truncate longer strings).
+# Must never exit non-zero or block.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+CWD=$(json_field "$INPUT" ".cwd")
+
+BRANCH=""
+SHA=""
+UNCOMMITTED=0
+
+if [[ -n "$CWD" ]] && is_git_worktree "$CWD"; then
+  BRANCH=$(git_branch_of "$CWD" || echo "")
+  SHA=$(git_short_sha_of "$CWD" || echo "")
+  UNCOMMITTED=$(git_uncommitted_count_of "$CWD" || echo "0")
+
+  # Last 2 commits (short SHA only for brevity) — keeps output under 500 chars
+  RECENT=$(run_with_timeout 1 -- git -C "$CWD" log --format="%h %s" -2 2>/dev/null \
+    | paste -sd ' | ' - || echo "")
+
+  # Build output and hard-cap at 490 chars to stay within Claude Code's limit
+  OUT=$(printf 'Include in compact summary:\n- git branch: %s sha: %s\n- recent commits: %s\n- uncommitted files: %s\n- cwd: %s\nPreserve: decisions made, files modified, open questions, planned next steps.' \
+    "${BRANCH:-unknown}" "${SHA:-unknown}" "${RECENT:-none}" "$UNCOMMITTED" "${CWD:-unknown}")
+  printf '%s' "${OUT:0:490}"
+else
+  OUT=$(printf 'Include in compact summary:\n- cwd: %s (not a git repository)\nPreserve: decisions made, files modified, open questions, planned next steps.' \
+    "${CWD:-unknown}")
+  printf '%s' "${OUT:0:490}"
+fi
+
+exit 0

package/core/harnesses/claude/hooks/pre-implement-gate.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Claude front door: delegates the pre-implementation-gate decision to the
+# Canonical Policy Library, then translates it into Claude Code's verified deny
+# contract.
+#
+# Schema verified (Phase 8.3, 2026-04-17): hookSpecificOutput.permissionDecision
+# "deny" is correctly recognized by Claude Code and blocks execution — exit code
+# alone is not sufficient here, so this front door is a translator, not a bare
+# exec (unlike session-context/stop-check, which never need this translation).
+set -uo pipefail
+export DOFLOW_AGENT="${DOFLOW_AGENT:-claude}"
+
+command -v jq >/dev/null 2>&1 || exit 0
+source "$(dirname "$0")/../../.doflow/shared/hooks/policies/deny-json.sh"
+
+POLICY="$(dirname "$0")/../../.doflow/shared/hooks/policies/pre-implementation-gate.sh"
+REASON=$(bash "$POLICY" 2>&1 >/dev/null)
+CODE=$?
+
+[ "$CODE" -ne 0 ] && emit_pretooluse_deny_nested "${REASON:-Implementation requires an approved plan.md}"
+exit 0