@lannguyensi/harness 0.54.0 → 0.56.0

package/dist/cli/pack/hook-bootstrap.d.ts

@@ -82,3 +82,93 @@ export declare function resolveToolInput(event: {
  * hook then falls back to its legacy message shape.
  */
 export declare function parseConfigUx(raw: unknown, stderr: NodeJS.WritableStream, hookLabel: string): PolicyUx | undefined;
+export interface ResolveHookPackContextOptions extends LoaderOptions {
+    pack?: string;
+    generatedDir?: string;
+    manifest?: Manifest;
+}
+export interface ResolvedHookPackContext {
+    manifest: Manifest;
+    declared: Manifest["policy_packs"][number];
+    generatedDir: string;
+}
+export type ResolveHookPackContextResult = {
+    ok: true;
+    context: ResolvedHookPackContext;
+} | {
+    ok: false;
+    diagnostic: string;
+};
+/**
+ * Load the manifest (or use injection), confirm `packName` is declared and
+ * enabled, and resolve `generatedDir` — the fixed sequence that follows
+ * `loadManifestOrInjected` in nearly every pack hook. Returns a single
+ * failure shape with a ready-to-emit `${hookLabel}: ...` diagnostic instead
+ * of three separate early-return blocks, so a caller wires it as:
+ *
+ *   const ctx = resolveHookPackContext(hookLabel, packName, opts);
+ *   if (!ctx.ok) return noop(ctx.diagnostic, stderr, ...);
+ */
+export declare function resolveHookPackContext(hookLabel: string, packName: string, opts: ResolveHookPackContextOptions): ResolveHookPackContextResult;
+export interface ResolvedSessionAndAgentIds {
+    sessionId: string;
+    agentId: string;
+}
+export type ResolveSessionAndAgentIdsResult = {
+    ok: true;
+    ids: ResolvedSessionAndAgentIds;
+} | {
+    ok: false;
+    diagnostic: string;
+    sessionId: string | null;
+};
+/**
+ * Parse and validate `session_id` + `agent_id` off an event body (the
+ * subagent-start/subagent-stop shared shape). `validateAgentId` is
+ * injected rather than imported here — the agent-id allowlist lives with
+ * the understanding-before-execution pack's in-flight records
+ * (`rejectMalformedAgentId`), and this module stays pack-agnostic on
+ * purpose (see the module header).
+ */
+export declare function resolveSessionAndAgentIds(hookLabel: string, event: {
+    session_id?: unknown;
+    agent_id?: unknown;
+}, validateAgentId: (agentId: string) => void): ResolveSessionAndAgentIdsResult;
+export interface ResolveSubagentHookContextOptions extends ResolveHookPackContextOptions {
+    stderr: NodeJS.WritableStream;
+}
+export interface ResolvedSubagentHookContext {
+    sessionId: string;
+    agentId: string;
+    declared: Manifest["policy_packs"][number];
+    generatedDir: string;
+}
+export type ResolveSubagentHookContextResult = {
+    ok: true;
+    context: ResolvedSubagentHookContext;
+} | {
+    ok: false;
+    diagnostic: string;
+    sessionId: string | null;
+    agentId: string | null;
+};
+/**
+ * The three-step preamble subagent-start and subagent-stop both ran
+ * verbatim before the point where their bodies diverge (write vs. clear):
+ * pause-sentinel check, session_id/agent_id resolution, then pack-context
+ * resolution. Extracted to close the residual clone between the two hook
+ * files (review finding, subagent-gate). `verb` names the hook for both
+ * the pause check's own stderr label and the caller-facing "paused,
+ * skipping" diagnostic (e.g. "subagent-start"); `hookLabel` is the fuller
+ * `harness pack hook: <verb>` prefix used in every other diagnostic.
+ *
+ * Each ok:false case reports a `sessionId`/`agentId` pair matching exactly
+ * what the pre-extraction call sites passed to their own `noop()`: both
+ * null on a pause, `sessionId` non-null (once past validation) on a
+ * missing/malformed agent_id, and both non-null once ids resolved but the
+ * pack context failed.
+ */
+export declare function resolveSubagentHookContext(hookLabel: string, verb: string, packName: string, event: {
+    session_id?: unknown;
+    agent_id?: unknown;
+}, validateAgentId: (agentId: string) => void, opts: ResolveSubagentHookContextOptions): ResolveSubagentHookContextResult;

package/dist/cli/pack/hook-bootstrap.js

@@ -20,6 +20,24 @@
 //      Codex shim that sends `raw_input` instead — the exact shape
 //      `hook-codex-post-tool-use.ts`'s own private `resolveToolInput`
 //      already handles).
+//   7. `resolveHookPackContext` — the declared-pack-lookup / enabled-check /
+//      generatedDir-resolution trio that follows manifest load in nearly
+//      every hook. Its shape is closely mirrored by hook-post-tool-use.ts,
+//      hook-track-active-claim.ts, hook-pre-tool-use.ts and the Codex
+//      siblings, which were deliberately left calling their own inline
+//      copies rather than switched over here (out of scope for the task
+//      that added this helper); it was extracted for the
+//      subagent-start/subagent-stop pair, which would otherwise have
+//      re-duplicated it a further two times.
+//   8. `resolveSessionAndAgentIds` — session_id + agent_id parse and
+//      validation shared by subagent-start/subagent-stop. Pack-agnostic
+//      by construction: the agent-id validator is injected by the caller
+//      rather than imported here, so this module stays free of any
+//      understanding-before-execution-specific dependency.
+//   9. `resolveSubagentHookContext` — the pause-check / id-resolution /
+//      pack-context preamble shared verbatim by subagent-start and
+//      subagent-stop, up to the point where their bodies diverge (write
+//      vs. clear). Composes 2, 7, and 8 above.
 //
 // Not used by:
 //   - hook-runtime-reality.ts: its stdin reader uses async iteration + an
@@ -37,6 +55,8 @@
 // to each hook. This module covers structural boilerplate only, not semantics.
 import { checkPauseFromLoader } from "../pause-check.js";
 import { loadManifest } from "../loader.js";
+import { resolveGeneratedDir } from "../../runtime/pending-approval.js";
+import { rejectMalformedSessionId } from "../../runtime/reject-malformed-session-id.js";
 import { PolicyUxSchema } from "../../schema/index.js";
 // ---------------------------------------------------------------------------
 // 1. Standard stdin reader
@@ -164,4 +184,146 @@ export function parseConfigUx(raw, stderr, hookLabel) {
     }
     return result.data;
 }
+/**
+ * Load the manifest (or use injection), confirm `packName` is declared and
+ * enabled, and resolve `generatedDir` — the fixed sequence that follows
+ * `loadManifestOrInjected` in nearly every pack hook. Returns a single
+ * failure shape with a ready-to-emit `${hookLabel}: ...` diagnostic instead
+ * of three separate early-return blocks, so a caller wires it as:
+ *
+ *   const ctx = resolveHookPackContext(hookLabel, packName, opts);
+ *   if (!ctx.ok) return noop(ctx.diagnostic, stderr, ...);
+ */
+export function resolveHookPackContext(hookLabel, packName, opts) {
+    let manifest;
+    let manifestPath;
+    try {
+        ({ manifest, manifestPath } = loadManifestOrInjected(opts, opts.manifest));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: manifest load failed (${err.message}), skipping`,
+        };
+    }
+    const declared = manifest.policy_packs.find((p) => p.name === packName);
+    if (!declared) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: pack "${packName}" not declared in manifest, skipping`,
+        };
+    }
+    if (!declared.enabled) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: pack "${packName}" is enabled:false, skipping`,
+        };
+    }
+    const generatedDir = opts.generatedDir ??
+        (manifestPath !== undefined
+            ? resolveGeneratedDir({
+                ...(opts.homeDir !== undefined ? { homeDir: opts.homeDir } : {}),
+                manifestPath,
+            })
+            : undefined);
+    if (generatedDir === undefined) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: generatedDir unresolvable, skipping`,
+        };
+    }
+    return { ok: true, context: { manifest, declared, generatedDir } };
+}
+/**
+ * Parse and validate `session_id` + `agent_id` off an event body (the
+ * subagent-start/subagent-stop shared shape). `validateAgentId` is
+ * injected rather than imported here — the agent-id allowlist lives with
+ * the understanding-before-execution pack's in-flight records
+ * (`rejectMalformedAgentId`), and this module stays pack-agnostic on
+ * purpose (see the module header).
+ */
+export function resolveSessionAndAgentIds(hookLabel, event, validateAgentId) {
+    const sessionId = pickString(event.session_id) ?? "";
+    const agentId = pickString(event.agent_id) ?? "";
+    if (sessionId === "") {
+        return { ok: false, diagnostic: `${hookLabel}: missing session_id, skipping`, sessionId: null };
+    }
+    // Validate sessionId right after the emptiness check, before any other
+    // early return, so every ok:false path below carries an already-rejected
+    // (never a raw, unvalidated) sessionId — a caller that echoes `sessionId`
+    // into a diagnostic or a path.join can never see an unvalidated value.
+    try {
+        rejectMalformedSessionId(sessionId);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: malformed session_id (${err.message}), skipping`,
+            sessionId: null,
+        };
+    }
+    if (agentId === "") {
+        return { ok: false, diagnostic: `${hookLabel}: missing agent_id, skipping`, sessionId };
+    }
+    try {
+        validateAgentId(agentId);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            diagnostic: `${hookLabel}: malformed agent_id (${err.message}), skipping`,
+            sessionId,
+        };
+    }
+    return { ok: true, ids: { sessionId, agentId } };
+}
+/**
+ * The three-step preamble subagent-start and subagent-stop both ran
+ * verbatim before the point where their bodies diverge (write vs. clear):
+ * pause-sentinel check, session_id/agent_id resolution, then pack-context
+ * resolution. Extracted to close the residual clone between the two hook
+ * files (review finding, subagent-gate). `verb` names the hook for both
+ * the pause check's own stderr label and the caller-facing "paused,
+ * skipping" diagnostic (e.g. "subagent-start"); `hookLabel` is the fuller
+ * `harness pack hook: <verb>` prefix used in every other diagnostic.
+ *
+ * Each ok:false case reports a `sessionId`/`agentId` pair matching exactly
+ * what the pre-extraction call sites passed to their own `noop()`: both
+ * null on a pause, `sessionId` non-null (once past validation) on a
+ * missing/malformed agent_id, and both non-null once ids resolved but the
+ * pack context failed.
+ */
+export function resolveSubagentHookContext(hookLabel, verb, packName, event, validateAgentId, opts) {
+    if (checkHookPause(verb, opts.stderr, opts, opts.generatedDir).paused) {
+        return {
+            ok: false,
+            diagnostic: `harness paused; ${verb} skipping without evaluating.`,
+            sessionId: null,
+            agentId: null,
+        };
+    }
+    const idsResult = resolveSessionAndAgentIds(hookLabel, event, validateAgentId);
+    if (!idsResult.ok) {
+        return {
+            ok: false,
+            diagnostic: idsResult.diagnostic,
+            sessionId: idsResult.sessionId,
+            agentId: null,
+        };
+    }
+    const { sessionId, agentId } = idsResult.ids;
+    const ctx = resolveHookPackContext(hookLabel, packName, opts);
+    if (!ctx.ok) {
+        return { ok: false, diagnostic: ctx.diagnostic, sessionId, agentId };
+    }
+    return {
+        ok: true,
+        context: {
+            sessionId,
+            agentId,
+            declared: ctx.context.declared,
+            generatedDir: ctx.context.generatedDir,
+        },
+    };
+}
 //# sourceMappingURL=hook-bootstrap.js.map

package/dist/cli/pack/hook-bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-bootstrap.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-bootstrap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hook-bootstrap.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/hook-pre-tool-use.js

@@ -56,7 +56,7 @@ import * as path from "node:path";
 import { readRegularFileRejectingSymlink } from "../../io/read-regular-file.js";
 import { queryLedgerByTag, } from "../../policies/index.js";
 import { renderProducers } from "../../policies/producers.js";
-import { ADOPTION_LEDGER_DIRNAME, CLAUDE_CODE_HARNESS, checkOperatorApprovalMarkers, checkPersistedReport, defaultReportsDir, delegationMarkerPathFor, delegationReportPathFor, harnessAllowed, listPersistedReports, matchLedgerEntries, parseAutoApprove, readActiveClaim, recordPermissionModeObservation, selectNewestStrictSessionReport, verifyDelegation, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import { ADOPTION_LEDGER_DIRNAME, CLAUDE_CODE_HARNESS, checkOperatorApprovalMarkers, checkPersistedReport, defaultReportsDir, delegationMarkerPathFor, delegationReportPathFor, harnessAllowed, listPersistedReports, matchLedgerEntries, parseAutoApprove, readActiveClaim, recordPermissionModeObservation, sanitizeForDisplay, selectNewestStrictSessionReport, verifyDelegation, verifyInflightRecord, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
 import { resolveMode, toPackageMode, } from "../../policy-packs/builtin/understanding-before-execution.js";
 import { sha256Hex, signingKeyExists } from "../../runtime/approval-signing.js";
 import { findLatestParseError, renderMalformedSectionsNotice } from "../approve/understanding.js";
@@ -523,6 +523,12 @@ export async function runPackHookPreToolUseCli(opts = {}) {
     // distinct phrase from "no approval marker" so an operator/auditor can
     // tell a forgery attempt apart from the routine "never approved" case.
     let markerForged = false;
+    // `markers.detail` itself, hoisted alongside `markerForged` so the
+    // in-flight consult below can still surface it: a forged SESSION/TASK
+    // marker sitting next to a genuinely valid in-flight record (ADR "TTL,
+    // cwd, and subagents") is a forgery attempt the operator should see
+    // even though the in-flight record is what ends up opening the gate.
+    let markerForgedDetail;
     if (generatedDir !== undefined) {
         // Source 1a/1b: task-scoped marker for the currently-claimed task
         // (harness/1ee26e77 + PR #198 correctness fix), then the
@@ -533,6 +539,20 @@ export async function runPackHookPreToolUseCli(opts = {}) {
         const markers = checkOperatorApprovalMarkers(generatedDir, sessionId, declared.config, stderr);
         markerExpired = markers.expired;
         markerForged = markers.forged;
+        if (markerForged) {
+            // `markers.detail` is only ever the SESSION marker's detail on the
+            // unmatched path (see OperatorMarkerApproval.detail); when it is
+            // the TASK marker that failed verification, that fact is buried
+            // inside `taskCheckDetail`'s wrapping instead. Detect which one
+            // actually carries the forgery phrase so this line names the
+            // marker that was actually tampered with, not always the session
+            // one (review T-003 R3 L1: a forged task marker next to an intact
+            // session marker used to report the session's unrelated "no
+            // approval marker" detail here).
+            const taskMarkerIsForged = /forged\/unsigned marker rejected/.test(markers.taskCheckDetail);
+            const forgedMarkerDetail = taskMarkerIsForged ? markers.taskCheckDetail : markers.detail;
+            markerForgedDetail = `harness pack hook: forged/unsigned marker rejected for session ${sessionId}; ${forgedMarkerDetail}`;
+        }
         if (markers.source !== "task") {
             // Trace the task-marker miss to stderr so an operator chasing
             // "why isn't my approval working?" sees the active-claim vs marker
@@ -550,6 +570,59 @@ export async function runPackHookPreToolUseCli(opts = {}) {
             };
         }
     }
+    // Source 1c: in-flight subagent record (ADR "TTL, cwd, and subagents").
+    // An Agent-tool subagent shares its parent's
+    // `session_id`, so the marker check above cannot tell a subagent's call
+    // apart from the parent's own — the payload's `agent_id` is what does.
+    // Consulted ONLY here, ONLY when the marker check just missed AND the
+    // payload names a non-empty `agent_id`: a main-line call (no
+    // `agent_id`) never reaches `verifyInflightRecord` at all, so no record
+    // on disk for any agent can ever open the gate for a main-line call.
+    const agentId = typeof event.agent_id === "string" && event.agent_id.length > 0
+        ? event.agent_id
+        : undefined;
+    // Sanitized copy for every surface a human or the agent itself reads
+    // (the block suffix, the forged phrase, this allow diagnostic): the raw
+    // `agentId` above is what verification and path-building use, but an
+    // attacker-controlled `agent_id` is otherwise interpolated verbatim
+    // into stderr and the agent-facing deny text (review finding: newline
+    // injection, unbounded length).
+    const displayAgentId = agentId !== undefined ? sanitizeForDisplay(agentId) : undefined;
+    // True SPECIFICALLY when a record FILE existed but failed verification
+    // (bad signature, or its body disagreed with its own path) — the same
+    // distinction `markerForged` draws for the operator marker. Folded into
+    // the auto-approval gating below so a forged record is declined the
+    // same way a forged marker is, without duplicating that enforcement.
+    let inflightForged = false;
+    // True SPECIFICALLY when the record verified and agreed with its own
+    // path but aged past the staleness window — distinct from `forged` and
+    // from a record simply never existing, so the subagent sentence below
+    // can name the actual cause instead of always saying "no record".
+    let inflightStale = false;
+    if (generatedDir !== undefined && agentId !== undefined) {
+        const record = verifyInflightRecord(generatedDir, sessionId, agentId, opts.now !== undefined ? { now: opts.now } : {});
+        inflightForged = record.forged;
+        inflightStale = record.stale;
+        if (record.matched) {
+            // A forged SESSION/TASK marker sitting next to this valid record is
+            // a distinct forgery attempt: surfaced to stderr BEFORE the allow
+            // diagnostic, but never gating it — the in-flight record is its
+            // own, independently-verified approval authority (ADR "TTL, cwd,
+            // and subagents"), so a forged copy of a DIFFERENT authority must
+            // not turn this allow into a block.
+            if (markerForgedDetail !== undefined) {
+                stderr.write(`${markerForgedDetail}\n`);
+            }
+            const diagnostic = `harness pack hook: in-flight subagent record for agent ${displayAgentId} (${record.detail}), allowing.`;
+            stderr.write(`${diagnostic}\n`);
+            return {
+                exitCode: 0,
+                blocked: false,
+                approvalCheck: { approved: true, source: "inflight", detail: record.detail },
+                diagnostic,
+            };
+        }
+    }
     // Persisted-report EVIDENCE probe (task 7402301d). This used to be
     // "Source 2", an equal approval authority consulted right after a forged
     // marker was rejected, and it was unsigned: under the threat model that
@@ -573,16 +646,44 @@ export async function runPackHookPreToolUseCli(opts = {}) {
     // historic trail. The result intentionally does NOT influence the
     // allow/block decision.
     const ledger = await checkLedger(manifest, sessionId, opts);
+    // A subagent call (non-empty `agent_id`) that reached this point had no
+    // matching in-flight record — missing, for a different agent, forged,
+    // stale, or naming a malformed id (`verifyInflightRecord` never throws
+    // on any of those; it just reports `matched: false`). Branched on the
+    // actual verification outcome rather than always naming "no record": a
+    // forged or stale record is a materially different signal than one
+    // that never existed — the parent DID hold a valid approval at some
+    // point — and conflating them misdirects the agent's next action.
+    // Gated on `generatedDir !== undefined`: when it
+    // is not resolvable (test/injection path), `verifyInflightRecord` was
+    // never consulted at all (see `inflightForged`/`inflightStale` staying
+    // at their `false` initializers above), so there is no verification
+    // outcome to report. Named explicitly so an agent reading the deny
+    // text knows to stop rather than retry: unlike the operator-approval
+    // case, nothing this session can do mints a new record — only the
+    // parent's NEXT `subagent-start` call can.
+    const subagentRecordSentence = generatedDir !== undefined && displayAgentId !== undefined
+        ? inflightForged
+            ? ` subagent ${displayAgentId}: the in-flight record for this subagent failed verification; stop cleanly and report to the orchestrator instead of retrying.`
+            : inflightStale
+                ? ` subagent ${displayAgentId}: the in-flight record for this subagent is older than the staleness window; stop cleanly and report to the orchestrator instead of retrying.`
+                : ` subagent ${displayAgentId}: no in-flight approval record (the parent session held no valid approval when this subagent started, or the record was removed); stop cleanly and report to the orchestrator instead of retrying.`
+        : "";
     // Neither operator source approved. When a marker FILE existed but
     // failed signature verification, use a distinct reason phrase
     // ("forged/unsigned marker rejected") instead of the routine "no
     // approval marker" — audit/operator surfaces can then tell an active
     // forgery attempt (or a pre-signing legacy marker) apart from a session
-    // that simply never approved (harness/f9485cc7).
+    // that simply never approved (harness/f9485cc7). A forged in-flight
+    // record gets its own distinct phrase for the same reason, checked
+    // second so a forged SESSION/TASK marker (the higher-authority forgery)
+    // is never masked by a merely-forged copy of it.
     const reason = generatedDir !== undefined
         ? markerForged
             ? `forged/unsigned marker rejected for session ${sessionId}; ${report.detail}; ${ledger.detail}`
-            : `no approval marker for session ${sessionId}; ${report.detail}; ${ledger.detail}`
+            : inflightForged
+                ? `forged/unsigned in-flight record for agent ${displayAgentId} rejected for session ${sessionId}; ${report.detail}; ${ledger.detail}`
+                : `no approval marker for session ${sessionId}; ${report.detail}; ${ledger.detail}${subagentRecordSentence}`
         : `generatedDir not resolvable (test/injection path); ${report.detail}; ${ledger.detail}`;
     // Stage the session id so `harness approve`, run from the operator's
     // shell where $CLAUDE_CODE_SESSION_ID / $CLAUDE_SESSION_ID is unset, can resolve it without
@@ -705,7 +806,12 @@ export async function runPackHookPreToolUseCli(opts = {}) {
     // simply still in flight. That is the one case where the deny text asks
     // for a retry, so it is the one case that sets this flag.
     let reportScanTimedOut = false;
-    if (generatedDir !== undefined && !markerForged) {
+    // `!inflightForged` added alongside `!markerForged`: a forged in-flight
+    // record is the same posture as a forged marker (ADR condition 6, "a
+    // forgery detected is never laundered into an approval") — no point
+    // spending a delegation resolution on a call already known to end in a
+    // decline.
+    if (generatedDir !== undefined && !markerForged && !inflightForged) {
         // `null` stderr on purpose: `attemptAutoApproval` parses the same
         // block a few lines below and writes the malformed-config line
         // itself, so passing this hook's stderr here would double it.
@@ -761,11 +867,28 @@ export async function runPackHookPreToolUseCli(opts = {}) {
                     launcherReportPath,
                 });
                 if (!verified.ok) {
-                    // A missing, moved, or content-modified launcher report surfaces
+                    // An absent, moved, or content-modified launcher report surfaces
                     // here through the verifier's own distinct reasons
-                    // (`report_path_mismatch` / `report_content_mismatch`), same as
-                    // every other refusal: no special-casing needed now that this
-                    // hook actually checks the fallback shape against a file.
+                    // (`report_missing` / `report_path_mismatch` /
+                    // `report_content_mismatch`), same as every other refusal: no
+                    // special-casing needed now that this hook actually checks the
+                    // fallback shape against a file. `verified.detail` names the
+                    // expected path for the three file-state cases this hook can
+                    // actually reach (absent / wrong path / wrong bytes). Two of
+                    // `verifyDelegation`'s binding-shape branches are unreachable
+                    // from here for different reasons, so their details are worth
+                    // spelling out separately rather than lumping them together:
+                    // "no report path offered" never fires from this call site,
+                    // since this hook always offers the conventional path
+                    // (`launcherReportPath` above is unconditional); "no
+                    // reportContentHash to check against" IS reachable here, just
+                    // not from a delegation this hook itself minted, since
+                    // `writeDelegationMarker` refuses to produce that half-binding
+                    // shape (a hand-signed marker can still carry it, as the
+                    // half-binding test in
+                    // understanding-before-execution-delegation.test.ts shows), and
+                    // its detail names the delegation marker's own path, not the
+                    // report path, since there is no report path yet to name.
                     stderr.write(`harness pack hook: delegation for ${childSessionId} refused: ${verified.reason}: ${verified.detail}\n`);
                 }
                 else {
@@ -1003,7 +1126,18 @@ export async function runPackHookPreToolUseCli(opts = {}) {
         sessionConsistency: { kind: "env", variable: "CLAUDE_CODE_SESSION_ID" },
         packConfig: declared.config,
         reportsDir,
-        markerForged,
+        // Folded with `inflightForged`: `attemptAutoApproval`'s own guard on
+        // this flag is the ACTUAL enforcement point for "a forgery is never
+        // laundered into an approval" (the `!inflightForged` added to the
+        // block above only skips a doomed delegation resolution; it does not
+        // by itself stop this call).
+        markerForged: markerForged || inflightForged,
+        // Names which of the two the flag above actually folds together, so
+        // the decline diagnostic says the right artifact. A real marker
+        // forgery keeps the plain "marker" wording even when both happen to
+        // be true, matching the higher-authority precedence `reason` above
+        // already gives it.
+        forgedKind: markerForged ? "marker" : inflightForged ? "inflight" : undefined,
         // Slice 3: present only when the branch above verified a delegation
         // for this child session. It supplies key ONE in place of a
         // `when`-listed `permission_mode`; every other condition, key two
@@ -1046,7 +1180,27 @@ export async function runPackHookPreToolUseCli(opts = {}) {
     const latestParseError = report.report === null
         ? findLatestParseError(path.join(path.dirname(reportsDir), "parse-errors"), sessionId)
         : null;
-    stdout.write(`${blockJson(toolName, "no approved Understanding Report for this session", configProducers, configUx, sessionId, escapeHint, latestParseError?.malformedSections, reportScanTimedOut ? DELEGATION_REPORT_RETRY_INSTRUCTION : null)}\n`);
+    // The subagent record sentence, delivered to the AGENT through the
+    // same channel the slice-3 retry instruction uses (appended after both
+    // the `ux:` and legacy envelopes, so it survives either one) rather
+    // than staying stderr/audit-only, reaching only `reason` /
+    // `approvalCheck.detail` and never the agent-facing stdout JSON. A
+    // main-line block (`displayAgentId` undefined) never carries it.
+    //
+    // The retry instruction takes PRECEDENCE when both would apply: nothing
+    // stops a delegated session (ADR "Report capture under `-p`") from also
+    // being the parent of an in-flight subagent, but the two instructions
+    // disagree on what the agent should do next — the subagent sentence
+    // says stop, the retry instruction says retry — and the delegation
+    // path can still succeed on the very next retry regardless of the
+    // subagent record's own state, so telling the agent to stop here would
+    // be wrong.
+    const agentInstruction = reportScanTimedOut
+        ? DELEGATION_REPORT_RETRY_INSTRUCTION
+        : displayAgentId !== undefined && subagentRecordSentence.length > 0
+            ? subagentRecordSentence.trim()
+            : null;
+    stdout.write(`${blockJson(toolName, "no approved Understanding Report for this session", configProducers, configUx, sessionId, escapeHint, latestParseError?.malformedSections, agentInstruction)}\n`);
     return {
         exitCode: 0,
         blocked: true,