simt-dev 0.2.2 → 0.3.0

package/src/agenthooks/render.mjs

@@ -0,0 +1,240 @@
+// One renderer per harness: the payload in, the decision out, and the config written.
+//
+// Four harnesses read a hook and no two agree on anything. The config path, the event
+// name, the shape of the document, the tool name for a shell command, the key holding
+// the command, and the JSON a hook answers with are all different, and none of them is
+// the same fact. So this module owns the differences and `policy.mjs` owns none of
+// them:
+//
+//   claude       .claude/settings.json   PreToolUse      {"hooks":{E:[{matcher,hooks:[h]}]}}
+//   codex        .codex/hooks.json       PreToolUse      {"hooks":{E:[{matcher,hooks:[h]}]}}
+//   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
+//   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
+//
+// 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.
+//
+// Two things are recorded per row that a reader of the code cannot get from the code:
+// the page the shape was read from, and whether anything about the row is inferred.
+// An inferred key is marked as inferred rather than presented as documented, because
+// the failure that matters is not a missing policy — it is a policy that silently never
+// fires in a harness whose payload we guessed wrong.
+
+import { CLI } from '../name.mjs';
+import { LOADERS } from '../projection/loaders.mjs';
+import { EVENTS } from './policy.mjs';
+
+/** The seconds a hook is allowed before the harness gives up on it. */
+const TIMEOUT_SECONDS = 10;
+
+/**
+ * The hook's own entry point, as it appears inside every harness's config.
+ *
+ * A repository that has this tool has its binary on PATH, and `--harness` is explicit
+ * rather than detected from the payload: a hook that guessed would answer in the wrong
+ * 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}`;
+}
+
+/** The path a config file lives at, from the reader table rather than a second list. */
+export function hookPath(id) {
+  const row = LOADERS.find((l) => l.id === id);
+  return row?.hooks?.path ?? null;
+}
+
+/** The reader rows that document a hooks file, and the ones that document none. */
+export function hookRows() {
+  return LOADERS.map((l) => ({
+    id: l.id,
+    label: l.label,
+    path: l.hooks?.path ?? null,
+    note: l.hooks ? l.hooks.verified : (l.hooksNote ?? 'no hooks file is documented'),
+  }));
+}
+
+const ADAPTERS = {
+  claude: {
+    id: 'claude',
+    event: 'PreToolUse',
+    matcher: 'Bash|Edit|Write|MultiEdit|NotebookEdit',
+    denyExit: 2,
+    verified: 'docs.claude.com/en/docs/claude-code/hooks, read 2026-10-16',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
+      writes: ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(p.tool_name)
+        ? [p.tool_input?.file_path].filter(Boolean)
+        : [],
+    }),
+    deny: (message) => ({
+      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
+    }),
+  },
+  codex: {
+    id: 'codex',
+    event: 'PreToolUse',
+    matcher: 'Bash|apply_patch',
+    denyExit: 2,
+    verified: 'developers.openai.com/codex/hooks, read 2026-10-16',
+    // Codex is the one harness that will not run a hook until a person has approved the
+    // exact definition, keyed by its hash — so an install that does not say this leaves
+    // the repository with a hook that never fires and no way to tell why.
+    trust: 'Codex skips a hook nobody has trusted: review it with /hooks, or the entry stays inert.',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
+      // apply_patch carries its targets inside the patch text, one header line per file.
+      writes:
+        p.tool_name === 'apply_patch'
+          ? [...String(p.tool_input?.command ?? '').matchAll(/^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm)].map((m) => m[1].trim())
+          : [],
+    }),
+    deny: (message) => ({
+      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
+    }),
+  },
+  cursor: {
+    id: 'cursor',
+    event: 'preToolUse',
+    matcher: 'Shell|Write|Edit',
+    denyExit: 2,
+    verified: 'cursor.com/docs/agent/hooks, read 2026-10-16',
+    root: (p) => p.working_directory ?? p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Shell' ? (p.tool_input?.command ?? null) : null,
+      writes: ['Write', 'Edit'].includes(p.tool_name)
+        ? [p.tool_input?.file_path ?? p.tool_input?.path].filter(Boolean)
+        : [],
+    }),
+    deny: (message) => ({ permission: 'deny', user_message: message, agent_message: message }),
+  },
+  antigravity: {
+    id: 'antigravity',
+    event: 'PreToolUse',
+    matcher: 'run_command|write_to_file|replace_file_content|multi_replace_file_content',
+    // The page documents the decision JSON and not an exit code, so the denial travels
+    // in the JSON only: a non-zero exit whose meaning the vendor has not stated is not
+    // a block, it is a guess that happens to be loud.
+    denyExit: 0,
+    verified: 'antigravity.google/docs/hooks, read 2026-10-16',
+    root: (p) => p.workspacePaths?.[0] ?? p.cwd,
+    extract: (p) => {
+      const call = p.toolCall ?? {};
+      const args = call.args ?? {};
+      return {
+        command: call.name === 'run_command' ? (args.CommandLine ?? null) : null,
+        writes: ['write_to_file', 'replace_file_content', 'multi_replace_file_content'].includes(call.name)
+          ? [args.TargetFile].filter(Boolean)
+          : [],
+      };
+    },
+    deny: (message) => ({ decision: 'deny', reason: message }),
+  },
+};
+
+/** The four adapters, in the order the reader table lists them. */
+export function adapters() {
+  return hookRows()
+    .filter((r) => r.path !== null)
+    .map((r) => ADAPTERS[r.id])
+    .filter(Boolean);
+}
+
+export function adapter(id) {
+  const row = ADAPTERS[id];
+  return row && hookPath(id) !== null ? row : null;
+}
+
+/** The facts a payload carries, and the root it names. An unknown shape yields none. */
+export function factsFrom(row, payload) {
+  return { root: row.root(payload) ?? process.cwd(), ...row.extract(payload ?? {}) };
+}
+
+/** The document to print for a decision, or null when there is nothing to say. */
+export function decisionJson(row, decision) {
+  if (decision.decision !== 'deny') return null;
+  return row.deny(decision.messages.join('\n'));
+}
+
+// ---------------------------------------------------------------------------
+// The config file: reading ours out of somebody else's JSON, and putting it back.
+// ---------------------------------------------------------------------------
+
+/** The name antigravity's document keys its hooks by; its events live under a name. */
+const NAMED_HOOK = 'simt-dev-policies';
+
+/** Where a document keeps its event keys. Antigravity is the odd one: by name. */
+function container(row, config, { create = false } = {}) {
+  if (row.id === 'antigravity') {
+    if (config[NAMED_HOOK] === undefined && create) config[NAMED_HOOK] = {};
+    return config[NAMED_HOOK] ?? null;
+  }
+  // Before `hooks`, so a file this tool creates reads the way the vendor's own example
+  // does rather than with the version key appended wherever it happened to land.
+  if (row.id === 'cursor' && config.version === undefined && create) config.version = 1;
+  if (config.hooks === undefined && create) config.hooks = {};
+  return config.hooks ?? null;
+}
+
+/** The group this tool owns for one event, in that harness's shape. */
+function group(row) {
+  const command = hookCommand(row.id);
+  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
+    // into an absent one, and the whole point of writing it is that it runs.
+    return { command, timeout: TIMEOUT_SECONDS, matcher: row.matcher, failClosed: true };
+  }
+  return { matcher: row.matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+}
+
+/** Whether a group is this tool's, judged by the command it runs and not by position. */
+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];
+  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);
+}
+
+/**
+ * The document with this tool's hook 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.
+ */
+function withHook(row, config) {
+  const box = container(row, config, { create: true });
+  const kept = entries(row, config).filter((e) => !ours(e));
+  box[row.event] = [...kept, group(row)];
+  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' };
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch (e) {
+    return { error: `not valid JSON (${e.message}); left alone` };
+  }
+  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`;
+  return { text, action: text === existing ? 'unchanged' : 'updated' };
+}

package/src/argv.mjs

@@ -51,6 +51,14 @@ export const BOOL_FLAGS = new Set([
   // command whose output changes because something was installed elsewhere is one a
   // reader stops trusting.
   'user',
+  // harness loaders: print the vendor facts (order, caps, imports, hooks and MCP
+  // config) without measuring a repository. The measurement is the other mode; this is
+  // the one that answers "what does this reader do", which does not depend on the repo.
+  'table',
+  // sync: name every line the inferability filter dropped and the evidence behind it
+  // (plan 0003 R09). Off by default because a count is enough to act on; the per-line
+  // detail is what an author needs, and a reader is not an author.
+  'explain',
 ]);
 
 export const VALUE_FLAGS = new Set([
@@ -71,6 +79,27 @@ export const VALUE_FLAGS = new Set([
   // silently applied an unnamed set of rules is the decoration this repository exists
   // to refuse. One is on offer today, so the command rejects any other by name.
   'spec',
+  // harness loaders: which reader to report. A value rather than a boolean because
+  // "--loader" would not say WHICH loader, and a report that silently applied to all
+  // of them would be decoration that misdescribes the artefact.
+  'reader',
+  // harness loaders: measure as if the agent were standing here. The chain rows walk
+  // the project root down to the working directory, so this is what makes them mean
+  // anything beyond the root document.
+  'at',
+  // tokens: split a local Claude Code or Codex session transcript into rules, file
+  // reads and tool output. Local paths only (ADR-075).
+  'session',
+  // bench run / report: arms, harness adapter, model id, repetition count, regrade target and arm comparison.
+  'arm',
+  'harness',
+  'model',
+  'reps',
+  'regrade',
+  'compare',
+  // plan done: the test command that proves the slice. Plan 0003 R31.
+  'test',
+  'state',
 ]);
 
 /**
@@ -86,7 +115,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']);
+export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare']);
 
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
@@ -140,6 +169,12 @@ export function parse(argv) {
           return { ok: false, code: usage(`--${raw} must be a non-negative integer, received ${value}`) };
         }
         flags[camel(raw)] = n;
+      } else if (raw === 'reps') {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1) {
+          return { ok: false, code: usage(`--reps must be a positive integer, received ${value}`) };
+        }
+        flags.reps = n;
       } else {
         const key = camel(raw);
         flags[key] = REPEATABLE_FLAGS.has(raw)