@axplusb/kepler 1.0.10 → 2.0.0

package/src/core/approval.mjs

@@ -11,45 +11,42 @@
  */
 
 import { toolDisplayLabel, toolDisplaySummary } from '../terminal/tool-display.mjs';
+import {
+  classify as classifyTier,
+  TIERS,
+  requiresExplicitApproval,
+  requiresCheckpoint,
+  label as tierLabel,
+} from './risk-tier.mjs';
+import {
+  renderApprovalPrompt,
+  renderInlinePrompt,
+  defaultOptions as approvalOptions,
+} from '../ui/approval.mjs';
 
 // ── Tool Classification ──
+//
+// Risk tiering moved to src/core/risk-tier.mjs (PRD-055 §8.1). WRITE_TOOLS
+// stays here only because `planMode` blocks anything that writes.
 
 const WRITE_TOOLS = new Set([
     'shell', 'write_file', 'write_project', 'edit_file', 'delete_file',
     'validate_build', 'lint_check',
 ]);
 
-const NEVER_AUTO_APPROVE = new Set(['delete_file']);
-
-const FORCE_APPROVAL_SHELL = [
-    /\brm\s/,
-    /\bunlink\s/,
-    /\brmdir\s/,
-    /\bgit\s+clean/,
-    /\bgit\s+reset/,
-    /\bgit\s+push.*--force/,
-];
-
-const RISK_LEVELS = {
-    read_file: 'none', read_files: 'none', search_code: 'none',
-    search_files: 'none', list_files: 'none', get_file_info: 'none',
-    validate_file: 'none', validate_structure: 'none',
-    write_file: 'low', write_project: 'low', edit_file: 'low',
-    lint_check: 'low', validate_build: 'medium',
-    shell: 'medium',
-    delete_file: 'high',
-};
-
-function assessShellRisk(command) {
-    if (!command) return 'medium';
-    if (/rm\s+-r/i.test(command)) return 'high';
-    if (/git\s+(push|reset|clean|checkout\s+\.)/i.test(command)) return 'high';
-    if (/drop\s+(table|database)/i.test(command)) return 'high';
-    if (/sudo\s/i.test(command)) return 'high';
-    if (/^(ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)/i.test(command)) return 'low';
-    if (/^git\s+(status|log|diff|show|branch|tag|remote|stash\s+list|blame|shortlog|describe|rev-parse|ls-files|ls-tree)/i.test(command)) return 'low';
-    if (/^(npm\s+(test|run|list|ls|view|info|outdated|audit)|node\s+--check|python3?\s+-m\s+py_compile|cargo\s+(check|test|clippy))/i.test(command)) return 'low';
-    return 'medium';
+function defaultWhy(tier, tool, args) {
+    switch (tier) {
+        case TIERS.SHELL_DANGEROUS:
+            return `Shell command matches a high-risk pattern (rm -rf, sudo, force push, etc.). Confirm before running.`;
+        case TIERS.DESTRUCTIVE:
+            return `${tool} permanently mutates project state. Confirm before running.`;
+        case TIERS.SHELL_MEDIUM:
+            return `Mutates the workspace or environment (install, build, commit, push).`;
+        case TIERS.NETWORK:
+            return `Reaches an external network endpoint.`;
+        default:
+            return '';
+    }
 }
 
 // ── ANSI helpers ──
@@ -107,93 +104,146 @@ export class ApprovalManager {
         // Auto-approve everything in headless/autoApprove mode (no TTY prompts)
         if (this.autoApprove) {
             this.history.push({ tool: toolName, decision: 'auto', time: Date.now() });
-            return { approved: true };
+            return { approved: true, tier: classifyTier(toolName, args) };
         }
-        if (!WRITE_TOOLS.has(toolName) && !requireApproval) {
-            return { approved: true };
+
+        const tier = classifyTier(toolName, args);
+
+        // 'auto' tiers: read, shell-safe.
+        if (tier === TIERS.READ || tier === TIERS.SHELL_SAFE) {
+            this.history.push({ tool: toolName, decision: 'auto-tier', tier, time: Date.now() });
+            return { approved: true, tier };
+        }
+
+        // 'auto-with-undo' tier: local-edit. Checkpoint is taken by the tool
+        // executor before the edit; here we just approve.
+        if (tier === TIERS.LOCAL_EDIT) {
+            this.history.push({ tool: toolName, decision: 'auto-with-undo', tier, time: Date.now() });
+            return { approved: true, tier, requireCheckpoint: true };
         }
-        if (toolName === 'shell') {
-            const risk = assessShellRisk(args.command);
-            if (risk === 'low') {
-                this.history.push({ tool: toolName, decision: 'auto-safe', time: Date.now() });
-                return { approved: true };
+
+        // Honor approve-all / type-allow shortcuts for non-explicit tiers only.
+        if (!requiresExplicitApproval(tier)) {
+            if (this.approveAll) {
+                this.history.push({ tool: toolName, decision: 'auto-all', tier, time: Date.now() });
+                return { approved: true, tier };
             }
-            if (FORCE_APPROVAL_SHELL.some(p => p.test(args.command || ''))) {
-                return this._prompt(toolName, args, context);
+            if (this.approvedToolTypes.has(toolName)) {
+                this.history.push({ tool: toolName, decision: 'type-auto', tier, time: Date.now() });
+                return { approved: true, tier };
             }
         }
-        if (NEVER_AUTO_APPROVE.has(toolName)) {
-            return this._prompt(toolName, args, context);
-        }
-        if (this.approveAll) {
-            this.history.push({ tool: toolName, decision: 'auto', time: Date.now() });
-            return { approved: true };
-        }
-        if (this.approvedToolTypes.has(toolName)) {
-            this.history.push({ tool: toolName, decision: 'type-auto', time: Date.now() });
-            return { approved: true };
-        }
-        return this._prompt(toolName, args, context);
+
+        return this._prompt(toolName, args, { ...context, tier });
     }
 
     async _prompt(toolName, args, context = {}) {
-        const baseRisk = RISK_LEVELS[toolName] || 'medium';
-        const assessedRisk = toolName === 'shell' ? assessShellRisk(args.command) : baseRisk;
-        const risk = context.risk || assessedRisk;
-        const label = toolDisplayLabel(toolName);
+        const tier = context.tier || classifyTier(toolName, args);
+        const explicit = requiresExplicitApproval(tier);
+        const why = context.reason || context.why || defaultWhy(tier, toolName, args);
         const summary = toolDisplaySummary(toolName, args);
-        const isDestructive = risk === 'high';
-
-        write(`\n  ${isDestructive ? `${YELLOW}⚠${RST}` : `${CYAN}?${RST}`}  ${BOLD}Approval required${RST}\n`);
-        write(`  ${GRAY}Action${RST}  ${WHITE}${label}${RST}\n`);
-        if (summary) write(`  ${GRAY}Target${RST}  ${WHITE}${summary.slice(0, 160)}${RST}\n`);
-        write(`  ${GRAY}Risk${RST}    ${isDestructive ? YELLOW : CYAN}${risk}${RST}\n`);
-        if (context.reason) write(`  ${GRAY}Reason${RST}  ${DIM}${String(context.reason).slice(0, 160)}${RST}\n`);
-
-        if (isDestructive) {
-            write(`  ${DIM}Choose${RST}  ${WHITE}[y]${RST} allow once  ${WHITE}[n]${RST} deny  ${WHITE}[d]${RST} details\n`);
-        } else {
-            write(`  ${DIM}Choose${RST}  ${WHITE}[y]${RST} once  ${WHITE}[n]${RST} deny  ${WHITE}[t]${RST} this action  ${WHITE}[a]${RST} all  ${WHITE}[d]${RST} details\n`);
+        const options = approvalOptions(tier);
+
+        let selected = 0; // arrow-driven cursor
+        let printedHeight = 0;
+
+        // For TTYs we redraw in place on every arrow key so the prompt feels
+        // live. For non-TTYs / pipes we just print once and read a line.
+        const isInteractive = process.stdin.isTTY;
+        if (!isInteractive) {
+            write(explicit
+                ? renderApprovalPrompt({ tool: toolName, args, tier, why, selected, options }) + '\n'
+                : renderInlinePrompt({ tool: toolName, args, tier, why }) + '\n');
         }
 
-        const key = await this._readKey();
+        const drawExplicit = () => {
+            // Move up over the previous render before re-printing.
+            if (printedHeight > 0) {
+                write(`\x1b[${printedHeight}F`); // cursor to start of N lines above
+                write('\x1b[J');                   // clear from cursor to end of screen
+            }
+            const block = renderApprovalPrompt({ tool: toolName, args, tier, why, selected, options });
+            write(block + '\n');
+            printedHeight = block.split('\n').length;
+        };
 
-        switch (key) {
-            case 'y':
-            case 'Y':
-            case 'return':
+        if (isInteractive && explicit) drawExplicit();
+        if (isInteractive && !explicit) write(renderInlinePrompt({ tool: toolName, args, tier, why }) + '\n');
+
+        // ── Input loop ─────────────────────────────────────────────────
+        const choose = async () => {
+            for (;;) {
+                const k = await this._readKey();
+
+                if (k === 'up' || k === 'left') {
+                    if (!explicit || !isInteractive) continue;
+                    selected = (selected - 1 + options.length) % options.length;
+                    drawExplicit();
+                    continue;
+                }
+                if (k === 'down' || k === 'right' || k === 'tab') {
+                    if (!explicit || !isInteractive) continue;
+                    selected = (selected + 1) % options.length;
+                    drawExplicit();
+                    continue;
+                }
+                if (k === 'return') {
+                    return options[selected].value;
+                }
+                if (k === 'escape') return 'reject';
+
+                // Letter shortcut: match against option.key
+                if (typeof k === 'string' && k.length === 1) {
+                    const lower = k.toLowerCase();
+                    const idx = options.findIndex(o => o.key === lower);
+                    if (idx >= 0) {
+                        selected = idx;
+                        if (isInteractive && explicit) drawExplicit();
+                        return options[idx].value;
+                    }
+                }
+                // Anything else: ignore and re-read.
+            }
+        };
+
+        const value = await choose();
+
+        switch (value) {
+            case 'approve':
                 write(`  ${GREEN}✓${RST}  ${DIM}${toolName}${RST} ${DIM}${summary.slice(0, 60)}${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'yes', time: Date.now() });
-                return { approved: true };
+                this.history.push({ tool: toolName, decision: 'yes', tier, time: Date.now() });
+                return { approved: true, tier };
 
-            case 'n':
-            case 'N':
-            case 'escape':
+            case 'reject':
                 write(`  ${RED}✗${RST}  ${DIM}denied${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'no', time: Date.now() });
-                return { approved: false, reason: 'User denied' };
+                this.history.push({ tool: toolName, decision: 'no', tier, time: Date.now() });
+                return { approved: false, tier, reason: 'User denied' };
 
-            case 'a':
-            case 'A':
-                if (isDestructive) return this._prompt(toolName, args, context);
+            case 'allow-all':
+                if (explicit) return this._prompt(toolName, args, context);
                 this.approveAll = true;
                 write(`  ${GREEN}✓✓${RST} ${DIM}allow-all activated${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'approve-all', time: Date.now() });
-                return { approved: true };
+                this.history.push({ tool: toolName, decision: 'approve-all', tier, time: Date.now() });
+                return { approved: true, tier };
 
-            case 't':
-            case 'T':
-                if (isDestructive) return this._prompt(toolName, args, context);
+            case 'allow-type':
+                if (explicit) return this._prompt(toolName, args, context);
                 this.approvedToolTypes.add(toolName);
                 write(`  ${GREEN}✓${RST}  ${DIM}always allow ${toolName}${RST}\n\n`);
-                this.history.push({ tool: toolName, decision: 'type-approve', time: Date.now() });
-                return { approved: true };
+                this.history.push({ tool: toolName, decision: 'type-approve', tier, time: Date.now() });
+                return { approved: true, tier };
 
-            case 'd':
-            case 'D':
-                write(`\n${DIM}${JSON.stringify(args, null, 2)}${RST}\n\n`);
+            case 'why':
+                write(`\n  ${DIM}${(context.reason || why).slice(0, 400)}${RST}\n\n`);
+                printedHeight = 0;
                 return this._prompt(toolName, args, context);
 
+            case 'edit':
+            case 'replan':
+                write(`  ${YELLOW}↩${RST}  ${DIM}reject with hint — rework the plan${RST}\n\n`);
+                this.history.push({ tool: toolName, decision: 'replan', tier, time: Date.now() });
+                return { approved: false, tier, reason: 'User asked to re-plan' };
+
             default:
                 return this._prompt(toolName, args, context);
         }
@@ -221,7 +271,16 @@ export class ApprovalManager {
                 const str = data.toString();
 
                 if (bytes[0] === 0x03) process.exit(0);
-                if (bytes[0] === 0x1b) { resolve('escape'); return; }
+                // Arrow keys: ESC [ A/B/C/D (3-byte CSI sequences)
+                if (bytes.length === 3 && bytes[0] === 0x1b && bytes[1] === 0x5b) {
+                    if (bytes[2] === 0x41) { resolve('up');    return; }
+                    if (bytes[2] === 0x42) { resolve('down');  return; }
+                    if (bytes[2] === 0x43) { resolve('right'); return; }
+                    if (bytes[2] === 0x44) { resolve('left');  return; }
+                }
+                // Bare Esc (single byte) — explicit reject signal
+                if (bytes.length === 1 && bytes[0] === 0x1b) { resolve('escape'); return; }
+                if (bytes[0] === 0x09) { resolve('tab'); return; }
                 if (str === '\r' || str === '\n') { resolve('return'); return; }
                 resolve(str);
             });

package/src/core/backend-url.mjs

@@ -9,8 +9,8 @@
 
 const BACKEND_URLS = {
     local:       'http://127.0.0.1:8000',
-    development: 'https://tarang-backend-development.up.railway.app',
-    production:  'https://tarang-backend-intl-web-app-production.up.railway.app',
+    development: 'https://codekepler-backend-dev.kindisland-9034322d.eastus.azurecontainerapps.io',
+    production:  'https://codekepler-backend-prod.redsky-6d31f3e5.eastus.azurecontainerapps.io',
 };
 
 // Aliases

package/src/core/headless.mjs

@@ -188,6 +188,11 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
         toolBreakdown[t.tool] = (toolBreakdown[t.tool] || 0) + 1;
     }
 
+    // Include sub-agent tool counts in the total
+    for (const sa of subAgents) {
+        toolCount += sa.tool_calls || 0;
+    }
+
     emit({
         type: 'complete',
         tools: toolCount,

package/src/core/risk-tier.mjs

@@ -0,0 +1,239 @@
+/**
+ * Risk tier classifier — Mission Control (PRD-055 §8.1).
+ *
+ *   import { classify, TIERS, behavior } from './risk-tier.mjs';
+ *   const tier = classify('shell', { command: 'rm -rf node_modules' });
+ *   // → 'shell-dangerous'
+ *
+ * Pure: no I/O, no async. Tested in isolation; the rest of the CLI relies on
+ * the return value to decide whether to auto-approve, auto-approve with
+ * checkpoint, or hold for explicit approval.
+ *
+ * The CLI never asks the backend for the tier. The backend's job is to say
+ * "this is what I want to run"; we map that to a tier locally so dangerous
+ * intent can't be hidden behind a friendly description.
+ */
+
+// ── Tier enum ────────────────────────────────────────────────────────────
+
+export const TIERS = Object.freeze({
+  READ:            'read',
+  LOCAL_EDIT:      'local-edit',
+  SHELL_SAFE:      'shell-safe',
+  SHELL_MEDIUM:    'shell-medium',
+  SHELL_DANGEROUS: 'shell-dangerous',
+  DESTRUCTIVE:     'destructive',
+  NETWORK:         'network',
+});
+
+/**
+ * Default behavior by tier:
+ *   auto              — proceed silently
+ *   auto-with-undo    — proceed but record a checkpoint first
+ *   prompt-safe       — prompt with Enter=approve default
+ *   prompt-explicit   — magenta-bordered prompt, no default
+ */
+export const BEHAVIOR = Object.freeze({
+  [TIERS.READ]:            'auto',
+  [TIERS.LOCAL_EDIT]:      'auto-with-undo',
+  [TIERS.SHELL_SAFE]:      'auto',
+  [TIERS.SHELL_MEDIUM]:    'prompt-safe',
+  [TIERS.SHELL_DANGEROUS]: 'prompt-explicit',
+  [TIERS.DESTRUCTIVE]:     'prompt-explicit',
+  [TIERS.NETWORK]:         'prompt-safe',
+});
+
+export function behavior(tier) {
+  return BEHAVIOR[tier] || 'prompt-safe';
+}
+
+// ── Tool → tier (non-shell) ─────────────────────────────────────────────
+
+const READ_TOOLS = new Set([
+  'read_file', 'read_files',
+  'search_code', 'search_files', 'grep',
+  'list_files', 'get_file_info', 'get_project_overview',
+  'git_status', 'git_diff',
+  'analyze_code',
+  'validate_file', 'validate_structure',
+]);
+
+const LOCAL_EDIT_TOOLS = new Set([
+  'edit_file', 'write_file', 'write_project',
+]);
+
+const DESTRUCTIVE_TOOLS = new Set([
+  'delete_file',
+]);
+
+const NETWORK_TOOLS = new Set([
+  'WebFetch', 'fetch_url',
+]);
+
+// ── Shell sub-classifier ────────────────────────────────────────────────
+
+const SHELL_SAFE_RE = [
+  // Inspection / read-only
+  /^\s*(ls|cat|head|tail|less|more|wc|file|stat|tree|find|grep|rg|ag|fd|echo|printf|pwd|whoami|date|which|type|env|printenv|uname|hostname|id|df|du|uptime|free|top|ps|lsof)\b/i,
+  /^\s*git\s+(status|log|diff|show|branch|tag|remote|stash\s+list|blame|shortlog|describe|rev-parse|ls-files|ls-tree|config\s+--get)\b/i,
+  // Test-only invocations
+  /^\s*(npm|pnpm|yarn)\s+(test|run\s+test|run\s+lint|list|ls|view|info|outdated)\b/i,
+  /^\s*node\s+--check\b/i,
+  /^\s*python3?\s+-m\s+py_compile\b/i,
+  /^\s*pytest\b(?!.*--?(delete|rm|destructive))/i,
+  /^\s*cargo\s+(check|test|clippy|build)\b/i,
+  /^\s*go\s+(test|vet|build)\b/i,
+  /^\s*make\s+(test|check|lint|build)\b/i,
+];
+
+const SHELL_DANGEROUS_RE = [
+  /\brm\s+-r/i,
+  /\brm\s+--recursive/i,
+  /\brm\s+-rf?\b/i,
+  /\bunlink\s/i,
+  /\brmdir\s+-/i,
+  /\bgit\s+push.*--force/i,
+  /\bgit\s+push.*-f\b/i,
+  /\bgit\s+reset\s+--hard/i,
+  /\bgit\s+clean\s+-f/i,
+  /\bgit\s+checkout\s+\./i,
+  /\bgit\s+stash\s+drop/i,
+  /\bgit\s+branch\s+-D/i,
+  /\bgit\s+filter-branch/i,
+  /\bsudo\b/i,
+  /\bsu\s+-/i,
+  /\bcurl\b.*\|\s*(sh|bash|zsh)/i,
+  /\bwget\b.*\|\s*(sh|bash|zsh)/i,
+  /\beval\s+["'$(]/i,
+  /\bkubectl\s+delete/i,
+  /\bdocker\s+(rm|rmi|system\s+prune|volume\s+rm|network\s+rm)/i,
+  /\bdrop\s+(table|database|schema)/i,
+  /\btruncate\s+table/i,
+  /\bmkfs\b/i,
+  /\bdd\s+if=/i,
+  /:\s*\(\s*\)\s*\{.*:\|/i, // fork bomb
+  />\s*\/dev\/sda/i,
+];
+
+const SHELL_MEDIUM_RE = [
+  /^\s*(npm|pnpm|yarn)\s+(install|i|add|remove|uninstall|update|upgrade|publish|deploy)\b/i,
+  /^\s*pip\s+(install|uninstall|--upgrade)\b/i,
+  /^\s*pipx\s+(install|uninstall)\b/i,
+  /^\s*brew\s+(install|uninstall|upgrade|update)\b/i,
+  /^\s*apt(-get)?\s+(install|remove|upgrade|update)\b/i,
+  /^\s*cargo\s+(install|uninstall|publish|run)\b/i,
+  /^\s*go\s+(install|get|mod\s+tidy|mod\s+download)\b/i,
+  /^\s*make(\s|$)/i,
+  /^\s*git\s+(commit|push|pull|merge|rebase|fetch|checkout(?!\s+\.)|cherry-pick|revert|tag|stash(?!\s+drop))/i,
+  /^\s*docker\s+(build|run|exec|compose|pull|push|tag)/i,
+];
+
+export function classifyShell(command) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return TIERS.SHELL_MEDIUM;
+
+  // Dangerous wins over safe — never let a safe-looking prefix mask `&& rm -rf`.
+  if (SHELL_DANGEROUS_RE.some(re => re.test(cmd))) return TIERS.SHELL_DANGEROUS;
+
+  // For a chained command, classify each segment and take the riskiest —
+  // never let a safe-looking prefix mask `&& npm install` or worse.
+  if (/&&|\|\||;|\|(?!\|)/.test(cmd)) {
+    const segments = splitShellSegments(cmd);
+    if (segments.length > 1) {
+      let worst = TIERS.SHELL_SAFE;
+      for (const seg of segments) {
+        const t = classifyShell(seg);
+        worst = riskier(worst, t);
+        if (worst === TIERS.SHELL_DANGEROUS) return worst;
+      }
+      return worst;
+    }
+  }
+
+  if (SHELL_MEDIUM_RE.some(re => re.test(cmd))) return TIERS.SHELL_MEDIUM;
+  if (SHELL_SAFE_RE.some(re => re.test(cmd)))   return TIERS.SHELL_SAFE;
+  return TIERS.SHELL_MEDIUM;
+}
+
+function splitShellSegments(cmd) {
+  // Split on top-level &&, ||, ;, | — naive but enough for the classifier.
+  return cmd.split(/&&|\|\||;|\|/).map(s => s.trim()).filter(Boolean);
+}
+
+const TIER_ORDER = [
+  TIERS.READ,
+  TIERS.SHELL_SAFE,
+  TIERS.LOCAL_EDIT,
+  TIERS.NETWORK,
+  TIERS.SHELL_MEDIUM,
+  TIERS.DESTRUCTIVE,
+  TIERS.SHELL_DANGEROUS,
+];
+
+function riskier(a, b) {
+  return TIER_ORDER.indexOf(b) > TIER_ORDER.indexOf(a) ? b : a;
+}
+
+// ── Top-level classify ──────────────────────────────────────────────────
+
+/**
+ * Classify a tool call into a risk tier. Always returns one of TIERS.
+ *
+ * @param {string} tool   Tool name (e.g. 'shell', 'edit_file')
+ * @param {object} args   Tool arguments (e.g. { command: 'rm -rf x' })
+ */
+export function classify(tool, args = {}) {
+  if (!tool) return TIERS.SHELL_MEDIUM;
+
+  if (READ_TOOLS.has(tool))        return TIERS.READ;
+  if (LOCAL_EDIT_TOOLS.has(tool))  return TIERS.LOCAL_EDIT;
+  if (DESTRUCTIVE_TOOLS.has(tool)) return TIERS.DESTRUCTIVE;
+  if (NETWORK_TOOLS.has(tool))     return TIERS.NETWORK;
+
+  if (tool === 'shell' || tool === 'run_tests' || tool === 'validate_build' || tool === 'lint_check') {
+    return classifyShell(args.command || args.cmd || '');
+  }
+
+  // Sub-agents inherit their parent's risk (read-ish by default).
+  if (['explore', 'plan', 'verify', 'debug', 'refactor', 'analyze_code'].includes(tool)) {
+    return TIERS.READ;
+  }
+
+  // MCP tools: assume network unless the name implies read.
+  if (tool.startsWith('mcp')) {
+    return /(?:read|get|list|search|describe|info|status)/i.test(tool) ? TIERS.READ : TIERS.NETWORK;
+  }
+
+  return TIERS.SHELL_MEDIUM;
+}
+
+/**
+ * Convenience: human label for a tier (used in approval prompts and the
+ * status bar). Returned strings already uppercased / hyphenated.
+ */
+export function label(tier) {
+  switch (tier) {
+    case TIERS.READ:            return 'READ';
+    case TIERS.LOCAL_EDIT:      return 'LOCAL-EDIT';
+    case TIERS.SHELL_SAFE:      return 'SHELL-SAFE';
+    case TIERS.SHELL_MEDIUM:    return 'SHELL-MEDIUM';
+    case TIERS.SHELL_DANGEROUS: return 'SHELL-DANGEROUS';
+    case TIERS.DESTRUCTIVE:     return 'DESTRUCTIVE';
+    case TIERS.NETWORK:         return 'NETWORK';
+    default:                    return String(tier || '').toUpperCase();
+  }
+}
+
+/**
+ * Whether the tool needs an explicit human keystroke before running.
+ */
+export function requiresExplicitApproval(tier) {
+  return behavior(tier) === 'prompt-explicit';
+}
+
+/**
+ * Whether the tier should auto-create an undo checkpoint before running.
+ */
+export function requiresCheckpoint(tier) {
+  return behavior(tier) === 'auto-with-undo';
+}