@xhulz/nina 0.70.0 → 0.71.0

package/src/cost.mjs

@@ -11,11 +11,19 @@
  *
  * It reads only what the run's transcript gained since its last call, keeps counts per message and
  * nothing else, under the project's gate directory, and lets every call through if anything goes wrong.
+ *
+ * Two things a run pays for on every turn after are settled at the call itself. A shell command's long
+ * output stays in the context and is re-read on every turn — outputs longer than a screen were a fifth of
+ * what two projects' stages re-read — so past `clipAt` characters it goes to a file beside the ones Claude
+ * Code keeps for the session, and the run sees its first and last lines and where the rest is. And a call
+ * that ran past the five minutes a subagent's cache lives makes the next turn write the whole context again,
+ * at twelve times a read's price — a quarter of what one project's stages spent — so the run is told then.
  */
 
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { projectGateDir } from './gate.mjs';
+import { CLIP_MARK } from './transcripts.mjs';
 
 /** Where a run's counts are kept between calls, one file per agent. */
 const stateDir = (root) => join(projectGateDir(root), 'cost');
@@ -45,18 +53,168 @@ function gained(path, from) {
   return { text: buffer.subarray(0, end + 1).toString('utf8'), to: from + end + 1 };
 }
 
+/** How long a subagent's prompt cache lives without a turn: a call that runs past it is paid for again in full. */
+const CACHE_MS = 5 * 60_000;
+
+/**
+ * Whether a shell command reads a file or a diff rather than producing output: what it prints is what the
+ * run asked to read, so clipping it would only send the run to read the file it was cut to. What a command
+ * line prints last is its last command's, and of a pipe its last stage's, so that is the one judged:
+ * `sed -i … && node run` produces output, and `cd p && cat f` or `node run && tail -n 50 log` reads.
+ *
+ * @param {unknown} command - The Bash call's command.
+ * @returns {boolean}
+ */
+export function readsByShell(command) {
+  if (typeof command !== 'string') return false;
+  // Read as words, never by a pattern that backtracks: the command is the model's, of any length.
+  const assignment = (word) => /^\w+=/.test(word);
+  // A subshell's parentheses are not part of the words they hold.
+  const unwrap = (word) => {
+    let from = 0;
+    let to = word.length;
+    while (from < to && word[from] === '(') from += 1;
+    while (to > from && word[to - 1] === ')') to -= 1;
+    return word.slice(from, to);
+  };
+  const segments = command
+    .split(/&&|\|\||;|\n/)
+    .map((segment) => segment.split(/\s+/).map(unwrap).filter(Boolean))
+    // A segment of assignments alone prints nothing.
+    .filter((words) => words.length && !words.every(assignment));
+  const piped = (segments.at(-1) ?? []).join(' ').split('|').at(-1);
+  const words = piped.split(/\s+/).filter(Boolean);
+  // Less what runs a command rather than being it: assignments, `export NAME=…`, `timeout N`, `nice`, `command`.
+  let i = 0;
+  while (i < words.length) {
+    if (assignment(words[i]) || words[i] === 'nice' || words[i] === 'command') i += 1;
+    else if ((words[i] === 'export' && assignment(words[i + 1] ?? '')) || (words[i] === 'timeout' && words[i + 1])) i += 2;
+    else break;
+  }
+  if (['cat', 'sed', 'head', 'tail', 'nl', 'awk', 'less', 'more'].includes(words[i])) return true;
+  if (words[i] !== 'git') return false;
+  // `git diff` and `git show`, past the options that come before a subcommand.
+  i += 1;
+  while (words[i] === '--no-pager' || words[i] === '-C' || words[i] === '-c') i += words[i] === '--no-pager' ? 1 : 2;
+  return words[i] === 'diff' || words[i] === 'show';
+}
+
+/**
+ * The first lines of a text up to a size, or its last ones; a single line longer than the size is cut.
+ *
+ * @param {string} text - The output.
+ * @param {number} size - Characters at most.
+ * @param {boolean} fromEnd - The last lines rather than the first.
+ * @returns {string}
+ */
+function lines(text, size, fromEnd) {
+  const all = text.split('\n');
+  const kept = [];
+  let length = 0;
+  for (const line of fromEnd ? all.reverse() : all) {
+    if (length + line.length + 1 > size) break;
+    kept.push(line);
+    length += line.length + 1;
+  }
+  if (kept.length === 0) return fromEnd ? text.slice(-size) : text.slice(0, size);
+  return (fromEnd ? kept.reverse() : kept).join('\n');
+}
+
+/**
+ * A long Bash output clipped: the whole of it written to a file in the session's `tool-results` directory,
+ * where Claude Code keeps the outputs it moves out itself and a stage may read, and in its place the first
+ * lines, the last ones — where a test runner or a battery prints its summary — and where the rest is.
+ * Null when the output is short, the command reads a file, or the file cannot be written: the run then sees
+ * the output as it was.
+ *
+ * @param {object} input - The PostToolUse hook's input.
+ * @param {number} clipAt - The characters past which an output is clipped; 0 clips nothing.
+ * @returns {{updatedToolOutput: object, chars: number}|null}
+ */
+export function clipOutput(input, clipAt) {
+  const response = input?.tool_response;
+  if (input?.tool_name !== 'Bash' || !(clipAt > 0) || response === null || typeof response !== 'object' || typeof response.stdout !== 'string') return null;
+  const stderr = typeof response.stderr === 'string' ? response.stderr : '';
+  const chars = response.stdout.length + stderr.length;
+  if (chars <= clipAt || response.isImage || readsByShell(input.tool_input?.command)) return null;
+  const id = /^[A-Za-z0-9_-]{1,80}$/.test(String(input.tool_use_id ?? '')) ? input.tool_use_id : `${Date.now()}`;
+  const file = join(dirname(input.transcript_path), input.session_id, 'tool-results', `nina-${id}.txt`);
+  const whole = stderr ? `${response.stdout}\n--- stderr ---\n${stderr}` : response.stdout;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, whole);
+  } catch {
+    return null;
+  }
+  const said =
+    `${CLIP_MARK}: ${whole.split('\n').length.toLocaleString('en-US')} lines and ${chars.toLocaleString('en-US')} characters, of which the first and last lines are shown. ` +
+    `The whole of it${stderr ? ', stderr after stdout,' : ''} is in ${file} — grep it, or read the range you need: read whole, it all comes back into your context and is re-read on every turn after.]`;
+  // A stdout short enough to show whole is shown once, the notice after it: only what is long is cut.
+  const head = Math.round(clipAt / 8);
+  const tail = Math.round((clipAt * 3) / 8);
+  const stdout = response.stdout.length > head + tail ? `${lines(response.stdout, head, false)}\n…\n${said}\n…\n${lines(response.stdout, tail, true)}` : `${response.stdout}\n${said}`;
+  return {
+    chars,
+    updatedToolOutput: { ...response, stdout, stderr: stderr ? lines(stderr, head, true) : stderr },
+  };
+}
+
 /**
  * What one call of the watch says, or null: the counts are brought up to date from the run's transcript,
  * and a warning is due each time the total re-read crosses `warnAt`, then twice it, four times it, and on.
+ * A long Bash output is clipped to a file ({@link clipOutput}), and a call that outlived the cache is named.
  *
  * @param {object} input - The PostToolUse hook's input.
- * @param {{root: string, warnAt: number, now?: number}} options
+ * @param {{root: string, warnAt: number, clipAt?: number, now?: number}} options
  * @returns {object|null} The hook's answer.
  */
