agent-harness-kit 0.6.0 → 0.8.0

package/src/templates/scripts/pretooluse-bash-guard.sh.hbs

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# PreToolUse hook (matcher: Bash) — denies a small, deterministic set of
+# shell commands that would bypass the harness's safety net. Replaces the
+# "don't disable the structural test" warning in CLAUDE.md with a hard
+# guardrail (Hashimoto axiom: every failure becomes a permanent prevention).
+#
+# What's denied (and why):
+#   1. `git (push|commit) --no-verify`     — bypasses pre-push baseline guard
+#   2. `rm -rf .harness/`                  — wipes lockfile + baseline state
+#   3. `rm -rf .claude/`                   — wipes skills/agents/hooks config
+#   4. `chmod -x scripts/(structural-test|precompletion|pre-push)…`
+#                                          — disables hook scripts via perm bit
+#   5. `> .harness/structural-baseline.json` (truncation)
+#                                          — wipes baseline without GC ritual
+#   6. `jq … .harness/structural-baseline.json | … > ...`
+#                                          — manual baseline grow (covered by
+#                                            baseline-monotonic guard, but the
+#                                            agent should not even try)
+#   7. Setting `disableAllHooks: true` via sed/jq into .claude/settings.json
+#
+# Allowed escape hatch: `AHK_ALLOW_BYPASS=1` environment variable. When
+# present, the guard logs the attempt to .harness/bypass.log and lets the
+# command through. Use only with explicit user intent (e.g. mass-rename
+# refactor). The bypass leaves a paper trail so it can't be silent.
+#
+# Decision contract:
+#   - Pattern match + no bypass → exit 0 + JSON permissionDecision: "deny"
+#     with permissionDecisionReason explaining the rule.
+#   - No match → exit 0 with no output (defer to model's auto-mode).
+#   - Bypass env present → log + exit 0 (defer, command proceeds).
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then
+    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
+  else
+    if [ -n "$2" ]; then
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
+    else
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+    fi
+  fi
+}
+
+if ! have_jp; then
+  # Without a JSON parser we can't read the command. Skip rather than
+  # spuriously block — failing closed here would deny EVERY Bash call.
+  exit 0
+fi
+
+CMD=$(echo "$INPUT" | jp '.tool_input.command // empty')
+[ -z "$CMD" ] && exit 0
+
+# Compose denial reason. Empty when allowed.
+REASON=""
+
+# Pattern 1: --no-verify on git push / commit
+if echo "$CMD" | grep -qE '\bgit\s+(push|commit)\b.*--no-verify\b'; then
+  REASON="git push/commit --no-verify bypasses the pre-push baseline-monotonic guard. The kit ships that guard because the path of least resistance for new violations is 'append them to the baseline' — which defeats the rule. Fix the underlying violation, then push without --no-verify."
+fi
+
+# Pattern 2: rm -rf .harness/ or .claude/
+if echo "$CMD" | grep -qE '\brm\s+(-[rRf]+\s+|--recursive\s+)+\.?\.?/?\.harness(/|\s|$)'; then
+  REASON="rm -rf .harness/ removes the lockfile + structural baseline. Use 'agent-harness-kit upgrade' to refresh installed files instead."
+fi
+if echo "$CMD" | grep -qE '\brm\s+(-[rRf]+\s+|--recursive\s+)+\.?\.?/?\.claude(/|\s|$)'; then
+  REASON="rm -rf .claude/ removes every skill/agent/hook the kit wrote. Re-init with 'agent-harness-kit init' if you need a clean slate."
+fi
+
+# Pattern 3: chmod -x on hook scripts (silently disables them)
+if echo "$CMD" | grep -qE '\bchmod\s+([-+]?[ugoa]?[-+=][rwxX]*)?-x\s+scripts/(structural-test|precompletion|pre-push|session-start|pretooluse)' \
+   || echo "$CMD" | grep -qE '\bchmod\s+0?[0-6][0-6][0-6]\s+scripts/(structural-test|precompletion|pre-push|session-start|pretooluse)'; then
+  REASON="chmod -x on a hook script silently disables the harness. If you need to skip the check this turn, set AHK_HOOK_MODE=warn for the session — that leaves an audit trail."
+fi
+
+# Pattern 4: truncating the structural baseline
+if echo "$CMD" | grep -qE '(^|[;&|]\s*)(:|true|echo\s*("\["|\[\]|"|null))\s*>\s*\.harness/structural-baseline\.json' \
+   || echo "$CMD" | grep -qE '>\s*\.harness/structural-baseline\.json\s*$'; then
+  # The second pattern is broader (any redirect TO the baseline). Allow
+  # 'mv' or 'cp' which produce non-truncating writes; this pattern catches
+  # the `> baseline.json` shape only.
+  REASON="Direct write to .harness/structural-baseline.json bypasses the monotonic guard. Append entries through the kit's own /garbage-collection skill, or fix the violation in code so the baseline shrinks."
+fi
+
+# Pattern 5: setting disableAllHooks via sed/jq
+if echo "$CMD" | grep -qE '(sed|jq).*disableAllHooks.*true.*\.claude/settings\.json' \
+   || echo "$CMD" | grep -qE '\.claude/settings\.json.*disableAllHooks.*true' \
+   || echo "$CMD" | grep -qE 'disableAllHooks.*true.*\.claude/settings\.json'; then
+  REASON="disableAllHooks: true defeats every protection the kit installs. If you need to temporarily disable a specific hook for debugging, remove it explicitly with a commit message explaining why."
+fi
+
+if [ -z "$REASON" ]; then
+  # Command passed all checks — defer to the auto-mode classifier (or to
+  # whatever permission rule the user has set). We do not return
+  # permissionDecision: "allow" because that would auto-approve every
+  # benign Bash call, robbing the user of explicit approvals when in
+  # default mode.
+  exit 0
+fi
+
+# Bypass escape hatch — leaves an audit trail.
+if [ "${AHK_ALLOW_BYPASS:-}" = "1" ]; then
+  mkdir -p .harness
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+  ESCAPED_CMD=${CMD//$'\n'/ }
+  ESCAPED_CMD=${ESCAPED_CMD//\"/\\\"}
+  printf '{"ts":"%s","sha":"%s","bypass":"AHK_ALLOW_BYPASS","reason":"%s","command":"%s"}\n' \
+    "$TS" "$SHA" "${REASON//\"/\\\"}" "$ESCAPED_CMD" >> .harness/bypass.log
+  exit 0
+fi
+
+# Emit deny. JSON via Node so escaping is honest.
+if command -v node >/dev/null 2>&1; then
+  node -e "
+    const reason = process.argv[1];
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason
+      }
+    };
+    process.stdout.write(JSON.stringify(out));
+  " "$REASON"
+elif have_jq; then
+  jq -nc --arg r "$REASON" \
+    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $r}}'
+else
+  # Fallback: exit 2 with stderr. Older Claude Code versions parse stderr
+  # for denial reason when JSON unavailable.
+  echo "$REASON" >&2
+  exit 2
+fi
+exit 0

