diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7c50194..92ed7c2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,6 +44,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # The devkit-guard shell wrappers exec the Go engine binary.
+      # Provide Go so hooks_test.sh can build it on first run (the
+      # script auto-builds if $CLAUDE_PLUGIN_ROOT/bin/devkit-engine is
+      # missing) — without this, every "expected exit 2" fixture would
+      # silently fall through the no-binary path and fail.
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: src/go.mod
+          cache-dependency-path: src/go.sum
+
       - name: Run hook smoke tests
         run: bash hooks/hooks_test.sh
 
diff --git a/hooks/devkit-guard.sh b/hooks/devkit-guard.sh
index 248dc85..1b4901e 100755
--- a/hooks/devkit-guard.sh
+++ b/hooks/devkit-guard.sh
@@ -1,124 +1,67 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# nullglob: an unmatched glob expands to nothing rather than the literal
+# pattern, so the array-glob construct below is correct when no
+# versioned binary exists.
+shopt -s nullglob
 
 # devkit-guard: PreToolUse hook that enforces workflow step ordering.
-# Reads $CLAUDE_PLUGIN_DATA/session.json. Blocks out-of-step actions.
-# Exit 0 = allow, Exit 2 + stderr = hard block.
+# Thin wrapper around `devkit-engine guard`. All policy lives in Go
+# (src/cmd/guard.go) so the shell side is just binary resolution + exec.
 #
-# Policy matrix:
-#   step_type=command, enforce=hard → allow only devkit MCP + TodoWrite
-#                                     (engine runs the command, not Claude)
-#   step_type=prompt,  enforce=hard → allow Read/Grep/Glob/NotebookRead/
-#                                     TodoWrite + devkit MCP. Forces the
-#                                     agent to advance before any
-#                                     write/bash/dispatch. Closes issue #63
-#                                     drift hole.
-#   step_type=prompt,  enforce=soft → allow everything, emit stderr nudge
-#   step_type=parallel             → allow everything (engine dispatches)
-#   stale session (see lib/read-session.sh) → allow + warn; do not enforce
-#                                     against an orphaned state file.
+# Exit 0 = allow, exit 2 = hard block (with diagnostic on stderr).
+# Stdin (the PreToolUse JSON payload) is passed through unchanged so
+# the engine can parse tool_name itself — no jq, no python3.
 #
-# This hook uses an ALLOWLIST rather than a blocklist because the
-# Claude Code tool surface evolves — Task, SlashCommand, ExitPlanMode,
-# BashOutput, KillBash, TodoWrite, any mcp__* tool, and future names
-# would silently bypass a blocklist of hardcoded names.
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=lib/read-session.sh
-source "${SCRIPT_DIR}/lib/read-session.sh"
+# Binary search order:
+#   1. $CLAUDE_PLUGIN_ROOT/bin/devkit-engine          — local dev symlink
+#   2. $CLAUDE_PLUGIN_ROOT/bin/devkit-engine-v*       — shipped release asset
+#
+# The `bin/devkit` first-run-download wrapper is DELIBERATELY not
+# reachable from this hook: downloading release assets from a
+# time-limited PreToolUse hook is unsafe (timeout → silent fail-open).
+# When no binary is found we fail OPEN with a LOUD diagnostic so the
+# user notices on their first tool call — blocking every tool call on
+# a broken install would wedge the session with no recovery path
+# except manually editing hooks.
 
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-}"
-if [[ -z "$DATA_DIR" ]]; then
-  printf 'devkit-guard: CLAUDE_PLUGIN_DATA unset — enforcement disabled\n' >&2
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [[ -z "$PLUGIN_ROOT" ]]; then
+  printf 'devkit-guard: CLAUDE_PLUGIN_ROOT unset — enforcement disabled\n' >&2
   exit 0
 fi
 
-SESSION_FILE="${DATA_DIR}/session.json"
+BIN_DIR="$PLUGIN_ROOT/bin"
 
-if ! parse_session_fields "$SESSION_FILE"; then
-  # python3 unavailable or JSON corrupt — fail closed if session file
-  # exists, otherwise fall through (no session = nothing to guard).
-  if [[ -f "$SESSION_FILE" ]]; then
-    printf 'BLOCKED: Cannot parse session state (python3 required or JSON corrupt). Remove %s to clear.\n' "$SESSION_FILE" >&2
-    exit 2
-  fi
-  exit 0
+# Preferred: local-dev symlink (created by `make install-plugin`).
+if [[ -x "$BIN_DIR/devkit-engine" ]]; then
+  exec "$BIN_DIR/devkit-engine" guard
 fi
 
-if [[ "$SESSION_STATUS" != "running" ]]; then
-  exit 0
-fi
-
-if [[ "$SESSION_STALE" == "1" ]]; then
-  printf 'devkit-guard: session %s idle past TTL — treating as orphaned (run devkit_start to reclaim)\n' "$SESSION_WORKFLOW" >&2
-  exit 0
-fi
-
-# Read tool name from stdin. Matches PreToolUse payload format.
-INPUT=$(cat)
-TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null) || {
-  # Malformed payload — surface a diagnostic so the transcript shows
-  # why the next veto lists an empty tool name, instead of letting the
-  # BLOCKED message say "(attempted tool: )" with no hint.
-  printf 'devkit-guard: could not parse tool name from PreToolUse payload (python3 or JSON error)\n' >&2
-  TOOL_NAME=""
-}
-
-# Build a progress label for veto messages so the agent always sees
-# workflow + position without another devkit_status round trip.
-step_label() {
-  if [[ -n "$SESSION_CURRENT_INDEX" && -n "$SESSION_TOTAL_STEPS" ]]; then
-    local human_index=$((SESSION_CURRENT_INDEX + 1))
-    printf '%s step %d/%d (%s)' "$SESSION_WORKFLOW" "$human_index" "$SESSION_TOTAL_STEPS" "$SESSION_CURRENT_STEP"
-  else
-    printf '%s (%s)' "$SESSION_WORKFLOW" "$SESSION_CURRENT_STEP"
+# Shipped release assets. Filenames look like
+# devkit-engine-v2.1.7-darwin-arm64. Pick the highest semver via
+# `sort -V` (GNU coreutils; available on Ubuntu runners and recent
+# macOS). A naive string comparison would pick v2.1.9 over v2.1.10
+# because `9 > 1` lexicographically — sort -V understands version
+# fields and orders them correctly.
+candidates=()
+for candidate in "$BIN_DIR"/devkit-engine-v*; do
+  [[ -x "$candidate" ]] && candidates+=("$candidate")
+done
+if (( ${#candidates[@]} > 0 )); then
+  latest=$(printf '%s\n' "${candidates[@]}" | sort -V | tail -n1)
+  if [[ -n "$latest" && -x "$latest" ]]; then
+    exec "$latest" guard
   fi
-}
-
-# Command steps: allow ONLY the MCP tools needed to progress the
-# workflow. Everything else is blocked, including future tools.
-if [[ "$SESSION_STEP_TYPE" == "command" && "$SESSION_ENFORCE" == "hard" ]]; then
-  case "$TOOL_NAME" in
-    mcp__*devkit-engine*|mcp__devkit__*|devkit_advance|devkit_status|devkit_list|devkit_start)
-      exit 0
-      ;;
-    TodoWrite)
-      exit 0
-      ;;
-    *)
-      printf 'BLOCKED: Command step "%s" in progress — the engine runs this step. Call devkit_advance to execute it. (attempted tool: %s)\n' "$(step_label)" "$TOOL_NAME" >&2
-      exit 2
-      ;;
-  esac
-fi
-
-# Prompt steps under hard enforcement: allow read-only evidence tools
-# plus devkit MCP. Blocks Write/Edit/Bash/Task/WebFetch/other MCP so
-# the agent cannot drift into unrelated work between step 1 and
-# devkit_advance. See issue #63.
-if [[ "$SESSION_STEP_TYPE" == "prompt" && "$SESSION_ENFORCE" == "hard" ]]; then
-  case "$TOOL_NAME" in
-    mcp__*devkit-engine*|mcp__devkit__*|devkit_advance|devkit_status|devkit_list|devkit_start)
-      exit 0
-      ;;
-    Read|Grep|Glob|TodoWrite|NotebookRead)
-      exit 0
-      ;;
-    *)
-      printf 'BLOCKED: devkit workflow %s is at a prompt step — gather evidence with Read/Grep/Glob then call devkit_advance. (attempted tool: %s)\n' "$(step_label)" "$TOOL_NAME" >&2
-      exit 2
-      ;;
-  esac
-fi
-
-# Prompt steps under soft enforcement: allow everything, but inject a
-# stderr nudge so the transcript shows the agent that a step is open.
-# Soft nudge is idempotent — if the agent ignores it, Stop gate still
-# blocks via devkit-stop-guard.sh.
-if [[ "$SESSION_STEP_TYPE" == "prompt" && "$SESSION_ENFORCE" != "hard" ]]; then
-  printf 'devkit-guard: %s is open — call devkit_advance when the step is complete.\n' "$(step_label)" >&2
-  exit 0
 fi
 
-# Parallel steps: engine is dispatching, agent needs full tool access.
+# No cached binary at all. Loud diagnostic + allow — see header
+# comment for the fail-open rationale. Point the user at the real
+# self-downloader at $BIN_DIR/devkit (that wrapper handles the
+# download + verify + cache flow on first run). There is no
+# `devkit install` subcommand — `devkit --version` triggers the same
+# cache-if-missing path with zero side effects.
+printf 'devkit-guard: ERROR no devkit-engine binary under %s — ' "$BIN_DIR" >&2
+printf 'run `%s/devkit --version` once to download and cache the engine. ' "$BIN_DIR" >&2
+printf 'Workflow enforcement is DISABLED until this is fixed.\n' >&2
 exit 0
