agent-harness-kit 0.6.0 → 0.7.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/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/.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
-          }
-        ]
-      }
-    ]
-  }
-}