@armadra/agent 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -5,6 +5,25 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.6.6 (2026-10-03)
+
+- **Local search hints**: when both `grep` and `glob` are directly available, the system prompt's rules gain one line
+  ("Locate code with grep/glob before reading; do not guess file paths."); the `grep` / `glob` descriptions now say when
+  to use them; `grep` takes `filesOnly: true` to list only the matching files (deduplicated, sorted by path, `limit` counts
+  files). `read` on a directory now points at a tool the model can actually call: `ls` when active, otherwise `glob`
+  (e.g. `pattern "src/*"`), otherwise a file inside it. In `-p` with the `minimal` / `coordinator` preset, a denied bash
+  `grep` / `rg` / `find` adds one stderr line on how to bring the tools back (`tools.default: ["+grep","+glob"]`). Tools
+  get the session's active tool set as the optional, read-only `ToolContext.activeTools`. This changes the `default`
+  prefix (about +35 tokens), so the first request after upgrading misses the cache once. Docs: docs/design.md §5.6,
+  docs/codemode.md.
+
+## 0.6.5 (2026-10-03)
+
+- **`AcpClient` can pass MCP servers when opening a session**: `newSession`, `resumeSession` and `loadSession` take an
+  optional third argument `{ mcpServers }` that is forwarded as-is in `session/new|resume|load` (default still `[]`, the
+  wire is unchanged when it is omitted). `AcpClient.features.mcpServers` lets a host detect support. ama itself still
+  sends none. Docs: docs/acp.md "As a client".
+
 ## 0.6.4 (2026-10-03)
 
 - **Interrupt and send now**: while a run is in progress, Enter still queues the message as a steer (delivered at the next

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,21 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.6（2026-10-03）
+
+- **本地检索提示**：`grep` 与 `glob` 都直接可用时，系统提示的规则节多一句「先 grep / glob 定位再 read，不要猜路径」；`grep` /
+  `glob` 的描述写明何时用；`grep` 新增 `filesOnly: true`，只列命中文件（去重、按路径排序，`limit` 按文件数计）。`read` 收到目录时
+  指向模型当前真能调用的工具：有 `ls` 说用 ls，否则有 `glob` 说用 glob（例如 `pattern "src/*"`），都没有则说读目录里的文件。`-p`
+  下 `minimal` / `coordinator` 预设里 bash 的 `grep` / `rg` / `find` 被拒时，stderr 补一行怎么加回
+  （`tools.default: ["+grep","+glob"]`）。工具经可选、只读的 `ToolContext.activeTools` 拿到会话活动集。`default` 前缀因此
+  变化（约 +35 token），升级后首个请求缓存未命中一次。文档：docs/design.md §5.6、docs/codemode.md。
+
+## 0.6.5（2026-10-03）
+
+- **`AcpClient` 开会话可传 MCP 服务器**：`newSession`、`resumeSession`、`loadSession` 新增可选的第三个参数
+  `{ mcpServers }`，原样随 `session/new|resume|load` 发出（缺省仍是 `[]`，不传时线路不变）；宿主用
+  `AcpClient.features.mcpServers` 检测是否支持。ama 自己仍不传。文档：docs/acp.md「作为客户端」。
+
 ## 0.6.4（2026-10-03）
 
 - **打断并立即发送**：运行中按 Enter 仍是排队插话（等下一个投递点送达），新增 `Ctrl+X`（键位动作 `app.message.interrupt`）立即中止

package/dist/agent/prompt-rules.d.ts

@@ -5,8 +5,10 @@
  * 保持一句、英文、只写模型确实会做错的事；预算见 `src/cli/prompt-budget.test.ts`。
  * 「edit 的多处修改」写在 edit 工具描述里（只在 edit 可用时出现）；并行批量在 codemode 独占时
  * 由它自己的说明负责，所以只在 read 直接可用时给。
+ * 「先定位再读」只在 grep 与 glob 都直接可用时给（docs/search-plan.md §4.2：`minimal` 下模型会连猜文件名）。
  */
 import type { ToolDefinition } from "../tools/types.js";
 export declare const DESTRUCTIVE_RULE = "Ask before destructive commands (rm -rf, git reset --hard, force push, deleting branches) unless the user requested them.";
 export declare const PARALLEL_READS_RULE = "Batch independent read-only tool calls into one turn.";
+export declare const LOCATE_RULE = "Locate code with grep/glob before reading; do not guess file paths.";
 export declare function baseRules(tools: readonly Pick<ToolDefinition, "name">[]): string[];

package/dist/agent/prompt-rules.js

@@ -5,14 +5,19 @@
  * 保持一句、英文、只写模型确实会做错的事；预算见 `src/cli/prompt-budget.test.ts`。
  * 「edit 的多处修改」写在 edit 工具描述里（只在 edit 可用时出现）；并行批量在 codemode 独占时
  * 由它自己的说明负责，所以只在 read 直接可用时给。
+ * 「先定位再读」只在 grep 与 glob 都直接可用时给（docs/search-plan.md §4.2：`minimal` 下模型会连猜文件名）。
  */
 export const DESTRUCTIVE_RULE = "Ask before destructive commands (rm -rf, git reset --hard, force push, deleting branches) unless the user requested them.";
 export const PARALLEL_READS_RULE = "Batch independent read-only tool calls into one turn.";
+export const LOCATE_RULE = "Locate code with grep/glob before reading; do not guess file paths.";
 export function baseRules(tools) {
     if (tools.length === 0)
         return [];
     const rules = [DESTRUCTIVE_RULE];
-    if (tools.some((tool) => tool.name === "read"))
+    const has = (name) => tools.some((tool) => tool.name === name);
+    if (has("read"))
         rules.push(PARALLEL_READS_RULE);
+    if (has("grep") && has("glob"))
+        rules.push(LOCATE_RULE);
     return rules;
 }

package/dist/agent/session-tools.js

@@ -266,6 +266,7 @@ export function createToolContext(core, runner, call, signal, onUpdate) {
         markRead: (path) => {
             core.readFiles.add(path);
         },
+        activeTools: new Set(core.activeToolNames()),
         tools: {
             executeTool: (name, input, options) => {
                 nested++;

package/dist/bundle/ama.cjs

@@ -41,7 +41,7 @@ var AMA_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    AMA_VERSION = true ? "0.6.4" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.6" : readPackageVersion();
   }
 });
 
@@ -3475,7 +3475,8 @@ var init_print = __esm({
         planPending: (version, where) => `ama: plan v${version} saved, awaiting approval (not executed): ${where}; -p does not approve on anyone's behalf — approve it in the interactive UI or via RPC plan_response, or set plan.unattended: approve to let -p approve and continue`,
         limitTurns: (limit) => `ama: reached the turn limit ${limit} (--max-turns / limits.maxTurns); run ended before finishing`,
         limitCost: (limit, spent) => `ama: reached the cost limit ${limit} (spent ${spent}; --max-cost / limits.maxCostUsd); run ended before finishing`,
-        denied: (count2, tools, reason) => `ama: ${plural(count2, "tool call")} denied: ${tools.join(", ")}${reason !== "" ? ` (${reason})` : ""}; -p has no one to approve; to allow them use --permission-mode auto-edit|auto or --allow <rule>`
+        denied: (count2, tools, reason) => `ama: ${plural(count2, "tool call")} denied: ${tools.join(", ")}${reason !== "" ? ` (${reason})` : ""}; -p has no one to approve; to allow them use --permission-mode auto-edit|auto or --allow <rule>`,
+        searchToolsMissing: (preset, missing) => `ama: the ${preset} preset has no ${missing.join(" / ")}; add ${missing.length === 1 ? "it" : "them"} with tools.default: [${missing.map((name) => `"+${name}"`).join(",")}]`
       },
       /** RPC 响应的 `error`（人读）。 */
       rpc: {
@@ -3520,7 +3521,8 @@ var init_print = __esm({
         planPending: (version, where) => `ama: 计划 v${version} 已落盘、待审批（未执行）：${where}；-p 不替人批准——在交互界面或 RPC plan_response 里审批，或设 plan.unattended: approve 让 -p 批准后接着执行`,
         limitTurns: (limit) => `ama: 已达到回合上限 ${limit}（--max-turns / limits.maxTurns），运行在完成前结束`,
         limitCost: (limit, spent) => `ama: 已达到费用上限 ${limit}（累计 ${spent}；--max-cost / limits.maxCostUsd），运行在完成前结束`,
-        denied: (count2, tools, reason) => `ama: ${count2} 次工具调用被拒：${tools.join("、")}${reason !== "" ? `（${reason}）` : ""}；-p 没有人审批，需要放行时用 --permission-mode auto-edit|auto 或 --allow <规则>`
+        denied: (count2, tools, reason) => `ama: ${count2} 次工具调用被拒：${tools.join("、")}${reason !== "" ? `（${reason}）` : ""}；-p 没有人审批，需要放行时用 --permission-mode auto-edit|auto 或 --allow <规则>`,
+        searchToolsMissing: (preset, missing) => `ama: ${preset} 预设没有 ${missing.join(" / ")}，可用 tools.default: [${missing.map((name) => `"+${name}"`).join(",")}] 加上`
       },
       rpc: {
         badTaskId: "taskId 应为字符串",
@@ -8090,7 +8092,7 @@ function createGlobTool() {
   return {
     name: "glob",
     label: "Glob",
-    description: "Find files by glob (`**`, `*`, `?`, `[...]`, `{a,b}`, leading `!` excludes). Patterns without `/` match names at any depth. Respects .gitignore/.ignore; newest first.",
+    description: "Find files by glob (`**`, `*`, `?`, `[...]`, `{a,b}`, leading `!` excludes). Patterns without `/` match names at any depth. Respects .gitignore/.ignore; newest first. Use to discover files before read.",
     parameters: {
       type: "object",
       properties: {
@@ -14456,6 +14458,18 @@ function isBinary(buf) {
 function error(message) {
   return { content: message, isError: true };
 }
+function directoryHint(shown2, ctx) {
+  const active = ctx.activeTools;
+  if (active === void 0 || active.has("ls")) return "use the ls tool instead";
+  if (active.has("glob")) {
+    if (shown2 === ".") return 'use glob (e.g. pattern "*")';
+    if (shown2.startsWith("/") || /^[A-Za-z]:/.test(shown2) || /[*?[\]{}!\\]/.test(shown2)) {
+      return `use glob (e.g. path ${JSON.stringify(shown2)}, pattern "*")`;
+    }
+    return `use glob (e.g. pattern ${JSON.stringify(`${shown2}/*`)})`;
+  }
+  return "read a file inside it";
+}
 function numberLines(lines2, firstLine3) {
   return lines2.map((line2, i) => `${String(firstLine3 + i).padStart(6)}	${line2}`).join("\n");
 }
@@ -14495,7 +14509,7 @@ async function executeRead(input2, ctx, options = {}) {
   } catch {
     return error(`File not found: ${shown2}`);
   }
-  if (info2.isDirectory()) return error(`${shown2} is a directory; use the ls tool instead`);
+  if (info2.isDirectory()) return error(`${shown2} is a directory; ${directoryHint(shown2, ctx)}`);
   if (imageMimeFromPath(abs) !== void 0) return readImage(abs, shown2, ctx, options);
   const buf = await (0, import_promises5.readFile)(abs);
   if (isBinary(buf)) return error(`${shown2} appears to be a binary file; refusing to read it`);
@@ -15861,7 +15875,7 @@ function compilePattern(input2) {
   const source = input2.literal ? escapeRegExp(input2.pattern) : input2.pattern;
   return new RegExp(source, input2.ignoreCase ? "i" : "");
 }
-async function searchFile(abs, regex) {
+async function searchFile(abs, regex, firstOnly = false) {
   try {
     const info2 = await (0, import_promises9.stat)(abs);
     if (!info2.isFile() || info2.size > GREP_MAX_FILE_BYTES) return void 0;
@@ -15870,9 +15884,11 @@ async function searchFile(abs, regex) {
     const lines2 = buf.toString("utf8").replace(/\r\n/g, "\n").split("\n");
     if (lines2[lines2.length - 1] === "") lines2.pop();
     const hits = [];
-    lines2.forEach((line2, i) => {
-      if (regex.test(line2)) hits.push(i);
-    });
+    for (let i = 0; i < lines2.length; i++) {
+      if (!regex.test(lines2[i])) continue;
+      hits.push(i);
+      if (firstOnly) break;
+    }
     return hits.length > 0 ? { lines: lines2, hits } : void 0;
   } catch {
     return void 0;
@@ -15929,6 +15945,7 @@ async function executeGrep(input2, ctx) {
     return { content: `Path not found: ${displayPath(root, ctx.cwd)}`, isError: true };
   }
   const files = await candidateFiles(root, rootIsFile, input2.glob, ctx.signal);
+  if (input2.filesOnly === true) return grepFilesOnly(files, regex, limit, ctx);
   const blocks = [];
   let matches2 = 0;
   let matchedFiles = 0;
@@ -15974,21 +15991,49 @@ async function executeGrep(input2, ctx) {
     details: { matches: matches2, files: matchedFiles, limited, truncated: cut.truncated }
   };
 }
+async function grepFilesOnly(files, regex, limit, ctx) {
+  const sorted = [...new Set(files)].sort();
+  const shown2 = [];
+  let limited = false;
+  outer: for (let i = 0; i < sorted.length; i += GREP_CONCURRENCY) {
+    if (ctx.signal.aborted) return { content: "aborted by user", isError: true };
+    const batch = sorted.slice(i, i + GREP_CONCURRENCY);
+    const results = await Promise.all(batch.map((f) => searchFile(f, regex, true)));
+    for (let j = 0; j < batch.length; j++) {
+      if (!results[j]) continue;
+      if (shown2.length >= limit) {
+        limited = true;
+        break outer;
+      }
+      shown2.push(displayPath(batch[j], ctx.cwd));
+    }
+  }
+  if (shown2.length === 0) {
+    return { content: "No matches found", details: { matches: 0, files: 0, filesOnly: true } };
+  }
+  const unique3 = [...new Set(shown2)].sort();
+  let content = unique3.join("\n");
+  if (limited) content += `
+
+[Stopped at ${limit} files. Narrow the search or raise limit.]`;
+  return { content, details: { files: unique3.length, filesOnly: true, limited } };
+}
 function createGrepTool() {
   return {
     name: "grep",
     label: "Grep",
-    description: "Search file contents by JS regex. Respects .gitignore/.ignore; skips binary and >2 MB files. Output: `path:line: text`.",
+    description: "Use to find where a symbol or text appears (JS regex). Skips ignored, binary, >2 MB files. Output `path:line: text`; filesOnly lists matching files.",
     parameters: {
       type: "object",
       properties: {
         pattern: { type: "string" },
-        path: { type: "string", description: "File or dir (default: cwd)" },
-        glob: { type: "string", description: "File filter, e.g. *.ts" },
+        path: { type: "string", description: "File or dir" },
+        glob: { type: "string", description: "e.g. *.ts" },
         ignoreCase: { type: "boolean" },
         literal: { type: "boolean" },
         context: { type: "integer", description: "0-5 lines" },
-        limit: { type: "integer", description: `Default ${DEFAULT_GREP_LIMIT}` }
+        limit: { type: "integer", description: `Default ${DEFAULT_GREP_LIMIT}` },
+        filesOnly: { type: "boolean" }
       },
       required: ["pattern"],
       additionalProperties: false
@@ -24309,15 +24354,18 @@ var init_session_subagent = __esm({
 function baseRules(tools) {
   if (tools.length === 0) return [];
   const rules = [DESTRUCTIVE_RULE];
-  if (tools.some((tool) => tool.name === "read")) rules.push(PARALLEL_READS_RULE);
+  const has = (name) => tools.some((tool) => tool.name === name);
+  if (has("read")) rules.push(PARALLEL_READS_RULE);
+  if (has("grep") && has("glob")) rules.push(LOCATE_RULE);
   return rules;
 }
-var DESTRUCTIVE_RULE, PARALLEL_READS_RULE;
+var DESTRUCTIVE_RULE, PARALLEL_READS_RULE, LOCATE_RULE;
 var init_prompt_rules = __esm({
   "src/agent/prompt-rules.ts"() {
     "use strict";
     DESTRUCTIVE_RULE = "Ask before destructive commands (rm -rf, git reset --hard, force push, deleting branches) unless the user requested them.";
     PARALLEL_READS_RULE = "Batch independent read-only tool calls into one turn.";
+    LOCATE_RULE = "Locate code with grep/glob before reading; do not guess file paths.";
   }
 });
 
@@ -25493,6 +25541,7 @@ function createToolContext(core, runner, call, signal, onUpdate) {
     markRead: (path) => {
       core.readFiles.add(path);
     },
+    activeTools: new Set(core.activeToolNames()),
     tools: {
       executeTool: (name, input2, options) => {
         nested++;
@@ -30738,6 +30787,9 @@ var init_jsonrpc = __esm({
 });
 
 // src/drivers/acp/client.ts
+function mcpServersOf(options) {
+  return [...options?.mcpServers ?? []];
+}
 function unattendedOutcome(params) {
   const reject2 = params.options.find((o) => o.kind === "reject_once");
   return {
@@ -30769,6 +30821,11 @@ var init_client = __esm({
         });
       }
       options;
+      /**
+       * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+       * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+       */
+      static features = { mcpServers: true };
       peer;
       /** sessionId → 挂起权限请求的取消器。 */
       pendingPermissions = /* @__PURE__ */ new Map();
@@ -30818,16 +30875,28 @@ var init_client = __esm({
       supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
       }
-      newSession(cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: [] }, signal);
+      newSession(cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionNew,
+          { cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-      resumeSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: [] }, signal);
+      resumeSession(sessionId, cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionResume,
+          { sessionId, cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       /** 回放历史（以 session/update 通知）。 */
-      loadSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: [] }, signal);
+      loadSession(sessionId, cwd, signal, options) {
+        return this.peer.request(
+          ACP_METHODS.sessionLoad,
+          { sessionId, cwd, mcpServers: mcpServersOf(options) },
+          signal
+        );
       }
       listSessions(cwd, cursor) {
         return this.peer.request(ACP_METHODS.sessionList, {
@@ -45619,6 +45688,7 @@ function resultSummary(input2, theme) {
     case "grep": {
       const matches2 = num9(details["matches"]);
       if (matches2 === 0) return muted(m.noMatch);
+      if (details["filesOnly"] === true) return muted(m.files(num9(details["files"]) ?? count2));
       if (matches2 === void 0) return muted(m.lines(count2));
       return muted(m.matches(matches2, num9(details["files"])));
     }
@@ -47890,6 +47960,27 @@ var init_json_event = __esm({
   }
 });
 
+// src/modes/print/search-hint.ts
+function isSearchCommand(command3) {
+  return SEARCH_COMMAND.test(command3);
+}
+function searchToolsHint(deniedBashCommands, preset, activeTools) {
+  if (!HINT_PRESETS.has(preset)) return void 0;
+  const missing = ["grep", "glob"].filter((name) => !activeTools.includes(name));
+  if (missing.length === 0) return void 0;
+  if (!deniedBashCommands.some(isSearchCommand)) return void 0;
+  return msg().print.print.searchToolsMissing(preset, missing);
+}
+var SEARCH_COMMAND, HINT_PRESETS;
+var init_search_hint = __esm({
+  "src/modes/print/search-hint.ts"() {
+    "use strict";
+    init_i18n();
+    SEARCH_COMMAND = /(?:^|[;&|(`]|\$\()\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sudo\s+)?(?:\S*\/)?(?:grep|egrep|fgrep|rg|ag|ack|find|fd)(?=\s|$)/;
+    HINT_PRESETS = /* @__PURE__ */ new Set(["minimal", "coordinator"]);
+  }
+});
+
 // src/modes/print/print-mode.ts
 var print_mode_exports = {};
 __export(print_mode_exports, {
@@ -47982,6 +48073,8 @@ async function runPrintMode(runtime, context) {
     return ExitCode.Usage;
   }
   const denied = [];
+  const bashCommands = /* @__PURE__ */ new Map();
+  const deniedBash = [];
   let limit;
   let plan2;
   let stopWaiting = () => void 0;
@@ -47994,12 +48087,19 @@ async function runPrintMode(runtime, context) {
       stopWaiting();
     } else if (event.type === "plan_proposed") plan2 = event;
     else if (event.type === "plan_resolved" && event.planId === plan2?.planId) plan2 = void 0;
-    if (event.type === "tool_execution_end" && event.denied === true)
+    if (event.type === "tool_execution_start" && event.toolName === "bash") {
+      const command3 = event.args?.command;
+      if (typeof command3 === "string") bashCommands.set(event.toolCallId, command3);
+    }
+    if (event.type === "tool_execution_end" && event.denied === true) {
       denied.push({
         toolCallId: event.toolCallId,
         toolName: event.toolName,
         reason: textOf5(event)
       });
+      const command3 = bashCommands.get(event.toolCallId);
+      if (event.toolName === "bash" && command3 !== void 0) deniedBash.push(command3);
+    }
     if (format === "stream-json") io.stdout(`${toJsonLine(toWireEvent(event))}
 `);
     else if (event.type === "auto_retry_start")
@@ -48078,6 +48178,16 @@ async function runPrintMode(runtime, context) {
 `
     );
   }
+  const deniedText = () => {
+    const hint = searchToolsHint(
+      deniedBash,
+      runtime.config.tools?.preset ?? "default",
+      runtime.tools.active().map((tool) => tool.name)
+    );
+    return `${describeDenied(denied)}
+${hint === void 0 ? "" : `${hint}
+`}`;
+  };
   if (signalled !== void 0) return signalled;
   if (stdoutClosed) return ExitCode.Ok;
   if (failure2 !== void 0) {
@@ -48086,8 +48196,7 @@ async function runPrintMode(runtime, context) {
     return ExitCode.RuntimeError;
   }
   if (limit !== void 0) {
-    if (denied.length > 0) io.stderr(`${describeDenied(denied)}
-`);
+    if (denied.length > 0) io.stderr(deniedText());
     io.stderr(`${describeLimit(limit)}
 `);
     return ExitCode.LimitReached;
@@ -48097,8 +48206,7 @@ async function runPrintMode(runtime, context) {
 `);
     return ExitCode.RuntimeError;
   }
-  if (denied.length > 0) io.stderr(`${describeDenied(denied)}
-`);
+  if (denied.length > 0) io.stderr(deniedText());
   if (plan2 !== void 0) {
     io.stderr(`${describePlanPending(plan2)}
 `);
@@ -48145,6 +48253,7 @@ var init_print_mode = __esm({
     init_subagent_registry();
     init_image_input();
     init_i18n();
+    init_search_hint();
     STDIN_WAIT_HINT_MS = 3e3;
     STDIN_FIRST_BYTE_MS = 2e3;
   }

package/dist/drivers/acp/client.d.ts

@@ -8,8 +8,10 @@
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
+ *   传入，原样转发。
  */
-import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification } from "./types.js";
+import { type AcpAgentCapabilities, type AcpContentBlock, type AcpImplementationInfo, type AcpInitializeResult, type AcpListSessionsResult, type AcpLoadSessionResult, type AcpNewSessionResult, type AcpPromptResult, type AcpRequestPermissionParams, type AcpRequestPermissionResult, type AcpSessionNotification, type AcpSessionOptions } from "./types.js";
 export interface AcpClientHandlers {
     onUpdate?(notification: AcpSessionNotification): void;
     /** `signal`：该会话被 cancel、连接关闭时 abort（此时应尽快回 cancelled）。 */
@@ -26,6 +28,13 @@ export interface AcpClientOptions extends AcpClientHandlers {
 export declare function unattendedOutcome(params: AcpRequestPermissionParams): AcpRequestPermissionResult;
 export declare class AcpClient {
     private readonly options;
+    /**
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     */
+    static readonly features: {
+        readonly mcpServers: true;
+    };
     private readonly peer;
     /** sessionId → 挂起权限请求的取消器。 */
     private readonly pendingPermissions;
@@ -41,11 +50,11 @@ export declare class AcpClient {
     supportsList(): boolean;
     supportsClose(): boolean;
     supportsImages(): boolean;
-    newSession(cwd: string, signal?: AbortSignal): Promise<AcpNewSessionResult>;
+    newSession(cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpNewSessionResult>;
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-    resumeSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    resumeSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     /** 回放历史（以 session/update 通知）。 */
-    loadSession(sessionId: string, cwd: string, signal?: AbortSignal): Promise<AcpLoadSessionResult>;
+    loadSession(sessionId: string, cwd: string, signal?: AbortSignal, options?: AcpSessionOptions): Promise<AcpLoadSessionResult>;
     listSessions(cwd?: string, cursor?: string): Promise<AcpListSessionsResult>;
     closeSession(sessionId: string): Promise<unknown>;
     prompt(sessionId: string, prompt: AcpContentBlock[], signal?: AbortSignal): Promise<AcpPromptResult>;

package/dist/drivers/acp/client.js

@@ -8,9 +8,15 @@
  *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
  * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
  *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ * - 开会话（new / resume / load）的 `mcpServers` 缺省为空数组；宿主可经 {@link AcpSessionOptions}
+ *   传入，原样转发。
  */
 import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
+/** 开会话参数里的 `mcpServers`：拷一份，缺省空数组。 */
+function mcpServersOf(options) {
+    return [...(options?.mcpServers ?? [])];
+}
 /** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
 export function unattendedOutcome(params) {
     const reject = params.options.find((o) => o.kind === "reject_once");
@@ -22,6 +28,11 @@ export function unattendedOutcome(params) {
 }
 export class AcpClient {
     options;
+    /**
+     * 本版客户端支持的可选能力，供宿主做特性检测（旧版没有这个字段）：
+     * - `mcpServers`：开会话时可经 {@link AcpSessionOptions} 传 MCP 服务器。
+     */
+    static features = { mcpServers: true };
     peer;
     /** sessionId → 挂起权限请求的取消器。 */
     pendingPermissions = new Map();
@@ -85,16 +96,16 @@ export class AcpClient {
     supportsImages() {
         return this.agentCapabilities.promptCapabilities?.image === true;
     }
-    newSession(cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: [] }, signal);
+    newSession(cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     /** 不回放历史（优先，R13：v2 计划取消 load）。 */
-    resumeSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: [] }, signal);
+    resumeSession(sessionId, cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     /** 回放历史（以 session/update 通知）。 */
-    loadSession(sessionId, cwd, signal) {
-        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: [] }, signal);
+    loadSession(sessionId, cwd, signal, options) {
+        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: mcpServersOf(options) }, signal);
     }
     listSessions(cwd, cursor) {
         return this.peer.request(ACP_METHODS.sessionList, {

package/dist/drivers/acp/types.d.ts

@@ -111,8 +111,28 @@ export interface AcpInitializeResult {
     authMethods?: AcpAuthMethod[];
     agentInfo?: AcpImplementationInfo;
 }
-/** ama 不向外部 Agent 传 MCP 服务器（Skills 不做 MCP），总是空数组。 */
-export type AcpMcpServer = Record<string, unknown>;
+/** `session/new.mcpServers[].env` 的一项。 */
+export type AcpEnvVariable = {
+    name: string;
+    value: string;
+};
+/** stdio 传输的 MCP 服务器：ACP v1 要求每个 Agent 都支持这一种。 */
+export type AcpStdioMcpServer = {
+    name: string;
+    command: string;
+    args: string[];
+    env: AcpEnvVariable[];
+};
+/**
+ * 交给外部 Agent 的 MCP 服务器。ama 自己不加（Skills 不做 MCP），缺省是空数组；宿主（如 Armadra）
+ * 经 {@link AcpSessionOptions} 传入的原样转发，http / sse 变体不在这里解释。
+ */
+export type AcpMcpServer = AcpStdioMcpServer | Record<string, unknown>;
+/** `AcpClient.newSession` / `resumeSession` / `loadSession` 的可选项。 */
+export interface AcpSessionOptions {
+    /** 随 `session/new|resume|load` 发给 Agent；缺省空数组。 */
+    mcpServers?: readonly AcpMcpServer[];
+}
 export interface AcpSessionMode {
     id: string;
     name: string;

package/dist/i18n/catalog.d.ts

@@ -1268,6 +1268,7 @@ declare const en: {
             limitTurns: (limit: number) => string;
             limitCost: (limit: string, spent: string) => string;
             denied: (count: number, tools: readonly string[], reason: string) => string;
+            searchToolsMissing: (preset: string, missing: readonly string[]) => string;
         };
         rpc: {
             unknownCommand: (type: string) => string;

package/dist/i18n/messages/print.d.ts

@@ -20,6 +20,7 @@ export declare const en: {
         limitTurns: (limit: number) => string;
         limitCost: (limit: string, spent: string) => string;
         denied: (count: number, tools: readonly string[], reason: string) => string;
+        searchToolsMissing: (preset: string, missing: readonly string[]) => string;
     };
     /** RPC 响应的 `error`（人读）。 */
     rpc: {
@@ -62,6 +63,7 @@ export declare const zh: {
         limitTurns: (limit: number) => string;
         limitCost: (limit: string, spent: string) => string;
         denied: (count: number, tools: readonly string[], reason: string) => string;
+        searchToolsMissing: (preset: string, missing: readonly string[]) => string;
     };
     rpc: {
         badTaskId: string;

package/dist/i18n/messages/print.js

@@ -23,6 +23,8 @@ export const en = {
         limitCost: (limit, spent) => `ama: reached the cost limit ${limit} (spent ${spent}; --max-cost / limits.maxCostUsd); run ended before finishing`,
         denied: (count, tools, reason) => `ama: ${plural(count, "tool call")} denied: ${tools.join(", ")}${reason !== "" ? ` (${reason})` : ""}; ` +
             "-p has no one to approve; to allow them use --permission-mode auto-edit|auto or --allow <rule>",
+        searchToolsMissing: (preset, missing) => `ama: the ${preset} preset has no ${missing.join(" / ")}; add ${missing.length === 1 ? "it" : "them"} with ` +
+            `tools.default: [${missing.map((name) => `"+${name}"`).join(",")}]`,
     },
     /** RPC 响应的 `error`（人读）。 */
     rpc: {
@@ -67,6 +69,8 @@ export const zh = {
         limitCost: (limit, spent) => `ama: 已达到费用上限 ${limit}（累计 ${spent}；--max-cost / limits.maxCostUsd），运行在完成前结束`,
         denied: (count, tools, reason) => `ama: ${count} 次工具调用被拒：${tools.join("、")}${reason !== "" ? `（${reason}）` : ""}；` +
             "-p 没有人审批，需要放行时用 --permission-mode auto-edit|auto 或 --allow <规则>",
+        searchToolsMissing: (preset, missing) => `ama: ${preset} 预设没有 ${missing.join(" / ")}，可用 ` +
+            `tools.default: [${missing.map((name) => `"+${name}"`).join(",")}] 加上`,
     },
     rpc: {
         badTaskId: "taskId 应为字符串",

package/dist/modes/interactive/tool-summary.js

@@ -191,6 +191,8 @@ export function resultSummary(input, theme) {
             const matches = num(details["matches"]);
             if (matches === 0)
                 return muted(m.noMatch);
+            if (details["filesOnly"] === true)
+                return muted(m.files(num(details["files"]) ?? count));
             if (matches === undefined)
                 return muted(m.lines(count));
             return muted(m.matches(matches, num(details["files"])));

package/dist/modes/print/print-mode.d.ts

@@ -14,7 +14,8 @@
  *   `context_pressure`）。
  * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
  * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
- *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
+ *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`；
+ *   [S-A] minimal / coordinator 下被拒的 bash 形如 grep / rg / find 时再补一行怎么加回 grep / glob。
  * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
  *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
  *   `maxTurnsReached: true`）、退出码 8。

package/dist/modes/print/print-mode.js

@@ -14,7 +14,8 @@
  *   `context_pressure`）。
  * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
  * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
- *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
+ *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`；
+ *   [S-A] minimal / coordinator 下被拒的 bash 形如 grep / rg / find 时再补一行怎么加回 grep / glob。
  * - [W5-H2] 预算（`--max-turns N` / `--max-cost USD` / config `limits.*`，agent/limits.ts）：到限
  *   （会话发 `limit_reached`）→ stderr 一行、json 带 `limitReached{kind, value, limit}`（回合到限另带
  *   `maxTurnsReached: true`）、退出码 8。
@@ -36,6 +37,7 @@ import { formatUsd } from "../../agent/limits.js";
 import { registryOf } from "../../agent/subagent-registry.js";
 import { promptImages, sessionModel } from "../image-input.js";
 import { msg } from "../../i18n/index.js";
+import { searchToolsHint } from "./search-hint.js";
 export function joinPrompt(argument, piped) {
     const parts = [argument ?? "", piped.replace(/\s+$/, "")].filter((p) => p.trim() !== "");
     return parts.join("\n\n");
@@ -121,6 +123,8 @@ export async function runPrintMode(runtime, context) {
         return ExitCode.Usage;
     }
     const denied = [];
+    const bashCommands = new Map();
+    const deniedBash = [];
     let limit;
     let plan;
     let stopWaiting = () => undefined;
@@ -136,12 +140,21 @@ export async function runPrintMode(runtime, context) {
             plan = event;
         else if (event.type === "plan_resolved" && event.planId === plan?.planId)
             plan = undefined;
-        if (event.type === "tool_execution_end" && event.denied === true)
+        if (event.type === "tool_execution_start" && event.toolName === "bash") {
+            const command = event.args?.command;
+            if (typeof command === "string")
+                bashCommands.set(event.toolCallId, command);
+        }
+        if (event.type === "tool_execution_end" && event.denied === true) {
             denied.push({
                 toolCallId: event.toolCallId,
                 toolName: event.toolName,
                 reason: textOf(event),
             });
+            const command = bashCommands.get(event.toolCallId);
+            if (event.toolName === "bash" && command !== undefined)
+                deniedBash.push(command);
+        }
         if (format === "stream-json")
             io.stdout(`${toJsonLine(toWireEvent(event))}\n`);
         else if (event.type === "auto_retry_start")
@@ -223,6 +236,10 @@ export async function runPrintMode(runtime, context) {
             entries: session.entries,
         })}\n`);
     }
+    const deniedText = () => {
+        const hint = searchToolsHint(deniedBash, runtime.config.tools?.preset ?? "default", runtime.tools.active().map((tool) => tool.name));
+        return `${describeDenied(denied)}\n${hint === undefined ? "" : `${hint}\n`}`;
+    };
     if (signalled !== undefined)
         return signalled;
     if (stdoutClosed)
@@ -233,7 +250,7 @@ export async function runPrintMode(runtime, context) {
     }
     if (limit !== undefined) {
         if (denied.length > 0)
-            io.stderr(`${describeDenied(denied)}\n`);
+            io.stderr(deniedText());
         io.stderr(`${describeLimit(limit)}\n`);
         return ExitCode.LimitReached;
     }
@@ -242,7 +259,7 @@ export async function runPrintMode(runtime, context) {
         return ExitCode.RuntimeError;
     }
     if (denied.length > 0)
-        io.stderr(`${describeDenied(denied)}\n`);
+        io.stderr(deniedText());
     if (plan !== undefined) {
         io.stderr(`${describePlanPending(plan)}\n`);
         return ExitCode.PlanPending;

package/dist/modes/print/search-hint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * [S-A] `-p` 下 bash 搜索命令被拒时的一行提示（docs/search-plan.md §4.2）。
+ *
+ * `minimal` / `coordinator` 预设没有 grep / glob，模型常改用 `bash grep` / `rg` / `find`，在无人值守下被拒后
+ * 只能猜文件名（§1.3 E3）。这里只在「被拒的 bash 命令形如搜索」且活动集缺 grep 或 glob 时提示怎么加回来；
+ * 不改权限判定，也不进模型上下文。
+ */
+export declare function isSearchCommand(command: string): boolean;
+/** 被拒的 bash 命令里有搜索类命令、预设是 minimal / coordinator、活动集缺 grep 或 glob → 提示一行；否则 undefined。 */
+export declare function searchToolsHint(deniedBashCommands: readonly string[], preset: string, activeTools: readonly string[]): string | undefined;

package/dist/modes/print/search-hint.js

@@ -0,0 +1,26 @@
+/**
+ * [S-A] `-p` 下 bash 搜索命令被拒时的一行提示（docs/search-plan.md §4.2）。
+ *
+ * `minimal` / `coordinator` 预设没有 grep / glob，模型常改用 `bash grep` / `rg` / `find`，在无人值守下被拒后
+ * 只能猜文件名（§1.3 E3）。这里只在「被拒的 bash 命令形如搜索」且活动集缺 grep 或 glob 时提示怎么加回来；
+ * 不改权限判定，也不进模型上下文。
+ */
+import { msg } from "../../i18n/index.js";
+/** 命令位置（行首或 `;` `&` `|` `(` 之后，允许前置 `VAR=x` / `sudo`）上的搜索类程序。 */
+const SEARCH_COMMAND = /(?:^|[;&|(`]|\$\()\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sudo\s+)?(?:\S*\/)?(?:grep|egrep|fgrep|rg|ag|ack|find|fd)(?=\s|$)/;
+/** 只在这两个预设下提示：`default` 本来就有 grep / glob，`codemode-only` 的脚本里可调用它们。 */
+const HINT_PRESETS = new Set(["minimal", "coordinator"]);
+export function isSearchCommand(command) {
+    return SEARCH_COMMAND.test(command);
+}
+/** 被拒的 bash 命令里有搜索类命令、预设是 minimal / coordinator、活动集缺 grep 或 glob → 提示一行；否则 undefined。 */
+export function searchToolsHint(deniedBashCommands, preset, activeTools) {
+    if (!HINT_PRESETS.has(preset))
+        return undefined;
+    const missing = ["grep", "glob"].filter((name) => !activeTools.includes(name));
+    if (missing.length === 0)
+        return undefined;
+    if (!deniedBashCommands.some(isSearchCommand))
+        return undefined;
+    return msg().print.print.searchToolsMissing(preset, missing);
+}

package/dist/tools/glob.js

@@ -197,7 +197,8 @@ export function createGlobTool() {
         name: "glob",
         label: "Glob",
         description: "Find files by glob (`**`, `*`, `?`, `[...]`, `{a,b}`, leading `!` excludes). " +
-            "Patterns without `/` match names at any depth. Respects .gitignore/.ignore; newest first.",
+            "Patterns without `/` match names at any depth. Respects .gitignore/.ignore; newest first. " +
+            "Use to discover files before read.",
         parameters: {
             type: "object",
             properties: {

package/dist/tools/grep.d.ts

@@ -5,6 +5,8 @@
  * - 文件按路径排序处理，输出确定；匹配行 `path:line: text`，上下文行 `path-line- text`，
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
+ * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
+ *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 export interface GrepInput {
@@ -15,6 +17,7 @@ export interface GrepInput {
     literal?: boolean;
     context?: number;
     limit?: number;
+    filesOnly?: boolean;
 }
 export declare const DEFAULT_GREP_LIMIT = 100;
 export declare const GREP_MAX_FILE_BYTES: number;

package/dist/tools/grep.js

@@ -5,6 +5,8 @@
  * - 文件按路径排序处理，输出确定；匹配行 `path:line: text`，上下文行 `path-line- text`，
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
+ * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
+ *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
  */
 import { readFile, stat } from "node:fs/promises";
 import { displayPath, resolvePath } from "./paths.js";
@@ -23,7 +25,7 @@ export function compilePattern(input) {
     const source = input.literal ? escapeRegExp(input.pattern) : input.pattern;
     return new RegExp(source, input.ignoreCase ? "i" : "");
 }
-async function searchFile(abs, regex) {
+async function searchFile(abs, regex, firstOnly = false) {
     try {
         const info = await stat(abs);
         if (!info.isFile() || info.size > GREP_MAX_FILE_BYTES)
@@ -35,10 +37,13 @@ async function searchFile(abs, regex) {
         if (lines[lines.length - 1] === "")
             lines.pop();
         const hits = [];
-        lines.forEach((line, i) => {
-            if (regex.test(line))
-                hits.push(i);
-        });
+        for (let i = 0; i < lines.length; i++) {
+            if (!regex.test(lines[i]))
+                continue;
+            hits.push(i);
+            if (firstOnly)
+                break;
+        }
         return hits.length > 0 ? { lines, hits } : undefined;
     }
     catch {
@@ -103,6 +108,8 @@ export async function executeGrep(input, ctx) {
         return { content: `Path not found: ${displayPath(root, ctx.cwd)}`, isError: true };
     }
     const files = await candidateFiles(root, rootIsFile, input.glob, ctx.signal);
+    if (input.filesOnly === true)
+        return grepFilesOnly(files, regex, limit, ctx);
     const blocks = [];
     let matches = 0;
     let matchedFiles = 0;
@@ -150,22 +157,52 @@ export async function executeGrep(input, ctx) {
         details: { matches, files: matchedFiles, limited, truncated: cut.truncated },
     };
 }
+/** [S-A] filesOnly：命中文件的显示路径，去重并按路径排序；limit 按文件数计。 */
+async function grepFilesOnly(files, regex, limit, ctx) {
+    const sorted = [...new Set(files)].sort();
+    const shown = [];
+    let limited = false;
+    outer: for (let i = 0; i < sorted.length; i += GREP_CONCURRENCY) {
+        if (ctx.signal.aborted)
+            return { content: "aborted by user", isError: true };
+        const batch = sorted.slice(i, i + GREP_CONCURRENCY);
+        const results = await Promise.all(batch.map((f) => searchFile(f, regex, true)));
+        for (let j = 0; j < batch.length; j++) {
+            if (!results[j])
+                continue;
+            if (shown.length >= limit) {
+                limited = true;
+                break outer;
+            }
+            shown.push(displayPath(batch[j], ctx.cwd));
+        }
+    }
+    if (shown.length === 0) {
+        return { content: "No matches found", details: { matches: 0, files: 0, filesOnly: true } };
+    }
+    const unique = [...new Set(shown)].sort();
+    let content = unique.join("\n");
+    if (limited)
+        content += `\n\n[Stopped at ${limit} files. Narrow the search or raise limit.]`;
+    return { content, details: { files: unique.length, filesOnly: true, limited } };
+}
 export function createGrepTool() {
     return {
         name: "grep",
         label: "Grep",
-        description: "Search file contents by JS regex. Respects .gitignore/.ignore; skips binary and >2 MB " +
-            "files. Output: `path:line: text`.",
+        description: "Use to find where a symbol or text appears (JS regex). Skips ignored, binary, >2 MB " +
+            "files. Output `path:line: text`; filesOnly lists matching files.",
         parameters: {
             type: "object",
             properties: {
                 pattern: { type: "string" },
-                path: { type: "string", description: "File or dir (default: cwd)" },
-                glob: { type: "string", description: "File filter, e.g. *.ts" },
+                path: { type: "string", description: "File or dir" },
+                glob: { type: "string", description: "e.g. *.ts" },
                 ignoreCase: { type: "boolean" },
                 literal: { type: "boolean" },
                 context: { type: "integer", description: "0-5 lines" },
                 limit: { type: "integer", description: `Default ${DEFAULT_GREP_LIMIT}` },
+                filesOnly: { type: "boolean" },
             },
             required: ["pattern"],
             additionalProperties: false,

package/dist/tools/read.d.ts

@@ -21,6 +21,11 @@ export interface ReadToolOptions {
     imageOptions?(ctx: ToolContext): ImageFitOptions;
 }
 export declare function isBinary(buf: Buffer): boolean;
+/**
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * 活动集未知（宿主自建上下文）时沿用旧文案。
+ */
+export declare function directoryHint(shown: string, ctx: Pick<ToolContext, "activeTools">): string;
 /** `cat -n` 形状。 */
 export declare function numberLines(lines: readonly string[], firstLine: number): string;
 export declare function executeRead(input: ReadInput, ctx: ToolContext, options?: ReadToolOptions): Promise<ToolResult>;

package/dist/tools/read.js

@@ -23,6 +23,25 @@ export function isBinary(buf) {
 function error(message) {
     return { content: message, isError: true };
 }
+/**
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * 活动集未知（宿主自建上下文）时沿用旧文案。
+ */
+export function directoryHint(shown, ctx) {
+    const active = ctx.activeTools;
+    if (active === undefined || active.has("ls"))
+        return "use the ls tool instead";
+    if (active.has("glob")) {
+        if (shown === ".")
+            return 'use glob (e.g. pattern "*")';
+        // cwd 外（绝对路径）或目录名含 glob 元字符时改用 path 参数，模式保持 `*`
+        if (shown.startsWith("/") || /^[A-Za-z]:/.test(shown) || /[*?[\]{}!\\]/.test(shown)) {
+            return `use glob (e.g. path ${JSON.stringify(shown)}, pattern "*")`;
+        }
+        return `use glob (e.g. pattern ${JSON.stringify(`${shown}/*`)})`;
+    }
+    return "read a file inside it";
+}
 /** `cat -n` 形状。 */
 export function numberLines(lines, firstLine) {
     return lines.map((line, i) => `${String(firstLine + i).padStart(6)}\t${line}`).join("\n");
@@ -64,7 +83,7 @@ export async function executeRead(input, ctx, options = {}) {
         return error(`File not found: ${shown}`);
     }
     if (info.isDirectory())
-        return error(`${shown} is a directory; use the ls tool instead`);
+        return error(`${shown} is a directory; ${directoryHint(shown, ctx)}`);
     if (imageMimeFromPath(abs) !== undefined)
         return readImage(abs, shown, ctx, options);
     const buf = await readFile(abs);

package/dist/tools/types.d.ts

@@ -230,6 +230,11 @@ export interface ToolContext {
     /** 本会话已 read 的绝对路径（write / edit 先读后写检查）。 */
     readonly readFiles: ReadonlySet<string>;
     markRead(absolutePath: string): void;
+    /**
+     * [S-A] 本次调用时模型可直接调用的工具名（会话活动集，只读快照）；工具据此给出可执行的提示
+     * （如 read 收到目录时说用 ls 还是 glob）。宿主 / SDK 自建上下文可不给。
+     */
+    readonly activeTools?: ReadonlySet<string>;
     /**
      * 嵌套调用其它工具（codemode 脚本、task），受同一管线；按全部未禁用工具查找（不限于活动集），
      * 发带 `parentToolCallId` 的 tool_execution_* 事件。`signal`：与 ctx.signal 合并，用于提前取消

package/docs/acp.md

@@ -64,6 +64,9 @@ stdin 关闭后等已开始的运行结束再退出（0）；SIGINT / SIGTERM
 - `session/request_permission` 交给 `onPermission`；没有处理器时回首个 `reject_once`（无人值守）。
 - `cancel(sessionId)` 发 `session/cancel`，并让该会话挂起的权限请求回 `cancelled`（规范要求）。
 - 只接受 Agent 自己给出的 `optionId`。
+- 开会话（`newSession` / `resumeSession` / `loadSession`）的 `mcpServers` 缺省为空数组；宿主可传第三个参数
+  `{ mcpServers }`（如 stdio 的 `{ name, command, args, env: [{ name, value }] }`），原样转发给 Agent。
+  `AcpClient.features.mcpServers === true` 表示支持（旧版没有 `features`）。ama 自己作客户端时仍不传。
 
 `AcpDriver` 在客户端之上实现驱动契约（`AgentDriver`）：续接优先 `session/resume`，其次 `session/load`（回放的历史丢弃），都不支持就新开并提示；按 ama 模式 `session/set_mode`，只读模式找不到对应模式 id 时拒绝启动。
 

package/docs/codemode.md

@@ -24,6 +24,8 @@
 
 缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、网络由 Node 还是操作系统沙箱隔离）；`ama doctor` 另列操作系统沙箱能力。
 
+`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
+
 `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
 `codemode` 本身的权限类随沙箱能力：网络隔离（Node ≥ 25，或有操作系统沙箱，见下文沙箱）时是 `read` 类，`default` 权限模式下免审批——脚本只能经 `tools.*` 做事，每次内层调用仍逐个经过权限管线；网络未隔离（Node 22 / 24 且没有操作系统沙箱）时是 `execute` 类，`default` 模式下每次都要审批，`-p` 等无人值守场景直接拒绝，此时常用做法是在配置里放行它：

package/docs/en/host-api.md

@@ -100,7 +100,7 @@ interface ToolResult {
 }
 ```
 
-`ToolContext` provides `toolCallId`, `cwd`, `sessionId`, `sessionFile?`, `signal`, `depth`, `model?`, `thinkingLevel?`, `outputDir?`, `onUpdate(partial)` (output while running), `readFiles` / `markRead`, `tools.executeTool(name, input)` (nested calls through the same pipeline), `session.appendCustom` / `lastCustom` (custom entries that never enter the context, see [session-format.md](../session-format.md), Chinese), `spawnSubagent?` and `log`.
+`ToolContext` provides `toolCallId`, `cwd`, `sessionId`, `sessionFile?`, `signal`, `depth`, `model?`, `thinkingLevel?`, `outputDir?`, `onUpdate(partial)` (output while running), `readFiles` / `markRead`, `activeTools?` (read-only snapshot of the session's active tool set, so tools can give actionable hints), `tools.executeTool(name, input)` (nested calls through the same pipeline), `session.appendCustom` / `lastCustom` (custom entries that never enter the context, see [session-format.md](../session-format.md), Chinese), `spawnSubagent?` and `log`.
 
 Host tools take the same path as built-in tools: schema validation → command hook PreToolUse → permission pipeline (classified by `permission`) → approval → execution → PostToolUse. They can also be called from codemode scripts as `tools.<name>()`.
 

package/docs/host-api.md

@@ -95,7 +95,7 @@ interface ToolResult {
 }
 ```
 
-`ToolContext` 提供 `toolCallId`、`cwd`、`sessionId`、`sessionFile?`、`signal`、`depth`、`model?`、`thinkingLevel?`、`outputDir?`、`onUpdate(partial)`（运行中输出）、`readFiles` / `markRead`、`tools.executeTool(name, input)`（嵌套调用，受同一管线）、`session.appendCustom` / `lastCustom`（不进上下文的 custom 条目，见 [session-format.md](session-format.md)）、`spawnSubagent?`、`log`。
+`ToolContext` 提供 `toolCallId`、`cwd`、`sessionId`、`sessionFile?`、`signal`、`depth`、`model?`、`thinkingLevel?`、`outputDir?`、`onUpdate(partial)`（运行中输出）、`readFiles` / `markRead`、`activeTools?`（会话活动集的只读快照，工具据此给可执行的提示）、`tools.executeTool(name, input)`（嵌套调用，受同一管线）、`session.appendCustom` / `lastCustom`（不进上下文的 custom 条目，见 [session-format.md](session-format.md)）、`spawnSubagent?`、`log`。
 
 宿主工具与内置工具走同一条路径：schema 校验 → 命令式 Hook PreToolUse → 权限管线（按 `permission` 分类）→ 审批 → 执行 → PostToolUse。在 codemode 脚本里也能以 `tools.<name>()` 调用。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [