simt-dev 0.3.1 → 0.5.0

package/src/advice/advice.mjs

@@ -0,0 +1,229 @@
+// Model and effort advice, read from the repository's own bench history (plan 0003 R40).
+//
+// The mapping the design row asks for — task features to the cheapest tier that resolved
+// similar tasks — is data, not opinion: the records `bench run` stored on disk already say
+// which model classes resolved which mined tasks and what those runs cost. So the tier
+// ladder is the estate's own evidence sorted by price, and no vendor name is written into
+// the code: a repository whose history has one class of run gets advice about that class,
+// and one whose history has three gets a ladder with three steps.
+//
+// The properties this exists to keep:
+//
+//   * Advice, never a choice. The output is a sentence in the brief header along with the
+//     bench numbers behind it; the agent (or the human) names the model, not simt-dev
+//     (P2). Nothing here writes a model id into a config, a lock or a command.
+//   * Deterministic. No model, no network, no clock (P1): the same runs directory yields
+//     the same advice, so a reviewable claim about cost is possible.
+//   * Quiet in thin evidence. A neighborhood with no resolved run yields a caution, not a
+//     made-up tier; a history with no runs at all yields no advice line.
+//
+// The measure of "cheapest" follows the bench's own report: cost in dollars when the run
+// records or a prices table price the tokens, total tokens otherwise. Ordering by a number
+// that does not exist for any run would be nondeterminism, not economics.
+import { classifyTask } from '../brief/kind.mjs';
+import { computeRunCost, isRunResolved, loadPrices, loadRunRecords } from '../bench/report.mjs';
+import { loadTasks } from '../bench/tasks.mjs';
+import { CONFIG_DIR } from '../name.mjs';
+
+/**
+ * Every advice report carries its row's accept bar (ADR-076: a metric is a measurement or
+ * it is not claimed).
+ */
+export const METRIC_NOTE =
+  'advice is advisory until a held-out bench shows >= 25% cost cut at delta R >= -2 (plan 0003 R40)';
+
+const TIERS = ['small', 'default', 'frontier'];
+
+/**
+ * The ladder can specialize beyond kind only while there is still evidence to stand on:
+ * below this many same-kind tasks the kind is the whole neighborhood, and a narrower
+ * window makes evidence worse, not "more similar".
+ */
+const NARROW_MIN_POOL = 6;
+
+/** The narrowed window needs at least these resolved runs or it is not evidence either. */
+const NARROW_MIN_RESOLVED = 3;
+
+/** A file window is a step from the estimate in either direction — a factor of two in size. */
+const WINDOW_HALF = 2;
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * Tier for a rank in the cheapest-first ladder: thirds, not absolute cost — an estate's
+ * "frontier" relative to its own history means more than a number the code guessed.
+ * The cheapest of two observed classes is 'small' and the dearer one 'default'; a class
+ * is 'frontier' only once a ladder has three steps, because a two-step ladder cannot
+ * name a top third honestly.
+ */
+export function tierOfRank(rank, count) {
+  if (count < 3) return rank === 0 ? TIERS[0] : TIERS[1];
+  if (rank * 3 < count) return TIERS[0];
+  if (rank * 3 >= count * 2) return TIERS[2];
+  return TIERS[1];
+}
+
+/**
+ * Total tokens a usage report carries — the measure that exists even with no prices file.
+ */
+function tokensOf(usage = {}) {
+  const num = (v) => Number(v ?? 0);
+  return num(usage.input) + num(usage.cacheWrite ?? usage.cache_write) + num(usage.cacheRead ?? usage.cache_read) + num(usage.output);
+}
+
+/**
+ * Load bench history as advice-ready run rows.
+ *
+ * A descriptor missing for a run leaves the row with `kind: null`; such a run can join no
+ * neighborhood, which is the honest answer — a task whose prompt was never mined is a
+ * task whose kind would be a guess.
+ */
+export async function loadHistory(root) {
+  const [records, prices, tasks] = await Promise.all([
+    loadRunRecords(root),
+    // An unreadable prices file would throw out of a brief, whose callers only asked for
+    // a packet; the bench has its own report for surfacing a broken prices file loudly.
+    loadPrices(root).catch(() => null),
+    loadTasks(root),
+  ]);
+  const byId = new Map(tasks.map((task) => [task.id, task]));
+  const runs = records.map((record) => {
+    const descriptor = byId.get(record.task) ?? null;
+    return {
+      task: record.task,
+      model: record.model,
+      resolved: isRunResolved(record),
+      cost: computeRunCost(record, prices),
+      tokens: tokensOf(record.usage),
+      toolCalls: Number(record?.usage?.toolCalls ?? record?.usage?.tool_calls ?? 0),
+      files: Number(descriptor?.gold?.files ?? record?.diff?.files ?? 0),
+      kind: descriptor ? classifyTask(descriptor.prompt ?? '', { paths: [] }).kind : null,
+    };
+  });
+  return { runs };
+}
+
+/**
+ * Advise from bench history for one task's features.
+ *
+ * @param {{kind: string, files: number}} features the task kind, and the estimate of how
+ *   many files it will touch (the brief's scope size; a history run carries the mined
+ *   task's gold stat in the same role)
+ * @param {{runs: object[]}} history rows from loadHistory
+ * @returns null when the history holds no runs; otherwise `{ picked, caution }` where
+ *   `picked` is `{ line, basis, metric }` when a tier was named (and `caution` null), and
+ *   `caution` explains the missing neighborhood when no tier can honestly be named
+ */
+export function advise(features, history) {
+  const runs = history?.runs ?? [];
+  if (runs.length === 0) return null;
+  const kind = features.kind;
+  const sameKind = runs.filter((run) => run.kind === kind);
+  const taskCount = new Set(sameKind.map((run) => run.task)).size;
+  if (sameKind.length === 0) {
+    return {
+      picked: null,
+      caution: `bench history holds no ${kind} task, so no cheap tier was advised`,
+    };
+  }
+
+  // The measure is chosen once, across all resolved history: a ladder built on dollars
+  // while the pick ran on tokens would compare a number with a different number's name.
+  const measure = runs.some((run) => run.resolved && run.cost > 0) ? 'cost' : 'tokens';
+
+  // Kind decides the neighborhood. The file window only specializes a neighborhood that
+  // has already got evidence to spare (NARROW_MIN_*): a factor-of-two window around the
+  // estimate refines "bugfix" to "small bugfix" when the kind has runs to lend, and says
+  // nothing when it has not.
+  let pool = sameKind;
+  if (features.files > 0 && sameKind.length >= NARROW_MIN_POOL) {
+    const near = sameKind.filter(
+      (run) =>
+        run.files > 0 &&
+        run.files >= Math.ceil(features.files / WINDOW_HALF) &&
+        run.files <= features.files * WINDOW_HALF,
+    );
+    if (near.filter((run) => run.resolved).length >= NARROW_MIN_RESOLVED) pool = near;
+  }
+  const poolTaskCount = new Set(pool.map((run) => run.task)).size;
+
+  // The ladder orders every model class the estate ever ran, cheapest first, so the
+  // advice can say where its pick sits in the estate's whole history. Uncost evidence is
+  // still cost position: a class that never resolved one of these tasks occupies a rung
+  // in the price ladder, and the resolved floor below — not the ladder — decides whether
+  // the pick is allowed to stand on it.
+  const ladderValues = new Map();
+  for (const run of runs) {
+    const values = ladderValues.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    ladderValues.set(run.model, values);
+  }
+  const ladderNames = [...ladderValues.keys()].sort(
+    (a, b) => median(ladderValues.get(a)) - median(ladderValues.get(b)) || a.localeCompare(b),
+  );
+
+  const resolvedByModel = new Map();
+  for (const run of pool) {
+    if (!run.resolved) continue;
+    const values = resolvedByModel.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    resolvedByModel.set(run.model, values);
+  }
+
+  // "Resolved similar tasks" is a floor, not a style: a class that never resolved one of
+  // these tasks is cheaper because it failed for less money.
+  const qualifying = ladderNames.filter((model) => resolvedByModel.has(model));
+  if (qualifying.length === 0) {
+    return {
+      picked: null,
+      caution: `no model resolved any of the ${taskCount} ${kind} task${taskCount === 1 ? '' : 's'} in bench history, so no cheap tier was advised`,
+    };
+  }
+
+  // Ties break on the model name, so the same history always yields the same pick (P4).
+  const cheapest = [...qualifying].sort(
+    (a, b) => median(resolvedByModel.get(a)) - median(resolvedByModel.get(b)) || a.localeCompare(b),
+  )[0];
+  const ladderRank = ladderNames.indexOf(cheapest);
+  const tier = tierOfRank(ladderRank, ladderNames.length);
+
+  // Effort advice is relative to the estate too: heavier turns of tool use than the
+  // estate's own resolved median is what "plan first" means here.
+  const resolvedRuns = runs.filter((run) => run.resolved);
+  const estateToolCalls = median(resolvedRuns.map((run) => run.toolCalls));
+  const resolvedRunsOfCheapest = pool.filter((run) => run.resolved && run.model === cheapest);
+  const pickToolCalls = median(resolvedRunsOfCheapest.map((run) => run.toolCalls));
+  const effort = estateToolCalls > 0 && pickToolCalls > estateToolCalls ? 'plan first' : 'no plan mode';
+
+  const pickMedian = median(resolvedByModel.get(cheapest));
+  const pickUnit = measure === 'cost' ? `cost $${pickMedian.toFixed(4)}` : `tokens ${Math.round(pickMedian)}`;
+
+  return {
+    picked: {
+      line: `${tier} model, ${effort}`,
+      basis: `from ${poolTaskCount} ${kind} task${poolTaskCount === 1 ? '' : 's'} in bench history; cheapest that resolved: ${cheapest} (median ${pickUnit}); a human picks the model, this only ranks classes`,
+      metric: METRIC_NOTE,
+    },
+    caution: null,
+  };
+}
+
+/**
+ * The brief's door into advice (plan 0003 R40): history on disk in, advice out, or null
+ * when the history has no runs at all — a brief in a repository without bench history
+ * carries every other section and no made-up opinion about models.
+ *
+ * `kind` comes in already classified when the caller is the brief itself, so the packet
+ * never carries two opinions about one task.
+ */
+export async function briefAdvice(root, { task = '', scope = [], kind = null } = {}) {
+  const history = await loadHistory(root);
+  if (history.runs.length === 0) return null;
+  const known = kind ?? classifyTask(task, { paths: scope }).kind;
+  return advise({ kind: known, files: scope.length }, history);
+}

package/src/agenthooks/policy.mjs

@@ -21,8 +21,16 @@
 
 import { CLI } from '../name.mjs';
 
-/** The events an agent-time hook can answer, normalised across harnesses. */
-export const EVENTS = ['pre-tool-use'];
+/**
+ * The events an agent-time hook can answer, normalised across harnesses.
+ *
+ * `pre-tool-use` is a decision: a payload in, a deny or nothing out, and exit 2 means
+ * block. `prompt-submit` is a delivery: the same payload shape in, context out, and it
+ * never denies anything — a hook that could stop a person's prompt would be a hook whose
+ * own bug is a person who cannot type (R29). `post-tool-use` recalls a lesson as one
+ * paragraph when a tool call fails with a signature matching `docs/lessons/*.md` (R33).
+ */
+export const EVENTS = ['pre-tool-use', 'prompt-submit', 'post-tool-use'];
 
 /** The environment variable that lifts named policies for one session. */
 export const ALLOW_ENV = 'SIMT_ALLOW';

package/src/agenthooks/prompt.mjs

@@ -0,0 +1,81 @@
+// The prompt-submit surface: the packet delivered where the agent will read it.
+//
+// This module must stay off the tool-call path, and the code's shape is what keeps it
+// there: `src/commands/agenthook.mjs` reaches it through a dynamic `import()` that only a
+// prompt event takes. The pre-tool hook is a latency promise — it answers before every
+// shell command an agent runs — so it imports the policy table, the decision and the
+// renderer and nothing that walks the repository, and `test/agenthooks.test.mjs` asserts
+// exactly that set. A delivery, by contrast, is the one thing here that must read the
+// repository, so it lives behind a door the pre-tool path never opens.
+//
+// Three rules shape what gets delivered:
+//
+//   * The repository opts in. The opt-in is a `brief` key in the repository's manifest,
+//     not the presence of a hook in a harness config: a repository that declared nothing
+//     is not spending its owner's context on a packet they did not ask for, and the
+//     manifest is the one file a person reviews before they commit the change.
+//   * The packet is capped, at PROMPT_CAP_BYTES. A packet is delivered into a prompt that
+//     already exists, and the ceiling is the measured bar of this slice rather than a
+//     value a repository is free to raise.
+//   * A delivery never blocks and never fails loudly. Everything that could go wrong —
+//     no index, no prompt in the payload, a registry that will not load — ends in no
+//     injection and a line on stderr. A hook that stopped a person's prompt because this
+//     tool could not answer would be worse than a hook that said nothing.
+
+import { readManifest } from '../projection/manifest.mjs';
+import { DEFAULT_BRIEF_BYTES, PROMPT_CAP_BYTES } from '../brief/packet.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+import { deliveryJson, factsFrom, promptText } from './render.mjs';
+
+/**
+ * Whether this repository asked for a delivered packet, and the ceiling it asked for.
+ *
+ * Presence is the opt-in and the value is a preference, so `"brief": {}` means "yes, at
+ * whatever you measured" and `"brief": { "bytes": 900 }` means "yes, and keep it small".
+ * A declared zero is not honoured as a ceiling: zero is this tool's word for "no ceiling"
+ * on the command line, and a delivered packet that meant "the whole repository" would be
+ * the one thing the cap exists to prevent. It is read from the manifest rather than from
+ * the harness config because the manifest is the file the repository reviews.
+ */
+export async function promptOptIn(root) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists || error) {
+    return { optedIn: false, bytes: DEFAULT_BRIEF_BYTES, why: `${exists ? error : 'no manifest'}` };
+  }
+  if (manifest?.brief === undefined || manifest.brief === null) {
+    return { optedIn: false, bytes: DEFAULT_BRIEF_BYTES, why: 'no `brief` key in the manifest' };
+  }
+  const declared = manifest.brief?.bytes;
+  const asked = Number.isFinite(declared) && declared > 0 ? declared : PROMPT_CAP_BYTES;
+  return { optedIn: true, bytes: Math.min(asked, PROMPT_CAP_BYTES) };
+}
+
+/**
+ * The context one prompt-submit call should deliver, or the reason it delivers nothing.
+ *
+ * `build: false` is the latency promise in one argument: a delivery reports a cold index
+ * rather than building one, so the first prompt in a fresh clone gets nothing and the
+ * second gets the packet. The alternative — a person watching their first prompt sit for
+ * a minute while a repository is walked — is how the hook gets uninstalled, and the
+ * packet is not worth a prompt that cannot be typed.
+ */
+export async function deliverPrompt(row, payload) {
+  const task = promptText(row, payload);
+  if (task === null) return { skipped: 'the payload carries no prompt this harness documents' };
+
+  // The root is the same dialect fact for both events, so it is read the same way.
+  const root = factsFrom(row, payload).root;
+  const optIn = await promptOptIn(root);
+  if (!optIn.optedIn) return { skipped: optIn.why };
+
+  // Federation is off on this path and on no other: a delivery has 300 ms to answer, and
+  // starting a declared server is a wait a prompt submit must not take. The task is the
+  // question a federation would ask, and a person is not made to wait for it here.
+  const result = await assembleBrief({ root, task, budget: optIn.bytes, build: false, federate: false });
+  if (result.error) return { skipped: 'the packet could not be assembled' };
+  if (result.cold) return { skipped: 'the index is empty, and a delivered packet never builds one' };
+
+  const json = deliveryJson(row, result.packed.text);
+  if (json === null) return { skipped: `${row.id} has no prompt event that can inject` };
+  return { json, root, bytes: result.packed.after };
+}