diff --git a/hooks/devkit-guard_test.sh b/hooks/devkit-guard_test.sh
deleted file mode 100755
index ab50a3e..0000000
--- a/hooks/devkit-guard_test.sh
+++ /dev/null
@@ -1,231 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Fixture matrix test for devkit-guard.sh.
-# Seeds CLAUDE_PLUGIN_DATA with a crafted session.json and pipes a
-# synthetic PreToolUse payload on stdin. Asserts exit code and the
-# substring of whatever stderr diagnostic the guard emitted.
-#
-# Run: bash hooks/devkit-guard_test.sh
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-GUARD="${SCRIPT_DIR}/devkit-guard.sh"
-
-if [[ ! -x "$GUARD" ]]; then
-  chmod +x "$GUARD" || true
-fi
-
-PASS=0
-FAIL=0
-FAILED_CASES=()
-
-# run_case <label> <session-json|""> <tool-name> <expected-exit> <expected-stderr-substr-or-empty>
-run_case() {
-  local label="$1"
-  local session_json="$2"
-  local tool_name="$3"
-  local expected_exit="$4"
-  local expected_substr="${5:-}"
-
-  local tmpdir
-  tmpdir=$(mktemp -d)
-  # shellcheck disable=SC2064
-  trap "rm -rf '$tmpdir'" RETURN
-
-  if [[ -n "$session_json" ]]; then
-    printf '%s' "$session_json" > "${tmpdir}/session.json"
-  fi
-
-  local payload
-  payload=$(printf '{"tool_name":"%s"}' "$tool_name")
-
-  set +e
-  CLAUDE_PLUGIN_DATA="$tmpdir" output=$(printf '%s' "$payload" | bash "$GUARD" 2>&1)
-  local actual_exit=$?
-  set -e
-
-  local ok=1
-  if [[ "$actual_exit" != "$expected_exit" ]]; then
-    ok=0
-  fi
-  if [[ -n "$expected_substr" && "$output" != *"$expected_substr"* ]]; then
-    ok=0
-  fi
-
-  if [[ $ok -eq 1 ]]; then
-    PASS=$((PASS + 1))
-    printf '  PASS  %s\n' "$label"
-  else
-    FAIL=$((FAIL + 1))
-    FAILED_CASES+=("$label (exit=$actual_exit, expected=$expected_exit, output=$output)")
-    printf '  FAIL  %s  (exit=%s expected=%s)\n    output: %s\n' "$label" "$actual_exit" "$expected_exit" "$output"
-  fi
-
-  rm -rf "$tmpdir"
-  trap - RETURN
-}
-
-# --- Fixtures --------------------------------------------------------------
-
-NOW_ISO=$(python3 -c 'import datetime; print(datetime.datetime.now(datetime.timezone.utc).isoformat())')
-STALE_ISO="2020-01-01T00:00:00+00:00"
-
-fresh_session() {
-  local step_type="$1"
-  local enforce="$2"
-  local status="${3:-running}"
-  printf '{
-  "id": "abc123",
-  "workflow": "tri-review",
-  "current_step": "gather",
-  "current_index": 0,
-  "total_steps": 6,
-  "step_type": "%s",
-  "enforce": "%s",
-  "status": "%s",
-  "started_at": "%s",
-  "updated_at": "%s"
-}' "$step_type" "$enforce" "$status" "$NOW_ISO" "$NOW_ISO"
-}
-
-stale_session() {
-  printf '{
-  "id": "abc123",
-  "workflow": "tri-review",
-  "current_step": "gather",
-  "current_index": 0,
-  "total_steps": 6,
-  "step_type": "prompt",
-  "enforce": "hard",
-  "status": "running",
-  "started_at": "%s",
-  "updated_at": "%s"
-}' "$STALE_ISO" "$STALE_ISO"
-}
-
-# --- Cases -----------------------------------------------------------------
-
-printf 'devkit-guard fixture matrix:\n'
-
-# No session file → always allow.
-run_case "no-session allows Write" "" "Write" 0 ""
-run_case "no-session allows Bash"  "" "Bash"  0 ""
-
-# status != running → always allow.
-run_case "status=done allows Write" \
-  "$(fresh_session prompt hard done)" "Write" 0 ""
-
-# Command step + hard: devkit + TodoWrite allowed, rest blocked.
-run_case "command-hard allows devkit_advance" \
-  "$(fresh_session command hard)" "mcp__plugin_devkit_devkit-engine__devkit_advance" 0 ""
-run_case "command-hard allows TodoWrite" \
-  "$(fresh_session command hard)" "TodoWrite" 0 ""
-run_case "command-hard blocks Write" \
-  "$(fresh_session command hard)" "Write" 2 "BLOCKED"
-run_case "command-hard blocks Bash" \
-  "$(fresh_session command hard)" "Bash" 2 "BLOCKED"
-
-# Prompt step + hard: evidence tools allowed, writes blocked. This is
-# the new behaviour closing issue #63.
-run_case "prompt-hard allows Read"  "$(fresh_session prompt hard)" "Read"  0 ""
-run_case "prompt-hard allows Grep"  "$(fresh_session prompt hard)" "Grep"  0 ""
-run_case "prompt-hard allows Glob"  "$(fresh_session prompt hard)" "Glob"  0 ""
-run_case "prompt-hard allows TodoWrite" "$(fresh_session prompt hard)" "TodoWrite" 0 ""
-run_case "prompt-hard allows devkit_advance" \
-  "$(fresh_session prompt hard)" "mcp__plugin_devkit_devkit-engine__devkit_advance" 0 ""
-run_case "prompt-hard blocks Write" "$(fresh_session prompt hard)" "Write" 2 "tri-review"
-run_case "prompt-hard blocks Edit"  "$(fresh_session prompt hard)" "Edit"  2 "BLOCKED"
-run_case "prompt-hard blocks Bash"  "$(fresh_session prompt hard)" "Bash"  2 "gather"
-run_case "prompt-hard blocks Task"  "$(fresh_session prompt hard)" "Task"  2 "BLOCKED"
-run_case "prompt-hard blocks WebFetch" \
-  "$(fresh_session prompt hard)" "WebFetch" 2 "BLOCKED"
-
-# Prompt step + soft: allow everything but emit a nudge on stderr.
-run_case "prompt-soft allows Write with nudge" \
-  "$(fresh_session prompt soft)" "Write" 0 "call devkit_advance"
-run_case "prompt-soft allows Bash" \
-  "$(fresh_session prompt soft)" "Bash" 0 "devkit-guard:"
-
-# Parallel step: always allow.
-run_case "parallel allows Write" \
-  "$(fresh_session parallel hard)" "Write" 0 ""
-
-# Stale session → allow + warn, regardless of step type. The stale
-# branch fires BEFORE the step-type dispatch, so flipping the order
-# would regress these cases.
-run_case "stale-prompt-hard allows Write (orphaned)" \
-  "$(stale_session)" "Write" 0 "orphaned"
-
-stale_session_with() {
-  # Args: step_type enforce
-  printf '{
-  "id": "abc123",
-  "workflow": "tri-review",
-  "current_step": "gather",
-  "current_index": 0,
-  "total_steps": 6,
-  "step_type": "%s",
-  "enforce": "%s",
-  "status": "running",
-  "started_at": "%s",
-  "updated_at": "%s"
-}' "$1" "$2" "$STALE_ISO" "$STALE_ISO"
-}
-
-run_case "stale-command-hard allows Bash (orphaned)" \
-  "$(stale_session_with command hard)" "Bash" 0 "orphaned"
-run_case "stale-prompt-soft allows Write (orphaned)" \
-  "$(stale_session_with prompt soft)" "Write" 0 "orphaned"
-
-# Backward-compat: session with only started_at (no updated_at) —
-# the parser falls through to started_at for pre-UpdatedAt binaries.
-run_case "legacy-session (no updated_at) treated as fresh when recent" \
-  "$(printf '{
-  "id": "legacy1",
-  "workflow": "tri-review",
-  "current_step": "gather",
-  "current_index": 0,
-  "total_steps": 6,
-  "step_type": "prompt",
-  "enforce": "hard",
-  "status": "running",
-  "started_at": "%s"
-}' "$NOW_ISO")" "Write" 2 "BLOCKED"
-
-# Corrupt JSON → fail-closed exit 2. Exercises the new code path on
-# the shared helper; the legacy hooks_test.sh only covered the old
-# inline parser.
-corrupt_tmp=$(mktemp -d)
-printf '{this is not json' > "$corrupt_tmp/session.json"
-set +e
-CLAUDE_PLUGIN_DATA="$corrupt_tmp" output=$(printf '{"tool_name":"Bash"}' | bash "$GUARD" 2>&1)
-corrupt_exit=$?
-set -e
-if [[ "$corrupt_exit" == "2" && "$output" == *"Cannot parse session state"* ]]; then
-  PASS=$((PASS + 1))
-  printf '  PASS  corrupt JSON fails closed with diagnostic\n'
-else
-  FAIL=$((FAIL + 1))
-  printf '  FAIL  corrupt JSON fails closed (exit=%s output=%s)\n' "$corrupt_exit" "$output"
-fi
-rm -rf "$corrupt_tmp"
-
-# C1 regression guard: the devkit MCP allowlist must be narrow enough
-# not to admit a third-party MCP tool whose name happens to contain
-# "devkit". Use a plausible-looking foreign tool name.
-run_case "prompt-hard blocks foreign devkit-like mcp" \
-  "$(fresh_session prompt hard)" "mcp__other__my_devkit_plugin" 2 "BLOCKED"
-run_case "prompt-hard allows real devkit-engine mcp" \
-  "$(fresh_session prompt hard)" "mcp__plugin_devkit_devkit-engine__devkit_advance" 0 ""
-
-# --- Report ---------------------------------------------------------------
-
-printf '\n%d passed, %d failed\n' "$PASS" "$FAIL"
-if [[ $FAIL -gt 0 ]]; then
-  printf '\nFailed cases:\n'
-  for c in "${FAILED_CASES[@]}"; do
-    printf '  - %s\n' "$c"
-  done
-  exit 1
-fi
-exit 0
diff --git a/hooks/devkit-stop-guard.sh b/hooks/devkit-stop-guard.sh
index 4322cf0..60725bb 100755
--- a/hooks/devkit-stop-guard.sh
+++ b/hooks/devkit-stop-guard.sh
@@ -1,73 +1,49 @@
 #!/usr/bin/env bash
 set -euo pipefail
+shopt -s nullglob
 
-# devkit-stop-guard: Stop hook that blocks session end during active workflows.
-# Outputs JSON: {"decision":"approve"} or {"decision":"block","reason":"..."}.
+# devkit-stop-guard: Stop hook that blocks session end during active
+# workflows. Thin wrapper around `devkit-engine guard --stop`. Emits
+# JSON ({"decision":"approve"} or {"decision":"block","reason":"..."})
+# on stdout and always exits 0 — Stop hooks communicate via verdict
+# payload, not exit code.
 #
