@bahulam/code 2.6.14 → 2.6.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "2.6.14",
+  "version": "2.6.16",
   "description": "Bahulam Code \u2014 abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-live-steering-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
+    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-render-queue.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-live-steering-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -49,8 +49,8 @@
     "web-tree-sitter": "^0.26.9"
   },
   "optionalDependencies": {
-    "@bahulam/runtime-darwin-arm64": "2.6.14",
-    "@bahulam/runtime-linux-x64": "2.6.14",
-    "@bahulam/runtime-win32-x64": "2.6.14"
+    "@bahulam/runtime-darwin-arm64": "2.6.16",
+    "@bahulam/runtime-linux-x64": "2.6.16",
+    "@bahulam/runtime-win32-x64": "2.6.16"
   }
 }

package/src/auth/tarang-auth.mjs

@@ -76,6 +76,12 @@ export class TarangAuth {
             models: this._config.models || {},
             configuredProviders: this._config.configured_providers || [],
             gatewayConfig: this._config.gateway_config || {},
+            // PRD-076 W7: persisted /model picks. `modelConfig` mirrors the
+            // Python-side key read_local_model_config() looks for; keep the
+            // snake_case JSON key so the runtime picks it up unchanged.
+            modelConfig: this._config.model_config || {},
+            modelMode: this._config.model_mode || null,
+            routePreference: this._config.route_preference || null,
         };
     }
 

package/src/config/cli-args.mjs

@@ -29,6 +29,7 @@ export function parseArgs(args) {
         timeout: null,
         allowedTools: null,
         disallowedTools: null,
+        route: null,
         resume: false,
         resumeSessionId: null,
         headless: false,
@@ -49,6 +50,10 @@ export function parseArgs(args) {
                 result.model = args[++i];
                 break;
 
+            case '--route':
+                result.route = args[++i];
+                break;
+
             case '--permission-mode':
                 result.permissionMode = args[++i];
                 break;
@@ -169,7 +174,8 @@ export function getUsageText() {
 Usage: occ [options] [prompt]
 
 Options:
-  --model, -m <model>        Model to use (default: claude-sonnet-4-6)
+  --model, -m <id|role=id>   Session model override (also named modes: fast|thinking|extra|max)
+  --route <platform|byok>    Model route; platform validates against the curated catalog
   --permission-mode <mode>   Permission mode (bypassPermissions, acceptEdits, plan, auto, dontAsk)
   --print, -p <prompt>       Non-interactive mode: run prompt and exit
   --output-format <fmt>      Output format: text, json, stream-json

package/src/config/model-catalog.mjs

@@ -0,0 +1,57 @@
+/**
+ * Shipped model catalog snapshot — Node side of PRD-076 W7.
+ *
+ * The canonical source is `codekepler-backend/app/services/
+ * model_catalog_snapshot.json` (admin dashboard edits it and publishes to
+ * Supabase). `stage-runtime-app.sh` copies that file into every runtime
+ * wheel at `runtime/app/services/model_catalog_snapshot.json`, so when
+ * `@bahulam/runtime-<platform>-<arch>` is installed as a sibling optional
+ * dep of `@bahulam/code`, the file is already on disk — we read from
+ * there instead of maintaining a third copy in the CLI package.
+ */
+
+import * as fs from 'node:fs';
+import { runtimeSnapshotPath } from '../core/bundled-runtime.mjs';
+
+let _cache = null;
+
+// Snapshot rows are camelCase (matches how the backend delivers the
+// static file); the /api/models response is snake_case. Normalize once
+// here so downstream consumers can treat both sources identically.
+function normalizeSnapshotRow(row) {
+  const id = row.value || row.id;
+  if (!id) return null;
+  return {
+    id,
+    provider: row.provider || (id.includes('/') ? id.split('/', 1)[0] : 'unknown'),
+    label: row.label || id,
+    input_cost_usd_per_m: row.inputCost ?? row.input_cost_usd_per_m ?? null,
+    output_cost_usd_per_m: row.outputCost ?? row.output_cost_usd_per_m ?? null,
+    context_length: row.context ?? row.context_length ?? null,
+    max_output: row.maxOutput ?? row.max_output ?? null,
+    supports_tools: row.supportsTools ?? row.supports_tools ?? false,
+    supports_reasoning: row.supportsReasoning ?? row.supports_reasoning ?? false,
+    harness_validated: row.harnessValidated ?? row.harness_validated ?? false,
+    cache_profile: row.cacheProfile ?? row.cache_profile ?? null,
+    platform_access_tier: row.platformAccessTier ?? row.platform_access_tier ?? [],
+  };
+}
+
+/**
+ * Read the shipped catalog snapshot from the installed runtime bundle.
+ * Returns an array of normalized rows (API-shape) or null if the runtime
+ * isn't installed / the file is unreadable. Cached after first success.
+ */
+export function readShippedCatalog() {
+  if (_cache !== null) return _cache;
+  try {
+    const raw = fs.readFileSync(runtimeSnapshotPath(), 'utf-8');
+    const data = JSON.parse(raw);
+    const rows = Array.isArray(data?.models) ? data.models : [];
+    _cache = rows.map(normalizeSnapshotRow).filter(Boolean);
+    return _cache;
+  } catch {
+    _cache = null;
+    return null;
+  }
+}

package/src/core/approval-log.mjs

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { isSensitiveConfigPath } from './safety.mjs';
 
 const REDACTED = 'REDACTED';
 const MAX_ARG_LOG_CHARS = 4000;
@@ -53,10 +54,32 @@ function sanitizeForLog(value, depth = 0) {
 function safeArgs(args) {
   if (args?.command) return redactSensitive(String(args.command)).slice(0, MAX_ARG_LOG_CHARS);
   if (args?.file_path || args?.path) return redactSensitive(String(args.file_path || args.path)).slice(0, MAX_ARG_LOG_CHARS);
+  if (Array.isArray(args?.files)) {
+    try {
+      const { files, ...rest } = args;
+      return JSON.stringify({
+        ...sanitizeForLog(rest),
+        files: files.slice(0, 100).map(file => sanitizeProjectFileArg(file)),
+      }).slice(0, MAX_ARG_LOG_CHARS);
+    } catch {
+      return '[files omitted]';
+    }
+  }
   try { return JSON.stringify(sanitizeForLog(args || {})).slice(0, MAX_ARG_LOG_CHARS); }
   catch { return redactSensitive(String(args || '')).slice(0, MAX_ARG_LOG_CHARS); }
 }
 
+function sanitizeProjectFileArg(file) {
+  if (typeof file === 'string') return redactSensitive(file);
+  if (!file || typeof file !== 'object') return sanitizeForLog(file);
+  const out = sanitizeForLog(file);
+  const filePath = file.path || file.file_path || '';
+  if (isSensitiveConfigPath(filePath) && typeof out.content === 'string') {
+    out.content = '[redacted sensitive config]';
+  }
+  return out;
+}
+
 function safeText(value, max = 500) {
   if (!value) return undefined;
   return redactSensitive(String(value)).slice(0, max);

package/src/core/approval.mjs

@@ -25,7 +25,7 @@ import {
   defaultOptions as approvalOptions,
 } from '../ui/approval.mjs';
 import { clearInputPrompt, isInputDockMounted, moveToContent, renderDockOverlay } from '../ui/input-dock.mjs';
-import { validateShellCommand } from './safety.mjs';
+import { isApprovalRequiredWritePath, isSensitiveConfigPath, validateShellCommand } from './safety.mjs';
 import { classifyCommand } from '../permissions/command-classifier.mjs';
 import { ApprovalLog } from './approval-log.mjs';
 import { TrustStore } from './trust.mjs';
@@ -46,9 +46,19 @@ const WRITE_TOOLS = new Set([
 
 function defaultWhy(tier, tool, args) {
     const subject = approvalSummary(tool, args);
+    const protectedTarget = protectedWriteTarget(tool, args);
+    if (protectedTarget) {
+        const target = protectedTarget.path;
+        if (protectedTarget.sensitive) {
+            return `Edits sensitive environment config (${target}). Confirm before writing; values stay redacted in summaries and diffs.`;
+        }
+        return `Edits protected project file (${subject || target}). Confirm before writing.`;
+    }
     switch (tier) {
         case TIERS.SENSITIVE_READ:
             return `Reads a sensitive path (${subject || 'secret-like file'}). Confirm before exposing its contents to the agent.`;
+        case TIERS.PROTECTED_EDIT:
+            return `Edits a protected project file. Confirm before writing.`;
         case TIERS.SHELL_DANGEROUS:
             return `Shell command matches a high-risk pattern (rm -rf, sudo, force push, etc.). Confirm before running.`;
         case TIERS.DESTRUCTIVE:
@@ -62,6 +72,26 @@ function defaultWhy(tier, tool, args) {
     }
 }
 
+function protectedWriteTarget(tool, args = {}) {
+    const paths = writeTargetPaths(tool, args);
+    const path = paths.find(isApprovalRequiredWritePath);
+    if (!path) return null;
+    return { path, sensitive: isSensitiveConfigPath(path) };
+}
+
+function writeTargetPaths(tool, args = {}) {
+    const key = String(tool || '').toLowerCase();
+    if (key === 'write_file' || key === 'edit_file') {
+        return [args.file_path || args.path].filter(Boolean);
+    }
+    if (key === 'write_project') {
+        return (args.files || [])
+            .map(file => typeof file === 'string' ? file : file?.path || file?.file_path)
+            .filter(Boolean);
+    }
+    return [];
+}
+
 function approvalSummary(tool, args = {}) {
     const summary = toolDisplaySummary(tool, args);
     if (tool !== 'shell') return summary;
@@ -118,6 +148,8 @@ export class ApprovalManager {
         this.history = [];
         this.rejectionHints = [];
         this._rl = null;
+        this._approvalPromptActive = false;
+        this._approvalPromptWasRaw = false;
     }
 
     setReadline(rl) { this._rl = rl; }
@@ -128,6 +160,29 @@ export class ApprovalManager {
         this._approvalPromptEnd = onApprovalPromptEnd || null;
     }
 
+    _beginApprovalInput() {
+        if (this._approvalPromptActive || !process.stdin.isTTY) return false;
+        this._approvalPromptActive = true;
+        this._approvalPromptWasRaw = process.stdin.isRaw;
+        if (this._execPause) this._execPause();
+        if (this._rl) this._rl.pause();
+        if (typeof process.stdin.setRawMode === 'function') {
+            process.stdin.setRawMode(true);
+        }
+        process.stdin.resume();
+        return true;
+    }
+
+    _endApprovalInput() {
+        if (!this._approvalPromptActive) return;
+        if (typeof process.stdin.setRawMode === 'function') {
+            process.stdin.setRawMode(this._approvalPromptWasRaw || false);
+        }
+        if (this._rl) this._rl.resume();
+        if (this._execResume) this._execResume();
+        this._approvalPromptActive = false;
+    }
+
     revoke() {
         const wasActive = this.approveAll || this.approvedToolTypes.size > 0;
         this.approveAll = false;
@@ -275,6 +330,9 @@ export class ApprovalManager {
             printedHeight = block.split('\n').length;
         };
 
+        const ownsApprovalInput = isInteractive ? this._beginApprovalInput() : false;
+
+        try {
         if (isInteractive) drawPrompt();
 
         // ── Input loop ─────────────────────────────────────────────────
@@ -334,7 +392,7 @@ export class ApprovalManager {
                 return { approved: true, tier };
 
             case 'allow-session': {
-                if (!this.policy.hitl?.allowSessionTrust) return this._prompt(toolName, args, context);
+                if (!this.policy.hitl?.allowSessionTrust) return await this._prompt(toolName, args, context);
                 const rule = this.trustStore.add({ tool: toolName, args, tier, scope: 'SESSION' });
                 write(`  ${GREEN}✓${RST}  ${DIM}trusted for this session: ${rule.pattern}${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'session-trust', tier, time: Date.now(), rule_id: rule.id });
@@ -343,7 +401,7 @@ export class ApprovalManager {
             }
 
             case 'allow-project': {
-                if (!this.policy.hitl?.allowProjectTrust) return this._prompt(toolName, args, context);
+                if (!this.policy.hitl?.allowProjectTrust) return await this._prompt(toolName, args, context);
                 const rule = this.trustStore.add({ tool: toolName, args, tier, scope: 'PROJECT' });
                 write(`  ${GREEN}✓${RST}  ${DIM}trusted for this project: ${rule.pattern}${RST}\n\n`);
                 this.history.push({ tool: toolName, decision: 'project-trust', tier, time: Date.now(), rule_id: rule.id });
@@ -362,7 +420,7 @@ export class ApprovalManager {
             }
 
             case 'allow-all':
-                if (requiresExplicitApproval(tier)) return this._prompt(toolName, args, context);
+                if (requiresExplicitApproval(tier)) return await 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', tier, time: Date.now() });
@@ -370,7 +428,7 @@ export class ApprovalManager {
                 return { approved: true, tier };
 
             case 'allow-type':
-                if (requiresExplicitApproval(tier)) return this._prompt(toolName, args, context);
+                if (requiresExplicitApproval(tier)) return await this._prompt(toolName, args, context);
                 this.approvedToolTypes.add(toolName);
                 this.history.push({ tool: toolName, decision: 'type-approve', tier, time: Date.now() });
                 this.approvalLog.append({ tool: toolName, args, tier, decision: 'type-approve', scope: 'session', prompt });
@@ -380,7 +438,7 @@ export class ApprovalManager {
             case 'why':
                 write(`\n  ${DIM}${(context.reason || why).slice(0, 400)}${RST}\n\n`);
                 printedHeight = 0;
-                return this._prompt(toolName, args, context);
+                return await this._prompt(toolName, args, context);
 
             case 'edit':
             case 'replan':
@@ -395,7 +453,10 @@ export class ApprovalManager {
             }
 
             default:
-                return this._prompt(toolName, args, context);
+                return await this._prompt(toolName, args, context);
+        }
+        } finally {
+            if (ownsApprovalInput) this._endApprovalInput();
         }
     }
 
@@ -406,16 +467,25 @@ export class ApprovalManager {
                 return;
             }
 
-            if (this._execPause) this._execPause();
-            if (this._rl) this._rl.pause();
+            const managesInput = !this._approvalPromptActive;
+            if (managesInput) {
+                if (this._execPause) this._execPause();
+                if (this._rl) this._rl.pause();
+            }
 
             const wasRaw = process.stdin.isRaw;
-            process.stdin.setRawMode(true);
+            if (managesInput && typeof process.stdin.setRawMode === 'function') {
+                process.stdin.setRawMode(true);
+            }
             process.stdin.resume();
             process.stdin.once('data', (data) => {
-                process.stdin.setRawMode(wasRaw || false);
-                if (this._rl) this._rl.resume();
-                if (this._execResume) this._execResume();
+                if (managesInput) {
+                    if (typeof process.stdin.setRawMode === 'function') {
+                        process.stdin.setRawMode(wasRaw || false);
+                    }
+                    if (this._rl) this._rl.resume();
+                    if (this._execResume) this._execResume();
+                }
 
                 const bytes = [...data];
                 const str = data.toString();
@@ -444,8 +514,11 @@ export class ApprovalManager {
                 return;
             }
 
-            if (this._execPause) this._execPause();
-            if (this._rl) this._rl.pause();
+            const managesInput = !this._approvalPromptActive;
+            if (managesInput) {
+                if (this._execPause) this._execPause();
+                if (this._rl) this._rl.pause();
+            }
 
             const wasRaw = process.stdin.isRaw;
             if (typeof process.stdin.setRawMode === 'function') {
@@ -460,8 +533,10 @@ export class ApprovalManager {
                 if (typeof process.stdin.setRawMode === 'function') {
                     process.stdin.setRawMode(wasRaw || false);
                 }
-                if (this._rl) this._rl.resume();
-                if (this._execResume) this._execResume();
+                if (managesInput) {
+                    if (this._rl) this._rl.resume();
+                    if (this._execResume) this._execResume();
+                }
             };
             const finish = () => {
                 cleanup();
@@ -535,6 +610,7 @@ function promptForLog(tool, args, tier, why) {
 function approvalTitleForLog(tier) {
     switch (tier) {
         case TIERS.SENSITIVE_READ:
+        case TIERS.PROTECTED_EDIT:
         case TIERS.SHELL_DANGEROUS:
         case TIERS.DESTRUCTIVE:
             return 'EXPLICIT APPROVAL';

package/src/core/bundled-runtime.mjs

@@ -364,6 +364,18 @@ export function isRuntimeInstalled() {
   return fs.existsSync(_runtimeBin());
 }
 
+/**
+ * Absolute path to the shipped model catalog snapshot inside the runtime
+ * bundle. Backend edits `app/services/model_catalog_snapshot.json` as the
+ * canonical source (admin dashboard publishes it to Supabase);
+ * stage-runtime-app.sh copies that same file into every runtime wheel at
+ * `runtime/app/services/model_catalog_snapshot.json`. The CLI reads from
+ * there so there is no third copy to keep in sync.
+ */
+export function runtimeSnapshotPath() {
+  return path.join(_runtimeRoot(), 'runtime', 'app', 'services', 'model_catalog_snapshot.json');
+}
+
 /** Diagnostic snapshot for `bahulam doctor`. */
 export function runtimeInfo() {
   return {

package/src/core/error-guidance.mjs

@@ -251,12 +251,16 @@ export function formatAgentErrorGuidance(data = {}) {
     lines.push('Upgrade your plan for a larger 5-hour message window, or switch to BYOK if available.');
     if (pricingUrl) lines.push(`Open ${pricingUrl} to upgrade.`);
   } else if (phase === 'gateway' || code.includes('gateway')) {
-    const label = providerGuidance?.label || 'provider';
-    lines.push(`The ${label} gateway failed before the agent could respond.`);
-    if (providerGuidance) {
+    // Generic first: on the platform route the user has NO provider key —
+    // telling them to "check your DeepSeek API key" is wrong and alarming.
+    // Provider-key guidance only applies when we know the route is BYOK.
+    const label = providerGuidance?.label || compact(data.provider) || 'model provider';
+    lines.push(`The upstream ${label} request failed before the agent could respond — usually a transient provider-side error.`);
+    lines.push('Retry the turn. If it persists, switch models with /model and try again.');
+    if (compact(data.route) === 'byok' && providerGuidance) {
       lines.push(...providerGuidance.lines);
     } else {
-      lines.push('Check the selected provider, model, and BYOK credentials in settings, then retry.');
+      lines.push('Using your own key (BYOK)? Verify it is saved and active in settings, then run /login so provider settings sync.');
     }
   } else if (/authentication|token/i.test(message)) {
     lines.push('Run /login to re-authenticate.');

package/src/core/file-diff.mjs

@@ -8,7 +8,7 @@ export function buildFileDiff({
   after = '',
   cwd = process.cwd(),
   context = 3,
-  maxDiffLines = 400,
+  maxDiffLines = Infinity,
 } = {}) {
   const oldText = before == null ? '' : String(before);
   const newText = after == null ? '' : String(after);

package/src/core/local-agent.mjs

@@ -21,11 +21,11 @@ const MAX_ITERATIONS = 50;
 const TOOL_SCHEMAS = [
     {
         name: 'shell',
-        description: 'Run one non-interactive shell command and return stdout/stderr. Do not use command substitution, backticks, or $(); run separate simple shell calls instead.',
+        description: 'Run one non-interactive shell command and return stdout/stderr. Command substitution (backticks, $()) is allowed but triggers a user-approval prompt; prefer plain commands when equivalent.',
         input_schema: {
             type: 'object',
             properties: {
-                command: { type: 'string', description: 'The command to execute. Avoid backticks and $(); split dependent checks into separate commands.' },
+                command: { type: 'string', description: 'The command to execute. Backticks/$() are allowed (user approval required); use them when splitting would be awkward.' },
                 timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000)' },
             },
             required: ['command'],
@@ -478,7 +478,7 @@ export class LocalAgent {
             'You are Bahulam Code, Bahulam\'s AI coding agent running in local mode.',
             'You have access to tools for reading, writing, and executing code.',
             'Use tools to accomplish the user\'s request. Be concise and direct.',
-            'For shell tools, never use command substitution, backticks, or $(). Run separate simple commands and carry values forward in text.',
+            'Shell command substitution (backticks, $()) is allowed but requires user approval — use it when it is the natural expression; otherwise prefer plain commands.',
         ];
         if (context.cwd) parts.push(`Working directory: ${context.cwd}`);
         if (context.gitBranch) parts.push(`Git branch: ${context.gitBranch}`);

package/src/core/risk-tier.mjs

@@ -14,12 +14,15 @@
  * intent can't be hidden behind a friendly description.
  */
 
+import { isApprovalRequiredWritePath, isSensitiveConfigPath } from './safety.mjs';
+
 // ── Tier enum ────────────────────────────────────────────────────────────
 
 export const TIERS = Object.freeze({
   READ:            'read',
   SENSITIVE_READ:  'sensitive-read',
   LOCAL_EDIT:      'local-edit',
+  PROTECTED_EDIT:  'protected-edit',
   SHELL_SAFE:      'shell-safe',
   SHELL_MEDIUM:    'shell-medium',
   SHELL_DANGEROUS: 'shell-dangerous',
@@ -38,6 +41,7 @@ export const BEHAVIOR = Object.freeze({
   [TIERS.READ]:            'auto',
   [TIERS.SENSITIVE_READ]:  'prompt-explicit',
   [TIERS.LOCAL_EDIT]:      'auto-with-undo',
+  [TIERS.PROTECTED_EDIT]:  'prompt-explicit',
   [TIERS.SHELL_SAFE]:      'auto',
   [TIERS.SHELL_MEDIUM]:    'prompt-safe',
   [TIERS.SHELL_DANGEROUS]: 'prompt-explicit',
@@ -77,6 +81,14 @@ const LOCAL_EDIT_TOOLS = new Set([
   'workflow_create_multi', 'workflow_sync_multi',
 ]);
 
+const WRITE_PATH_KEYS = [
+  'path', 'file_path', 'file', 'target',
+];
+
+const WRITE_PATH_ARRAY_KEYS = [
+  'paths', 'file_paths', 'targets',
+];
+
 const DESTRUCTIVE_TOOLS = new Set([
   'delete_file', 'skill_remove',
 ]);
@@ -219,6 +231,7 @@ const TIER_ORDER = [
   TIERS.SENSITIVE_READ,
   TIERS.SHELL_SAFE,
   TIERS.LOCAL_EDIT,
+  TIERS.PROTECTED_EDIT,
   TIERS.NETWORK,
   TIERS.SHELL_MEDIUM,
   TIERS.DESTRUCTIVE,
@@ -243,7 +256,9 @@ export function classify(tool, args = {}) {
   if (READ_TOOLS.has(tool)) {
     return isSensitiveRead(args) ? TIERS.SENSITIVE_READ : TIERS.READ;
   }
-  if (LOCAL_EDIT_TOOLS.has(tool))  return TIERS.LOCAL_EDIT;
+  if (LOCAL_EDIT_TOOLS.has(tool)) {
+    return isApprovalRequiredWrite(args) ? TIERS.PROTECTED_EDIT : TIERS.LOCAL_EDIT;
+  }
   if (DESTRUCTIVE_TOOLS.has(tool)) return TIERS.DESTRUCTIVE;
   if (NETWORK_TOOLS.has(tool))     return TIERS.NETWORK;
 
@@ -273,6 +288,7 @@ export function label(tier) {
     case TIERS.READ:            return 'READ';
     case TIERS.SENSITIVE_READ:  return 'SENSITIVE-READ';
     case TIERS.LOCAL_EDIT:      return 'LOCAL-EDIT';
+    case TIERS.PROTECTED_EDIT:  return 'PROTECTED-EDIT';
     case TIERS.SHELL_SAFE:      return 'SHELL-SAFE';
     case TIERS.SHELL_MEDIUM:    return 'SHELL-MEDIUM';
     case TIERS.SHELL_DANGEROUS: return 'SHELL-DANGEROUS';
@@ -310,11 +326,15 @@ export function isSensitiveReadPath(filePath = '') {
 
   const parts = normalized.split('/').filter(Boolean);
   const base = parts[parts.length - 1] || normalized;
-  if (base === '.env') return true;
+  if (isSensitiveConfigPath(base)) return true;
   if (/\.pem$/i.test(base)) return true;
   return parts.includes('secrets');
 }
 
+export function isApprovalRequiredWrite(args = {}) {
+  return extractWritePaths(args).some(isApprovalRequiredWritePath);
+}
+
 function extractReadPaths(args = {}) {
   const paths = [];
   for (const key of READ_PATH_KEYS) {
@@ -335,3 +355,34 @@ function extractReadPaths(args = {}) {
   }
   return paths;
 }
+
+function extractWritePaths(args = {}) {
+  const paths = [];
+  for (const key of WRITE_PATH_KEYS) {
+    if (typeof args[key] === 'string') paths.push(args[key]);
+  }
+  for (const key of WRITE_PATH_ARRAY_KEYS) {
+    const value = args[key];
+    if (!Array.isArray(value)) continue;
+    for (const item of value) {
+      if (typeof item === 'string') {
+        paths.push(item);
+      } else if (item && typeof item === 'object') {
+        for (const nestedKey of WRITE_PATH_KEYS) {
+          if (typeof item[nestedKey] === 'string') paths.push(item[nestedKey]);
+        }
+      }
+    }
+  }
+  if (Array.isArray(args.files)) {
+    for (const item of args.files) {
+      if (typeof item === 'string') paths.push(item);
+      else if (item && typeof item === 'object') {
+        for (const nestedKey of WRITE_PATH_KEYS) {
+          if (typeof item[nestedKey] === 'string') paths.push(item[nestedKey]);
+        }
+      }
+    }
+  }
+  return paths;
+}