From 69ace118b308ae034db720751a5cb4d51e5ad175 Mon Sep 17 00:00:00 2001
From: Tym Rabchuk <tymrabchuk@gmail.com>
Date: Fri, 10 Apr 2026 20:01:18 -0400
Subject: [PATCH 1/3] fix(hooks): extend devkit-guard to prompt steps + orphan
 recovery (#63)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes the drift hole where a workflow prompt step returns its prompt
and the agent can run arbitrary unrelated tools without ever calling
devkit_advance. The engine correctly holds step ordering inside a
workflow; this closes the outer "force the agent to actually use it"
loop at the hook layer.

- devkit-guard.sh: under enforce=hard, prompt steps now allow only
  Read/Grep/Glob/TodoWrite/NotebookRead + devkit MCP tools. Write,
  Edit, Bash, Task, WebFetch, and other MCP tools are blocked with a
  veto naming workflow + step N/M. Soft enforce emits a stderr nudge
  instead of blocking.
- hooks/lib/read-session.sh: shared python3 parser sourced by both
  devkit-guard and devkit-stop-guard (eliminates drift risk from
  duplicate parsing).
- SessionState.UpdatedAt: bumped on every WriteSessionJSON; hooks
  treat sessions idle past 30min TTL as orphaned and stop enforcing.
- devkit_start: reclaims stale sessions instead of rejecting, so a
  crashed engine no longer wedges the slot forever.
- hooks.json: devkit-guard timeout 2s → 5s to hedge python3 cold-start
  on Windows (proper fix is a native Go guard — follow-up issue).
- Tests: Go coverage for UpdatedAt bump + stale/fresh reclaim cutoff;
  new hooks/devkit-guard_test.sh fixture matrix (21 cases) covering
  command/prompt × hard/soft × fresh/stale.
---
 README.md                  |   2 +-
 hooks/devkit-guard.sh      | 117 ++++++++++++++++----------
 hooks/devkit-guard_test.sh | 167 +++++++++++++++++++++++++++++++++++++
 hooks/devkit-stop-guard.sh |  67 ++++++++-------
 hooks/hooks.json           |   2 +-
 hooks/lib/read-session.sh  |  89 ++++++++++++++++++++
 src/lib/state_json.go      |  35 ++++----
 src/lib/state_test.go      |  46 ++++++++++
 src/mcp/tools.go           |  24 +++++-
 src/mcp/tools_test.go      | 164 ++++++++++++++++++++++++++++++++++++
 10 files changed, 626 insertions(+), 87 deletions(-)
 create mode 100755 hooks/devkit-guard_test.sh
 create mode 100644 hooks/lib/read-session.sh

diff --git a/README.md b/README.md
index 1c47758..174a42d 100644
--- a/README.md
+++ b/README.md
@@ -197,7 +197,7 @@ Coding principles (`clean-code`, `dry`, `yagni`, `dont-reinvent`, `executing`, `
 | PreToolUse | **audit-trail** | Logs every command to `.devkit/audit.log` |
 | PreToolUse | **pr-gate** | Prompts to run the pr-ready skill before `gh pr create` |
 | PreToolUse | **rtk-rewrite** | Compresses Bash output via RTK (no-op if not installed) |
-| PreToolUse | **devkit-guard** | Blocks out-of-step tools during workflow command steps |
+| PreToolUse | **devkit-guard** | Blocks out-of-step tools during workflow command AND prompt steps (hard enforce); soft enforce emits a reminder. Skills are intentionally unguarded. |
 | PostToolUse | **post-validate** | Suppressed errors, leaked secrets, writes outside repo |
 | PostToolUse | **slop-detect** | AI code patterns — doc/code imbalance, restating comments |
 | PostToolUse | **lang-review** | Language-aware checks: Go, TypeScript, Rust, Python, Shell |
diff --git a/hooks/devkit-guard.sh b/hooks/devkit-guard.sh
index 5419f6e..ea7c281 100755
--- a/hooks/devkit-guard.sh
+++ b/hooks/devkit-guard.sh
@@ -5,81 +5,114 @@ set -euo pipefail
 # Reads $CLAUDE_PLUGIN_DATA/session.json. Blocks out-of-step actions.
 # Exit 0 = allow, Exit 2 + stderr = hard block.
 #
-# Policy: during a command step (workflow.yml `command:`), the engine —
-# not Claude — executes the shell. The only tool Claude is allowed to
-# call is devkit_advance (which triggers execution and returns the next
-# step). Everything else is blocked so Claude cannot observe or
-# interfere with the state of the step.
+# Policy matrix:
+#   step_type=command, enforce=hard → allow only devkit MCP + TodoWrite
+#                                     (engine runs the command, not Claude)
+#   step_type=prompt,  enforce=hard → allow evidence-gathering + devkit MCP
+#                                     (Read/Grep/Glob/TodoWrite) — force
+#                                     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.
 #
 # 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"
+
 DATA_DIR="${CLAUDE_PLUGIN_DATA:-}"
 if [[ -z "$DATA_DIR" ]]; then
   printf 'devkit-guard: CLAUDE_PLUGIN_DATA unset — enforcement disabled\n' >&2
-  exit 0  # not in plugin context
+  exit 0
 fi
 
 SESSION_FILE="${DATA_DIR}/session.json"
-if [[ ! -f "$SESSION_FILE" ]]; then
-  exit 0  # no active workflow
-fi
 
-# Parse all session fields in a single python3 call (no jq dependency).
-# Outputs tab-separated: status, step_type, enforce, current_step.
-# Passes file path via sys.argv to prevent shell injection. Handles
-# FileNotFoundError so a TOCTOU race (file cleared between -f and open)
-# is treated as "no session," matching the pre-check intent.
-SESSION_DATA=$(python3 -c "
-import json, sys
-try:
-    d = json.load(open(sys.argv[1]))
-except FileNotFoundError:
-    print('\t'.join(['', '', '', '']))
-    sys.exit(0)
-print('\t'.join([
-    d.get('status', ''),
-    d.get('step_type', ''),
-    d.get('enforce', 'hard'),
-    d.get('current_step', '')
-]))
-" "$SESSION_FILE" 2>/dev/null) || {
-  # python3 unavailable or JSON corrupt — fail closed if session file exists
-  printf 'BLOCKED: Cannot parse session state (python3 required or JSON corrupt). Remove %s to clear.\n' "$SESSION_FILE" >&2
-  exit 2
-}
+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
+fi
 
-IFS=$'\t' read -r STATUS STEP_TYPE ENFORCE CURRENT_STEP <<< "$SESSION_DATA"
+if [[ "$SESSION_STATUS" != "running" ]]; then
+  exit 0
+fi
 
-if [[ "$STATUS" != "running" ]]; then
+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
+# 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 || echo "")
 
+# 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"
+  fi
+}
+
 # Command steps: allow ONLY the MCP tools needed to progress the
-# workflow. Everything else is blocked, including future tools the
-# hook author hasn't heard of.
-if [[ "$STEP_TYPE" == "command" && "$ENFORCE" == "hard" ]]; then
+# workflow. Everything else is blocked, including future tools.
+if [[ "$SESSION_STEP_TYPE" == "command" && "$SESSION_ENFORCE" == "hard" ]]; then
   case "$TOOL_NAME" in
-    # MCP devkit tools — Claude uses these to drive the engine.
     mcp__*devkit*|devkit_advance|devkit_status|devkit_list|devkit_start)
       exit 0
       ;;
-    # TodoWrite is a pure in-memory tracker with no side effects, allowed.
     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' "$CURRENT_STEP" "$TOOL_NAME" >&2
+      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/parallel steps: allow everything (Claude needs full tool access).
+# 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*|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.
 exit 0
diff --git a/hooks/devkit-guard_test.sh b/hooks/devkit-guard_test.sh
new file mode 100755
index 0000000..ade37ab
--- /dev/null
+++ b/hooks/devkit-guard_test.sh
@@ -0,0 +1,167 @@
+#!/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.
+run_case "stale-prompt-hard allows Write (orphaned)" \
+  "$(stale_session)" "Write" 0 "orphaned"
+
+# --- 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 c632bfc..10a154a 100755
--- a/hooks/devkit-stop-guard.sh
+++ b/hooks/devkit-stop-guard.sh
@@ -8,6 +8,13 @@ set -euo pipefail
 # 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.
+
+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
@@ -17,38 +24,42 @@ if [[ -z "$DATA_DIR" ]]; then
 fi
 
 SESSION_FILE="${DATA_DIR}/session.json"
-if [[ ! -f "$SESSION_FILE" ]]; then
+
+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
   printf '{"decision":"approve"}'
   exit 0
 fi
 
-# Parse all fields in a single python3 call. Passes path via sys.argv
-# to prevent shell injection. Outputs valid JSON directly. Handles the
-# TOCTOU race (file cleared between -f test and open) as "no session"
-# so we don't spuriously block a completed workflow.
-PARSED=$(python3 -c "
-import json, sys
-try:
-    d = json.load(open(sys.argv[1]))
-except FileNotFoundError:
-    print(json.dumps({'decision': 'approve'}))
-    sys.exit(0)
-if d.get('status') == 'running':
-    remaining = d.get('total_steps', 0) - d.get('current_index', 0)
-    wf = d.get('workflow', 'unknown')
-    print(json.dumps({
-        'decision': 'block',
-        'reason': f'Workflow {wf} incomplete — {remaining} steps remaining. Call devkit_advance to continue.'
-    }))
-else:
-    print(json.dumps({'decision': 'approve'}))
-" "$SESSION_FILE" 2>/dev/null) || {
-  # Cannot parse — fail closed with diagnostic. User must either
-  # complete the workflow or remove the stale file manually.
-  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"
+if [[ "$SESSION_STATUS" != "running" ]]; then
+  printf '{"decision":"approve"}'
+  exit 0
+fi
+
+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
-}
+fi
 
-printf '%s' "$PARSED"
+REMAINING=0
+if [[ -n "$SESSION_TOTAL_STEPS" && -n "$SESSION_CURRENT_INDEX" ]]; then
+  REMAINING=$((SESSION_TOTAL_STEPS - SESSION_CURRENT_INDEX))
+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.
+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"
 exit 0
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 82be6c0..52780a3 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": 2
+            "timeout": 5
           }
         ]
       }
diff --git a/hooks/lib/read-session.sh b/hooks/lib/read-session.sh
new file mode 100644
index 0000000..05a68b8
--- /dev/null
+++ b/hooks/lib/read-session.sh
@@ -0,0 +1,89 @@
+#!/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)
+        age = (datetime.datetime.now(datetime.timezone.utc) - t).total_seconds()
+        if age > ttl:
+            stale = "1"
+    except ValueError:
+        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
+
+  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/lib/state_json.go b/src/lib/state_json.go
index f954b81..c145b22 100644
--- a/src/lib/state_json.go
+++ b/src/lib/state_json.go
@@ -10,20 +10,24 @@ import (
 
 // SessionState is the hot-path state file read by hooks on every tool call.
 type SessionState struct {
-	ID           string            `json:"id"`
-	Workflow     string            `json:"workflow"`
-	Input        string            `json:"input"`
-	CurrentStep  string            `json:"current_step"`
-	CurrentIndex int               `json:"current_index"`
-	TotalSteps   int               `json:"total_steps"`
-	StepType     string            `json:"step_type"` // "prompt" | "command" | "parallel"
-	Enforce      string            `json:"enforce"`
-	Branch       bool              `json:"branch"`
-	BudgetUSD    float64           `json:"budget_usd"`
-	SpentUSD     float64           `json:"spent_usd"`
-	StartedAt    time.Time         `json:"started_at"`
-	Outputs      map[string]string `json:"outputs"`
-	Status       string            `json:"status"` // "running" | "done" | "failed"
+	ID           string    `json:"id"`
+	Workflow     string    `json:"workflow"`
+	Input        string    `json:"input"`
+	CurrentStep  string    `json:"current_step"`
+	CurrentIndex int       `json:"current_index"`
+	TotalSteps   int       `json:"total_steps"`
+	StepType     string    `json:"step_type"` // "prompt" | "command" | "parallel"
+	Enforce      string    `json:"enforce"`
+	Branch       bool      `json:"branch"`
+	BudgetUSD    float64   `json:"budget_usd"`
+	SpentUSD     float64   `json:"spent_usd"`
+	StartedAt    time.Time `json:"started_at"`
+	// UpdatedAt is bumped on every WriteSessionJSON. Hooks read this to
+	// detect orphaned sessions (engine crash leaves Status=running but
+	// no process is advancing) and refuse to enforce against them.
+	UpdatedAt time.Time         `json:"updated_at"`
+	Outputs   map[string]string `json:"outputs"`
+	Status    string            `json:"status"` // "running" | "done" | "failed"
 	// Busy is a claim flag held for the duration of an in-flight step
 	// advance. Written under the session lock; a concurrent claimant
 	// seeing it set must abort instead of racing the current writer.
@@ -74,6 +78,9 @@ func WriteSessionJSON(dataDir string, state *SessionState) error {
 }
 
 func writeSessionJSONLocked(dataDir string, state *SessionState) error {
+	// Bump on every write so hooks can spot orphaned sessions via
+	// staleness — see SessionState.UpdatedAt.
+	state.UpdatedAt = time.Now()
 	data, err := json.MarshalIndent(state, "", "  ")
 	if err != nil {
 		return fmt.Errorf("marshal session: %w", err)
diff --git a/src/lib/state_test.go b/src/lib/state_test.go
index 29f6d19..cc4eaba 100644
--- a/src/lib/state_test.go
+++ b/src/lib/state_test.go
@@ -3,6 +3,7 @@ package lib
 import (
 	"os"
 	"testing"
+	"time"
 )
 
 func TestNewSessionID(t *testing.T) {
@@ -78,3 +79,48 @@ func TestSessionJSON(t *testing.T) {
 		t.Error("expected nil after clear")
 	}
 }
+
+// TestSessionJSONUpdatedAtBumps guards the staleness signal hooks rely
+// on: every Write/Update call must move UpdatedAt forward. A regression
+// here would wedge hooks into permanent "fresh session" mode and let
+// orphaned sessions block tool calls forever.
+func TestSessionJSONUpdatedAtBumps(t *testing.T) {
+	dir := t.TempDir()
+	state := &SessionState{
+		ID:       "abc123",
+		Workflow: "research",
+		StepType: "prompt",
+		Enforce:  "hard",
+		Status:   "running",
+		Outputs:  map[string]string{},
+	}
+
+	if err := WriteSessionJSON(dir, state); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	first, err := ReadSessionJSON(dir)
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	if first.UpdatedAt.IsZero() {
+		t.Fatal("UpdatedAt should be set after WriteSessionJSON")
+	}
+
+	// Sleep a hair past the timestamp resolution so the second bump is
+	// observable even on systems with 1ms time granularity.
+	time.Sleep(2 * time.Millisecond)
+
+	if _, err := UpdateSessionJSON(dir, func(cur *SessionState) (*SessionState, error) {
+		cur.CurrentStep = "next"
+		return cur, nil
+	}); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	second, err := ReadSessionJSON(dir)
+	if err != nil {
+		t.Fatalf("read after update: %v", err)
+	}
+	if !second.UpdatedAt.After(first.UpdatedAt) {
+		t.Errorf("UpdatedAt did not advance: first=%v second=%v", first.UpdatedAt, second.UpdatedAt)
+	}
+}
diff --git a/src/mcp/tools.go b/src/mcp/tools.go
index f2b60af..7406fa3 100644
--- a/src/mcp/tools.go
+++ b/src/mcp/tools.go
@@ -24,6 +24,14 @@ const commandTimeout = 5 * time.Minute
 // cannot consume the full commandTimeout budget.
 const gateTimeout = 60 * time.Second
 
+// sessionStaleTTL is the age after which an existing "running" session
+// is considered orphaned — i.e. the previous engine process crashed
+// without clearing state. devkit_start will overwrite such a session
+// instead of rejecting the call, and the PreToolUse hook stops
+// enforcing against it. Tuned to exceed any realistic command step
+// plus a safety margin.
+const sessionStaleTTL = 30 * time.Minute
+
 func (s *Server) listTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) {
 	tool := mcpmcp.NewTool("devkit_list",
 		mcpmcp.WithDescription("List available workflows"),
@@ -120,7 +128,21 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) {
 		firstStep := wf.Steps[0]
 		state, err := lib.UpdateSessionJSON(s.dataDir, func(cur *lib.SessionState) (*lib.SessionState, error) {
 			if cur != nil && (cur.Status == "running" || cur.Status == "starting") {
-				return nil, fmt.Errorf("workflow %s already %s (session %s). Call devkit_advance to continue or devkit_status to check", cur.Workflow, cur.Status, cur.ID)
+				// Stale-session recovery: a previous engine process
+				// crashed or was killed without clearing state, so the
+				// slot is wedged. Gate on UpdatedAt (not StartedAt) so a
+				// long-running workflow that is actively advancing keeps
+				// the slot, while one that has genuinely stopped making
+				// progress gets reclaimed. Fall back to StartedAt for
+				// pre-UpdatedAt sessions written by older binaries.
+				lastBump := cur.UpdatedAt
+				if lastBump.IsZero() {
+					lastBump = cur.StartedAt
+				}
+				if !lastBump.IsZero() && time.Since(lastBump) < sessionStaleTTL {
+					return nil, fmt.Errorf("workflow %s already %s (session %s). Call devkit_advance to continue or devkit_status to check", cur.Workflow, cur.Status, cur.ID)
+				}
+				fmt.Fprintf(os.Stderr, "devkit_start: reclaiming stale session %s (workflow %s, idle for %s)\n", cur.ID, cur.Workflow, time.Since(lastBump).Round(time.Second))
 			}
 			return &lib.SessionState{
 				ID:           sessionID,
diff --git a/src/mcp/tools_test.go b/src/mcp/tools_test.go
index 101a4f2..8e4e7d8 100644
--- a/src/mcp/tools_test.go
+++ b/src/mcp/tools_test.go
@@ -292,6 +292,170 @@ steps:
 	}
 }
 
+// TestStartReclaimsStaleSession verifies the orphan-recovery path: a
+// session older than sessionStaleTTL must be overwritten by a new
+// devkit_start rather than rejected. Without this, a crashed engine
+// process wedges the slot forever and the user has to manually clear
+// session.json.
+func TestStartReclaimsStaleSession(t *testing.T) {
+	wfDir := t.TempDir()
+	dataDir := t.TempDir()
+
+	writeFile(t, filepath.Join(wfDir, "review.yml"), `name: review
+description: Code review workflow
+steps:
+  - id: analyse
+    prompt: Analyse {{input}} and identify issues.
+`)
+
+	// Pre-seed an orphaned session: status=running but UpdatedAt far
+	// enough in the past that the TTL check fires. The write path
+	// bumps UpdatedAt to now, so we have to rewrite the raw file
+	// after to backdate it.
+	stale := &lib.SessionState{
+		ID:        "stale1234567",
+		Workflow:  "review",
+		Status:    "running",
+		StartedAt: time.Now().Add(-2 * time.Hour),
+		UpdatedAt: time.Now().Add(-2 * time.Hour),
+		Outputs:   map[string]string{},
+	}
+	if err := lib.WriteSessionJSON(dataDir, stale); err != nil {
+		t.Fatalf("seed stale session: %v", err)
+	}
+	// WriteSessionJSON bumped UpdatedAt to now — rewrite via Update
+	// to force the stale timestamp back onto disk.
+	if _, err := lib.UpdateSessionJSON(dataDir, func(cur *lib.SessionState) (*lib.SessionState, error) {
+		cur.UpdatedAt = time.Now().Add(-2 * time.Hour)
+		cur.StartedAt = time.Now().Add(-2 * time.Hour)
+		return cur, nil
+	}); err != nil {
+		t.Fatalf("backdate: %v", err)
+	}
+	// And writeSessionJSONLocked will have bumped it again, so do a
+	// raw marshal bypassing the helper. Instead: use os.Chtimes-style
+	// trick isn't enough since we need the field inside the JSON.
+	// Easiest: write the JSON file directly.
+	rawPath := filepath.Join(dataDir, "session.json")
+	raw := []byte(`{
+  "id": "stale1234567",
+  "workflow": "review",
+  "input": "",
+  "current_step": "",
+  "current_index": 0,
+  "total_steps": 1,
+  "step_type": "prompt",
+  "enforce": "hard",
+  "branch": false,
+  "budget_usd": 0,
+  "spent_usd": 0,
+  "started_at": "2020-01-01T00:00:00Z",
+  "updated_at": "2020-01-01T00:00:00Z",
+  "outputs": {},
+  "status": "running"
+}
+`)
+	if err := os.WriteFile(rawPath, raw, 0o600); err != nil {
+		t.Fatalf("write raw: %v", err)
+	}
+
+	srv := newTestServer(t, dataDir, wfDir)
+	_, handler := srv.startTool()
+	req := mcpmcp.CallToolRequest{}
+	req.Params.Arguments = map[string]interface{}{
+		"workflow": "review",
+		"input":    "main.go",
+	}
+
+	result, err := handler(context.Background(), req)
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	if result.IsError {
+		tc, _ := result.Content[0].(mcpmcp.TextContent)
+		t.Fatalf("expected reclaim to succeed, got error: %s", tc.Text)
+	}
+
+	state, err := lib.ReadSessionJSON(dataDir)
+	if err != nil || state == nil {
+		t.Fatalf("read reclaimed session: %v", err)
+	}
+	if state.ID == "stale1234567" {
+		t.Errorf("expected a fresh session ID after reclaim, still got the stale one")
+	}
+	if state.Input != "main.go" {
+		t.Errorf("expected new input 'main.go', got %q", state.Input)
+	}
+}
+
+// TestStartRejectsFreshSession is the inverse: TestStartAlreadyRunning
+// covers the case where an in-progress session has a fresh UpdatedAt.
+// This test adds the explicit guarantee that the TTL cutoff is real —
+// a session 29 minutes old must still reject, only >30min reclaims.
+func TestStartRejectsFreshSession(t *testing.T) {
+	wfDir := t.TempDir()
+	dataDir := t.TempDir()
+
+	writeFile(t, filepath.Join(wfDir, "review.yml"), `name: review
+description: Code review workflow
+steps:
+  - id: analyse
+    prompt: Analyse {{input}} and identify issues.
+`)
+
+	// 29 minutes old — below the 30-minute TTL.
+	fresh := &lib.SessionState{
+		ID:        "fresh1234567",
+		Workflow:  "review",
+		Status:    "running",
+		StartedAt: time.Now().Add(-29 * time.Minute),
+		UpdatedAt: time.Now().Add(-29 * time.Minute),
+		Outputs:   map[string]string{},
+	}
+	if err := lib.WriteSessionJSON(dataDir, fresh); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	// WriteSessionJSON bumps UpdatedAt; rewrite raw so the test
+	// actually exercises the 29-minute case.
+	rawPath := filepath.Join(dataDir, "session.json")
+	raw := []byte(`{
+  "id": "fresh1234567",
+  "workflow": "review",
+  "input": "",
+  "current_step": "",
+  "current_index": 0,
+  "total_steps": 1,
+  "step_type": "prompt",
+  "enforce": "hard",
+  "branch": false,
+  "budget_usd": 0,
+  "spent_usd": 0,
+  "started_at": "` + time.Now().Add(-29*time.Minute).UTC().Format(time.RFC3339Nano) + `",
+  "updated_at": "` + time.Now().Add(-29*time.Minute).UTC().Format(time.RFC3339Nano) + `",
+  "outputs": {},
+  "status": "running"
+}
+`)
+	if err := os.WriteFile(rawPath, raw, 0o600); err != nil {
+		t.Fatalf("write raw: %v", err)
+	}
+
+	srv := newTestServer(t, dataDir, wfDir)
+	_, handler := srv.startTool()
+	req := mcpmcp.CallToolRequest{}
+	req.Params.Arguments = map[string]interface{}{
+		"workflow": "review",
+		"input":    "main.go",
+	}
+	result, err := handler(context.Background(), req)
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	if !result.IsError {
+		t.Fatal("expected IsError=true for fresh session below TTL")
+	}
+}
+
 func TestAdvancePromptSteps(t *testing.T) {
 	wfDir := t.TempDir()
 	dataDir := t.TempDir()

From 4d26748e455d45b0d99ecabae693151084fe7915 Mon Sep 17 00:00:00 2001
From: Tym Rabchuk <tymrabchuk@gmail.com>
Date: Fri, 10 Apr 2026 20:08:26 -0400
Subject: [PATCH 2/3] test(hooks): update hooks_test.sh for new prompt-step
 policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CI smoke suite asserted prompt+hard+Bash → allow, which is exactly
the drift hole this branch closes. Replace the single old case with
explicit coverage of the new allowlist:

- prompt+hard: Read/Grep/devkit_advance allow; Bash/Write/Task block
- prompt+soft: Bash allowed (nudge-only)
- parallel+hard: Task allowed (engine dispatches)
---
 hooks/hooks_test.sh | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/hooks/hooks_test.sh b/hooks/hooks_test.sh
index 06774b4..aa52a5d 100644
--- a/hooks/hooks_test.sh
+++ b/hooks/hooks_test.sh
@@ -199,10 +199,36 @@ run_guard '{"status":"done","step_type":"command","enforce":"hard","current_step
   '{"tool_name":"Bash","tool_input":{"command":"ls"}}' \
   0 "status=done → allow"
 
-# Prompt step (any enforce) → allow everything
+# Prompt step + hard enforce: read-only evidence tools allowed,
+# Write/Bash/Task blocked. Closes the drift hole from issue #63.
+run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
+  '{"tool_name":"Read","tool_input":{"file_path":"main.go"}}' \
+  0 "prompt+hard+Read → allow"
+run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
+  '{"tool_name":"Grep","tool_input":{"pattern":"foo"}}' \
+  0 "prompt+hard+Grep → allow"
 run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
   '{"tool_name":"Bash","tool_input":{"command":"ls"}}' \
-  0 "prompt step hard enforce → allow Bash"
+  2 "prompt+hard+Bash → block (drift hole #63)"
+run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
+  '{"tool_name":"Write","tool_input":{"file_path":"x.go","content":"x"}}' \
+  2 "prompt+hard+Write → block"
+run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
+  '{"tool_name":"Task","tool_input":{}}' \
+  2 "prompt+hard+Task → block"
+run_guard '{"status":"running","step_type":"prompt","enforce":"hard","current_step":"analyse"}' \
+  '{"tool_name":"devkit_advance"}' \
+  0 "prompt+hard+devkit_advance → allow"
+
+# Prompt step + soft enforce: allow everything (with stderr nudge).
+run_guard '{"status":"running","step_type":"prompt","enforce":"soft","current_step":"analyse"}' \
+  '{"tool_name":"Bash","tool_input":{"command":"ls"}}' \
+  0 "prompt+soft+Bash → allow with nudge"
+
+# Parallel step: engine dispatches, agent needs full tool access.
+run_guard '{"status":"running","step_type":"parallel","enforce":"hard","current_step":"fanout"}' \
+  '{"tool_name":"Task","tool_input":{}}' \
+  0 "parallel+hard+Task → allow"
 
 # Command step + hard enforce + Bash → block (exit 2)
 run_guard '{"status":"running","step_type":"command","enforce":"hard","current_step":"build"}' \

From 6c7220e0ceb2bb8945b5a47fdef948b8ece974c2 Mon Sep 17 00:00:00 2001
From: Tym Rabchuk <tymrabchuk@gmail.com>
Date: Sat, 11 Apr 2026 00:13:06 -0400
Subject: [PATCH 3/3] fix(hooks): mega-review remediation for PR #64
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses critical findings from tri-review + pr-review-toolkit
mega-review before merge.

Critical fixes:
- hooks/devkit-guard.sh: narrow MCP allowlist from `mcp__*devkit*` to
  `mcp__*devkit-engine*|mcp__devkit__*` so a third-party tool with
  "devkit" in its name cannot sneak through hard enforcement.
- hooks/lib/read-session.sh: align TTL boundary with Go side (>= not >)
  so a session at exactly 30min has the same verdict in hook + start.
- hooks/lib/read-session.sh: catch TypeError (naive datetime) in addition
  to ValueError, so a session file without tzinfo doesn't crash the
  parser and flip the guard into fail-closed mode.
- hooks/lib/read-session.sh: require exactly 8 tab-separated fields from
  the python3 parser — a future refactor dropping a field would have
  silently defaulted SESSION_STALE to empty and started enforcing
  against orphaned sessions.
- hooks/devkit-stop-guard.sh: wrap the final python3 verdict emit with
  a manual-JSON fail-closed fallback. Under `set -e` an unguarded python3
  crash would exit non-zero with no Stop decision on stdout, leaving
  the behaviour undefined.
- hooks/devkit-guard.sh: stderr diagnostic on tool-name parse failure,
  so the BLOCKED message doesn't just say "(attempted tool: )" with
  no hint.
- src/mcp/tools.go: surface stale-session reclaim in the
  NewToolResultText response so the agent immediately sees that the
  previous session's outputs were discarded. Also refuse to reclaim
  a session with BOTH timestamps zero (malformed state file).
- src/lib/state_json.go: document the UpdatedAt side-effect on
  WriteSessionJSON so future callers don't get bitten by the mutation.

Test coverage additions:
- devkit-guard_test.sh: fail-closed corrupt-JSON fixture on the new
  code path.
- devkit-guard_test.sh: stale-command-hard, stale-prompt-soft, and
  legacy-session-without-updated_at fixtures.
- devkit-guard_test.sh: regression guards for narrowed MCP glob
  (blocks foreign devkit-like, allows real devkit-engine).
- src/mcp/tools_test.go: assert agent-visible reclaim notice in
  TestStartReclaimsStaleSession; assert specific error string in
  TestStartRejectsFreshSession so an unrelated error can't pass
  silently.

Test matrix: 27 devkit-guard fixtures + 46 hooks_test.sh smoke +
Go unit tests all green.
---
 hooks/devkit-guard.sh      | 18 +++++++----
 hooks/devkit-guard_test.sh | 66 +++++++++++++++++++++++++++++++++++++-
 hooks/devkit-stop-guard.sh | 12 +++++--
 hooks/lib/read-session.sh  | 23 +++++++++++--
 src/lib/state_json.go      |  3 ++
 src/mcp/tools.go           | 18 ++++++++---
 src/mcp/tools_test.go      | 54 +++++++++++++------------------
 7 files changed, 147 insertions(+), 47 deletions(-)

diff --git a/hooks/devkit-guard.sh b/hooks/devkit-guard.sh
index ea7c281..248dc85 100755
--- a/hooks/devkit-guard.sh
+++ b/hooks/devkit-guard.sh
@@ -8,9 +8,9 @@ set -euo pipefail
 # Policy matrix:
 #   step_type=command, enforce=hard → allow only devkit MCP + TodoWrite
 #                                     (engine runs the command, not Claude)
-#   step_type=prompt,  enforce=hard → allow evidence-gathering + devkit MCP
-#                                     (Read/Grep/Glob/TodoWrite) — force
-#                                     the agent to advance before any
+#   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
@@ -56,7 +56,13 @@ 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 || echo "")
+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.
@@ -73,7 +79,7 @@ step_label() {
 # workflow. Everything else is blocked, including future tools.
 if [[ "$SESSION_STEP_TYPE" == "command" && "$SESSION_ENFORCE" == "hard" ]]; then
   case "$TOOL_NAME" in
-    mcp__*devkit*|devkit_advance|devkit_status|devkit_list|devkit_start)
+    mcp__*devkit-engine*|mcp__devkit__*|devkit_advance|devkit_status|devkit_list|devkit_start)
       exit 0
       ;;
     TodoWrite)
@@ -92,7 +98,7 @@ fi
 # devkit_advance. See issue #63.
 if [[ "$SESSION_STEP_TYPE" == "prompt" && "$SESSION_ENFORCE" == "hard" ]]; then
   case "$TOOL_NAME" in
-    mcp__*devkit*|devkit_advance|devkit_status|devkit_list|devkit_start)
+    mcp__*devkit-engine*|mcp__devkit__*|devkit_advance|devkit_status|devkit_list|devkit_start)
       exit 0
       ;;
     Read|Grep|Glob|TodoWrite|NotebookRead)
diff --git a/hooks/devkit-guard_test.sh b/hooks/devkit-guard_test.sh
index ade37ab..ab50a3e 100755
--- a/hooks/devkit-guard_test.sh
+++ b/hooks/devkit-guard_test.sh
@@ -150,10 +150,74 @@ run_case "prompt-soft allows Bash" \
 run_case "parallel allows Write" \
   "$(fresh_session parallel hard)" "Write" 0 ""
 
-# Stale session → allow + warn, regardless of step type.
+# 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"
diff --git a/hooks/devkit-stop-guard.sh b/hooks/devkit-stop-guard.sh
index 10a154a..4322cf0 100755
--- a/hooks/devkit-stop-guard.sh
+++ b/hooks/devkit-stop-guard.sh
@@ -55,11 +55,19 @@ 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.
-python3 -c '
+# 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"
+' "$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
 exit 0
diff --git a/hooks/lib/read-session.sh b/hooks/lib/read-session.sh
index 05a68b8..b1affa3 100644
--- a/hooks/lib/read-session.sh
+++ b/hooks/lib/read-session.sh
@@ -56,10 +56,19 @@ if ts:
         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()
-        if age > ttl:
+        # >= 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:
+    except (ValueError, TypeError):
         pass  # unparseable timestamp — treat as fresh, fail-safe
 
 print("\t".join([
@@ -74,6 +83,16 @@ print("\t".join([
 ]))
 ' "$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 \
diff --git a/src/lib/state_json.go b/src/lib/state_json.go
index c145b22..25d36de 100644
--- a/src/lib/state_json.go
+++ b/src/lib/state_json.go
@@ -71,6 +71,9 @@ func withSessionLock(dataDir string, fn func() error) error {
 }
 
 // WriteSessionJSON atomically writes session state under the session lock.
+// Side effect: mutates state.UpdatedAt to time.Now() before serialising.
+// Callers holding the struct for later comparison or retry must account
+// for this — take a copy first if the original timestamp matters.
 func WriteSessionJSON(dataDir string, state *SessionState) error {
 	return withSessionLock(dataDir, func() error {
 		return writeSessionJSONLocked(dataDir, state)
diff --git a/src/mcp/tools.go b/src/mcp/tools.go
index 7406fa3..487e9c3 100644
--- a/src/mcp/tools.go
+++ b/src/mcp/tools.go
@@ -126,6 +126,7 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) {
 		// we publish the transition to "running" below.
 		sessionID := lib.NewSessionID()
 		firstStep := wf.Steps[0]
+		var reclaimedNote string
 		state, err := lib.UpdateSessionJSON(s.dataDir, func(cur *lib.SessionState) (*lib.SessionState, error) {
 			if cur != nil && (cur.Status == "running" || cur.Status == "starting") {
 				// Stale-session recovery: a previous engine process
@@ -139,10 +140,17 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) {
 				if lastBump.IsZero() {
 					lastBump = cur.StartedAt
 				}
-				if !lastBump.IsZero() && time.Since(lastBump) < sessionStaleTTL {
+				// Both timestamps zero → malformed state file. Refuse
+				// to silently reclaim; the user needs to see this.
+				if lastBump.IsZero() {
+					return nil, fmt.Errorf("workflow %s is %s (session %s) but has no timestamps — remove session.json manually to recover", cur.Workflow, cur.Status, cur.ID)
+				}
+				if time.Since(lastBump) < sessionStaleTTL {
 					return nil, fmt.Errorf("workflow %s already %s (session %s). Call devkit_advance to continue or devkit_status to check", cur.Workflow, cur.Status, cur.ID)
 				}
-				fmt.Fprintf(os.Stderr, "devkit_start: reclaiming stale session %s (workflow %s, idle for %s)\n", cur.ID, cur.Workflow, time.Since(lastBump).Round(time.Second))
+				idle := time.Since(lastBump).Round(time.Second)
+				reclaimedNote = fmt.Sprintf("Note: reclaimed stale session %s (workflow %s, idle %s). Outputs from the previous session were discarded.\n\n", cur.ID, cur.Workflow, idle)
+				fmt.Fprintf(os.Stderr, "devkit_start: reclaiming stale session %s (workflow %s, idle for %s)\n", cur.ID, cur.Workflow, idle)
 			}
 			return &lib.SessionState{
 				ID:           sessionID,
@@ -217,8 +225,10 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) {
 			}
 		}
 
-		// Build response with first step + principles
-		response := s.formatStepResponse(wf, state, &firstStep, input)
+		// Build response with first step + principles. Prefix with the
+		// reclaim notice (if any) so the agent sees the discarded
+		// session immediately, not buried in a stderr log file.
+		response := reclaimedNote + s.formatStepResponse(wf, state, &firstStep, input)
 		return mcpmcp.NewToolResultText(response), nil
 	}
 }
diff --git a/src/mcp/tools_test.go b/src/mcp/tools_test.go
index 8e4e7d8..f30702a 100644
--- a/src/mcp/tools_test.go
+++ b/src/mcp/tools_test.go
@@ -308,34 +308,9 @@ steps:
     prompt: Analyse {{input}} and identify issues.
 `)
 
-	// Pre-seed an orphaned session: status=running but UpdatedAt far
-	// enough in the past that the TTL check fires. The write path
-	// bumps UpdatedAt to now, so we have to rewrite the raw file
-	// after to backdate it.
-	stale := &lib.SessionState{
-		ID:        "stale1234567",
-		Workflow:  "review",
-		Status:    "running",
-		StartedAt: time.Now().Add(-2 * time.Hour),
-		UpdatedAt: time.Now().Add(-2 * time.Hour),
-		Outputs:   map[string]string{},
-	}
-	if err := lib.WriteSessionJSON(dataDir, stale); err != nil {
-		t.Fatalf("seed stale session: %v", err)
-	}
-	// WriteSessionJSON bumped UpdatedAt to now — rewrite via Update
-	// to force the stale timestamp back onto disk.
-	if _, err := lib.UpdateSessionJSON(dataDir, func(cur *lib.SessionState) (*lib.SessionState, error) {
-		cur.UpdatedAt = time.Now().Add(-2 * time.Hour)
-		cur.StartedAt = time.Now().Add(-2 * time.Hour)
-		return cur, nil
-	}); err != nil {
-		t.Fatalf("backdate: %v", err)
-	}
-	// And writeSessionJSONLocked will have bumped it again, so do a
-	// raw marshal bypassing the helper. Instead: use os.Chtimes-style
-	// trick isn't enough since we need the field inside the JSON.
-	// Easiest: write the JSON file directly.
+	// WriteSessionJSON / UpdateSessionJSON always bump UpdatedAt to
+	// time.Now(), so the only way to land a past timestamp on disk is
+	// to write the raw JSON file directly.
 	rawPath := filepath.Join(dataDir, "session.json")
 	raw := []byte(`{
   "id": "stale1234567",
@@ -376,6 +351,16 @@ steps:
 		t.Fatalf("expected reclaim to succeed, got error: %s", tc.Text)
 	}
 
+	// Assert the agent-visible reclaim notice is present — without
+	// this the agent has no signal that its prior session was wiped.
+	tc, _ := result.Content[0].(mcpmcp.TextContent)
+	if !strings.Contains(tc.Text, "reclaimed stale session stale1234567") {
+		t.Errorf("expected reclaim notice in response, got:\n%s", tc.Text)
+	}
+	if !strings.Contains(tc.Text, "Outputs from the previous session were discarded") {
+		t.Errorf("expected discarded-outputs warning in response, got:\n%s", tc.Text)
+	}
+
 	state, err := lib.ReadSessionJSON(dataDir)
 	if err != nil || state == nil {
 		t.Fatalf("read reclaimed session: %v", err)
@@ -388,10 +373,11 @@ steps:
 	}
 }
 
-// TestStartRejectsFreshSession is the inverse: TestStartAlreadyRunning
-// covers the case where an in-progress session has a fresh UpdatedAt.
-// This test adds the explicit guarantee that the TTL cutoff is real —
-// a session 29 minutes old must still reject, only >30min reclaims.
+// TestStartRejectsFreshSession asserts the TTL cutoff is real — a
+// session 29 minutes old must still reject, only sessions at or past
+// the 30 minute sessionStaleTTL get reclaimed. Error message is
+// checked so a regression where IsError stays true for an unrelated
+// reason (e.g. workflow not found) doesn't pass this test silently.
 func TestStartRejectsFreshSession(t *testing.T) {
 	wfDir := t.TempDir()
 	dataDir := t.TempDir()
@@ -454,6 +440,10 @@ steps:
 	if !result.IsError {
 		t.Fatal("expected IsError=true for fresh session below TTL")
 	}
+	tc, _ := result.Content[0].(mcpmcp.TextContent)
+	if !strings.Contains(tc.Text, "already running") {
+		t.Errorf("expected 'already running' TTL-enforcement error, got: %s", tc.Text)
+	}
 }
 
 func TestAdvancePromptSteps(t *testing.T) {