@fusengine/harness 0.1.92 → 0.1.93

package/src/policy/prd/prd-io.ts

@@ -0,0 +1,89 @@
+/**
+ * Thin fail-closed wrappers over `util/json-io.ts` + the `prd-schema.ts`
+ * parsers. Both async (CLI, PostToolUse) and sync (SubagentStart/Stop, which
+ * must not float async work) variants. The only two files in this module
+ * that touch disk (besides `prd-enabled.ts`).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { readJsonFile, writeJsonFile } from "../../util/json-io";
+import { prdAgentReportPath, prdRouterPath, prdTaskPath } from "./prd-paths";
+import { parseAgentReportFile, parseRouter, parseTaskFile } from "./prd-schema";
+import type { PrdAgentReportFile, PrdRouter, PrdTaskFile } from "./interfaces/types";
+
+function readJsonSync(path: string): unknown {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the router file; `null` when missing or malformed. */
+export async function readRouter(root: string, homeSeg: string): Promise<PrdRouter | null> {
+  const raw = await readJsonFile<unknown>(prdRouterPath(root, homeSeg));
+  return raw === null ? null : parseRouter(raw);
+}
+
+/** Sync twin of {@link readRouter}, for SubagentStart/Stop call sites. */
+export function readRouterSync(root: string, homeSeg: string): PrdRouter | null {
+  const raw = readJsonSync(prdRouterPath(root, homeSeg));
+  return raw === null ? null : parseRouter(raw);
+}
+
+/** Reads a task-PRD file; `null` when missing or malformed. */
+export async function readTaskFile(root: string, homeSeg: string, relPrd: string): Promise<PrdTaskFile | null> {
+  const raw = await readJsonFile<unknown>(prdTaskPath(root, homeSeg, relPrd));
+  return raw === null ? null : parseTaskFile(raw);
+}
+
+/** Sync twin of {@link readTaskFile}. */
+export function readTaskFileSync(root: string, homeSeg: string, relPrd: string): PrdTaskFile | null {
+  const raw = readJsonSync(prdTaskPath(root, homeSeg, relPrd));
+  return raw === null ? null : parseTaskFile(raw);
+}
+
+/** Reads every task-PRD file named in `router`, keyed by task name (`null` per unreadable/malformed entry). */
+export async function readAllTaskFiles(
+  root: string,
+  homeSeg: string,
+  router: PrdRouter,
+): Promise<Record<string, PrdTaskFile | null>> {
+  const out: Record<string, PrdTaskFile | null> = {};
+  for (const [task, entry] of Object.entries(router)) {
+    out[task] = await readTaskFile(root, homeSeg, entry.prd);
+  }
+  return out;
+}
+
+/** Reads an agent's own report file; `null` when missing or malformed. */
+export async function readAgentReport(root: string, homeSeg: string, agent: string): Promise<PrdAgentReportFile | null> {
+  const raw = await readJsonFile<unknown>(prdAgentReportPath(root, homeSeg, agent));
+  return raw === null ? null : parseAgentReportFile(raw);
+}
+
+/** Sync twin of {@link readAgentReport}. */
+export function readAgentReportSync(root: string, homeSeg: string, agent: string): PrdAgentReportFile | null {
+  const raw = readJsonSync(prdAgentReportPath(root, homeSeg, agent));
+  return raw === null ? null : parseAgentReportFile(raw);
+}
+
+/** Atomically writes the router file. */
+export async function writeRouter(root: string, homeSeg: string, router: PrdRouter): Promise<void> {
+  await writeJsonFile(prdRouterPath(root, homeSeg), router);
+}
+
+/** Atomically writes a task-PRD file. */
+export async function writeTaskFile(root: string, homeSeg: string, relPrd: string, file: PrdTaskFile): Promise<void> {
+  await writeJsonFile(prdTaskPath(root, homeSeg, relPrd), file);
+}
+
+/** Atomically writes an agent's own report file. */
+export async function writeAgentReport(
+  root: string,
+  homeSeg: string,
+  agent: string,
+  file: PrdAgentReportFile,
+): Promise<void> {
+  await writeJsonFile(prdAgentReportPath(root, homeSeg, agent), file);
+}

