@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/hooks/spawn_guard_shadow_hook.ts

@@ -3,10 +3,12 @@
  * Spawn-guard — SHADOW ONLY (road-to-subagent-lifecycle-integrity Phase 3
  * Step 1, activated per `docs/contracts/concern-activation-policy.md`).
  *
- * What it does: on every `Agent` / `Task` tool call, read the open-dispatch
- * set the Phase-1 ledger maintains, and append one `spawn_guard_shadow` line
- * recording what a guard WOULD have done at several candidate thresholds.
- * It emits nothing to the model and it never blocks. Exit is always 0.
+ * What it does: on every `Agent` / `Task` call and every resume (`SendMessage`),
+ * read the open-dispatch set the Phase-1 ledger maintains, and append one
+ * `spawn_guard_shadow` line recording what a guard WOULD have done at several
+ * candidate thresholds; a spawn also records whether a warm worker would have
+ * been re-tasked instead (`reuse`). It emits nothing to the model and it never
+ * blocks. Exit is always 0.
  *
  * ── Why shadow and not warn ───────────────────────────────────────────────
  *
@@ -46,14 +48,26 @@
  * rides along as context and becomes a real measurement only when Phase 0
  * Step 4 establishes whether `agent_id` reaches a PreToolUse payload.
  *
- * PRIVACY BY CONSTRUCTION: counts and candidate verdicts only. No prompt, no
- * agent id, no tool input — the record type has no field able to hold any.
+ * PRIVACY BY CONSTRUCTION: counts, candidate verdicts, and a reuse verdict whose
+ * only free string is a worker's durable name from the register. A name read
+ * from the tool input reaches disk only as a session-bound digest. No prompt, no
+ * message, no recipient, no agent id.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { appendLedgerLine, openRecordStats, resolveConsumerRoot } from './subagent_ledger_hook.js';
+import { probeHostCapabilities } from '../_lib/host_capability.js';
+import { recentHostMarker } from '../_lib/quota_parked.js';
+import { shadowReuseVerdict, type ReuseContext, type WorkerState } from '../_lib/worker_reuse.js';
+import {
+    LEDGER_DIR,
+    appendLedgerLine,
+    openRecordStats,
+    readOpenRecords,
+    refFor,
+    resolveConsumerRoot,
+} from './subagent_ledger_hook.js';
 import { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW } from './exit_codes.js';
 
