@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/modular.ts

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+import type { Prompt } from "../prompt/types";
+import { detectModularArchitecture } from "../policy/detect-project";
+
+const NEXT_CONVENTION = /^(page|layout|loading|error|not-found|route|template|default|global-error|opengraph-image|twitter-image|icon|apple-icon|sitemap|robots|manifest|middleware)\.(tsx|ts|js|jsx)$/;
+const NEXT_STATIC = /\.(css|ico|png|jpg|svg|json)$/;
+const PHP_BLOCKED_IN_APP: readonly string[] = [
+  "/app/Models/", "/app/Services/", "/app/Actions/", "/app/Http/Controllers/",
+  "/app/Http/Requests/", "/app/Http/Resources/", "/app/Contracts/", "/app/DTOs/",
+  "/app/Repositories/", "/app/Events/", "/app/Listeners/", "/app/Jobs/",
+  "/app/Notifications/", "/app/Policies/",
+];
+
+const block = (reason: string): Prompt => ({
+  kind: "block", title: "Modular architecture", reason,
+  actions: ["Move the code into the correct feature module", "Import only from the shared core module"],
+});
+
+/** Next.js `modules/` architecture: `app/` convention + cross-module import rules. */
+function nextModular(filePath: string, content: string, cwd: string): Prompt | null {
+  const rel = relative(cwd, filePath);
+  const bn = basename(filePath);
+  if ((rel.startsWith("app/") || rel.startsWith("src/app/")) && !NEXT_CONVENTION.test(bn) && !NEXT_STATIC.test(bn)) {
+    return block(`BLOCKED: modular Next.js — '${bn}' is not an app/ convention file. Move business logic to modules/[feature]/. Only page.tsx, layout.tsx, route.ts allowed in app/.`);
+  }
+  const mod = filePath.match(/\/modules\/([^/]+)\//);
+  if (!mod) return null;
+  const current = mod[1] ?? "";
+  for (const m of content.matchAll(/from\s+['"][@.][^'"]*?\/modules\/([^/]+)\//g)) {
+    const imported = m[1] ?? "";
+    if (current === "cores") {
+      if (imported !== "cores" && imported !== "core") return block(`BLOCKED: modules/cores/ must not import from modules/${imported}/. Cores must be independent.`);
+    } else if (imported !== current && imported !== "cores" && imported !== "core") {
+      return block(`BLOCKED: cross-module import — '${current}' imports from '${imported}'. Only modules/cores/ is shared.`);
+    }
+  }
+  return null;
+}
+
+/** Laravel FuseCore architecture: `app/` domain ban + module.json + cross-module `use` rules. */
+function fusecore(filePath: string, content: string, cwd: string): Prompt | null {
+  for (const b of PHP_BLOCKED_IN_APP) {
+    if (filePath.includes(b)) {
+      // Parity validate-fusecore.py:52-55 — name the precise target sub-path per
+      // entry (blocked.replace("/app/","/FuseCore/{Module}/App/")), not a generic dir.
+      const from = b.replace(/^\/|\/$/g, "");
+      const to = b.replaceAll("/app/", "/FuseCore/{Module}/App/").replace(/^\/|\/$/g, "");
+      return block(`BLOCKED: FuseCore project. Code in '${from}' FORBIDDEN. Move to '${to}'.`);
+    }
+  }
+  const mod = filePath.match(/\/FuseCore\/([A-Za-z]+)\//);
+  if (!mod) return null;
+  const name = mod[1] ?? "";
+  const mj = join(cwd, "FuseCore", name, "module.json");
+  // Parity validate-fusecore.py: name the full path to create ("Create {mj} first.").
+  if (!existsSync(mj)) return block(`BLOCKED: Module '${name}' missing module.json. Create ${mj} first.`);
+  for (const m of content.matchAll(/use\s+FuseCore\\(\w+)\\/g)) {
+    const imported = m[1] ?? "";
+    if (name === "Core") {
+      if (imported !== "Core") return block(`BLOCKED: FuseCore\\Core\\ must not use FuseCore\\${imported}\\.`);
+    } else if (imported !== name && imported !== "Core") {
+      return block(`BLOCKED: cross-module use — '${name}' uses '${imported}'. Only FuseCore\\Core\\ is shared.`);
+    }
+  }
+  return null;
+}
+
+/** Enforce the project's modular architecture (Next.js `modules/` or Laravel FuseCore) on a Write/Edit. */
+export function modularGate(tool: string, filePath: string | undefined, content: string | undefined, cwd: string | undefined): Prompt | null {
+  if ((tool !== "Write" && tool !== "Edit") || !filePath || !cwd) return null;
+  if (/\/(node_modules|dist|build|\.next|vendor|storage)\//.test(filePath)) return null;
+  const arch = detectModularArchitecture(cwd);
+  if (arch === "nextjs-modular" && /\.(tsx|ts|jsx|js)$/.test(filePath)) return nextModular(filePath, content ?? "", cwd);
+  if (arch === "fusecore" && filePath.endsWith(".php")) return fusecore(filePath, content ?? "", cwd);
+  return null;
+}

package/src/runtime/normalize.ts

@@ -0,0 +1,107 @@
+import { parseApplyPatch } from "../adapters/codex/apply-patch";
+import { extractCursorEvent } from "../adapters/cursor/normalize";
+import { commandToString } from "./command-string";
+import { canonicalizeCodexShellTool } from "./codex-shell-tool";
+import { canonicalizeMcpToolName } from "./mcp-tool-name";
+
+/** One file/edit fanned out from Codex `apply_patch` or Cursor `afterFileEdit`. */
+export interface NormalizedFile {
+  filePath: string;
+  content: string;
+  oldString?: string;
+  op: "add" | "update" | "delete";
+}
+
+/** A hook event normalized across harnesses. */
+export interface NormalizedEvent {
+  /** Native event name when the adapter exposes one explicitly (Cursor). */
+  eventName?: string;
+  phase: "pre" | "post";
+  tool: string;
+  input: Record<string, unknown>;
+  sessionId: string;
+  filePath?: string;
+  content?: string;
+  /** Edit only: the tool_input.old_string being replaced — lets the file-size gate (policy/evaluate.ts + policy/edit-outcome.ts) compute the post-edit outcome instead of judging the stale on-disk count alone. Undefined for Write (no such field) and for cline/apply_patch (parsed separately, no equivalent field). */
+  oldString?: string;
+  command?: string;
+  /** Cursor-only independent command candidates from beforeMCPExecution. */
+  commandCandidates?: string[];
+  /** Subagent type, if the tool-use came from one (Explore/Plan are file-size-exempt). */
+  agentType?: string;
+  /** Harness-resolved permission mode (Claude emits it natively; Codex maps `AskForApproval::Never` to the same "bypassPermissions" string — see adapters/codex/permission-mode.ts). Generic field, Codex-only consumer today. */
+  permissionMode?: string;
+  /** Codex logical tool-use identity, shared by sibling hook callbacks. */
+  toolUseId?: string;
+  /** Harness-reported working directory used to scope Codex authorization. */
+  cwd?: string;
+  /** Validated Cursor multi-root workspace paths in wire order. */
+  workspaceRoots?: string[];
+  /**
+   * Per-file changes for Codex `apply_patch` and per-edit changes for Cursor
+   * `afterFileEdit`; undefined for single-file events.
+   */
+  files?: NormalizedFile[];
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Normalize a hook payload, including Cline nesting and native Cursor events.
+ */
+export function normalizeEvent(id: string, payload: Record<string, unknown>): NormalizedEvent {
+  if (id === "cline") {
+    const post = payload.postToolUse as Record<string, unknown> | undefined;
+    const node = (post ?? (payload.preToolUse as Record<string, unknown> | undefined)) ?? {};
+    const params = (node.parameters as Record<string, unknown> | undefined) ?? {};
+    return {
+      phase: post ? "post" : "pre",
+      tool: str(node.toolName) ?? "",
+      input: params,
+      sessionId: str(payload.taskId) ?? "",
+      filePath: str(params.path),
+      content: str(params.content),
+      command: str(params.command),
+    };
+  }
+  if (id === "cursor") {
+    return {
+      ...extractCursorEvent(payload),
+      sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
+      agentType: str(payload.agent_type),
+      permissionMode: str(payload.permission_mode),
+    };
+  }
+  const event = str(payload.hook_event_name) ?? "";
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? payload;
+  const tool = canonicalizeCodexShellTool(id, canonicalizeMcpToolName(id, str(payload.tool_name) ?? ""));
+  const base = {
+    phase: (/post|after/i.test(event) ? "post" : "pre") as "pre" | "post",
+    tool,
+    input,
+    sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
+    agentType: str(payload.agent_type) ?? str(input.subagent_type),
+    permissionMode: str(payload.permission_mode),
+    toolUseId: str(payload.tool_use_id),
+    cwd: str(payload.cwd),
+  };
+  // Codex's `apply_patch` (its PRIMARY edit primitive) carries the whole change
+  // set as a freeform patch in `command` — no `file_path`/`content`, so the
+  // file-size/DRY/protected-path gates saw nothing (enforcement 0%). Fan it out
+  // into `files` and DROP the patch text from `command` so it can't false-match
+  // the git guards. Every other tool is untouched below.
+  if (tool === "apply_patch") {
+    const patch = str(input.command) ?? str(payload.command) ?? "";
+    const files = parseApplyPatch(patch).map((f) => ({ filePath: f.path, content: f.content, op: f.op }));
+    return { ...base, phase: base.phase, files: files.length > 0 ? files : undefined };
+  }
+  return {
+    ...base,
+    filePath: str(input.file_path) ?? str(input.path) ?? str(payload.file_path),
+    content: str(input.content) ?? str(input.new_string),
+    oldString: str(input.old_string),
+    command: commandToString(input.command) ?? commandToString(payload.command),
+  };
+}

package/src/runtime/notices.ts

@@ -0,0 +1,91 @@
+/**
+ * @module notices
+ * Compact, uniform "compliance" notices for the user-visible `systemMessage`
+ * channel — the visual counterpart to the additionalContext-only gate/credit
+ * signals, which land in agent-only context and stay invisible to the human in
+ * the Claude Code UI (deny reasons show in red; these did not show at all).
+ * Owner-reported gap: pass-notices existed in v0.1.49 for design gates, but
+ * nothing surfaced skill credits, freshness, or the sniper reminder to the human.
+ *
+ * The text builders are pure. `refCreditNoticeFor` is the one exception — like
+ * `pre-allow.ts` uses the JSON `oncePerWindow`, this one uses the exclusive
+ * {@link onceExclusive} mode instead: it fires on the same short burst window
+ * as `track-changes.ts`'s sniper reminder, fanned out across every installed
+ * plugin's PostToolUse hook for ONE real edit, so the same lost-update race
+ * applies (lesson 2026-07-05 16:00). Rendering onto a harness's native stdout
+ * always goes through the existing adapter helpers (`respond`/
+ * `attachSystemMessage`); a harness with no `systemMessage` channel (e.g.
+ * cline) silently drops the notice there (documented no-op, never a crash) —
+ * nothing in this module renders directly.
+ *
+ * CHANNEL CONTRACT — human-only, exactly once: the `userMessage`/`systemMessage`
+ * these notices ride is a HUMAN channel by platform contract. It never reaches
+ * the agent — `formatPrompt` (src/prompt/types.ts) excludes it — so the emitting
+ * sub-agent does NOT see its own notice; only the human owner does, and exactly
+ * ONCE even under the multi-plugin fan-out, because the emitter is gated by
+ * {@link onceExclusive}. Verified live 2026-07-06: under the real ×11 fan-out a
+ * single skill-ref Read surfaced one `✓ SOLID refs read` line in the owner's
+ * terminal (not duplicated, and correctly invisible to the agent).
+ */
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+
+/** One compliance line: `✓ <gate> — <detail>` (detail omitted when empty). */
+export function complianceNotice(gate: string, detail: string): string {
+  return detail ? `✓ ${gate} — ${detail}` : `✓ ${gate}`;
+}
+
+/** One non-blocking requirement line: `⚠ <requirement> — <detail>`. */
+export function requirementNotice(requirement: string, detail: string): string {
+  return detail ? `⚠ ${requirement} — ${detail}` : `⚠ ${requirement}`;
+}
+
+/** Extract the skill name from a `.md` ref path (`.../skills/<name>/...`), or null when it isn't a skill reference (a banal doc Read — no notice). */
+export function skillNameFromRefPath(path: string): string | null {
+  const m = /skills\/([^/]+)\//.exec(path);
+  return m?.[1] ?? null;
+}
+
+/** Notice for a SOLID/skill reference credited via an in-session Read, or null for a non-skill `.md`. */
+export function refCreditedNotice(path: string): string | null {
+  const skill = skillNameFromRefPath(path);
+  return skill ? complianceNotice("SOLID refs read", skill) : null;
+}
+
+/** Notice for the APEX freshness gate (explore+research) currently satisfied. */
+export function evidenceFreshNotice(): string {
+  return complianceNotice("evidence fresh", "explore+research");
+}
+
+/** Notice mirroring the existing sniper-required additionalContext reminder. */
+export function sniperRequiredNotice(fileName: string): string {
+  return requirementNotice("sniper required", fileName);
+}
+
+/**
+ * The one `✓ SOLID refs read (<skill>)` notice to show for this PostToolUse
+ * call, or null. Scans the activities `activityFor` recorded from this event
+ * for a skill-ref Read, deduped per (session, path) against the same burst
+ * window as the sniper reminder — the ~11 sibling-plugin fan-out for one real
+ * Read must never repeat it (lesson 2026-07-05 15:21).
+ * @param activities - This event's recorded activities (only `ref` entries matter).
+ * @param sessionId - Current session id (dedup scope).
+ * @param now - Event clock.
+ * @param dir - State-dir override for the dedup sidecar (tests MUST pass an
+ *   isolated dir; production passes the per-project state dir).
+ */
+export function refCreditNoticeFor(
+  activities: ReadonlyArray<{ kind: string; path?: string }>,
+  sessionId: string,
+  now: number,
+  dir?: string,
+): string | null {
+  for (const a of activities) {
+    if (a.kind !== "ref" || !a.path) continue;
+    const notice = refCreditedNotice(a.path);
+    if (!notice) continue;
+    if (!onceExclusive(`ref-credited:${sessionId}:${a.path}`, BURST_DEDUP_MS, { now, dir })) continue;
+    return notice;
+  }
+  return null;
+}

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 };
+}