package/src/policy/prd/prd-ownership.ts

@@ -0,0 +1,99 @@
+/**
+ * The PreToolUse ownership decision. Everything it needs is passed in — no
+ * I/O. Pure functions over already-loaded router/task-PRD/bindings data.
+ */
+import type { PrdIdentity, PrdOwnershipVerdict, PrdPathKind, PrdTaskFile } from "./interfaces/types";
+
+/** True when `name === agentType`, or `"<agentType>-<n>"` with `n >= 2`. */
+export function matchesAgentName(name: string, agentType: string): boolean {
+  if (name === agentType) return true;
+  if (!name.startsWith(agentType)) return false;
+  const suffix = name.slice(agentType.length);
+  if (!suffix.startsWith("-")) return false;
+  const numPart = suffix.slice(1);
+  return /^\d+$/.test(numPart) && Number(numPart) >= 2;
+}
+
+/** Agent names in `taskFile` whose name matches `agentType` (base or `-n` suffixed). */
+export function candidateAgentNames(agentType: string, taskFile: PrdTaskFile): string[] {
+  return Object.keys(taskFile).filter((name) => matchesAgentName(name, agentType));
+}
+
+/**
+ * agentId -> bound name resolution. `bindings` is the journal's `prdOwners`
+ * map (agentId -> name), read-only here. Returns the candidate already
+ * bound to this agentId, or the SOLE still-unbound candidate (free to bind
+ * now), or `null` (ambiguous: >1 free candidate, or 0 candidates at all).
+ */
+export function resolveOwnerBinding(
+  candidates: string[],
+  agentId: string,
+  bindings: Record<string, string>,
+): { name: string; alreadyBound: boolean } | null {
+  const boundToMe = bindings[agentId];
+  if (boundToMe !== undefined && candidates.includes(boundToMe)) {
+    return { name: boundToMe, alreadyBound: true };
+  }
+  const takenByOthers = new Set(
+    Object.entries(bindings).filter(([id]) => id !== agentId).map(([, name]) => name),
+  );
+  const free = candidates.filter((c) => !takenByOthers.has(c));
+  if (free.length !== 1) return null;
+  const [name] = free;
+  return name === undefined ? null : { name, alreadyBound: false };
+}
+
+const COORDINATOR_ONLY_LABEL: Record<"router" | "task" | "docs", string> = {
+  router: "router",
+  task: "task PRD",
+  docs: "docs",
+};
+
+function evaluateCoordinatorOnly(kind: "router" | "task" | "docs", identity: PrdIdentity): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: true };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: `${COORDINATOR_ONLY_LABEL[kind]} is coordinator-only` };
+}
+
+function evaluateAgentReport(
+  agent: string,
+  identity: PrdIdentity,
+  taskFile: PrdTaskFile | null,
+  bindings: Record<string, string>,
+): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: false, reason: "agent report is not the coordinator's to write" };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  if (identity.agentType === undefined || identity.agentId === undefined) {
+    return { allow: false, reason: "unidentifiable agent_type — cannot verify ownership" };
+  }
+  const candidates = candidateAgentNames(identity.agentType, taskFile ?? {});
+  const resolved = resolveOwnerBinding(candidates, identity.agentId, bindings);
+  if (!resolved || resolved.name !== agent) {
+    return { allow: false, reason: "name doesn't match your agent_type, or already bound to another agent" };
+  }
+  return resolved.alreadyBound
+    ? { allow: true }
+    : { allow: true, bind: { agentId: identity.agentId, name: resolved.name } };
+}
+
+/**
+ * Top-level PreToolUse verdict for ONE file path already known to be in
+ * scope (`classifyPrdPath` returned non-`"other"`/non-`null` upstream).
+ */
+export function evaluateWriteOwnership(input: {
+  kind: PrdPathKind;
+  identity: PrdIdentity;
+  taskFile: PrdTaskFile | null;
+  bindings: Record<string, string>;
+}): PrdOwnershipVerdict {
+  const { kind, identity, taskFile, bindings } = input;
+
+  if (kind.kind === "router" || kind.kind === "task" || kind.kind === "docs") {
+    return evaluateCoordinatorOnly(kind.kind, identity);
+  }
+  if (kind.kind === "agentReport") {
+    return evaluateAgentReport(kind.agent, identity, taskFile, bindings);
+  }
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: "not a recognized PRD file" };
+}

