@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/hooks/mcp_usage_observation_hook.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * Foreign MCP tool names, observed on `post_tool_use`
+ * (road-to-neighbours-that-pull-their-weight step 3.3, decision D12).
+ *
+ * DEFAULT-ON LOCAL OBSERVATION, AND IT BYPASSES THE TELEMETRY OPT-IN. Stated
+ * here first because it is the one property a reader must not have to infer.
+ * This concern writes on every install, whether or not the org telemetry switch
+ * was ever enabled, because the file it writes feeds `doctor neighbours` — a
+ * report the consumer runs on their own tree — and gating it on an org switch
+ * would publish `0` on every install that never enabled one. Nothing here is
+ * telemetry: no transport reads the file, it is never spooled, and it lives
+ * under gitignored `agents/runtime/` (decision D9).
+ *
+ * WHAT IS RECORDED: the tool NAME, `mcp__<server>__<tool>`, and the UTC day it
+ * was last seen. Nothing else — no arguments, no response, no session id, no
+ * host. The dispatcher serves this concern a REDUCED payload: its manifest
+ * entry declares no `needs_payload_bodies`, so `tool_input` and `tool_response`
+ * arrive as size-only stubs and cannot be recorded even by mistake.
+ *
+ * RETENTION. A map keyed by tool name, rewritten in place at most once per day
+ * per name — bounded by the neighbour's tool surface, so it needs no TTL job.
+ * The reader applies a 30-day window; older entries stop counting. Deleting
+ * `agents/runtime/neighbour-tool-use.json` erases all of it.
+ *
+ * Why a concern of its own rather than a branch of `telemetry-usage`: that
+ * concern's dispatcher filter is `tools: [Skill]` and matches exactly, so a
+ * branch there was never called for an MCP tool; and a concern named for
+ * opt-in telemetry should not also carry default-on local collection. Both
+ * were the AI council's findings (2026-10-02); the owner chose this shape.
+ *
+ * No `tools:` filter on the manifest entry, deliberately: MCP tool names are
+ * not enumerable and matching is exact. The prefix test below is the filter.
+ *
+ * Exit code is ALWAYS 0 and nothing is printed — it observes, never gates.
+ */
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import { FOREIGN_TOOL_USE_REL, MCP_TOOL_PREFIX, resolveStoreRoot, usageDay } from '../_lib/neighbour_tool_use.js';
+import { update_json_under_lock } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW } from './exit_codes.js';
+
+type JsonObject = { [k: string]: unknown };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The MCP tool name off the envelope, or null for anything else. */
+export function mcpToolName(envelope: unknown): string | null {
+    if (!isObject(envelope)) return null;
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const v = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    return typeof v === 'string' && v.startsWith(MCP_TOOL_PREFIX) && v.length > MCP_TOOL_PREFIX.length ? v : null;
+}
+
+function record(envelope: unknown, consumer_root: string): number {
+    try {
+        const tool = mcpToolName(envelope);
+        if (tool === null) return EXIT_ALLOW;
+        const day = usageDay(new Date());
+        update_json_under_lock<Record<string, string>>(
+            path.join(resolveStoreRoot(consumer_root), FOREIGN_TOOL_USE_REL),
+            (seen) => (seen[tool] === day ? null : ({ ...seen, [tool]: day } as Record<string, string>)),
+            { blocking: false },
+        );
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+export function run(stdin_text: string, options: { consumer_root: string }): number {
+    let envelope: unknown;
+    try {
+        const raw = stdin_text.trim();
+        if (!raw) return EXIT_ALLOW;
+        envelope = JSON.parse(raw);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return record(envelope, options.consumer_root);
+}
+
+function _root(envelope: unknown): string {
+    if (isObject(envelope)) {
+        const v = envelope['cwd'] ?? envelope['workspace_root'] ?? envelope['project_root'];
+        if (typeof v === 'string' && v) return v;
+    }
+    return process.cwd();
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: unknown = {};
+    try {
+        envelope = raw.trim() ? JSON.parse(raw) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return record(envelope, _root(envelope));
+}
+
+// Bundle-safety: guarded at the call site so esbuild drops the whole entry
+// check inside the shared hook bundle (see telemetry_usage_hook.ts, D11).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (typeof __AGENT_CONFIG_BUNDLE__ === 'undefined' || !__AGENT_CONFIG_BUNDLE__) {
+    if (_isCliEntry()) process.exit(main());
+}

package/src/scripts/hooks/one_question_per_ask_hook.ts

@@ -14,33 +14,38 @@
  * names the count so the caller can split the ask instead of guessing what
  * happened.
  *
- * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries no observed
- * per-host tool, so this guard matches on a name SHAPE and is filtered by the
- * manifest's per-concern `tools:` key to the same candidate names. No host's
- * delivered surface has been OBSERVED in this tree carrying a question-picker
- * tool, which is why `STRUCTURED_ASK_SHAPES` is empty and no per-host shape row
- * exists — the same sentence `_lib/structured_ask.ts` already uses about itself.
+ * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries ONE observed
+ * per-host tool — `claude`'s `AskUserQuestion`, 48 calls across versions
+ * 2.1.252 to 2.1.284 between 2026-09-01 and 2026-10-02.
  *
- * That is NARROWER than the claim this header used to make. The earlier
- * sentence asserted that on every host measured today the concern therefore
- * matches nothing at all, and the two are different claims with only the first
- * supported. The old wording is described here rather than quoted, because
- * 1.1's drift check is a grep and a grep cannot tell a refuted quotation from
- * a live assertion. The measurement base is ONE row:
- * `_lib/host_capability.ts`'s registry records `structured_ask: false` for
- * `claude` alone, observed-absent on Claude Code 2.1.263 on 2026-09-07, and the
- * other eight hosts in `docs/enforcement-by-host.md` have no row at all — never
- * looked, not measured. "Every host measured" read against that table therefore
- * describes one host, and a present-tense claim about what the concern matches
- * turns one dated single-version reading into a standing property, which the registry's own
- * comment refuses in the same breath: the observation "is not a claim that the
- * vendor ships no such tool anywhere, and a later session observing one writes
- * the `true` row over it".
+ * THIS GUARD DOES NOT USE THAT ROW, and the distinction matters enough to say
+ * rather than leave to a reader. `verdict()` calls `isStructuredAskTool(tool)`
+ * with no host id, so the shape branch is unreachable from here and the name
+ * SHAPE pattern decides on every host, `claude` included — filtered by the
+ * manifest's per-concern `tools:` key to the same candidate names. Threading a
+ * host id through would NARROW what this guard matches on the one host where a
+ * picker is known to exist (`ask_user_question` would stop matching), which is
+ * a behaviour change and not a header repair, so it is deliberately not made
+ * here.
  *
- * So the honest statement is about what has been looked at, not about what
- * fires. The concern exists so the first host whose delivered surface carries a
- * picker meets the rule already in force, not because a violation has been
- * observed.
+ * This header carried the opposite claim until 2026-10-05 — that no host's
+ * delivered surface had been observed carrying a picker — and it was wrong in
+ * a specific, instructive way rather than merely stale. Its measurement base
+ * was one `false` row taken from a SUBAGENT leg, whose surface carries no
+ * picker because a subagent has no user to ask. The step from "this leg has
+ * none" to "no host has been observed with one" is the substitution the
+ * observation protocol exists to refuse, and the registry comment now records
+ * which leg each reading came from for that reason. The old wording is
+ * described rather than quoted, because 1.1's drift check is a grep and a grep
+ * cannot tell a refuted quotation from a live assertion.
+ *
+ * The other eight hosts in `docs/enforcement-by-host.md` still have no row at
+ * all — never looked, not measured — so nothing here is a claim about them.
+ *
+ * WHAT THE OBSERVATION DOES NOT CHANGE: the deny threshold. One question per
+ * call is `ask-when-uncertain`'s Iron Law, not a host limit, and all 47
+ * parsed calls already carried exactly one. The guard has had nothing to deny
+ * and that is the expected reading, not evidence it is inert.
  *
  * ENFORCEMENT REACH, also honestly. `fail_closed: false` and the exit-1 deny
  * are only a deny where the host both binds `pre_tool_use` AND honours the
@@ -162,6 +167,17 @@ export function selfTest(): number {
             { tool_name: 'ask_user_question', tool_input: { question: 'which one?' } },
             false,
         ],
+        [
+            // PINS THE HEADER'S INVARIANT. `ask_user_question` is not the name
+            // claude's observed shape row carries, so this case denies only
+            // while `verdict()` passes no host id and the name-SHAPE pattern
+            // decides. Thread a host id through and the shape branch rejects
+            // the name, the call stops being an ask, and this flips to allow —
+            // which is the silent narrowing the header says is not being made.
+            'a snake_case picker with two questions is still denied — this guard is host-blind',
+            { tool_name: 'ask_user_question', tool_input: { questions: [{}, {}] } },
+            true,
+        ],
         [
             'an empty ask passes — malformed, but not this guard\'s failure',
             { tool_name: 'AskUserQuestion', tool_input: { questions: [] } },

package/src/scripts/hooks/payload_stub.ts

@@ -108,7 +108,16 @@ export const BODY_CLASSES: readonly BodyClass[] = ["input", "result"] as const;
  */
 export const BODY_KEYS: Readonly<Record<BodyClass, readonly string[]>> = {
   input: ["tool_input", "toolInput"],
-  result: ["tool_response", "toolResponse", "tool_result", "toolUseResult"],
+  // `error` is a result body and is listed as one. On claude's
+  // `PostToolUseFailure` the failing call carries NO `tool_response` at all —
+  // the command's own stdout and stderr arrive here instead, under the first
+  // line stating the exit code. Until that event was bound this key reached no
+  // concern, so its absence from this list cost nothing; binding the event
+  // without adding it would have delivered raw command output in full to every
+  // concern on the slot, including the fourteen that never declared `result`.
+  // That is exactly the content this module exists to withhold, so the key
+  // belongs to the class whose semantics it has — not to an exception.
+  result: ["tool_response", "toolResponse", "tool_result", "toolUseResult", "error"],
 };
 
 export interface PayloadStub extends JsonObject {

package/src/scripts/hooks/push_settle_hook.ts

@@ -195,9 +195,10 @@ export function buildReminder(branch: string, pr: number | null): { reason: stri
     `  2. Red? Read only the failing part:\n` +
     `     gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'\n` +
     `     then fix it and push again (fix-what-you-see: the author is irrelevant).\n` +
-    `  3. Still red after 3 attempts on the same target, or blocked on something ` +
-    `only the user can decide — stop and say so, with the three attempts named ` +
-    `(autonomous-execution N=3).\n\n` +
+    `  3. 3 attempts on the same target triggers autonomous-execution's ` +
+    `execution.fix_loop_max strategy shift — change approach, never stop. ` +
+    `Blocked on something only the user can decide is the one branch that halts: ` +
+    `say so, with what was tried named.\n\n` +
     `Handing the user a red PR with its cause named and unfixed is not a delivery ` +
     `either. If you are deliberately leaving this WIP, say that in the reply — ` +
     `silence is what this hook exists to stop.`;