package/src/templates/scripts/session-end.sh.hbs

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# SessionEnd hook — append a single observability line to PROGRESS.md when
+# the session terminates. Never blocks (SessionEnd is cleanup-only per
+# Claude Code docs).
+#
+# Output line shape:
+#   YYYY-MM-DD HH:MM | session_end | <reason> | <branch> | <sha>
+#
+# Example:
+#   2026-05-16 19:00 | session_end | clear | main | abc1234
+#
+# Reasons (per Claude Code docs): clear, resume, logout, prompt_input_exit,
+# bypass_permissions_disabled, other.
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then jq -r "$1"
+  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+  fi
+}
+
+REASON="unknown"
+if have_jp; then
+  REASON=$(echo "$INPUT" | jp '.end_reason // "unknown"' 2>/dev/null || echo "unknown")
+fi
+
+BR="(no-git)"
+SHA="(no-git)"
+if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+  BR=$(git branch --show-current 2>/dev/null || echo "(detached)")
+  SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "(none)")
+fi
+
+mkdir -p .harness
+TS=$(date +"%Y-%m-%d %H:%M")
+echo "$TS | session_end | $REASON | $BR | $SHA" >> .harness/PROGRESS.md
+exit 0

package/src/templates/scripts/session-start.sh.hbs

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# SessionStart hook — inject a compact, deterministic context block when
+# a session begins, resumes, or comes back from compaction. Output goes
+# via JSON stdout `hookSpecificOutput.additionalContext`, which Claude
+# Code feeds into the conversation context before the first turn.
+#
+# Three matchers fire this hook:
+#   startup → fresh session. Inject branch + uncommitted summary +
+#             current feature (from feature_list.json) + golden-principles
+#             cap reminder. ~10-20 lines of structured state.
+#   resume  → user ran --resume / --continue. Same payload as startup,
+#             plus tail of PROGRESS.md so the model picks up where the
+#             last session stopped.
+#   compact → context was just compacted (mid-session). Pull the snapshot
+#             written by the PreCompact hook (.harness/compaction-snapshot.json)
+#             and re-inject it. Without this, the model loses everything
+#             that mattered about the current feature mid-compaction.
+#
+# The hook never blocks. Exit 0 + JSON to stdout is the *only* control
+# path that Claude reads.
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then
+    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
+  else
+    if [ -n "$2" ]; then
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
+    else
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+    fi
+  fi
+}
+
+SOURCE=""
+if have_jp; then
+  SOURCE=$(echo "$INPUT" | jp '.source // "startup"')
+fi
+
+# Build the additionalContext payload as plain text first, then JSON-escape
+# the whole thing at the end. Plain text is easier to read while iterating
+# on the hook, and Claude renders it as-is in the conversation view.
+CTX=""
+
+# 1. Branch + uncommitted count (always)
+if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+  BR=$(git branch --show-current 2>/dev/null || echo "(detached)")
+  COUNT=$(git status --short 2>/dev/null | wc -l | tr -d ' ')
+  CTX+="[harness] git: branch=$BR, uncommitted=$COUNT file(s)"$'\n'
+fi
+
+# 2. Current feature (from feature_list.json) — picks the first entry with
+#    passes=false so the model resumes the in-flight work, not a finished
+#    one. Skipped if file missing or jp unavailable.
+if [ -f feature_list.json ] && have_jp; then
+  FIRST_OPEN=$(echo '{}' | jp '.placeholder // empty' 2>/dev/null || true) # warm jp
+  # Use a transient script — we want { id, title } of first passes:false entry.
+  if have_jq; then
+    FEAT=$(jq -r 'first(.features[] | select(.passes == false)) | "[harness] feature: \(.id) — \(.title)"' \
+      feature_list.json 2>/dev/null || true)
+  else
+    # Node fallback path: emit (id, title) via a one-liner.
+    FEAT=$(node -e "
+      const f = JSON.parse(require('fs').readFileSync('feature_list.json', 'utf8'));
+      const open = (f.features || []).find(x => x.passes === false);
+      if (open) process.stdout.write('[harness] feature: ' + open.id + ' — ' + open.title);
+    " 2>/dev/null || true)
+  fi
+  if [ -n "$FEAT" ]; then
+    CTX+="$FEAT"$'\n'
+  fi
+fi
+
+# 3. PROGRESS.md tail (resume only — fresh sessions don't need it).
+if [ "$SOURCE" = "resume" ] && [ -f .harness/PROGRESS.md ]; then
+  TAIL=$(tail -3 .harness/PROGRESS.md 2>/dev/null | sed 's/^/  /')
+  if [ -n "$TAIL" ]; then
+    CTX+="[harness] PROGRESS.md tail:"$'\n'"$TAIL"$'\n'
+  fi
+fi
+
+# 4. Re-injection from compaction snapshot. The PreCompact hook writes
+#    .harness/compaction-snapshot.json before the model loses context.
+#    On `source: compact` we read it back and inline the most useful
+#    fields so the post-compaction model knows where it was.
+if [ "$SOURCE" = "compact" ] && [ -f .harness/compaction-snapshot.json ] && have_jp; then
+  SNAP_BRANCH=$(jp '.branch // empty' .harness/compaction-snapshot.json 2>/dev/null || true)
+  SNAP_SHA=$(jp '.sha // empty' .harness/compaction-snapshot.json 2>/dev/null || true)
+  SNAP_FEAT=$(jp '.feature // empty' .harness/compaction-snapshot.json 2>/dev/null || true)
+  SNAP_TS=$(jp '.compacted_at // empty' .harness/compaction-snapshot.json 2>/dev/null || true)
+  CTX+="[harness] post-compaction snapshot (taken $SNAP_TS):"$'\n'
+  [ -n "$SNAP_BRANCH" ] && CTX+="  branch=$SNAP_BRANCH"$'\n'
+  [ -n "$SNAP_SHA" ] && CTX+="  sha=$SNAP_SHA"$'\n'
+  [ -n "$SNAP_FEAT" ] && CTX+="  current-feature=$SNAP_FEAT"$'\n'
+fi
+
+# 5. Layer rule reminder (always — short, deterministic). Lets the model
+#    re-establish the forward-only rule without reading CLAUDE.md again.
+if [ -f harness.config.json ] && have_jp; then
+  LAYERS=$(jp '.domains[0].layers[]' harness.config.json 2>/dev/null | tr '\n' ' ' | sed 's/ $//' | tr ' ' '>')
+  LAYERS=${LAYERS//>/ → }
+  if [ -n "$LAYERS" ]; then
+    CTX+="[harness] layer rule (forward-only): $LAYERS"$'\n'
+  fi
+fi
+
+if [ -z "$CTX" ]; then
+  # Nothing meaningful to inject. Exit clean with no output — Claude
+  # treats this as "hook ran but had nothing to say".
+  exit 0
+fi
+
+# Emit the JSON envelope. Use Node's JSON.stringify for the escape so we
+# don't have to hand-roll \n / \" handling.
+if command -v node >/dev/null 2>&1; then
+  node -e "
+    const ctx = process.argv[1];
+    const out = { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: ctx } };
+    process.stdout.write(JSON.stringify(out));
+  " "$CTX"
+elif have_jq; then
+  jq -nc --arg ctx "$CTX" '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
+else
+  # Last-resort: emit as plain stdout. Claude Code accepts plain text from
+  # SessionStart hooks (it's treated as additionalContext too).
+  printf '%s' "$CTX"
+fi
+exit 0

package/src/templates/scripts/statusline.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// statusLine — single compact line into Claude Code's TUI status bar.
+// Reads stdin (Claude Code payload), augments with kit state, emits to
+// stdout. Failure mode: print nothing rather than crash.
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function safeRead(rel) {
+  try { return readFileSync(resolve(CWD, rel), "utf8"); }
+  catch { return null; }
+}
+function safeJSON(rel) {
+  const raw = safeRead(rel);
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+function readStdinSync() {
+  try { return readFileSync(0, "utf8"); } catch { return ""; }
+}
+
+function pieces() {
+  const out = [];
+  const lock = safeJSON(".harness/installed.json");
+  if (lock?.version) out.push(`{kit-v${lock.version}}`);
+
+  const features = safeJSON("feature_list.json");
+  if (features?.features && Array.isArray(features.features)) {
+    const open = features.features.find((f) => f.passes === false);
+    out.push(open ? `feat:${open.id}` : "feat:clean");
+  }
+
+  try {
+    const br = spawnSync("git", ["branch", "--show-current"], {
+      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    const status = spawnSync("git", ["status", "--short"], {
+      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (br.status === 0 && br.stdout.trim()) {
+      const dirty = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+      out.push(dirty > 0 ? `${br.stdout.trim()}(±${dirty})` : br.stdout.trim());
+    }
+  } catch { /* git not on PATH — skip */ }
+
+  const raw = readStdinSync();
+  let payload = null;
+  if (raw) { try { payload = JSON.parse(raw); } catch { /* ignore */ } }
+  if (payload?.context && typeof payload.context.percentage === "number") {
+    out.push(`ctx:${Math.round(payload.context.percentage)}%`);
+  }
+  if (payload?.cost && typeof payload.cost.total === "number") {
+    const v = payload.cost.total;
+    out.push(`$${v < 1 ? v.toFixed(2) : v.toFixed(1)}`);
+  }
+  return out;
+}
+
+const line = pieces().join(" • ");
+if (line) process.stdout.write(line);

package/src/templates/scripts/structural-test-on-edit.sh.hbs

@@ -7,18 +7,41 @@
 set -eo pipefail
 
 INPUT=$(cat)
-if ! command -v jq >/dev/null 2>&1; then
-  exit 0  # jq missing — silently skip rather than spuriously blocking
+
+# Resolve where this hook lives so we can find _lib/json-pick.mjs (Node-based
+# jq fallback). Pure-Node fallback removes the previous fail-open behaviour
+# when jq is missing — silently skipping the structural check on jq-less
+# environments (minimal CI, Windows without WSL+brew) was a known audit hole.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then jq -r "$1"
+  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+  fi
+}
+if ! have_jp; then
+  echo "[ahk] structural-test-on-edit: no JSON parser available (need jq OR node + scripts/_lib/json-pick.mjs)." >&2
+  exit 0
 fi
 
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+FILE=$(echo "$INPUT" | jp '.tool_input.file_path // empty')
 [ -z "$FILE" ] && exit 0
 
 # Only run on source files, and only inside the configured roots.
 case "$FILE" in
   *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)  ENGINE=ts ;;
   *.py)                               ENGINE=py ;;
-  *.rs)                               ENGINE=rust ;;
+  *.rs)                               ENGINE=node ;;
+  *.swift)                            ENGINE=node ;;
+  *.kt|*.kts)                         ENGINE=node ;;
   *)                                  exit 0 ;;
 esac
 
