@event4u/agent-config 16.4.0 → 17.0.0

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

@@ -197,7 +197,8 @@ import {
     graphUntestedVerdict,
 } from '../_lib/graph_feeder_record.js';
 import { type GraphState, graphState } from '../code_graph/detect.js';
-import { isVerificationCommand } from '../_lib/verification_command.js';
+import { isVerificationAttempt, isVerificationCommand } from '../_lib/verification_command.js';
+import { openSvgObligation } from './svg_obligation.js';
 // Round 8 — the record path detector C prefers over its own regex. The regex
 // reads a command's TEXT and `echo test` matches it; these read what the run
 // exited with and what it printed.
@@ -761,7 +762,7 @@ export function detectUnverifiedEdit(
 
     for (let i = lastEdit + 1; i < toolCalls.length; i += 1) {
         const c = toolCalls[i]!;
-        if (c.name === 'Bash' && c.command !== undefined && isVerificationCommand(c.command)) {
+        if (c.name === 'Bash' && c.command !== undefined && isVerificationAttempt(c.command)) {
             return null;
         }
     }
@@ -772,7 +773,7 @@ export function detectUnverifiedEdit(
         evidence: edited,
         reason:
             'this turn changed a file and then ran no verification command — ' +
-            'no test, type-check, lint or build call follows the last edit ' +
+            'no test, type-check, lint, build or asset render follows the last edit ' +
             '(verify-before-complete: a claim without a fresh run is unverified)',
         mode: 'transcript',
     };
@@ -1281,6 +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, 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("");

package/src/scripts/hooks_status.ts

@@ -30,6 +30,8 @@ import {
   _load_yaml,
 } from "./hooks/dispatch_hook.js";
 import { loadHostLowering } from "./hooks/host_lowering.js";
+import { type ClaudeHookScope, claudeHookScope } from "./_lib/claude_hook_scope.js";
+import { event4u_root } from "./_lib/user_global_paths.js";
 import { type SlotReading, readSlots } from "./report_enforcement_drift.js";
 
 // src/scripts/hooks_status.ts → parents[1] is the repo root (.../parents[2]
@@ -106,6 +108,13 @@ export interface PlatformRow {
    */
   blocking_enforcement: Record<string, string>;
   hint: string | null;
+  /**
+   * Claude only. Where the managed hooks are registered (global and/or
+   * project), which runtime they would reach, and the resulting state. Present
+   * because Claude Code MERGES `~/.claude/settings.json` with the project file,
+   * so one file cannot answer "are the hooks installed" for that host.
+   */
+  claude_scope?: ClaudeHookScope;
 }
 
 export interface StatusMatrix {
@@ -206,8 +215,27 @@ function _blocking_enforcement(
   return out;
 }
 
+/** Where to look for the user-scope half of Claude's merged settings. Injected by tests. */
+export interface UserScope {
+  home: string;
+  runtimeRoot: string;
+  pathEnv: string;
+}
+
+function _defaultUserScope(): UserScope {
+  return {
+    home: process.env["HOME"] ?? "",
+    runtimeRoot: path.join(event4u_root(), "runtime"),
+    pathEnv: process.env["PATH"] ?? "",
+  };
+}
+
 /** Build the runtime matrix as a plain object — JSON-serialisable. */
-export function collect(project_root: string, manifest: JsonObject): StatusMatrix {
+export function collect(
+  project_root: string,
+  manifest: JsonObject,
+  userScope: UserScope = _defaultUserScope(),
+): StatusMatrix {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
   const severities = _severities(manifest);
@@ -226,9 +254,20 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
         }
       }
     }
+    // Claude merges the user-scope settings file with the project one, so its
+    // status comes from the managed commands in BOTH, never from whether the
+    // project file merely exists.
+    const claude_scope =
+      platform === "claude" && !fallback_only
+        ? claudeHookScope({ projectRoot: project_root, ...userScope })
+        : undefined;
     const status = fallback_only
       ? "degraded"
-      : _bridge_status(project_root, rel);
+      : claude_scope !== undefined
+        ? claude_scope.registered_in.length > 0
+          ? "installed"
+          : "missing"
+        : _bridge_status(project_root, rel);
     rows.push({
       platform,
       status,
@@ -240,6 +279,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
       hint: ["missing", "empty", "degraded", "n/a"].includes(status)
         ? hint
         : null,
+      ...(claude_scope !== undefined ? { claude_scope } : {}),
     });
   }
   return { schema_version: 1, platforms: rows };
@@ -277,10 +317,25 @@ export function _render_table(matrix: StatusMatrix): string {
   for (const row of matrix.platforms) {
     const marker = _STATUS_MARKER[row.status] ?? "?  ";
     let head = `${marker}${row.platform.padEnd(9)} ${row.status}`;
-    if (row.bridge_path) {
+    if (row.claude_scope !== undefined) {
+      const where = row.claude_scope.registered_in.length > 0 ? row.claude_scope.registered_in.join(" + ") : "neither scope";
+      head += `  (managed hooks in: ${where} — ~/.claude/settings.json and <project>/.claude/settings.json are merged)`;
+    } else if (row.bridge_path) {
       head += `  (${row.bridge_path})`;
     }
     lines.push(head);
+    if (row.claude_scope !== undefined) {
+      const s = row.claude_scope;
+      lines.push(`    state                  → ${s.state}`);
+      lines.push(
+        `    runtime                → ${s.runtime}` + (s.runtime_version !== null ? ` v${s.runtime_version}` : ""),
+      );
+      lines.push(
+        `    managed / foreign      → global ${s.managed_commands.global} / ${s.foreign_commands.global}, ` +
+          `project ${s.managed_commands.project} / ${s.foreign_commands.project}  (foreign hooks are never counted as ours)`,
+      );
+      if (s.version_skew !== null) lines.push(`    ⚠️  ${s.version_skew}`);
+    }
     lines.push(
       `    ask                    → ${row.ask}` +
         (row.ask === "native"

package/src/scripts/inbox_source_census.ts

@@ -113,6 +113,13 @@ export interface TopicCensus {
     decisionIds: string[];
     fileCount: number;
     anchorTotal: number;
+    /**
+     * Paths under this topic the census did NOT read, relative to the topic
+     * directory. A file the walk skipped is not a file that is not there, and
+     * the closing coverage line cannot be read as complete while this is
+     * non-empty.
+     */
+    uncounted: string[];
 }
 
 /**
@@ -195,13 +202,46 @@ function censusFile(abs: string, rel: string): FileCensus {
     };
 }
 
-/** Group one topic folder's files into source sets and count its anchors. */
-export function censusTopic(dir: string, topic: string): TopicCensus {
-    const names = fs
-        .readdirSync(dir, { withFileTypes: true })
-        .filter((d) => d.isFile() && TEXT_EXT.has(path.extname(d.name).toLowerCase()))
-        .map((d) => d.name)
-        .sort();
+/**
+ * Every path under `dir`, recursively, split into the text files the census
+ * reads and everything else. Both are relative to `dir` and sorted.
+ *
+ * The recursion is the repair. The previous reader took only the files
+ * DIRECTLY in a topic directory, so a nested folder of later-loop plans was
+ * invisible while the closing line still claimed every anchor left with a
+ * ledger row. Measured on the round that found it: twelve files reported
+ * against fourteen present, and zero revision sets against three.
+ */
+function collect(dir: string, recursive: boolean): { text: string[]; other: string[] } {
+    const text: string[] = [];
+    const other: string[] = [];
+    const walk = (abs: string, rel: string): void => {
+        for (const d of fs.readdirSync(abs, { withFileTypes: true })) {
+            const childRel = rel === '' ? d.name : `${rel}/${d.name}`;
+            if (d.isDirectory()) {
+                if (recursive) walk(path.join(abs, d.name), childRel);
+                continue;
+            }
+            if (!d.isFile()) continue;
+            if (TEXT_EXT.has(path.extname(d.name).toLowerCase())) text.push(childRel);
+            else other.push(childRel);
+        }
+    };
+    walk(dir, '');
+    text.sort();
+    other.sort();
+    return { text, other };
+}
+
+/**
+ * Group one topic folder's files into source sets and count its anchors.
+ *
+ * `recursive` is true for a topic, false for the round root — `censusRoot`
+ * treats each immediate subdirectory as its own topic, so a recursive root
+ * pass would count those files twice.
+ */
+export function censusTopic(dir: string, topic: string, recursive = true): TopicCensus {
+    const { text: names, other: uncounted } = collect(dir, recursive);
 
     const byStem = new Map<string, FileCensus[]>();
     const ids = new Set<string>();
@@ -209,7 +249,12 @@ export function censusTopic(dir: string, topic: string): TopicCensus {
         const abs = path.join(dir, name);
         const fc = censusFile(abs, name);
         for (const id of decisionIds(fs.readFileSync(abs, 'utf-8'))) ids.add(id);
-        const stem = stemOf(name);
+        // The stem comes from the BASENAME, so `plan.md` and `v2/plan.md` are
+        // one revision set across directory levels. That is the grouping this
+        // repair is for; it also means two unrelated files that happen to
+        // share a stem at different depths read as one set, which is why each
+        // member is printed with its path relative to the topic.
+        const stem = stemOf(path.basename(name));
         const bucket = byStem.get(stem);
         if (bucket) bucket.push(fc);
         else byStem.set(stem, [fc]);
@@ -228,6 +273,7 @@ export function censusTopic(dir: string, topic: string): TopicCensus {
         sets,
         decisionIds: [...ids].sort(),
         fileCount: names.length,
+        uncounted,
         anchorTotal: sets.reduce(
             (n, s) => n + s.members.reduce((m, f) => m + f.total, 0),
             0,
@@ -238,12 +284,12 @@ export function censusTopic(dir: string, topic: string): TopicCensus {
 /** Walk a round root: each immediate subdirectory is a topic, plus the root itself. */
 export function censusRoot(root: string): TopicCensus[] {
     const out: TopicCensus[] = [];
-    const rootLevel = censusTopic(root, '.');
-    if (rootLevel.fileCount > 0) out.push(rootLevel);
+    const rootLevel = censusTopic(root, '.', false);
+    if (rootLevel.fileCount > 0 || rootLevel.uncounted.length > 0) out.push(rootLevel);
     for (const d of fs.readdirSync(root, { withFileTypes: true })) {
         if (!d.isDirectory()) continue;
         const t = censusTopic(path.join(root, d.name), d.name);
-        if (t.fileCount > 0) out.push(t);
+        if (t.fileCount > 0 || t.uncounted.length > 0) out.push(t);
     }
     return out;
 }
@@ -252,6 +298,7 @@ function render(topics: TopicCensus[], write: (s: string) => unknown): void {
     let files = 0;
     let anchors = 0;
     let revisionSets = 0;
+    let uncounted = 0;
     for (const t of topics) {
         write(`\n## ${t.topic}\n`);
         for (const s of t.sets) {
@@ -268,13 +315,27 @@ function render(topics: TopicCensus[], write: (s: string) => unknown): void {
             if (s.isRevisionSet) revisionSets += 1;
         }
         if (t.decisionIds.length > 0) write(`  decision ids: ${t.decisionIds.join(' ')}\n`);
+        if (t.uncounted.length > 0) {
+            write(`  not counted (${String(t.uncounted.length)}): ${t.uncounted.join(', ')}\n`);
+        }
         files += t.fileCount;
         anchors += t.anchorTotal;
+        uncounted += t.uncounted.length;
     }
     write(
         `\ntopics ${String(topics.length)} · files ${String(files)} · ` +
-            `revision sets ${String(revisionSets)} · anchors ${String(anchors)}\n` +
-            'Every anchor leaves the run carrying a ledger row or named in one `no-demand` line.\n' +
+            `revision sets ${String(revisionSets)} · anchors ${String(anchors)} · ` +
+            `not counted ${String(uncounted)}\n`,
+    );
+    if (uncounted > 0) {
+        write(
+            `${String(uncounted)} file(s) are named above and were NOT read — the census reads ` +
+                `${[...TEXT_EXT].sort().join(' ')} only. The anchor total below is over what was ` +
+                'read, so it is a floor and not a measure of the folder.\n',
+        );
+    }
+    write(
+        'Every anchor leaves the run carrying a ledger row or named in one `no-demand` line.\n' +
             'Every revision set owes a consecutive-member diff (/analyze:inbox Phase 2b).\n',
     );
 }

package/src/scripts/install

@@ -208,6 +208,15 @@ if $NO_UI; then
     export AGENT_CONFIG_NO_UI=1
 fi
 
+# `--scope global` is documented above as "same as --global", and it was not:
+# it set SCOPE and nothing else, so the PROJECT payload sync still ran. Under
+# npx that sync auto-detects its target three levels above the package, which
+# is the npx cache, so a global dry-run reported writing `.augment/` there.
+if [[ "${SCOPE:-}" == "global" ]]; then
+    GLOBAL=true
+    SKIP_SYNC=true
+fi
+
 # road-to-global-only-install § Phase 3.3 — consumer-floor gate.
 #
 # Consumer installs are global-only (ADR-020). Explicit --scope=project
@@ -419,12 +428,19 @@ run_bridges() {
         runner=($tsx_bin "$INSTALL_TS")
     fi
 
+    local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
     if $DRY_RUN; then
-        $QUIET || echo "  ⏭️  Skipping bridges (--dry-run)"
-        return 0
+        # The install stage owns the global plan, so a dry run asks IT rather
+        # than skipping it: install.ts returns from its plan summary before any
+        # write or subprocess. Skipping it here left a global dry run printing
+        # nothing but the one stage that does not apply to a global install.
+        $GLOBAL && args+=(--global)
+        [[ -n "$SCOPE" ]] && args+=(--scope="$SCOPE")
+        args+=(--tools="$TOOLS" --no-ui --dry-run)
+        "${runner[@]}" "${args[@]}"
+        return $?
     fi
 
-    local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
     [[ -n "$USER_TYPE" ]] && args+=(--user-type="$USER_TYPE")
     $FORCE && args+=(--force)
@@ -473,6 +489,12 @@ if ! $SKIP_SYNC; then
         exit 1
     fi
     run_sync || RC=$?
+elif $DRY_RUN && ! $QUIET; then
+    if $GLOBAL; then
+        echo "  ⏭️  Project payload sync: skipped — a global install writes user-scope host paths only."
+    else
+        echo "  ⏭️  Project payload sync: skipped (--skip-sync)."
+    fi
 fi
 
 if [[ $RC -ne 0 ]]; then