-# Policy: symmetric with devkit-guard.sh. If the session file exists but
-# cannot be parsed, we fail CLOSED (block with a clear reason) rather
-# than silently approve — a corrupted state file during an active
-# workflow is a bug the user needs to see, not something to paper over.
-# Stale sessions (see lib/read-session.sh TTL) are treated as orphaned
-# and the Stop is approved so the user is never wedged by a crashed
-# engine process.
+# Binary search order and no-binary fallback rationale: see
+# devkit-guard.sh header comment.
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=lib/read-session.sh
-source "${SCRIPT_DIR}/lib/read-session.sh"
-
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-}"
-if [[ -z "$DATA_DIR" ]]; then
-  printf 'devkit-stop-guard: CLAUDE_PLUGIN_DATA unset — enforcement disabled\n' >&2
-  printf '{"decision":"approve"}'
-  exit 0
-fi
-
-SESSION_FILE="${DATA_DIR}/session.json"
-
-if ! parse_session_fields "$SESSION_FILE"; then
-  if [[ -f "$SESSION_FILE" ]]; then
-    printf 'devkit-stop-guard: cannot parse session state (python3 missing or JSON corrupt); blocking Stop\n' >&2
-    printf '{"decision":"block","reason":"devkit session state corrupted — remove %s to clear"}' "$SESSION_FILE"
-    exit 0
-  fi
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+if [[ -z "$PLUGIN_ROOT" ]]; then
+  printf 'devkit-stop-guard: CLAUDE_PLUGIN_ROOT unset — enforcement disabled\n' >&2
   printf '{"decision":"approve"}'
   exit 0
 fi
 
-if [[ "$SESSION_STATUS" != "running" ]]; then
-  printf '{"decision":"approve"}'
-  exit 0
-fi
+BIN_DIR="$PLUGIN_ROOT/bin"
 
-if [[ "$SESSION_STALE" == "1" ]]; then
-  printf 'devkit-stop-guard: session %s idle past TTL — approving Stop (reclaim on next devkit_start)\n' "$SESSION_WORKFLOW" >&2
-  printf '{"decision":"approve"}'
-  exit 0
+if [[ -x "$BIN_DIR/devkit-engine" ]]; then
+  exec "$BIN_DIR/devkit-engine" guard --stop
 fi
 
-REMAINING=0
-if [[ -n "$SESSION_TOTAL_STEPS" && -n "$SESSION_CURRENT_INDEX" ]]; then
-  REMAINING=$((SESSION_TOTAL_STEPS - SESSION_CURRENT_INDEX))
+# Pick the highest semver via sort -V. See devkit-guard.sh for the
+# rationale on why a naive string comparison is wrong (v2.1.9 would
+# lexicographically sort above v2.1.10).
+candidates=()
+for candidate in "$BIN_DIR"/devkit-engine-v*; do
+  [[ -x "$candidate" ]] && candidates+=("$candidate")
+done
+if (( ${#candidates[@]} > 0 )); then
+  latest=$(printf '%s\n' "${candidates[@]}" | sort -V | tail -n1)
+  if [[ -n "$latest" && -x "$latest" ]]; then
+    exec "$latest" guard --stop
+  fi
 fi
-WF="${SESSION_WORKFLOW:-unknown}"
 
-# Emit the block verdict via python3 json.dumps so the reason string is
-# escaped safely — workflow names and step IDs flow from workflow YAML
-# and could theoretically contain characters that need escaping.
-# Fail-closed fallback: if python3 crashes (OOM, broken pipe, PATH race)
-# after parse_session_fields already succeeded, emit a plain-ASCII block
-# verdict manually so Claude Code still sees a decision — without this
-# the script would exit under `set -e` and the Stop hook behaviour
-# becomes undefined.
-if ! python3 -c '
-import json, sys
-print(json.dumps({
-    "decision": "block",
-    "reason": f"Workflow {sys.argv[1]} incomplete — {sys.argv[2]} steps remaining. Call devkit_advance to continue."
-}))
-' "$WF" "$REMAINING" 2>/dev/null; then
-  printf 'devkit-stop-guard: verdict emit failed; falling back to manual JSON\n' >&2
-  printf '{"decision":"block","reason":"devkit workflow incomplete — call devkit_advance to continue"}'
-fi
+# No engine binary: approve so the user is never wedged in an
+# un-stoppable session. Loud stderr so the broken install is visible.
+# Point at the real self-downloader at $BIN_DIR/devkit, not a
+# non-existent `devkit install` subcommand.
+printf 'devkit-stop-guard: ERROR no devkit-engine binary under %s — ' "$BIN_DIR" >&2
+printf 'run `%s/devkit --version` once to cache the engine. ' "$BIN_DIR" >&2
+printf 'Stop enforcement DISABLED.\n' >&2
+printf '{"decision":"approve"}'
 exit 0
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 52780a3..4682826 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -75,7 +75,7 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/devkit-guard.sh",
             "statusMessage": "Workflow guard...",
-            "timeout": 5
+            "timeout": 10
           }
         ]
       }
@@ -158,7 +158,7 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/devkit-stop-guard.sh",
             "statusMessage": "Workflow check...",
-            "timeout": 2
+            "timeout": 10
           }
         ]
       }
diff --git a/hooks/hooks_test.sh b/hooks/hooks_test.sh
index aa52a5d..01f2444 100644
--- a/hooks/hooks_test.sh
+++ b/hooks/hooks_test.sh
@@ -8,6 +8,32 @@
 set -uo pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+# The devkit-guard.sh / devkit-stop-guard.sh wrappers need
+# CLAUDE_PLUGIN_ROOT to locate the engine binary. Default it to the
+# repo root when unset so `bash hooks/hooks_test.sh` just works from
+# a fresh clone (CI and local dev alike), matching how the wrappers
+# behave in production (CLAUDE_PLUGIN_ROOT points at the installed
+# plugin dir, which has the same layout as the repo root).
+REPO_ROOT="$(cd "$HOOK_DIR/.." && pwd)"
+export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$REPO_ROOT}"
+
+# Ensure the Go engine binary exists so the devkit-guard wrapper tests
+# exercise the real binary, not the "no binary → loud warn + allow"
+# fallback. That fallback is correct production behavior (don't wedge
+# the session on a broken install) but in tests it silently turns
+# every "expected exit 2" fixture into a false pass.
+ENGINE_BIN="$CLAUDE_PLUGIN_ROOT/bin/devkit-engine"
+if [[ ! -x "$ENGINE_BIN" ]]; then
+  if command -v go >/dev/null 2>&1 && [[ -f "$REPO_ROOT/src/go.mod" ]]; then
+    printf 'hooks_test.sh: building devkit-engine for guard tests...\n' >&2
+    (cd "$REPO_ROOT/src" && go build -o "$ENGINE_BIN" .) || {
+      printf 'hooks_test.sh: failed to build devkit-engine — guard tests will fall through the no-binary path and some fixtures will be skipped\n' >&2
+    }
+  else
+    printf 'hooks_test.sh: go unavailable and no devkit-engine binary at %s — guard tests will use the no-binary fallback path\n' "$ENGINE_BIN" >&2
+  fi
+fi
+
 PASS=0
 FAIL=0
 ERRORS=""
@@ -352,6 +378,112 @@ else
   fail "devkit-stop-guard: corrupt JSON (got: $out)"
 fi
 
+echo ""
+echo "=== Shell wrapper binary resolution ==="
+
+# These tests exercise the 3-tier binary resolution in the wrappers
+# themselves, not the Go guard logic. Previously untested — the thin
+# wrappers are exactly where silent bugs hide on fresh installs.
+
+# CLAUDE_PLUGIN_ROOT unset → disabled warning + exit 0 (guard)
+out=$(CLAUDE_PLUGIN_ROOT="" printf '{"tool_name":"Bash"}' \
+  | CLAUDE_PLUGIN_ROOT="" bash "$HOOK_DIR/devkit-guard.sh" 2>&1)
+exit_code=$?
+if [[ $exit_code -eq 0 && "$out" == *"CLAUDE_PLUGIN_ROOT unset"* ]]; then
+  pass "devkit-guard: CLAUDE_PLUGIN_ROOT unset → disabled + exit 0"
+else
+  fail "devkit-guard: CLAUDE_PLUGIN_ROOT unset (exit=$exit_code out=$out)"
+fi
+
+# CLAUDE_PLUGIN_ROOT unset → {"decision":"approve"} (stop-guard)
+out=$(CLAUDE_PLUGIN_ROOT="" printf '{}' \
+  | CLAUDE_PLUGIN_ROOT="" bash "$HOOK_DIR/devkit-stop-guard.sh" 2>/dev/null)
+if printf '%s' "$out" | jq -e '.decision=="approve"' >/dev/null 2>&1; then
+  pass "devkit-stop-guard: CLAUDE_PLUGIN_ROOT unset → approve"
+else
+  fail "devkit-stop-guard: CLAUDE_PLUGIN_ROOT unset (out=$out)"
+fi
+
+# Empty bin/ directory — simulates a fresh install before the binary
+# has been built or downloaded. Wrappers must log + allow (guard) /
+# log + approve (stop-guard). Point PLUGIN_ROOT at a tmp dir with
+# only an empty bin/ subdir and the real hook scripts copied in.
+empty_root=$(mktemp -d)
+track_tmp "$empty_root"
+mkdir -p "$empty_root/bin" "$empty_root/hooks"
+cp "$HOOK_DIR/devkit-guard.sh" "$HOOK_DIR/devkit-stop-guard.sh" "$empty_root/hooks/"
+chmod +x "$empty_root/hooks/"*.sh
+
+out=$(printf '{"tool_name":"Bash"}' \
+  | CLAUDE_PLUGIN_ROOT="$empty_root" bash "$empty_root/hooks/devkit-guard.sh" 2>&1)
+exit_code=$?
+if [[ $exit_code -eq 0 && "$out" == *"no devkit-engine binary"* ]]; then
+  pass "devkit-guard: empty bin/ → loud warning + allow"
+else
+  fail "devkit-guard: empty bin/ (exit=$exit_code out=$out)"
+fi
+
+out=$(printf '{}' \
+  | CLAUDE_PLUGIN_ROOT="$empty_root" bash "$empty_root/hooks/devkit-stop-guard.sh" 2>/dev/null)
+if printf '%s' "$out" | jq -e '.decision=="approve"' >/dev/null 2>&1; then
+  pass "devkit-stop-guard: empty bin/ → approve"
+else
+  fail "devkit-stop-guard: empty bin/ (out=$out)"
+fi
+
+# Versioned binary only (no local-dev symlink). The wrapper should
+# pick up the versioned binary via the glob. Create a stub that prints
+# its argv so we can verify `guard` was passed through.
+versioned_root=$(mktemp -d)
+track_tmp "$versioned_root"
+mkdir -p "$versioned_root/bin" "$versioned_root/hooks"
+cat > "$versioned_root/bin/devkit-engine-v2.1.7-fake" <<'STUB'
+#!/bin/sh
+echo "STUB_INVOKED args=$*" >&2
+exit 0
+STUB
+chmod +x "$versioned_root/bin/devkit-engine-v2.1.7-fake"
+cp "$HOOK_DIR/devkit-guard.sh" "$versioned_root/hooks/"
+chmod +x "$versioned_root/hooks/devkit-guard.sh"
+
+err=$(printf '{"tool_name":"Bash"}' \
+  | CLAUDE_PLUGIN_ROOT="$versioned_root" bash "$versioned_root/hooks/devkit-guard.sh" 2>&1 >/dev/null)
+if [[ "$err" == *"STUB_INVOKED args=guard"* ]]; then
+  pass "devkit-guard: versioned binary → exec with guard arg"
+else
+  fail "devkit-guard: versioned binary not picked up (err=$err)"
+fi
+
+# Multiple versioned binaries — wrapper must pick the highest SEMVER
+# via sort -V, not lexicographic order. The 9→10 digit-count boundary
+# is the exact case where naive string comparison goes wrong
+# ("v2.1.9" sorts above "v2.1.10" lexicographically because `9 > 1`).
+# This pins the sort -V fix from the second-pass review.
+multi_root=$(mktemp -d)
+track_tmp "$multi_root"
+mkdir -p "$multi_root/bin" "$multi_root/hooks"
+cat > "$multi_root/bin/devkit-engine-v2.1.9-fake" <<'STUB'
+#!/bin/sh
+echo "WRONG_OLD_v2.1.9" >&2
+exit 0
+STUB
+cat > "$multi_root/bin/devkit-engine-v2.1.10-fake" <<'STUB'
+#!/bin/sh
+echo "CORRECT_NEW_v2.1.10" >&2
+exit 0
+STUB
+chmod +x "$multi_root/bin/devkit-engine-v2.1.9-fake" "$multi_root/bin/devkit-engine-v2.1.10-fake"
+cp "$HOOK_DIR/devkit-guard.sh" "$multi_root/hooks/"
+chmod +x "$multi_root/hooks/devkit-guard.sh"
+
+err=$(printf '{"tool_name":"Bash"}' \
+  | CLAUDE_PLUGIN_ROOT="$multi_root" bash "$multi_root/hooks/devkit-guard.sh" 2>&1 >/dev/null)
+if [[ "$err" == *"CORRECT_NEW_v2.1.10"* ]]; then
+  pass "devkit-guard: multi-version v2.1.9 vs v2.1.10 → picks v2.1.10 (semver, not lex)"
+else
+  fail "devkit-guard: multi-version picked wrong binary (err=$err)"
+fi
+
 echo ""
 echo "========================================="
 echo "Results: $PASS passed, $FAIL failed"