@@ -61,10 +84,10 @@ Fix the violation before continuing — do NOT disable the test.
 EOF
     exit 2
   fi
-elif [ "$ENGINE" = "rust" ]; then
-  # The Rust adapter is a Node script (`harness/structural-check.mjs`); it
-  # scans the whole workspace rather than a single file because the regex
-  # is cheap. If the script isn't present yet, exit 0 (graceful degrade).
+elif [ "$ENGINE" = "node" ]; then
+  # Node-based adapters (Rust / Swift / Kotlin). All ship the same
+  # harness/structural-check.mjs entry point. Workspace-wide scan because
+  # the regex is cheap. Missing script → graceful degrade.
   if [ ! -f harness/structural-check.mjs ]; then
     exit 0
   fi

package/src/templates/scripts/telemetry-on-skill.sh

@@ -4,23 +4,45 @@
 #
 # Used by harness:report to compute per-skill success rate, average duration,
 # and to surface drift over time.
+#
+# v0.7: migrated from `command -v jq` fail-open gate to the kit's jp() helper
+# so the telemetry record still gets written on jq-less CI / Windows. Without
+# the migration, telemetry quietly went dark anywhere jq wasn't installed.
 set -e
 
 INPUT=$(cat)
-if ! command -v jq >/dev/null 2>&1; then
-  exit 0  # jq missing — skip silently rather than spuriously blocking
-fi
 
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then jq -r "$1"
+  else node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+  fi
+}
+if ! have_jp; then exit 0; fi
+
+TOOL=$(echo "$INPUT" | jp '.tool_name // empty')
 [ "$TOOL" = "Skill" ] || exit 0
 
