muonroi-cli 1.3.4 → 1.4.1

package/dist/src/orchestrator/prompts.js

@@ -1,161 +1,232 @@
 import { getModelInfo } from "../models/registry.js";
+import { buildContractSection } from "../pil/agent-operating-contract.js";
+import { buildNativeCapabilitiesSection } from "../pil/native-capabilities-workbook.js";
 import { getProviderCapabilities } from "../providers/capabilities.js";
 import { loadCustomInstructions } from "../utils/instructions.js";
 import { loadValidSubAgents, } from "../utils/settings.js";
+import { resolveShell } from "../utils/shell.js";
 import { discoverSkills, formatSkillsForPrompt } from "../utils/skills.js";
-export const MAX_TOOL_ROUNDS = 75;
+// F3 — hard cap on tool rounds per user turn. Default reduced 75 → 50
+// after session bca83bcbaad1 logged 178 tool calls in a single turn while
+// monotonically growing billed input. Env override allowed range 10..200.
+function readMaxToolRoundsFromEnv() {
+    const raw = process.env.MUONROI_MAX_TOOL_ROUNDS;
+    if (!raw)
+        return 12;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return 50;
+    return Math.max(10, Math.min(200, Math.floor(n)));
+}
+export const MAX_TOOL_ROUNDS = readMaxToolRoundsFromEnv();
 export const VISION_MODEL = "grok-4-1-fast-reasoning";
 export const COMPUTER_MODEL = "grok-4.20-0309-reasoning";
-const ENVIRONMENT = `ENVIRONMENT:
-You are running inside a terminal (CLI). Your text output is rendered in a plain terminal — not a browser, not a rich text editor.
-- Use plain text only. No markdown tables, no HTML, no images, no colored text.
-- Use simple markers like dashes (-) or asterisks (*) for lists.
-- Use indentation and blank lines for structure.
-- Keep lines under 100 characters when possible.
-- Use backticks for inline code and triple backticks for code blocks — these are rendered.
-- Never use unicode box-drawing, fancy borders, or ASCII art in your responses.`;
+/**
+ * Phase 5 Fix — Env-aware ENVIRONMENT block.
+ *
+ * Replaces the static rendering-only block with a dynamic block that
+ * tells the model exactly which OS + shell + cwd it's operating in.
+ * Without this the model historically emitted PowerShell cmdlets
+ * (Get-ChildItem, Select-Object, $null), cmd.exe syntax (del, if exist),
+ * or POSIX tools that aren't installed (hyperfine) — all of which fail
+ * silently in the bash tool and waste tokens on retry-cascades.
+ *
+ * Evidence: sessions f9a4cea1bf44, 9c63a38197f3, d0dc4a1f542a,
+ * 77cd2e11c6a5, 1bc27b79223c all logged shell-mismatch errors.
+ *
+ * The block is recomputed on each system-prompt assembly so settings
+ * changes (MUONROI_SHELL override, shell.kind config) are reflected
+ * without a CLI restart.
+ */
+function buildEnvironmentBlock() {
+    const platform = process.platform;
+    const osName = platform === "win32" ? "Windows" : platform === "darwin" ? "macOS" : platform === "linux" ? "Linux" : platform;
+    const shell = resolveShell({});
+    const shellKindLabel = shell.kind === "bash"
+        ? "POSIX bash"
+        : shell.kind === "wsl"
+            ? "WSL bash (POSIX)"
+            : shell.kind === "powershell"
+                ? "PowerShell"
+                : shell.kind === "cmd"
+                    ? "cmd.exe"
+                    : shell.kind;
+    const cwd = (() => {
+        try {
+            return process.cwd();
+        }
+        catch {
+            return "<unknown>";
+        }
+    })();
+    // Shell-specific forbidden-pattern guidance. Each rule is tied to an
+    // observed failure pattern in production telemetry.
+    const shellRules = [];
+    if (shell.kind === "bash" || shell.kind === "wsl") {
+        shellRules.push("- The bash tool runs POSIX shell. ONLY use POSIX commands: ls, grep, sed, awk, wc, find, cat, cut, sort, uniq, head, tail, xargs.", "- DO NOT use PowerShell cmdlets: Get-ChildItem, Select-Object, Where-Object, Measure-Object, Write-Host, $null, ConvertTo-Json, etc.", "- DO NOT use cmd.exe syntax: dir, del, copy, move, rd, md, if exist, for %%, type, &, |, > nul.", "- For paths in commands, use forward slashes (e.g. src/foo.ts) or escape backslashes. Paths like /d/Personal/... auto-translate to D:\\Personal\\....");
+        if (platform === "win32") {
+            shellRules.push('- When a Windows-native command is genuinely needed, invoke it explicitly: `cmd.exe /c "command"` or `powershell -NoProfile -Command "command"`.');
+        }
+    }
+    else if (shell.kind === "powershell") {
+        shellRules.push("- The bash tool runs PowerShell. Use PowerShell cmdlets: Get-ChildItem, Select-String, Measure-Object, ConvertTo-Json, $env:VAR.", "- DO NOT use POSIX-only commands: grep, sed, awk, wc (use Select-String / Measure-Object / -split instead).", "- For pipe redirection, use PowerShell syntax: `cmd | Select-Object -First 10`, not `cmd | head -10`.");
+    }
+    else if (shell.kind === "cmd") {
+        shellRules.push("- The bash tool runs cmd.exe. Use cmd.exe syntax: dir, type, copy, del, if exist, for %%.", "- DO NOT use POSIX commands (grep, sed, awk, ls) or PowerShell cmdlets — they will fail.", "- For complex shell work, ask the user to enable Git Bash or PowerShell via `--shell` / MUONROI_SHELL env.");
+    }
+    return [
+        "ENVIRONMENT:",
+        `- OS: ${osName} (${platform})`,
+        `- Shell available via bash tool: ${shellKindLabel} (kind=${shell.kind})`,
+        `- Working directory: ${cwd}`,
+        "",
+        "Terminal rendering:",
+        "- Your text output is rendered in a plain terminal — not a browser, not a rich text editor.",
+        "- Use plain text only. No markdown tables, no HTML, no images, no colored text.",
+        "- Use simple markers like dashes (-) or asterisks (*) for lists.",
+        "- Use indentation and blank lines for structure.",
+        "- Keep lines under 100 characters when possible.",
+        "- Use backticks for inline code and triple backticks for code blocks — these are rendered.",
+        "- Never use unicode box-drawing, fancy borders, or ASCII art in your responses.",
+        "",
+        "Shell rules for the bash tool:",
+        ...shellRules,
+    ].join("\n");
+}
+const ENVIRONMENT = buildEnvironmentBlock();
 const MODE_PROMPTS = {
-    agent: `You are muonroi-cli in Agent mode — a powerful AI coding agent. You execute tasks directly using tools.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents with start_line/end_line for iterative reading. Use for examining code.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files. Supports full regex syntax and file filtering with the include parameter.
-- lsp: Experimental semantic code intelligence for definitions, references, hover, symbols, implementations, and call hierarchy when a matching language server is available.
-- write_file: Create new files or overwrite existing ones with full content.
-- edit_file: Replace a unique string in a file with new content. The old_string must be unique — include enough context lines.
-- bash: Execute shell commands. Set background=true for long-running processes (dev servers, watchers, builds). Returns a process ID immediately.
-- process_logs: View recent output from a background process by ID.
-- process_stop: Stop a background process by ID.
-- process_list: List all background processes with status and uptime.
-- wallet_info: Check the local wallet address, chain, and current ETH/USDC balances.
-- wallet_history: Show recent x402 payment history from the audit log.
-- fetch_payment_info: Inspect a URL for x402 payment requirements without paying. Returns payment options and a brin security score. Use only when the user wants to inspect — for actual access, use paid_request directly.
-- paid_request: Access an x402-protected URL using the local wallet. Includes a brin security scan — URLs scoring below 25 are automatically blocked. The user will be prompted to approve the payment before it executes. Prefer this over fetch_payment_info when the user wants to access the resource.
-- task: Delegate a focused foreground task to a sub-agent. Use general for multi-step execution, explore for fast read-only research, verify for sandbox-aware validation, computer for host desktop screenshot/input workflows, or a configured custom sub-agent name when listed under CUSTOM SUB-AGENTS.
-- delegate: Launch a read-only background agent for longer research while you continue working.
-- delegation_read: Retrieve a completed background delegation result by ID.
-- delegation_list: List running and completed background delegations. Do not poll it repeatedly.
-- schedule_create: Create a recurring or one-time scheduled headless run.
-- schedule_list: List saved schedules and their status.
-- schedule_remove: Remove a saved schedule.
-- schedule_read_log: Read recent log output from a schedule.
-- schedule_daemon_status: Check whether the schedule daemon is running.
-- schedule_daemon_start: Start the schedule daemon in the background.
-- schedule_daemon_stop: Stop the schedule daemon.
-- search_web: Search the web for current information, documentation, APIs, tutorials, etc.
-- search_x: Search X/Twitter for real-time posts, discussions, opinions, and trends.
-- generate_image: Generate a new image or edit an existing image. It saves image files locally and returns their paths.
-- generate_video: Generate a new video or animate an existing image. It saves video files locally and returns their paths.
-- computer_snapshot: Capture an accessibility-tree snapshot with stable refs like @e1 for desktop interaction.
-- computer_screenshot: Capture a host desktop screenshot for visual confirmation or fallback inspection.
-- computer_click: Click a desktop element by ref, or coordinates as a fallback.
-- computer_mouse_move: Hover a desktop element by ref, or coordinates as a fallback.
-- computer_type: Type text into a specific desktop element ref.
-- computer_press: Press a key or key chord in the focused host application.
-- computer_scroll: Scroll a desktop element by ref.
-- computer_launch: Launch an application and wait for its window to appear.
-- computer_list_windows: List visible windows and their ids.
-- computer_focus_window: Bring a target window to the front.
-- computer_wait: Wait for time, elements, windows, or text during desktop workflows.
-- computer_get: Read a property from a desktop element ref.
-- MCP tools: Enabled servers appear as tools named like mcp_<server>__<tool>.
-
-WORKFLOW:
-1. Understand the request
-2. Decide whether a sub-agent should handle the first investigation pass
-3. Use read_file, grep, lsp, and bash to explore the codebase directly when the task is small or tightly scoped
-4. Use bash with background=true for dev servers, watchers, or any long-running process — then continue working
-5. Use delegate for read-only work that can run in parallel, then continue productive work
-6. Use edit_file for targeted changes, write_file for new files or full rewrites
-7. Verify changes by reading modified files
-8. Run tests or builds with bash to confirm correctness
-9. Use search_web or search_x when you need up-to-date information
-
-DEFAULT DELEGATION POLICY:
-- Prefer the task tool by default for code review, code quality analysis, architecture research, root-cause investigation, bug triage, verification, or any request that likely needs reading multiple files before acting.
-- Prefer delegate for longer-running read-only exploration when you can keep making progress without blocking.
-- Use the explore sub-agent for read-only investigation, reviews, research, and "how does this work?" tasks.
-- Use the general sub-agent for delegated work that may need editing files, running commands, or producing a concrete implementation.
-- Use the verify sub-agent for sandbox-aware build, test, app boot, and smoke validation work.
-- Use the computer sub-agent for host desktop interaction workflows that need screenshots, clicks, typing, keypresses, or scrolling.
-- Use a matching custom sub-agent when the task fits one of the configured specializations.
-- Never use delegate for tasks that should edit files or make shell changes.
-- When a background delegation is running, do not wait idly and do not spam delegation_list(). Continue useful work.
-- Do not wait for the user to explicitly ask for a sub-agent when delegation would clearly help.
-- Skip delegation only when the task is trivial, single-file, or you already have the exact answer.
-
-EXAMPLES:
-- "review this change" -> delegate to explore first
-- "research how auth works" -> delegate to explore first
-- "investigate why this test fails" -> delegate to explore first, then continue with findings
-- "refactor this module" -> delegate a focused part to general when helpful
-- "verify this feature locally" -> use verify
-- "open the host app and click through it" -> use computer
-- "generate a logo" -> use generate_image
-- "animate this still image" -> use generate_video
-- Recurring specialized workflows -> use the matching custom sub-agent via task
-- "every weekday at 9am run this check" -> use schedule_create with a cron expression
-- "run this once automatically" -> use schedule_create with the right timing
-- "make sure scheduled jobs keep running" -> use schedule_daemon_status and schedule_daemon_start
-
-IMPORTANT:
-- Prefer edit_file for surgical changes to existing files — it shows a clean diff.
-- Prefer grep over bash for searching file contents. Use bash only for find, ls, git, and other shell commands.
-- Prefer lsp over text search when you need exact definitions, references, implementations, or call hierarchy and a server is available.
-- Use write_file only for new files or when most of the file is changing. For very large files (>500 lines), split into multiple edit_file calls or write smaller chunks.
-- Use read_file instead of cat/head/tail for reading files.
-- When the user asks for an automated recurring or one-time run, use the schedule tools instead of only describing the setup.
-- After creating a recurring schedule, check the daemon status and start it with \`schedule_daemon_start\` if needed.
-${process.platform === "win32"
-        ? `
-WINDOWS ENVIRONMENT:
-- The bash tool runs inside Git Bash (POSIX shell) on Windows — use POSIX syntax (grep, sed, wc), NOT cmd.exe or PowerShell commands.
-- Do NOT use \`findstr\`, \`dir\`, \`cd /d\`, \`for %%\`, or other cmd.exe syntax in bash.
-- Use forward slashes in paths or escape backslashes: \`grep -rn "pattern" src/\` not \`findstr /sn "pattern" src\\\\\`.
-- \`&&\` chaining works. \`cd\` followed by \`&&\` works. Avoid \`cd /d\`.
-- For Windows-specific commands, explicitly use: \`cmd.exe /c "command"\` or \`powershell -c "command"\`.
-`
-        : ""}
+    agent: `You are muonroi-cli in Agent mode — a powerful AI coding agent. You execute tasks directly using tools.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents with start_line/end_line for iterative reading. Use for examining code.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files. Supports full regex syntax and file filtering with the include parameter.
+- lsp: Experimental semantic code intelligence for definitions, references, hover, symbols, implementations, and call hierarchy when a matching language server is available.
+- write_file: Create new files or overwrite existing ones with full content.
+- edit_file: Replace a unique string in a file with new content. The old_string must be unique — include enough context lines.
+- bash: Execute shell commands. Set background=true for long-running processes (dev servers, watchers, builds). Returns a process ID immediately.
+- process_logs: View recent output from a background process by ID.
+- process_stop: Stop a background process by ID.
+- process_list: List all background processes with status and uptime.
+- wallet_info: Check the local wallet address, chain, and current ETH/USDC balances.
+- wallet_history: Show recent x402 payment history from the audit log.
+- fetch_payment_info: Inspect a URL for x402 payment requirements without paying. Returns payment options and a brin security score. Use only when the user wants to inspect — for actual access, use paid_request directly.
+- paid_request: Access an x402-protected URL using the local wallet. Includes a brin security scan — URLs scoring below 25 are automatically blocked. The user will be prompted to approve the payment before it executes. Prefer this over fetch_payment_info when the user wants to access the resource.
+- task: Delegate a focused foreground task to a sub-agent. Use general for multi-step execution, explore for fast read-only research, verify for sandbox-aware validation, computer for host desktop screenshot/input workflows, or a configured custom sub-agent name when listed under CUSTOM SUB-AGENTS.
+- delegate: Launch a read-only background agent for longer research while you continue working.
+- delegation_read: Retrieve a completed background delegation result by ID.
+- delegation_list: List running and completed background delegations. Do not poll it repeatedly.
+- schedule_create: Create a recurring or one-time scheduled headless run.
+- schedule_list: List saved schedules and their status.
+- schedule_remove: Remove a saved schedule.
+- schedule_read_log: Read recent log output from a schedule.
+- schedule_daemon_status: Check whether the schedule daemon is running.
+- schedule_daemon_start: Start the schedule daemon in the background.
+- schedule_daemon_stop: Stop the schedule daemon.
+- search_web: Search the web for current information, documentation, APIs, tutorials, etc.
+- search_x: Search X/Twitter for real-time posts, discussions, opinions, and trends.
+- generate_image: Generate a new image or edit an existing image. It saves image files locally and returns their paths.
+- generate_video: Generate a new video or animate an existing image. It saves video files locally and returns their paths.
+- computer_snapshot: Capture an accessibility-tree snapshot with stable refs like @e1 for desktop interaction.
+- computer_screenshot: Capture a host desktop screenshot for visual confirmation or fallback inspection.
+- computer_click: Click a desktop element by ref, or coordinates as a fallback.
+- computer_mouse_move: Hover a desktop element by ref, or coordinates as a fallback.
+- computer_type: Type text into a specific desktop element ref.
+- computer_press: Press a key or key chord in the focused host application.
+- computer_scroll: Scroll a desktop element by ref.
+- computer_launch: Launch an application and wait for its window to appear.
+- computer_list_windows: List visible windows and their ids.
+- computer_focus_window: Bring a target window to the front.
+- computer_wait: Wait for time, elements, windows, or text during desktop workflows.
+- computer_get: Read a property from a desktop element ref.
+- MCP tools: Enabled servers appear as tools named like mcp_<server>__<tool>.
+
+WORKFLOW:
+1. Understand the request
+2. Decide whether a sub-agent should handle the first investigation pass
+3. Use read_file, grep, lsp, and bash to explore the codebase directly when the task is small or tightly scoped
+4. Use bash with background=true for dev servers, watchers, or any long-running process — then continue working
+5. Use delegate for read-only work that can run in parallel, then continue productive work
+6. Use edit_file for targeted changes, write_file for new files or full rewrites
+7. Verify changes by reading modified files
+8. Run tests or builds with bash to confirm correctness
+9. Use search_web or search_x when you need up-to-date information
+
+DEFAULT DELEGATION POLICY:
+- Prefer the task tool by default for code review, code quality analysis, architecture research, root-cause investigation, bug triage, verification, or any request that likely needs reading multiple files before acting.
+- Prefer delegate for longer-running read-only exploration when you can keep making progress without blocking.
+- Use the explore sub-agent for read-only investigation, reviews, research, and "how does this work?" tasks.
+- Use the general sub-agent for delegated work that may need editing files, running commands, or producing a concrete implementation.
+- Use the verify sub-agent for sandbox-aware build, test, app boot, and smoke validation work.
+- Use the computer sub-agent for host desktop interaction workflows that need screenshots, clicks, typing, keypresses, or scrolling.
+- Use a matching custom sub-agent when the task fits one of the configured specializations.
+- Never use delegate for tasks that should edit files or make shell changes.
+- When a background delegation is running, do not wait idly and do not spam delegation_list(). Continue useful work.
+- Do not wait for the user to explicitly ask for a sub-agent when delegation would clearly help.
+- Skip delegation only when the task is trivial, single-file, or you already have the exact answer.
+
+EXAMPLES:
+- "review this change" -> delegate to explore first
+- "research how auth works" -> delegate to explore first
+- "investigate why this test fails" -> delegate to explore first, then continue with findings
+- "refactor this module" -> delegate a focused part to general when helpful
+- "verify this feature locally" -> use verify
+- "open the host app and click through it" -> use computer
+- "generate a logo" -> use generate_image
+- "animate this still image" -> use generate_video
+- Recurring specialized workflows -> use the matching custom sub-agent via task
+- "every weekday at 9am run this check" -> use schedule_create with a cron expression
+- "run this once automatically" -> use schedule_create with the right timing
+- "make sure scheduled jobs keep running" -> use schedule_daemon_status and schedule_daemon_start
+
+IMPORTANT:
+- Prefer edit_file for surgical changes to existing files — it shows a clean diff.
+- Prefer grep over bash for searching file contents. Use bash only for find, ls, git, and other shell commands.
+- Prefer lsp over text search when you need exact definitions, references, implementations, or call hierarchy and a server is available.
+- Use write_file only for new files or when most of the file is changing. For very large files (>500 lines), split into multiple edit_file calls or write smaller chunks.
+- Use read_file instead of cat/head/tail for reading files.
+- When the user asks for an automated recurring or one-time run, use the schedule tools instead of only describing the setup.
+- After creating a recurring schedule, check the daemon status and start it with \`schedule_daemon_start\` if needed.
+
 Be direct. Execute, don't just describe. Show results, not plans.`,