package/src/policy/prd/prd-paths.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure path builders and classifiers for the PRD file tree
+ * (`<root>/<homeSeg>/apex/prd*`). No fs access — string/path compare only.
+ */
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { PrdPathKind, PrdRouter } from "./interfaces/types";
+
+const AGENT_REPORT_SUFFIX = "-prd.json";
+const DOCS_SUFFIX = ".md";
+
+function apexDir(root: string, homeSeg: string): string {
+  return join(root, homeSeg, "apex");
+}
+
+/** Absolute path to the router (`<root>/<homeSeg>/apex/prd.json`). */
+export function prdRouterPath(root: string, homeSeg: string): string {
+  return join(apexDir(root, homeSeg), "prd.json");
+}
+
+/** Absolute path to the PRD directory (`<root>/<homeSeg>/apex/prd`). */
+export function prdDir(root: string, homeSeg: string): string {
+  return join(apexDir(root, homeSeg), "prd");
+}
+
+/** Absolute path to a task-PRD file, given the router entry's `prd` field. */
+export function prdTaskPath(root: string, homeSeg: string, relPrd: string): string {
+  return join(apexDir(root, homeSeg), relPrd);
+}
+
+/** Absolute path to an agent's own report file (`prd/agents/<agent>-prd.json`). */
+export function prdAgentReportPath(root: string, homeSeg: string, agent: string): string {
+  return join(prdDir(root, homeSeg), "agents", `${agent}${AGENT_REPORT_SUFFIX}`);
+}
+
+/** Absolute path to a task's free-form doc (`prd/docs/<task>.md`). */
+export function prdDocsPath(root: string, homeSeg: string, task: string): string {
+  return join(prdDir(root, homeSeg), "docs", `${task}${DOCS_SUFFIX}`);
+}
+
+function resolveAgainstRoot(filePath: string, root: string): string {
+  return isAbsolute(filePath) ? resolve(filePath) : resolve(root, filePath);
+}
+
+/**
+ * True when `filePath` (absolute or root-relative) resolves under
+ * `<root>/<homeSeg>/apex/prd/`, or is exactly the router itself. Normalizes
+ * via `path.resolve`/`relative`; a `..` that escapes the PRD dir is rejected.
+ */
+export function isPrdScopedPath(filePath: string, root: string, homeSeg: string): boolean {
+  const abs = resolveAgainstRoot(filePath, root);
+  if (abs === resolve(prdRouterPath(root, homeSeg))) return true;
+  const rel = relative(resolve(prdDir(root, homeSeg)), abs);
+  return rel !== "" && rel !== "." && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Classifies an in-scope PRD path into one of the 4 file kinds (router,
+ * task, agentReport, docs), or `"other"` when it is textually under
+ * `apex/prd/` but matches none of the router-declared task files. `null`
+ * when the path is not in scope at all (see {@link isPrdScopedPath}).
+ */
+export function classifyPrdPath(
+  filePath: string,
+  root: string,
+  homeSeg: string,
+  router: PrdRouter | null,
+): PrdPathKind | null {
+  if (!isPrdScopedPath(filePath, root, homeSeg)) return null;
+  const abs = resolveAgainstRoot(filePath, root);
+  if (abs === resolve(prdRouterPath(root, homeSeg))) return { kind: "router" };
+
+  const dir = resolve(prdDir(root, homeSeg));
+  const parts = relative(dir, abs).split(sep);
+  const [first, second] = parts;
+
+  if (parts.length === 2 && first === "agents" && second?.endsWith(AGENT_REPORT_SUFFIX)) {
+    return { kind: "agentReport", agent: second.slice(0, -AGENT_REPORT_SUFFIX.length) };
+  }
+  if (parts.length === 2 && first === "docs" && second?.endsWith(DOCS_SUFFIX)) {
+    return { kind: "docs", task: second.slice(0, -DOCS_SUFFIX.length) };
+  }
+  if (router) {
+    for (const [task, entry] of Object.entries(router)) {
+      if (resolve(prdTaskPath(root, homeSeg, entry.prd)) === abs) return { kind: "task", task };
+    }
+  }
+  return { kind: "other" };
+}

package/src/policy/prd/prd-schema.ts

@@ -0,0 +1,151 @@
+/**
+ * Fail-closed parsers (malformed input -> `null`, never throw) and small
+ * immutable builders for the PRD JSON contract. Pure — no fs.
+ */
+import type {
+  PrdAgentEntryCompacted, PrdAgentReportFile, PrdRouter, PrdRouterEntry, PrdRouterStatus,
+  PrdSubTask, PrdTaskAgentEntry, PrdTaskFile,
+} from "./interfaces/types";
+
+const ROUTER_STATUSES: readonly PrdRouterStatus[] = ["assigned", "in-progress", "validated"];
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function parseRouterEntry(v: unknown): PrdRouterEntry | null {
+  if (!isRecord(v)) return null;
+  if (typeof v.prd !== "string") return null;
+  if (typeof v.status !== "string" || !ROUTER_STATUSES.includes(v.status as PrdRouterStatus)) return null;
+  const validatedAt = v["validated-at"];
+  if (validatedAt !== undefined && typeof validatedAt !== "string") return null;
+  return validatedAt === undefined
+    ? { prd: v.prd, status: v.status as PrdRouterStatus }
+    : { prd: v.prd, status: v.status as PrdRouterStatus, "validated-at": validatedAt };
+}
+
+/** Parses the router file (`prd.json`); `null` on any malformed shape. */
+export function parseRouter(raw: unknown): PrdRouter | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdRouter = {};
+  for (const [task, v] of Object.entries(raw)) {
+    const entry = parseRouterEntry(v);
+    if (!entry) return null;
+    out[task] = entry;
+  }
+  return out;
+}
+
+function parseSubTask(v: unknown): PrdSubTask | null {
+  if (!isRecord(v) || typeof v.status !== "string") return null;
+  if (v.status !== "assigned" && v.status !== "validated") return null;
+  const validatedAt = v["validated-at"];
+  if (validatedAt !== undefined && typeof validatedAt !== "string") return null;
+  return validatedAt === undefined ? { status: v.status } : { status: v.status, "validated-at": validatedAt };
+}
+
+function parseAgentEntry(v: unknown): PrdTaskAgentEntry | null {
+  if (!isRecord(v) || !isStringArray(v.files)) return null;
+  if (v.status === "validated") {
+    if (typeof v["validated-at"] !== "string") return null;
+    return { status: "validated", files: v.files, "validated-at": v["validated-at"] };
+  }
+  if (!isRecord(v["sub-tasks"])) return null;
+  const subTasks: Record<string, PrdSubTask> = {};
+  for (const [sub, sv] of Object.entries(v["sub-tasks"])) {
+    const parsed = parseSubTask(sv);
+    if (!parsed) return null;
+    subTasks[sub] = parsed;
+  }
+  return { files: v.files, "sub-tasks": subTasks };
+}
+
+/** Parses a task-PRD file; `null` on any malformed shape. */
+export function parseTaskFile(raw: unknown): PrdTaskFile | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdTaskFile = {};
+  for (const [agent, v] of Object.entries(raw)) {
+    const entry = parseAgentEntry(v);
+    if (!entry) return null;
+    out[agent] = entry;
+  }
+  return out;
+}
+
+/** Parses an agent's own report file; `null` on any malformed shape. */
+export function parseAgentReportFile(raw: unknown): PrdAgentReportFile | null {
+  if (!isRecord(raw)) return null;
+  const out: PrdAgentReportFile = {};
+  for (const [task, subs] of Object.entries(raw)) {
+    if (!isRecord(subs)) return null;
+    const parsedSubs: Record<string, PrdAgentReportFile[string][string]> = {};
+    for (const [sub, v] of Object.entries(subs)) {
+      if (!isRecord(v) || v.status !== "done" || !isStringArray(v.modified) || !isStringArray(v.unchanged)) {
+        return null;
+      }
+      const doneAt = v["done-at"];
+      if (doneAt !== undefined && typeof doneAt !== "string") return null;
+      parsedSubs[sub] = doneAt === undefined
+        ? { status: "done", modified: v.modified, unchanged: v.unchanged }
+        : { status: "done", modified: v.modified, unchanged: v.unchanged, "done-at": doneAt };
+    }
+    out[task] = parsedSubs;
+  }
+  return out;
+}
+
+/** True when `e` is the post-compaction shape. */
+export function isCompacted(e: PrdTaskAgentEntry): e is PrdAgentEntryCompacted {
+  return "status" in e && e.status === "validated" && !("sub-tasks" in e);
+}
+
+/** Sub-tasks of an agent entry; `{}` when already compacted. */
+export function subTasksOf(e: PrdTaskAgentEntry): Record<string, PrdSubTask> {
+  return isCompacted(e) ? {} : e["sub-tasks"];
+}
+
+/** Files owned by an agent entry, expanded or compacted. */
+export function filesOf(e: PrdTaskAgentEntry): string[] {
+  return e.files;
+}
+
+/** `["needs >= 2 agents", ...]` — empty when the task PRD satisfies the contract. */
+export function validateTaskFileInvariant(taskFile: PrdTaskFile): string[] {
+  const errors: string[] = [];
+  if (Object.keys(taskFile).length < 2) errors.push("needs >= 2 agents");
+  return errors;
+}
+
+/** Returns a new router with `task`'s status (and optional `validated-at`) updated. */
+export function withRouterStatus(
+  router: PrdRouter,
+  task: string,
+  status: PrdRouterStatus,
+  at?: string,
+): PrdRouter {
+  const existing = router[task];
+  if (!existing) return router;
+  const entry: PrdRouterEntry = at === undefined
+    ? { prd: existing.prd, status }
+    : { prd: existing.prd, status, "validated-at": at };
+  return { ...router, [task]: entry };
+}
+
+/** Returns a new task-PRD file with one agent's sub-task flipped to `validated`. */
+export function withSubTaskValidated(
+  taskFile: PrdTaskFile,
+  agent: string,
+  sub: string,
+  at: string,
+): PrdTaskFile {
+  const entry = taskFile[agent];
+  if (!entry || isCompacted(entry)) return taskFile;
+  const subTask = entry["sub-tasks"][sub];
+  if (!subTask) return taskFile;
+  const nextSubTasks = { ...entry["sub-tasks"], [sub]: { status: "validated" as const, "validated-at": at } };
+  return { ...taskFile, [agent]: { files: entry.files, "sub-tasks": nextSubTasks } };
+}

