@fusengine/harness 0.1.92 → 0.1.94

package/src/runtime/prd/prd-candidate-files.ts

@@ -0,0 +1,23 @@
+/**
+ * @module prd-candidate-files
+ * Shared candidate-path extraction for a hook event, used by both
+ * {@link prdPreGate} and {@link prdPostCheck} — the fanned-out
+ * `apply_patch`/`afterFileEdit` set when present, else the single
+ * `event.filePath`.
+ */
+import type { NormalizedEvent } from "../normalize";
+
+/**
+ * @param event - The normalized hook event.
+ * @param restrictToWrite - When true (PreToolUse — the default), a bare
+ * `event.filePath` only counts for `Write`/`Edit` (never a `Read`, which must
+ * stay unaffected by the ownership gate). PostToolUse call sites pass
+ * `false`: they only ever see a real Write/Edit-shaped event already.
+ * @returns The candidate file paths (possibly empty).
+ */
+export function prdCandidateFiles(event: NormalizedEvent, restrictToWrite = true): string[] {
+  if (event.files?.length) return event.files.map((f) => f.filePath);
+  if (!event.filePath) return [];
+  if (restrictToWrite && event.tool !== "Write" && event.tool !== "Edit") return [];
+  return [event.filePath];
+}

package/src/runtime/prd/prd-canon.ts

@@ -0,0 +1,50 @@
+/**
+ * @module prd-canon
+ * Best-effort symlink canonicalization for the paths `prdPreGate`/
+ * `prdPostCheck` feed into lot A's pure `isPrdScopedPath`/`classifyPrdPath`
+ * (documented "string/path compare only — no fs", by design). Those
+ * comparisons need `root` and each candidate file path on the SAME
+ * representation — but on macOS, `process.cwd()` inside a spawned process
+ * resolves `/var` to its canonical `/private/var` while a caller-constructed
+ * absolute path (e.g. from `os.tmpdir()`) may still carry the unresolved
+ * `/var` alias, so two paths naming the identical file compare unequal.
+ * Same `realpathSync.native` + raw-path-on-failure idiom already used by
+ * `adapters/cursor/context.ts`'s `cursorAbsolutePath`.
+ */
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, sep } from "node:path";
+
+/** Canonicalizes an existing directory (e.g. the project root); the raw value on failure. */
+export function canonicalRoot(root: string): string {
+  try {
+    return realpathSync.native(root);
+  } catch {
+    return root;
+  }
+}
+
+/**
+ * Canonicalizes an absolute file path that may not exist yet — including
+ * under a brand-new subdirectory (e.g. a task's FIRST `prd/docs/<task>.md`,
+ * whose `docs/` dir doesn't exist yet either): walks up from the full path,
+ * dropping one segment at a time, until an ancestor resolves, then rejoins
+ * the non-existent tail onto that canonical prefix. `root` itself always
+ * resolves (guaranteed present by `isPrdEnabled`), so this always terminates
+ * on a real answer for any path actually under the project root. A relative
+ * path is returned as-is (no `root` to anchor a symlink comparison against).
+ */
+export function canonicalFilePath(path: string): string {
+  if (!isAbsolute(path)) return path;
+  const parts = path.split(sep);
+  for (let end = parts.length; end > 0; end--) {
+    const prefix = parts.slice(0, end).join(sep) || sep;
+    try {
+      const real = realpathSync.native(prefix);
+      const tail = parts.slice(end);
+      return tail.length > 0 ? join(real, ...tail) : real;
+    } catch {
+      continue; // try a shorter, more likely to exist, ancestor
+    }
+  }
+  return path;
+}

package/src/runtime/prd/prd-identity.ts

