Use mode-aware CLI-first tool guidance in Auto mode

[acking-you]

Problem

While exploring a recent Claude Code release, I noticed that its Auto-mode system prompt now includes the following instruction:

Do your work through the Bash tool wherever it can accomplish the job: read files with cat, head, or sed -n, search with grep and find, and make file changes with sed, heredocs, or short scripts, rather than using the dedicated Read, Edit, Write tools. Fall back to a dedicated tool only when Bash genuinely cannot do the job.

This reminded me of a problem I encountered shortly after I started using Claude Code around August 2025: long Write calls sometimes failed, and the model repeatedly retried the same tool with nearly the same payload because it had no alternative path.

• Dedicated tools (Read, Edit, Write) give the product typed inputs, path validation, structured diffs, artifacts, and predictable UI events. They are easier to constrain, review, and potentially roll back. Their weakness is the fixed schema: when a tool or payload fails, the model may have no way to decompose the operation or switch strategies.
• Bash, CLI tools, and pipelines let the model compose its own workflow. It can split a large write, inspect intermediate results, switch to a heredoc or script, and recover using stderr and exit codes. The cost is weaker product control: arbitrary commands are harder to understand semantically, present as precise file changes, constrain, or roll back.

Claude Code adds this guidance only in Auto mode. My interpretation is that Auto's risk evaluation and approval boundary compensate for the reduced control of a general-purpose shell. This preserves CLI composability while keeping dedicated tools as a fallback.

Maka already has the relevant building blocks: Auto uses a managed workspace-write sandbox, Bash calls are audited, and dedicated file tools provide structured diffs and stronger filesystem semantics. It currently lacks mode-aware guidance for choosing between them.

Desired outcome

In managed Auto sessions, guide the model to:

• Prefer Bash and composable CLI workflows when they improve inspection, transformation, or failure recovery.
• Use dedicated file tools when structured diffs, UI integration, or stronger filesystem controls matter.
• Keep the existing sandbox and approval boundary unchanged; CLI-first must not imply unrestricted shell access.
• Make shell-originated file changes reviewable where possible.

The policy should remain disabled for read-only or restricted tool profiles where Bash is unavailable or the same safety boundary cannot be enforced.

Alternatives or workarounds

• Prefer dedicated tools everywhere: better product control, but weaker recovery from tool-specific failures.
• Expose only Bash: maximum composability, but weaker structured review and safety semantics.
• Recommend Bash only after a dedicated tool fails: preserves the current default, but still makes the model enter avoidable retry loops before switching strategies.

[testikun]

I am picking up #3507. The implementation will be limited to the normal Interactive main-session prompt and will not change Maka's execution authority.

Implementation plan

1. Add packages/runtime/src/system-prompt/auto-tool-guidance.ts with one pure resolveAutoToolGuidance(...) interface. It will receive the Host permission snapshot, final tool names, shell availability, and profile restrictions, and return either a prompt fragment or undefined.
2. Add permissionMode to InteractiveRunComposerInput and pass backendContext.header.permissionMode from the Host factory.
3. Resolve the guidance only after tool-profile projection, plan filtering, and capability routing have produced the final tools array. Candidate tools will not be used for eligibility.
4. Append the fragment only to the normal assembleMainSessionSystemPrompt() path. The child-instruction path and headless-coding-v1 early-return path will remain unchanged.
5. Increment INTERACTIVE_RUN_COMPOSER_REVISION because the model-visible prompt composition changes.

Eligibility and prompt behavior

The fragment will be emitted only when all of the following are true:

• permissionMode === ask (the UI Auto mode);
• the final exposed tool set contains Bash;
• the turn shell has no setup error;
• no fixed toolProfile or explicit boundTools ceiling owns the prompt;
• the run is not using a child instruction.

The fragment will tell the model to use Bash/CLI for batching, pipelines, transformations, generated payloads, and recovery from structured-tool limitations; use Read/Glob/Grep for straightforward inspection; and use Edit/Write/apply_patch when path validation or reviewable diffs matter. It will also state that Bash cannot bypass the current workspace, network, sandbox, or approval boundary. Tool names that are absent from the final surface will not be advertised.

Tests and acceptance

• Add pure resolver tests for ask, explore, bypass, missing Bash, unavailable shell, fixed profiles, bound tool ceilings, and dynamic tool-name rendering.
• Add composer regressions proving that the fragment appears once in an eligible Auto main session and remains absent from child prompts, restricted surfaces, broken-shell sessions, and non-Auto modes.
• Keep the exact headless-coding-v1 prompt/tool ceiling test unchanged.
• Treat the implementation as complete only when the new fragment is limited to the eligible surface and no permission, sandbox, Bash execution, persisted contract, or tool-schema behavior changes.

Related

• Issue: Use mode-aware CLI-first tool guidance in Auto mode #3507
• Design document: docs/architecture/maka-3507-auto-tool-guidance-design.zh-CN.md
• Permission and Bash classification: packages/core/src/permission.ts
• Interactive composition seam: packages/runtime-host/src/server/interactive-run-composer.ts
• Fixed headless profile: packages/runtime-host/src/server/hosted-execution-tool-profile.ts

---

中文概要

第一版只修改普通 Interactive 主会话的 prompt 组合：新增一个纯 resolveAutoToolGuidance(...) 模块，并在最终工具路由完成后调用。只有 permissionMode = ask、最终工具面包含 Bash、shell 正常、且没有固定 profile、bound tool ceiling 或 child instruction 时才注入。

提示会明确 Bash/CLI 适合批处理、流水线、转换、生成和失败恢复；Read/Glob/Grep 适合简单检查；Edit/Write/apply_patch 适合路径校验和可审查 diff。不会改变权限、沙箱、Bash 安全分类、执行逻辑、持久化协议或 headless v1，并通过纯函数测试和 Composer 回归测试验收。

[testikun]

Implementation update: PR #3705 is ready and closes this issue.

What was implemented

• Added a pure resolver for Auto-mode tool guidance.
• Eligibility is based on the Host permissionMode and the final model-visible tool surface, not candidate tools or collaboration mode.
• Guidance is injected only into a normal Interactive main session when Bash is available and the shell is healthy. It is excluded from child agents, Side Conversations, Deep Research, bound/restricted surfaces, fixed profiles, and non-Auto modes.
• The text recommends Bash/CLI for batching, pipelines, transformations, generated payloads, and recovery, while preserving structured inspection/edit tools where they are a better fit. It also states that Bash cannot bypass Maka sandbox, workspace, network, or approval boundaries.

Verification: Runtime 2997 passed / 13 skipped; Runtime Host 1137 passed; focused regression tests 34 passed.

中文摘要

PR #3705 已完成实现并绑定本 issue。改动只增加普通 Auto 主会话的工具选择提示：根据 Host 权限快照和最终实际暴露的工具集合决定是否注入，不修改权限、沙箱、审批、Bash 执行逻辑或 headless v1。子代理、Side Conversation、Deep Research、受限工具面、固定 profile、shell 异常和非 Auto 模式都不会注入。