package/src/runtime/handle-post.ts

@@ -14,6 +14,7 @@ import { recordCodexPostFailure } from "../tracking/codex-post-failure";
 import { defaultStateDir } from "./paths";
 import { fanOutFiles, firstFileMatch } from "./post-fanout";
 import { postOutcome } from "./post-outcome";
+import { prdPostCheck } from "./prd";
 import type { PreContext } from "./handle-pre";
 import type { HandleOutcome } from "./handle";
 
@@ -75,6 +76,7 @@ export async function handlePost(ctx: PreContext): Promise<HandleOutcome> {
   // tracking, validation, post-edit context, and notices.
   const files = fanOutFiles(event);
   for (const f of files) postTrackingSideEffects(opts.scope ?? "core", f, f.input, opts.now, payload, opts.cwd);
+  await prdPostCheck(id, event, opts.cwd, file, opts.now); // PRD cross-check — advisory only, never returns stdout
   const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
   if (seoDeny && !cursorAfterFileEdit) return { stdout: seoDeny, exit: 0 };
   if (opts.scope === "solid") {

package/src/runtime/handle-pre.ts

@@ -16,6 +16,7 @@ import { applyPatchGate } from "./apply-patch-gate";
 import { isBypassPermissions } from "../adapters/codex/permission-mode";
 import { evaluate } from "../policy/evaluate";
 import { confirmGate } from "./confirm/confirm-gate";
+import { prdPreGate } from "./prd";
 import type { HandleOptions, HandleOutcome } from "./handle";
 
 /** Context the PreToolUse pipeline needs (resolved once by {@link handleHook}). */
@@ -85,6 +86,16 @@ export async function handlePre(ctx: PreContext): Promise<HandleOutcome> {
     if (taskCtx) return { stdout: taskCtx, exit: 0 };
   }
 
+  // PRD (task/agent ownership coordination): inert unless FUSE_PRD=1 AND a
+  // router is present — see runtime/prd/prd-pre-gate.ts. Runs BEFORE the
+  // apply_patch gate below: `applyPatchGate` runs `evaluate()` per file, whose
+  // `runGuards()` already includes `protectedPathGuard` — which unconditionally
+  // blocks every `.claude/apex/` path, PRD included. A PRD write this gate just
+  // authorized must short-circuit past both `applyPatchGate` and the gate chain
+  // further down, never reach either.
+  const prdOutcome = await prdPreGate(id, payload, event, opts.cwd, file, opts.now);
+  if (prdOutcome) return prdOutcome;
+
   // Codex `apply_patch`: normalize.ts fanned the freeform patch into per-file
   // changes. OR their static verdicts — one violating hunk blocks the whole
   // envelope. `event.files` is undefined for every other tool/harness.

package/src/runtime/lifecycle/dispatch.ts

@@ -17,6 +17,10 @@ import { cartoSessionStart } from "./cartographer/session-start";
 import { dispatchLessons } from "./lessons/dispatch";
 import { withSnapshot } from "./snapshot";
 import { stopCore } from "./stop-core";
+import { prdSubagentContext, prdSubagentStopGate, prdStopGate } from "../prd";
+import { joinContextResponses } from "../../policy/prd";
+import { sanitizeSessionId } from "../home-state";
+import { defaultStateDir, trackFile } from "../paths";
 
 /** Which plugin's hooks.json invoked the harness (selects SessionStart behavior). */
 export type PluginScope = "core" | "solid" | "rules" | "carto" | "security" | "changelog" | "aipilot" | "lessons" | "seo" | "memory" | "tailwindcss";
@@ -70,11 +74,14 @@ export function dispatchLifecycle(input: LifecycleInput): string | null {
       if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
       if (input.scope === "aipilot") return "";
       if (input.scope === "lessons") return dispatchLessons("SubagentStart", input.payload, input.cwd, input.now, input.id ?? "claude-code");
-      return subagentCacheContext(input.payload.session_id);
-    case "Stop":
+      return joinContextResponses(subagentCacheContext(input.payload.session_id), prdSubagentContext(input.payload, input.cwd, input.id ?? "claude-code"));
+    case "Stop": {
       if (input.scope === "lessons") return dispatchLessons("Stop", input.payload, input.cwd, input.now, input.id ?? "claude-code");
-      return input.scope === "core" ? stopCore(input.payload, input.cwd, input.now) : null;
-    case "SubagentStop":
+      if (input.scope !== "core") return null;
+      const prdBlock = prdStopGate(input.payload, input.cwd, input.id ?? "claude-code", trackFile(sanitizeSessionId(input.payload.session_id) ?? "unknown", defaultStateDir(input.cwd)), input.now);
+      return prdBlock || stopCore(input.payload, input.cwd, input.now);
+    }
+    case "SubagentStop": {
       // G0 counterpart of the SubagentStart branch above — the SAME
       // monotone max-write, never a decrement (see confirm-subagent.ts).
       markSubagentSeen(input.payload.session_id, input.now);
@@ -84,7 +91,13 @@ export function dispatchLifecycle(input: LifecycleInput): string | null {
       // explore evidence even when sidechain PostToolUse hooks never fired
       // (#43612/#27655/#34692). SubagentStop is main-session-dispatched (reliable).
       harvestSubagentTrack(input.payload, input.cwd, input.now);
-      return trackAgentMemory(input.payload, undefined, input.now);
+      // null = PRD had nothing to say (off, unnamed agent, or genuinely done)
+      // -> normal trackAgentMemory handling; a non-null string (block, or ""
+      // on an already-blocked replay) must be returned AS-IS, never layered
+      // under a stale "agent completed" message.
+      const prdBlock = prdSubagentStopGate(input.payload, input.cwd, input.id ?? "claude-code", trackFile(sanitizeSessionId(input.payload.session_id) ?? "unknown", defaultStateDir(input.cwd)), input.now);
+      return prdBlock !== null ? prdBlock : trackAgentMemory(input.payload, undefined, input.now);
+    }
     case "TeammateIdle":
       return teammateIdleContext(input.payload, input.cwd, undefined, input.now);
     case "PostToolUseFailure":

package/src/runtime/normalize.ts

@@ -33,6 +33,8 @@ export interface NormalizedEvent {
   permissionMode?: string;
   /** Codex logical tool-use identity, shared by sibling hook callbacks. */
   toolUseId?: string;
+  /** Sub-agent identifier, if the tool-use came from one (Claude/Codex only — Cursor/Kimi never send this field, confirmed live). */
+  agentId?: string;
   /** Harness-reported working directory used to scope Codex authorization. */
   cwd?: string;
   /** Validated Cursor multi-root workspace paths in wire order. */
@@ -71,6 +73,7 @@ export function normalizeEvent(id: string, payload: Record<string, unknown>): No
       ...extractCursorEvent(payload),
       sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
       agentType: str(payload.agent_type),
+      agentId: str(payload.agent_id),
       permissionMode: str(payload.permission_mode),
     };
   }
@@ -83,6 +86,7 @@ export function normalizeEvent(id: string, payload: Record<string, unknown>): No
     input,
     sessionId: str(payload.session_id) ?? str(payload.conversation_id) ?? "",
     agentType: str(payload.agent_type) ?? str(input.subagent_type),
+    agentId: str(payload.agent_id),
     permissionMode: str(payload.permission_mode),
     toolUseId: str(payload.tool_use_id),
     cwd: str(payload.cwd),

package/src/runtime/prd/index.ts

@@ -0,0 +1,8 @@
+/** Barrel for `src/runtime/prd/**` — the runtime wiring surface (design doc §2). */
+export { prdPreGate } from "./prd-pre-gate";
+export { prdPostCheck } from "./prd-post-check";
+export { prdSubagentContext } from "./prd-subagent-context";
+export { prdSubagentStopGate } from "./prd-subagent-stop";
+export { prdStopGate } from "./prd-stop-gate";
+export { resolvePrdIdentity } from "./prd-identity";
+export { prdCandidateFiles } from "./prd-candidate-files";