@@ -0,0 +1,32 @@
+/**
+ * @module prd-identity
+ * Resolve a {@link PrdIdentity} from a normalized hook event. Structural, not
+ * field-presence-based: Cursor and Kimi NEVER carry `agent_id`/`agent_type` on
+ * a sub-agent's own tool-use (live-captured — see the PRD design doc Risks
+ * §1/§2), so on those two targets the absence of `agentId` is NOT evidence of
+ * being the lead — it is a harness ceiling, and the verdict must stay
+ * `"unknown"` (advisory, never a hard block) regardless of what the payload
+ * carries. Every other target (claude-code, codex, and any future harness
+ * sharing their schema) DOES carry `agent_id` on a real sub-agent call, so
+ * there `agentId`'s absence structurally proves "this is the lead".
+ */
+import type { NormalizedEvent } from "../normalize";
+import type { PrdIdentity } from "../../policy/prd/interfaces/types";
+
+/** Harness targets whose payloads never carry per-event agent identity (live-confirmed for Cursor; documented schema for Kimi — design doc Risks §1/§2). */
+const NO_IDENTITY_SUPPORT: ReadonlySet<string> = new Set(["cursor", "kimi"]);
+
+/**
+ * Resolve the PRD identity of the current tool-use.
+ * @param id - Harness target id (e.g. "claude-code", "codex", "cursor", "kimi").
+ * @param event - The normalized hook event (reads `agentId`/`agentType`).
+ * @returns The resolved {@link PrdIdentity} — `lead: "unknown"` on Cursor/Kimi,
+ * `lead: true` when no `agentId` is present elsewhere, `lead: false` (with
+ * whatever `agentType` came along, possibly undefined — see design Risks §4)
+ * otherwise.
+ */
+export function resolvePrdIdentity(id: string, event: NormalizedEvent): PrdIdentity {
+  if (NO_IDENTITY_SUPPORT.has(id)) return { lead: "unknown", agentId: event.agentId, agentType: event.agentType };
+  if (!event.agentId) return { lead: true };
+  return { lead: false, agentId: event.agentId, agentType: event.agentType };
+}

package/src/runtime/prd/prd-post-check.ts

@@ -0,0 +1,73 @@
+/**
+ * @module prd-post-check
+ * PostToolUse cross-check (design doc §2.2). Side-effect only — never
+ * produces stdout. Fires only when the touched path just resolved to a
+ * task-PRD or the router (the only two places a `validated` status is
+ * asserted), reloads every named agent's own report, and journals any NEW
+ * cross-check violation (deduped by `{task,agent,sub,reason}` so a repeated
+ * PostToolUse on the same file never re-appends the same finding).
+ */
+import { hashText } from "../../util/json-io";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  classifyPrdPath, crossCheckTask, isPrdEnabled, prdProjectRoot,
+  readAgentReport, readRouter, readTaskFile,
+  type PrdAgentReportFile, type PrdCrossCheckViolation,
+} from "../../policy/prd";
+import { withTrack } from "../../tracking/store";
+import { recordPrdViolation } from "../../tracking/session-state";
+import { prdCandidateFiles } from "./prd-candidate-files";
+import { canonicalFilePath, canonicalRoot } from "./prd-canon";
+import type { NormalizedEvent } from "../normalize";
+
+/** Stable dedup key for one violation, shared across replays of the same PostToolUse. */
+function violationKey(v: PrdCrossCheckViolation): string {
+  return hashText(JSON.stringify([v.task, v.agent, v.sub, v.reason]));
+}
+
+/**
+ * Run the PRD PostToolUse cross-check. Side-effect only — journals new
+ * violations, never returns anything to render.
+ */
+export async function prdPostCheck(id: string, event: NormalizedEvent, cwd: string, trackFilePath: string, now: number): Promise<void> {
+  if (!isPrdEnabled(cwd, id)) return;
+  const root = canonicalRoot(prdProjectRoot(cwd)); // see prd-canon.ts — same representation as the candidate file paths below
+  const homeSeg = harnessHomeSegment(id);
+  const router = await readRouter(root, homeSeg);
+  if (!router) return;
+
+  const files = prdCandidateFiles(event, false).map(canonicalFilePath);
+  const touchedTasks = new Set<string>();
+  for (const f of files) {
+    const kind = classifyPrdPath(f, root, homeSeg, router);
+    if (kind?.kind === "task") touchedTasks.add(kind.task);
+    else if (kind?.kind === "router") for (const task of Object.keys(router)) touchedTasks.add(task);
+  }
+  if (touchedTasks.size === 0) return;
+
+  const violations: PrdCrossCheckViolation[] = [];
+  for (const task of touchedTasks) {
+    const entry = router[task];
+    if (!entry) continue;
+    const taskFile = await readTaskFile(root, homeSeg, entry.prd);
+    if (!taskFile) continue;
+    const reports: Record<string, PrdAgentReportFile> = {};
+    for (const agent of Object.keys(taskFile)) {
+      const report = await readAgentReport(root, homeSeg, agent);
+      if (report) reports[agent] = report;
+    }
+    violations.push(...crossCheckTask(taskFile, reports, task));
+  }
+  if (violations.length === 0) return;
+
+  await withTrack(trackFilePath, (t) => {
+    const known = new Set((t.prdViolations ?? []).map(violationKey));
+    let next = t;
+    for (const v of violations) {
+      if (known.has(violationKey(v))) continue;
+      known.add(violationKey(v));
+      next = recordPrdViolation(next, { ...v, ts: now });
+    }
+    return next;
+  });
+}

