sprag-cli 3.52.0 → 3.54.0

package/src/seed-rules.js

@@ -46,23 +46,25 @@ import {
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-export function seedStatePath() {
-  return join(userDataDir(), 'seed-state.json');
+// Codex answers are kept apart: saying no in one agent must not consume the
+// other agent's offer, and the two agents write to different ratchet files.
+export function seedStatePath({ agent = 'claude' } = {}) {
+  return join(userDataDir(), agent === 'codex' ? 'codex-seed-state.json' : 'seed-state.json');
 }
 
-export function loadSeedState() {
+export function loadSeedState(opts = {}) {
   try {
-    const data = JSON.parse(readFileSync(seedStatePath(), 'utf8'));
+    const data = JSON.parse(readFileSync(seedStatePath(opts), 'utf8'));
     return data && typeof data.decided === 'object' && data.decided ? data : { decided: {} };
   } catch {
     return { decided: {} };
   }
 }
 
-export function saveSeedState(state) {
+export function saveSeedState(state, opts = {}) {
   const dir = userDataDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(seedStatePath(), JSON.stringify(state, null, 2) + '\n');
+  writeFileSync(seedStatePath(opts), JSON.stringify(state, null, 2) + '\n');
 }
 
 /** Bundled tier-delegation presets (empty array when the file is unreadable). */
@@ -80,15 +82,19 @@ export function modelPresets() {
  * ids would renumber the moment a rule is inserted above them, silently moving
  * a user's "no" onto a different rule.
  */
-export function ratchetPresets(lang = userLanguage()) {
-  return presetRuleEntries().map((r) => ({
-    // Hashed from the Korean text in both languages: the id has to survive a
-    // reworded translation, or a user who declined a rule would be asked again
-    // the next time its English copy changes.
-    id: `fix-${createHash('sha1').update(r.ko).digest('hex').slice(0, 6)}`,
-    text: lang === 'ko' ? r.ko : r.en,
-    ko: r.ko,
-  }));
+export function ratchetPresets(lang = userLanguage(), { agent = 'claude' } = {}) {
+  return presetRuleEntries()
+    // A preset without `agents` applies everywhere; one naming Claude model
+    // tiers would only mislead a Codex session.
+    .filter((r) => !r.agents || r.agents.includes(agent))
+    .map((r) => ({
+      // Hashed from the Korean text in both languages: the id has to survive a
+      // reworded translation, or a user who declined a rule would be asked again
+      // the next time its English copy changes.
+      id: `fix-${createHash('sha1').update(r.ko).digest('hex').slice(0, 6)}`,
+      text: lang === 'ko' ? r.ko : r.en,
+      ko: r.ko,
+    }));
 }
 
 const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}(\s*\([^)]*\))?:\s*/, '').trim();
@@ -102,9 +108,11 @@ const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}(\s*\([^)]*\))?:\s*/, '').
  * whose own route-scan already promoted that shape does not need ours, and
  * offering it anyway would read as the tool failing to notice its own state.
  */
