@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/notification-sound.ts

@@ -0,0 +1,49 @@
+/**
+ * @module notification-sound
+ * Resolve the on-disk sound file for a hook notification kind: a per-kind env
+ * override, else the package's own `assets/song/` bundle, else a plugin-root
+ * fallback. Returns an absolute path or `null` ("stay silent"). NEVER throws.
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runningVersion } from "../cli/doctor";
+
+/** Notification kinds the harness can voice. */
+export type SoundKind = "stop" | "permission" | "human";
+
+/** Kind → asset filename (under `assets/song/` and the plugin-root fallback). */
+const FILES: Record<SoundKind, string> = { stop: "finish.mp3", permission: "permission-need.mp3", human: "need-human.mp3" };
+
+/** Kind → env var holding an explicit override path. */
+const ENV_VARS: Record<SoundKind, string> = { stop: "FUSE_HARNESS_SOUND_STOP", permission: "FUSE_HARNESS_SOUND_PERMISSION", human: "FUSE_HARNESS_SOUND_HUMAN" };
+
+/**
+ * Resolve the sound file for `kind`, or `null` when none is available. Cascade:
+ * (1) the per-kind env override when present on disk; (2) the package's own
+ * `assets/song/<f>.mp3`, located by walking up to the running `package.json`
+ * ({@link runningVersion} — survives the flat/hashed `dist/` bundle a hardcoded
+ * `../../` of non-deterministic depth would escape); (3) `$CLAUDE_PLUGIN_ROOT/song/<f>.mp3`. Never throws.
+ * @param kind - Which event to voice.
+ * @param env - Injectable environment (defaults to `process.env`).
+ * @param moduleUrl - Injectable module URL (defaults to this module's; locates the package).
+ */
+export function resolveSound(kind: SoundKind, env: Record<string, string | undefined> = process.env, moduleUrl: string = import.meta.url): string | null {
+  try {
+    const override = env[ENV_VARS[kind]];
+    if (override && existsSync(override)) return override;
+    const pkgRoot = runningVersion(moduleUrl).path;
+    if (pkgRoot !== "unknown") {
+      const asset = join(pkgRoot, "assets", "song", FILES[kind]);
+      if (existsSync(asset)) return asset;
+    }
+    const pluginRoot = env.CLAUDE_PLUGIN_ROOT;
+    if (pluginRoot) {
+      const fallback = join(pluginRoot, "song", FILES[kind]);
+      if (existsSync(fallback)) return fallback;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/runtime/notifications.ts

@@ -0,0 +1,77 @@
+/**
+ * @module notifications
+ * Native OS notification sound for lifecycle hook events (turn Stop, permission
+ * needed, human needed). ON by default; opt OUT with `FUSE_HARNESS_SOUND=0`.
+ *
+ * Only two events invoke {@link notify}: the core-scope `Stop` (Codex-only —
+ * Claude voices Stop via its own native `afplay` hook, so this never double-
+ * sounds) and `TeammateIdle` (Claude-only, which has no native sound). That
+ * structural split IS the anti-double-sound guarantee — do NOT add a harness-id
+ * gate here: it would silence `TeammateIdle`'s "human" sound, whose only home is
+ * claude-code. PermissionRequest/Notification stay native-only and are
+ * intentionally not wired here (no dead code).
+ *
+ * ABSOLUTE fail-open, `command || true` semantics: an opt-out, an unsupported
+ * platform, a missing player binary, a missing/undecodable sound file, or a
+ * non-zero exit is swallowed — this module NEVER throws and NEVER blocks the
+ * caller, so a broken/absent player can never break a hook.
+ * @packageDocumentation
+ */
+import { spawn } from "node:child_process";
+import { resolveSound, type SoundKind } from "./notification-sound";
+
+export type { SoundKind } from "./notification-sound";
+
+/** A resolved player invocation (binary + argv). */
+export interface PlayerSpec {
+  bin: string;
+  args: string[];
+}
+
+/**
+ * The player command for `platform` playing `file`, or undefined for an
+ * unsupported platform. Pure — no filesystem/process access, so it is cheaply
+ * unit-testable without spawning anything. mp3 decoding is native on darwin
+ * (`afplay`); on linux (`paplay`/libsndfile) and win32 (`SoundPlayer`, wav-only)
+ * a bare mp3 may not decode — harmless under the fail-open contract.
+ * @param platform - `process.platform`-shaped value.
+ * @param file - Absolute path to the sound file to play.
+ */
+export function resolvePlayer(platform: string, file: string): PlayerSpec | undefined {
+  if (platform === "darwin") return { bin: "afplay", args: [file] };
+  if (platform === "linux") return { bin: "paplay", args: [file] };
+  if (platform === "win32") return { bin: "powershell", args: ["-NoProfile", "-c", `(New-Object Media.SoundPlayer '${file}').PlaySync()`] };
+  return undefined;
+}
+
+/** True unless the user opted OUT (`FUSE_HARNESS_SOUND=0`). ON by default. */
+export function soundEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  return env.FUSE_HARNESS_SOUND !== "0";
+}
+
+/**
+ * Fire-and-forget a native notification sound for `kind`. See module doc for
+ * the absolute fail-open contract. A `null` resolved sound (nothing on disk) is
+ * a silent no-op.
+ * @param kind - Which event to voice.
+ * @param opts - Injectable platform/env/spawn for tests; production defaults to the real ones.
+ */
+export function notify(
+  kind: SoundKind,
+  opts: { platform?: string; env?: Record<string, string | undefined>; spawnFn?: typeof spawn } = {},
+): void {
+  try {
+    const env = opts.env ?? process.env;
+    if (!soundEnabled(env)) return;
+    const file = resolveSound(kind, env);
+    if (!file) return;
+    const player = resolvePlayer(opts.platform ?? process.platform, file);
+    if (!player) return;
+    const run = opts.spawnFn ?? spawn;
+    const child = run(player.bin, player.args, { stdio: "ignore", detached: true });
+    child.on("error", () => { /* fail-open: a missing binary must never throw */ });
+    child.unref();
+  } catch {
+    /* absolute fail-open: a notification must never break the hook */
+  }
+}

package/src/runtime/paths.ts

@@ -0,0 +1,59 @@
+/**
+ * @module paths
+ * Runtime path helpers — per-project, out-of-tree harness state.
+ *
+ * Default base: ~/.fuse-harness/state/<projectHash>/
+ * where projectHash = 8-char MD5 of CLAUDE_PROJECT_DIR (or cwd).
+ * Persistent and not world-writable (unlike /tmp), and OUTSIDE the repo so the
+ * agent has no "legitimate" reason to write it (the protected-path guard denies
+ * it, and the gate verifies freshness from the transcript, not this file).
+ *
+ * @packageDocumentation
+ */
+
+import { join } from "node:path";
+import { hashText } from "../util/json-io";
+import { fuseHarnessHome } from "./home-state";
+
+/** Resolve the project root from the environment or fall back to cwd. */
+function resolveProjectDir(): string {
+  return process.env["CLAUDE_PROJECT_DIR"] ?? process.cwd();
+}
+
+/**
+ * Compute a stable 8-char hex hash for a project directory path.
+ * Delegates to `hashText` (MD5, non-cryptographic — used as a stable dir key only).
+ *
+ * @param projectDir - Absolute path to the project root; defaults to CLAUDE_PROJECT_DIR/cwd.
+ * @returns 8-char lowercase hex string.
+ */
+export function projectHash(projectDir?: string): string {
+  return hashText(projectDir ?? resolveProjectDir());
+}
+
+/**
+ * Canonical base directory for per-project harness state.
+ * Resolves to: ~/.fuse-harness/state/<projectHash>/
+ *
+ * @param projectDir - Optional override for hashing; defaults to CLAUDE_PROJECT_DIR/cwd.
+ * @returns Absolute directory path (not yet created on disk).
+ */
+export function defaultStateDir(projectDir?: string): string {
+  return join(fuseHarnessHome(), "state", projectHash(projectDir));
+}
+
+/**
+ * Absolute path to a session's track JSON file.
+ *
+ * The session identifier is sanitised to `[A-Za-z0-9_-]` before use in the filename.
+ *
+ * @param sessionId - Claude session identifier (raw value accepted; sanitised internally).
+ * @param baseDir   - Override the base directory. Omit in production; pass an explicit
+ *                    temp path in unit tests to avoid touching $HOME.
+ * @returns Absolute path, e.g. ~/.fuse-harness/state/a1b2c3d4/track-abc123.json
+ */
+export function trackFile(sessionId: string, baseDir?: string): string {
+  const dir = baseDir ?? defaultStateDir();
+  const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "_") || "default";
+  return join(dir, `track-${safe}.json`);
+}

package/src/runtime/post-fanout.ts

@@ -0,0 +1,41 @@
+import type { NormalizedEvent } from "./normalize";
+
+/**
+ * Fan Codex `apply_patch` or Cursor `afterFileEdit` `event.files` into one
+ * per-file event per touched file, so the per-file PostToolUse gates (SOLID
+ * size, Tailwind, tracking, post-edit context) see EACH file instead of the
+ * whole patch (whose own `filePath`/`content` are always undefined). `add`
+ * maps to `Write`, `update` to `Edit` (mirrors the Pre-phase `applyPatchGate`'s
+ * tool mapping); `delete`/`move` map to a tool none of those Write|Edit-gated
+ * checks recognize, so they no-op on it without special-casing each gate.
+ * Returns `[event]` unchanged when no per-file changes are present.
+ * @param event - The normalized PostToolUse event.
+ * @returns One event per touched file, or the original event.
+ */
+export function fanOutFiles(event: NormalizedEvent): NormalizedEvent[] {
+  if (!event.files || event.files.length === 0) return [event];
+  return event.files.map((f) => ({
+    ...event,
+    tool: f.op === "add" ? "Write" : f.op === "update" ? "Edit" : "apply_patch:delete",
+    filePath: f.filePath,
+    content: f.op === "delete" ? undefined : f.content,
+    oldString: f.oldString,
+  }));
+}
+
+/**
+ * Run `check(tool, filePath)` over each fanned-out file, OR-ing the verdict —
+ * the first non-empty result wins (parity with `applyPatchGate`'s "one
+ * violating hunk blocks the whole envelope").
+ * @param files - Per-file events from {@link fanOutFiles}.
+ * @param check - A PostToolUse gate keyed on `(tool, filePath)`.
+ * @returns The first non-empty result, or `""` when every file is clean.
+ */
+export function firstFileMatch(files: readonly NormalizedEvent[], check: (tool: string, filePath: string) => string): string {
+  for (const f of files) {
+    if (!f.filePath) continue;
+    const result = check(f.tool, f.filePath);
+    if (result) return result;
+  }
+  return "";
+}

package/src/runtime/post-outcome.ts

@@ -0,0 +1,61 @@
+import { attachSystemMessage } from "../adapters/claude";
+import { designPassNotice } from "../policy/design/gates";
+import { refCreditNoticeFor } from "./notices";
+import { defaultStateDir } from "./paths";
+import { respond } from "./respond";
+import type { Activity } from "./record";
+import type { HandleOutcome } from "./handle";
+import type { NormalizedEvent } from "./normalize";
+import { formatPrompt, type Prompt } from "../prompt/types";
+
+/** Extract the additional-context body from a Claude-shaped post response. */
+export function additionalContextOf(stdout: string): string {
+  if (!stdout) return "";
+  try {
+    const parsed = JSON.parse(stdout) as { hookSpecificOutput?: { additionalContext?: string } };
+    return parsed.hookSpecificOutput?.additionalContext ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function cursorPostToolOutput(eventName: string, designWarn: Prompt | null, userMessage: string | undefined, extra: string): string {
+  if (!/^postToolUse$/i.test(eventName)) return "";
+  const context = [designWarn ? formatPrompt(designWarn) : "", designWarn?.userMessage, userMessage, additionalContextOf(extra)]
+    .filter(Boolean)
+    .join("\n");
+  return context ? JSON.stringify({ additional_context: context }) : "";
+}
+
+/**
+ * Assemble the final PostToolUse response after all side effects and deny paths.
+ * @param input - Final assembly values captured at their original evaluation times.
+ * @returns The native hook outcome.
+ */
+export function postOutcome(input: {
+  id: string; agentId: string; sessionId: string; now: number; cwd: string;
+  activities: readonly Activity[]; files: readonly NormalizedEvent[];
+  designCacheDir: string; designWarn: Prompt | null; extra: string;
+  cursorAfterFileEdit: boolean; cursorEventName: string;
+}): HandleOutcome {
+  const { id, agentId, sessionId, now, cwd, activities, files, designCacheDir, designWarn, extra, cursorAfterFileEdit, cursorEventName } = input;
+  const noticeLines: string[] = [];
+  for (const f of files) {
+    const notice = designPassNotice({ agentId, tool: f.tool, filePath: f.filePath ?? "", content: f.content ?? "", url: "", phase: "post" }, designCacheDir);
+    if (notice?.userMessage) noticeLines.push(notice.userMessage);
+  }
+  const notice: Prompt | null = noticeLines.length ? { kind: "inform", title: "Design pipeline", reason: "", userMessage: noticeLines.join("\n") } : null;
+  const refNotice = refCreditNoticeFor(activities, sessionId, now, defaultStateDir(cwd));
+  const userMessage = [notice?.userMessage, refNotice].filter(Boolean).join("\n") || undefined;
+  // Cursor ignores callback fields for afterFileEdit; complete successfully
+  // without emitting the permission schema reserved for pre-execution hooks.
+  if (cursorAfterFileEdit) return { stdout: "{}", exit: 0 };
+  if (id === "cursor") return { stdout: cursorPostToolOutput(cursorEventName, designWarn, userMessage, extra), exit: 0 };
+  if (designWarn) return { stdout: respond(id, userMessage ? { ...designWarn, userMessage } : designWarn, "PostToolUse"), exit: 0 };
+  if (!userMessage) return { stdout: extra, exit: 0 };
+  const withUserMessage: Prompt = notice ? { ...notice, userMessage } : { kind: "inform", title: "Compliance", reason: "", userMessage };
+  if (!extra) return { stdout: respond(id, withUserMessage, "PostToolUse"), exit: 0 };
+  if (id === "claude-code" || id === "codex") return { stdout: attachSystemMessage(extra, userMessage), exit: 0 };
+  if (id === "kimi") return { stdout: respond(id, withUserMessage, "PostToolUse"), exit: 0 };
+  return { stdout: respond(id, withUserMessage, "PostToolUse") || extra, exit: 0 };
+}

package/src/runtime/pre-allow.ts

@@ -0,0 +1,97 @@
+/**
+ * PreToolUse ALLOW-path response assembly. Reached only after every gate
+ * allowed (a deny/ask already returned upstream), so nothing here can block nor
+ * override a decision. Combines the Python-parity pass notice (systemMessage)
+ * with the single most-specific decision-time lesson (additionalContext), plus
+ * a compact "evidence fresh" compliance notice on the first APEX-scoped code
+ * Write/Edit that clears the freshness gate.
+ */
+import { designPassNotice } from "../policy/design/gates";
+import { resolveCorpusRoot } from "../policy/design/corpus";
+import { lessonFor } from "../policy/lessons/lesson-gate";
+import { lessonsFileFor } from "./lifecycle/lessons/state";
+import { projectRoot } from "../util/project-root";
+import { oncePerWindow } from "./inject-dedup";
+import { defaultStateDir } from "./paths";
+import { isApexScoped } from "./gate-helpers";
+import { REQUIRED_AGENTS, DEFAULT_WINDOW_MS } from "./gate";
+import { agentsFreshInTrack } from "../freshness/agent-evidence-record";
+import { loadTrack } from "../tracking/store";
+import { evidenceFreshNotice } from "./notices";
+import { respond } from "./respond";
+import type { NormalizedEvent } from "./normalize";
+import type { HandleOutcome } from "./handle";
+import type { Prompt } from "../prompt/types";
+
+/** Session-track + clock inputs the "evidence fresh" notice needs (absent = feature off, e.g. no caller-provided track file). */
+export interface EvidenceCheck {
+  /** Session track file path (same one the gate chain reads/writes). */
+  trackFile: string;
+  /** APEX freshness window in ms (defaults to {@link DEFAULT_WINDOW_MS}). */
+  windowMs?: number;
+  /** Event clock. */
+  now: number;
+}
+
+/**
+ * `✓ evidence fresh (explore+research)` for the first APEX-scoped Write/Edit
+ * that finds explore-codebase + research-expert evidence still within the
+ * freshness window — the user-visible confirmation for a gate that, until now,
+ * only ever spoke up when it BLOCKED. Deduped once per freshness window per
+ * session (same window the gate itself re-validates on), so it reads as "just
+ * confirmed", not a notice on every edit. Returns null for anything but a
+ * Write/Edit on an APEX-scoped path, or when evidence isn't fresh.
+ */
+async function freshEvidenceNotice(event: NormalizedEvent, evidence: EvidenceCheck, cwd: string): Promise<string | null> {
+  if ((event.tool !== "Write" && event.tool !== "Edit") || !isApexScoped(event.filePath)) return null;
+  const windowMs = evidence.windowMs ?? DEFAULT_WINDOW_MS;
+  const track = await loadTrack(evidence.trackFile);
+  if (!agentsFreshInTrack(track, REQUIRED_AGENTS, windowMs, evidence.now)) return null;
+  if (!oncePerWindow(`evidence-fresh:${event.sessionId}`, windowMs, { now: evidence.now, dir: defaultStateDir(cwd) })) return null;
+  return evidenceFreshNotice();
+}
+
+/**
+ * Build the native outcome for a PreToolUse call that passed every gate: emit a
+ * user-visible pass notice (once per allowed call), the "evidence fresh"
+ * compliance notice when applicable, and, when its TRIGGERS match this call,
+ * the one cooldown-guarded decision-time lesson. All 3 channels ride a single
+ * response (lesson → additionalContext, notices → systemMessage).
+ * @param id - Harness id for {@link respond}.
+ * @param event - The normalized PreToolUse event.
+ * @param payload - The raw hook payload (for `agent_id`).
+ * @param mcpDir - MCP state dir backing the pass-notice throttle.
+ * @param cwd - Project root (lesson file + notice scope).
+ * @param evidence - Session track + clock for the "evidence fresh" notice (omit to disable it).
+ * @returns The native hook outcome (empty stdout when nothing to emit).
+ */
+export async function allowOutcome(
+  id: string,
+  event: NormalizedEvent,
+  payload: Record<string, unknown>,
+  mcpDir: string,
+  cwd: string,
+  evidence?: EvidenceCheck,
+  corpusRoot?: string,
+): Promise<HandleOutcome> {
+  const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+  const notice = designPassNotice({
+    agentId,
+    tool: event.tool, filePath: event.filePath ?? "", content: event.content ?? "",
+    url: typeof event.input.url === "string" ? event.input.url : "", phase: "pre",
+    corpusMissing: agentId !== "" && (corpusRoot ?? resolveCorpusRoot()) === "",
+  }, mcpDir);
+  const lesson = lessonFor(event.tool, event.input, { file: lessonsFileFor(projectRoot(cwd)), once: oncePerWindow });
+  const evidenceNotice = evidence ? await freshEvidenceNotice(event, evidence, cwd) : null;
+  if (lesson) {
+    const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n") || undefined;
+    const merged = userMessage ? { ...lesson, userMessage } : lesson;
+    return { stdout: respond(id, merged, event.eventName ?? "PreToolUse"), exit: 0 };
+  }
+  if (evidenceNotice) {
+    const userMessage = [notice?.userMessage, evidenceNotice].filter(Boolean).join("\n");
+    const prompt: Prompt = notice ? { ...notice, userMessage } : { kind: "inform", title: "APEX freshness", reason: "", userMessage };
+    return { stdout: respond(id, prompt, event.eventName ?? "PreToolUse"), exit: 0 };
+  }
+  return { stdout: notice ? respond(id, notice, event.eventName ?? "PreToolUse") : "", exit: 0 };
+}

package/src/runtime/precommit.ts

@@ -0,0 +1,60 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Prompt } from "../prompt/types";
+
+const TIMEOUT_MS = 30_000;
+const ESLINT_CONFIGS: readonly string[] = [".eslintrc.json", ".eslintrc.js", "eslint.config.js", "eslint.config.mjs", "eslint.config.ts"];
+const PRETTIER_CONFIGS: readonly string[] = [".prettierrc", ".prettierrc.json", "prettier.config.js"];
+
+/** Run a linter; returns its error output, or "" if it passed / spawn-failed / timed out (fail-open). */
+function runLinter(file: string, args: string[], label: string, cwd: string): string {
+  try {
+    execFileSync(file, args, { cwd, timeout: TIMEOUT_MS, stdio: ["ignore", "pipe", "pipe"] });
+    return "";
+  } catch (e: unknown) {
+    const err = e as { status?: number | null; stdout?: Buffer; stderr?: Buffer };
+    if (err.status === undefined || err.status === null) return "";
+    const out = (err.stdout?.toString() ?? err.stderr?.toString() ?? "").trim();
+    return out ? `[${label}]\n${out}` : "";
+  }
+}
+
+/** Run the applicable linters in `cwd`, returning a block of errors per failing tool. */
+function collectErrors(cwd: string): string[] {
+  const has = (f: string): boolean => existsSync(join(cwd, f));
+  const errors: string[] = [];
+  if (has("package.json")) {
+    if (ESLINT_CONFIGS.some(has)) {
+      const m = runLinter("bunx", ["eslint", ".", "--max-warnings", "0"], "ESLint", cwd);
+      if (m) errors.push(m);
+    }
+    if (has("tsconfig.json")) {
+      const m = runLinter("bunx", ["tsc", "--noEmit"], "TypeScript", cwd);
+      if (m) errors.push(m);
+    }
+    if (PRETTIER_CONFIGS.some(has)) {
+      const m = runLinter("bunx", ["prettier", "--check", "."], "Prettier", cwd);
+      if (m) errors.push(m);
+    }
+  }
+  if (has("requirements.txt") || has("pyproject.toml")) {
+    const m = runLinter("ruff", ["check", "."], "Ruff", cwd);
+    if (m) errors.push(m);
+  }
+  return errors;
+}
+
+/** Block a `git commit` when linters fail (effectful: runs eslint/tsc/prettier/ruff, never auto-fixes). */
+export function preCommitGate(tool: string, command: string | undefined, cwd: string | undefined): Prompt | null {
+  if (tool !== "Bash" || !command || !cwd) return null;
+  if (!command.startsWith("git") || !command.includes("commit")) return null;
+  const errors = collectErrors(cwd);
+  if (!errors.length) return null;
+  return {
+    kind: "block",
+    title: "Pre-commit checks failed",
+    reason: `COMMIT BLOCKED — fix then retry:\n\n${errors.join("\n\n")}`,
+    actions: ["Fix the linter/type errors above", "Re-run the commit"],
+  };
+}

package/src/runtime/prompt-text.ts

@@ -0,0 +1,38 @@
+/**
+ * Normalizes a hook payload's `prompt` field across harness shapes: a plain
+ * string (Claude Code, Codex) or an array of content blocks (Kimi 0.31.1 —
+ * captured live: `[{"type":"text","text":"..."}]` on `UserPromptSubmit`).
+ * Never throws: this runs inside a hook, where an exception breaks the harness.
+ */
+
+/** A Kimi-shaped prompt content block: any object carrying a `text` string. */
+interface PromptTextBlock {
+  text: string;
+}
+
+/** True for an object whose `text` property is a string (the only field this reads). */
+function hasTextField(value: unknown): value is PromptTextBlock {
+  return typeof value === "object" && value !== null && typeof (value as { text?: unknown }).text === "string";
+}
+
+/**
+ * Coerce a hook payload's `prompt` field to plain text.
+ *
+ * - A string is returned AS-IS (same reference, no trim/normalize) — this is
+ *   the identity branch that guarantees zero regression on Claude Code/Codex,
+ *   whose `prompt` is already a string.
+ * - An array (Kimi's content-block shape) is flattened: every element with a
+ *   string `.text` is kept, joined with `"\n"` — one block per line, since
+ *   downstream consumers ({@link detectCreationIntent}, {@link detectMode})
+ *   only run `\b`-anchored regexes with no line-start/end assumption, so a
+ *   newline join is safe and reads like the multi-turn/multi-block source.
+ * - Anything else (`undefined`, `null`, a number, a plain object) yields `""`.
+ *
+ * @param value - The raw `prompt` field from a hook payload (unknown shape).
+ * @returns The prompt text, or `""` when it cannot be recovered.
+ */
+export function promptText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.filter(hasTextField).map((b) => b.text).join("\n");
+  return "";
+}

package/src/runtime/receipt-capture.ts

@@ -0,0 +1,34 @@
+/**
+ * Bash verification-receipt extraction for PostToolUse: a `tsc`/`bun test`
+ * run is parsed (exit code + output) into a signed receipt the TaskCompleted
+ * gate later demands. Structured responses ONLY: Kimi Code CLI sends
+ * `tool_output` as a truncated STRING (no exit_code, no stdout/stderr
+ * channels) — parsing it would forge a success receipt (`exit 0`, empty
+ * output) for possibly-failed runs, so a non-object source is skipped.
+ */
+import { captureReceipt } from "../tracking/receipts";
+
+/**
+ * Record a verification receipt for a Bash run when the response is structured.
+ * @param file - Session track file.
+ * @param tool - The tool name (only "Bash" receipts exist).
+ * @param command - The executed command.
+ * @param toolResult - `payload.tool_result` (preferred), when present.
+ * @param response - `payload.tool_response ?? payload.tool_output` fallback.
+ * @param now - Clock.
+ */
+export async function captureBashReceipt(
+  file: string,
+  tool: string,
+  command: string | undefined,
+  toolResult: unknown,
+  response: unknown,
+  now: number,
+): Promise<void> {
+  if (tool !== "Bash" || !command) return;
+  const r = (toolResult ?? response) as { exit_code?: unknown; stdout?: unknown; stderr?: unknown } | undefined;
+  if (!r || typeof r !== "object") return;
+  const out = `${typeof r.stdout === "string" ? r.stdout : ""}\n${typeof r.stderr === "string" ? r.stderr : ""}`;
+  const exit = Number(r.exit_code ?? 0);
+  await captureReceipt(file, command, out, Number.isFinite(exit) ? exit : 0, now);
+}

package/src/runtime/record.ts

@@ -0,0 +1,26 @@
+import { dirname } from "node:path";
+import { withTrack } from "../tracking/store";
+import { recordAgent, recordDoc, recordRefRead, type AgentQuality } from "../tracking/session-state";
+import { appendRefRead } from "../freshness/ref-journal";
+
+/** A unit of session activity to record (discriminated union on `kind`). */
+export type Activity =
+  | { kind: "agent"; name: string; ts: number; quality?: AgentQuality }
+  | { kind: "doc"; framework: string; sessionId: string; source: string; ts?: number }
+  | { kind: "ref"; path: string; ts?: number };
+
+/** Apply an activity to a session's track and persist it (PostToolUse path). */
+export async function recordActivity(file: string, activity: Activity): Promise<void> {
+  await withTrack(file, (track) =>
+    activity.kind === "agent"
+      ? recordAgent(track, activity.name, activity.ts, activity.quality)
+      : activity.kind === "doc"
+        ? recordDoc(track, activity.framework, activity.sessionId, activity.source, activity.ts)
+        : recordRefRead(track, activity.path, activity.ts),
+  );
+  // Mirror a `.md` ref read into the append-only journal: the racy load→save above
+  // loses a lone write under the hook fan-out, and a teammate's read has not yet
+  // flushed to the platform transcript at edit time (multi-minute lag > TTL) — the
+  // journal is the fresh, race-immune source the gate folds back (see ref-journal.ts).
+  if (activity.kind === "ref") appendRefRead(dirname(file), activity.path, activity.ts ?? Date.now());
+}

package/src/runtime/respond.ts

@@ -0,0 +1,92 @@
+import { formatPrompt, type Prompt } from "../prompt/types";
+import { denyResponse, contextResponse, informResponse } from "../adapters/claude";
+import { toHermesResponse } from "../adapters/hermes";
+import { toKimiResponse } from "../adapters/kimi";
+import { toCursorResponse } from "../adapters/cursor/respond";
+
+/**
+ * Map a portable {@link Prompt} to a harness's native hook response, honoring
+ * all 3 prompt kinds (`block`/`ask`/`inform`) instead of collapsing `ask` and
+ * `inform` together. Reuses the Claude adapter's `denyResponse`/
+ * `contextResponse`/`informResponse` builders for claude-code/codex (same hook
+ * shape) to avoid duplicating the JSON.
+ * - claude-code/codex: `block` -> deny, `ask` -> interactive
+ *   `permissionDecision:"ask"`, `inform` -> non-blocking `additionalContext`.
+ * - gemini-cli/cline: their real hook schemas have no interactive "ask"
+ *   state (deny is the only blocking outcome), so `ask` and `inform` already
+ *   both resolve to non-blocking context injection — unchanged.
+ * - cursor: `ask` degrades to a native `permission:"deny"` because Cursor does
+ *   not reliably apply `ask` on `preToolUse`; `inform` stays non-blocking.
+ * - hermes: delegated to the adapter's `toHermesResponse` — `block` ->
+ *   `{decision:"block",reason}`; `ask`/`inform` degrade to non-blocking
+ *   `{context}` (Hermes has no interactive "ask" state).
+ * - kimi: delegated to the adapter's `toKimiResponse` — `block`/`ask` ->
+ *   `hookSpecificOutput.permissionDecision:"deny"` (Kimi Code CLI's hooks
+ *   contract documents only "deny"; `ask` downgrades with a prefix, mirroring
+ *   the codex branch above), `inform` -> raw text on stdout (Kimi appends
+ *   stdout to context on exit 0 — no `hookSpecificOutput` envelope documented
+ *   for non-blocking context injection).
+ *
+ * User-visible pass notices (`prompt.userMessage`, Python `hook_output.allow_pass`
+ * / `post_pass` parity), by harness:
+ * - claude-code/codex: top-level `systemMessage` ("warning message shown to the
+ *   user"); a pure notice (empty `reason`) emits `{systemMessage}` alone. Codex
+ *   consumes the Claude hook schema, so it rides the same field.
+ * - gemini-cli: common `systemMessage` output field ("displayed immediately to
+ *   the user in the terminal") — the notice rides there.
+ * - cursor: `user_message` is its user-visible channel (see case comment).
+ * - cline: NO user-visible channel (`cancel`/`contextModification`/
+ *   `errorMessage`-on-cancel only) — the notice is dropped silently (a pure
+ *   notice returns "" = plain allow).
+ * @param id - Harness id.
+ * @param prompt - The portable prompt to render.
+ * @param event - The firing hook event name for the claude-code/codex branch
+ * (defaults to `"PreToolUse"`, the only phase every existing caller but
+ * `handle-post.ts` renders) — a POST-phase caller MUST pass `"PostToolUse"`
+ * (or its real raw event name) so `hookEventName` matches the event that
+ * actually fired instead of a hardcoded, wrong `"PreToolUse"`.
+ */
+export function respond(id: string, prompt: Prompt, event: string = "PreToolUse"): string {
+  const message = formatPrompt(prompt);
+  const { kind, userMessage, reason } = prompt;
+  switch (id) {
+    case "claude-code":
+    case "codex":
+      if (kind === "block") return denyResponse(event, message);
+      if (kind === "inform") {
+        return userMessage ? informResponse(event, userMessage, reason ? message : "") : contextResponse(event, message);
+      }
+      // Codex parses but NEVER honors `permissionDecision: "ask"` (deny-only) — an
+      // `ask` would silently fail open. Downgrade it to an explicit deny so the
+      // gate still bites; the reason is prefixed so the honest limit is visible.
+      if (id === "codex") {
+        return denyResponse(event, `[downgraded from ask — Codex has no interactive approval]\n${message}`);
+      }
+      return JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: event,
+          permissionDecision: "ask",
+          permissionDecisionReason: message,
+        },
+      });
+    case "gemini-cli":
+      if (kind === "block") return JSON.stringify({ decision: "deny", reason: message });
+      if (userMessage) return JSON.stringify({ ...(reason ? { hookSpecificOutput: { additionalContext: message } } : {}), systemMessage: userMessage });
+      return JSON.stringify({ hookSpecificOutput: { additionalContext: message } });
+    case "cursor":
+      return toCursorResponse(prompt, event === "PreToolUse" ? "preToolUse" : event);
+    case "hermes":
+      // Single source of truth for the Hermes wire shape lives in the adapter
+      // (same JSON.stringify contract as the inline cases above).
+      return toHermesResponse(prompt);
+    case "kimi":
+      // Single source of truth for the Kimi wire shape lives in the adapter.
+      return toKimiResponse(prompt);
+    case "cline":
+      if (kind === "block") return JSON.stringify({ cancel: true, errorMessage: message });
+      if (userMessage && !reason) return ""; // pure notice: no user-visible channel — silent allow
+      return JSON.stringify({ contextModification: message });
+    default:
+      return "";
+  }
+}