package/src/runtime/prd/prd-pre-gate.ts

@@ -0,0 +1,172 @@
+/**
+ * @module prd-pre-gate
+ * PreToolUse orchestrator for the PRD module (design doc §2.0/§2.1). Inert
+ * unless {@link isPrdEnabled}: one env read + one `statSync`, zero further
+ * disk access. When active, denies a Bash write under `apex/prd/` for
+ * EVERYONE (no identity check needed — see below) — covering both shell
+ * output redirects (`>`/`>>`, `shellOutputRedirects`) AND the non-redirect
+ * write verbs `cp`, `mv`, `tee`, `sed -i`/`perl -i`, `install`, `dd of=`
+ * (`extraBashWriteTargets`, `prd-bash-targets.ts`) — then resolves ownership
+ * for Write/Edit/apply_patch/afterFileEdit targets and either short-circuits
+ * past `gate()`/`protectedPathGuard` with an allow, or returns the standard
+ * deny — never both, never a silent pass-through of a denied write.
+ */
+import { dirname } from "node:path";
+import type { Prompt } from "../../prompt/types";
+import { respond } from "../respond";
+import { withDenyNotice } from "../deny-notice";
+import { allowOutcome } from "../pre-allow";
+import { projectLayout } from "../../config/layout";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import { shellOutputRedirects } from "../../policy/guards/bash-write-redirects";
+import { extraBashWriteTargets } from "./prd-bash-targets";
+import {
+  candidateAgentNames, classifyPrdPath, evaluateWriteOwnership, isPrdEnabled, isPrdScopedPath,
+  prdProjectRoot, readAllTaskFiles, readRouter,
+  type PrdOwnershipVerdict, type PrdPathKind, type PrdTaskFile,
+} from "../../policy/prd";
+import { loadTrack, withTrack } from "../../tracking/store";
+import { recordPrdOwner } from "../../tracking/session-state";
+import { resolvePrdIdentity } from "./prd-identity";
+import { prdCandidateFiles } from "./prd-candidate-files";
+import { canonicalFilePath, canonicalRoot } from "./prd-canon";
+import type { NormalizedEvent } from "../normalize";
+import type { HandleOutcome } from "../handle";
+
+const ACTIONS = ["Write only the files/report this agent owns per its PRD slice", "Run `harness prd status` to see the current assignment"];
+
+function denyOutcome(id: string, event: NormalizedEvent, trackFilePath: string, now: number, reason: string): HandleOutcome {
+  const prompt: Prompt = { kind: "block", ruleId: "prd-ownership", title: "PRD ownership", reason, actions: ACTIONS };
+  return { stdout: withDenyNotice(id, respond(id, prompt, event.eventName ?? "PreToolUse"), prompt, event.sessionId, dirname(trackFilePath), now), exit: 0 };
+}
+
+/**
+ * Narrows `taskFile` to the names `evaluateWriteOwnership` needs to correctly
+ * resolve a SPECIFIC requested agent-report name, WITHOUT changing lot A's
+ * pure `resolveOwnerBinding`/`evaluateWriteOwnership` (unmodified) — a lot B
+ * integration adapter around a real call-site gap, not a policy change.
+ *
+ * Two rules, matching the design's "first-come, exact-name-first" contract:
+ * - `target === agentType` (claiming YOUR OWN exact name): always legitimate
+ *   on a cold start — narrow to just `target`, so a same-type SIBLING's mere
+ *   existence never manufactures a false "ambiguous" (`resolveOwnerBinding`
+ *   otherwise sees 2 equally-free candidates and gives up for BOTH).
+ * - `target !== agentType` (claiming a "-n" SIBLING slot): only legitimate
+ *   once the EXACT-match name is already claimed by someone else — keep
+ *   BOTH names, so `resolveOwnerBinding` sees 2 free candidates (denied,
+ *   ambiguous) until the exact slot is taken, then exactly 1 (allowed).
+ * In every case, this agentId's own EXISTING binding (if any) and every
+ * name already claimed by anyone are also kept, so a mismatch against an
+ * established binding is still caught (never silently dropped from view).
+ */
+function narrowForTarget(taskFile: PrdTaskFile, agentType: string, target: string, agentId: string, bindings: Record<string, string>): PrdTaskFile {
+  const allCandidates = candidateAgentNames(agentType, taskFile);
+  const keep = new Set<string>([target]);
+  if (target !== agentType) keep.add(agentType);
+  const myBinding = bindings[agentId];
+  if (myBinding !== undefined) keep.add(myBinding);
+  for (const name of Object.values(bindings)) keep.add(name);
+  const out: PrdTaskFile = {};
+  for (const name of allCandidates) {
+    const entry = taskFile[name];
+    if (keep.has(name) && entry) out[name] = entry;
+  }
+  return out;
+}
+
+/** The task-PRD (if any) that declares `agent` as a literal key, across every task in the router. */
+function governingTaskFile(agent: string, taskFiles: Record<string, PrdTaskFile | null>): PrdTaskFile | null {
+  for (const tf of Object.values(taskFiles)) {
+    if (tf && Object.hasOwn(tf, agent)) return tf;
+  }
+  return null;
+}
+
+/**
+ * Run the PreToolUse PRD gate.
+ * @returns The native outcome (allow bypassing `gate()`, or deny), or `null`
+ * to fall through to the ordinary pipeline (module off, or nothing in scope).
+ */
+export async function prdPreGate(
+  id: string,
+  payload: Record<string, unknown>,
+  event: NormalizedEvent,
+  cwd: string,
+  trackFilePath: string,
+  now: number,
+): Promise<HandleOutcome | null> {
+  if (!isPrdEnabled(cwd, id)) return null;
+  // Canonicalized once: `isPrdScopedPath`/`classifyPrdPath` are pure
+  // string/path compares (lot A, by design, no fs) — on macOS, `cwd` (from a
+  // spawned process) resolves `/var` to `/private/var` while a caller's own
+  // absolute path may still carry the unresolved alias, so root and target
+  // must share ONE representation before any comparison (prd-canon.ts).
+  const root = canonicalRoot(prdProjectRoot(cwd));
+  const homeSeg = harnessHomeSegment(id);
+
+  if (event.tool === "Bash" && event.command) {
+    const redirectHit = shellOutputRedirects(event.command).some((r) => isPrdScopedPath(canonicalFilePath(r.target), root, homeSeg));
+    // Beyond `>`/`>>` redirects: cp/mv/tee/sed -i/perl -i/install/dd of= also
+    // write a file without any redirect operator (prd-bash-targets.ts, local
+    // to this module — never merged into the shared bash-write-redirects.ts/
+    // protectedPathGuard, see that file's own header for why).
+    const verbHit = extraBashWriteTargets(event.command).some((t) => isPrdScopedPath(canonicalFilePath(t), root, homeSeg));
+    if (redirectHit || verbHit) return denyOutcome(id, event, trackFilePath, now, "PRD files must be written via Write/Edit/apply_patch, never Bash.");
+  }
+
+  const files = prdCandidateFiles(event).map(canonicalFilePath);
+  if (files.length === 0) return null;
+
+  const router = await readRouter(root, homeSeg);
+  if (router === null) {
+    if (!files.some((f) => isPrdScopedPath(f, root, homeSeg))) return null;
+    return denyOutcome(id, event, trackFilePath, now, "PRD router is malformed JSON — fix apex/prd.json or unset FUSE_PRD.");
+  }
+
+  const inScope = files
+    .map((f) => ({ file: f, kind: classifyPrdPath(f, root, homeSeg, router) }))
+    .filter((c): c is { file: string; kind: PrdPathKind } => c.kind !== null && c.kind.kind !== "other");
+  if (inScope.length === 0) return null;
+
+  const identity = resolvePrdIdentity(id, event);
+  const track = await loadTrack(trackFilePath);
+  // Mutated in-loop (never the loaded track): a 2nd agent-report file in the
+  // SAME envelope must see the 1st file's pending bind, or a single agentId
+  // could claim two different agent names in one apply_patch batch (each
+  // looks free in isolation otherwise).
+  let bindings = { ...(track.prdOwners ?? {}) };
+  const taskFiles = inScope.some((c) => c.kind.kind === "agentReport") ? await readAllTaskFiles(root, homeSeg, router) : {};
+
+  const binds: { agentId: string; name: string }[] = [];
+  for (const { file, kind } of inScope) {
+    let taskFile: PrdTaskFile | null = null;
+    if (kind.kind === "agentReport") {
+      const governing = governingTaskFile(kind.agent, taskFiles);
+      taskFile = governing && identity.agentType !== undefined && identity.agentId !== undefined
+        ? narrowForTarget(governing, identity.agentType, kind.agent, identity.agentId, bindings)
+        : governing;
+    }
+    const verdict: PrdOwnershipVerdict = evaluateWriteOwnership({ kind, identity, taskFile, bindings });
+    if (verdict.allow === false) return denyOutcome(id, event, trackFilePath, now, `${file}: ${verdict.reason}`);
+    if (verdict.allow === true && verdict.bind) {
+      binds.push(verdict.bind);
+      bindings = { ...bindings, [verdict.bind.agentId]: verdict.bind.name };
+    }
+  }
+
+  // A mixed envelope (some candidate files never classified in-scope by
+  // classifyPrdPath, e.g. a genuinely unrelated file bundled into the SAME
+  // apply_patch) must never ride THIS allow past applyPatchGate/gate() for
+  // those other files — only a PURE-PRD envelope (every candidate file
+  // in-scope) may short-circuit. A denial above (ownership violation on an
+  // in-scope file) still fires regardless of mixing; only the ALLOW path is
+  // restricted here, so it never becomes a silent bypass for an unclassified
+  // file the PRD gate was never meant to authorize.
+  if (inScope.length !== files.length) return null;
+
+  if (binds.length > 0) {
+    await withTrack(trackFilePath, (t) => binds.reduce((acc, b) => recordPrdOwner(acc, b.agentId, b.name), t));
+  }
+  const mcpDir = projectLayout(cwd).cacheDir;
+  return allowOutcome(id, event, payload, mcpDir, cwd, { trackFile: trackFilePath, now });
+}

