@event4u/agent-config 10.3.0 → 10.4.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -129,6 +129,7 @@ import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
+import { openRecordStats } from './subagent_ledger_hook.js';
 
 /** Dispatcher-internal block code. Pinned to 1 by `concern_block_exit_parity`. */
 const EXIT_BLOCK = 1;
@@ -842,6 +843,39 @@ export function main(): number {
 
     const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined) || process.cwd();
 
+    // Layer 1b — an open subagent dispatch is an EXPLICIT allow
+    // (road-to-subagent-lifecycle-integrity Phase 3 Step 2).
+    //
+    // A turn waiting on an async subagent has, by construction, outstanding
+    // work the model cannot finish in this turn. Refusing it is the upstream
+    // Stop-hook x async-subagent loop shape (anthropics/claude-code#55754):
+    // the gate refuses, the model still cannot proceed because the dispatch
+    // has not returned, and the refusal repeats.
+    //
+    // This is an allow path and can never become a deny path — it only ever
+    // lets a turn END that would otherwise have been refused. It reads the
+    // Phase-1 ledger; a ledger that is absent, empty or unreadable yields zero
+    // open records and changes nothing, so the gate degrades to exactly its
+    // previous behaviour rather than failing open in the dangerous direction.
+    //
+    // R2 round 2, finding 2: it used to be an early `return EXIT_ALLOW`, which
+    // suppressed ALL FOUR detectors. A pending dispatch explains a promissory
+    // closing (A) and an unsettled completion claim (D); it explains nothing
+    // about a language mismatch (B) or an unverified edit (C), and silencing
+    // those was scope Step 2 never asked for. Applied per detector below.
+    //
+    // R2 round 2, finding 1: the count is TTL-filtered inside
+    // `openRecordStats`. A leaked record from a dispatch that never returned
+    // would otherwise read as "a dispatch is open" forever and, because this
+    // branch is an ALLOW, disable those two detectors indefinitely with no
+    // signal — the ledger's own leak inherited with the opposite polarity.
+    let dispatchOpen = false;
+    try {
+        dispatchOpen = openRecordStats(workspaceRoot).open_count > 0;
+    } catch {
+        // An unreadable ledger is not a reason to change the verdict.
+    }
+
     const transcriptPath = str(
         (payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined,
     );
@@ -881,7 +915,10 @@ export function main(): number {
     // second, configurable notion of warranted layered on top of it.
     const findings: Finding[] = [];
     for (const f of [
-        detectPromissory(lastAssistant),
+        // A and D are the completion-adjacent pair a pending dispatch excuses
+        // (Phase 3 Step 2, narrowed by R2 round 2 finding 2). B and C are not
+        // excused by anything about a dispatch and run unchanged.
+        dispatchOpen ? null : detectPromissory(lastAssistant),
         detectLanguage(lastAssistant, readLanguagePin(workspaceRoot)),
         detectUnverifiedEdit(toolCalls),
         // Round 7 § Phase 1 — detector D, in the same unconditional list as the
@@ -891,7 +928,7 @@ export function main(): number {
         // gating is where the comment above says gating belongs — inside the
         // detector: no CI observed, or a settled read, or no completion claim
         // ⇒ no finding.
-        detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot)),
+        dispatchOpen ? null : detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot)),
     ]) {
         if (f) findings.push(f);
     }

package/src/scripts/lint_hook_manifest.ts

@@ -55,6 +55,8 @@ const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
   "stop",
   "pre_compact",
   "agent_error",
+  "subagent_start",
+  "subagent_stop",
 ]);
 
 // Known platform identifiers.

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -51,19 +51,40 @@
  * findings under `--strict` · 2 usage or IO error. A scan that walked no rules
  * exits 2 rather than green — a gate that scanned nothing must never read as a
  * pass.
