@event4u/agent-config 10.3.0 → 11.0.0

package/src/scripts/hook_manifest.yaml

@@ -535,6 +535,48 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-subagent-lifecycle-integrity Phase 1 (Steps 2+3) — the subagent
+  # lifecycle ledger. Binds ONLY the two new events; on every other slot it is
+  # not listed at all. Appends `subagent_start` / `subagent_stop` lines to
+  # gitignored runtime state and keeps one open-record file per live dispatch
+  # so depth and concurrency are derived from the set rather than asserted.
+  #
+  # CAPTURE ONLY, and that is load-bearing rather than cautious: Phase 1's
+  # falsifier (envelope return rate >=95% and no dispatch over 2x its tier
+  # budget-equivalent duration) can only be read off a window no mechanism
+  # reacted to. `validateResponse` runs in observe mode — the verdict is
+  # written down and dropped, never emitted as a decision. Phase 2's
+  # return-gate and Phase 3's spawn-guard are the concerns allowed to act, and
+  # both are pre-registered as gated on the baseline this one produces.
+  #
+  # Never blocks, never warns: exit 0 on every path including a malformed
+  # payload or an unwritable disk. fail_closed: false.
+  subagent-ledger:
+    script: src/scripts/hooks/subagent_ledger_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+  # road-to-subagent-lifecycle-integrity Phase 3 Step 1 — spawn guard, SHADOW
+  # ONLY, per docs/contracts/concern-activation-policy.md. On every Agent/Task
+  # call it appends one `spawn_guard_shadow` line recording what a guard WOULD
+  # have done at three candidate threshold pairs. It emits nothing to the model
+  # and has no code path that can deny.
+  #
+  # It skips the warn rung deliberately: the activation policy rules it out for
+  # a concern on its way to blocking, because a verified-firing per-turn
+  # injection left its own compliance rate unmoved (session-canary, 24 of 29)
+  # while both blocking carriers in conformance round 5 reached zero. A warn
+  # would pay this concern's full per-call cost and buy nothing measurable;
+  # shadow pays the same cost and buys the distribution the shipped threshold
+  # has to be derived from.
+  #
+  # Never blocks, never warns: exit 0 on every path. fail_closed: false.
+  spawn-guard-shadow:
+    script: src/scripts/hooks/spawn_guard_shadow_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    tools: [Agent, Task]
 
 # Role axis (road-to-token-economy-dispatch Phase 2). The dispatcher reads
 # AGENT_CONFIG_SESSION_ROLE (resolved via _lib/session_role.ts — set ONLY by
@@ -568,7 +610,7 @@ platforms:
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape, language-mirror]
     # round-5 § 6.1 — the ONLY binding on this slot in the tree. `pre_compact`
     # sets a pin-lost marker; the `post_tool_use` entry above re-emits the pin
@@ -577,6 +619,11 @@ platforms:
     # shape § 6.2 refuses. claude only: it is the sole verified platform, and
     # the measured compaction defect is a Claude Code transcript fact.
     pre_compact:      [language-mirror]
+    # road-to-subagent-lifecycle-integrity Phase 1 Step 1. `claude` is the only
+    # platform where both native events were measured present on the installed
+    # binary (2.1.229 — see the evidence page cited on the alias rows below).
+    subagent_start:   [subagent-ledger]
+    subagent_stop:    [subagent-ledger]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
   # on top of the Claude Code CLI. Same lifecycle vocabulary, same
@@ -607,8 +654,17 @@ platforms:
     # still costs the dispatch, and its entire output is thrown away.
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    # subagent-ledger IS bound here, unlike the two nudges above, and the
+    # difference is the delivery channel rather than the platform: the nudges
+    # depend on stdout reaching the model, which this trampoline discards by
+    # construction; the ledger's entire output is a disk append, which survives
+    # a discarded stdout and a discarded exit code alike. It stays dead until
+    # the upstream settings-source blockers land and the events actually fire —
+    # structurally ready, costing nothing in the meantime.
+    subagent_start:   [subagent-ledger]
+    subagent_stop:    [subagent-ledger]
 
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
   # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
@@ -698,6 +754,12 @@ native_event_aliases:
     PostToolUse:       post_tool_use
     PreToolUse:        pre_tool_use
     PreCompact:        pre_compact
+    # road-to-subagent-lifecycle-integrity Phase 1 Step 1. Both tokens were
+    # re-extracted from the installed binary at 2.1.229 (exact-token counts 12
+    # and 24) rather than carried over from the 2.1.220 spike — see
+    # agents/evidence/investigations/subagent-lifecycle-phase0-host-pin.md.
+    SubagentStart:     subagent_start
+    SubagentStop:      subagent_stop
   # Cowork shares Claude Code's PascalCase event vocabulary verbatim
   # (Cowork is Claude Code under the hood). Native names are duplicated
   # here rather than aliased so dispatcher logs / feedback carry the