-export function watch(input, { root, warnAt, now = Date.now() }) {
+export function watch(input, { root, warnAt, clipAt = 0, now = Date.now() }) {
   // Only inside a subagent, which is where `agent_id` is set; and an id that could not be a file name is not one.
   if (input?.hook_event_name !== 'PostToolUse' || !/^[A-Za-z0-9_-]{1,64}$/.test(String(input.agent_id ?? ''))) return null;
-  if (typeof input.transcript_path !== 'string' || typeof input.session_id !== 'string' || !(warnAt > 0)) return null;
+  // The session's id becomes a directory name below, in the clip's path and the transcript's.
+  if (typeof input.transcript_path !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(String(input.session_id ?? ''))) return null;
+  const clipped = clipOutput(input, clipAt);
+  const counted = warnAt > 0 ? count(input, { root, warnAt, now }) : null;
+  const ran = typeof input.duration_ms === 'number' && input.duration_ms > CACHE_MS ? input.duration_ms : null;
+  if (!clipped && !counted?.due && ran === null) return null;
+  const size = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : `${Math.round(n / 1000)}k`);
+  const context = [];
+  const person = [];
+  if (counted?.due) {
+    context.push(
+      `NINA cost watch: this run has re-read ${counted.total} tokens of its own context${counted.turn}; every further turn costs more than the last. ` +
+        'If what is left is more than one run should carry, stop where your work is whole, hand back what you have, and name what is left, so the orchestrator can send it as its own step. Otherwise finish without widening the work.',
+    );
+    person.push(`${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} has re-read ${counted.total} tokens of its own context${counted.turn}.`);
+  }
+  if (ran !== null) {
+    const minutes = Math.round(ran / 60_000);
+    const whole = counted?.context ? `, about ${size(counted.context)} tokens,` : '';
+    context.push(
+      `NINA cost watch: that call ran ${minutes} minutes, past the five your context stays cached between turns, so your next turn writes all of it${whole} again — at twelve times what re-reading it costs. ` +
+        'Wait in calls that each end within three minutes: run the rest in shares, or start it in the background and check on it no more often than every three minutes (Hard Rule #19).',
+    );
+    person.push(`${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} waited ${minutes} min in one call; its next turn writes its whole context again.`);
+  }
+  return {
+    ...(person.length ? { systemMessage: `NINA: ${person.join(' ')}` } : {}),
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      ...(context.length ? { additionalContext: context.join('\n\n') } : {}),
+      ...(clipped ? { updatedToolOutput: clipped.updatedToolOutput } : {}),
+    },
+  };
+}
+
+/**
+ * The run's re-read brought up to date from its transcript, and whether a warning is due; null when the
+ * transcript is not there.
+ *
+ * @param {object} input - The PostToolUse hook's input.
+ * @param {{root: string, warnAt: number, now: number}} options
+ * @returns {{due: boolean, total: string, turn: string, context: number|null}|null}
+ */
+function count(input, { root, warnAt, now }) {
   const transcript = join(dirname(input.transcript_path), input.session_id, 'subagents', `agent-${input.agent_id}.jsonl`);
   if (!existsSync(transcript)) return null;
   const dir = stateDir(root);
@@ -69,6 +227,7 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
   }
   const { text, to } = gained(transcript, state.offset);
   let last = null;
