@event4u/agent-config 9.29.0 → 9.30.0

package/src/scripts/hooks/delegation_nudge_hook.ts

@@ -99,6 +99,7 @@ import { load_agent_settings } from "../_lib/agent_settings.js";
 import { probeHostCapabilities } from "../_lib/host_capability.js";
 import type { ActivationInputs, Classification, TaskSignals } from "../_lib/auto_dispatch.js";
 import { classifyLadder, type LadderRung } from "../_lib/judgment_ladder.js";
+import { resolveSessionRole } from "../_lib/session_role.js";
 import { resolveSubagentRouting, type Tier } from "../_lib/subagent_routing.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
 
@@ -338,6 +339,17 @@ export function buildNudgeLine(
 ): string {
   const unit = sliceCount === 1 ? "slice" : "slices";
   const rungLabel = rung === null ? "rung-?" : `rung-${rung}`;
+  // Rung 0.5 (token-economy-dispatch 4.3): cite the sub-spawn ask path —
+  // never a spawn recommendation for a question-shaped slice.
+  if (rung === 0.5) {
+    return (
+      `<delegation-nudge>rung-0.5: ask, est. <1k tokens. This is a single bounded ` +
+      `question — answer it via ONE completion ` +
+      "(`./scripts-run src/scripts/ask_transport \"<question>\"`) instead of a " +
+      `subagent spawn (measured spawn floor: ~251k tokens) — ` +
+      `${classification.reason}.</delegation-nudge>`
+    );
+  }
   // Rung 1 (single bounded slice) carries no do-in-steps/do-in-parallel
   // mode of its own — `classification.mode` is `null` for that shape.
   const modeLabel = classification.mode ?? "single-slice";
@@ -353,7 +365,11 @@ export interface NudgeResult {
   classification: Classification;
   sliceCount: number;
   tier: Tier;
-  /** The judgment-ladder rung this verdict resolved to (2.4) — 1 or 2 only, this concern's scope. */
+  /** The judgment-ladder rung this verdict resolved to (2.4) — 1 or 2 in
+   *  production today: classifyPrompt returns null for every non-subagent
+   *  verdict including rung 0.5 (the carrier stays silent on questions);
+   *  buildNudgeLine's 0.5 branch is vocabulary for orchestrator-facing
+   *  surfaces and direct callers. */
   rung: LadderRung;
 }
 
@@ -374,9 +390,30 @@ export function classifyPrompt(
       workspace_root,
       hostId,
     );
-    const ladder = classifyLadder({ taskText: prompt, signals, activation, agentTeams });
+    // Recursive-dispatch guard input — the SHARED session-role detector
+    // (_lib/session_role.ts, "one detector, two consumers, test-pinned
+    // equal"): a session marked worker/reviewer by a suite-owned spawn
+    // wrapper never receives a delegation nudge. Unmarked sessions keep
+    // the documented gap (no host discriminator exists) — fail-open.
+    const sessionRole = resolveSessionRole(process.env);
+    const ladder = classifyLadder({
+      taskText: prompt,
+      signals,
+      activation,
+      agentTeams,
+      insideSubagentSession: sessionRole !== "orchestrator",
+    });
+    // Rung 0.5 (token-economy-dispatch 4.3): on a USER prompt the carrier
+    // stays SILENT for a bounded question — the agent answers in-session at
+    // zero marginal cost, and injecting an ask_transport citation here would
+    // be the cosmetic-injection failure this repo measured at 24/29 misses.
+    // The 0.5 verdict is an ORCHESTRATOR-facing routing datum (slice
+    // resolution); buildNudgeLine carries the rung-0.5 vocabulary for those
+    // surfaces. Silence here also guarantees a question-shaped prompt can
+    // never produce a spawn nudge ("the carrier stops nudging full spawns
+    // for question-shaped slices").
     if (ladder.verdict !== "subagent") {
-      return null; // rung-0 script, rung-3/4 team/council, or ∅ ask/in-session — out of scope here
+      return null; // rung-0 script, rung-0.5 ask-transport, rung-3/4 team/council, or ∅ user-ask/in-session
     }
     const tier = recommendSliceTier(downshift, separate_quota_pool);
     // Rung 1 (single bounded slice) has no explicit slice count of its own —

package/src/scripts/hooks/dispatch_hook.ts

@@ -48,6 +48,7 @@ import {
   clearHookStdinOverride,
 } from "./hook_stdin.js";
 import { emitFor, type Severity } from "./host_semantics.js";
+import { resolveSessionRole, type SessionRole } from "../_lib/session_role.js";
 
 // Free-form JSON values flow through every helper here; a documented
 // alias keeps the surface honest without `any` (ADR-200 § strict TS).
@@ -305,12 +306,42 @@ export function _concern_matches_tool(concern: JsonObject, tool_name: string): b
 }
 
 /**
- * Return the ordered concern definitions for (platform, event).
+ * Role axis (road-to-token-economy-dispatch Phase 2): the set of concern
+ * names the given role drops. Empty for `orchestrator`, for a role without
+ * a manifest entry (fail-open, 2.4), and ALWAYS for `pre_tool_use` — the
+ * safety-guard slot is structurally undroppable (2.3); `lint_hook_manifest`
+ * additionally rejects a drop entry bound to that slot at CI time.
+ */
+export function _role_drop_set(
+  manifest: JsonObject,
+  role: string,
+  event: string,
+): Set<string> {
+  if (!role || role === "orchestrator" || event === "pre_tool_use") {
+    return new Set();
+  }
+  const rolesRaw = manifest["roles"];
+  const roleSpec = _isObject(rolesRaw) ? rolesRaw[role] : undefined;
+  if (!_isObject(roleSpec)) {
+    return new Set(); // unknown role → full chain (fail-open)
+  }
+  const drop = roleSpec["drop"];
+  if (!Array.isArray(drop)) {
+    return new Set();
+  }
+  return new Set(drop.filter((d): d is string => typeof d === "string"));
+}
+
+/**
+ * Return the ordered concern definitions for (platform, event) under the
+ * given session role (default `orchestrator` — byte-identical to the
+ * pre-role-axis behaviour).
  */
 export function _resolve_concerns(
   manifest: JsonObject,
   platform: string,
   event: string,
+  role: SessionRole = "orchestrator",
 ): ConcernDef[] {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
@@ -325,10 +356,14 @@ export function _resolve_concerns(
   if (!Array.isArray(names)) {
     return [];
   }
+  const dropped = _role_drop_set(manifest, role, event);
   const concernsRaw = manifest["concerns"];
   const concerns_def = _isObject(concernsRaw) ? concernsRaw : {};
   const out: ConcernDef[] = [];
   for (const name of names) {
+    if (typeof name === "string" && dropped.has(name)) {
+      continue; // role-dropped orchestrator-only concern
+    }
     const spec = typeof name === "string" ? concerns_def[name] : undefined;
     if (!spec || !_isObject(spec)) {
       process.stderr.write(
@@ -1035,12 +1070,14 @@ export function main(argv?: string[]): number {
 
   const payload_text = process.stdin.isTTY ? "" : _readStdin();
   _maybe_capture_payload(args, payload_text);
-  const concerns = _resolve_concerns(manifest, args.platform, args.event);
+  const session_role = resolveSessionRole(process.env);
+  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role);
 
   if (args.dry_run) {
     const plan = {
       platform: args.platform,
       event: args.event,
+      role: session_role,
       concerns: concerns.map((c) => c["name"]),
     };
     process.stdout.write(_py_json_dumps(plan, 2) + "\n");

package/src/scripts/hooks/edit_shape_hook.ts

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * Edit-shape advisory — `post_tool_use` concern
+ * (road-to-token-economy-cache Phase 5.1/5.2).
+ *
+ * Fires when a `Write` tool call REPLACED an existing, git-tracked file of at
+ * least `MIN_FILE_LINES` lines while the effective change was at most
+ * `MAX_DIFF_RATIO` of the file — the wasteful shape where the agent re-emits
+ * a whole file to change a few lines. One advisory line names the cheaper
+ * primitive: a targeted Edit pays for the diff, not the file.
+ *
+ * ## Committed thresholds (roadmap 5.1 — committed in this concern header)
+ *
+ * `MIN_FILE_LINES = 50` and `MAX_DIFF_RATIO = 0.20` are COMMITTED constants,
+ * not tunables: the roadmap requires the thresholds to live in the concern
+ * header so a threshold change is a reviewed diff, never a silent drift.
+ * Ratio definition: `(added + deleted) / current file line count` from
+ * `git diff --numstat` — a 5-line in-place change on a 60-line file measures
+ * as 10/60 ≈ 17 % (numstat counts a changed line once on each side).
+ *
+ * ## Honest mechanism — why git, not the payload
+ *
+ * At PostToolUse time the target file is ALREADY overwritten on disk, and the
+ * PostToolUse payload carries only the NEW content (`tool_input.content`) —
+ * the pre-image is not observable from the event itself (verified against the
+ * payload shapes `design_slop_hook.ts` / `orchestration_record_hook.ts`
+ * read). The pre-image that IS still observable is git's: for a tracked file,
+ * `git diff HEAD --numstat -- <path>` diffs the working tree against the last
+ * commit, so `added + deleted` is a deterministic effective-diff measure.
+ * Two consequences, stated rather than hidden:
+ *   - The measured diff is CUMULATIVE since HEAD for that path, not the delta
+ *     of this one Write. A session's second small Write to the same file
+ *     measures both writes together — an over-count that only makes the
+ *     ratio LARGER, i.e. biases toward silence, never toward a false fire.
+ *   - An untracked (brand-new) file has no HEAD pre-image and produces no
+ *     numstat row → silent. Correct: writing a new file is not a wasteful
+ *     replace, it is the only primitive that creates one.
+ * A path with NO unstaged/staged modification vs HEAD (diff of 0 lines) is
+ * also silent — the fire condition per the roadmap is "tracked in git with an
+ * observable modification whose ratio is small", and a 0-row diff cannot
+ * distinguish a no-op Write from an already-committed state.
+ *
+ * ## Once-per-session gate (roadmap 5.2)
+ *
+ * Mirrors `end_review_nudge_hook.ts`'s F2 marker: a JSON marker under
+ * `<workspace_root>/agents/runtime/state/edit-shape/<sha256(session)>.json`
+ * (gitignored — `agents/runtime/` is blanket-ignored) records that THIS
+ * session already fired; later qualifying Writes in the same session return
+ * silently. The marker carries a timestamp and nothing else — counts/flags
+ * only, never content. The economy nudge must not itself become an economy
+ * problem.
+ *
+ * ## Path exemptions (committed constant — shared list with `reread-guard`)
+ *
+ * `dist/**`, any path containing `/generated/`, `*.lock`, `*.min.*`, and
+ * `agents/runtime/**` are exempt: generated/derived surfaces are legitimately
+ * re-emitted wholesale, and nudging there is pure noise.
+ *
+ * ## Delivery — `{decision:"warn", reason, additional_context}` at exit 2
+ *
+ * Mirrors `delegation_nudge_hook.ts` exactly. Severity is taken from the
+ * EXIT CODE, not the `decision` field: a warn verdict is reported at exit
+ * `EXIT_WARN` (2) so `host_semantics.emitFor` reduces it to severity `"warn"`
+ * and forwards `additional_context` into
+ * `hookSpecificOutput.additionalContext`.
+ *
+ * WHY EXIT 2 NEVER BLOCKS (copied from `delegation_nudge_hook.ts`, verified
+ * there against the real dispatcher): `host_semantics.emitFor`'s
+ * `severity === "warn"` branch returns `{exit: 0, stdout:
+ * claudeAdditionalContext(event, reason)}` UNCONDITIONALLY — it does not
+ * consult `CLAUDE_BLOCK_CAPABLE_EVENTS` at all (that check only gates the
+ * `"block"` severity branch). On the verified `claude` platform the real
+ * process exit handed back to the host is always 0 for a warn verdict; the
+ * internal `EXIT_WARN` is dispatcher-internal bookkeeping, never the byte
+ * that reaches Claude Code.
+ *
+ * ROBUSTNESS: malformed payload → exit 0 silently; every fs/git error is
+ * swallowed. This concern never blocks a tool call on any path.
+ */
+import { spawnSync } from 'node:child_process';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+const EXIT_ALLOW = 0;
+// Severity is taken from the EXIT CODE, not from the `decision` field in the
+// stdout payload — see the file header for why this never blocks on `claude`.
+const EXIT_WARN = 2;
+
+/** Committed threshold (roadmap 5.1): minimum current line count of the
+ *  replaced file before this concern has anything to say. */
+export const MIN_FILE_LINES = 50;
+
+/** Committed threshold (roadmap 5.1): maximum `(added+deleted)/fileLines`
+ *  ratio for the Write to count as a full-rewrite-with-small-diff. */
+export const MAX_DIFF_RATIO = 0.2;
+
+/**
+ * Committed exemption list (roadmap 5.2/6.2 — deliberately duplicated in
+ * `reread_guard_hook.ts`; the two concerns share the list by convention, and
+ * a shared module would couple two independently-rollback-able hooks).
+ */
+export const EXEMPT_PATH_PATTERNS: readonly RegExp[] = [
+    /(^|\/)dist\//i, // dist/**
+    /\/generated\//i, // any path containing /generated/
+    /\.lock$/i, // *.lock
+    /\.min\.[^/]+$/i, // *.min.*
+    /(^|\/)agents\/runtime\//i, // agents/runtime/**
+];
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function str(v: JsonValue | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+
+/** True when `filePath` (absolute or repo-relative) matches the exemption list. */
+export function isExemptPath(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/');
+    return EXEMPT_PATH_PATTERNS.some((re) => re.test(normalized));
+}
+
+/** One `git diff --numstat` row reduced to its added+deleted line count. */
+export function parseNumstatLines(raw: string): number {
+    let total = 0;
+    for (const line of raw.split('\n')) {
+        const m = /^(\d+|-)\t(\d+|-)\t.+$/.exec(line);
+        if (!m) continue;
+        const added = m[1] === '-' ? 0 : Number(m[1]);
+        const deleted = m[2] === '-' ? 0 : Number(m[2]);
+        total += added + deleted;
+    }
+    return total;
+}
+
+/**
+ * Effective-diff line count for ONE path: `git diff HEAD --numstat -- <path>`
+ * at `cwd` (working tree + index vs the last commit — git still holds the
+ * pre-image the PostToolUse payload no longer carries). Fails closed to `0`
+ * (silent) — no repo, no HEAD, untracked path, or `git` missing all read as
+ * "nothing observable to nudge about".
+ */
+export function effectiveDiffLines(cwd: string, relPath: string): number {
+    try {
+        const r = spawnSync('git', ['diff', 'HEAD', '--numstat', '--', relPath], {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        if (r.status !== 0) return 0;
+        return parseNumstatLines(r.stdout ?? '');
+    } catch {
+        return 0;
+    }
+}
+
+/** Current line count of the file on disk. Fails closed to `0` (silent). */
+export function fileLineCount(absPath: string): number {
+    try {
+        const text = fs.readFileSync(absPath, 'utf8');
+        if (text.length === 0) return 0;
+        // Trailing newline does not open a new line.
+        return text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+    } catch {
+        return 0;
+    }
+}
+
+/** The exactly-one advisory line this concern injects when it fires. */
+export function buildAdvisoryLine(fileLines: number, diffLines: number): string {
+    const pct = Math.round((diffLines / fileLines) * 100);
+    return (
+        `this Write replaced ${fileLines} lines for an effective diff of ~${pct}% ` +
+        `(${diffLines} changed lines) — a targeted Edit pays for the diff, not the file.`
+    );
+}
+
+/**
+ * Stable, filesystem-safe once-per-session key — mirrors
+ * `end_review_nudge_hook.deriveSessionKey`: the envelope's `session_id`
+ * (falling back to the payload's) is HASHED, never stored raw.
+ */
+export function deriveSessionKey(envelope: JsonObject, payload: JsonObject): string {
+    const raw =
+        str(envelope['session_id'] as JsonValue | undefined) ||
+        str((payload['session_id'] ?? payload['sessionId']) as JsonValue | undefined);
+    const material = raw || 'unknown-session';
+    return crypto.createHash('sha256').update(material).digest('hex');
+}
+
+function sessionStateFile(workspaceRoot: string, sessionKey: string): string {
+    return path.join(workspaceRoot, 'agents', 'runtime', 'state', 'edit-shape', `${sessionKey}.json`);
+}
+
+/** True when THIS session already fired. Fails closed to `false` (may repeat,
+ *  never silences over an unreadable state dir). */
+export function hasFiredThisSession(workspaceRoot: string, sessionKey: string): boolean {
+    try {
+        return fs.existsSync(sessionStateFile(workspaceRoot, sessionKey));
+    } catch {
+        return false;
+    }
+}
+
+function markFiredThisSession(workspaceRoot: string, sessionKey: string): void {
+    try {
+        atomic_write_json(sessionStateFile(workspaceRoot, sessionKey), {
+            fired_at: new Date().toISOString(),
+        });
+    } catch {
+        // a state-write failure must never affect the tool call
+    }
+}
+
+function extractToolName(payload: JsonObject): string {
+    return str((payload['tool_name'] ?? payload['toolName'] ?? payload['tool']) as JsonValue | undefined);
+}
+
+function extractFilePath(payload: JsonObject): string {
+    const ti = payload['tool_input'] ?? payload['toolInput'] ?? payload['input'];
+    if (!isObject(ti)) return '';
+    return str((ti['file_path'] ?? ti['path'] ?? ti['filePath']) as JsonValue | undefined);
+}
+
+export function main(): number {
+    try {
+        const [envelope, payload] = unwrap(readHookStdin(), 'claude');
+
+        const event = str(envelope['event'] as JsonValue | undefined);
+        if (event !== '' && event !== 'post_tool_use') return EXIT_ALLOW;
+
+        const toolName = extractToolName(payload);
+        if (toolName !== 'Write') return EXIT_ALLOW; // manifest `tools: [Write]` twin — belt and braces
+
+        const filePath = extractFilePath(payload);
+        if (!filePath) return EXIT_ALLOW;
+
+        const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined).trim() || process.cwd();
+        const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(workspaceRoot, filePath);
+        const relPath = path.relative(workspaceRoot, absPath);
+        if (isExemptPath(relPath) || isExemptPath(absPath)) return EXIT_ALLOW;
+
+        const fileLines = fileLineCount(absPath);
+        if (fileLines < MIN_FILE_LINES) return EXIT_ALLOW;
+
+        const diffLines = effectiveDiffLines(workspaceRoot, relPath.startsWith('..') ? absPath : relPath);
+        // 0 = no observable modification vs HEAD (untracked file, clean path,
+        // no repo) — silent per the header's honest-mechanism note.
+        if (diffLines === 0) return EXIT_ALLOW;
+        if (diffLines / fileLines > MAX_DIFF_RATIO) return EXIT_ALLOW;
+
+        // Cheap checks first, then the once-per-session gate (same ordering
+        // discipline as end_review_nudge's F12).
+        const sessionKey = deriveSessionKey(envelope, payload);
+        if (hasFiredThisSession(workspaceRoot, sessionKey)) return EXIT_ALLOW;
+        markFiredThisSession(workspaceRoot, sessionKey);
+
+        process.stdout.write(
+            `${JSON.stringify({
+                decision: 'warn',
+                reason: `edit-shape: Write replaced a ${fileLines}-line file for a ${diffLines}-line effective diff`,
+                additional_context: buildAdvisoryLine(fileLines, diffLines),
+            })}\n`,
+        );
+        return EXIT_WARN;
+    } catch {
+        return EXIT_ALLOW; // malformed payload / any error — never touch the tool call
+    }
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+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 {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -131,6 +131,11 @@ export interface DispatchFacts {
     /** Absolute measured tokens the dispatched slice consumed. `null` = not observed (async). */
     totalTokens: number | null;
     totalDurationMs: number | null;
+    /** Serialized LENGTH of the tool result — the chars this dispatch returned
+     *  into the orchestrator context (Phase 6.3 return-channel detector).
+     *  A COUNT derived from the result object; the content itself is never
+     *  read into the record (privacy by construction). `null` = async ack. */
+    returnChannelChars: number | null;
     isAsync: boolean;
     isError: boolean;
 }
@@ -199,7 +204,19 @@ export function extractDispatchFacts(payload: JsonObject): DispatchFacts {
     const isAsync = result !== null && (result['isAsync'] === true || result['status'] === 'async_launched');
     const isError = payload['is_error'] === true || payload['isError'] === true || (result !== null && result['is_error'] === true);
 
-    return { subagentType, resolvedModel, totalTokens, totalDurationMs, isAsync, isError };
+    // Phase 6.3 return-channel size: measured as the serialized LENGTH of the
+    // result object — a count; the content never enters the record. Async
+    // acks carry no result payload worth measuring (null, never fabricated).
+    let returnChannelChars: number | null = null;
+    if (result !== null && !isAsync) {
+        try {
+            returnChannelChars = JSON.stringify(result).length;
+        } catch {
+            returnChannelChars = null;
+        }
+    }
+
+    return { subagentType, resolvedModel, totalTokens, totalDurationMs, returnChannelChars, isAsync, isError };
 }
 
 /**
@@ -231,6 +248,7 @@ export function buildRecordInput(facts: DispatchFacts, ts: string, id: string):
         }
         if (facts.totalTokens !== null) input.dispatch_tokens = facts.totalTokens;
         if (facts.totalDurationMs !== null) input.wall_clock_ms = facts.totalDurationMs;
+        if (facts.returnChannelChars !== null) input.return_channel_chars = facts.returnChannelChars;
     }
     // Async launch ack: every metric field stays absent (undefined → the
     // schema's own null/0 default) rather than fabricated from nothing.