@@ -710,6 +772,13 @@ native_event_aliases:
     PostToolUse:       post_tool_use
     PreToolUse:        pre_tool_use
     PreCompact:        pre_compact
+    # Cowork is Claude Code under the hood, so the subagent pair is aliased
+    # here for the same reason the rest of the table is duplicated rather than
+    # referenced. NOT independently measured on a Cowork build — the alias
+    # costs nothing if the host never sends the event, and the ledger records
+    # absence as data rather than assuming arrival.
+    SubagentStart:     subagent_start
+    SubagentStop:      subagent_stop
   cursor:
     sessionStart:        session_start
     sessionEnd:          session_end

package/src/scripts/hooks/concern_registry.ts

@@ -62,6 +62,8 @@ import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
 import { main as rereadGuardMain } from './reread_guard_hook.js';
 import { main as sessionEolMain } from './session_eol_hook.js';
+import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
+import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
 export type ConcernMain = (argv?: string[]) => number | undefined | void;
@@ -106,4 +108,6 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
     'src/scripts/hooks/reread_guard_hook.ts': rereadGuardMain as ConcernMain,
     'src/scripts/hooks/session_eol_hook.ts': sessionEolMain as ConcernMain,
+    'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
+    'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
 };

package/src/scripts/hooks/dispatch_hook.ts

@@ -80,6 +80,14 @@ export const EXIT_WARN = 2;
 // Per Council Round 2 (Q3): `agent_error` covers agent-level crashes
 // that are not concern-triggered, so chat-history can checkpoint
 // partial sessions on abnormal exit.
+//
+// `subagent_start` / `subagent_stop` (road-to-subagent-lifecycle-integrity
+// Phase 1 Step 1) are the dispatch-level twins of the session pair: they
+// bracket ONE subagent run rather than one session. The host tokens they map
+// to were re-extracted at 2.1.229 rather than carried over from the 2.1.220
+// spike — see agents/evidence/investigations/subagent-lifecycle-phase0-host-pin.md.
+// Only `claude` and `cowork` alias them today; every other platform simply
+// never sends them, which the alias table already expresses by omission.
 export const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
   "session_start",
   "session_end",
@@ -89,6 +97,8 @@ export const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
   "stop",
   "pre_compact",
   "agent_error",
+  "subagent_start",
+  "subagent_stop",
 ]);
 
 const _SEVERITY_BY_EXIT: Record<number, string> = {

package/src/scripts/hooks/host_semantics.ts

@@ -62,6 +62,8 @@ const CLAUDE_HOOK_EVENT_NAME: Record<string, string> = {
     session_end: "SessionEnd",
     stop: "Stop",
     pre_compact: "PreCompact",
+    subagent_start: "SubagentStart",
+    subagent_stop: "SubagentStop",
 };
 
 /**

package/src/scripts/hooks/spawn_guard_shadow_hook.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env tsx
+/**
+ * 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.
+ *
+ * ── Why shadow and not warn ───────────────────────────────────────────────
+ *
+ * The plan's own text said "ships warn-first … then flips to deny on
+ * evidence, per the concern activation policy". That policy did not exist
+ * when the step was written — three roadmaps cited it and none had written
+ * it — so the step could not be executed without inventing the posture it had
+ * deliberately deferred. The policy now exists, and it rules the warn rung
+ * out for a concern on its way to blocking:
+ *
+ *   - `session-canary` is a per-turn injection, VERIFIED to fire, whose
+ *     compliance miss rate did not move (24 of 29 task starts).
+ *   - conformance round 5: both blocking carriers reached zero violations,
+ *     neither advisory carrier did.
+ *
+ * A warn would pay this concern's full per-call cost and, on the evidence,
+ * buy nothing. Shadow pays the same cost and buys the distribution the
+ * threshold has to be derived from — which is the only thing standing
+ * between this guard and a number picked out of the air.
+ *
+ * ── Why several thresholds at once ────────────────────────────────────────
+ *
+ * One candidate answers yes/no; a spread answers "at which value does this
+ * start catching things, and at which does it start denying legitimate
+ * work". The policy requires the shipped default to sit at the legitimate
+ * distribution's 99th percentile + 1, and that cannot be read off a single
+ * candidate. The plan's own N=2 / M=4 is included as one candidate among
+ * three, which is the honest status of a pre-registered starting value.
+ *
+ * ── What this does NOT measure, stated rather than implied ────────────────
+ *
+ * Depth. The estimate is the deepest open record + 1, maximised over ALL open
+ * records regardless of lineage, because pre-spawn there is no `agent_id` to
+ * resolve a real parent from. That makes it >= 2 whenever anything is open —
+ * flat fan-out included — so it **decides nothing**: no candidate's verdict
+ * reads it, and the line carries `depth_usable_for_derivation: false`. It
+ * 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.
+ */
+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 { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The two subagent-dispatch tool names this repo has observed across hosts. */
+export const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set(['Agent', 'Task']);
+
+/** One candidate guard configuration under shadow evaluation. */
+export interface Candidate {
+    readonly label: string;
+    /** Refuse when the new dispatch's depth would reach this. */
+    readonly max_depth: number;
+    /** Refuse when this many dispatches are already open. */
+    readonly max_concurrent: number;
+}
+
+/**
+ * The candidate spread. `n2m4` is the roadmap's pre-registered pair, carried
+ * as ONE candidate rather than as the answer; the wider pairs exist so the
+ * shadow log yields a curve instead of a single verdict.
+ */
+export const CANDIDATES: readonly Candidate[] = [
+    { label: 'n2m4', max_depth: 2, max_concurrent: 4 },
+    { label: 'n3m6', max_depth: 3, max_concurrent: 6 },
+    { label: 'n4m8', max_depth: 4, max_concurrent: 8 },
+];
+
+export interface ShadowVerdict {
+    readonly label: string;
+    readonly would_deny: boolean;
+    /** Which arm tripped. Only `concurrent` can appear — see below. */
+    readonly on: string[];
+}
+
+/**
+ * Pure: evaluate every candidate against the observed state.
+ *
+ * **Only the concurrency arm produces a verdict** (R2 round 2, finding 3). The
+ * depth arm is confounded by construction and was silently poisoning the very
+ * curve this shadow exists to produce:
+ *
+ * `depth_estimate` is `max(open depths) + 1`, maximised over ALL open records
+ * regardless of lineage, and every record carries depth >= 1. So the estimate
+ * is >= 2 whenever anything at all is open — including a flat fan-out with no
+ * nesting whatsoever. `n2m4`'s depth arm would then read `would_deny` on an
+ * ordinary sibling spawn, and the 99th-percentile derivation the activation
+ * policy prescribes would be computed over the estimator's artefact rather
+ * than over observed nesting.
+ *
+ * This was not caught by reasoning; it was caught by a reviewer after an
+ * end-to-end probe produced exactly that reading and it was briefly mistaken
+ * for a signal.
+ *
+ * Real per-spawn depth needs the parent lineage, which needs `agent_id` on the
+ * PreToolUse payload — Phase 0 Step 4, still open. Until it lands, the depth
+ * number rides along as context, flagged unusable, and decides nothing.
+ */
+export function evaluateCandidates(depthEstimate: number, concurrentOpen: number): ShadowVerdict[] {
+    void depthEstimate;
+    return CANDIDATES.map((c) => {
+        const on: string[] = [];
+        if (concurrentOpen >= c.max_concurrent) on.push('concurrent');
+        return { label: c.label, would_deny: on.length > 0, on };
+    });
+}
+
+function unwrapPayload(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+function extractToolName(payload: JsonObject): string | null {
+    const v = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+export function processEnvelope(envelope: JsonValue, consumerRoot: string): 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;
+
+        const stats = openRecordStats(consumerRoot);
+        // Pre-spawn there is no agent id to resolve a parent from; the deepest
+        // open record + 1 is an upper bound, exact only for a linear chain.
+        const depthEstimate = stats.max_depth + 1;
+        const verdicts = evaluateCandidates(depthEstimate, stats.open_count);
+        const nowIso = new Date().toISOString();
+
+        appendLedgerLine(consumerRoot, nowIso, {
+            event: 'spawn_guard_shadow',
+            ts: nowIso,
+            tool: toolName,
+            concurrent_open: stats.open_count,
+            depth_estimate: depthEstimate,
+            depth_estimate_basis: 'deepest-open-record-plus-one',
+            // R2 round 2, finding 3: the estimate is >= 2 whenever anything is
+            // open, nesting or not, so it must not reach a derivation. It rides
+            // as context with the flag that says so.
+            depth_usable_for_derivation: false,
+            // R2 round 2, finding 4: without these, a quiet estate, a ledger
+            // this hook cannot see, and a root mismatch all emit byte-identical
+            // records — the instrument-goes-quiet failure one layer up from the
+            // 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 })),
+            // Shadow posture is a property of this file, not of a setting —
+            // there is no code path here that can deny.
+            posture: 'shadow',
+        });
+    } catch {
+        // Never disturb a tool call for a measurement.
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+// R2 round 2, finding 6: this file used to carry its OWN root-resolution
+// order, a third one alongside the ledger's and the turn-end gate's. A reader
+// that resolves a different root than the writer finds an empty ledger, and
+// every consumer here reads an empty ledger as "nothing is open" — a silent
+// wrong answer rather than an error. One exported resolver, three callers.
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: JsonValue = {};
+    try {
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, resolveConsumerRoot(envelope));
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());