+  const n = (v) => (typeof v === 'number' ? v : 0);
   for (const line of text.split('\n')) {
     if (!line.includes('"cache_read_input_tokens"')) continue;
     try {
@@ -78,6 +237,8 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
       if (message?.id && typeof read === 'number') {
         state.read[message.id] = read;
         last = read;
+        // The whole context that turn held, which a turn after an expired cache writes again.
+        state.context = read + n(message.usage.cache_creation_input_tokens) + n(message.usage.input_tokens);
       }
     } catch {
       // A torn line loses one message's count.
@@ -92,18 +253,12 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
   state.warned = crossed;
   mkdirSync(dir, { recursive: true });
   writeFileSync(file, JSON.stringify(state));
-  if (!due) return null;
-  const m = (n) => `${Math.round(n / 1e6)}M`;
-  const size = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : `${Math.round(n / 1000)}k`);
-  const turn = last === null ? '' : `, and each turn now re-reads about ${size(last)} tokens more`;
+  const size = (v) => (v >= 1e6 ? `${(v / 1e6).toFixed(1)}M` : `${Math.round(v / 1000)}k`);
   return {
-    systemMessage: `NINA: ${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} has re-read ${m(total)} tokens of its own context${turn}.`,
-    hookSpecificOutput: {
-      hookEventName: 'PostToolUse',
-      additionalContext:
-        `NINA cost watch: this run has re-read ${m(total)} tokens of its own context${turn}; every further turn costs more than the last. ` +
-        'If what is left is more than one run should carry, stop where your work is whole, hand back what you have, and name what is left, so the orchestrator can send it as its own step. Otherwise finish without widening the work.',
-    },
+    due,
+    total: `${Math.round(total / 1e6)}M`,
+    turn: last === null ? '' : `, and each turn now re-reads about ${size(last)} tokens more`,
+    context: typeof state.context === 'number' ? state.context : null,
   };
 }
 
