@delorenj/pjangler 1.1.5 → 1.2.2

package/templates/commonproject/template/.agents/hooks/hindsight/hindsight-recall.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# Claude Code UserPromptSubmit hook: recall Hindsight memories.
+# Reads JSON from stdin (Claude hook contract), outputs context to stdout.
+# Gracefully exits if hindsight CLI is not installed.
+set -euo pipefail
+
+HS_BIN="${HOME}/.local/bin/hindsight"
+
+# Parse Claude's JSON stdin
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // .message // empty' 2>/dev/null || echo "")
+
+# Load journal telemetry helper (no-ops gracefully on its own)
+# shellcheck source=lib/hindsight-journal.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-journal.sh"
+SESSION_ID=$(journal_session_id_from "$INPUT")
+PROMPT_FIRST120=$(printf '%s' "$PROMPT" | head -c 120)
+
+# Skip if hindsight CLI is missing — but still log the skip for the journal.
+if [[ ! -x "$HS_BIN" ]]; then
+  journal_log "$SESSION_ID" "$(jq -nc \
+    --arg p "$PROMPT_FIRST120" \
+    --argjson plen ${#PROMPT} \
+    '{event:"recall_skipped", reason:"hindsight_binary_missing", prompt_len:$plen, prompt_first120:$p}')"
+  exit 0
+fi
+
+# Skip empty or noisy prompts — but still log the skip.
+if [[ -z "$PROMPT" ]] || [[ ${#PROMPT} -lt 24 ]]; then
+  journal_log "$SESSION_ID" "$(jq -nc \
+    --arg p "$PROMPT_FIRST120" \
+    --argjson plen ${#PROMPT} \
+    '{event:"recall_skipped", reason:(if $plen==0 then "empty_prompt" else "prompt_under_min_length" end), min_length:24, prompt_len:$plen, prompt_first120:$p}')"
+  exit 0
+fi
+
+# Detect bank via shared resolver (GitHub remote name → repo basename → "general")
+# shellcheck source=lib/hindsight-bank.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-bank.sh"
+BANK=$(resolve_bank)
+
+# Per-source line caps keep total bounded without starving later layers.
+PRIMARY_LINES="${HINDSIGHT_PRIMARY_LINES:-30}"
+FALLBACK_LINES="${HINDSIGHT_FALLBACK_LINES:-15}"
+LINKED_LINES_PER_BANK="${HINDSIGHT_LINKED_LINES:-12}"
+
+recall_cli() {
+  NO_COLOR=1 \
+  CLICOLOR=0 \
+  CLICOLOR_FORCE=0 \
+  FORCE_COLOR=0 \
+  TERM=dumb \
+  COLORTERM= \
+  RICH_NO_COLOR=1 \
+  HINDSIGHT_NO_COLOR=1 \
+  HINDSIGHT_NO_SPINNER=1 \
+  HINDSIGHT_DISABLE_SPINNER=1 \
+    "$HS_BIN" memory recall "$@"
+}
+
+sanitize_recall_output() {
+  if command -v perl >/dev/null 2>&1; then
+    perl -pe 's/\e\][^\a]*(?:\a|\e\\)//g; s/\e\[[0-?]*[ -\/]*[@-~]//g; s/[^\r\n]*\r//g; s/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]//g'
+  else
+    sed -E $'s|\x1B\\[[0-?]*[ -/]*[@-~]||g; s|\x1B\\][^\a]*(\a|\x1B\\\\)||g' | tr '\r' '\n'
+  fi
+}
+
+cap() { sanitize_recall_output | sed '/^[[:space:]]*$/d' | head -n "$1"; }
+
+# Primary bank recall
+MEMORIES=$(recall_cli "$BANK" "$PROMPT" 2>/dev/null | cap "$PRIMARY_LINES" || echo "")
+
+# Fallback to general if primary bank is different
+FALLBACK=""
+if [[ "$BANK" != "general" ]]; then
+  FALLBACK=$(recall_cli "general" "$PROMPT" 2>/dev/null | cap "$FALLBACK_LINES" || echo "")
+fi
+
+# Always-on global banks — cross-project knowledge that should surface
+# regardless of which repo we're in (homelab routing, infra conventions, etc).
+# Override via HINDSIGHT_GLOBAL_BANKS="infra dotfiles ..." (space-separated).
+GLOBAL_BANKS="${HINDSIGHT_GLOBAL_BANKS:-infra}"
+GLOBAL=""
+for gb in $GLOBAL_BANKS; do
+  [[ "$gb" == "$BANK" || "$gb" == "general" ]] && continue
+  gout=$(recall_cli "$gb" "$PROMPT" --budget low 2>/dev/null | cap "$FALLBACK_LINES" || echo "")
+  if [[ -n "$gout" ]]; then
+    GLOBAL="${GLOBAL}
+<!-- global-bank: $gb -->
+${gout}"
+  fi
+done
+
+# Linked-bank fanout via Dream's graph cache.
+# Cache path/threshold/fanout cap are env-tunable; set HINDSIGHT_FANOUT=0 to disable.
+LINKED=""
+GRAPH_CACHE="${HINDSIGHT_DREAM_GRAPH:-${HOME}/.hindsight/dream/bank-graph.json}"
+FANOUT_ENABLED="${HINDSIGHT_FANOUT:-1}"
+FANOUT_MAX="${HINDSIGHT_FANOUT_MAX:-2}"
+FANOUT_MIN_SCORE="${HINDSIGHT_FANOUT_MIN_SCORE:-0.1}"
+
+LINKED_BANKS_USED=()
+if [[ "$FANOUT_ENABLED" != "0" ]] && [[ -f "$GRAPH_CACHE" ]] && command -v jq &>/dev/null; then
+  LINKED_BANKS=$(jq -r --arg b "$BANK" --argjson min "$FANOUT_MIN_SCORE" --argjson n "$FANOUT_MAX" \
+    '(.graph[$b] // []) | map(select(.score >= $min)) | .[:$n] | .[].bank' \
+    "$GRAPH_CACHE" 2>/dev/null || true)
+  for linked in $LINKED_BANKS; do
+    [[ -z "$linked" || "$linked" == "$BANK" || "$linked" == "general" ]] && continue
+    out=$(recall_cli "$linked" "$PROMPT" --budget low --max-tokens 1024 2>/dev/null | cap "$LINKED_LINES_PER_BANK" || echo "")
+    if [[ -n "$out" ]]; then
+      LINKED="${LINKED}
+<!-- linked-bank: $linked -->
+${out}"
+      LINKED_BANKS_USED+=("$linked")
+    fi
+  done
+fi
+
+ALL=""
+[[ -n "$MEMORIES" ]] && ALL="${MEMORIES}"
+[[ -n "$FALLBACK" ]] && ALL="${ALL}
+${FALLBACK}"
+[[ -n "$GLOBAL" ]] && ALL="${ALL}
+${GLOBAL}"
+[[ -n "$LINKED" ]] && ALL="${ALL}
+${LINKED}"
+
+# Final overall guard so we never dump unbounded recall output.
+ALL=$({ printf '%s\n' "$ALL" | sanitize_recall_output | sed '/^[[:space:]]*$/d' | head -100; } || true)
+
+if [[ -n "$ALL" ]]; then
+  printf '\n'
+  printf '<!-- hindsight:recall bank=%s -->\n' "$BANK"
+  printf '%s\n' "$ALL"
+  printf '<!-- /hindsight:recall -->\n'
+fi
+
+# --- Journal telemetry: record what we asked and what we got back ---
+count_nonempty() { printf '%s\n' "$1" | awk 'NF{c++} END{print c+0}'; }
+primary_lines=$(count_nonempty "$MEMORIES")
+fallback_lines=$(count_nonempty "$FALLBACK")
+global_lines=$(count_nonempty "$GLOBAL")
+linked_lines=$(count_nonempty "$LINKED")
+total_lines=$(count_nonempty "$ALL")
+total_chars=${#ALL}
+# Empty array if no linked banks; otherwise JSON array of names.
+if [[ ${#LINKED_BANKS_USED[@]} -eq 0 ]]; then
+  linked_json='[]'
+else
+  linked_json=$(printf '%s\n' "${LINKED_BANKS_USED[@]}" | jq -R . | jq -sc .)
+fi
+
+journal_log "$SESSION_ID" "$(jq -nc \
+  --arg bank "$BANK" \
+  --arg p "$PROMPT_FIRST120" \
+  --argjson plen ${#PROMPT} \
+  --argjson pl "$primary_lines" \
+  --argjson fl "$fallback_lines" \
+  --argjson gl "$global_lines" \
+  --argjson ll "$linked_lines" \
+  --argjson tl "$total_lines" \
+  --argjson tc "$total_chars" \
+  --argjson linked "$linked_json" \
+  --arg global "$GLOBAL_BANKS" \
+  '{
+     event: "recall",
+     bank: $bank,
+     prompt_len: $plen,
+     prompt_first120: $p,
+     primary_lines: $pl,
+     fallback_lines: $fl,
+     global_lines: $gl,
+     linked_lines: $ll,
+     total_lines: $tl,
+     total_chars: $tc,
+     linked_banks: $linked,
+     global_banks: $global,
+     returned_anything: ($tl > 0)
+   }')"

package/templates/commonproject/template/.agents/hooks/hindsight/hindsight-retain.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Claude Code PostToolUse hook: retain file edits in Hindsight.
+# Reads JSON from stdin (Claude hook contract), fire-and-forget.
+# Gracefully exits if hindsight CLI is not installed.
+set -euo pipefail
+
+HS_BIN="${HOME}/.local/bin/hindsight"
+if [[ ! -x "$HS_BIN" ]]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || echo "")
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null || echo "")
+CONTENT_LEN=${#CONTENT}
+
+if [[ $CONTENT_LEN -lt 50 ]]; then
+  exit 0
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [[ -n "$REPO_ROOT" ]]; then
+  REL_PATH="${FILE_PATH#$REPO_ROOT/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+EXT="${FILE_PATH##*.}"
+SNIPPET=$(echo "$CONTENT" | head -5 | tr '\n' ' ' | cut -c1-200)
+
+# Detect bank via shared resolver (GitHub remote name → repo basename → "general")
+# shellcheck source=lib/hindsight-bank.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-bank.sh"
+BANK=$(resolve_bank)
+
+# Load journal telemetry helper
+# shellcheck source=lib/hindsight-journal.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-journal.sh"
+SESSION_ID=$(journal_session_id_from "$INPUT")
+
+RETAIN_TEXT="Edited ${REL_PATH} (${EXT}): ${SNIPPET}"
+
+# Fire-and-forget retain
+"$HS_BIN" memory retain "$BANK" "$RETAIN_TEXT" \
+  --context "code-edit" &>/dev/null &
+
+# Journal telemetry: record what we retained
+journal_log "$SESSION_ID" "$(jq -nc \
+  --arg bank "$BANK" \
+  --arg file "$REL_PATH" \
+  --arg ext "$EXT" \
+  --arg ctx "code-edit" \
+  --arg text "$RETAIN_TEXT" \
+  --arg snippet "$SNIPPET" \
+  --argjson len $CONTENT_LEN \
+  --argjson auto true \
+  '{
+     event: "retain",
+     bank: $bank,
+     context: $ctx,
+     file: $file,
+     ext: $ext,
+     content_len: $len,
+     snippet: $snippet,
+     retained_text: $text,
+     source: "auto_posttooluse"
+   }')"
+
+exit 0

package/templates/commonproject/template/.agents/hooks/hindsight/hindsight-session-end.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Claude Code Stop hook: capture session summary in Hindsight + write journal entry.
+# Gracefully exits if hindsight CLI is not installed.
+#
+# Hardening notes (2026-05-11):
+#  - Every external call is wrapped in `timeout` so a wedged Hindsight API
+#    (or any other downstream) can't anchor the hook beyond a known bound.
+#  - The journal-writer pipe was bugged: `printf ... | setsid CMD </dev/null`
+#    had its pipe data discarded because the explicit /dev/null redirect on
+#    the setsid command overrode the pipe. Fixed by writing $INPUT to a temp
+#    file and feeding it via `< $tmp` (no pipe → no override).
+#  - Claude Code's hook contract waits for the foreground process AND any
+#    inherited stdio fds to close. setsid+nohup+disown handles process
+#    detachment; the explicit fd redirects (now ordered correctly) close out
+#    the parent's pipe so the harness can return immediately.
+set -uo pipefail
+
+HS_BIN="${HOME}/.local/bin/hindsight"
+
+# Stdin holds the Stop hook JSON ({session_id, transcript_path, cwd, ...}).
+# Persist it to a temp file so we can deliver it to a detached child via
+# fd redirect (not a pipe — see header note).
+INPUT_TMP=$(mktemp -t hindsight-stop-input.XXXXXX)
+cat > "$INPUT_TMP" 2>/dev/null || echo "{}" > "$INPUT_TMP"
+
+# Best-effort cleanup. The journal writer reads $INPUT_TMP early in its run,
+# so a short delay before unlinking is safe; we just trust the OS to GC the
+# inode after both readers exit. No trap needed.
+
+# 1. Write the journal entry (uses per-session telemetry log).
+#    Fully daemonize: setsid + nohup + closed std fds so the writer survives
+#    after this hook returns. The reflect step can take 30+ seconds, and
+#    Claude Code reaps the hook's process group when the foreground command
+#    returns — without setsid the writer gets SIGHUP'd mid-call.
+JOURNAL_WRITER="$(dirname "${BASH_SOURCE[0]}")/hindsight-journal-write.sh"
+if [[ -x "$JOURNAL_WRITER" ]]; then
+  setsid nohup "$JOURNAL_WRITER" \
+    < "$INPUT_TMP" \
+    > /dev/null 2>&1 &
+  disown 2>/dev/null || true
+fi
+
+# 2. Record a session-end marker memory (legacy behavior). Same detach pattern.
+#    Wrapped in `timeout 3` defensively even though it's already detached:
+#    if a future change ever runs this synchronously, the bound still holds.
+if [[ -x "$HS_BIN" ]]; then
+  # shellcheck source=lib/hindsight-bank.sh
+  source "$(dirname "${BASH_SOURCE[0]}")/lib/hindsight-bank.sh"
+  BANK=$(resolve_bank)
+  setsid nohup timeout 30 "$HS_BIN" memory retain "$BANK" \
+    "Session ended at $(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --context "session-summary" \
+    < /dev/null > /dev/null 2>&1 &
+  disown 2>/dev/null || true
+fi
+
+exit 0

package/templates/commonproject/template/.agents/hooks/hindsight/lib/hindsight-bank.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Shared bank resolver for Hindsight hooks.
+# Source this file, then call: BANK=$(resolve_bank)
+#
+# Resolution order (first non-empty wins):
+#   1. .hindsight/bank file in repo root (explicit override; written by Dream agent or by hand)
+#   2. HINDSIGHT_BANK env var (per-shell override; useful for ad-hoc routing)
+#   3. GitHub remote repo name (origin) e.g. "delorenj/claude-runtime" -> "claude-runtime"
+#   4. Local repo root basename (fallback when no remote configured)
+#   5. "general" (when not in a git repo at all)
+#
+# The override file format is a single line containing the bank name. Whitespace
+# and a trailing newline are stripped. Lines starting with '#' are treated as
+# comments and ignored.
+
+resolve_bank() {
+  local url name root override
+
+  root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+
+  # 1. Repo-local override file
+  if [[ -n "$root" && -f "$root/.hindsight/bank" ]]; then
+    override=$(grep -v '^[[:space:]]*#' "$root/.hindsight/bank" 2>/dev/null \
+                 | head -n1 \
+                 | tr -d '[:space:]')
+    if [[ -n "$override" ]]; then
+      echo "$override"
+      return
+    fi
+  fi
+
+  # 2. Env var override
+  if [[ -n "${HINDSIGHT_BANK:-}" ]]; then
+    echo "$HINDSIGHT_BANK"
+    return
+  fi
+
+  # 3. GitHub remote name
+  url=$(git remote get-url origin 2>/dev/null || true)
+  if [[ -n "$url" ]]; then
+    url="${url%.git}"
+    name="${url##*/}"
+    if [[ -n "$name" ]]; then
+      echo "$name"
+      return
+    fi
+  fi
+
+  # 4. Repo root basename
+  if [[ -n "$root" ]]; then
+    basename "$root"
+    return
+  fi
+
+  # 5. Final fallback
+  echo "general"
+}

package/templates/commonproject/template/.agents/hooks/hindsight/lib/hindsight-journal.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Shared telemetry-logging helpers for the Hindsight journal pipeline.
+#
+# Usage:
+#   source "~/.agents/hooks/lib/hindsight-journal.sh"
+#   journal_log "$SESSION_ID" '{"event":"recall","bank":"foo",...}'
+#
+# Each session's events are appended to a per-session JSONL file:
+#   ~/.agents/journal/sessions/<session_id>.jsonl
+#
+# The Stop hook reads this file at session-end to synthesize the journal entry,
+# then the file is left in place (for forensics) or pruned by a separate sweeper.
+
+HS_JOURNAL_DIR="${HS_JOURNAL_DIR:-${HOME}/.agents/journal}"
+HS_JOURNAL_SESSIONS_DIR="${HS_JOURNAL_DIR}/sessions"
+
+# Append one event (a JSON object string) to the current session's log.
+# Silently no-ops if session_id is empty or jq is unavailable.
+journal_log() {
+  local session_id="$1"
+  local event_json="$2"
+
+  [[ -z "$session_id" ]] && return 0
+  [[ -z "$event_json" ]] && return 0
+  command -v jq >/dev/null 2>&1 || return 0
+
+  mkdir -p "$HS_JOURNAL_SESSIONS_DIR" 2>/dev/null || return 0
+
+  local log_file="${HS_JOURNAL_SESSIONS_DIR}/${session_id}.jsonl"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # Validate + inject timestamp; drop the event silently if it isn't valid JSON.
+  printf '%s' "$event_json" |
+    jq -c --arg ts "$ts" '. + {ts: $ts}' >>"$log_file" 2>/dev/null ||
+    true
+}
+
+# Extract session_id from Claude Code hook JSON on stdin.
+# Echoes the id (or empty string). The caller is expected to have already cat'd stdin.
+journal_session_id_from() {
+  local input="$1"
+  command -v jq >/dev/null 2>&1 || {
+    echo ""
+    return 0
+  }
+  echo "$input" | jq -r '.session_id // empty' 2>/dev/null || echo ""
+}

package/templates/commonproject/template/.agents/hooks/hooks.master.json

@@ -0,0 +1,97 @@
+{
+  "$comment": "SINGLE SOURCE OF TRUTH for this repo's project-scoped agent hooks. Hand-edit ONLY this file, then run `mise run hooks-sync` (or re-cd into the repo) to regenerate every per-agent config. Generated files are NOT hand-edited. Pattern: the /ssot-fanout skill. See .agents/hooks/README.md.",
+  "version": 1,
+  "marker": "project-agent-hooks",
+  "hooks": [
+    {
+      "id": "skill-check-reminder",
+      "lifecycle": "user_prompt",
+      "script": "reminder-for-skill-check.sh",
+      "timeout_s": 3,
+      "reads_stdin": false,
+      "description": "Inject a project-skills + BMAD-recap reminder into each prompt."
+    },
+    {
+      "id": "hindsight-recall",
+      "lifecycle": "user_prompt",
+      "script": "hindsight/hindsight-recall.sh",
+      "timeout_s": 5,
+      "reads_stdin": true,
+      "description": "Recall Hindsight memories for the prompt (no-ops gracefully if the hindsight CLI is absent)."
+    },
+    {
+      "id": "hindsight-retain",
+      "lifecycle": "post_tool",
+      "script": "hindsight/hindsight-retain.sh",
+      "matcher": "Write|Edit|MultiEdit",
+      "timeout_s": 5,
+      "reads_stdin": true,
+      "description": "Retain file edits into Hindsight after Write/Edit/MultiEdit."
+    },
+    {
+      "id": "hindsight-session-end",
+      "lifecycle": "session_end",
+      "script": "hindsight/hindsight-session-end.sh",
+      "timeout_s": 5,
+      "reads_stdin": true,
+      "description": "Capture a session summary + write a Hindsight journal entry on stop."
+    }
+  ],
+  "agents": {
+    "claude": {
+      "enabled": true,
+      "dialect": "claude_settings",
+      "config_target": ".claude/settings.json",
+      "base_dir": "$CLAUDE_PROJECT_DIR/.agents/hooks",
+      "timeout_unit": "s",
+      "owns_hooks_key": true,
+      "lifecycle_events": {
+        "user_prompt": "UserPromptSubmit",
+        "post_tool": "PostToolUse",
+        "session_end": "Stop"
+      },
+      "notes": "Committed to the repo, so every dev gets these automatically with NO bootstrap. Claude expands $CLAUDE_PROJECT_DIR in hook commands at runtime. sync owns the entire `hooks` key of this file."
+    },
+    "codex": {
+      "enabled": true,
+      "dialect": "codex_hooks",
+      "config_target": "~/.codex/hooks.json",
+      "base_dir": "{repo}/.agents/hooks",
+      "timeout_unit": "ms",
+      "lifecycle_events": {
+        "user_prompt": "UserPromptSubmit",
+        "post_tool": "PostToolUse",
+        "session_end": "Stop"
+      },
+      "notes": "Codex has no project-scoped hook file, so sync INJECTS absolute-path entries into the per-user ~/.codex/hooks.json on `mise enter` and REMOVES them on `mise leave`. Idempotent; backs up to ~/.codex/hooks.json.caf-bak before first write. Set CAF_HOOKS_SKIP_CODEX=1 to opt out (e.g. if you already run these hooks globally)."
+    },
+    "hermes": {
+      "enabled": true,
+      "dialect": "hermes_config",
+      "config_target": "agents/hermes/pm/runtime/config.yaml",
+      "allowlist_target": "agents/hermes/pm/runtime/shell-hooks-allowlist.json",
+      "adapter": "hermes/hindsight-hook.sh",
+      "runner": "bash {repo}/.agents/hooks/hermes/hindsight-hook.sh",
+      "timeout_s": 5,
+      "lifecycle_events": {
+        "post_tool": "post_tool_call",
+        "session_end": "on_session_end"
+      },
+      "notes": "Hermes runs hooks shell=False (argv) with the payload as JSON on stdin and requires commands in shell-hooks-allowlist.json. It has NO user-prompt event, so hindsight-recall is not wired. Instead of the Claude-shaped scripts, Hermes uses the ADAPTER (hermes/hindsight-hook.sh) which translates the Hermes payload and pins the project bank (repo basename) (resolve_bank from the runtime cwd would resolve to the PM submodule). sync merges into the per-deployment runtime config.yaml + allowlist (idempotent, backed up, skipped if the runtime is absent). Disable per-dev via local.json disabled_agents:[\"hermes\"]."
+    },
+    "kimi": {
+      "enabled": true,
+      "dialect": "kimi_config",
+      "config_target": "~/.kimi-code/config.toml",
+      "config_home_env": "KIMI_CODE_HOME",
+      "base_dir": "{repo}/.agents/hooks",
+      "timeout_unit": "s",
+      "lifecycle_events": {
+        "user_prompt": "UserPromptSubmit",
+        "post_tool": "PostToolUse",
+        "session_end": "Stop"
+      },
+      "notes": "Kimi Code CLI hooks live in the per-user ~/.kimi-code/config.toml (KIMI_CODE_HOME overrides) as a `hooks` array of {event,command,matcher?,timeout}. Kimi is Claude-compatible: identical event names, payload {hook_event_name,session_id,cwd,prompt} / {tool_name,tool_input} on stdin, shell:true commands, timeout in SECONDS, edit tools named Write/Edit. So it reuses the SAME scripts (guard-wrapped) as claude/codex. No project-local config.toml exists, so sync INJECTS a sentinel-bounded [[hooks]] block on enter and removes it on leave (idempotent text-merge, backs up to config.toml.caf-bak). Disable per-dev via local.json disabled_agents:[\"kimi\"]."
+    }
+  }
+}

package/templates/commonproject/template/.agents/hooks/lib/hook-guard.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Per-dev runtime opt-out wrapper for a single hook.
+#
+#   hook-guard.sh <hook-id> <command> [args...]
+#
+# If <hook-id> is listed in .agents/local.json `.hooks.disabled[]`, exits 0
+# WITHOUT running the command (silent success — no "hook failed" noise in the
+# agent). Otherwise execs the command, passing stdin straight through so the
+# real hook still receives its JSON payload.
+#
+# This is how a dev disables an individual hook even for Claude, whose hook
+# config is committed (and therefore the same for everyone): the committed
+# command is the guarded form, and the guard consults each dev's local.json at
+# runtime.
+set -uo pipefail
+
+HOOK_ID="${1:-}"
+shift || true
+
+# shellcheck source=local-config.sh
+source "$(dirname "${BASH_SOURCE[0]}")/local-config.sh"
+
+if [[ -n "$HOOK_ID" ]] && hook_disabled "$HOOK_ID"; then
+  exit 0
+fi
+
+# Nothing to run (defensive) — succeed quietly.
+[[ $# -eq 0 ]] && exit 0
+
+exec "$@"

package/templates/commonproject/template/.agents/hooks/lib/local-config.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Sourceable helpers for per-dev `.agents/local.json` overrides.
+#
+# Source this, then call:
+#   hook_disabled  <hook-id>     # true if .hooks.disabled[] contains the id
+#   agent_disabled <agent>       # true if .hooks.disabled_agents[] contains the agent
+#   skill_disabled <skill-name>  # true if .skills.disabled[] contains the name
+#
+# All FAIL OPEN (return 1 = "not disabled") when `.agents/local.json` or `jq` is
+# absent, so a missing/garbled local config can never silently kill hooks/skills.
+#
+# `.agents/local.json` is gitignored — each dev owns their own. See
+# `.agents/local.example.json` for the schema.
+
+# Repo root, resolved from this lib's location (.agents/hooks/lib/ -> ../../..).
+_caf_local_json() {
+  local d
+  d="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." 2>/dev/null && pwd)" || return 1
+  printf '%s/.agents/local.json' "$d"
+}
+
+# _caf_listed <jq-array-path> <value>  -> 0 if value is in the array.
+_caf_listed() {
+  local jq_path="$1" val="$2" f
+  f="$(_caf_local_json)" || return 1
+  [[ -f "$f" ]] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  jq -e --arg v "$val" "((${jq_path} // []) | index(\$v)) != null" "$f" >/dev/null 2>&1
+}
+
+hook_disabled()  { _caf_listed '.hooks.disabled' "$1"; }
+agent_disabled() { _caf_listed '.hooks.disabled_agents' "$1"; }
+skill_disabled() { _caf_listed '.skills.disabled' "$1"; }
+
+# True if the dev opted to let their GLOBAL agent system (~/.agents/skills) provide
+# any overlapping skill, so the project linker should skip it (no duplicates).
+# Teammates with no global layer omit this and inherit the full project set.
+skills_defer_to_global() {
+  local f
+  f="$(_caf_local_json)" || return 1
+  [[ -f "$f" ]] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  jq -e '.skills.defer_to_global == true' "$f" >/dev/null 2>&1
+}
+
+# True if <skill-name> is provided by the global agent SSOT. `-e` follows the
+# ~/.agents/skills symlink (-> skillex/skill-sets/global) and its entries.
+skill_is_global() {
+  local name="$1" gdir="${AGENTS_GLOBAL_SKILLS_DIR:-$HOME/.agents/skills}"
+  [[ -e "${gdir}/${name}" ]]
+}

package/templates/commonproject/template/.agents/hooks/reminder-for-skill-check.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# UserPromptSubmit hook (PROJECT-SCOPED).
+#
+# Nudges the agent to check this project's skills and resume BMAD context.
+# Portable across developers: the project's skills directory is resolved
+# RELATIVE to this script's location, not a hardcoded home path — so the same
+# committed copy works for every dev who clones the repo.
+#
+# stdout from a UserPromptSubmit hook is injected into the prompt as context.
+set -uo pipefail
+
+# This script lives at <repo>/.agents/hooks/reminder-for-skill-check.sh
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${HOOK_DIR}/../.." && pwd)"
+SKILLS_DIR="${PROJECT_ROOT}/.agents/skills"
+
+echo "⚡ REMINDER: Before starting, check if any skills in ${SKILLS_DIR}/ are relevant to this request."
+echo " - If this project uses the BMAD method (a ./_bmad* folder exists) start the session with a brief recap of where the last session left off and suggest the next logical step. If there are options, lay them out, think it through, then offer your recommendation. ⚡"
+echo "> NOTE: Treat docs with a grain of salt — this is a fast-moving solo project, so stale data is likely. Gauge confidence with recency: run 'llr' (alias for 'fdfind --type f --hidden --exclude .git -X ls -lt --time=ctime -r --color=auto') and use mtime as a compass correlating mutation-recency with local relevance."
+exit 0