package/src/agenthooks/render.mjs

@@ -11,6 +11,26 @@
 //   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
 //   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
 //
+// The prompt-submit event (R29) is a second table, and it is shorter because the vendors
+// are: two of the four document a prompt event that can put text into the model's context,
+// and a delivery is the only thing this tool does there. Neither takes a matcher — both
+// document that field for tool events, and a matcher a harness ignores is a matcher the
+// next person believes is filtering something.
+//
+//   claude       .claude/settings.json   UserPromptSubmit   hookSpecificOutput.additionalContext
+//   codex        .codex/hooks.json       UserPromptSubmit   hookSpecificOutput.additionalContext
+//   cursor       .cursor/hooks.json      beforeSubmitPrompt CANNOT INJECT: block-only
+//   antigravity  .agents/hooks.json      (no prompt event documented)
+//
+// Cursor is the one that would be a mistake to write anyway. Its `beforeSubmitPrompt` hook
+// can only continue or block, so the entry would carry no packet and a broken one would
+// stop a person from typing — and its only injection point, `sessionStart.additional_context`,
+// fires once when the session is created, which is a different lifetime from the brief a
+// task needs. Gemini CLI documents `BeforeAgent`, which does inject, but the product was
+// replaced by Antigravity CLI on 2026-06-18 and its config is not in the reader table this
+// module takes its paths from; a harness this tool did not verify is a harness it does not
+// write to.
+//
 // The paths are not written here. They come from the reader table (R14) because that is
 // where each one was verified against its vendor page, and a second copy of a verified
 // fact is a copy that drifts the first time a vendor moves the file.