package/src/runtime/prd/prd-stop-gate.ts

@@ -0,0 +1,167 @@
+/**
+ * @module prd-stop-gate
+ * Block-once gate for the LEAD's `Stop` event when the router carries an
+ * unresolved PRD cross-check violation (design doc §2.5). SYNC, same
+ * one-shot idiom as {@link prdSubagentStopGate}, keyed `sessionId:Stop`
+ * instead of per-agent. Covers Codex too — its `Stop` already routes to
+ * `stopCore` under `scope === "core"`.
+ */
+import { dirname } from "node:path";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  canPromoteRouterEntry, hasAnyViolations, isCompacted, isPrdEnabled, prdProjectRoot,
+  readRouterSync, readTaskFileSync, subTasksOf, type PrdRouter, type PrdTaskFile,
+} from "../../policy/prd";
+import { journalLogPath, readTrackSync } from "../../tracking/track-compact";
+import { trackJournalEnabled } from "../../tracking/store";
+import { appendEvent } from "../../tracking/track-journal";
+import { diffTrackEvents } from "../../tracking/track-diff";
+import { prdAlreadyBlocked, recordPrdStopBlocked, type SessionTrack } from "../../tracking/session-state";
+import { signTrack, writeLastNonce } from "../../tracking/integrity";
+import { withTrackLockSync } from "../../tracking/track-lock-sync";
+import { atomicWrite } from "../../util/json-io";
+import { blockResponse, contextResponse } from "../../adapters/claude";
+import { respond } from "../respond";
+
+const REASON = "PRD cross-check found unresolved violation(s): a task/sub-task is marked validated without a matching done report. Run `harness prd status` for details.";
+
+/** Sync twin of `readAllTaskFiles` (lot A only exposes the async variant). */
+function readAllTaskFilesSync(root: string, homeSeg: string, router: PrdRouter): Record<string, PrdTaskFile | null> {
+  const out: Record<string, PrdTaskFile | null> = {};
+  for (const [task, entry] of Object.entries(router)) out[task] = readTaskFileSync(root, homeSeg, entry.prd);
+  return out;
+}
+
+/**
+ * Persist the one-shot block marker on the SAME side `trackJournalEnabled()`
+ * reads from. Twin of `prd-subagent-stop.ts`'s own `persistStopBlocked`
+ * (intentionally duplicated, not cross-imported — same SOLID file-size
+ * discipline as this module's other duplicated helpers, e.g.
+ * `readAllTaskFilesSync`). Bug this fixes: the old code always appended to
+ * the journal regardless of mode, but `readTrackSync(file,
+ * trackJournalEnabled())` never folds the log when `FUSE_TRACK_JOURNAL=0`
+ * (track-compact.ts) — so a legacy replay never saw the marker and
+ * re-blocked the lead's Stop on every call.
+ */
+function persistStopBlocked(trackFilePath: string, track: SessionTrack, key: string, now: number): void {
+  if (trackJournalEnabled()) {
+    const next = recordPrdStopBlocked(track, key, now);
+    for (const ev of diffTrackEvents(track, next, now)) appendEvent(journalLogPath(trackFilePath), ev.field, ev.op, ev.value, ev.ts);
+    return;
+  }
+  withTrackLockSync(dirname(trackFilePath), () => {
+    const fresh = readTrackSync(trackFilePath, false); // reload under lock: avoid clobbering a concurrent legacy RMW
+    const envelope = signTrack(recordPrdStopBlocked(fresh, key, now));
+    atomicWrite(trackFilePath, JSON.stringify(envelope, null, 2));
+    writeLastNonce(envelope.nonce);
+  });
+}
+
+/** Task names whose task-PRD is fully validated (every agent, every sub-task) but not yet compacted (`prd-compact.ts`'s own per-agent test, applied task-wide). */
+function compactableTasks(router: PrdRouter, taskFiles: Record<string, PrdTaskFile | null>): string[] {
+  const ready: string[] = [];
+  for (const task of Object.keys(router)) {
+    const taskFile = taskFiles[task];
+    if (!taskFile || canPromoteRouterEntry(taskFile)) continue; // missing/unparseable, or already fully compacted
+    const fullyValidated = Object.values(taskFile).every((entry) => {
+      if (isCompacted(entry)) return true;
+      const subs = Object.values(subTasksOf(entry));
+      return subs.length > 0 && subs.every((s) => s.status === "validated");
+    });
+    if (fullyValidated) ready.push(task);
+  }
+  return ready;
+}
+
+/** Names the compactable task(s) and the exact `harness prd compact` invocation (verified against `cli/prd/compact.ts`'s own usage string). */
+function compactHintText(tasks: string[]): string {
+  if (tasks.length === 1) return `PRD task "${tasks[0]}" is fully validated and ready to compact. Run \`harness prd compact ${tasks[0]}\`.`;
+  return `PRD tasks fully validated and ready to compact: ${tasks.join(", ")}. Run \`harness prd compact <task>\` for each.`;
+}
+
+/**
+ * Non-blocking "ready to compact" hint. Target-agnostic by design: an id
+ * allowlist here would silently go stale the day a target's real Stop wiring
+ * changes, so this mirrors the SAME per-target form choice as the block path
+ * directly below instead of hardcoding one target — kimi/gemini-cli/cline
+ * get their own native `respond()` inform envelope, everyone else gets the
+ * `Stop` `additionalContext` channel. Whether this function is ever REACHED
+ * for a given id is a wiring question, not a code question: measured live
+ * against the real hooks.json this project ships (claude-plugins/
+ * codex-plugins/kimi-code-plugins) plus each target's own hook docs — only
+ * Codex's Stop wiring is a plain `hook codex core` with no short-circuit;
+ * claude-code's and Kimi's own Stop hook always carries `--sound stop`,
+ * which exits in `maybePlaySound()` (`src/cli/hook-sound.ts`) before stdin
+ * is ever read, and hermes/gemini-cli/cline have no event literally named
+ * `Stop` in their own documented hook taxonomy at all — see prd.md's Known
+ * limitations for the full measurement. One-shot per session, on a marker
+ * key DISTINCT from the block-once key so neither shadows the other.
+ * @param id - Harness target id.
+ * @param payload - The raw Stop hook payload.
+ * @param router - The parsed router.
+ * @param taskFiles - Every router task's parsed task-PRD (or `null`).
+ * @param track - The current session track.
+ * @param trackFilePath - The session track file path.
+ * @param now - Event clock.
+ * @returns The native non-blocking stdout (once per session), else `""`.
+ */
+function compactReminder(
+  id: string, payload: Record<string, unknown>, router: PrdRouter,
+  taskFiles: Record<string, PrdTaskFile | null>, track: SessionTrack, trackFilePath: string, now: number,
+): string {
+  const ready = compactableTasks(router, taskFiles);
+  if (ready.length === 0) return "";
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const key = `${sessionId}:StopCompactHint`;
+  if (prdAlreadyBlocked(track, key)) return "";
+  persistStopBlocked(trackFilePath, track, key, now);
+  const text = compactHintText(ready);
+  if (id === "kimi" || id === "gemini-cli" || id === "cline") {
+    return respond(id, { kind: "inform", title: "PRD compact", reason: text }, "Stop");
+  }
+  return contextResponse("Stop", text);
+}
+
+/**
+ * Run the PRD lead-Stop block-once gate.
+ * @param payload - The raw Stop hook payload.
+ * @param cwd - Project root.
+ * @param id - Harness target id.
+ * @param trackFilePath - The session track file path.
+ * @param now - Event clock.
+ * @returns The native block stdout (once per session); else the compact
+ * hint (once per session, whichever ids' real Stop wiring reaches it); else `""`.
+ */
+export function prdStopGate(payload: Record<string, unknown>, cwd: string, id: string, trackFilePath: string, now: number): string {
+  if (!isPrdEnabled(cwd, id)) return "";
+  if (id === "cursor") return ""; // `stop` is Cursor's terminal observation event, not gated today (design doc §5 table).
+  const root = prdProjectRoot(cwd);
+  const homeSeg = harnessHomeSegment(id);
+  const router = readRouterSync(root, homeSeg);
+  if (!router) return "";
+  const track = readTrackSync(trackFilePath, trackJournalEnabled());
+  // Two independent violation sources, per the design doc: (a) unresolved
+  // `prdViolations` already journaled by the PostToolUse cross-check
+  // (§2.2 — `hasAnyViolations` has no track access, so THIS is that half),
+  // (b) `hasAnyViolations` itself — a router entry marked `validated` whose
+  // task-PRD isn't actually fully validated.
+  const trackHasViolations = (track.prdViolations?.length ?? 0) > 0;
+  if (!trackHasViolations) {
+    const taskFiles = readAllTaskFilesSync(root, homeSeg, router);
+    if (!hasAnyViolations(router, taskFiles)) return compactReminder(id, payload, router, taskFiles, track, trackFilePath, now);
+  }
+
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+  const key = `${sessionId}:Stop`;
+  if (prdAlreadyBlocked(track, key)) return "";
+  persistStopBlocked(trackFilePath, track, key, now);
+
+  // gemini-cli/cline: route through respond() for their own native block
+  // envelope (see prd-subagent-stop.ts's identical routing comment for the
+  // full rationale — claude-code/codex/hermes stay on blockResponse
+  // unchanged, respond() cannot reproduce their byte-identical shape here).
+  if (id === "kimi" || id === "gemini-cli" || id === "cline") {
+    return respond(id, { kind: "block", title: "PRD cross-check", reason: REASON }, "Stop");
+  }
+  return blockResponse(REASON);
+}