diff --git a/hooks/lib/read-session.sh b/hooks/lib/read-session.sh
deleted file mode 100644
index b1affa3..0000000
--- a/hooks/lib/read-session.sh
+++ /dev/null
@@ -1,108 +0,0 @@
-#!/usr/bin/env bash
-# read-session.sh: shared session.json parser sourced by devkit-guard.sh
-# and devkit-stop-guard.sh. NOT executed directly.
-#
-# parse_session_fields <session-file>
-#   On success sets: SESSION_STATUS, SESSION_STEP_TYPE, SESSION_ENFORCE,
-#   SESSION_CURRENT_STEP, SESSION_WORKFLOW, SESSION_CURRENT_INDEX,
-#   SESSION_TOTAL_STEPS, SESSION_STALE ("1" if older than TTL, "0"
-#   otherwise). Returns 0.
-#   On parse failure returns 1 (caller decides fail-open vs fail-closed).
-#   On missing file sets SESSION_STATUS="" and returns 0.
-#
-# Stale check reads updated_at (ISO 8601 from Go time.Time); if missing
-# or unparseable the session is treated as fresh. Falls back to
-# started_at for backward compatibility with pre-UpdatedAt state files.
-
-# 30 minutes — mirrors sessionStaleTTL in src/mcp/tools.go.
-: "${DEVKIT_SESSION_STALE_TTL_SECONDS:=1800}"
-
-parse_session_fields() {
-  local session_file="$1"
-
-  SESSION_STATUS=""
-  SESSION_STEP_TYPE=""
-  SESSION_ENFORCE=""
-  SESSION_CURRENT_STEP=""
-  SESSION_WORKFLOW=""
-  SESSION_CURRENT_INDEX=""
-  SESSION_TOTAL_STEPS=""
-  SESSION_STALE="0"
-
-  if [[ ! -f "$session_file" ]]; then
-    return 0
-  fi
-
-  # Single python3 call. Path passed via sys.argv to prevent shell
-  # injection. FileNotFoundError is TOCTOU between the -f test and
-  # open() — treat as "no session" to match the pre-check intent.
-  local parsed
-  parsed=$(python3 -c '
-import json, sys, datetime
-try:
-    d = json.load(open(sys.argv[1]))
-except FileNotFoundError:
-    print("\t".join([""] * 8))
-    sys.exit(0)
-
-ttl = int(sys.argv[2])
-stale = "0"
-ts = d.get("updated_at") or d.get("started_at") or ""
-if ts:
-    # Go marshals time.Time as RFC3339 with nanoseconds, e.g.
-    # "2026-04-10T12:34:56.789Z". fromisoformat handles Z only on
-    # 3.11+, so strip trailing Z for older pythons.
-    if ts.endswith("Z"):
-        ts = ts[:-1] + "+00:00"
-    try:
-        t = datetime.datetime.fromisoformat(ts)
-        # Attach UTC if the timestamp came in naive (no tzinfo).
-        # Without this the subtraction raises TypeError and the whole
-        # python call traps, flipping the guard into fail-closed mode
-        # on any state file written by a non-Go producer.
-        if t.tzinfo is None:
-            t = t.replace(tzinfo=datetime.timezone.utc)
-        age = (datetime.datetime.now(datetime.timezone.utc) - t).total_seconds()
-        # >= so the hook and Go-side `time.Since < ttl` agree at exactly
-        # the TTL boundary — otherwise a 30-min-old session is "fresh"
-        # to the hook but reclaimed by devkit_start.
-        if age >= ttl:
-            stale = "1"
-    except (ValueError, TypeError):
-        pass  # unparseable timestamp — treat as fresh, fail-safe
-
-print("\t".join([
-    d.get("status", ""),
-    d.get("step_type", ""),
-    d.get("enforce", "hard") or "hard",
-    d.get("current_step", ""),
-    d.get("workflow", ""),
-    str(d.get("current_index", "")),
-    str(d.get("total_steps", "")),
-    stale,
-]))
-' "$session_file" "$DEVKIT_SESSION_STALE_TTL_SECONDS" 2>/dev/null) || return 1
-
-  # Guard against a python3 refactor dropping a field: require exactly
-  # 8 tab-separated fields, else fail-closed so a silent truncation
-  # can't let SESSION_STALE default-false through and start enforcing
-  # against orphaned sessions.
-  local field_count
-  field_count=$(awk -F'\t' '{print NF}' <<< "$parsed")
-  if [[ "$field_count" != "8" ]]; then
-    return 1
-  fi
-
-  IFS=$'\t' read -r \
-    SESSION_STATUS \
-    SESSION_STEP_TYPE \
-    SESSION_ENFORCE \
-    SESSION_CURRENT_STEP \
-    SESSION_WORKFLOW \
-    SESSION_CURRENT_INDEX \
-    SESSION_TOTAL_STEPS \
-    SESSION_STALE \
-    <<< "$parsed"
-
-  return 0
-}
diff --git a/src/cmd/guard.go b/src/cmd/guard.go
new file mode 100644
index 0000000..7146182
--- /dev/null
+++ b/src/cmd/guard.go
@@ -0,0 +1,474 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/5uck1ess/devkit/lib"
+	"github.com/spf13/cobra"
+)
+
+// guardDefaultStaleTTL mirrors sessionStaleTTL in src/mcp/tools.go so an
+// idle-but-not-cleared session.json is never enforced against.
+const guardDefaultStaleTTL = 30 * time.Minute
+
+// guardExit is the exit-code contract the hook relies on:
+//
+//	0 — allow (PreToolUse), or emit approve JSON (Stop).
+//	2 — hard block (PreToolUse). Diagnostic on stderr.
+//
+// Stop mode always exits 0; the verdict is carried in the JSON payload.
+// We route every exit through this function so tests can stub it and
+// cobra's own error-to-exit-1 mapping never leaks through.
+var guardExit = os.Exit
+
+// guardStdin / guardStdout / guardStderr are package-level IO hooks so
+// tests can drive the command without touching os.* globals.
+var (
+	guardStdin  io.Reader = os.Stdin
+	guardStdout io.Writer = os.Stdout
+	guardStderr io.Writer = os.Stderr
+)
+
+var (
+	guardToolName string
+	guardStopMode bool
+)
+
+var guardCmd = &cobra.Command{
+	Use:   "guard",
+	Short: "PreToolUse/Stop hook enforcement for devkit workflows",
+	Long: `Guard enforces workflow step ordering for the devkit engine.
+
+In PreToolUse mode (default) it reads a tool name and exits 0 to allow
+or 2 to block. In --stop mode it emits a Stop-hook JSON verdict on
+stdout ({"decision":"approve"} or {"decision":"block","reason":...}).
+
+The allowlist policy mirrors hooks/devkit-guard.sh exactly:
+  command step + hard  → only devkit MCP + TodoWrite
+  prompt step  + hard  → read-only evidence tools + devkit MCP
+  prompt step  + soft  → allow with a stderr nudge
+  parallel / unknown   → allow (engine is dispatching)
+  stale session (TTL)  → allow with a stderr warning (orphan recovery)`,
+	// Override the root's PersistentPreRunE: the guard hook runs on
+	// every PreToolUse call and must not require a git repo, must not
+	// open the SQLite DB, and must not fail if the host project has no
+	// .git at all. Same reason applies to the post-run hook.
+	PersistentPreRunE:  func(cmd *cobra.Command, args []string) error { return nil },
+	PersistentPostRunE: func(cmd *cobra.Command, args []string) error { return nil },
+	Run:                runGuard,
+	Args:               cobra.NoArgs,
+	SilenceUsage:       true,
+	SilenceErrors:      true,
+}
+
+func init() {
+	guardCmd.Flags().StringVar(&guardToolName, "tool-name", "", "tool name (parsed from stdin JSON if empty)")
+	guardCmd.Flags().BoolVar(&guardStopMode, "stop", false, "emit Stop-hook JSON verdict instead of PreToolUse exit code")
+	rootCmd.AddCommand(guardCmd)
+}
+
+func runGuard(cmd *cobra.Command, args []string) {
+	if guardStopMode {
+		runStopGuard()
+		return
+	}
+	runPreToolGuard()
+}
+
+// readToolNameFromStdin extracts tool_name from a PreToolUse payload.
+// Returns "" with a nil error for genuinely empty stdin (the common
+// case when --tool-name is used instead). Any real failure (read error,
+// malformed JSON) returns a non-nil error so the caller can log it
+// distinctly — silent "" on parse failure would mask Claude Code schema
+// drift. Under hard enforcement the empty tool name still falls through
+// to the default-block branch, so errors never cause a silent ALLOW.
+func readToolNameFromStdin() (string, error) {
+	data, err := io.ReadAll(guardStdin)
+	if err != nil {
+		return "", fmt.Errorf("read stdin: %w", err)
+	}
+	if len(data) == 0 {
+		return "", nil
+	}
+	var payload struct {
+		ToolName string `json:"tool_name"`
+	}
+	if err := json.Unmarshal(data, &payload); err != nil {
+		return "", fmt.Errorf("parse PreToolUse JSON: %w", err)
+	}
+	return payload.ToolName, nil
+}
+
+// resolveDataDir returns CLAUDE_PLUGIN_DATA or "" if unset. The shell
+// hook prints a one-line "enforcement disabled" diagnostic to stderr
+// when this is empty; we mirror that so log output is unchanged.
+func resolveDataDir(stopMode bool) string {
+	dir := os.Getenv("CLAUDE_PLUGIN_DATA")
+	if dir == "" {
+		prefix := "devkit-guard"
+		if stopMode {
+			prefix = "devkit-stop-guard"
+		}
+		fmt.Fprintf(guardStderr, "%s: CLAUDE_PLUGIN_DATA unset — enforcement disabled\n", prefix)
+	}
+	return dir
+}
+
+// staleTTL honours the DEVKIT_SESSION_STALE_TTL_SECONDS override the
+// old lib/read-session.sh supported, so operators who tuned the env
+// var during the PR #64 rollout do not see behaviour drift. Garbage
+// values (non-numeric, non-positive, whitespace) log a one-line warning
+// to stderr and fall back to the default — silent downgrade to "never
+// stale" would disable orphan recovery without any user-visible signal.
+func staleTTL() time.Duration {
+	raw := os.Getenv("DEVKIT_SESSION_STALE_TTL_SECONDS")
+	if raw == "" {
+		return guardDefaultStaleTTL
+	}
+	trimmed := strings.TrimSpace(raw)
+	n, err := strconv.Atoi(trimmed)
+	if err != nil {
+		fmt.Fprintf(guardStderr,
+			"devkit-guard: DEVKIT_SESSION_STALE_TTL_SECONDS=%q is not an integer — using default %s\n",
+			raw, guardDefaultStaleTTL)
+		return guardDefaultStaleTTL
+	}
+	if n <= 0 {
+		fmt.Fprintf(guardStderr,
+			"devkit-guard: DEVKIT_SESSION_STALE_TTL_SECONDS=%d must be positive — using default %s\n",
+			n, guardDefaultStaleTTL)
+		return guardDefaultStaleTTL
+	}
+	return time.Duration(n) * time.Second
+}
+
+// sessionIsStale mirrors the lib/read-session.sh TTL rule: prefer
+// UpdatedAt, fall back to StartedAt for pre-UpdatedAt state files
+// written by older engine binaries. An unparseable (zero) timestamp is
+// treated as fresh so a schema gap can't silently disarm enforcement —
+// but a zero-timestamp session is anomalous, so we surface it on stderr
+// so a wedged session at least leaves a debuggable trail.
+func sessionIsStale(s *lib.SessionState) bool {
+	ref := s.UpdatedAt
+	if ref.IsZero() {
+		ref = s.StartedAt
+	}
+	if ref.IsZero() {
+		fmt.Fprintf(guardStderr,
+			"devkit-guard: WARNING session %s has no updated_at/started_at timestamps — stale-check disabled (engine version mismatch?)\n",
+			s.Workflow)
+		return false
+	}
+	return time.Since(ref) > staleTTL()
+}
+
+// stepLabel reproduces the shell step_label() helper so veto messages
+// carry workflow + position + step id without another devkit_status
+// round trip.
+func stepLabel(s *lib.SessionState) string {
+	if s.TotalSteps > 0 {
+		return fmt.Sprintf("%s step %d/%d (%s)", s.Workflow, s.CurrentIndex+1, s.TotalSteps, s.CurrentStep)
+	}
+	return fmt.Sprintf("%s (%s)", s.Workflow, s.CurrentStep)
+}
+
+// sessionFileExists is the cheap read-only probe we use BEFORE touching
+// the session lock. The no-workflow hot path (every PreToolUse call
+// when the user has no active session) must not trigger the mkdir +
+// lock-file create side effects of lib.ReadSessionJSON — on network
+// mounts those writes can blow the 2s hook timeout and, more subtly,
+// they materialise sentinel files in $CLAUDE_PLUGIN_DATA for users who
+// never asked for a workflow. A single os.Stat is ~50µs locally and
+// has zero filesystem side effects.
+func sessionFileExists(dataDir string) bool {
+	if dataDir == "" {
+		return false
+	}
+	_, err := os.Stat(filepath.Join(dataDir, "session.json"))
+	return err == nil
+}
+
+// effectiveEnforce defaults an empty Enforce field to "hard". The shell
+// version relied on python3 .get('enforce','hard'); the fixture matrix
+// explicitly asserts that a command step with no enforce field still
+// blocks. See hooks_test.sh "missing enforce field" case.
+func effectiveEnforce(s *lib.SessionState) string {
+	if s.Enforce == "" {
+		return "hard"
+	}
+	return s.Enforce
+}
+
+// isDevkitMCPTool identifies tools that are part of the devkit MCP
+// server's own surface — and therefore safe to allow during a command
+// or prompt step because they drive the engine, not the agent.
+//
+// Iteration history:
+//  1. Pre-#64: mcp__*devkit* — unanchored substring. Any third-party
+//     tool name containing "devkit" would bypass (e.g.
+//     mcp__plugin_evil__devkit_masquerade).
+//  2. PR #64: mcp__*devkit-engine*|mcp__devkit__* — required the
+//     server name somewhere in the string. Still loose enough that
+//     a plugin with "devkit-engine" elsewhere in its tool name would
+//     pass.
+//  3. This PR: anchored on the full plugin+server prefix. Even a
+//     future second MCP server under the devkit plugin cannot
+//     silently inherit command-step permissions — it would have to
+//     be added to this allowlist deliberately.
+//
+// Accepted forms:
+//   - devkit_advance / devkit_status / devkit_list / devkit_start
+//     (bare names used in local dev and direct stdio callers)
+//   - mcp__plugin_devkit_devkit-engine__<tool>
+//     (Claude Code plugin convention: plugin=devkit, server=devkit-engine)
+//   - mcp__devkit__<tool>
+//     (short-form namespace for non-plugin MCP hosts that register the
+//     server directly)
+//
+// Any other mcp__* tool falls through to default-deny.
+func isDevkitMCPTool(name string) bool {
+	switch name {
+	case "devkit_advance", "devkit_status", "devkit_list", "devkit_start":
+		return true
+	}
+	if strings.HasPrefix(name, "mcp__plugin_devkit_devkit-engine__") {
+		return true
+	}
+	if strings.HasPrefix(name, "mcp__devkit__") {
+		return true
+	}
+	return false
+}
+
+func runPreToolGuard() {
+	dataDir := resolveDataDir(false)
+	if dataDir == "" {
+		guardExit(0)
+		return
+	}
+
+	// Hot path: no active workflow → single stat, zero writes. This
+	// must come BEFORE lib.ReadSessionJSON so we don't trigger the
+	// withSessionLock mkdir + lock-file create side effects for users
+	// who have $CLAUDE_PLUGIN_DATA set but no running session.
+	if !sessionFileExists(dataDir) {
+		guardExit(0)
+		return
+	}
+
+	state, err := lib.ReadSessionJSON(dataDir)
+	if err != nil {
+		// Any error from ReadSessionJSON after sessionFileExists
+		// returned true is a real problem: parse failure, lock
+		// acquire failure, permission denial, quota exceeded, or a
+		// filesystem error. Fail closed unconditionally — silently
+		// allowing on permission errors would let a corrupted plugin
+		// data dir disarm the guard without any user-visible signal.
+		// The "no session" case is signalled by (nil, nil) from
+		// ReadSessionJSON and handled below, so we never reach here
+		// on a legitimately-absent session.
+		sessionPath := filepath.Join(dataDir, "session.json")
+		fmt.Fprintf(guardStderr,
+			"BLOCKED: devkit-guard cannot read session state at %s. "+
+				"Check permissions and JSON validity. Remove the file to clear. (%v)\n",
+			sessionPath, err)
+		guardExit(2)
+		return
+	}
+	if state == nil || state.Status != "running" {
+		// state == nil handles the TOCTOU where the file existed at
+		// stat time but was removed before ReadSessionJSON acquired
+		// the lock — ReadSessionJSON returns (nil, nil) for os.IsNotExist.
+		guardExit(0)
+		return
+	}
+
+	if sessionIsStale(state) {
+		fmt.Fprintf(guardStderr,
+			"devkit-guard: session %s idle past TTL — treating as orphaned (run devkit_start to reclaim)\n",
+			state.Workflow)
+		guardExit(0)
+		return
+	}
+
+	tool := guardToolName
+	if tool == "" {
+		t, terr := readToolNameFromStdin()
+		if terr != nil {
+			// Log distinctly so schema drift in the PreToolUse payload
+			// doesn't silently degrade into "unknown tool name" and
+			// fall through to default-deny (or worse, default-allow
+			// under parallel). The empty tool name we fall through
+			// with still blocks under hard enforcement.
+			fmt.Fprintf(guardStderr,
+				"devkit-guard: cannot determine tool name from stdin: %v — treating as unknown\n",
+				terr)
+		}
+		tool = t
+	}
+	enforce := effectiveEnforce(state)
+
+	// attemptedTool is what we print in veto diagnostics. An empty
+	// tool name means we failed to parse it from stdin (or got an
+	// intentional "" from a flag default); surface that explicitly
+	// so users don't see a dangling "attempted tool: " paren.
+	attemptedTool := tool
+	if attemptedTool == "" {
+		attemptedTool = "<unknown>"
+	}
+
+	switch state.StepType {
+	case "command":
+		if enforce != "hard" {
+			guardExit(0)
+			return
+		}
+		if isDevkitMCPTool(tool) || tool == "TodoWrite" {
+			guardExit(0)
+			return
+		}
+		fmt.Fprintf(guardStderr,
+			"BLOCKED: Command step %q in progress — the engine runs this step. Call devkit_advance to execute it. (attempted tool: %s)\n",
+			stepLabel(state), attemptedTool)
+		guardExit(2)
+		return
+
+	case "prompt":
+		if enforce == "hard" {
+			if isDevkitMCPTool(tool) {
+				guardExit(0)
+				return
+			}
+			switch tool {
+			case "Read", "Grep", "Glob", "TodoWrite", "NotebookRead":
+				guardExit(0)
+				return
+			}
+			fmt.Fprintf(guardStderr,
+				"BLOCKED: devkit workflow %s is at a prompt step — gather evidence with Read/Grep/Glob then call devkit_advance. (attempted tool: %s)\n",
+				stepLabel(state), attemptedTool)
+			guardExit(2)
+			return
+		}
+		// Soft enforcement: allow + nudge. Idempotent — the Stop-hook
+		// still blocks if the agent rides the nudge indefinitely.
+		fmt.Fprintf(guardStderr,
+			"devkit-guard: %s is open — call devkit_advance when the step is complete.\n",
+			stepLabel(state))
+		guardExit(0)
+		return
+
+	default:
+		// parallel or unknown — engine is dispatching, allow through.
+		guardExit(0)
+	}
+}
+
+// stopVerdict is the JSON shape consumed by Claude Code's Stop hook.
+type stopVerdict struct {
+	Decision string `json:"decision"`
+	Reason   string `json:"reason,omitempty"`
+}
+
+// writeStopVerdict emits the JSON verdict on stdout with no trailing
+// newline, matching the shell hook's exact byte output. json.Marshal
+// on a plain string-only struct cannot fail, so we do not carry a
+// fallback branch — if this ever panics the test suite will catch it.
+func writeStopVerdict(v stopVerdict) {
+	data, err := json.Marshal(v)
+	if err != nil {
+		// Truly unreachable for stopVerdict's shape (only strings).
+		// If the struct ever grows a field that can fail to marshal,
+		// we want the panic in test/CI rather than silently emitting
+		// a hardcoded block verdict that hides the bug.
+		panic(fmt.Errorf("devkit-stop-guard: unreachable json.Marshal failure on stopVerdict: %w", err))
+	}
+	if _, err := fmt.Fprint(guardStdout, string(data)); err != nil {
+		// Stdout is the Stop hook's only channel. Log to stderr so a
+		// broken pipe leaves some post-mortem trail, but still return
+		// cleanly so Claude Code doesn't time out waiting for us.
+		fmt.Fprintf(guardStderr,
+			"devkit-stop-guard: failed to write verdict to stdout: %v\n", err)
+	}
+}
+
+func runStopGuard() {
+	dataDir := resolveDataDir(true)
+	if dataDir == "" {
+		writeStopVerdict(stopVerdict{Decision: "approve"})
+		guardExit(0)
+		return
+	}
+
+	// Hot path: no session file → approve. Same reason as the Pre
+	// variant — avoid the mkdir/lock side effects on the cold path.
+	if !sessionFileExists(dataDir) {
+		writeStopVerdict(stopVerdict{Decision: "approve"})
+		guardExit(0)
+		return
+	}
+
+	state, err := lib.ReadSessionJSON(dataDir)
+	if err != nil {
+		// Any error after a positive sessionFileExists is a real
+		// problem — fail closed with an actionable reason. The Stop
+		// hook's fail-closed verdict is a BLOCK so the user sees the
+		// diagnostic in their transcript and can recover manually
+		// rather than shipping a half-finished workflow.
+		sessionPath := filepath.Join(dataDir, "session.json")
+		fmt.Fprintf(guardStderr,
+			"devkit-stop-guard: cannot read session state at %s: %v — blocking Stop\n",
+			sessionPath, err)
+		writeStopVerdict(stopVerdict{
+			Decision: "block",
+			Reason: fmt.Sprintf(
+				"devkit session state unreadable — remove %s to clear", sessionPath),
+		})
+		guardExit(0)
+		return
+	}
+	if state == nil || state.Status != "running" {
+		// state == nil handles the TOCTOU where the file was removed
+		// between sessionFileExists and ReadSessionJSON.
+		// Stop is enforce-agnostic — any running workflow blocks Stop
+		// regardless of soft/hard — so we don't consult effectiveEnforce.
+		writeStopVerdict(stopVerdict{Decision: "approve"})
+		guardExit(0)
+		return
+	}
+
+	if sessionIsStale(state) {
+		fmt.Fprintf(guardStderr,
+			"devkit-stop-guard: session %s idle past TTL — approving Stop (reclaim on next devkit_start)\n",
+			state.Workflow)
+		writeStopVerdict(stopVerdict{Decision: "approve"})
+		guardExit(0)
+		return
+	}
+
+	remaining := 0
+	if state.TotalSteps > 0 {
+		remaining = state.TotalSteps - state.CurrentIndex
+		if remaining < 0 {
+			remaining = 0
+		}
+	}
+	wf := state.Workflow
+	if wf == "" {
+		wf = "unknown"
+	}
+	writeStopVerdict(stopVerdict{
+		Decision: "block",
+		Reason: fmt.Sprintf(
+			"Workflow %s incomplete — %d steps remaining. Call devkit_advance to continue.",
+			wf, remaining),
+	})
+	guardExit(0)
+}
diff --git a/src/cmd/guard_test.go b/src/cmd/guard_test.go
new file mode 100644
index 0000000..34ad062
--- /dev/null
+++ b/src/cmd/guard_test.go
@@ -0,0 +1,889 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/5uck1ess/devkit/lib"
+)
+
+// IMPORTANT: tests in this file MUST NOT call t.Parallel().
+//
+// newGuardTestEnv mutates six package-level globals (guardExit,
+// guardStdin, guardStdout, guardStderr, guardToolName, guardStopMode)
+// plus the CLAUDE_PLUGIN_DATA env var. Parallel subtests would race on
+// all of these — data race, t.Setenv rejection, and cross-test buffer
+// bleed-through. If you need parallel execution, refactor guard.go to
+// pass a *guardContext struct through runPreToolGuard/runStopGuard
+// instead of using package-level IO hooks.
+
+// guardTestEnv wires the package-level IO + exit hooks to per-test
+// buffers and a captured exit code, then runs the command. It returns
+// the captured exit code, stdout, and stderr so table-driven tests can
+// assert on all three.
+type guardTestEnv struct {
+	exit   int
+	stdout bytes.Buffer
+	stderr bytes.Buffer
+}
+
+func newGuardTestEnv(t *testing.T, stdinPayload, toolName string, stopMode bool, dataDir string) *guardTestEnv {
+	t.Helper()
+
+	env := &guardTestEnv{exit: -1}
+
+	// Capture exit. Real os.Exit would terminate the test binary.
+	prevExit := guardExit
+	guardExit = func(code int) {
+		env.exit = code
+	}
+	t.Cleanup(func() { guardExit = prevExit })
+
+	prevStdin := guardStdin
+	prevStdout := guardStdout
+	prevStderr := guardStderr
+	guardStdin = strings.NewReader(stdinPayload)
+	guardStdout = &env.stdout
+	guardStderr = &env.stderr
+	t.Cleanup(func() {
+		guardStdin = prevStdin
+		guardStdout = prevStdout
+		guardStderr = prevStderr
+	})
+
+	// Reset flag state so previous tests don't leak into this one.
+	prevToolName := guardToolName
+	prevStopMode := guardStopMode
+	guardToolName = toolName
+	guardStopMode = stopMode
+	t.Cleanup(func() {
+		guardToolName = prevToolName
+		guardStopMode = prevStopMode
+	})
+
+	// Isolate CLAUDE_PLUGIN_DATA so parallel tests don't collide.
+	prevEnv, hadPrev := os.LookupEnv("CLAUDE_PLUGIN_DATA")
+	if dataDir == "" {
+		os.Unsetenv("CLAUDE_PLUGIN_DATA")
+	} else {
+		t.Setenv("CLAUDE_PLUGIN_DATA", dataDir)
+	}
+	t.Cleanup(func() {
+		if hadPrev {
+			os.Setenv("CLAUDE_PLUGIN_DATA", prevEnv)
+		} else {
+			os.Unsetenv("CLAUDE_PLUGIN_DATA")
+		}
+	})
+
+	return env
+}
+
+// writeSession writes a session.json into tmpDir using the Go struct so
+// the on-disk layout tracks lib.SessionState exactly. Tests that want
+// malformed or partial JSON use writeSessionRaw instead.
+func writeSession(t *testing.T, dir string, s lib.SessionState) {
+	t.Helper()
+	// Default UpdatedAt to now so tests aren't all accidentally stale.
+	if s.UpdatedAt.IsZero() {
+		s.UpdatedAt = time.Now()
+	}
+	data, err := json.Marshal(&s)
+	if err != nil {
+		t.Fatalf("marshal session: %v", err)
+	}
+	writeSessionRaw(t, dir, data)
+}
+
+func writeSessionRaw(t *testing.T, dir string, data []byte) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(dir, "session.json"), data, 0o600); err != nil {
+		t.Fatalf("write session.json: %v", err)
+	}
+}
+
+func TestGuardPreToolUse(t *testing.T) {
+	// Each row maps 1:1 to a case in hooks/hooks_test.sh so the fixture
+	// matrix stays portable across the shell and Go harnesses.
+	//
+	// wantStderrSubstr is optional and pins the veto-message wording
+	// on block rows. This is a deliberate substring match so future
+	// message edits have to update the tests — the wording is the
+	// only feedback the agent sees when a tool call is rejected, and
+	// wording regressions have been historically easy to ship.
+	tests := []struct {
+		name             string
+		dataDir          bool // set CLAUDE_PLUGIN_DATA
+		hasSession       bool
+		session          lib.SessionState
+		stdin            string
+		toolFlag         string
+		wantExit         int
+		wantStderrSubstr string
+	}{
+		{
+			name:     "no CLAUDE_PLUGIN_DATA → allow",
+			dataDir:  false,
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			name:     "no session file → allow",
+			dataDir:  true,
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "status=done → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status:      "done",
+				StepType:    "command",
+				Enforce:     "hard",
+				CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "command+hard+Bash → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status:      "running",
+				StepType:    "command",
+				Enforce:     "hard",
+				CurrentStep: "build",
+				Workflow:    "feature",
+				TotalSteps:  3,
+			},
+			stdin:            `{"tool_name":"Bash"}`,
+			wantExit:         2,
+			wantStderrSubstr: "BLOCKED: Command step",
+		},
+		{
+			name:       "command+hard+Write → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            `{"tool_name":"Write"}`,
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: Write",
+		},
+		{
+			name:       "command+hard+devkit_advance → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"devkit_advance"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "command+hard+mcp__devkit__advance → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"mcp__devkit__advance"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "command+hard+TodoWrite → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"TodoWrite"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "command+soft → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "soft", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+hard+Read → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Read"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+hard+Grep → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Grep"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+hard+Bash → block (issue #63 drift hole)",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+				Workflow: "tri-review", TotalSteps: 6,
+			},
+			stdin:            `{"tool_name":"Bash"}`,
+			wantExit:         2,
+			wantStderrSubstr: "gather evidence with Read/Grep/Glob",
+		},
+		{
+			name:       "prompt+hard+Write → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+				Workflow: "tri-review", TotalSteps: 6,
+			},
+			stdin:            `{"tool_name":"Write"}`,
+			wantExit:         2,
+			wantStderrSubstr: "tri-review step",
+		},
+		{
+			name:       "prompt+hard+Task → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:            `{"tool_name":"Task"}`,
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: Task",
+		},
+		{
+			name:       "prompt+hard+devkit_advance → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"devkit_advance"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+soft+Bash → allow with nudge",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "soft", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "parallel+hard+Task → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "parallel", Enforce: "hard", CurrentStep: "fanout",
+			},
+			stdin:    `{"tool_name":"Task"}`,
+			wantExit: 0,
+		},
+		{
+			// The shell hook relied on python .get('enforce','hard')
+			// to catch this silent-degrade case. Mirrored via
+			// effectiveEnforce().
+			name:       "command step missing enforce → block (default hard)",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 2,
+		},
+		{
+			// Empty step_type is non-command and non-prompt, so the
+			// default branch (parallel/unknown) allows through. This
+			// protects the agent from being wedged by a schema gap.
+			name:       "missing step_type → allow (non-command fallthrough)",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			// --tool-name flag short-circuits the stdin read entirely.
+			name:       "command+hard+tool-name flag Bash → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    "",
+			toolFlag: "Bash",
+			wantExit: 2,
+		},
+		{
+			// Long MCP tool name produced by Claude Code's plugin
+			// namespacing — mcp__plugin_<plugin>_<server>__<tool>.
+			// Must still match the mcp__*devkit* allowlist glob.
+			name:       "command+hard+long MCP devkit tool name → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"mcp__plugin_devkit_devkit-engine__devkit_advance"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+hard+Glob → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Glob"}`,
+			wantExit: 0,
+		},
+		{
+			name:       "prompt+hard+Edit → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"Edit"}`,
+			wantExit: 2,
+		},
+		{
+			name:       "prompt+hard+WebFetch → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"WebFetch"}`,
+			wantExit: 2,
+		},
+		{
+			name:       "parallel+hard+Write → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "parallel", Enforce: "hard", CurrentStep: "fanout",
+			},
+			stdin:    `{"tool_name":"Write"}`,
+			wantExit: 0,
+		},
+		{
+			// parallel+soft should allow exactly the same as parallel+hard.
+			// Explicit row so a future refactor that adds an enforce
+			// check to the parallel branch cannot sneak through.
+			name:       "parallel+soft+Bash → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "parallel", Enforce: "soft", CurrentStep: "fanout",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			// Fixture parity gap: the deleted hooks/devkit-guard_test.sh
+			// asserted prompt+hard+TodoWrite allow but the Go port only
+			// tested TodoWrite under command+hard. Pin it explicitly.
+			name:       "prompt+hard+TodoWrite → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "analyse",
+			},
+			stdin:    `{"tool_name":"TodoWrite"}`,
+			wantExit: 0,
+		},
+		{
+			// Fixture parity gap: soft enforcement is supposed to let
+			// write-tier tools through, not just Bash. Pin the contract.
+			name:       "prompt+soft+Write → allow with nudge",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "soft", CurrentStep: "analyse",
+				Workflow: "feature", TotalSteps: 4,
+			},
+			stdin:            `{"tool_name":"Write"}`,
+			wantExit:         0,
+			wantStderrSubstr: "call devkit_advance",
+		},
+		{
+			// TotalSteps=0 exercises the no-index branch of stepLabel().
+			// Engine always writes TotalSteps > 0 in practice, but this
+			// pins the defensive fallback so removing it fails a test.
+			name:       "prompt+hard+Bash with TotalSteps=0 → block (no-index label)",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "prompt", Enforce: "hard", CurrentStep: "unknown",
+				Workflow: "mystery", TotalSteps: 0,
+			},
+			stdin:            `{"tool_name":"Bash"}`,
+			wantExit:         2,
+			wantStderrSubstr: "mystery (unknown)",
+		},
+		{
+			// N2 negative: a third-party MCP server whose tool name
+			// happens to contain "devkit" as a substring must NOT be
+			// treated as a devkit MCP tool. The old shell glob
+			// mcp__*devkit* would have allowed this, creating an
+			// allowlist bypass. Pin the tightened Go behavior.
+			name:       "command+hard+evil MCP tool containing 'devkit' → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            `{"tool_name":"mcp__plugin_evil_server__devkit_masquerade"}`,
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: mcp__plugin_evil_server__devkit_masquerade",
+		},
+		{
+			// mcp__devkit__<tool> short-form namespace (used in local
+			// dev and non-plugin MCP hosts) must still be allowed.
+			name:       "command+hard+mcp__devkit__advance short-form → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"mcp__devkit__advance"}`,
+			wantExit: 0,
+		},
+		{
+			// Anchoring on plugin+server (not just plugin): a
+			// hypothetical future second MCP server under the devkit
+			// plugin must NOT inherit command-step permissions
+			// automatically. Adding such a server would require a
+			// deliberate change to isDevkitMCPTool.
+			name:       "command+hard+mcp__plugin_devkit_other_server__tool → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            `{"tool_name":"mcp__plugin_devkit_other_server__probe"}`,
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: mcp__plugin_devkit_other_server__probe",
+		},
+		{
+			// Status comparison is case-sensitive. A future engine
+			// that writes "RUNNING" would silently disable enforcement.
+			// Pin the current contract so any change is deliberate.
+			name:       "Status=RUNNING (uppercase) treated as not-running → allow",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "RUNNING", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:    `{"tool_name":"Bash"}`,
+			wantExit: 0,
+		},
+		{
+			// --tool-name flag must win over stdin. Flag is used by
+			// wrappers that pre-parse the payload; stdin is the
+			// fallback. Pin the precedence so it can't silently flip.
+			name:       "command+hard+flag Bash beats stdin devkit_advance → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            `{"tool_name":"devkit_advance"}`,
+			toolFlag:         "Bash",
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: Bash",
+		},
+		{
+			// Empty stdin with no flag and a hard command step must
+			// block — empty tool name is not in any allowlist. Pin
+			// the fail-closed contract against schema drift.
+			name:       "command+hard+empty stdin → block (unknown tool)",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            ``,
+			wantExit:         2,
+			wantStderrSubstr: "attempted tool: <unknown>",
+		},
+		{
+			// Malformed stdin JSON: readToolNameFromStdin returns an
+			// error, the call site logs it, falls through with "",
+			// and the hard command step blocks. Pin this so a future
+			// refactor can't silently allow on parse failure.
+			name:       "command+hard+malformed stdin → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+			},
+			stdin:            `{not json`,
+			wantExit:         2,
+			wantStderrSubstr: "cannot determine tool name",
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			var dir string
+			if tc.dataDir {
+				dir = t.TempDir()
+				if tc.hasSession {
+					writeSession(t, dir, tc.session)
+				}
+			}
+			env := newGuardTestEnv(t, tc.stdin, tc.toolFlag, false, dir)
+			runGuard(guardCmd, nil)
+			if env.exit != tc.wantExit {
+				t.Fatalf("exit=%d want=%d\nstderr=%s", env.exit, tc.wantExit, env.stderr.String())
+			}
+			if tc.wantStderrSubstr != "" && !strings.Contains(env.stderr.String(), tc.wantStderrSubstr) {
+				t.Fatalf("stderr missing substring %q\ngot: %s", tc.wantStderrSubstr, env.stderr.String())
+			}
+		})
+	}
+}
+
+// TestGuardStaleTTLGarbageValues pins the fail-safe behaviour of
+// staleTTL() when the DEVKIT_SESSION_STALE_TTL_SECONDS env var is
+// set to garbage values. A silent fallback to default would be
+// acceptable correctness-wise, but a silent fallback WITHOUT a stderr
+// warning would hide operator misconfiguration, so we assert both the
+// returned value AND the warning text.
+func TestGuardStaleTTLGarbageValues(t *testing.T) {
+	tests := []struct {
+		name           string
+		envValue       string
+		wantWarn       bool
+		wantWarnSubstr string
+	}{
+		{"non-numeric", "abc", true, "is not an integer"},
+		{"negative", "-5", true, "must be positive"},
+		{"zero", "0", true, "must be positive"},
+		{"trailing space (handled)", "1800 ", false, ""}, // TrimSpace normalises this
+		{"empty (falls through)", "", false, ""},         // early return, no warn
+		{"overflow", "99999999999999999999", true, "is not an integer"},
+	}
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			var stderr bytes.Buffer
+			prevStderr := guardStderr
+			guardStderr = &stderr
+			t.Cleanup(func() { guardStderr = prevStderr })
+			t.Setenv("DEVKIT_SESSION_STALE_TTL_SECONDS", tc.envValue)
+
+			got := staleTTL()
+			// For "trailing space" the value parses to 1800s.
+			// For everything else we expect the default.
+			if tc.envValue == "1800 " {
+				if got != 1800*time.Second {
+					t.Fatalf("trimmed value should parse to 1800s, got %s", got)
+				}
+			} else if got != guardDefaultStaleTTL {
+				t.Fatalf("garbage value should fall back to default %s, got %s",
+					guardDefaultStaleTTL, got)
+			}
+
+			warned := stderr.Len() > 0
+			if warned != tc.wantWarn {
+				t.Fatalf("warn=%v want=%v (stderr=%q)", warned, tc.wantWarn, stderr.String())
+			}
+			if tc.wantWarnSubstr != "" && !strings.Contains(stderr.String(), tc.wantWarnSubstr) {
+				t.Fatalf("stderr missing %q: %q", tc.wantWarnSubstr, stderr.String())
+			}
+		})
+	}
+}
+
+// TestGuardStaleTTLHonourLongerOverride checks the "relax the clock"
+// direction of the env override: a 2-hour TTL should treat a 45-minute-
+// old session as fresh, where the default 30-minute TTL would mark it
+// stale. Pins the semantic so a future refactor that hardcodes the
+// default cannot silently kill the override.
+func TestGuardStaleTTLHonourLongerOverride(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DEVKIT_SESSION_STALE_TTL_SECONDS", "7200") // 2h
+	writeSession(t, dir, lib.SessionState{
+		Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+		Workflow: "feature", TotalSteps: 2,
+		UpdatedAt: time.Now().Add(-45 * time.Minute),
+	})
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 2 {
+		t.Fatalf("45-min-old session under 2h TTL should still be fresh and blocking: exit=%d stderr=%s",
+			env.exit, env.stderr.String())
+	}
+}
+
+// TestGuardStaleZeroTimestampWarn verifies the defensive warning for
+// sessions with neither UpdatedAt nor StartedAt — a schema-drift
+// scenario where an older engine wrote a session file without
+// timestamps. The guard treats these as fresh (fail-safe towards
+// enforcement), but must log a warning so the anomaly isn't silent.
+func TestGuardStaleZeroTimestampWarn(t *testing.T) {
+	dir := t.TempDir()
+	// Zero time literal requires bypassing writeSession's default.
+	data := []byte(`{"status":"running","step_type":"command","enforce":"hard","current_step":"build","workflow":"legacy","total_steps":1}`)
+	writeSessionRaw(t, dir, data)
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 2 {
+		t.Fatalf("zero-timestamp session must still enforce: exit=%d", env.exit)
+	}
+	if !strings.Contains(env.stderr.String(), "no updated_at/started_at timestamps") {
+		t.Fatalf("expected zero-timestamp WARNING, got: %s", env.stderr.String())
+	}
+}
+
+// TestGuardUnreadableSession exercises the fail-closed path when the
+// session file exists but cannot be read due to permissions. This is
+// the concrete "broken install silently disarms enforcement" scenario
+// from the review — the fail-closed contract must fire here, not the
+// fail-open fallback the old code had. Unix-only because chmod 0 is
+// meaningless on Windows.
+func TestGuardUnreadableSession(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("chmod 0 is a no-op on Windows")
+	}
+	if os.Geteuid() == 0 {
+		t.Skip("root bypasses file-mode permissions")
+	}
+	dir := t.TempDir()
+	path := filepath.Join(dir, "session.json")
+	if err := os.WriteFile(path, []byte(`{"status":"running","step_type":"command","enforce":"hard"}`), 0o000); err != nil {
+		t.Fatalf("write unreadable session: %v", err)
+	}
+	t.Cleanup(func() { os.Chmod(path, 0o600) }) // let t.TempDir cleanup succeed
+
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 2 {
+		t.Fatalf("unreadable session must fail closed: exit=%d stderr=%s",
+			env.exit, env.stderr.String())
+	}
+	if !strings.Contains(env.stderr.String(), "BLOCKED") {
+		t.Fatalf("expected BLOCKED diagnostic, got: %s", env.stderr.String())
+	}
+}
+
+// TestGuardStaleSessionPromptSoft covers the gap identified in code
+// review: the stale-session warning must fire under prompt+soft just
+// like under command+hard, because the staleness check precedes the
+// step-type switch.
+func TestGuardStaleSessionPromptSoft(t *testing.T) {
+	dir := t.TempDir()
+	old := time.Now().Add(-2 * time.Hour)
+	writeSession(t, dir, lib.SessionState{
+		Status: "running", StepType: "prompt", Enforce: "soft", CurrentStep: "analyse",
+		Workflow: "tri-review", TotalSteps: 6,
+		UpdatedAt: old, StartedAt: old,
+	})
+	env := newGuardTestEnv(t, `{"tool_name":"Write"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 0 {
+		t.Fatalf("stale prompt+soft must allow: exit=%d", env.exit)
+	}
+	if !strings.Contains(env.stderr.String(), "idle past TTL") {
+		t.Fatalf("expected stale warning, got: %s", env.stderr.String())
+	}
+}
+
+func TestGuardPreToolUseCorruptSession(t *testing.T) {
+	dir := t.TempDir()
+	writeSessionRaw(t, dir, []byte("{not valid json"))
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 2 {
+		t.Fatalf("corrupt session should fail closed: exit=%d stderr=%s", env.exit, env.stderr.String())
+	}
+	if !strings.Contains(env.stderr.String(), "BLOCKED") {
+		t.Fatalf("expected BLOCKED diagnostic, got: %s", env.stderr.String())
+	}
+}
+
+func TestGuardPreToolUseStaleSession(t *testing.T) {
+	dir := t.TempDir()
+	// Stale session: UpdatedAt older than TTL. This is the orphan
+	// recovery path — without it a crashed engine process would wedge
+	// every subsequent tool call until the user manually cleaned up.
+	old := time.Now().Add(-2 * time.Hour)
+	writeSession(t, dir, lib.SessionState{
+		Status:      "running",
+		StepType:    "command",
+		Enforce:     "hard",
+		CurrentStep: "build",
+		Workflow:    "feature",
+		UpdatedAt:   old,
+		StartedAt:   old,
+	})
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 0 {
+		t.Fatalf("stale session should allow: exit=%d", env.exit)
+	}
+	if !strings.Contains(env.stderr.String(), "idle past TTL") {
+		t.Fatalf("expected TTL warning, got: %s", env.stderr.String())
+	}
+}
+
+func TestGuardPreToolUseEnvTTLOverride(t *testing.T) {
+	dir := t.TempDir()
+	// Set a 1-second TTL via env so a 2-second-old session is stale.
+	// Mirrors the DEVKIT_SESSION_STALE_TTL_SECONDS hook-era knob.
+	t.Setenv("DEVKIT_SESSION_STALE_TTL_SECONDS", "1")
+	writeSession(t, dir, lib.SessionState{
+		Status: "running", StepType: "command", Enforce: "hard", CurrentStep: "build",
+		UpdatedAt: time.Now().Add(-2 * time.Second),
+	})
+	env := newGuardTestEnv(t, `{"tool_name":"Bash"}`, "", false, dir)
+	runGuard(guardCmd, nil)
+	if env.exit != 0 {
+		t.Fatalf("stale via env override should allow: exit=%d", env.exit)
+	}
+}
+
+func TestGuardStopHook(t *testing.T) {
+	tests := []struct {
+		name         string
+		dataDir      bool
+		hasSession   bool
+		session      lib.SessionState
+		rawSession   []byte // overrides session if non-nil
+		wantDecision string
+		wantReason   string // substring match, "" skips
+	}{
+		{
+			name:         "no CLAUDE_PLUGIN_DATA → approve",
+			dataDir:      false,
+			wantDecision: "approve",
+		},
+		{
+			name:         "no session file → approve",
+			dataDir:      true,
+			wantDecision: "approve",
+		},
+		{
+			name:       "running workflow → block",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "running", Workflow: "test", TotalSteps: 5, CurrentIndex: 2,
+			},
+			wantDecision: "block",
+			wantReason:   "3 steps remaining",
+		},
+		{
+			name:       "done workflow → approve",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "done", Workflow: "test", TotalSteps: 5, CurrentIndex: 4,
+			},
+			wantDecision: "approve",
+		},
+		{
+			name:       "failed workflow → approve",
+			dataDir:    true,
+			hasSession: true,
+			session: lib.SessionState{
+				Status: "failed", Workflow: "test", TotalSteps: 5, CurrentIndex: 2,
+			},
+			wantDecision: "approve",
+		},
+		{
+			name:         "corrupt JSON → block (fail closed)",
+			dataDir:      true,
+			rawSession:   []byte("not json"),
+			wantDecision: "block",
+			wantReason:   "unreadable",
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			var dir string
+			if tc.dataDir {
+				dir = t.TempDir()
+				switch {
+				case tc.rawSession != nil:
+					writeSessionRaw(t, dir, tc.rawSession)
+				case tc.hasSession:
+					writeSession(t, dir, tc.session)
+				}
+			}
+			env := newGuardTestEnv(t, "", "", true, dir)
+			runGuard(guardCmd, nil)
+
+			if env.exit != 0 {
+				t.Fatalf("stop hook must always exit 0, got %d", env.exit)
+			}
+
+			var v stopVerdict
+			if err := json.Unmarshal(env.stdout.Bytes(), &v); err != nil {
+				t.Fatalf("stop verdict not valid JSON: %q (%v)", env.stdout.String(), err)
+			}
+			if v.Decision != tc.wantDecision {
+				t.Fatalf("decision=%q want=%q", v.Decision, tc.wantDecision)
+			}
+			if tc.wantReason != "" && !strings.Contains(v.Reason, tc.wantReason) {
+				t.Fatalf("reason=%q should contain %q", v.Reason, tc.wantReason)
+			}
+		})
+	}
+}
+
+func TestGuardStopHookStaleSession(t *testing.T) {
+	// Stale-during-Stop → approve so a crashed engine doesn't trap the
+	// user in an un-stoppable session.
+	dir := t.TempDir()
+	old := time.Now().Add(-2 * time.Hour)
+	writeSession(t, dir, lib.SessionState{
+		Status:    "running",
+		Workflow:  "test",
+		UpdatedAt: old,
+		StartedAt: old,
+	})
+	env := newGuardTestEnv(t, "", "", true, dir)
+	runGuard(guardCmd, nil)
+	var v stopVerdict
+	if err := json.Unmarshal(env.stdout.Bytes(), &v); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	if v.Decision != "approve" {
+		t.Fatalf("stale stop should approve: %+v", v)
+	}
+}