-SKILL=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+SKILL=$(echo "$INPUT" | jp '.tool_input.skill // empty')
 [ -z "$SKILL" ] && exit 0
 
 mkdir -p .harness
-LINE=$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-              --arg skill "$SKILL" \
-              --arg sha "$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')" \
-              '{ts: $ts, event: "skill_invoked", skill: $skill, sha: $sha}')
-echo "$LINE" >> .harness/telemetry.jsonl
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+
+# Compose JSONL line by hand — same shape as the previous jq-built record.
+# Quoting via printf '%s' so embedded spaces in skill names don't break the
+# line. Skill names are constrained to `[a-z0-9-]+` upstream so we don't
+# need full JSON escaping here.
+printf '{"ts":"%s","event":"skill_invoked","skill":"%s","sha":"%s"}\n' \
+  "$TS" "$SKILL" "$SHA" >> .harness/telemetry.jsonl
 exit 0

package/src/templates/scripts/userprompt-guard.sh.hbs

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — denies prompt patterns that undo harness safety
+# rules. Hard guardrail replacing soft CLAUDE.md guidance.
+#
+# Denied patterns:
+#   1. "ignore previous instructions" / "disregard above"
+#   2. "disable the structural test" / "skip the structural check"
+#   3. "bypass the (Stop|PreToolUse|hook) (rules?|checks?)"
+#   4. "remove the .harness" / "delete .harness directory"
+#   5. "set disableAllHooks: true"
+#
+# Escape hatch: AHK_ALLOW_BYPASS=1 logs to .harness/bypass.log + lets through.
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then
+    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
+  else
+    if [ -n "$2" ]; then
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
+    else
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+    fi
+  fi
+}
+
+if ! have_jp; then
+  exit 0
+fi
+
+PROMPT=$(echo "$INPUT" | jp '.prompt // empty')
+[ -z "$PROMPT" ] && exit 0
+
+LOWER=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+REASON=""
+
+if printf '%s' "$LOWER" | grep -qE '(ignore|disregard|forget) (the|all|any|your|previous|prior|above)'; then
+  REASON="Prompts that ask Claude to ignore previous instructions defeat the harness's safety rules. State the actual change you need; the structural test and Stop checklist are deterministic and stay enforced."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE '(disable|skip|turn off|bypass) (the )?(structural|layer|stop hook|stop check|precompletion|lint|harness:check)'; then
+  REASON="Disabling the structural test or Stop checklist is not how the kit is meant to be used. Fix the violation in code, or open an ADR if the layer rule itself needs to change."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE 'bypass (the )?(pretooluse|posttooluse|sessionstart|sessionend|precompact|hook|hooks|rules?|checks?)'; then
+  REASON="Prompts that ask to bypass kit hooks defeat their purpose. If a specific hook is wrong for your workflow, edit it explicitly with a commit message; do not phrase the request as 'bypass'."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE '(remove|delete|wipe|rm -rf|drop) (the )?(\.harness|\.claude)( |/|$|\.)'; then
+  REASON="Removing .harness/ or .claude/ deletes the kit's lockfile, structural baseline, skills, agents, and hooks. Use 'agent-harness-kit upgrade' to refresh installed files; do not delete by hand."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE 'disableallhooks.*true'; then
+  REASON="disableAllHooks: true defeats every protection the kit installs. Remove specific hooks explicitly if needed; do not flip the master switch."
+fi
+
+if [ -z "$REASON" ]; then
+  exit 0
+fi
+
+if [ "${AHK_ALLOW_BYPASS:-}" = "1" ]; then
+  mkdir -p .harness
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+  ESCAPED_PROMPT=${PROMPT//$'\n'/ }
+  ESCAPED_PROMPT=${ESCAPED_PROMPT//\"/\\\"}
+  printf '{"ts":"%s","sha":"%s","bypass":"AHK_ALLOW_BYPASS","reason":"%s","prompt":"%s","hook":"UserPromptSubmit"}\n' \
+    "$TS" "$SHA" "${REASON//\"/\\\"}" "$ESCAPED_PROMPT" >> .harness/bypass.log
+  exit 0
+fi
+
+if command -v node >/dev/null 2>&1; then
+  node -e "
+    const reason = process.argv[1];
+    const out = { decision: 'block', reason };
+    process.stdout.write(JSON.stringify(out));
+  " "$REASON"
+elif have_jq; then
+  jq -nc --arg r "$REASON" '{decision:"block", reason:$r}'
+else
+  echo "$REASON" >&2
+  exit 2
+fi
+exit 0

package/src/templates/.claude/hooks/hooks.json.hbs

@@ -1,39 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-hooks.json",
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash scripts/structural-test-on-edit.sh",
-            "timeout": 30
-          }
-        ]
-      },
-      {
-        "matcher": "Skill",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash scripts/telemetry-on-skill.sh",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash scripts/precompletion-checklist.sh",
-            "timeout": 20
-          }
-        ]
-      }
-    ]
-  }
-}