@@ -120,18 +275,18 @@ function prune(root, now) {
 }
 
 /**
- * The hook: reads the event from stdin, answers on stdout when a warning is due, and exits 0 whatever
- * happens — a hook that fails must not stop the run it watches.
+ * The hook: reads the event from stdin, answers on stdout when a warning is due or an output is clipped,
+ * and exits 0 whatever happens — a hook that fails must not stop the run it watches.
  *
- * @param {{root: string, warnAt: number, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream}} options
+ * @param {{root: string, warnAt: number, clipAt?: number, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream}} options
  * @returns {Promise<number>}
  */
-export async function runCostWatch({ root, warnAt, stdin = process.stdin, stdout = process.stdout }) {
+export async function runCostWatch({ root, warnAt, clipAt = 0, stdin = process.stdin, stdout = process.stdout }) {
   try {
     const chunks = [];
     for await (const chunk of stdin) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
     const now = Date.now();
-    const answer = watch(JSON.parse(Buffer.concat(chunks).toString('utf8')), { root, warnAt, now });
+    const answer = watch(JSON.parse(Buffer.concat(chunks).toString('utf8')), { root, warnAt, clipAt, now });
     if (answer) stdout.write(`${JSON.stringify(answer)}\n`);
     if (Math.random() < 0.01) prune(root, now);
   } catch {

package/src/dashboard.html

@@ -362,7 +362,9 @@ const RENDER = {
         table(['stage', 'runs', 'median', 'total', 'share', ''], d.cost.rows.map((r) => [el('span', { class: 'role' }, r.role), String(r.runs), money(r.median), money(r.total), pct(r.total, d.cost.total), bar([[r.total / d.cost.total, 'var(--pink)']])]), [1, 2, 3, 4]),
         d.cost.unpriced ? el('p', { class: 'note faint' }, `${d.cost.unpriced} run(s) on a model the price table does not know.`) : null] : null,
       d.context ? [el('h3', {}, 'context · every turn re-reads it all'),
-        table(['stage', 'rounds', 'n', 'turns', 'calls/turn', 'starts at', 'peak', 'prompt'], d.context.rows.map((r, i, all) => [i > 0 && all[i - 1].role === r.role ? '' : el('span', { class: 'role' }, r.role), el('span', { class: 'faint' }, r.label), String(r.n), String(r.turns), r.callsPerTurn.toFixed(2), kTokens(r.start), kTokens(r.peak), r.prompt === null ? '—' : r.prompt.toLocaleString('en-US')]), [2, 3, 4, 5, 6, 7])] : null,
+        table(['stage', 'rounds', 'n', 'turns', 'calls/turn', 'starts at', 'peak', 'prompt'], d.context.rows.map((r, i, all) => [i > 0 && all[i - 1].role === r.role ? '' : el('span', { class: 'role' }, r.role), el('span', { class: 'faint' }, r.label), String(r.n), String(r.turns), r.callsPerTurn.toFixed(2), kTokens(r.start), kTokens(r.peak), r.prompt === null ? '—' : r.prompt.toLocaleString('en-US')]), [2, 3, 4, 5, 6, 7]),
+        d.context.reread?.length ? el('h3', {}, 'what the turns re-read') : null,
+        d.context.reread?.length ? table(['stage', 'rounds', 'opened with', 'rewrites', 'of spend', 'clipped'], d.context.reread.map((r) => [el('span', { class: 'role' }, r.role), String(r.n), r.fixed === null ? '—' : `${Math.round(r.fixed * 100)}%`, String(r.rewrites), r.rewriteShare === null ? '—' : `${Math.round(r.rewriteShare * 100)}%`, String(r.clipped)]), [1, 2, 3, 4, 5]) : null] : null,
       d.proportion ? [el('h3', {}, 'proportion · the size of a change against its chain'),
         table(['largest write', 'cycles', 'with a planner or architect', ''], d.proportion.rows.map((r) => [r.label, String(r.cycles), r.cycles ? `${r.designed} (${pct(r.designed, r.cycles)})` : '—', bar([[r.cycles ? r.designed / r.cycles : 0, 'var(--pink)']])]), [1, 2]),
         d.proportion.over ? el('p', { class: 'note warn' }, `${d.proportion.over.count} implementer round(s) wrote more files than one step may (${d.proportion.over.limit}); the largest wrote ${d.proportion.over.largest}.`) : null,

package/src/langfuse.mjs

@@ -112,8 +112,11 @@ export function contextMode(setting) {
   return setting?.content === 'prompts' ? 'prompts' : setting?.content ? 'full' : null;
 }
 
-/** A round's shape, as metadata on its root: how many turns and calls it took, and how large its context and prompt were. */
-const SHAPE = ['turns', 'tool_calls', 'context_start', 'context_peak', 'prompt_chars'];
+/**
+ * A round's shape, as metadata on its root: how many turns and calls it took, how large its context and prompt
+ * were, how often it wrote an expired cache again and how much, and how many outputs the cost watch clipped.
+ */
+const SHAPE = ['turns', 'tool_calls', 'context_start', 'context_peak', 'prompt_chars', 'cache_rewrites', 'cache_rewritten', 'clipped'];
 
 /**
  * The OTLP span at the root of a dispatch's trace. Without its context, a run that spent tokens is a

package/src/transcripts.mjs

@@ -860,7 +860,7 @@ async function attachAgentDetail(projectDir, dispatches) {
       if (
         run.agent_read_bytes === size &&
         !('resumes' in run) &&
-        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'lines_written' in r && 'shell_writes' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r)
+        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'lines_written' in r && 'shell_writes' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r && 'cache_rewrites' in r && 'clipped' in r)
       ) {
         continue;
       }
@@ -899,6 +899,8 @@ async function attachAgentDetail(projectDir, dispatches) {
         calls: new Set(),
         /** How long the prompt that opened the round was, in characters; never the prompt. */
         promptChars: null,
+        /** The tool results the cost watch clipped to a file, so they were never re-read whole. */
+        clipped: 0,
       });
       const rounds = [fresh()];
       const roundOf = roundsOf();
@@ -942,6 +944,19 @@ async function attachAgentDetail(projectDir, dispatches) {
             // A torn line loses one edit, not the run's.
           }
         }