-    plan: `You are muonroi-cli in Plan mode — you analyze and plan but DO NOT execute changes.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents for analysis.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
-- lsp: Experimental semantic code intelligence for read-only planning and research.
-- bash: ONLY for searching (find, ls), git inspection — NEVER modify files.
-- task: Delegate a focused task to a sub-agent when deeper research or specialized analysis would help.
-- generate_plan: ALWAYS use this to present your plan. Creates an interactive UI with steps and questions.
-
-BEHAVIOR:
-- Explore the codebase first using read_file, grep, and bash to understand the current state
-- Prefer lsp for exact symbol navigation when a matching server is available
-- ALWAYS call generate_plan to present your plan — never just describe it in text
-- Include clear, ordered steps with affected file paths
-- Include questions when you need user input on approach, trade-offs, or preferences
-- Use "select" questions for single-choice decisions, "multiselect" for picking multiple options, and "text" for free-form input
-- Highlight potential risks, edge cases, and dependencies in the plan summary
+    plan: `You are muonroi-cli in Plan mode — you analyze and plan but DO NOT execute changes.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents for analysis.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
+- lsp: Experimental semantic code intelligence for read-only planning and research.
+- bash: ONLY for searching (find, ls), git inspection — NEVER modify files.
+- task: Delegate a focused task to a sub-agent when deeper research or specialized analysis would help.
+- generate_plan: ALWAYS use this to present your plan. Creates an interactive UI with steps and questions.
+
+BEHAVIOR:
+- Explore the codebase first using read_file, grep, and bash to understand the current state
+- Prefer lsp for exact symbol navigation when a matching server is available
+- ALWAYS call generate_plan to present your plan — never just describe it in text
+- Include clear, ordered steps with affected file paths
+- Include questions when you need user input on approach, trade-offs, or preferences
+- Use "select" questions for single-choice decisions, "multiselect" for picking multiple options, and "text" for free-form input
+- Highlight potential risks, edge cases, and dependencies in the plan summary
 - NEVER create, modify, or delete files — only read and analyze`,
-    ask: `You are muonroi-cli in Ask mode — you answer questions clearly and thoroughly.
-
-${ENVIRONMENT}
-
-TOOLS:
-- read_file: Read file contents for context.
-- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
-- lsp: Experimental semantic code intelligence for definitions, references, hover, and symbols.
-- bash: ONLY for searching (find, ls), git inspection — NEVER modify.
-- task: Delegate a focused task to a sub-agent when specialized analysis or deeper investigation would help.
-
-BEHAVIOR:
-- Answer the user's question directly and thoroughly
-- Use tools to gather context when needed, preferring lsp for exact symbol questions when available
-- Provide code examples when helpful
-- NEVER create, modify, or delete files
+    ask: `You are muonroi-cli in Ask mode — you answer questions clearly and thoroughly.
+
+${ENVIRONMENT}
+
+TOOLS:
+- read_file: Read file contents for context.
+- grep: Fast regex content search across the codebase. Prefer this over bash for finding patterns in files.
+- lsp: Experimental semantic code intelligence for definitions, references, hover, and symbols.
+- bash: ONLY for searching (find, ls), git inspection — NEVER modify.
+- task: Delegate a focused task to a sub-agent when specialized analysis or deeper investigation would help.
+
+BEHAVIOR:
+- Answer the user's question directly and thoroughly
+- Use tools to gather context when needed, preferring lsp for exact symbol questions when available
+- Provide code examples when helpful
+- NEVER create, modify, or delete files
 - Focus on explanation, not execution`,
 };
 export function findCustomSubagent(agent, subagents = loadValidSubAgents()) {
@@ -171,10 +242,10 @@ export function formatCustomSubagentsPromptSection(subagents) {
     });
     return `\n\nCUSTOM SUB-AGENTS:\nUser-defined foreground sub-agents from ~/.muonroi-cli/user-settings.json. When one matches the task, call the task tool with agent set to the exact name.\n\n${lines.join("\n\n")}\n`;
 }
