karajan-code 4.11.0 → 4.13.0

package/README.md

@@ -24,12 +24,16 @@
 
 Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
-- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk.
+- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. The install wires it as a native MCP tool (`kj_rag_query`) so querying the index is the agent's cheapest path. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk. A distilled engineering canon rides along: `kj rag query --library` serves pattern cards (when it applies, when it does NOT, the canonical citation) so plans name a greenfield alternative instead of following the legacy line by inertia.
 - **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
 - **Tests prove behavior** — the failing test exists first; the suite is never left red.
 - **Deterministic first, then cross-AI review** — `kj review --staged` runs SonarQube on the changed files before any AI opinion (BLOCKER/CRITICAL reject on the spot), then binds a verdict from a *different* AI to the sha256 of the exact diff — stamped with the workspace it ran from. Without an approved verdict, **the commit does not enter** (pre-commit gate).
 - **A third AI arbitrates disputes** — `kj solomon` rules when brain and reviewer disagree. Security findings are never overridable — not even by arbitration.
 - **Branch first, lanes for parallel work** — the base branch only moves through atomic PRs; `kj worktree start|list|done` gives each concurrent task its own isolated lane.
+- **Least privilege for agents** — spawned agent subprocesses receive an env allowlist (their own CLI's auth, never your cloud keys or registry tokens), and `kj check` inventories every MCP the project can reach, flagging what appeared since the last check. Sensitive-surface tasks self-invoke `kj audit --security` — a zero-token pass (prompt-injection over the agent-context files + OSV + Semgrep + Sonar) — and remediate before review.
+- **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
+- **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
+- **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 
@@ -64,6 +68,12 @@ Requires git and at least one AI agent CLI — two enables cross-AI review; thre
 
 Full method: [Work with your agent](https://karajancode.com/docs/v4/working-with-your-agent/) · [The gates](https://karajancode.com/docs/v4/gates/) · [Command reference](https://karajancode.com/docs/v4/commands/).
 
+## Guarantee levels: governed vs supervised
+
+Karajan **governs** any agent with git gates — the false green is structurally impossible no matter who writes, because the gates live in the repository, not in the agent's goodwill. On top of that, the **Karajan Sentinel** adds **supervision inside the turn**: `kj harden` wires deterministic hooks into the harness — one records the method state of the session as tools run (sources edited vs tests touched, escapes used), and a Stop hook blocks the agent from ending its turn while violations are open: sources edited on the base branch, a branch without a card, code without a single test touched. Every block states the exact violation and its remediation; `kj sentinel status` shows what the supervisor sees. It fails open — and says so — rather than ever hanging a session, and every `KJ_ALLOW_*` escape is recorded.
+
+Synchronous blocking hooks exist today only in Claude Code. That makes the supported setup explicit: **to guarantee a harness that controls the LLM, use Claude Code as the host** — Claude writes, Codex reviews (a review subprocess needs no hooks), and a third CLI arbitrates when available. On any other host Karajan still governs at the full git-gate level and tells you which level is active — it never pretends a supervision it cannot enforce.
+
 ## Headless mode
 
 The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).

package/docs/README.es.md

@@ -16,12 +16,16 @@
 
 Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
-- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk.
+- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. La instalación lo cablea como herramienta MCP nativa (`kj_rag_query`), de modo que consultar el índice sea el camino más barato del agente. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk. Y viaja con un canon de ingeniería destilado: `kj rag query --library` sirve fichas de patrón (cuándo aplica, cuándo NO, la cita canónica) para que los planes nombren una alternativa greenfield en vez de seguir la línea del legacy por inercia.
 - **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
 - **Los tests prueban el comportamiento** — el test que falla existe primero; la suite nunca se queda en rojo.
 - **Determinista primero, luego revisión IA-cruzada** — `kj review --staged` pasa SonarQube sobre los ficheros cambiados antes de cualquier opinión de IA (BLOCKER/CRITICAL rechazan en el acto), y después liga el veredicto de una IA *distinta* al sha256 del diff exacto — estampado con el workspace desde el que corrió. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
 - **Una tercera IA arbitra las disputas** — `kj solomon` decide cuando brain y reviewer discrepan. Los hallazgos de seguridad no los anula nadie — ni siquiera el arbitraje.
 - **Rama primero, carriles para el paralelo** — la rama base solo se mueve por PRs atómicas; `kj worktree start|list|done` da a cada tarea concurrente su carril aislado.
+- **Mínimo privilegio para agentes** — los subprocesos de agente reciben un allowlist de entorno (la auth de su propio CLI, jamás tus claves cloud ni tokens de registro), y `kj check` inventaría cada MCP alcanzable del proyecto marcando lo aparecido desde el último check. Las tareas con superficie sensible se auto-invocan `kj audit --security` — pasada de cero tokens (prompt-injection sobre los ficheros de contexto del agente + OSV + Semgrep + Sonar) — y remedian antes del review.
+- **Nada personal se publica** — cada boundary de salida se audita antes de dejar la máquina: el pre-commit rechaza un diff con tus datos vetados, los tokens de plataforma hardcodeados (`ghp_`, `sk-`, `AKIA`…) bloquean directamente, el scan del tarball guarda el publish, y `kj privacy scan <dir>` audita cualquier build. Tu denylist vive en `~/.karajan/privacy.yml` — la instalación pregunta y la escribe por ti.
+- **Instalar ES activar** — `kj env install` ejecuta él mismo el enforcement (hooks de git, gate de veredicto, tool gate) en vez de confiar en que el agente corra pasos de setup, y termina imprimiendo el método en la propia conversación que instaló. Un commit fuera del método se rechaza, no se narra.
+- **El turno no puede terminar en rojo — el Sentinel** — un supervisor determinista (cero LLM) cableado a los hooks síncronos del harness registra el estado del método de la sesión según corren las herramientas, y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas. El programa manda, el agente piensa. Ver [niveles de garantía](#niveles-de-garantía-gobernado-vs-supervisado).
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 
@@ -56,6 +60,12 @@ Requiere git y al menos un CLI de agente de IA — con dos hay revisión cruzada
 
 Método completo: [Trabaja con tu agente](https://karajancode.com/docs/es/v4/working-with-your-agent/) · [Los gates](https://karajancode.com/docs/es/v4/gates/) · [Referencia de comandos](https://karajancode.com/docs/es/v4/commands/).
 
+## Niveles de garantía: gobernado vs supervisado
+
+Karajan **gobierna** a cualquier agente con gates de git — el falso verde es estructuralmente imposible escriba quien escriba, porque los gates viven en el repositorio, no en la buena voluntad del agente. Encima de eso, el **Karajan Sentinel** añade **supervisión dentro del turno**: `kj harden` cablea hooks deterministas al harness — uno registra el estado del método de la sesión según corren las herramientas (fuentes editadas vs tests tocados, escapes usados), y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas: fuentes editadas en la rama base, rama sin card, código sin tocar un solo test. Cada bloqueo dice la violación exacta y su remediación; `kj sentinel status` muestra lo que ve el supervisor. Ante cualquier duda falla en abierto — y lo dice — antes que colgar una sesión, y cada escape `KJ_ALLOW_*` queda registrado.
+
+Los hooks síncronos con capacidad de bloqueo hoy solo existen en Claude Code. Eso hace explícito el montaje soportado: **para garantizar un harness que controle al LLM, usa Claude Code como anfitrión** — Claude escribe, Codex revisa (un subproceso de revisión no necesita hooks), y un tercer CLI arbitra cuando está disponible. Con cualquier otro anfitrión Karajan sigue gobernando al nivel completo de gates de git y te dice qué nivel está activo — jamás finge una supervisión que no puede imponer.
+
 ## Modo headless
 
 El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. Agentes y CI pasan `--non-interactive` (o `KJ_NON_INTERACTIVE=1`): los gates seguros se auto-responden y los findings FAIL paran el run con exit code de verdad. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.11.0",
+  "version": "4.13.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/release-check.js

@@ -0,0 +1,109 @@
+/**
+ * release-check (KJC-TSK-0712) — the release checklist made verifiable:
+ * a note loses salience; a check fails RED with the exact list. Generics
+ * fit any karajan project; each project extends via `release_check.items`
+ * (file_contains with {version}, or command with exit-0 semantics).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { runCommand } from "../utils/process.js";
+import { loadPrivacyList, scanPaths } from "../privacy/scan.js";
+
+const semverCmp = (a, b) => {
+  const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+};
+
+async function genericChecks(projectDir) {
+  const checks = [];
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    checks.push({ name: "manifest", ok: true, detail: "no package.json — generic version checks skipped (declared items still run)" });
+    return { checks, version: null, pkg: null };
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const version = pkg.version;
+  checks.push({ name: "manifest", ok: Boolean(version), detail: version ? `version ${version}` : "package.json has no version" });
+
+  const clPath = join(projectDir, "CHANGELOG.md");
+  if (!existsSync(clPath)) {
+    checks.push({ name: "changelog-current", ok: false, detail: "no CHANGELOG.md — the release story must exist before the release" });
+  } else {
+    const cl = readFileSync(clPath, "utf8");
+    const topVersioned = (cl.match(/^## \[(\d+\.\d+\.\d+)\]/m) || [])[1] || null;
+    // Content still sitting under [Unreleased] means unpromoted entries —
+    // the tarball would ship changes its release notes do not tell.
+    const afterUnreleased = cl.split(/^## \[Unreleased\]\s*$/m)[1] ?? "";
+    const unreleasedBody = afterUnreleased.split(/^## \[/m)[0] ?? "";
+    const pending = /\S/.test(unreleasedBody);
+    const ok = topVersioned === version && !pending;
+    checks.push({
+      name: "changelog-current",
+      ok,
+      detail: ok
+        ? `top section is [${version}], Unreleased empty`
+        : pending
+          ? `[Unreleased] still carries content — promote it into [${version}] before releasing`
+          : `top CHANGELOG section is [${topVersioned ?? "none"}] but the manifest says ${version} — promote Unreleased before releasing`,
+    });
+  }
+
+  const tagsOut = await runCommand("git", ["-C", projectDir, "tag", "--list", "v[0-9]*"]);
+  const tags = (tagsOut.stdout || "").split("\n").map((t) => t.trim().replace(/^v/, "")).filter((t) => /^\d+\.\d+\.\d+$/.test(t));
+  const ahead = version ? tags.filter((t) => semverCmp(t, version) > 0) : [];
+  checks.push({
+    name: "tags",
+    ok: ahead.length === 0,
+    detail: ahead.length ? `tag(s) ahead of the manifest exist: v${ahead.join(", v")}` : (tags.includes(version) ? `v${version} already tagged` : `tag v${version} pending (created after publish)`),
+  });
+  return { checks, version, pkg };
+}
+
+async function packPrivacyCheck(projectDir, pkg) {
+  // Every non-private named package is publishable (exports/files-based
+  // packages carry no main/bin) — they all get the scan.
+  if (!pkg || pkg.private === true || !pkg.name || !pkg.version) return null;
+  try {
+    const out = await runCommand("npm", ["pack", "--dry-run", "--json", "--silent"], { cwd: projectDir });
+    const files = (JSON.parse(out.stdout || "[]")[0]?.files || []).map((f) => join(projectDir, f.path));
+    const blocks = scanPaths(files, { list: loadPrivacyList() }).filter((f) => f.severity === "block");
+    return { name: "pack-privacy", ok: blocks.length === 0, detail: blocks.length ? `${blocks.length} personal-data/secret hit(s) in the publishable files` : `${files.length} publishable file(s) clean` };
+  } catch (err) {
+    return { name: "pack-privacy", ok: false, detail: `npm pack --dry-run failed: ${err.message}` };
+  }
+}
+
+async function declaredItems(projectDir, config, version) {
+  const items = config?.release_check?.items;
+  if (!Array.isArray(items)) return [];
+  const checks = [];
+  for (const item of items) {
+    const name = item?.name || "unnamed item";
+    if (item?.file_contains?.path && item.file_contains.pattern != null) {
+      const p = isAbsolute(item.file_contains.path) ? item.file_contains.path : join(projectDir, item.file_contains.path);
+      const needle = String(item.file_contains.pattern).replaceAll("{version}", version ?? "");
+      const ok = existsSync(p) && readFileSync(p, "utf8").includes(needle);
+      checks.push({ name, ok, detail: ok ? `"${needle}" found in ${item.file_contains.path}` : `"${needle}" NOT found in ${item.file_contains.path}` });
+    } else if (item?.command) {
+      try {
+        const res = await runCommand("sh", ["-c", String(item.command).replaceAll("{version}", version ?? "")], { cwd: projectDir });
+        checks.push({ name, ok: res.exitCode === 0, detail: res.exitCode === 0 ? "command exited 0" : `command exited ${res.exitCode}` });
+      } catch (err) {
+        checks.push({ name, ok: false, detail: `command failed to run: ${err.message}` });
+      }
+    } else {
+      checks.push({ name, ok: false, detail: "unknown item shape — use file_contains {path, pattern} or command" });
+    }
+  }
+  return checks;
+}
+
+export async function runReleaseCheck({ projectDir = process.cwd(), config = {} } = {}) {
+  const { checks, version, pkg } = await genericChecks(projectDir);
+  const pack = await packPrivacyCheck(projectDir, pkg);
+  if (pack) checks.push(pack);
+  checks.push(...await declaredItems(projectDir, config, version));
+  return { ok: checks.every((c) => c.ok), version, checks };
+}

package/src/cli/advanced-commands.js

@@ -30,8 +30,8 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -20,6 +20,7 @@ import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { envInstallCommand, briefCommand } from "../commands/env.js";
+import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
 import { huCommand } from "../commands/hu.js";
@@ -27,6 +28,10 @@ import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { verifySentinelScripts, resolveSentinelRoot } from "../harden/sentinel-hooks.js";
 
 /**
  * Register the "meta" / single-role / housekeeping commands: pre-pipeline
@@ -262,6 +267,46 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0712 — memory is the reminder, the check is the guarantee.
+  const release = program.command("release").description("Release ceremony helpers");
+  release.command("check")
+    .description("Verify the release checklist deterministically (manifest vs CHANGELOG vs tags, privacy scan of publishable files, plus the project's release_check.items); exit 1 lists exactly what is missing")
+    .option("--json", "Machine-readable result")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "release-check", flags, async ({ config }) => {
+        const res = await runReleaseCheck({ projectDir: config?.projectDir || process.cwd(), config });
+        if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+        else {
+          for (const c of res.checks) console.log(`  ${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+          console.log(res.ok ? `release check: ready to release ${res.version ?? ""}`.trim() : "release check: NOT ready — fix the red items first");
+        }
+        process.exitCode = res.ok ? 0 : 1;
+      });
+    });
+
+  // KJC-TSK-0713 — the Sentinel: the method state the harness hooks record.
+  const sentinel = program.command("sentinel").description("Deterministic method supervisor wired into the harness hooks (Claude Code)");
+  sentinel.command("status")
+    .description("Print the per-session method facts (sources/tests edited, escapes used) and any open violation the Stop gate would block on")
+    .action(() => {
+      const script = join(resolveSentinelRoot(), ".karajan", "harness", "stop.mjs");
+      if (!existsSync(script)) {
+        console.log("sentinel: not installed in this project — run `kj harden` (standard profile or higher)");
+        process.exitCode = 1;
+        return;
+      }
+      process.exitCode = spawnSync("node", [script, "--status"], { stdio: "inherit" }).status ?? 0;
+    });
+  sentinel.command("verify")
+    .description("Verify the harness scripts match this kj install — the root of trust is the installed package, not the project tree; exit 1 lists what was modified")
+    .option("--json", "Machine-readable result")
+    .action((flags) => {
+      const res = verifySentinelScripts();
+      if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+      else console.log(res.ok ? "sentinel verify: scripts intactos" : `sentinel verify: modificados fuera de kj harden: ${res.mismatched.join(", ")} — restaura con kj harden`);
+      process.exitCode = res.ok ? 0 : 1;
+    });
+
   // KJC-TSK-0704 — the outbound privacy boundary: audit before anything ships.
   const privacy = program.command("privacy").description("Personal-data (PII) auditing of outbound boundaries: staged diffs, build outputs, docs trees");
   privacy.command("scan [paths...]")

package/src/commands/harden.js

@@ -19,6 +19,7 @@ import { installGuidelines } from "../harden/guidelines-engine.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
 import { installHooks } from "../harden/harden-engine.js";
 import { installHarnessHooks } from "../harden/harness-hooks.js";
+import { installSentinelHooks } from "../harden/sentinel-hooks.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
 import { installWorkflows } from "../harden/workflow-engine.js";
 import { detectTestFramework } from "../utils/project-detect.js";
@@ -146,6 +147,10 @@ export async function hardenCommand({
     if (profile !== "minimal" && !dryRun) {
       const hh = installHarnessHooks({ projectDir, logger });
       result.harnessHooks = hh.wired ? "wired" : "script-only";
+      // KJC-TSK-0713 — the Sentinel: method state + Stop gate (turn cannot
+      // end red). Same Claude-only harness surface as the tool gate.
+      const sh = installSentinelHooks({ projectDir, logger });
+      result.sentinelHooks = sh.wired ? "wired" : "script-only";
     }
   } catch (err) {
     if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));

package/src/commands/report.js

@@ -162,6 +162,9 @@ async function buildReport(dir, sessionId) {
   if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
   if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
   if (session.rtk_savings) report.rtk_savings = session.rtk_savings;
+  // The session may belong to another workspace: its snapshot knows the
+  // project dir the sentinel state lives in (same source solomon-rules uses).
+  if (session.config_snapshot?.projectDir) report.project_dir = session.config_snapshot.projectDir;
   return report;
 }
 
@@ -210,6 +213,36 @@ function printTextReport(report) {
   console.log(formatCommitsText(report.commits_generated));
 }
 
+/**
+ * KJC-TSK-0715 — escapes are the user's decisions, never the agent's silent
+ * shortcuts: every KJ_ALLOW_* the sentinel honored surfaces in the report.
+ */
+export function formatSentinelEscapes(state) {
+  const events = Array.isArray(state?.escape_events) ? state.escape_events : [];
+  if (events.length === 0) return null;
+  const lines = events.map(
+    (e) => `  ${e.ts ? new Date(e.ts).toISOString() : "?"} ${e.escape} (tool: ${e.tool || "?"}, session: ${e.sid || "?"})`
+  );
+  return `Sentinel escapes used (${events.length}):\n${lines.join("\n")}`;
+}
+
+// The sentinel state is a PROJECT artifact (<project>/.karajan/harness), not
+// a session artifact: the `dir` the report handlers receive is the GLOBAL
+// sessions root (~/.karajan/sessions) and never contains it. `kj report` is
+// run from inside the project, so the project dir is the cwd — overridable
+// for callers reporting on another workspace.
+async function printSentinelEscapes({ projectDir = process.cwd(), format } = {}) {
+  if (format === "json") return;
+  try {
+    const raw = await fs.readFile(path.join(projectDir, ".karajan", "harness", "sentinel-state.json"), "utf8");
+    const text = formatSentinelEscapes(JSON.parse(raw));
+    if (text) {
+      console.log("");
+      console.log(text);
+    }
+  } catch { /* no sentinel state in this project — nothing to report */ }
+}
+
 function formatDuration(ms) {
   if (ms === null || ms === undefined) return "-";
   if (ms < 1000) return `${ms}ms`;
@@ -384,6 +417,7 @@ async function handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace,
   } else {
     printTextReport(report);
   }
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
 }
 
 async function handleSingleSessionReport({ dir, entries, sessionId, format, trace, currency }) {
@@ -405,9 +439,10 @@ async function handleSingleSessionReport({ dir, entries, sessionId, format, trac
   if (trace) {
     const { cur, rate } = await resolveTraceOptions(currency);
     printTraceReport(report, cur, rate);
-    return;
+  } else {
+    printTextReport(report);
   }
-  printTextReport(report);
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
 }
 
 export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd", pgTask = null }) {

package/src/harden/harness-hooks.js

@@ -12,8 +12,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-const SCRIPT_REL = join(".karajan", "harness", "pretooluse.mjs");
-
 const SCRIPT_BODY = `#!/usr/bin/env node
 // kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
 // tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
@@ -43,38 +41,67 @@ process.stdin.on("end", () => {
 });
 `;
 
-const hookEntry = (matcher) => ({ matcher, hooks: [{ type: "command", command: `node ${SCRIPT_REL}` }] });
-
-/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
-export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
-  const scriptAbs = join(projectDir, SCRIPT_REL);
-  mkdirSync(join(projectDir, ".karajan", "harness"), { recursive: true });
-  writeFileSync(scriptAbs, SCRIPT_BODY, { mode: 0o755 });
+/** Write a managed hook script under .karajan/harness/ and return its path. */
+export function writeHarnessScript(projectDir, name, body) {
+  const dir = join(projectDir, ".karajan", "harness");
+  mkdirSync(dir, { recursive: true });
+  const abs = join(dir, name);
+  writeFileSync(abs, body, { mode: 0o755 });
+  return abs;
+}
 
+/**
+ * Merge hook entries into .claude/settings.json. Preserve, never clobber:
+ * invalid JSON or a hook event with an unexpected (non-array) shape is the
+ * user's business — the file is left alone and the caller wires manually.
+ * entries: [{ event, matcher?, script }] where script is a .karajan/harness
+ * basename; an entry is present when that script already appears under the
+ * same event (and matcher, when given).
+ */
+export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
   const settingsPath = join(projectDir, ".claude", "settings.json");
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
       settings = JSON.parse(readFileSync(settingsPath, "utf8"));
     } catch {
-      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (tool gate script written, wire it manually)`);
-      return { script: scriptAbs, wired: false };
+      logger.warn?.(`kj harden: ${settingsPath} is not valid JSON — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
     }
   }
   settings.hooks = settings.hooks || {};
-  // Preserve, never clobber: an existing PreToolUse with an unexpected shape
-  // is the user's business — leave the file alone (same as invalid JSON).
-  if ("PreToolUse" in settings.hooks && !Array.isArray(settings.hooks.PreToolUse)) {
-    logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.PreToolUse — leaving it untouched (tool gate script written, wire it manually)`);
-    return { script: scriptAbs, wired: false };
+  for (const { event } of entries) {
+    if (event in settings.hooks && !Array.isArray(settings.hooks[event])) {
+      logger.warn?.(`kj harden: ${settingsPath} has a non-array hooks.${event} — leaving it untouched (hook scripts written, wire them manually)`);
+      return { wired: false };
+    }
   }
-  const pre = Array.isArray(settings.hooks.PreToolUse) ? settings.hooks.PreToolUse : [];
-  for (const matcher of ["Write", "Bash"]) {
-    const present = pre.some((e) => e?.matcher === matcher && JSON.stringify(e).includes("pretooluse.mjs"));
-    if (!present) pre.push(hookEntry(matcher));
+  for (const { event, matcher, script } of entries) {
+    const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const present = list.some(
+      (e) => JSON.stringify(e).includes(script) && (matcher === undefined || e?.matcher === matcher),
+    );
+    if (!present) {
+      const cmd = { type: "command", command: `node ${join(".karajan", "harness", script)}` };
+      list.push(matcher === undefined ? { hooks: [cmd] } : { matcher, hooks: [cmd] });
+    }
+    settings.hooks[event] = list;
   }
-  settings.hooks.PreToolUse = pre;
   mkdirSync(join(projectDir, ".claude"), { recursive: true });
   writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
-  return { script: scriptAbs, wired: true };
+  return { wired: true };
+}
+
+/** Write the script and merge the PreToolUse entries into .claude/settings.json. */
+export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
+  const { wired } = mergeClaudeHooks({
+    projectDir,
+    logger,
+    entries: [
+      { event: "PreToolUse", matcher: "Write", script: "pretooluse.mjs" },
+      { event: "PreToolUse", matcher: "Bash", script: "pretooluse.mjs" },
+    ],
+  });
+  return { script: scriptAbs, wired };
 }

package/src/harden/sentinel-hooks.js

@@ -0,0 +1,295 @@
+/**
+ * sentinel-hooks — SEN-A (KJC-TSK-0713, epic KJC-PCS-0071 Karajan Sentinel).
+ * v3 had authority without intelligence; v4 intelligence without authority.
+ * The Sentinel separates them: a deterministic PROGRAM (zero LLM) supervises
+ * the agent through the harness's synchronous hooks — PostToolUse records
+ * method facts per session, Stop BLOCKS ending the turn while violations are
+ * open. Claude Code only: it is the one harness with synchronous blocking
+ * hooks, which is why the guaranteed level requires Claude as host (ADR).
+ */
+
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { CARD_REF_RE } from "../review/card-first.js";
+import { mergeClaudeHooks, writeHarnessScript } from "./harness-hooks.js";
+
+/** The harness lives at the PROJECT root — resolve it even from a subdir. */
+export function resolveSentinelRoot(dir = process.cwd()) {
+  try {
+    return (
+      execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir
+    );
+  } catch {
+    return dir;
+  }
+}
+
+const LIB_BODY = `// kj sentinel shared lib (KJC-TSK-0714) — managed by \`kj harden\`.
+// Single source for every sentinel script: state, branch, classification,
+// violations, and escape recording.
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+export const STATE = join(here, "sentinel-state.json");
+export const ROOT = join(here, "..", "..");
+export const TESTS = /(^|\\/)(tests?|__tests__|spec)\\/|\\.(test|spec)\\.[a-z]+$/;
+export const CODE = /\\.(m?[jt]sx?|c[jt]s|py|go|rs|java|rb|php|cs|swift|kt|astro|svelte|vue|c|h|cc|cpp|hpp)$/;
+export const CARD = new RegExp(${JSON.stringify(CARD_REF_RE.source)}, "i");
+export const BASE_BRANCHES = new Set(["main", "master"]);
+export const load = () => { try { return JSON.parse(readFileSync(STATE, "utf8")); } catch { return {}; } };
+export const save = (state) => writeFileSync(STATE, JSON.stringify(state, null, 2));
+export const session = (state, sid) => {
+  state.sessions ||= {};
+  return (state.sessions[sid] ||= { edited_sources: [], edited_tests: [], escapes: [], errors: [], blocks: 0 });
+};
+export const branchOf = () => {
+  try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
+  catch { return null; }
+};
+export const violations = (s, branch) => {
+  const v = [];
+  if (!s || !(s.edited_sources || []).length) return v;
+  if (BASE_BRANCHES.has(branch)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion");
+  else if (branch && !CARD.test(branch)) v.push("La rama '" + branch + "' no referencia ninguna card — usa feat/<CARD-ID>-descripcion (y una card VIVA en el board)");
+  if (!(s.edited_tests || []).length) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
+  return v;
+};
+export const recordEscape = (sid, escape, tool) => {
+  const state = load();
+  const s = session(state, sid);
+  s.at = Date.now();
+  if (!s.escapes.includes(escape)) s.escapes.push(escape);
+  (state.escape_events ||= []).push({ escape, tool, sid, ts: Date.now() });
+  save(state);
+};
+`;
+
+const POST_BODY = `#!/usr/bin/env node
+// kj sentinel state writer (KJC-TSK-0713) — managed by \`kj harden\`.
+// Records deterministic method facts per session; never blocks, never fails
+// a tool call (PostToolUse, always exit 0).
+import { relative } from "node:path";
+import { CODE, TESTS, ROOT, load, save, session } from "./sentinel-lib.mjs";
+const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII"];
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    const file = input.file_path || input.notebook_path;
+    if (!["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(tool) || !file) process.exit(0);
+    const state = load();
+    const s = session(state, sid);
+    s.at = Date.now();
+    const rel = relative(ROOT, file).replaceAll("\\\\", "/");
+    const bucket = TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
+    if (bucket && !bucket.includes(rel)) bucket.push(rel);
+    for (const e of ESCAPES)
+      if (process.env[e] === "1" && !s.escapes.includes(e)) {
+        s.escapes.push(e);
+        (state.escape_events ||= []).push({ escape: e, tool, sid, ts: Date.now() });
+      }
+    const ids = Object.keys(state.sessions);
+    if (ids.length > 5) delete state.sessions[ids.sort((a, b) => (state.sessions[a].at || 0) - (state.sessions[b].at || 0))[0]];
+    save(state);
+  } catch { /* fail open — the sentinel never breaks a tool call */ }
+  process.exit(0);
+});
+`;
+
+const STOP_BODY = `#!/usr/bin/env node
+// kj sentinel stop gate (KJC-TSK-0713) — managed by \`kj harden\`. Exit 2
+// BLOCKS ending the turn while method violations are open (stderr lists each
+// one with its remediation). Fails OPEN on corrupt state, git errors, or
+// after 3 unresolved blocks — a sentinel bug never bricks the session — and
+// the fail-open is recorded in the state. \`--status\` prints, never blocks.
+import { spawnSync } from "node:child_process";
+import { load, save, branchOf, violations, ROOT } from "./sentinel-lib.mjs";
+if (process.argv.includes("--status")) {
+  const st = load();
+  const branch = branchOf();
+  const sessions = Object.entries(st.sessions || {});
+  if (!sessions.length) console.log("sentinel: sin actividad registrada en esta sesion");
+  for (const [sid, s] of sessions) {
+    console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : ""));
+    for (const x of violations(s, branch)) console.log("  ROJO: " + x);
+  }
+  process.exit(0);
+}
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    const { session_id: sid = "default" } = JSON.parse(raw);
+    const state = load();
+    // Tamper check runs regardless of session state: shell indirection leaves
+    // no edit-tool record, but it cannot survive \`kj sentinel verify\`, whose
+    // root of trust is the INSTALLED kj package (outside this project tree) —
+    // nothing under .karajan can vouch for itself. No kj on PATH → fail open.
+    const ver = spawnSync("kj", ["sentinel", "verify", "--json"], { cwd: ROOT, encoding: "utf8" });
+    let tampered = [];
+    if (!ver.error && ver.status !== null && ver.status !== 0) {
+      try { tampered = JSON.parse(ver.stdout).mismatched || ["unknown"]; } catch { tampered = ["unknown"]; }
+    }
+    if (tampered.length) {
+      state.tamper_blocks = (state.tamper_blocks || 0) + 1;
+      save(state);
+      if (state.tamper_blocks > 3) {
+        console.error("kj sentinel: fail-open tras 3 bloqueos por manipulacion sin restaurar — corre kj harden y avisa a tu usuario");
+        process.exit(0);
+      }
+      console.error("kj sentinel: scripts del supervisor modificados fuera de kj harden (" + tampered.join(", ") + ") — restaura con kj harden antes de terminar; si lo cambiaste tu (humano), reinstalar lo deja en verde.");
+      process.exit(2);
+    }
+    state.tamper_blocks = 0;
+    const s = state.sessions?.[sid];
+    if (!s) process.exit(0);
+    const v = violations(s, branchOf());
+    if (!v.length) {
+      s.blocks = 0;
+      save(state);
+      if ((s.escapes || []).length)
+        console.log(JSON.stringify({ systemMessage: "kj sentinel: esta sesion uso " + s.escapes.length + " escape(s): " + s.escapes.join(", ") + " — decision registrada; detalle en kj sentinel status." }));
+      process.exit(0);
+    }
+    s.blocks = (s.blocks || 0) + 1;
+    if (s.blocks > 3) {
+      (s.errors ||= []).push("fail-open: 3 bloqueos consecutivos sin resolver — el sentinel se aparta para no colgar la sesion");
+      save(state);
+      console.error("kj sentinel: fail-open tras 3 bloqueos sin resolver — revisa kj sentinel status con tu usuario");
+      process.exit(0);
+    }
+    save(state);
+    console.error("kj sentinel: el turno NO puede terminar con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve las violaciones (o pide a tu usuario el escape) y termina de nuevo. Estado: kj sentinel status");
+    process.exit(2);
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+const PRETOOL_BODY = `#!/usr/bin/env node
+// kj sentinel pretooluse gate (KJC-TSK-0714) — managed by \`kj harden\`.
+// Consults the session method state BEFORE the tool runs: the rule fires
+// before the damage, not in the post-mortem. Exit 2 blocks (stderr says the
+// remediation); read-only tools are never wired here; every honored escape
+// is recorded as an auditable event. Fails OPEN on anything unexpected.
+import { relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, load, violations, recordEscape } from "./sentinel-lib.mjs";
+const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+const PUBLISH = /\\bnpm\\s+publish\\b|\\bfirebase\\s+deploy\\b|\\bgh\\s+release\\s+create\\b/;
+const PUSH = /\\bgit\\s+push\\b/;
+const PROTECTED = /\\.claude\\/settings\\.json\\b|\\.karajan\\/(hooks|harness)\\//;
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
+    // Self-protection (KJC-TSK-0715) rules run BEFORE any escape, including
+    // KJ_SENTINEL_OFF: the sentinel is not dismantled from inside a session —
+    // only the human, editing outside it.
+    if (EDIT_TOOLS.includes(tool)) {
+      const target = input.file_path || input.notebook_path;
+      const relT = target ? relative(ROOT, String(target)).replaceAll("\\\\", "/") : "";
+      if (relT && PROTECTED.test(relT)) {
+        console.error("kj sentinel: ese fichero es parte del supervisor (" + relT + ") — solo el humano desmonta el sentinel, editalo fuera de la sesion.");
+        process.exit(2);
+      }
+    }
+    // Any Bash that NAMES the supervisor's files is denied — a write-verb
+    // blocklist is bypassable (cp, dd, one-liners), and reading them is what
+    // the Read/Grep tools are for. Shell indirection (variables, globs,
+    // substitution) cannot be resolved from command text: that vector is
+    // caught by the Stop gate's checksum verification, which blocks the turn.
+    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\\\", "/"))) {
+      console.error("kj sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion.");
+      process.exit(2);
+    }
+    if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    if (EDIT_TOOLS.includes(tool)) {
+      const file = input.file_path || input.notebook_path;
+      const rel = file ? relative(ROOT, String(file)).replaceAll("\\\\", "/") : "";
+      if (rel && CODE.test(rel) && !TESTS.test(rel)) {
+        const branch = branchOf();
+        const why = !branch ? null : BASE_BRANCHES.has(branch) ? "base" : !CARD.test(branch) ? "nocard" : null;
+        if (why) {
+          if (process.env.KJ_ALLOW_NO_CARD === "1") { recordEscape(sid, "KJ_ALLOW_NO_CARD", tool); process.exit(0); }
+          console.error(why === "base"
+            ? "kj sentinel: no se editan fuentes en la rama base '" + branch + "' — crea la card (kj hu add) y la rama: git checkout -b feat/<CARD-ID>-descripcion. (KJ_ALLOW_NO_CARD=1 = excepcion consciente, queda registrada)"
+            : "kj sentinel: la rama '" + branch + "' no referencia ninguna card — crea/mueve la card a running (kj hu add | kj hu move) y usa una rama feat/<CARD-ID>-descripcion. (KJ_ALLOW_NO_CARD=1 = excepcion consciente, queda registrada)");
+          process.exit(2);
+        }
+      }
+    }
+    if (tool === "Bash") {
+      const cmd = String(input.command || "");
+      if (PUBLISH.test(cmd)) {
+        if (process.env.KJ_ALLOW_RELEASE === "1") { recordEscape(sid, "KJ_ALLOW_RELEASE", tool); process.exit(0); }
+        const res = spawnSync("kj", ["release", "check", "--json"], { cwd: ROOT, encoding: "utf8" });
+        if (res.error || res.status === null) process.exit(0);
+        if (res.status !== 0) {
+          let items = "";
+          try { items = (JSON.parse(res.stdout).checks || []).filter((c) => !c.ok).map((c) => "\\n- " + c.name + ": " + c.detail).join(""); } catch { /* raw output */ }
+          console.error("kj sentinel: release check en ROJO — no se publica ni despliega hasta resolverlo:" + (items || "\\n- corre kj release check para el detalle") + "\\n(KJ_ALLOW_RELEASE=1 = excepcion consciente, queda registrada)");
+          process.exit(2);
+        }
+      } else if (PUSH.test(cmd)) {
+        const v = violations(load().sessions?.[sid], branchOf());
+        if (v.length) {
+          console.error("kj sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve antes de empujar. Estado: kj sentinel status");
+          process.exit(2);
+        }
+      }
+    }
+  } catch { /* fail open */ }
+  process.exit(0);
+});
+`;
+
+const SCRIPT_BODIES = {
+  "sentinel-lib.mjs": LIB_BODY,
+  "posttooluse.mjs": POST_BODY,
+  "stop.mjs": STOP_BODY,
+  "pretooluse-sentinel.mjs": PRETOOL_BODY,
+};
+
+/**
+ * Tamper detection (KJC-TSK-0715): compare the on-disk harness scripts with
+ * what THIS kj install would write. The root of trust is the installed kj
+ * package — outside the project tree, beyond the session's tool reach —
+ * because nothing under .karajan can vouch for itself.
+ */
+export function verifySentinelScripts({ projectDir } = {}) {
+  const dir = join(projectDir || resolveSentinelRoot(), ".karajan", "harness");
+  const mismatched = [];
+  for (const [name, body] of Object.entries(SCRIPT_BODIES)) {
+    try {
+      if (readFileSync(join(dir, name), "utf8") !== body) mismatched.push(name);
+    } catch {
+      mismatched.push(name);
+    }
+  }
+  return { ok: mismatched.length === 0, mismatched };
+}
+
+/** Write the sentinel scripts (shared lib + state writer + gates) and wire them. */
+export function installSentinelHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  const [lib, post, stop, pre] = Object.entries(SCRIPT_BODIES).map(([name, body]) =>
+    writeHarnessScript(projectDir, name, body),
+  );
+  const { wired } = mergeClaudeHooks({
+    projectDir,
+    logger,
+    entries: [
+      { event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "pretooluse-sentinel.mjs" },
+      { event: "PreToolUse", matcher: "Bash", script: "pretooluse-sentinel.mjs" },
+      { event: "PostToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "posttooluse.mjs" },
+      { event: "Stop", script: "stop.mjs" },
+    ],
+  });
+  return { scripts: [lib, post, stop, pre], wired };
+}