+        if (line.includes(CLIP_MARK) && line.includes('"tool_result"')) {
+          try {
+            const row = JSON.parse(line);
+            const content = row?.type === 'user' ? row.message?.content : null;
+            for (const block of Array.isArray(content) ? content : []) {
+              const said = block?.type === 'tool_result' ? block.content : null;
+              const text = typeof said === 'string' ? said : Array.isArray(said) ? said.map((x) => x?.text ?? '').join('') : '';
+              if (text.includes(CLIP_MARK)) round.clipped += 1;
+            }
+          } catch {
+            // A torn line loses one count.
+          }
+        }
         if (line.includes('"name":"Bash"')) {
           try {
             for (const block of JSON.parse(line)?.message?.content ?? []) {
@@ -1028,6 +1043,9 @@ async function attachAgentDetail(projectDir, dispatches) {
           record.tool_calls = round.calls.size;
           record.context_start = shape.start;
           record.context_peak = shape.peak;
+          record.cache_rewrites = shape.rewrites;
+          record.cache_rewritten = shape.rewritten;
+          record.clipped = round.clipped;
           record.prompt_chars = round.promptChars;
           record.usage_model = spent.model;
           record.effort = spent.effort;
@@ -1078,20 +1096,40 @@ export function promptOf(row, round) {
   return row?.type === 'user' && (round > 1 || !row.isMeta) && typeof content === 'string' ? content : null;
 }
 
+/** The smallest context whose loss counts as a rewrite: below it, a turn writing most of it is the round beginning. */
+const REWRITE_FLOOR = 30_000;
+
 /**
- * How a round spent its context: how many turns it took, and how large the context each turn re-read was
- * when the round began and at its largest. Every turn is billed the whole context again, so a round that
- * begins where a long one ended — a run resumed for a fix — pays for everything before it on each turn.
+ * How a round spent its context: how many turns it took, how large the context each turn re-read was
+ * when the round began and at its largest, and how often its cache had expired. Every turn is billed the
+ * whole context again, so a round that begins where a long one ended — a run resumed for a fix — pays for
+ * everything before it on each turn.
+ *
+ * A turn reads its context from the cache only while the cache is alive — five minutes after the turn
+ * before, for a subagent — and past that writes all of it again, at twelve times a read's price. So a turn
+ * that wrote more than half of a context of at least {@link REWRITE_FLOOR} tokens is counted a rewrite.
  *
  * @param {Map<string, {usage: object}>} usage - Message id → its final usage, in the order the round sent them.
- * @returns {{turns: number, start: number|null, peak: number|null}} Context sizes in tokens.
+ * @returns {{turns: number, start: number|null, peak: number|null, rewrites: number, rewritten: number}} Context sizes in tokens.
  */
 export function contextOf(usage) {
   const n = (v) => (typeof v === 'number' ? v : 0);
-  const sizes = [...usage.values()].map(({ usage: u }) => n(u.input_tokens) + n(u.cache_read_input_tokens) + n(u.cache_creation_input_tokens));
-  return { turns: sizes.length, start: sizes[0] ?? null, peak: sizes.length > 0 ? Math.max(...sizes) : null };
+  const turns = [...usage.values()].map(({ usage: u }) => ({ size: n(u.input_tokens) + n(u.cache_read_input_tokens) + n(u.cache_creation_input_tokens), written: n(u.cache_creation_input_tokens) }));
+  const sizes = turns.map((t) => t.size);
+  let rewrites = 0;
+  let rewritten = 0;
+  for (let i = 1; i < turns.length; i += 1) {
+    if (sizes[i - 1] >= REWRITE_FLOOR && turns[i].written > sizes[i - 1] / 2) {
+      rewrites += 1;
+      rewritten += turns[i].written;
+    }
+  }
+  return { turns: sizes.length, start: sizes[0] ?? null, peak: sizes.length > 0 ? Math.max(...sizes) : null, rewrites, rewritten };
 }
 
+/** How the cost watch opens an output it clipped (`src/cost.mjs`), which is how a snapshot counts them. */
+export const CLIP_MARK = '[NINA clipped this output';
+
 /**
  * What a run spent, from each of its messages' final usage: tokens by kind, and the model and effort
  * level that most of its messages ran at. Metadata — counts, a model id and a level, never a message.

package/src/wiring.mjs

@@ -146,6 +146,23 @@ const HOOKS = [
 /** Where a project's hooks can live: Claude Code reads both, so a hook kept in the local file counts. */
 const SETTINGS_FILES = ['.claude/settings.json', '.claude/settings.local.json'];
 
+/**
+ * Settings a project's `.claude/settings.json` carries beside its hooks, each shipped with the script whose
+ * concern it is. `why` is what `check` says when one is missing. A key the owner already wrote, in either
+ * settings file and with whatever value, is theirs: `wire` adds a missing one and never changes one.
+ *
+ * The skill listing is every installed skill's description, sized at a hundredth of the model's context
+ * window, and every stage whose tools include `Skill` re-reads it on every turn: 32k characters in two
+ * projects, a twentieth of what their stages re-read. The skills a stage must use are named in its spec,
+ * and every skill's name stays listed however small the budget, so the descriptions buy a stage nothing.
+ */
+const SETTINGS = [
+  {
+    key: 'skillListingBudgetFraction', value: 0.001, script: COST,
+    why: "every stage that may invoke a skill re-reads every installed skill's description on every turn, about 9k tokens",
+  },
+];
+
 /** The scripts some hook runs — `check` asks for these by hook, not by npm script. */
 export const HOOK_SCRIPTS = new Set(HOOKS.map((h) => h.script));
 
@@ -252,11 +269,13 @@ function covered(hooks, h) {
  *
  * @param {string} target - The project directory.
  * @param {(event: string) => boolean} [wanted] - Events whose malformed lists are worth a problem.
- * @returns {Promise<{merged: Record<string, object[]>, problems: string[]}>} Each merged group says `from` which file.
+ * @returns {Promise<{merged: Record<string, object[]>, problems: string[], keys: Set<string>}>} Each merged group says
+ *   `from` which file; `keys` holds every top-level key either file sets.
  */
 async function projectHooks(target, wanted = () => false) {
   const merged = {};
   const problems = [];
+  const keys = new Set();
   for (const rel of SETTINGS_FILES) {
     const path = join(target, rel);
     if (!existsSync(path)) continue;
@@ -267,6 +286,7 @@ async function projectHooks(target, wanted = () => false) {
       problems.push(`${rel} is not valid JSON — ${error.message}`);
       continue;
     }
+    if (settings && typeof settings === 'object' && !Array.isArray(settings)) for (const key of Object.keys(settings)) keys.add(key);
     const shape = settings?.hooks;
     if (shape === undefined || shape === null) continue;
     if (typeof shape !== 'object' || Array.isArray(shape)) {
@@ -278,7 +298,7 @@ async function projectHooks(target, wanted = () => false) {
       else if (wanted(event)) problems.push(`${rel}'s hooks.${event} is not a list — no hook in it can run`);
     }
   }
-  return { merged, problems };
+  return { merged, problems, keys };
 }
 
 /** The command settings run for a hook, when they run one — the selftest runs it the same way. */
@@ -298,7 +318,8 @@ export function hookCommand(settings, event, script) {
  * @returns {string}
  */
 export function settingsFile(shipped = HOOK_SCRIPTS) {
-  return `${JSON.stringify({ hooks: settingsHooks(HOOKS.filter((h) => shipped.has(h.script))) }, null, 2)}\n`;
+  const values = Object.fromEntries(SETTINGS.filter((x) => shipped.has(x.script)).map((x) => [x.key, x.value]));
+  return `${JSON.stringify({ ...values, hooks: settingsHooks(HOOKS.filter((h) => shipped.has(h.script))) }, null, 2)}\n`;
 }
 
 /** Hooks as settings JSON, grouped by event. */
@@ -369,8 +390,11 @@ export async function missingWiring(target, shipped) {
   }
   const wanted = HOOKS.filter((h) => shipped.has(h.script));
   if (wanted.length === 0) return out;
-  const { merged, problems } = await projectHooks(target, (event) => wanted.some((h) => h.event === event));
+  const { merged, problems, keys } = await projectHooks(target, (event) => wanted.some((h) => h.event === event));
   out.push(...problems);
+  for (const x of SETTINGS.filter((x) => shipped.has(x.script) && !keys.has(x.key))) {
+    out.push(`.claude/settings.json has no "${x.key}" — without it ${x.why}; \`nina wire --apply\` sets it to ${x.value}`);
+  }
   for (const h of wanted) {
     const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
     if (doubled(running)) {
@@ -468,7 +492,11 @@ export async function applyWiring(target, shipped, { settings: editSettings = tr
     if (readable) {
       const hooks = settings.hooks ?? {};
       const added = [];
-      const { merged } = await projectHooks(target);
+      const { merged, keys } = await projectHooks(target);
+      for (const x of SETTINGS.filter((x) => shipped.has(x.script) && !keys.has(x.key))) {
+        settings[x.key] = x.value;
+        added.push(`"${x.key}": ${x.value}`);
+      }
       for (const h of HOOKS.filter((h) => shipped.has(h.script))) {
         const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
         if (covered(merged, h) && !doubled(running)) continue;