+ *
+ * `--self-test` proves those rejections still fire in the binary a contributor
+ * runs, not merely in the imported functions `tests/scripts/pack_reach.test.ts`
+ * exercises. `--root <dir>` exists for it: the three inputs are ordinary tree
+ * reads, so a temporary fixture repo can reproduce every verdict, which is why
+ * this gate adopts the harness rather than claiming the exemption.
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const RULES_DIR = path.join(REPO, 'src', 'rules');
-const SKILLS_DIR = path.join(REPO, 'src', 'skills');
-const PACKS_FILE = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+
+interface Roots {
+    rulesDir: string;
+    skillsDir: string;
+    packsFile: string;
+}
+
+/** The three inputs, resolved against `root` so a fixture tree can stand in. */
+function rootsFor(root: string): Roots {
+    return {
+        rulesDir: path.join(root, 'src', 'rules'),
+        skillsDir: path.join(root, 'src', 'skills'),
+        packsFile: path.join(root, 'src', 'config', 'discovery', 'packs.yml'),
+    };
+}
 
 export interface PackDef {
     id: string;
@@ -212,10 +233,165 @@ export function analyze(
     return findings;
 }
 
-function main(): number {
-    const packs = readPacks(PACKS_FILE);
-    const rules = readRules(RULES_DIR);
-    const skillPacks = readSkillPacks(SKILLS_DIR);
+interface Args {
+    quiet: boolean;
+    strict: boolean;
+    selfTest: boolean;
+    root: string;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, strict: false, selfTest: false, root: REPO };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--quiet') args.quiet = true;
+        else if (a === '--strict') args.strict = true;
+        else if (a === '--self-test') args.selfTest = true;
+        else if (a === '--root') {
+            // Never fall back to the real repo. A self-test whose root argument
+            // went missing would otherwise scan the live tree instead of its
+            // fixture and could still exit 0 — a green run proving nothing,
+            // which is the exact failure `_lib/gate_self_test.ts` exists for.
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error('--root requires a directory argument');
+            }
+            args.root = value;
+            i += 1;
+        }
+    }
+    return args;
+}
+
+/**
+ * Build a fixture tree. `packsYml` is written verbatim; each rule and skill is
+ * a minimal frontmatter block, which is all `readRules` / `readSkillPacks`
+ * ever look at.
+ */
+function _fixture(
+    tmp: string,
+    name: string,
+    packsYml: string,
+    rules: ReadonlyArray<{ name: string; packs?: string[]; routes: string[] }>,
+    skills: ReadonlyArray<{ name: string; packs?: string[] }>,
+): string {
+    const root = path.join(tmp, name);
+    const { rulesDir, skillsDir, packsFile } = rootsFor(root);
+    fs.mkdirSync(rulesDir, { recursive: true });
+    fs.mkdirSync(skillsDir, { recursive: true });
+    fs.mkdirSync(path.dirname(packsFile), { recursive: true });
+    fs.writeFileSync(packsFile, packsYml, 'utf-8');
+    const list = (key: string, values?: string[]): string =>
+        values === undefined ? '' : `${key}: [${values.join(', ')}]\n`;
+    for (const rule of rules) {
+        fs.writeFileSync(
+            path.join(rulesDir, `${rule.name}.md`),
+            `---\n${list('packs', rule.packs)}${list('routes_to', rule.routes)}---\n\n# ${rule.name}\n`,
+            'utf-8',
+        );
+    }
+    for (const skill of skills) {
+        fs.mkdirSync(path.join(skillsDir, skill.name), { recursive: true });
+        fs.writeFileSync(
+            path.join(skillsDir, skill.name, 'SKILL.md'),
+            `---\n${list('packs', skill.packs)}---\n\n# ${skill.name}\n`,
+            'utf-8',
+        );
+    }
+    return root;
+}
+
+function _selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lrspr-selftest-'));
+    const runRaw = (args: readonly string[]): number =>
+        runGateCli(REPO, 'src/scripts/lint_rule_skill_pack_reach.ts', args, REPO);
+    const run = (root: string, extra: readonly string[] = []): number =>
+        runRaw(['--root', root, '--quiet', ...extra]);
+
+    // `alpha` stands alone; `beta` pulls `alpha` in transitively.
+    const PACKS = '- id: alpha\n- id: beta\n  requires: [alpha]\n- id: gamma\n';
+
+    try {
+        const unreachable = _fixture(
+            tmp,
+            'unreachable',
+            PACKS,
+            [{ name: 'r', packs: ['gamma'], routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const viaRequires = _fixture(
+            tmp,
+            'via-requires',
+            PACKS,
+            [{ name: 'r', packs: ['beta'], routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const unscopedRule = _fixture(
+            tmp,
+            'unscoped-rule',
+            PACKS,
+            [{ name: 'r', routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const unscopedSkill = _fixture(
+            tmp,
+            'unscoped-skill',
+            PACKS,
+            [{ name: 'r', packs: ['gamma'], routes: ['skill:s'] }],
+            [{ name: 's' }],
+        );
+        const empty = _fixture(tmp, 'empty', PACKS, [], [{ name: 's', packs: ['alpha'] }]);
+
+        return runSelfTest({
+            gate: 'lint_rule_skill_pack_reach',
+            minCases: 6,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'a rule routing into a pack its own closure never reaches is rejected under --strict',
+                    expect: 'reject',
+                    run: () => run(unreachable, ['--strict']),
+                },
+                {
+                    name: 'an empty rule corpus refuses to report a pass',
+                    expect: 'reject',
+                    run: () => run(empty, ['--strict']),
+                },
+                {
+                    name: 'the same route passes when `requires` pulls the skill pack in transitively',
+                    expect: 'accept',
+                    run: () => run(viaRequires, ['--strict']),
+                },
+                {
+                    name: 'an unscoped rule ships everywhere, so its route is always reachable',
+                    expect: 'accept',
+                    run: () => run(unscopedRule, ['--strict']),
+                },
+                {
+                    name: 'an unscoped skill ships everywhere, so no route into it can be unreachable',
+                    expect: 'accept',
+                    run: () => run(unscopedSkill, ['--strict']),
+                },
+                {
+                    name: '--root with no value is refused rather than silently scanning the real tree',
+                    expect: 'reject',
+                    run: () => runRaw(['--quiet', '--root']),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = _parseArgs(argv);
+    if (args.selfTest) return _selfTest();
+
+    const { rulesDir, skillsDir, packsFile } = rootsFor(args.root);
+    const packs = readPacks(packsFile);
+    const rules = readRules(rulesDir);
+    const skillPacks = readSkillPacks(skillsDir);
 
     if (rules.length === 0 || skillPacks.size === 0 || packs.size === 0) {
         process.stderr.write(
@@ -231,8 +407,7 @@ function main(): number {
     // --quiet suppresses the per-finding lines but never the count line: this
     // gate is expected to stay non-empty for a while, and a quiet run that
     // printed nothing at all would read as clean.
-    const quiet = process.argv.includes('--quiet');
-    if (!quiet) {
+    if (!args.quiet) {
         for (const finding of errors) {
             process.stdout.write(`❌  ${finding.subject} — ${finding.detail}\n`);
         }
@@ -241,16 +416,22 @@ function main(): number {
         }
     }
 
-    const strict = process.argv.includes('--strict');
+    // Two lines on purpose. `check_gate_coverage`'s SCANNED_RE is
+    // `/^\s*scanned:\s*(\d+)\s*$/m` — the count must END the line — so the
+    // detailed breakdown below can never satisfy it. This gate was registered
+    // `enforced` with `min_scanned: 90` and had therefore reported `null` since
+    // 924cad87f: an enforced floor that no output could ever meet. Emit the
+    // machine-readable contract line first, then the human breakdown.
+    process.stdout.write(`scanned: ${rules.length}\n`);
     process.stdout.write(
-        `scanned: ${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
+        `${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
     );
-    if (errors.length > 0 && !strict) {
+    if (errors.length > 0 && !args.strict) {
         process.stdout.write(
             `advisory run: ${errors.length} unreachable-route finding(s) reported, exit 0. Promote with --strict once the set is empty.\n`,
         );
     }
-    return strict && errors.length > 0 ? 1 : 0;
+    return args.strict && errors.length > 0 ? 1 : 0;
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {

package/tests/fixtures/hooks/subagent_start.json

@@ -0,0 +1,7 @@
+{
+  "session_id": "fixture-subagent-start-001",
+  "agent_id": "fixture-agent-0001",
+  "agent_type": "Explore",
+  "cwd": "/workspace",
+  "platform_hint": "claude"
+}

package/tests/fixtures/hooks/subagent_stop.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "fixture-subagent-stop-001",
+  "agent_id": "fixture-agent-0001",
+  "agent_type": "Explore",
+  "last_assistant_message": "{\"summary\":\"fixture envelope\",\"handoff\":\"none\",\"confidence\":\"high\",\"findings\":[],\"risks\":[]}",
+  "cwd": "/workspace",
+  "platform_hint": "claude"
+}