@@ -67,6 +81,154 @@ function isObject(v: unknown): v is JsonObject {
 /** The two subagent-dispatch tool names this repo has observed across hosts. */
 export const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set(['Agent', 'Task']);
 
+/**
+ * The tool that re-tasks a finished worker — and also messages a running one,
+ * a teammate, or the lead. The host's concurrency cap checks new spawns only
+ * and admits a resume past it, so a guard that counted spawns only would
+ * undercount exactly the runs the host does not bound. Only a send the ledger
+ * can place on a finished leg is called a resume; see {@link classifySend}.
+ */
+export const RESUME_TOOL_NAMES: ReadonlySet<string> = new Set(['SendMessage']);
+
+/**
+ * `resume` — the recipient hashes to a ledger ref that is not open and whose
+ * stop this same session recorded: a finished leg of this session is
+ * re-entered, which starts a run.
+ * `message_running` — the ref is open: the message starts no run.
+ * `message_or_resume` — the ledger cannot place the recipient in this session
+ * (a name, a teammate, the lead, another session's leg, no session id, a stop
+ * older than the scan window). Recorded, never called a resume.
+ *
+ * The verdict describes the attempted send at `pre_tool_use`; whether the host
+ * then accepts it is not visible here.
+ */
+export type SendKind = 'resume' | 'message_running' | 'message_or_resume';
+
+/** Bytes read from the end of each monthly ledger file when looking for a stop. */
+export const STOP_SCAN_BYTES = 1024 * 1024;
+
+function tailOf(file: string): string {
+    let fd: number;
+    try {
+        fd = fs.openSync(file, 'r');
+    } catch {
+        return '';
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, STOP_SCAN_BYTES);
+        const buf = Buffer.alloc(length);
+        fs.readSync(fd, buf, 0, length, size - length);
+        return buf.toString('utf8');
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+function stoppedInSession(root: string, ref: string, sessionId: string, now: Date): boolean {
+    const prev = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+    for (const month of [now.toISOString().slice(0, 7), prev.toISOString().slice(0, 7)]) {
+        for (const line of tailOf(path.join(root, LEDGER_DIR, `${month}.jsonl`)).split('\n')) {
+            if (!line.includes(ref)) continue;
+            try {
+                const rec = JSON.parse(line) as Record<string, unknown>;
+                if (rec['event'] === 'subagent_stop' && rec['ref'] === ref && rec['session_id'] === sessionId) {
+                    return true;
+                }
+            } catch {
+                // The first line of a tail is usually cut; a torn line is no evidence.
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * The ref a named spawn of this session left in the register, read from the
+ * same bounded tails as a stop; null when this session named no such worker.
+ */
+/** Longer names are neither recorded nor resolved: a name is an address, not a payload. */
+export const NAME_MAX = 128;
+
+/** Domain-separated digest of (session, name); the only form a tool-input name takes on disk. */
+function nameKey(sessionId: string, name: string): string {
+    return refFor(`subagent-name\0${sessionId}\0${name}`);
+}
+
+function refForName(root: string, name: string, sessionId: string, now: Date): string | null {
+    if (name.length > NAME_MAX) return null;
+    const key = nameKey(sessionId, name);
+    let found: string | null = null;
+    const prev = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+    for (const month of [prev.toISOString().slice(0, 7), now.toISOString().slice(0, 7)]) {
+        for (const line of tailOf(path.join(root, LEDGER_DIR, `${month}.jsonl`)).split('\n')) {
+            if (!line.includes('subagent_named')) continue;
+            try {
+                const rec = JSON.parse(line) as Record<string, unknown>;
+                if (rec['event'] === 'subagent_named' && rec['name_key'] === key && typeof rec['ref'] === 'string') {
+                    found = rec['ref'];
+                }
+            } catch {
+                // A torn line is no evidence.
+            }
+        }
+    }
+    return found;
+}
+
+/**
+ * Classify one send. `recipient_kind: name` is resolved through the register a
+ * named spawn of this session left; any other recipient is taken as an agent id
+ * and hashed with the ledger's own `refFor`. Neither the recipient nor its ref
+ * is written.
+ */
+export function classifySend(
+    root: string,
+    toolInput: unknown,
+    sessionId: string | null,
+    now: Date = new Date(),
+): SendKind {
+    const input = isObject(toolInput) ? toolInput : {};
+    const recipient = input['to'];
+    if (typeof recipient !== 'string' || recipient === '') return 'message_or_resume';
+    if (sessionId === null || sessionId === '') return 'message_or_resume';
+    const ref = input['recipient_kind'] === 'name' ? refForName(root, recipient, sessionId, now) : refFor(recipient);
+    if (ref === null) return 'message_or_resume';
+    if (readOpenRecords(root).has(ref)) return 'message_running';
+    return stoppedInSession(root, ref, sessionId, now) ? 'resume' : 'message_or_resume';
+}
+
+/**
+ * On a completed named spawn, record which ledger ref the name now addresses.
+ * Neither the name nor the agent id reaches disk in clear; both are digested first.
+ */
+export function recordNamedSpawn(root: string, payload: JsonObject, sessionId: string | null, nowIso: string): void {
+    const input = isObject(payload['tool_input']) ? payload['tool_input'] : {};
+    const result = isObject(payload['tool_response']) ? payload['tool_response'] : {};
+    const name = input['name'];
+    const agentId = result['agentId'];
+    if (typeof name !== 'string' || name === '' || name.length > NAME_MAX || typeof agentId !== 'string' || agentId === '') return;
+    if (sessionId === null) return;
+    appendLedgerLine(root, nowIso, { event: 'subagent_named', ts: nowIso, ref: refFor(agentId), name_key: nameKey(sessionId, name), session_id: sessionId });
+}
+
+/**
+ * Platforms where `pre_tool_use` was observed firing on the resume tool, with a
+ * deny honoured there. Elsewhere the line says the resume half is unobserved.
+ */
+export const RESUME_ADMISSION_OBSERVED: ReadonlySet<string> = new Set(['claude']);
+
+/**
+ * Inputs to the reuse verdict. Production passes none: `host_resume` comes
+ * from the host row, and no worker register is recorded yet, which the verdict
+ * names as `worker_register_unrecorded` rather than reading as empty.
+ */
+export interface ShadowDeps {
+    host_resume?: boolean;
+    workers?: readonly WorkerState[] | null;
+    context?: ReuseContext | null;
+}
+
 /** One candidate guard configuration under shadow evaluation. */
 export interface Candidate {
     readonly label: string;
@@ -136,12 +298,34 @@ function extractToolName(payload: JsonObject): string | null {
     return typeof v === 'string' && v ? v : null;
 }
 
-export function processEnvelope(envelope: JsonValue, consumerRoot: string): number {
+export function processEnvelope(envelope: JsonValue, consumerRoot: string, deps: ShadowDeps = {}): number {
     try {
         if (!isObject(envelope)) return EXIT_ALLOW;
         const payload = unwrapPayload(envelope);
         const toolName = extractToolName(payload);
-        if (toolName === null || !DISPATCH_TOOL_NAMES.has(toolName)) return EXIT_ALLOW;
+        if (toolName === null) return EXIT_ALLOW;
+        if (envelope['event'] === 'post_tool_use' || payload['hook_event_name'] === 'PostToolUse') {
+            if (DISPATCH_TOOL_NAMES.has(toolName)) {
+                const sid = payload['session_id'] ?? envelope['session_id'];
+                recordNamedSpawn(consumerRoot, payload, typeof sid === 'string' ? sid : null, new Date().toISOString());
+            }
+            return EXIT_ALLOW;
+        }
+        const isResume = RESUME_TOOL_NAMES.has(toolName);
+        if (!isResume && !DISPATCH_TOOL_NAMES.has(toolName)) return EXIT_ALLOW;
+        const platform = typeof envelope['platform'] === 'string' ? envelope['platform'] : null;
+        const toolInput = isObject(payload['tool_input']) ? payload['tool_input'] : {};
+        const sessionRaw = payload['session_id'] ?? envelope['session_id'];
+        const sessionId = typeof sessionRaw === 'string' ? sessionRaw : null;
+        const sendKind: SendKind | null = isResume ? classifySend(consumerRoot, toolInput, sessionId) : null;
+        // Only the verdict's label and reason codes reach disk — never the tool input.
+        const reuse = isResume
+            ? null
+            : shadowReuseVerdict({
+                  host_resume: deps.host_resume ?? probeHostCapabilities(platform).worker_resume,
+                  workers: deps.workers ?? null,
+                  context: deps.context ?? null,
+              });
 
         const stats = openRecordStats(consumerRoot);
         // Pre-spawn there is no agent id to resolve a parent from; the deepest
@@ -167,7 +351,16 @@ export function processEnvelope(envelope: JsonValue, consumerRoot: string): numb
             // one the ledger already fixed for itself.
             ledger_present: stats.ledger_present,
             stale_open_excluded: stats.stale_excluded,
-            candidates: verdicts.map((v) => ({ label: v.label, would_deny: v.would_deny, on: v.on })),
+            // A message to a running worker starts no run, so it is not set
+            // against a threshold that counts runs.
+            ...(sendKind === 'message_running'
+                ? {}
+                : { candidates: verdicts.map((v) => ({ label: v.label, would_deny: v.would_deny, on: v.on })) }),
+            dispatch_kind: sendKind ?? 'spawn',
+            resume_admission: platform !== null && RESUME_ADMISSION_OBSERVED.has(platform) ? 'counted' : 'unobserved',
+            ...(reuse === null ? {} : { reuse }),
+            // A recent host-sourced rate marker: a new spawn would have waited.
+            ...(isResume ? {} : { rate_window: recentHostMarker(consumerRoot) ? 'would_wait' : 'clear' }),
             // Shadow posture is a property of this file, not of a setting —
             // there is no code path here that can deny.
             posture: 'shadow',

package/src/scripts/hooks/state_io.ts

@@ -280,7 +280,7 @@ export function atomic_write_text(target: string, text: string): void {
  *
  * PLATFORM AND VERSION the guarantee is claimed on: **local filesystems on the
  * platforms this package supports** — macOS/APFS and Linux/ext4|btrfs|xfs, on
- * Node >= 20.11.0 (`package.json` `engines`). Native Windows is explicitly not
+ * Node >= 22.6.0 (`package.json` `engines`). Native Windows is explicitly not
  * a first-class target (`docs/installation.md` § Windows names WSL2 or Git
  * Bash), so no claim is made for it. Verified locally on Darwin 24.6.0 arm64.
  *
@@ -708,7 +708,7 @@ export function session_state_file(dir: string, session_id: string): string {
  * FILESYSTEMS WITHOUT HARD LINKS fall back to the racy sequence, deliberately.
  * The peer-review round asked for this before accepting `link` as the fix, and
  * it was the one condition of the three not already met: `linkSync` is the
- * tree's first, `engines` only pins Node >= 20.11, and `installation.md` names
+ * tree's first, `engines` only pins Node >= 22.6, and `installation.md` names
  * Windows — so a share, a FUSE mount, or a restricted container can answer
  * `EPERM` / `ENOSYS` / `EXDEV` / `EOPNOTSUPP` / `EMLINK`. Throwing there would
  * be caught by the pruner's outer handler and leave the tombstone behind, which

package/src/scripts/hooks/svg_obligation.ts

@@ -54,6 +54,15 @@
  *         paragraph promised more than the code did (finding 2 of this
  *         change's own completion review), and a gate whose documented
  *         assurance outruns its implementation is quoted as written.
+ *
+ *         SUPERSEDED WHERE A RECORD EXISTS. On a host whose `post_tool_use`
+ *         recorder is live, the transcript reading above is not consulted at all: a manifest counts
+ *         only when its current bytes hash to the digest the hook recorded as
+ *         a standalone render of that file finished (`_lib/asset_render_record.ts`).
+ *         No write-route pattern list stands in for that observation, so a
+ *         manifest written by ANY other route discharges nothing. The paragraph
+ *         above remains the rule only where no record exists, and the refusal
+ *         says so.
  *   (iv)  A deleted `.svg` opens no obligation — it has no current digest, so
  *         there is nothing a render could be bound to.
  *
@@ -74,6 +83,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { isAssetRenderCommand } from '../_lib/verification_command.js';
+import {
+    RENDER_REL,
+    hasInstrumentGap,
+    isPureRender,
+    readAssetRenderRecords,
+    recordedManifest,
+    type AssetRenderRecord,
+} from '../_lib/asset_render_record.js';
 import type { ToolCall } from '../_lib/turn_end_transcript.js';
 
 /**
@@ -83,7 +100,7 @@ import type { ToolCall } from '../_lib/turn_end_transcript.js';
  * Two copies of a command-shape regex is how the two detectors come to
  * disagree about what a render is.
  */
-export { isAssetRenderCommand };
+export { isAssetRenderCommand, isPureRender, RENDER_REL };
 
 /**
  * Tools that WRITE. One copy, here rather than imported from the gate: the
@@ -91,9 +108,6 @@ export { isAssetRenderCommand };
  */
 const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
-/** Where `ui:render` writes. One copy of the path, shared with the CLI by value. */
-export const RENDER_REL = path.join('agents', 'runtime', 'state', 'render');
-
 /**
  * Paths whose `.svg` files are planted on purpose. Precision (ii).
  *
@@ -255,6 +269,44 @@ export interface SvgObligationInputs {
      * none of them discharges anything (16.5.0 release review).
      */
     renderDirTampered?: boolean;
+    /**
+     * The renders the `post_tool_use` recorder saw finish this turn, or
+     * `null` where no recorder is live. An array — even an empty one — is the
+     * ONLY evidence read: the transcript fields above are then ignored.
+     */
+    recorded?: readonly AssetRenderRecord[] | null;
+}
+
+/** Appended to every refusal on a host with no live recorder. Pinned verbatim. */
+export const TRANSCRIPT_FALLBACK_REASON =
+    'transcript fallback: no readable `post_tool_use` render record exists for this turn — no live ' +
+    'recorder on this host (`agent-config hooks:status`), or a render whose exit status the host did not ' +
+    'report — so the manifest was read under the transcript rule — ' +
+    'an omission check, not an attestation';
+
+/** The record-path verdict for one file. */
+function recordVerdict(
+    root: string,
+    abs: string,
+    digest: string,
+    records: readonly AssetRenderRecord[],
+): DischargeKind | string {
+    let changed = false;
+    for (const r of records) {
+        if (path.resolve(root, r.file) !== abs || r.file_digest !== digest) continue;
+        const read = recordedManifest(root, r);
+        if (read === null) continue;
+        if ('changed' in read) {
+            changed = true;
+            continue;
+        }
+        const kind = dischargeFor([read.manifest as AssetManifestish], digest);
+        if (kind !== null) return kind;
+    }
+    return changed
+        ? 'the manifest the observed render left has changed since, so it is no longer the record of that render'
+        : 'no successful `ui:render --profile asset` of these bytes was observed by the hook this turn with a ' +
+              'manifest that discharges them — a manifest written by any other route discharges nothing';
 }
 
 /**
@@ -294,6 +346,13 @@ export function readSvgObligations(root: string, inputs: SvgObligationInputs): S
         }
         const digest = crypto.createHash('sha256').update(bytes).digest('hex');
 
+        if (Array.isArray(inputs.recorded)) {
+            const verdict = recordVerdict(root, path.resolve(root, abs), digest, inputs.recorded);
+            if (verdict === 'verified' || verdict === 'static-only') discharged.push({ file: relPath, kind: verdict });
+            else open.push({ file: relPath, reason: verdict });
+            continue;
+        }
+
         // (iii) The manifests are only consulted once a render was observed.
         // Reading them first and then discarding the verdict would make the
         // ordering look like a performance detail rather than the rule.
@@ -365,19 +424,6 @@ export function renderNames(commands: readonly string[], relPath: string): boole
     });
 }
 
-/**
- * A render call standing alone — no second command chained to it and no
- * redirect — so its text cannot also carry a write. A leading `cd <dir> &&`,
- * piping its output to a read-only filter, and folding stderr into stdout are
- * allowed.
- */
-export function isPureRender(command: string): boolean {
-    if (!isAssetRenderCommand(command)) return false;
-    const [head, ...pipes] = command.replace(/^\s*cd\s+[^;&|<>`$\n]+&&\s*/, '').replace(/\s\d?>&\d\b/g, ' ').replace(/\s2>\s*\/dev\/null\b/g, ' ').split('|');
-    if (/[;&<>`\n]|\$\(/.test(head ?? '')) return false;
-    return pipes.every((p) => /^\s*(tail|head|grep|jq|cat|less|wc)\b[^;&<>`|]*$/.test(p) && !/\$\(/.test(p));
-}
-
 /**
  * Does a shell command (other than a pure render) write somewhere a render
  * manifest could live? Read by shape: a write operator, together with the
@@ -430,7 +476,12 @@ function escapeRe(s: string): string {
 export function openSvgObligation(
     workspaceRoot: string,
     toolCalls: readonly ToolCall[],
+    recordedRaw: readonly unknown[] | null = null,
 ): { detector: 'verification'; evidence: string; reason: string; mode: 'transcript' } | null {
+    // A render the host reported no exit for is an instrument gap, never a
+    // missing render: refusing on it would refuse honest work for the host's
+    // silence, so the transcript rule answers instead.
+    const recordedRenders = recordedRaw === null || hasInstrumentGap(recordedRaw) ? null : recordedRaw;
     // Precision (iii). The render has to come AFTER the edit it describes, on
     // both evidence paths — `toolCalls` is assembled for both, so one rule
     // covers them rather than two that can disagree.
@@ -470,7 +521,11 @@ export function openSvgObligation(
 
     let reading: SvgObligationReading;
     try {
-        reading = readSvgObligations(workspaceRoot, { edits, renderDirTampered });
+        reading = readSvgObligations(workspaceRoot, {
+            edits,
+            renderDirTampered,
+            recorded: recordedRenders === null ? null : readAssetRenderRecords(recordedRenders),
+        });
     } catch {
         // A gate that crashed on its own instrument is a new failure mode on a
         // path meant to be inert. An unreadable render directory is no finding.
@@ -492,6 +547,7 @@ export function openSvgObligation(
         reason:
             `this turn edited an .svg and no render describes it${more} — ${first.reason}. ` +
             'A bare `ui:render --profile asset` that rendered nothing, and a test or lint run over other ' +
-            'files, both discharge nothing: the gate reads the render, never the call.',
+            'files, both discharge nothing: the gate reads the render, never the call.' +
+            (recordedRenders === null ? ` (${TRANSCRIPT_FALLBACK_REASON})` : ''),
     };
 }

package/src/scripts/hooks/tool_result_bytes_hook.ts

@@ -47,9 +47,17 @@
  * identical while the cost came back. The `RESULT_KEYS` literals below are the
  * key NAMES this concern looks under, not a read of the body.
  *
- * TWO COUNTS, ONE OF THEM REDUNDANT TODAY. `raw_bytes` is what
- * the host handed the dispatcher; `delivered_bytes` is what reached the
- * model. Today they are EQUAL BY CONSTRUCTION, and the construction is
+ * TWO COUNTS, ONE OF THEM REDUNDANT TODAY. Both count the host's HOOK
+ * ENVELOPE — the serialised `tool_response` the host hands a post_tool_use
+ * hook — and NOT what reached the model. The two differ by tool: for Edit and
+ * Write the hook envelope carries the whole original file while the model
+ * receives a short confirmation, so for those two tools the envelope is many
+ * times what the model saw, and for a text Read it is about the same. The
+ * payload the model received is a separate metric,
+ * `tool-result-payload-bytes`, read from transcripts. `raw_bytes` is
+ * the hook envelope the host handed the dispatcher; `delivered_bytes` is the
+ * hook envelope after any rewrite a concern could apply on its way back.
+ * Today they are EQUAL BY CONSTRUCTION, and the construction is
  * checkable: nothing under `src/` or `docs/` emits the host's result-rewrite
  * field, so no concern can rewrite a tool result on its way past. That
  * absence is a grep, and the grep lives in this concern's test rather than
@@ -196,10 +204,11 @@ function censusFile(consumerRoot: string): string {
 export interface CensusLine {
     ts: string;
     tool: string | null;
-    /** UTF-8 bytes the host handed the dispatcher. `null` ⇒ unmeasurable. */
+    /** UTF-8 bytes of the hook envelope the host handed the dispatcher. `null` ⇒ unmeasurable. */
     raw_bytes: number | null;
     /**
-     * UTF-8 bytes that reached the model.
+     * UTF-8 bytes of the hook envelope after any rewrite — NOT what reached
+     * the model (see the header; that figure is `tool-result-payload-bytes`).
      *
      * Equal to {@link CensusLine.raw_bytes} by construction today — nothing in
      * this tree rewrites a tool result. It is recorded anyway so that a later

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -1282,7 +1282,7 @@ function runDetectors(inputs: DetectorInputs): Finding[] {
         // on a completion CLAIM, and a turn waiting on a subagent has not
         // finished — so its closing is not the claim F is about. Same slot,
         // opposite trigger, opposite treatment of `dispatchOpen`.
-        openSvgObligation(workspaceRoot, toolCalls),
+        openSvgObligation(workspaceRoot, toolCalls, runState?.asset_renders ?? null),
         dispatchOpen ? null : detectUntestedChange(lastAssistant, toolCalls, runState),
     ]) {
         if (f) findings.push(f);

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -46,7 +46,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { hookSectionEnabled } from '../_lib/hook_settings.js';
-import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
+import { isHandoverShape, isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
@@ -164,17 +164,7 @@ export function isUiWrite(event: ToolEvent): boolean {
  * read-before-write, and `report_consultation_rate`'s output says so.
  */
 export function isArtifactRead(event: ToolEvent): boolean {
-    if (event.isWrite || !event.file) return false;
-    const normalized = event.file.replace(/\\/g, '/').toLowerCase();
-    return (
-        normalized.endsWith('design.html') ||
-        // The Claude Design canvas artboard. NOT covered by the line above:
-        // `ToDo.dc.html` does not end in `design.html`, which is exactly why
-        // the rule needed a second file pattern (2.5) and why the drift guard
-        // below reds when one is added here without the other.
-        normalized.endsWith('.dc.html') ||
-        normalized.includes('.claude/design-system/')
-    );
+    return !event.isWrite && isHandoverShape(event.file);
 }
 
 export interface SessionState {

package/src/scripts/hooks_doctor.ts

@@ -46,6 +46,17 @@ import {
   type RefusalStats,
 } from "./_lib/turn_end_refusals.js";
 import { ledgerWritable, readDelivered } from "./_lib/obligations.js";
+import {
+  defaultFloorPostureDeps,
+  readFloorPosture,
+  renderFloorPosture,
+  type FloorPosture,
+} from "./_lib/floor_posture.js";
+import {
+  readCredentialDenyTier,
+  renderCredentialDenyTier,
+  type CredentialDenyReport,
+} from "./_lib/credential_deny_rows.js";
 
 // src/scripts/hooks_doctor.ts → parents[2] (../../..) is the repo root,
 // mirroring the Python `Path(__file__).resolve().parents[2]`.
@@ -205,6 +216,18 @@ export interface DoctorPayload {
   obligation_ledger: ObligationLedgerStats;
   /** The machine's install stamp, for reading the version split below it. */
   install_boundary: InstallBoundary;
+  /**
+   * What carries the destructive-action floor here: whether the hook runtime
+   * resolves at all, the host sandbox keys, and any neighbour PreToolUse hook.
+   * Report only — it never changes the exit code and never writes a setting.
+   */
+  floor_posture: FloorPosture;
+  /**
+   * The host's own deny rows for the credential classes the read guard refuses:
+   * which are in force, and which the user would paste. Offered, never written:
+   * a written row would break the published no-host-setting-write commitment.
+   */
+  credential_deny: CredentialDenyReport;
 }
 
 /** What the doctor can say about the ledger without interpreting a single row. */
@@ -316,6 +339,8 @@ export function collect(
     turn_end_refusals,
     obligation_ledger: collectLedgerStats(project_root),
     install_boundary: readInstallBoundary(),
+    floor_posture: readFloorPosture(defaultFloorPostureDeps(project_root)),
+    credential_deny: readCredentialDenyTier(defaultFloorPostureDeps(project_root)),
   };
 }
 
@@ -500,6 +525,12 @@ export function _render_table(payload: DoctorPayload): string {
   lines.push(..._render_refusals(payload));
   lines.push("");
   lines.push(..._render_ledger(payload));
+  lines.push("");
+  lines.push("Floor posture");
+  lines.push("-".repeat(60));
+  lines.push(...renderFloorPosture(payload.floor_posture));
+  lines.push("");
+  lines.push(...renderCredentialDenyTier(payload.credential_deny));
   // Dispatch-issues detail — last 20 grouped by concern.
   if (payload.dispatch_issues.length > 0) {
     lines.push("");