@@ -36,8 +56,8 @@ const TIMEOUT_SECONDS = 10;
  * harness's dialect when a payload arrived in an unexpected shape, and the harness would
  * read a decision it does not understand as no decision at all.
  */
-export function hookCommand(id) {
-  return `${CLI} agent-hook ${EVENTS[0]} --harness ${id}`;
+export function hookCommand(id, event = EVENTS[0]) {
+  return `${CLI} agent-hook ${event} --harness ${id}`;
 }
 
 /** The path a config file lives at, from the reader table rather than a second list. */
@@ -73,6 +93,20 @@ const ADAPTERS = {
     deny: (message) => ({
       hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
     }),
+    // The delivery door. `additionalContext` is documented for this event and is
+    // wrapped into the conversation at the point the hook fired, which is why the
+    // packet goes here rather than into a system prompt: the cached prefix survives.
+    prompt: {
+      event: 'UserPromptSubmit',
+      verified: 'code.claude.com/docs/en/hooks, read 2026-10-19',
+      context: (text) => ({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }),
+    },
+    post: {
+      event: 'PostToolUse',
+      matcher: 'Bash',
+      verified: 'code.claude.com/docs/en/hooks, read 2026-10-19',
+      context: (text) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }),
+    },
   },
   codex: {
     id: 'codex',
@@ -96,6 +130,17 @@ const ADAPTERS = {
     deny: (message) => ({
       hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
     }),
+    prompt: {
+      event: 'UserPromptSubmit',
+      verified: 'developers.openai.com/codex/hooks, read 2026-10-19',
+      context: (text) => ({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }),
+    },
+    post: {
+      event: 'PostToolUse',
+      matcher: 'Bash',
+      verified: 'developers.openai.com/codex/hooks, read 2026-10-19',
+      context: (text) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }),
+    },
   },
   cursor: {
     id: 'cursor',
@@ -111,6 +156,11 @@ const ADAPTERS = {
         : [],
     }),
     deny: (message) => ({ permission: 'deny', user_message: message, agent_message: message }),
