@armadra/agent 0.6.5 → 0.6.7

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.7 (2026-10-03)
+
+- **A host runner with id `ama` is used**: when the host registers a runner for `ama` via `HostApi.runners.provide`
+  (for example another ama node on an Armadra canvas), `task(agent="ama")` now goes to it instead of being unknown; without
+  one nothing changes, and the built-in types (`general` / `explore` / `plan`) are always ama sub-sessions. Docs:
+  docs/agents.md.
+
+## 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

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,21 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.7（2026-10-03）
+
+- **宿主注入的 `ama` runner 生效**：宿主经 `HostApi.runners.provide` 注入 id 为 `ama` 的 runner（如 Armadra 画布上另一个
+  ama 节点）时，`task(agent="ama")` 交给它；没注入时行为不变，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
+  文档：docs/agents.md。
+
+## 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` 新增可选的第三个参数

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/agents/external.d.ts

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -34,6 +35,11 @@ export declare const externalTesting: {
 export declare function isExternalSpec(name: string): boolean;
 /** 外部 CLI 的类型（`task(agent="claude")`）。 */
 export declare function externalDefinition(spec: string): AgentDefinition;
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export declare const HOST_AMA_RUNNER = "host:ama";
 export declare function hostDefinition(runner: HostRunner): AgentDefinition;
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export declare function externalOnPath(spec: string, env: NodeJS.ProcessEnv): boolean;

package/dist/agents/external.js

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -58,8 +59,17 @@ function definition(name, runner, description, source) {
 export function externalDefinition(spec) {
     return definition(spec, spec, `External ${labelOf(spec)} CLI (its own login, model and permission policy; full instructions in prompt).`, "builtin");
 }
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export const HOST_AMA_RUNNER = "host:ama";
+/** 宿主 runner id → 类型里的 runner 名。 */
+function hostRunnerName(id) {
+    return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 export function hostDefinition(runner) {
-    return definition(runner.id, runner.id, runner.description, "host");
+    return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export function externalOnPath(spec, env) {
@@ -207,8 +217,16 @@ export class SessionExternalAgents {
     runner(agent) {
         if (agent.runner === "ama")
             return undefined;
-        const spec = agent.runner;
+        // 宿主注入的 `ama` 走宿主；宿主已注销时报不可用，不退回自起（驱动表里也有一个 ama）。
+        // 宿主 id 不在 AgentRunnerSpec 的字面量里（见 definition），按字符串比
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec);
+        if (hostAma && host === undefined) {
+            const error = new AmaError("agent_host_only", `"ama" was provided by the host and is no longer available`);
+            return { id: spec, start: () => Promise.reject(error) };
+        }
         let inner;
         try {
             inner = this.agents.resolve(spec);

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.5" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.7" : 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++;
@@ -33492,8 +33541,11 @@ function externalDefinition(spec2) {
     "builtin"
   );
 }
+function hostRunnerName(id) {
+  return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 function hostDefinition(runner) {
-  return definition(runner.id, runner.id, runner.description, "host");
+  return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 function externalOnPath(spec2, env) {
   const found = candidatesFor(spec2);
@@ -33545,7 +33597,7 @@ function mergeAgentInfos(base4, external) {
   }
   return out;
 }
-var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, ExternalTaskHandle, infoCache, SessionExternalAgents;
+var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, HOST_AMA_RUNNER, ExternalTaskHandle, infoCache, SessionExternalAgents;
 var init_external = __esm({
   "src/agents/external.ts"() {
     "use strict";
@@ -33562,6 +33614,7 @@ var init_external = __esm({
     LISTED_EXTERNAL_AGENTS = ["claude", "codex"];
     NO_AGENT_PROBE_ENV = "AMA_NO_AGENT_PROBE";
     externalTesting = {};
+    HOST_AMA_RUNNER = "host:ama";
     ExternalTaskHandle = class {
       constructor(inner, reopen) {
         this.inner = inner;
@@ -33640,8 +33693,17 @@ var init_external = __esm({
       /** 注册表的 `runners(agent)`：ama 子会话类型返回 undefined。 */
       runner(agent) {
         if (agent.runner === "ama") return void 0;
-        const spec2 = agent.runner;
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec2 = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec2);
+        if (hostAma && host === void 0) {
+          const error2 = new AmaError(
+            "agent_host_only",
+            `"ama" was provided by the host and is no longer available`
+          );
+          return { id: spec2, start: () => Promise.reject(error2) };
+        }
         let inner;
         try {
           inner = this.agents.resolve(spec2);
@@ -45639,6 +45701,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"])));
     }
@@ -47910,6 +47973,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, {
@@ -48002,6 +48086,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;
@@ -48014,12 +48100,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")
@@ -48098,6 +48191,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) {
@@ -48106,8 +48209,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;
@@ -48117,8 +48219,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)}
 `);
@@ -48165,6 +48266,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/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/agents.md

@@ -259,7 +259,7 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 
 ### 嵌入宿主
 
-有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。
+有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。宿主注入的 runner id 也可以是 `ama`（例如画布上另一个 ama 节点）：`task(agent="ama")` 交给宿主，不起子会话；没注入时 `ama` 照旧不是可用类型，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
 
 **在 Armadra 画布终端里直接运行 ama（没有 `--host`）**：此时 ama 按独立模式工作，自己启动的外部 Agent 是这个终端节点里的子进程，不会出现在画布上，也不经连线授权；需要让多个 Agent 在画布上协同，就在画布上连线 Agent 节点，或以宿主模式嵌入 ama。终端带着该节点的身份变量（`ARMADRA_NODE_ID`、`ARMADRA_SESSION_ID`、Hook 端点、`ARMADRA_CANVAS_CONTROL` 等），ama 起子进程时一律剥离（askpass 除外），否则 Armadra 装在 Claude / Codex 上的 Hook 会把子 Agent 的事件记到这个节点名下。
 

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.5",
+  "version": "0.6.7",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [