@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -9,7 +9,7 @@
  * is deliberately not another reminder. It is a check at the point of
  * delivery that can say no.
  *
- * FOUR detectors ride on one guard, because building the unsafe part twice
+ * FIVE detectors ride on one guard, because building the unsafe part twice
  * is how a second detector becomes a second outage:
  *
  *   A — promissory closing  (FC-5, 20 measured occurrences)
@@ -22,11 +22,18 @@
  *                            only, so tool activity is invisible to A and B.)
  *   D — completion claim    (a claim of done carrying no fresh evidence; landed
  *                            under conformance round 7 § Phase 1.)
+ *   E — pending decision    (an earlier reply in the SAME user turn put numbered
+ *                            options to the user and the closing reply carries
+ *                            none — the turn asked and then dropped the ask.
+ *                            Read off `assistantTurnTexts`, which is why that
+ *                            field exists: every other detector reads
+ *                            `lastAssistant` alone and therefore cannot see a
+ *                            question that was asked one reply earlier.)
  *
- * TWO of the four are CONDITIONAL, and saying "unconditional" here would be the
+ * TWO of the five are CONDITIONAL, and saying "unconditional" here would be the
  * same stale-header defect this block corrects below. A and D are the
  * completion-adjacent pair an open subagent dispatch excuses, so `main()` runs
- * them only when `dispatchOpen` is false; B and C run on every turn-end. That
+ * them only when `dispatchOpen` is false; B, C and E run on every turn-end. That
  * narrowing is deliberate (Phase 3 Step 2, narrowed again by R2 round 2) and is
  * the third allow path, alongside the two re-entrancy layers — see the
  * per-detector list in `main()`.
@@ -35,7 +42,7 @@
  * below has carried four since round 7. `DETECTOR_IDS` in
  * `_lib/turn_end_refusals.ts` is read off that union rather than off this
  * comment for exactly that reason, and the count is corrected here rather than
- * left as a stale header the next reader has to disbelieve.
+ * left as a stale header the next reader has to disbelieve. E made it five.
  *
  * ## Removal condition
  *
@@ -157,6 +164,23 @@ import {
 // agreement invisible when the producer's layout moved. A builder makes the move
 // a type error.
 import { statePathFor as ciStatePathFor } from '../before_complete_hook.js';
+// The spec-backed options-block reading, imported rather than re-derived:
+// `user-interaction` Iron Law 1's definition of an ask — a block PLUS its
+// recommendation line — lives in exactly one place and detector E reads it from
+// there.
+//
+// WHAT KEEPS IT FROM RUNNING ON IMPORT, stated precisely because the obvious
+// answer is wrong: that module is `_isCliEntry`-guarded, but WITHOUT the
+// `__AGENT_CONFIG_BUNDLE__` early-out this file carries. Inside
+// `dist/hooks/dispatch.js` every module shares one `import.meta.url`, so the
+// guard alone would not settle it; what does is the `.__direct__` argv rewrite
+// in the `build:hooks` banner. Named here so a future change to that banner
+// does not silently start running a lint's `main()` on every hook dispatch.
+// Detector E, extracted to `_lib` where its prose costs no ratchet debt.
+// Re-exported so every existing importer of this module is unchanged.
+import { detectDroppedDecision } from '../_lib/dropped_decision.js';
+
+export { detectDroppedDecision };
 import { isSafeTranscriptPath } from './end_review_nudge_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -190,7 +214,13 @@ const EXIT_ALLOW = 0;
 export const TRANSCRIPT_READ_MAX_BYTES = 8 * 1024 * 1024; // 8 MB
 
 /** Detector identity, used in the state marker and the refusal text. */
-export type DetectorId = 'promissory' | 'language' | 'verification' | 'completion';
+export type DetectorId =
+    | 'promissory'
+    | 'language'
+    | 'verification'
+    | 'completion'
+    | 'pending-decision'
+    | 'untested';
 
 export interface Finding {
     detector: DetectorId;
@@ -723,6 +753,110 @@ export function detectUnverifiedEdit(toolCalls: readonly ToolCall[]): Finding |
     };
 }
 