+    // beforeSubmitPrompt is documented as continue/block and nothing else, so there is no
+    // key to deliver a packet in. Writing the entry anyway would put a command that reads
+    // a repository on the path of every prompt a person types, to say nothing.
+    prompt: null,
+    post: null,
   },
   antigravity: {
     id: 'antigravity',
@@ -133,6 +183,10 @@ const ADAPTERS = {
       };
     },
     deny: (message) => ({ decision: 'deny', reason: message }),
+    // No prompt event is documented for this harness's hooks file, and a guessed event
+    // name is a hook that never fires while its config says it does.
+    prompt: null,
+    post: null,
   },
 };
 
@@ -160,6 +214,37 @@ export function decisionJson(row, decision) {
   return row.deny(decision.messages.join('\n'));
 }
 
+/**
+ * The document to print for a delivery, or null when the harness takes none.
+ *
+ * A delivery is never a decision: nothing here can deny, and the caller exits 0 whatever
+ * this returns. That is the whole difference between the two events, and it is why the
+ * prompt event has no `denyExit` — there is no exit code that means "here is some context".
+ */
+export function deliveryJson(row, text) {
+  return row.prompt ? row.prompt.context(text) : null;
+}
+
+/** The document to print for a post-tool lesson recall delivery, or null when the harness takes none. */
+export function postDeliveryJson(row, text) {
+  return row.post ? row.post.context(text) : null;
+}
+
+/**
+ * The submitted text a prompt payload carries, or null when it carries none we recognise.
+ *
+ * Marked inferred rather than documented: both harnesses that take this event place the
+ * prompt at the top level, but only in the example on each page, not as a stated contract.
+ * An unrecognised payload therefore delivers nothing and says so on stderr. The failure
+ * this must not have is the opposite one — a packet delivered as though it answered a task
+ * it never saw, which reads as a confident answer about the wrong question.
+ */
+export function promptText(row, payload) {
+  if (!row.prompt) return null;
+  const text = payload?.prompt ?? payload?.user_prompt ?? payload?.message;
+  return typeof text === 'string' && text.trim().length > 0 ? text : null;
+}
+
 // ---------------------------------------------------------------------------
 // The config file: reading ours out of somebody else's JSON, and putting it back.
 // ---------------------------------------------------------------------------