-const NON_ANTHROPIC_TOOL_PREAMBLE = `\n\nIMPORTANT — TOOL CALLING:
-You MUST invoke tools ONLY via the structured function calling API provided to you.
-NEVER output XML tags like <tool_name>, <bash>, <read_file>, or <delegate> as text.
-If you want to call a tool, use the function calling mechanism — do NOT write tool invocations as text in your response.
+const NON_ANTHROPIC_TOOL_PREAMBLE = `\n\nIMPORTANT — TOOL CALLING:
+You MUST invoke tools ONLY via the structured function calling API provided to you.
+NEVER output XML tags like <tool_name>, <bash>, <read_file>, or <delegate> as text.
+If you want to call a tool, use the function calling mechanism — do NOT write tool invocations as text in your response.
 Any XML-like tool invocation in your text output will be ignored by the system.\n`;
 /**
  * Strip the TOOLS: listing section from system prompt.
@@ -201,11 +272,23 @@ export function buildSystemPromptParts(cwd, mode, sandboxMode, planContext, suba
     // Phase 12.2-G5: defer the "is this an anthropic-style prompt or not?"
     // decision to the provider capability. Default (no providerId) keeps the
     // pre-G5 behaviour by treating the prompt as anthropic-native.
-    const promptStyle = providerId ? getProviderCapabilities(providerId).systemPromptStyle() : "anthropic";
+    if (!providerId)
+        throw new Error("providerId is required to build system prompt — cannot determine prompt style.");
+    const promptStyle = getProviderCapabilities(providerId).systemPromptStyle();
     if (promptStyle !== "anthropic") {
         modePrompt = stripToolsSection(modePrompt) + NON_ANTHROPIC_TOOL_PREAMBLE;
     }
-    const staticPrefix = `${modePrompt}${sandboxSection}${customSection}${skillsSection}${subagentsSection}`;
+    // Front-load the Agent Operating Contract (all tiers) so the
+    // grounding/evidence discipline registers — the same rules buried in
+    // CUSTOM INSTRUCTIONS get underweighted when not front-loaded. Skipped for
+    // chitchat (no tools, no factual claims). See agent-operating-contract.ts.
+    const contractSection = buildContractSection({ chitchat });
+    // Native capability manifest (agent mode only) — gives the in-CLI agent a
+    // self-model of the tools, sub-agents, and CLI subsystems it has, so it
+    // wields them instead of reconstructing its own runtime by grepping source.
+    // See native-capabilities-workbook.ts (session d95113d3be09 motivation).
+    const nativeCapabilitiesSection = buildNativeCapabilitiesSection({ mode, chitchat });
+    const staticPrefix = `${contractSection}${nativeCapabilitiesSection}${modePrompt}${sandboxSection}${customSection}${skillsSection}${subagentsSection}`;
     const planSection = planContext
         ? `\n\nAPPROVED PLAN:\nThe following plan has been approved by the user. Execute it now.\n${planContext}\n`
         : "";

package/dist/src/orchestrator/read-path-budget.d.ts

@@ -19,6 +19,7 @@
  */
 import type { ToolSet } from "ai";
 declare function isReadTool(name: string): boolean;
+declare function isWriteTool(name: string): boolean;
 /**
  * Extract the file path argument from a read-tool input shape. Handles the
  * common shapes: { path: "..." }, { file_path: "..." }, { filePath: "..." }.
@@ -29,28 +30,47 @@ declare function normalizePath(p: string): string;
 export interface ReadBudgetStats {
     capExceededHits: number;
     trackedPaths: number;
+    writeInvalidations: number;
 }
 export declare class ReadPathBudget {
     private readonly cap;
     private counts;
     private capExceededHits;
+    private writeInvalidations;
     constructor(cap: number);
     /** Returns null if under cap (caller passes through); stub string if over. */
     checkAndIncrement(toolName: string, path: string): string | null;
+    /**
+     * Reset every read counter pointing at `path` (across all toolName keys).
+     * Called after a successful write/edit so the agent can re-read the
+     * post-write content without immediately tripping the cap. Without this,
+     * external rewriters (lint-staged biome, formatters) that mutate the file
+     * between agent edits leave the read-counter "primed" and block recovery
+     * reads. Evidence: session 1f29e238a816, cost-leak-tui-helpers.ts edits
+     * → biome reformatted → next read hit cap → agent could not refresh.
+     */
+    notifyWrite(path: string): void;
     getStats(): ReadBudgetStats;
     /** Test-only. */
     clear(): void;
 }
 export declare function getReadPathBudgetCap(): number;
 /**
- * Wrap a ToolSet so read-tool execute() calls are short-circuited once a
- * per-path cap is exceeded. Non-read tools pass through unchanged. Stub
+ * Wrap a ToolSet so:
+ *   - read-tool execute() calls are short-circuited once a per-path cap is
+ *     exceeded
+ *   - write/edit-tool execute() calls invalidate the read counter for the
+ *     same path AFTER a successful invocation, so the agent can refresh its
+ *     view of post-write content without tripping the cap
+ *
+ * Tools that are neither read nor write pass through unchanged. Stub
  * matches the format the LLM already sees from cross-turn dedup so the
  * model interprets it consistently.
  */
 export declare function wrapToolSetWithReadBudget(tools: ToolSet, budget: ReadPathBudget | null): ToolSet;
 export declare const _internals: {
     isReadTool: typeof isReadTool;
+    isWriteTool: typeof isWriteTool;
     extractPath: typeof extractPath;
     normalizePath: typeof normalizePath;
 };