-export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() } = {}) {
-  const { decided } = loadSeedState();
-  const registered = (() => {
+export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot(), agent = 'claude' } = {}) {
+  const { decided } = loadSeedState({ agent });
+  // Codex model routing comes from its own measured route-scan candidates;
+  // Claude tier presets name models Codex does not run.
+  const registered = agent === 'codex' ? [] : (() => {
     try {
       return loadModelRules().rules;
     } catch {
@@ -116,12 +124,12 @@ export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() }
   const haveText = new Set();
   for (const scope of ['global', 'project']) {
     try {
-      for (const r of harnessListRules({ root, scope }).rules) haveText.add(stripDate(r.text));
+      for (const r of harnessListRules({ root, scope, agent }).rules) haveText.add(stripDate(r.text));
     } catch { /* a missing ratchet file just means nothing is registered yet */ }
   }
 
   const out = [];
-  for (const p of modelPresets()) {
+  for (const p of agent === 'codex' ? [] : modelPresets()) {
     if (decided[p.id]) continue;
     if (haveModel.has(`${p.tier}|${p.category}`)) continue;
     out.push({
@@ -134,7 +142,7 @@ export function pendingSeeds({ lang = userLanguage(), root = findProjectRoot() }
       preset: p,
     });
   }
-  for (const p of ratchetPresets(lang)) {
+  for (const p of ratchetPresets(lang, { agent })) {
     if (decided[p.id]) continue;
     // Either language counts as already registered: `harness pull` may have
     // written the other one.
@@ -149,10 +157,10 @@ export function findSeed(id, opts = {}) {
   return pendingSeeds(opts).find((s) => s.id === id) || null;
 }
 
-function recordDecision(id, action, extra = {}) {
-  const state = loadSeedState();
+function recordDecision(id, action, extra = {}, { agent = 'claude' } = {}) {
+  const state = loadSeedState({ agent });
   state.decided[id] = { action, at: new Date().toISOString().slice(0, 10), ...extra };
-  saveSeedState(state);
+  saveSeedState(state, { agent });
 }
 
 /**
@@ -162,13 +170,15 @@ function recordDecision(id, action, extra = {}) {
  *
  * Returns { id, kind, scope, path?, rule } or null when the id is not pending.
  */
-export async function acceptSeed(id, { scope = 'global', root = findProjectRoot(), lang = userLanguage() } = {}) {
-  const seed = findSeed(id, { lang, root });
+export async function acceptSeed(id, { scope, root = findProjectRoot(), lang = userLanguage(), agent = 'claude' } = {}) {
+  // No default: a rule in the wrong scope is noise everywhere or missing where it mattered.
+  if (scope !== 'global' && scope !== 'project') throw new Error('acceptSeed needs an explicit scope: global or project');
+  const seed = findSeed(id, { lang, root, agent });
   if (!seed) return null;
 
   if (seed.kind === 'ratchet') {
-    const res = harnessPromote(seed.ruleText, { root, scope });
-    recordDecision(id, 'accepted', { scope });
+    const res = harnessPromote(seed.ruleText, { root, scope, agent });
+    recordDecision(id, 'accepted', { scope }, { agent });
     return { id, kind: 'ratchet', scope, path: res.path, rule: seed.ruleText };
   }
 
@@ -216,15 +226,15 @@ export async function acceptSeed(id, { scope = 'global', root = findProjectRoot(
 export function skipSeed(id, opts = {}) {
   const seed = findSeed(id, opts);
   if (!seed) return null;
-  recordDecision(id, 'skipped');
+  recordDecision(id, 'skipped', {}, { agent: opts.agent });
   return { id, kind: seed.kind, rule: seed.ruleText };
 }
 
 /** Forget every recorded answer — the full set becomes pending again. */
-export function resetSeeds() {
-  const state = loadSeedState();
+export function resetSeeds({ agent = 'claude' } = {}) {
+  const state = loadSeedState({ agent });
   const count = Object.keys(state.decided).length;
-  saveSeedState({ decided: {} });
+  saveSeedState({ decided: {} }, { agent });
   return count;
 }
 
@@ -236,9 +246,23 @@ export function resetSeeds() {
  * asked for, and because a single "register all of these?" question invites a
  * yes to rules the user never read.
  */
-export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot() } = {}) {
-  const pending = pendingSeeds({ lang, root });
+export function seedOfferBlock({ lang = userLanguage(), root = findProjectRoot(), agent = 'claude' } = {}) {
+  const pending = pendingSeeds({ lang, root, agent });
   if (pending.length === 0) return null;
+  if (agent === 'codex') {
+    // Codex hook text stays English; the rule text itself follows the user's language.
+    const cmd = (s) => `${CLI_NAME} seed ${s} --agent codex`;
+    return [
+      `[Sprag seed] ${pending.length} recommended Codex ratchet rule(s) from the bundled presets are not registered yet.`,
+      'Ask in your first reply, after answering any request the user opened with. Offer these choices in this order:',
+      `  1. Register all, globally: ${cmd('accept all --global')}`,
+      `  2. Register all, this project only: ${cmd('accept all --project')}`,
+      '  3. Decide one at a time: ask about each rule below and run its command as soon as they answer',
+      `  4. Register none: ${cmd('skip all')} (never offered again)`,
+      'Always confirm the scope with the user before running an accept command.',
+      ...pending.map((s) => `  [${s.id}] ${s.ruleText}`),
+    ].join('\n');
+  }
   const models = pending.filter((s) => s.kind === 'model');
   const fixes = pending.filter((s) => s.kind === 'ratchet');
   const lines = [];

package/src/session-paths.js

@@ -0,0 +1,242 @@
+/**
+ * session-paths — pull the file paths this session has already looked at out
+ * of its transcript, so a fresh subagent can be pointed at them instead of
+ * re-discovering them by exploring from scratch.
+ *
+ * Only the transcript TAIL is read: this runs from a PreToolUse hook on every
+ * Task/Agent call, so the whole file must not be parsed each time. Older tool
+ * calls fall out of the window, which is acceptable — the point is "recently
+ * touched", not "ever touched".
+ *
+ * The window is sized by measurement, not by brief.js's 256KiB convention. A
+ * transcript's bytes are dominated by tool RESULTS (file contents, command
+ * output, base64 images) while the tool_use records this reads are a few
+ * hundred bytes each, so a byte window is far shallower than it looks: on a
+ * real 4.65MB session it held 28 lines, 1.9% of the session, and recovered 0
+ * of the 8 path-bearing calls that session had made. At 1MB the same
+ * transcript gave back 4; the read cost 3.3ms against this hook's 10s
+ * timeout. See TAIL_BYTES below for why the default sits higher still.
+ */
+
+import { existsSync, statSync, realpathSync, openSync, readSync, closeSync } from 'node:fs';
+import { isAbsolute, resolve, relative, sep } from 'node:path';
+
+// Tools whose argument names a file directly, each with the key it uses. The
+// key is spelled out per tool rather than assumed: NotebookEdit takes
+// `notebook_path`, so reading `file_path` from every one of these silently
+// collected nothing from notebook edits while the docs listed the tool as
+// supported. MultiEdit belongs here for the same reason korean-lint's matcher
+// (`Write|Edit|MultiEdit|Bash`) counts it as a writing tool.
+//
+// Bash is left out on purpose: its `command` string is free text, not a path
+// field, and scraping it for paths would be a much noisier feature than this.
+const FILE_PATH_ARG = {
+  Read: 'file_path',
+  Edit: 'file_path',
+  MultiEdit: 'file_path',
+  Write: 'file_path',
+  NotebookEdit: 'notebook_path',
+};
+const PATH_ARG_TOOLS = new Set(['Grep', 'Glob']);
+
+/**
+ * How far back to read. 4MB costs 11.5ms on the measured session — nothing
+ * against the hook's 10s timeout — and buys margin that 1MB does not: a single
+ * transcript line can be 240KB when a session reads an image, so four such
+ * reads would exhaust a 1MB window inside one turn and empty this section
+ * again. The ceiling also bounds the buffer this allocates per delegation.
+ */
+const TAIL_BYTES = 4 * 1024 * 1024;
+
+/**
+ * A path that exists, is a file, and still resolves inside `root`.
+ *
+ * The containment test in the loop compares strings, and statSync follows
+ * symlinks, so a link that sits inside root while pointing outside it passed
+ * both. No new access is opened — every path here is one the parent session
+ * already read — but a function that goes as far as rejecting control
+ * characters in a filename should not be the loose one about links.
+ */
+function isRegularFileInside(abs, realRoot) {
+  try {
+    if (!statSync(abs).isFile()) return false;
+    // Both sides resolved: comparing a resolved path against an unresolved root
+    // rejects everything whenever the root itself sits behind a link, which is
+    // the normal case for a macOS temp directory (/tmp -> /private/tmp) and so
+    // for this project's own tests.
+    const real = relative(realRoot, realpathSync(abs));
+    return real !== '' && real !== '..' && !real.startsWith('..' + sep) && !isAbsolute(real);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recently-touched file paths for this session, most-recent-first, restricted
+ * to `root` and returned relative to it.
+ *
+ * Every failure mode — missing transcript, unreadable file, malformed JSON —
+ * collapses to an empty array rather than throwing, because this feeds a
+ * PreToolUse hook: one bad transcript line must not block the delegation it
+ * was only trying to make cheaper.
+ */
+export function recentToolPaths(transcriptPath, { root, limit = 15, tailBytes = TAIL_BYTES } = {}) {
+  try {
+    if (!transcriptPath || !existsSync(transcriptPath)) return [];
+    // Paths are reported relative to root, so without one there is nothing
+    // meaningful to return. resolve() would throw on undefined and the outer
+    // catch would hide that as an empty result, so say it here instead.
+    if (typeof root !== 'string' || root === '') return [];
+
+    const size = statSync(transcriptPath).size;
+    const start = Math.max(0, size - tailBytes);
+    // One byte of lookbehind, so the shift() below is right in both cases. When
+    // `start` happens to land just past a newline, the first line in the window
+    // is a whole record and dropping it lost one for nothing. Reading from the
+    // byte before means that case decodes with a leading '\n', whose split
+    // produces an empty first element — so the same unconditional shift()
+    // removes an empty string there and a genuine fragment otherwise.
+    const readFrom = start > 0 ? start - 1 : 0;
+    // allocUnsafe, not alloc: the read loop below overwrites what it uses and
+    // only buf.subarray(0, bytesRead) is ever decoded, so the untouched
+    // remainder never leaves this function. This saves zeroing 4MB per
+    // delegation, which is worth taking but is not where the cost of this
+    // function is — decoding the window to a string and splitting it allocates
+    // several times more. Cutting that means walking the buffer backwards by
+    // newline and decoding only the lines needed to reach `limit`, which is
+    // the change to make if the window is ever widened again.
+    const buf = Buffer.allocUnsafe(size - readFrom);
+    let fd;
+    let bytesRead = 0;
+    try {
+      fd = openSync(transcriptPath, 'r');
+      // One readSync is not promised to fill the whole request — a short read
+      // is common on some filesystems even mid-file — and the part it leaves
+      // unread here is the tail end of the buffer, which is the most recent
+      // slice of the transcript and exactly what this feature is trying to
+      // recover. Looping until the buffer is full (or the file runs out)
+      // keeps that slice from being silently dropped.
+      while (bytesRead < buf.length) {
+        const n = readSync(fd, buf, bytesRead, buf.length - bytesRead, readFrom + bytesRead);
+        if (n === 0) break;
+        bytesRead += n;
+      }
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+
+    // Only what was actually read. A transcript is still being written while
+    // this runs, so between statSync and openSync the file may have been
+    // truncated or rotated, which ends the loop above early (n === 0) with
+    // bytesRead short of the buffer. Decoding the untouched remainder would
+    // turn the last record into NUL bytes and lose the newest path to a
+    // parse error.
+    const lines = buf.subarray(0, bytesRead).toString('utf8').split('\n');
+    // A tail that began mid-file leaves the first line either a truncated
+    // record or, thanks to the lookbehind byte above, an empty string. Either
+    // way it goes. When the read started at byte 0 the file was smaller than
+    // the window and that line is whole, so keeping it costs nothing and
+    // dropping it would lose the only record a short transcript has.
+    if (start > 0) lines.shift();
+
+    // Resolved once, not per path: only the stat'ed candidates need it, and the
+    // root does not change between them. Falls back to the given root when it
+    // cannot be resolved, which keeps a missing directory from emptying the
+    // whole list.
+    let realRoot = root;
+    try {
+      realRoot = realpathSync(root);
+    } catch {
+      // keep root as given
+    }
+
+    // Chronological order first (oldest touched path to newest); reversed
+    // and deduped below so the most recent occurrence of each path wins.
+    const touched = [];
+    for (const line of lines) {
+      // Cheap prefilter before the JSON.parse cost, same trick brief.js uses
+      // for `"usage"` — most lines in a transcript are not tool_use blocks.
+      if (!line.includes('"tool_use"')) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const content = entry?.message?.content;
+      if (!Array.isArray(content)) continue;
+
+      for (const block of content) {
+        if (!block || block.type !== 'tool_use') continue;
+        const input = block.input;
+        if (!input || typeof input !== 'object') continue;
+
+        let rawPath = null;
+        // Grep and Glob are the two whose argument is a directory as often as
+        // a file, so what they contribute has to be confirmed before it is
+        // offered as something to read. Read/Edit/Write name a file by
+        // contract.
+        let mayBeDirectory = false;
+        const argKey = FILE_PATH_ARG[block.name];
+        if (argKey) rawPath = input[argKey];
+        else if (PATH_ARG_TOOLS.has(block.name)) {
+          rawPath = input.path;
+          mayBeDirectory = true;
+        }
+        if (typeof rawPath !== 'string' || rawPath === '') continue;
+        // A POSIX filename may hold any byte but `/` and NUL, and this list is
+        // rendered one path per line straight into the prompt of a subagent
+        // that has tool permissions. So a filename carrying a newline plus a
+        // sentence would leave the "already read these" section and arrive as
+        // its own instruction. Filenames are outside input whenever the
+        // session is working in a repository it did not write, which makes
+        // this a boundary rather than a curiosity.
+        //
+        // The class covers more than C0 and DEL, because more than those end a
+        // line: U+2028 and U+2029 are Unicode's own line and paragraph
+        // separators and U+0085 is NEL, and a renderer may break on any of
+        // them. The backtick is here for a different reason — the section wraps
+        // each path in one, so a name containing a backtick closes that span
+        // early and returns the rest of the line to prose. Both are cheaper to
+        // reject while collecting than to escape while rendering.
+        if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029`]/.test(rawPath)) continue;
+        // The free half of the directory test; the stat below covers the rest.
+        if (rawPath.endsWith('/') || rawPath.endsWith(sep)) continue;
+
+        const abs = isAbsolute(rawPath) ? rawPath : resolve(root, rawPath);
+        const rel = relative(root, abs);
+        // Outside root: relative() climbs out as ".." alone or ".." followed by
+        // a separator, or (on a different Windows drive) returns an
+        // already-absolute path. The separator has to be part of the test —
+        // without it a directory legitimately named `..fixtures` or `..cache`
+        // read as an escape and everything under it vanished from the list with
+        // no signal anywhere.
+        if (rel === '' || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) continue;
+
+        touched.push({ rel, mayBeDirectory });
+      }
+    }
+
+    const deduped = [];
+    const seen = new Set();
+    for (let i = touched.length - 1; i >= 0 && deduped.length < limit; i--) {
+      const { rel: p, mayBeDirectory } = touched[i];
+      if (seen.has(p)) continue;
+      seen.add(p);
+      // `Grep({ path: 'src' })` names a directory without a trailing
+      // separator, and the section this feeds says the session "already read
+      // these" — so a directory listed there invites a subagent to Read it and
+      // spend one of its capped tool calls on the failure. The same reasoning
+      // already guards the ratchet pointer in delegation-guard.js.
+      //
+      // This is the one place a syscall is worth it. It runs after dedupe and
+      // stops at `limit`, so at most 15 stats happen per delegation against an
+      // 11.5ms read, and only for the two tools that can name a directory.
+      if (mayBeDirectory && !isRegularFileInside(resolve(root, p), realRoot)) continue;
+      deduped.push(p);
+    }
+    return deduped;
+  } catch {
+    return [];
+  }
+}

package/src/update-check.js

@@ -266,16 +266,51 @@ export function releaseHighlights(body, lang = 'en') {
   return out;
 }
 
+/**
+ * The releases endpoint for one version, or a throw.
+ *
+ * The version that arrives here came out of a registry response rather than out
+ * of this process, so it is checked rather than trusted: a value carrying a
+ * slash or a scheme would otherwise have a say in which URL this function
+ * requests. Two checks are needed, because either one alone leaves a gap. The
+ * shape test rejects anything that is not a version, and the prefix test runs
+ * against the parsed URL rather than against the string it was built from,
+ * because `new URL` has collapsed `../` segments by that point and the same
+ * test on the raw string would pass a value that walks back out of the path.
+ * The origin is a constant either way, so no input can move the request to
+ * another host; this states that guarantee in code instead of leaving it
+ * implied.
+ */
+function releaseTagUrl(version) {
+  const tag = String(version);
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(tag)) {
+    throw new Error(`refusing to request notes for ${JSON.stringify(tag)}: not a version`);
+  }
+  const url = new URL(`${RELEASES_API}/v${tag}`);
+  if (!url.href.startsWith(`${RELEASES_API}/`)) {
+    throw new Error(`refusing to request ${url.href}: outside ${RELEASES_API}`);
+  }
+  return url;
+}
+
 /**
  * Fetch the highlights for one version. Returns [] on any failure: the notice
  * is worth showing with a bare version number, so a missing release, a rate
- * limit, or an offline machine must not cost the user the notice itself.
+ * limit, or an offline machine must not cost the user the notice itself. A
+ * version that fails the endpoint check above lands in that same place: no
+ * highlights, and the notice still goes out.
  */
 export async function fetchHighlights(version, { timeoutMs = FETCH_TIMEOUT_MS, lang = 'en' } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${RELEASES_API}/v${version}`, {
+    const endpoint = releaseTagUrl(version);
+    // The URL is this module's own constant plus a checked version. The
+    // scanner's node_ssrf heuristic reads any two-argument function as an HTTP
+    // handler and its first argument as request input, which is what it matched
+    // on here; this module serves nothing and has no request to read.
+    // nosemgrep: rules.lgpl.nodejs_scan.javascript-ssrf-rule-node_ssrf
+    const res = await fetch(endpoint, {
       signal: controller.signal,
       headers: { accept: 'application/vnd.github+json' },
     });