@@ -180,9 +265,36 @@ function container(row, config, { create = false } = {}) {
   return config.hooks ?? null;
 }
 
+/** The vendor's name for one of our events on this row, or null when it has none. */
+function vendorEvent(row, event) {
+  if (event === EVENTS[0]) return row.event;
+  if (event === 'prompt-submit') return row.prompt?.event ?? null;
+  if (event === 'post-tool-use') return row.post?.event ?? null;
+  return null;
+}
+
+/** The events a row answers, and the name each one goes under in its config file. */
+function eventsOf(row, { prompt = false, post = false } = {}) {
+  const pairs = [[EVENTS[0], row.event]];
+  if (prompt && row.prompt) pairs.push(['prompt-submit', row.prompt.event]);
+  if (post && row.post) pairs.push(['post-tool-use', row.post.event]);
+  return pairs;
+}
+
 /** The group this tool owns for one event, in that harness's shape. */
-function group(row) {
-  const command = hookCommand(row.id);
+function group(row, event = EVENTS[0]) {
+  const command = hookCommand(row.id, event);
+  if (event === 'prompt-submit') {
+    // No matcher: both vendors document that field for tool events, and a matcher a
+    // harness ignores is a matcher the next reader believes is filtering something.
+    return { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+  }
+  if (event === 'post-tool-use') {
+    const matcher = row.post?.matcher;
+    return matcher
+      ? { matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] }
+      : { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+  }
   if (row.id === 'cursor') {
     // failClosed is set because a hooks file this tool wrote should not silently
     // degrade to fail-open on its own crash: the vendor's default turns a broken hook
@@ -197,35 +309,44 @@ function ours(entry) {
   return JSON.stringify(entry).includes(`${CLI} agent-hook`);
 }
 
-function entries(row, config) {
-  const box = container(row, config);
-  const list = box?.[row.event];
+function entries(row, config, event = EVENTS[0]) {
+  const name = vendorEvent(row, event);
+  if (name === null) return [];
+  const list = container(row, config)?.[name];
   return Array.isArray(list) ? list : [];
 }
 
-/** Our entries in this document, for `status`; the document is not modified. */
-export function installedIn(row, config) {
-  return entries(row, config).filter(ours);
+/** Our entries in this document for one event, for `status`; the document is not modified. */
+export function installedIn(row, config, event = EVENTS[0]) {
+  return entries(row, config, event).filter(ours);
 }
 
 /**
- * The document with this tool's hook added, everything else left alone.
+ * The document with this tool's hooks added, everything else left alone.
  *
  * Written as JSON with two spaces and a trailing newline because that is what a file in
  * a repository reads like; a config that is rewritten with different indentation on
  * every run is a diff nobody can review. Keys this tool does not own are preserved
  * exactly, including their order, because the file belongs to the repository.
+ *
+ * One file can carry both events — Claude and Codex each hold a tool hook and a prompt
+ * hook in the same document — so this writes one group per event the row answers rather
+ * than one group per file. `prompt` is the caller's opt-in: a repository that has not
+ * asked for a delivered packet gets the tool hook and nothing extra, and the file it never
+ * asked to change is a file this tool does not touch.
  */
-function withHook(row, config) {
+function withHook(row, config, { prompt = false, post = false } = {}) {
   const box = container(row, config, { create: true });
-  const kept = entries(row, config).filter((e) => !ours(e));
-  box[row.event] = [...kept, group(row)];
+  for (const [event, name] of eventsOf(row, { prompt, post })) {
+    const kept = entries(row, config, event).filter((e) => !ours(e));
+    box[name] = [...kept, group(row, event)];
+  }
   return config;
 }
 
 /** The text `install` would write, or the reason the existing file cannot be read. */
-export function rendered(row, existing) {
-  if (existing === null) return { text: `${JSON.stringify(withHook(row, {}), null, 2)}\n`, action: 'created' };
+export function rendered(row, existing, options = {}) {
+  if (existing === null) return { text: `${JSON.stringify(withHook(row, {}, options), null, 2)}\n`, action: 'created' };
   let config;
   try {
     config = JSON.parse(existing);
@@ -235,6 +356,6 @@ export function rendered(row, existing) {
   if (config === null || typeof config !== 'object' || Array.isArray(config)) {
     return { error: 'not a JSON object; left alone' };
   }
-  const text = `${JSON.stringify(withHook(row, config), null, 2)}\n`;
+  const text = `${JSON.stringify(withHook(row, config, options), null, 2)}\n`;
   return { text, action: text === existing ? 'unchanged' : 'updated' };
 }

package/src/argv.mjs

@@ -74,10 +74,28 @@ export const BOOL_FLAGS = new Set([
   // Off by default because a path is the change the caller named, and the diff
   // is a different question.
   'changed',
+  // local doctor: allow non-loopback model URLs. Off by default because nothing leaves
+  // the machine unless explicitly overridden (ADR-075, plan 0003 R37).
+  'allow-remote',
+  // index / map / brief: opt into local vector embeddings configured under local.embed
+  // (plan 0003 R28, R37). Off by default unless recall@10 gains at least 10 points.
+  'embed',
+  // distill: regenerate a proposal that is already cached. Off by default because
+  // the cache is the point - the same source at the same budget is the same answer,
+  // and re-reading it is cheaper than re-deriving it (plan 0003 R38).
+  'refresh',
+  // distill: propose the summary from the configured local chat model instead of
+  // the deterministic outline. Off by default: no model in the default path (P1),
+  // and a model that is not asked for should not be opened against (ADR-090).
+  'local',
 ]);
 
 export const VALUE_FLAGS = new Set([
   'budget',
+  // bench critic: the labelled set of historical diffs to score (plan 0003 R39).
+  // A path, not a switch, because the labels themselves come from a human under
+  // ADR-008 — the tool never annotates for them.
+  'labels',
   'max-bytes',
   'paths',
   'skill',
@@ -118,6 +136,8 @@ export const VALUE_FLAGS = new Set([
   // map: outline (paths), names (exported symbols) or signatures (the line).
   // A boolean would not say which of the three the caller wanted.
   'level',
+  // decide: structured supersession spec (ADR-NNN or ADR-NNN:<ruling>[:<kind>], repeatable).
+  'supersedes',
 ]);
 
 /**
@@ -133,7 +153,7 @@ export const VALUE_FLAGS = new Set([
  * is a superset of the old behaviour, not a replacement: `--skill a,b` parsed before it
  * parses now.
  */
-export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare']);
+export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare', 'supersedes']);
 
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
@@ -207,6 +227,13 @@ export function parse(argv) {
   return { ok: true, value: { flags, positional } };
 }
 
+export function parsePathList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 /** `--max-bytes` -> `maxBytes`. Callers use camelCase; users type kebab-case. */
 function camel(name) {
   return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());

package/src/bench/grade.mjs

@@ -173,6 +173,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
       resolved: false,
       gatesPassed: false,
       diff,
+      goldFiles: [...goldFiles],
       agentPatch: diffPatchRes.stdout,
     };
   }
@@ -183,6 +184,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
       resolved: false,
       gatesPassed: false,
       diff,
+      goldFiles: [...goldFiles],
       agentPatch: diffPatchRes.stdout,
     };
   }
@@ -224,6 +226,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
     resolved,
     gatesPassed,
     diff,
+    goldFiles: [...goldFiles],
     agentPatch: diffPatchRes.stdout,
   };
 }