+// ---------------------------------------------------------------------------
+// Detector F — a completion claim over production code no test accompanies
+// ---------------------------------------------------------------------------
+
+/**
+ * WHY THIS EXISTS, and why detector C did not already cover it.
+ *
+ * Detector C asks "did ANY verification command run after the last edit". It is
+ * satisfied by `eslint`. That is deliberate — see `isVerificationCommand`, which
+ * is narrow about what counts as a command and says nothing about what the
+ * command COVERS. So a turn can write four hundred lines of feature code, run
+ * the linter, claim done, and pass every guard in this file.
+ *
+ * Measured consequence, reported by the maintainer 2026-09-11 about a consumer
+ * project: a feature shipped whose detail view crashed on open, whose flyouts
+ * were broken, and for which the maintainer then had to hand-enumerate what
+ * should have been exercised — every view, every CRUD path, drag-and-drop,
+ * mobile, filters. Their words: *"Solche Fehler können nur auftreten, weil Du
+ * nicht TDD gearbeitet ... hast."* Nothing in the suite refused that turn,
+ * because nothing in the suite asks whether the change is TESTED — only whether
+ * something ran.
+ *
+ * THE SIGNAL, and why it is this one. "Is the change covered" is undecidable
+ * from a transcript: coverage lives in the consumer's tooling, which this hook
+ * cannot run. What IS decidable is the cheapest possible proxy, and it happens
+ * to be the exact shape of the reported failure — **production source changed,
+ * no test file touched, done claimed**. A proxy is worth shipping here precisely
+ * because the population it flags is small and the failure it catches is total:
+ * a feature with zero new test lines is not under-tested, it is untested.
+ *
+ * WHY IT IS GATED ON THE CLAIM rather than on the edit. Firing on every edit
+ * would refuse the first turn of every red-green-refactor cycle — the discipline
+ * it exists to encourage — and a guard that fires on the majority of turns is a
+ * guard that gets switched off. The obligation belongs to the CLAIM, which is
+ * also where `verify-before-complete` puts it and where detector D already sits.
+ *
+ * WHAT IT CANNOT DO. It cannot tell a good test from a token one: a turn that
+ * touches any test file clears it. That is a deliberate floor rather than an
+ * oversight — `testing-anti-patterns` owns assertion quality, and a guard that
+ * tried to judge it from a path would be judging something it cannot see. The
+ * honest claim is narrow: this refuses the case where the agent wrote NO test at
+ * all and said it was finished.
+ */
+
+/** Extensions that carry behaviour a test can be owed for. */
+const _SOURCE_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|vue|svelte|php|py|rb|go|rs|java|kt|swift|cs|scala|ex|exs)$/i;
+
+/**
+ * Paths that ARE tests, across the conventions this suite's stacks use.
+ *
+ * Deliberately generous: a false NEGATIVE here (calling a test file a test) only
+ * silences the detector, while a false positive would refuse a turn that did
+ * write its tests — the direction that gets a guard disabled.
+ */
+const _TEST_PATH_RE =
+    /(?:^|\/)(?:tests?|specs?|__tests__|__specs__|e2e|cypress|playwright|features)\//i;
+const _TEST_FILE_RE =
+    /(?:\.(?:test|spec)\.[a-z]+$)|(?:_test\.[a-z]+$)|(?:(?:^|\/)test_[^/]+$)|(?:Test\.php$)|(?:Spec\.php$)|(?:\.feature$)/i;
+
+function _isTestPath(p: string): boolean {
+    return _TEST_PATH_RE.test(p) || _TEST_FILE_RE.test(p);
+}
+
+function _isProductionSource(p: string): boolean {
+    return _SOURCE_RE.test(p) && !_isTestPath(p);
+}
+
+/**
+ * Fire when the turn changed production code, touched no test, and said done.
+ *
+ * All three conditions are load-bearing. Drop the first and it fires on a docs
+ * turn; drop the second and it fires on a turn that did its job; drop the third
+ * and it fires mid-cycle on the red step of red-green-refactor.
+ */
+export function detectUntestedChange(reply: string, toolCalls: readonly ToolCall[]): Finding | null {
+    const edited = toolCalls
+        .filter((c) => _EDIT_TOOLS.has(c.name) && c.path !== undefined)
+        .map((c) => c.path as string);
+    const source = edited.filter(_isProductionSource);
+    if (source.length === 0) return null;
+    if (edited.some(_isTestPath)) return null;
+
+    // The claim gate, reusing detector D's pair rather than a second dialect of
+    // "done" — two lists of completion phrasings would drift, and the negation
+    // check is what keeps an honest "noch nicht fertig" from being refused.
+    const prose = visibleProse(reply);
+    const m = _COMPLETION_RE.exec(prose);
+    if (!m) return null;
+    if (_NEGATED_CLAIM_RE.test(_lineAround(prose, m.index))) return null;
+
+    const shown = source.slice(0, 3).join(', ');
+    return {
+        detector: 'untested',
+        evidence: shown + (source.length > 3 ? ` (+${String(source.length - 3)} more)` : ''),
+        reason:
+            'a completion claim over production code this turn changed, with NO test file ' +
+            'touched anywhere in the turn — running a linter is not evidence the change ' +
+            'works. Write the test that would have caught the failure, and enumerate the ' +
+            'states the change actually has (every view, every CRUD path, the empty and ' +
+            'error states) rather than the happy one. If a test genuinely does not belong ' +
+            'here, say which file carries the coverage instead',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Re-entrancy — the guard, keyed on the turn, not on the reply
 // ---------------------------------------------------------------------------
@@ -811,6 +945,7 @@ function markRefusedTurn(
     sessionKey: string,
     turnOrdinal: number,
     detectors: readonly DetectorId[],
+    promptId: string,
 ): void {
     if (is_replay_mode()) return;
     const file = sessionStateFile(workspaceRoot, sessionKey);
@@ -835,6 +970,7 @@ function markRefusedTurn(
                 turnOrdinal,
                 at: new Date().toISOString(),
                 version,
+                promptId,
             }) as unknown as Record<string, unknown>,
         );
     } catch {
@@ -868,6 +1004,20 @@ export interface ToolCall {
 
 export interface TranscriptTail {
     lastAssistant: string;
+    /**
+     * Every assistant text of the CURRENT turn, in order — reset at each genuine
+     * user prompt exactly like `toolCalls`, and for the same reason: a question
+     * asked three turns ago was answered, a question asked earlier in THIS turn
+     * was not. Detector E reads it; the other four read `lastAssistant`, which is
+     * always the last element when this is non-empty.
+     *
+     * A tool-only assistant entry contributes NOTHING here. `_messageText`
+     * returns null for it and the collector skips it, so the ordinary shape of a
+     * working turn — prose, tool call, prose — produces two elements and not
+     * three. That is the whole false-positive surface of detector E, and it is
+     * closed here rather than in the detector.
+     */
+    assistantTurnTexts: string[];
     /**
      * How many GENUINE user prompts the transcript carries — harness-injected
      * user-role entries excluded via `isSyntheticPrompt`. This is the turn's
@@ -899,7 +1049,12 @@ export function readTranscriptTail(
     transcriptPath: string,
     opts: { homeDir?: string; maxBytes?: number } = {},
 ): TranscriptTail {
-    const empty: TranscriptTail = { lastAssistant: '', turnOrdinal: 0, toolCalls: [] };
+    const empty: TranscriptTail = {
+        lastAssistant: '',
+        turnOrdinal: 0,
+        toolCalls: [],
+        assistantTurnTexts: [],
+    };
     if (!transcriptPath || !isSafeTranscriptPath(transcriptPath, opts)) return empty;
     let lines: string[];
     try {
@@ -919,6 +1074,7 @@ export function readTranscriptTail(
     let lastAssistant = '';
     let turnOrdinal = 0;
     let toolCalls: ToolCall[] = [];
+    let assistantTurnTexts: string[] = [];
     for (const rawLine of lines) {
         const line = rawLine.trim();
         if (!line) continue;
@@ -944,12 +1100,13 @@ export function readTranscriptTail(
         // only a tool_use block has no text at all, so `continue`-ing on a null
         // text would drop exactly the entries this detector exists to see.
         if (role === 'assistant') {
-            toolCalls.push(..._toolCalls(content));
+            toolCalls.push(...extractToolCalls(content));
         }
         const text = _messageText(content);
         if (text === null) continue;
         if (role === 'assistant') {
             lastAssistant = text;
+            assistantTurnTexts.push(text);
         } else if (!isSyntheticPrompt(text)) {
             turnOrdinal += 1;
             // A genuine user prompt starts a new turn, so the previous turn's
@@ -957,17 +1114,34 @@ export function readTranscriptTail(
             // run three turns ago would vouch for an edit made now — the
             // "fresh" in edit-without-FRESH-verification is this line.
             toolCalls = [];
+            // Same boundary, same reason, for detector E: an options block the
+            // user has since replied to is answered, not dropped. Resetting on
+            // the identical line is what makes "in the SAME user turn" true of
+            // the array rather than merely intended.
+            assistantTurnTexts = [];
         }
     }
-    return { lastAssistant: lastAssistant.trim(), turnOrdinal, toolCalls };
+    return {
+        lastAssistant: lastAssistant.trim(),
+        turnOrdinal,
+        toolCalls,
+        assistantTurnTexts,
+    };
 }
 
 /**
  * Extract this entry's tool calls, keeping only name, shell command and target
  * path. A tool input can hold a whole file body; nothing but those three fields
  * is carried forward.
+ *
+ * Exported because `measure_turn_end_gate` scores detectors C and E over a real
+ * transcript corpus and therefore has to rebuild the same `ToolCall[]` the gate
+ * sees. A second extractor there would be a second dialect of "what the turn
+ * did", and the measurement would then be of that dialect rather than of the
+ * shipped gate — the exact population-parity defect that script's own header
+ * documents twice.
  */
-function _toolCalls(content: unknown): ToolCall[] {
+export function extractToolCalls(content: unknown): ToolCall[] {
     if (!Array.isArray(content)) return [];
     const out: ToolCall[] = [];
     for (const blk of content) {
@@ -1074,11 +1248,30 @@ export function main(): number {
     // in production while its comment claimed it was enforced — the same
     // fixed-the-definition-not-the-caller shape as two other findings in that
     // round, which is why this line exists rather than a default parameter.
-    const { lastAssistant, turnOrdinal, toolCalls } = readTranscriptTail(transcriptPath, {
-        maxBytes: TRANSCRIPT_READ_MAX_BYTES,
-    });
+    const { lastAssistant, turnOrdinal, toolCalls, assistantTurnTexts } = readTranscriptTail(
+        transcriptPath,
+        { maxBytes: TRANSCRIPT_READ_MAX_BYTES },
+    );
     if (!lastAssistant) return EXIT_ALLOW;
 
+    // The closing reply comes from the field the host hands us when it supplies
+    // one, not only from a file the host writes asynchronously. The transcript
+    // may lag the in-memory conversation, and a tail that is one assistant entry
+    // short is silence for `detectDroppedDecision`, whose early return needs two
+    // texts — i.e. the detector goes quiet in exactly the shape it exists for.
+    // `suggestion_capture_hook.ts` reads the same field for the same reason.
+    // Appended, never substituted: `lastAssistant` and the four other detectors
+    // are untouched, and a host that supplies no such field is unchanged.
+    const payloadClosing = str(
+        (payload['last_assistant_message'] ?? payload['lastAssistantMessage']) as
+            | JsonValue
+            | undefined,
+    );
+    const closingFromPayload = payloadClosing !== '' && !assistantTurnTexts.includes(payloadClosing);
+    const turnTexts = closingFromPayload
+        ? [...assistantTurnTexts, payloadClosing]
+        : assistantTurnTexts;
+
     // Layer 2 — keyed on the turn's ORDINAL, never on the prompt's text.
     // A host that sends no `session_id` shares one bucket AND one small-integer
     // ordinal namespace, so an unrelated session whose ordinal matches a stored
@@ -1092,6 +1285,13 @@ export function main(): number {
     // producer keys that on the raw `session_id`. Passing `sessionKey` here would
     // read a path nothing writes — the same shape as the STATE_FILE break this
     // parameter exists to close.
+    // The host's own id for the prompt being processed. Read here and recorded
+    // beside the ordinal in the refusal marker — never used as the guard key.
+    // The ordinal's drift is what both re-entrancy layers exist for, so a later
+    // reading needs the pair to tell a drifted ordinal from a second prompt.
+    const promptId = str(
+        (payload['prompt_id'] ?? payload['promptId']) as JsonValue | undefined,
+    );
     const rawSessionId = str(envelope['session_id'] as JsonValue | undefined) || '';
     const sessionKey = deriveSessionKey(rawSessionId || 'unknown-session');
     if (alreadyRefusedTurn(workspaceRoot, sessionKey, turnOrdinal)) return EXIT_ALLOW;
@@ -1129,6 +1329,22 @@ export function main(): number {
         dispatchOpen
             ? null
             : detectCompletionClaim(lastAssistant, readCiSettled(workspaceRoot, rawSessionId)),
+        // Detector E is UNCONDITIONAL, and that is the opposite choice from A
+        // and D one line above rather than an oversight. An open dispatch
+        // excuses a promissory closing because the work is genuinely still
+        // running; it excuses nothing about a question the user was already
+        // asked. Worse: a dispatch — or the `end-review-nudge` stop concern
+        // that produced the measured failure — IS the continuation that drops
+        // the decision, so narrowing E the same way would silence it in exactly
+        // the case it exists for.
+        detectDroppedDecision(turnTexts, closingFromPayload),
+        // Detector F takes the OTHER side of that same question, and the two
+        // sitting adjacent is the clearest place to say why. E fires on a
+        // question already asked, which an open dispatch cannot excuse. F fires
+        // 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`.
+        dispatchOpen ? null : detectUntestedChange(lastAssistant, toolCalls),
     ]) {
         if (f) findings.push(f);
     }
@@ -1139,6 +1355,7 @@ export function main(): number {
         sessionKey,
         turnOrdinal,
         findings.map((f) => f.detector),
+        promptId,
     );
 
     const lines = findings.map(
@@ -1147,8 +1364,9 @@ export function main(): number {
     process.stderr.write(
         `turn-end-gate: REFUSED — this turn is not finished.\n${lines.join('\n')}\n` +
             '  Do the promised work now, correct the language, run the ' +
-            'verification the edit needs, or read the CI verdict before claiming ' +
-            'it — then end the turn.\n' +
+            'verification the edit needs, read the CI verdict before claiming ' +
+            'it, or re-present the options block this turn dropped — then end ' +
+            'the turn.\n' +
             '  This turn will not be refused a second time.\n',
     );
     return EXIT_BLOCK;

package/src/scripts/hooks_doctor.ts

@@ -40,10 +40,12 @@ import * as hooks_status from "./hooks_status.js";
 import {
   DETECTOR_IDS,
   collectRefusalStats,
+  emptyCounts,
   readInstallBoundary,
   type InstallBoundary,
   type RefusalStats,
 } from "./_lib/turn_end_refusals.js";
+import { ledgerWritable, readDelivered } from "./_lib/obligations.js";
 
 // src/scripts/hooks_doctor.ts → parents[2] (../../..) is the repo root,
 // mirroring the Python `Path(__file__).resolve().parents[2]`.
@@ -190,10 +192,35 @@ export interface DoctorPayload {
    * concern's health is already read, so this is where the number belongs.
    */
   turn_end_refusals: RefusalStats;
+  /**
+   * The obligation ledger's two readiness figures.
+   *
+   * Reported here and nowhere else, because the doctor is where a concern's
+   * health is already read and the ledger's failure mode is silence: it never
+   * throws, never refuses and never fails a turn, so an unwritable ledger
+   * looks exactly like a session that triggered no rules. These two lines are
+   * the difference between those, and they are the ONLY consumer the ledger
+   * has — reporting a count is not acting on the rows.
+   */
+  obligation_ledger: ObligationLedgerStats;
   /** The machine's install stamp, for reading the version split below it. */
   install_boundary: InstallBoundary;
 }
 
+/** What the doctor can say about the ledger without interpreting a single row. */
+export interface ObligationLedgerStats {
+  /** Probed by writing and removing a sentinel, not by reading mode bits. */
+  writable: boolean;
+  /**
+   * Rows for THIS session, or `null` when no session id was resolvable.
+   *
+   * `null` and `0` are different answers and are rendered differently: `0`
+   * means this session was delivered no rule, `null` means the doctor could
+   * not tell which session it is in and so has nothing to count.
+   */
+  rows_this_session: number | null;
+}
+
 /** Build the doctor payload — JSON-serialisable. */
 export function collect(
   project_root: string,
@@ -268,7 +295,9 @@ export function collect(
     turn_end_refusals = {
       sessionsWithRefusals: 0,
       total: 0,
-      byDetector: { promissory: 0, language: 0, verification: 0, completion: 0 },
+      // Derived, never a literal: a fifth detector made the old four-key object
+      // a type error here and a silent `NaN` in the aggregator it mirrors.
+      byDetector: emptyCounts(),
       byPeriod: [],
       legacyRecords: 0,
       unversionedRecords: 0,
@@ -285,10 +314,67 @@ export function collect(
     trampolines,
     dispatch_issues: issues,
     turn_end_refusals,
+    obligation_ledger: collectLedgerStats(project_root),
     install_boundary: readInstallBoundary(),
   };
 }
 
+/**
+ * The ledger's two figures, never throwing.
+ *
+ * The session id comes from the host's own environment variable, which is the
+ * same source the concerns key their state on. Absent means the doctor is
+ * being run outside a session — by a human at a shell, most often — and the
+ * honest answer is `null` rather than 0, because there is no session whose
+ * rows could be counted.
+ */
+export function collectLedgerStats(project_root: string): ObligationLedgerStats {
+  let writable = false;
+  try {
+    writable = ledgerWritable(project_root);
+  } catch {
+    writable = false;
+  }
+  const session = (process.env["CLAUDE_CODE_SESSION_ID"] ?? "").trim();
+  if (session === "") return { writable, rows_this_session: null };
+  try {
+    return { writable, rows_this_session: readDelivered(project_root, session).length };
+  } catch {
+    return { writable, rows_this_session: null };
+  }
+}
+
+/**
+ * The ledger section.
+ *
+ * Deliberately states what a row is NOT. The council lock this ledger sits
+ * under says installation proves availability and not exposure, so a reader
+ * who sees a healthy row count and concludes the rules were followed has made
+ * the one claim these records may never support. The line is cheap; the
+ * misreading it prevents is the whole reason the ledger needed a non-goal.
+ */
+export function _render_ledger(payload: DoctorPayload): string[] {
+  const s = payload.obligation_ledger;
+  const lines: string[] = [];
+  lines.push("Obligation ledger");
+  lines.push("-".repeat(60));
+  lines.push(
+    `${s.writable ? "✅ " : "❌ "}writable  ${
+      s.writable ? "agents/runtime/state/obligations/" : "cannot write agents/runtime/state/obligations/"
+    }`,
+  );
+  if (s.rows_this_session === null) {
+    lines.push("·  rows this session: no session id resolved — nothing to count");
+  } else {
+    lines.push(`·  rows this session: ${s.rows_this_session}`);
+  }
+  lines.push(
+    "   Rows record that an emitter ran. They are not evidence that a rule",
+  );
+  lines.push("   reached the model, and may not be read as compliance.");
+  return lines;
+}
+
 function _strVal(v: JsonValue | undefined): string {
   return v === undefined || v === null ? "undefined" : String(v);
 }
@@ -412,6 +498,8 @@ export function _render_table(payload: DoctorPayload): string {
   }
   lines.push("");
   lines.push(..._render_refusals(payload));
+  lines.push("");
+  lines.push(..._render_ledger(payload));
   // Dispatch-issues detail — last 20 grouped by concern.
   if (payload.dispatch_issues.length > 0) {
     lines.push("");

package/src/scripts/hooks_status.ts

@@ -73,11 +73,22 @@ export const PLATFORM_BRIDGES: Record<string, [string, string]> = {
   copilot: ["", "rule-only fallback — this package binds no hook here"],
 };
 
+/** The shape of a host's user-facing question primitive. */
+export type AskShape = "native" | "text";
+
 export interface PlatformRow {
   platform: string;
   status: string;
   bridge_path: string | null;
   fallback_only: boolean;
+  /**
+   * DECLARED in the manifest, never probed. A host with no row reads `text`:
+   * the conservative answer, and the one that is true of every host that has
+   * not said otherwise. Absent must not read as "unknown" here — an unknown
+   * that the contract then treats as native is exactly the silent degrade the
+   * row exists to prevent.
+   */
+  ask: AskShape;
   bindings: Record<string, string[]>;
   hint: string | null;
 }
@@ -122,6 +133,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
     const blockRaw = platforms[platform];
     const block = _isObject(blockRaw) ? blockRaw : {};
     const fallback_only = Boolean(block["fallback_only"]);
+    const ask: AskShape = block["ask"] === "native" ? "native" : "text";
     const bindings: Record<string, string[]> = {};
     if (!fallback_only) {
       for (const [ev, c] of Object.entries(block)) {
@@ -138,6 +150,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
       status,
       bridge_path: rel || null,
       fallback_only,
+      ask,
       bindings,
       hint: ["missing", "empty", "degraded", "n/a"].includes(status)
         ? hint
@@ -166,6 +179,12 @@ export function _render_table(matrix: StatusMatrix): string {
       head += `  (${row.bridge_path})`;
     }
     lines.push(head);
+    lines.push(
+      `    ask                    → ${row.ask}` +
+        (row.ask === "native"
+          ? "  (structured-ask tool; the recommendation is its default option)"
+          : "  (numbered text block — the fallback, and it says so)"),
+    );
     if (row.fallback_only) {
       lines.push(
         "    degraded: rule-only fallback " +