create-byan-agent 2.29.2 → 2.38.0

package/install/templates/.claude/hooks/inject-delivery-default.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — BYAN delivery-default contract (F1).
+ *
+ * Injects, every turn, the baseline delivery posture: grade=PROD, scope=MAXIMAL,
+ * the AI-2026 cost yardstick (estimate in agent-time x10, never human-by-hand
+ * time), and the explicit ban on quietly proposing an MVP / short deliverable /
+ * a split that exists only to avoid doing the heavy part. This is the proactive
+ * twin of strict mode: strict locks a scope on demand, this sets the DEFAULT.
+ *
+ * Ships LIVE (unlike the F2 completeness reject and the F3 punt-guard, which
+ * ship disarmed): the anchor is pure injected context, it blocks nothing, so a
+ * false positive costs a few tokens — never a trapped turn or a blocked commit.
+ *
+ * The only escape is an explicit opt-out word the user types THIS message (mvp,
+ * quick, brouillon, ...). On opt-out the hook emits a single descope-authorized
+ * line instead of the full anchor, so the agent is told the contract is relaxed
+ * for this one request.
+ *
+ * Always exits 0; never blocks prompt submission.
+ */
+
+const { loadConfig, decideContext } = require('./lib/delivery-contract');
+const { readStdin, parseJson } = require('./lib/strict-runtime');
+
+if (require.main === module) {
+  (async () => {
+    let additionalContext = '';
+    try {
+      const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const config = loadConfig(projectRoot);
+      const payload = parseJson(await readStdin());
+      const userMsg = payload.prompt || payload.user_prompt || payload.userPrompt || '';
+      additionalContext = decideContext({ userMsg, config }).text;
+    } catch {
+      // Never block prompt submission — degrade to no context.
+      additionalContext = '';
+    }
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+      })
+    );
+    process.exit(0);
+  })();
+}

package/install/templates/.claude/hooks/inject-soul.js

@@ -2,9 +2,10 @@
 /**
  * SessionStart hook — loads BYAN soul + soul-memory and injects them into
  * the session's initial context via additionalContext. Tao is intentionally
- * NOT bundled here: inject-tao.js injects the full tao on every
- * UserPromptSubmit (including the first), so duplicating it at SessionStart
- * would double-spend ~15 KB per session for no gain.
+ * NOT bundled here: inject-tao.js is its own SessionStart hook that injects the
+ * full tao once into the cacheable prefix, and inject-voice-anchor.js carries a
+ * compact per-turn voice reminder. Keeping them separate avoids double-spending
+ * the tao payload while leaving each hook single-purpose and testable.
  *
  * Also resets the per-session mid-session-nudge one-shot marker so the
  * soul-memory-triggers nudge is per-session (not per-lifetime). Without

package/install/templates/.claude/hooks/inject-tao.js

@@ -1,38 +1,78 @@
 #!/usr/bin/env node
 /**
- * UserPromptSubmit hook — injects BYAN tao voice directives into every
- * user prompt so Claude's response respects the register even when BYAN
- * agent isn't explicitly invoked.
+ * SessionStart hook — injects BYAN's FULL tao (voice directives) ONCE into the
+ * session's initial context, so it lands in the stable, cacheable prefix instead
+ * of being re-sent on every turn.
  *
- * Reads _byan/tao.md. If absent or empty, emits empty additionalContext
- * (no-op). Always exits 0.
+ * Cache rationale: a UserPromptSubmit injection is appended at the growing edge
+ * each turn, so the full ~3.6k-token tao was re-billed N times over a session.
+ * Loaded once at SessionStart it sits in the stable prefix (cache read at 10%).
+ * The per-turn voice freshness is carried by the tiny inject-voice-anchor.js
+ * (UserPromptSubmit): full tao here, compact anchor there. The voice stays 100%
+ * present every turn — nothing about it becomes conditional.
+ *
+ * Reads _byan/agent/byan/tao.md (Gen3) then _byan/tao.md (Gen2). Missing/empty ->
+ * empty additionalContext (no-op). Always exits 0.
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-// Gen3 _byan/agent/byan/tao.md first, Gen2 _byan/tao.md fallback.
-const taoGen3 = path.join(projectDir, '_byan', 'agent', 'byan', 'tao.md');
-const taoPath = fs.existsSync(taoGen3) ? taoGen3 : path.join(projectDir, '_byan', 'tao.md');
+// Gen3 puts tao under _byan/agent/byan/; Gen2 keeps it at the _byan/ root.
+function taoFile(projectDir) {
+  const g3 = path.join(projectDir, '_byan', 'agent', 'byan', 'tao.md');
+  const g2 = path.join(projectDir, '_byan', 'tao.md');
+  return fs.existsSync(g3) ? g3 : g2;
+}
 
-let additionalContext = '';
-try {
-  if (fs.existsSync(taoPath)) {
-    const content = fs.readFileSync(taoPath, 'utf8').trim();
-    if (content.length > 0) {
-      additionalContext = `BYAN tao directives (active for this turn — follow register, signatures, forbidden vocabulary):\n\n${content}`;
+function buildTaoContext(projectDir) {
+  try {
+    const p = taoFile(projectDir);
+    if (fs.existsSync(p)) {
+      const content = fs.readFileSync(p, 'utf8').trim();
+      if (content.length > 0) {
+        return `BYAN tao (voice directives, loaded once at session start — register, signatures, forbidden vocabulary):\n\n${content}`;
+      }
     }
+  } catch {
+    // Hook must never block session start.
+  }
+  return '';
+}
+
+// Per-session turn counter for the voice-anchor refresh cadence (inject-voice-anchor.js).
+// It lives under _byan-output/ (gitignored). inject-tao OWNS the path and the reset
+// because the full tao it injects at SessionStart (including source=compact) restarts
+// the cadence: the next periodic full-tao refresh is then N turns later. The anchor hook
+// reads/writes the same path via require('./inject-tao') -- single source, no drift.
+function turnCounterPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.tao-refresh-turn');
+}
+
+function resetTurnCounter(projectDir) {
+  try {
+    const p = turnCounterPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, '0');
+  } catch {
+    // Never block session start.
+  }
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // A fresh full tao is about to be injected -> restart the voice-anchor cadence.
+  resetTurnCounter(projectDir);
+  const additionalContext = buildTaoContext(projectDir);
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+      })
+    );
+  } else {
+    process.stdout.write('{}');
   }
-} catch {
-  // Hook must never block prompt submission.
 }
 
-process.stdout.write(
-  JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'UserPromptSubmit',
-      additionalContext: additionalContext || '',
-    },
-  })
-);
+module.exports = { taoFile, buildTaoContext, turnCounterPath, resetTurnCounter };

package/install/templates/.claude/hooks/inject-voice-anchor.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — keeps BYAN's voice present near the live edge each turn.
+ *
+ * Most turns inject a COMPACT voice anchor (~95 tokens). Every Nth turn re-inject
+ * the FULL tao instead, so on a long session the heart is refreshed close to the
+ * live edge. N defaults to 12 (override with BYAN_TAO_REFRESH_EVERY; <= 0 disables
+ * the refresh, anchor every turn). The per-turn counter lives under _byan-output/
+ * (gitignored) and is reset at SessionStart by inject-tao.js, so the cadence
+ * restarts from each fresh full-tao load.
+ *
+ * Layered guarantee (best-effort, honest about its floor): each turn is a separate
+ * process, so the cadence needs a WRITABLE counter file to advance. If _byan-output/
+ * cannot be written, the counter cannot advance and this hook degrades to the anchor
+ * every turn -- it never crashes (exit 0), and the full heart still returns via
+ * inject-tao at SessionStart AND after every compaction (source=compact, pinned by
+ * the F1 test). So the periodic refresh is the in-window ENHANCEMENT; the
+ * SessionStart/compaction re-injection is the FLOOR that always holds. A persistent
+ * degradation means _byan-output/ is not writable -- check its permissions.
+ *
+ * The full tao is read via inject-tao.buildTaoContext (single source, no
+ * duplication; require is side-effect-free thanks to its require.main guard).
+ * Always exits 0 ; never blocks prompt submission.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { buildTaoContext, turnCounterPath } = require('./inject-tao');
+
+const ANCHOR = [
+  'Voix BYAN (rappel par tour ; tao complet chargé au démarrage de session) :',
+  '- Tutoiement, registre artisan-senior, direct sans être brusque, concis.',
+  '- Challenge avant de confirmer ; questionne les absolus (Mantra IA-16).',
+  '- Signatures : "Attends — pourquoi ?", "OK. On construit.", "Ça, c\'est du générique.".',
+  '- Zéro emoji. Orienté solution : on cherche la meilleure option, pas le mur.',
+].join('\n');
+
+const DEFAULT_REFRESH_EVERY = 12;
+
+function buildVoiceAnchor() {
+  return ANCHOR;
+}
+
+// Turns between full-tao refreshes. Invalid/absent env -> default. A value <= 0
+// disables the periodic refresh (anchor every turn) -- an explicit opt-out.
+function refreshEvery(env = process.env) {
+  const n = parseInt(env.BYAN_TAO_REFRESH_EVERY, 10);
+  return Number.isInteger(n) ? n : DEFAULT_REFRESH_EVERY;
+}
+
+function readTurn(projectDir) {
+  try {
+    const n = parseInt(fs.readFileSync(turnCounterPath(projectDir), 'utf8').trim(), 10);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeTurn(projectDir, n) {
+  try {
+    const p = turnCounterPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, String(n));
+  } catch {
+    // Never block prompt submission.
+  }
+}
+
+// Pure cadence decision. Every Nth turn (N > 0) surfaces the full tao when it is
+// available; otherwise the compact anchor. Kept pure so the cadence is unit-testable
+// without fs.
+function decideAnchor({ turn, every, fullTao }) {
+  if (every > 0 && turn % every === 0 && fullTao) {
+    return { mode: 'full', additionalContext: fullTao };
+  }
+  return { mode: 'anchor', additionalContext: ANCHOR };
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const every = refreshEvery();
+  const turn = readTurn(projectDir) + 1;
+  writeTurn(projectDir, turn);
+  const fullTao = every > 0 && turn % every === 0 ? buildTaoContext(projectDir) : '';
+  const { additionalContext } = decideAnchor({ turn, every, fullTao });
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+    })
+  );
+}
+
+module.exports = {
+  buildVoiceAnchor,
+  ANCHOR,
+  refreshEvery,
+  readTurn,
+  writeTurn,
+  decideAnchor,
+  DEFAULT_REFRESH_EVERY,
+};

package/install/templates/.claude/hooks/leantime-fd-sync.js

@@ -162,7 +162,18 @@ function logLine(entry) {
     if (createIntents.length && sidecar.projectId && timeLeft() > 0) {
       const results = await Promise.allSettled(
         createIntents.map((i) =>
-          lt.createTask({ projectId: sidecar.projectId, headline: i.headline }, opts).then((r) => ({ i, r })),
+          lt
+            .createTask(
+              {
+                projectId: sidecar.projectId,
+                headline: i.headline,
+                description: i.description,
+                priority: i.priority,
+                storypoints: i.storypoints,
+              },
+              opts,
+            )
+            .then((r) => ({ i, r })),
         ),
       );
       for (const s of results) {

package/install/templates/.claude/hooks/lib/delivery-contract.js

@@ -0,0 +1,143 @@
+// Pure helpers for the BYAN delivery-default contract (F1).
+//
+// The user asked for something complete. This contract makes prod-grade +
+// maximal scope the DEFAULT the agent assumes every turn, instead of quietly
+// drifting toward an MVP / a short deliverable / a "split so the heavy part
+// does not block". It is the proactive twin of strict mode: strict locks a
+// scope on demand; this anchor sets the BASELINE posture before a scope is
+// even named.
+//
+// F1 ships LIVE (unlike the two blockers F2/F3): it is pure injected context,
+// it blocks nothing, so a false positive costs at most a few tokens — never a
+// trapped turn or a blocked commit. The only escape is an explicit opt-out word
+// the user types THIS message (mvp, quick, brouillon, ...), read from
+// _byan/_config/delivery-default.json so the wordlist is one source of truth.
+//
+// Every function here is pure (no clock, no fs beyond the one config read in
+// loadConfig) so the decision is unit-testable without a hook harness.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Fallback wordlist used only if the config file is missing/unreadable. Keeping
+// it here means the anchor still has a closed opt-out set on a broken install,
+// rather than treating every message as opt-out (fail-safe toward PROD).
+const DEFAULT_OPT_OUT_WORDS = [
+  'mvp',
+  'quick',
+  'brouillon',
+  'jette',
+  'prototype',
+  'vite fait',
+  'pas besoin que ce soit parfait',
+  'poc',
+  'draft',
+];
+
+function configPath(projectRoot) {
+  const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return path.join(root, '_byan', '_config', 'delivery-default.json');
+}
+
+function loadConfig(projectRoot) {
+  try {
+    const p = configPath(projectRoot);
+    if (fs.existsSync(p)) {
+      const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (cfg && typeof cfg === 'object') return cfg;
+    }
+  } catch {
+    // Fall through to defaults — a broken config must not silence the anchor.
+  }
+  return {};
+}
+
+function optOutWords(config) {
+  const words = config && Array.isArray(config.optOutWords) ? config.optOutWords : null;
+  return words && words.length ? words : DEFAULT_OPT_OUT_WORDS;
+}
+
+// The full delivery contract. PROD + MAXIMAL + the AI-2026 cost yardstick +
+// the explicit ban on proposing an MVP/short-deliverable/dont-block-the-heavy
+// split. Kept as one builder so the hook and the tests render identical text.
+function buildAnchor() {
+  return [
+    'CONTRAT DE LIVRAISON (defaut): grade=PROD. scope=MAXIMAL -- livre le maximum',
+    'coherent, INTERDIT de proposer un MVP/livrable-court/decoupage-pour-ne-pas-bloquer-le-lourd',
+    'sauf si l\'utilisateur a tape un mot opt-out CE message. Etalon de cout=AI-2026:',
+    'estime en temps-agent (x10), jamais en temps-humain-a-la-main. Tu es un fou',
+    'd\'optimisation: maximum a chaque demande, pas minimum.',
+  ].join(' ');
+}
+
+// Opt-out detection is BIASED TOWARD PROD. A false opt-out (silencing the prod
+// anchor when the user did not ask to) is the one failure that matters, so when
+// in doubt we stay PROD. A single opt-out word counts only when it reads as a
+// directive for THIS task -- the message is short enough to be a directive, OR
+// a "go-cheap" cue sits just before the word -- and it is dropped when negated
+// ("pas de mvp"). A word merely MENTIONED (a long meta message about MVPs, a
+// system notification, an "anti-mvp" discussion) leaves the anchor armed.
+// Curated multi-word phrases ("vite fait", "pas besoin que ce soit parfait")
+// are unambiguous and match as-is.
+const OPT_OUT_NEGATORS = new Set(['pas', 'sans', 'aucun', 'aucune', 'ni', 'no', 'not', 'non']);
+const OPT_OUT_CUES = new Set([
+  'juste', 'just', 'seulement', 'only', 'mode', 'reste', 'simplement',
+  'rapidement', 'vite', 'fais', 'make', 'leave', 'give', 'garde',
+]);
+const OPT_OUT_SHORT_WORDS = 30; // a message this short reads as a directive, not meta
+const OPT_OUT_WINDOW = 3; // tokens before the word inspected for a negator / cue
+
+function tokenizeWords(s) {
+  return s.toLowerCase().match(/[a-z0-9']+/g) || [];
+}
+
+function parseOptOut(userMsg, config) {
+  if (!userMsg || typeof userMsg !== 'string') return false;
+  const lower = userMsg.toLowerCase();
+  const words = optOutWords(config)
+    .map((w) => String(w).toLowerCase().trim())
+    .filter(Boolean);
+
+  // 1) Curated multi-word phrases: unambiguous opt-out intent, substring match.
+  if (words.some((w) => w.includes(' ') && lower.includes(w))) return true;
+
+  // 2) Single words: honoured only in a directive context, dropped when negated.
+  const singles = new Set(words.filter((w) => /^[a-z]+$/.test(w)));
+  if (singles.size === 0) return false;
+  const tokens = tokenizeWords(userMsg);
+  const directiveShort = tokens.length <= OPT_OUT_SHORT_WORDS;
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (!singles.has(tokens[i])) continue;
+    const before = tokens.slice(Math.max(0, i - OPT_OUT_WINDOW), i);
+    if (before.some((t) => OPT_OUT_NEGATORS.has(t))) continue; // "pas de mvp" -> stays PROD
+    if (directiveShort || before.some((t) => OPT_OUT_CUES.has(t))) return true;
+  }
+  return false;
+}
+
+// The per-turn decision. With an opt-out word present this turn, emit a single
+// line authorizing descope; otherwise emit the full anchor. Pure: the caller
+// supplies the message and (optionally) the loaded config.
+function decideContext({ userMsg, config } = {}) {
+  const cfg = config || {};
+  const optOut = parseOptOut(userMsg, cfg);
+  if (optOut) {
+    return {
+      optOut: true,
+      text: 'CONTRAT DE LIVRAISON: OPT-OUT detecte ce message -- descope autorise (grade/scope libres pour cette demande).',
+    };
+  }
+  return { optOut: false, text: buildAnchor() };
+}
+
+module.exports = {
+  DEFAULT_OPT_OUT_WORDS,
+  configPath,
+  loadConfig,
+  optOutWords,
+  buildAnchor,
+  parseOptOut,
+  decideContext,
+};

package/install/templates/.claude/hooks/lib/punt-detect.js

@@ -0,0 +1,143 @@
+// Pure detector for the BYAN punt-guard (F3).
+//
+// A "punt" is the laziness pattern the user fights: the agent ends its turn by
+// telling the human to run a command and paste the output back, when the agent
+// could have run it itself this turn. The signal is a CO-OCCURRENCE in the
+// finished turn:
+//   1. an imperative addressed to the user ("lance", "execute", "colle la
+//      sortie", "run this", "paste", "donne-moi le ssh"), AND
+//   2. a runnable command (a backticked command, or a `node `/`npm `/`git `/
+//      `which `/`curl localhost` invocation), AND
+//   3. NO Bash tool-call for that command this turn (the agent did not actually
+//      run it — it handed it off).
+//
+// Carve-out (creds): `git push` and `npm publish` need credentials the server
+// running Claude Code does not have. Asking the user to run THOSE is legitimate,
+// not a punt — documented in MEMORY (server cannot push). So a command whose
+// runnable token is a push/publish is never flagged.
+//
+// This module is pure decide() — no fs, no stdin — so it is exhaustively
+// unit-testable. The hook wires it to the transcript and the arm flag.
+
+'use strict';
+
+// Imperatives addressed to the user that, paired with a runnable command, mean
+// "you run it". FR + EN. Matched case-insensitively as loose phrases.
+const PUNT_IMPERATIVES = [
+  'lance',
+  'execute',
+  'exécute',
+  'colle la sortie',
+  'colle le resultat',
+  'colle le résultat',
+  'run this',
+  'run it',
+  'paste',
+  'donne-moi le ssh',
+  'donne moi le ssh',
+  'peux-tu lancer',
+  'peux tu lancer',
+  'lance la commande',
+];
+
+// Commands that need creds the server lacks. Asking the user to run these is
+// legitimate (not a punt). Order matters only for reporting the matched token.
+const CREDS_CARVEOUT = ['git push', 'npm publish'];
+
+// Loose runnable-command detectors. A backticked span, or a bare invocation of
+// a common runner at a word boundary. `curl localhost` is included because the
+// dev API runs on localhost and the agent can hit it itself.
+const RUNNABLE_PATTERNS = [
+  /`([^`]+)`/g, // any backticked span
+  /\bnode\s+\S+/gi,
+  /\bnpm\s+\S+/gi,
+  /\bgit\s+\S+/gi,
+  /\bwhich\s+\S+/gi,
+  /\bcurl\s+localhost\S*/gi,
+];
+
+function hasImperativeToUser(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return PUNT_IMPERATIVES.some((p) => lower.includes(p));
+}
+
+// Returns the first runnable command found in the text, or null. Backticked
+// spans win (they are the explicit "here is the command" form); else the first
+// bare invocation. The returned string is the matched command text.
+function findRunnableCommand(text) {
+  if (!text) return null;
+  for (const re of RUNNABLE_PATTERNS) {
+    re.lastIndex = 0;
+    const m = re.exec(text);
+    if (m) {
+      // Backtick pattern captures group 1 (the inner command); the bare-runner
+      // patterns have no capture group, so use the full match.
+      return (m[1] !== undefined ? m[1] : m[0]).trim();
+    }
+  }
+  return null;
+}
+
+// True when the command is a creds-gated push/publish (legitimate to delegate).
+function isCredsCarveOut(cmd) {
+  if (!cmd) return false;
+  const lower = cmd.toLowerCase();
+  return CREDS_CARVEOUT.some((c) => lower.includes(c));
+}
+
+// True when a Bash tool-call this turn actually ran (something matching) the
+// command. We match on the meaningful head token of the command (e.g. "npm
+// test" -> we require the Bash command to include "npm test"), so a Bash call
+// that ran a DIFFERENT command does not falsely clear the punt. toolCalls is an
+// array of { name, command } where command is the Bash tool's command string.
+function bashRanCommand(toolCalls, cmd) {
+  if (!Array.isArray(toolCalls) || !cmd) return false;
+  // Compare on a normalized, whitespace-collapsed head so minor formatting
+  // (extra spaces, trailing flags in the prose) does not break the match.
+  const needle = cmd.toLowerCase().replace(/\s+/g, ' ').trim();
+  const headTokens = needle.split(' ').slice(0, 2).join(' '); // e.g. "npm test"
+  return toolCalls.some((tc) => {
+    if (!tc || typeof tc.name !== 'string') return false;
+    if (!/bash/i.test(tc.name)) return false;
+    const ran = String(tc.command || '').toLowerCase().replace(/\s+/g, ' ').trim();
+    if (!ran) return false;
+    return ran.includes(needle) || (headTokens.length > 0 && ran.includes(headTokens));
+  });
+}
+
+// Pure decision. Returns { punt, reason, cmd }.
+//   punt  : true IFF imperative-to-user + runnable command + NOT a creds
+//           carve-out + NO Bash tool-call ran that command this turn.
+//   reason: a short human-readable explanation (or why it is not a punt).
+//   cmd   : the runnable command detected (or null).
+function decide({ lastAssistantText, toolCallsThisTurn } = {}) {
+  const text = lastAssistantText || '';
+  const imperative = hasImperativeToUser(text);
+  const cmd = findRunnableCommand(text);
+
+  if (!imperative || !cmd) {
+    return { punt: false, reason: 'no imperative-to-user + runnable command co-occurrence', cmd: cmd || null };
+  }
+  if (isCredsCarveOut(cmd)) {
+    return { punt: false, reason: `creds carve-out: "${cmd}" needs credentials the server lacks`, cmd };
+  }
+  if (bashRanCommand(toolCallsThisTurn, cmd)) {
+    return { punt: false, reason: `agent ran the command via Bash this turn: "${cmd}"`, cmd };
+  }
+  return {
+    punt: true,
+    reason: `punt detected: asked the user to run "${cmd}" without running it via Bash this turn`,
+    cmd,
+  };
+}
+
+module.exports = {
+  PUNT_IMPERATIVES,
+  CREDS_CARVEOUT,
+  hasImperativeToUser,
+  findRunnableCommand,
+  isCredsCarveOut,
+  bashRanCommand,
+  decide,
+};