package/src/runtime/prd/prd-subagent-context.ts

@@ -0,0 +1,69 @@
+/**
+ * @module prd-subagent-context
+ * SubagentStart injection (design doc §2.3) — the sub-agent's own PRD slice,
+ * never the whole task. Kept SYNCHRONOUS on purpose: `dispatchLifecycle` is
+ * called synchronously (no `await`) from `lifecycle-bridge.ts`/`handle.ts`,
+ * and making that chain async for one new injector would touch 3 unrelated
+ * files purely for signature plumbing — `prd-io.ts`'s sync twins
+ * (`readRouterSync`/`readTaskFileSync`) exist precisely so this call site
+ * needs zero signature changes anywhere else.
+ */
+import { contextResponse } from "../../adapters/claude";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import {
+  agentSlices, isPrdEnabled, prdProjectRoot, readRouterSync, readTaskFileSync, renderAgentSliceMarkdown,
+  type PrdSubagentSlice,
+} from "../../policy/prd";
+import { respond } from "../respond";
+
+/** Compliance reminder appended after the rendered slice(s) — the 3 rules a sub-agent must keep in mind. */
+const RULES = [
+  "1. Write ONLY the files listed in your slice above.",
+  "2. Report completion to YOUR OWN agent-report file above — never another agent's.",
+  "3. Do not mark a sub-task done until the work is actually finished; the coordinator validates from your report.",
+].join("\n");
+
+/** `agent_type`, same fallback `dispatch-aipilot.ts`'s `agentTypeOf` uses (duplicated here per SOLID file-size discipline, not cross-imported). */
+function agentTypeOf(payload: Record<string, unknown>): string {
+  return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+
+/**
+ * Build the SubagentStart PRD context injection for this agent, or `""` when
+ * the module is off, the caller is unnamed, or nothing in the router
+ * concerns it.
+ * @param payload - The raw SubagentStart hook payload.
+ * @param cwd - Project root.
+ * @param id - Harness target id.
+ * @returns The native `additionalContext` hook stdout, or `""`.
+ */
+export function prdSubagentContext(payload: Record<string, unknown>, cwd: string, id: string): string {
+  if (!isPrdEnabled(cwd, id)) return "";
+  const agentType = agentTypeOf(payload);
+  if (!agentType) return "";
+  const root = prdProjectRoot(cwd);
+  const homeSeg = harnessHomeSegment(id);
+  const router = readRouterSync(root, homeSeg);
+  if (!router) return "";
+
+  const slices: PrdSubagentSlice[] = [];
+  for (const [task, entry] of Object.entries(router)) {
+    const taskFile = readTaskFileSync(root, homeSeg, entry.prd);
+    if (!taskFile) continue;
+    slices.push(...agentSlices(taskFile, agentType, task));
+  }
+  if (slices.length === 0) return "";
+
+  const text = `${renderAgentSliceMarkdown(slices)}\n\n### Rules\n${RULES}`;
+  // gemini-cli/cline don't understand Claude's hookSpecificOutput.additionalContext
+  // envelope: gemini-cli's native shape has no hookEventName field and cline's
+  // is `{contextModification}` entirely — route them through respond()'s
+  // already-correct "inform" branches. claude-code/codex/kimi/cursor/hermes
+  // stay on contextResponse unchanged: respond()'s "inform" kind re-wraps the
+  // text through formatPrompt (adds a "[NOTE] title" line), which would NOT
+  // reproduce today's byte-identical raw-markdown output.
+  if (id === "gemini-cli" || id === "cline") {
+    return respond(id, { kind: "inform", title: "PRD assignment", reason: text }, "SubagentStart");
+  }
+  return contextResponse("SubagentStart", text);
+}