@armadra/agent 0.10.0 → 0.11.0

package/dist/tools/web/url-guard.js

@@ -0,0 +1,221 @@
+/**
+ * `web_fetch` 的地址守卫（docs/guides/permissions.md「网络类」）：URL 校验、私网 / 元数据地址判定、
+ * DNS 钉住与重定向策略。纯 `node:*`，模型侧固定英文。
+ *
+ * - URL：只收 `http:` / `https:`；拒 userinfo；全文 ≤ 2 048 字符、查询串 ≤ 1 024 字符；主机名必须含 `.`
+ *   （`localhost`、`*.localhost` 与无点主机一律拒——本机服务请走 bash 审批）；IP 字面量当场判定。
+ * - 地址：解析出的**全部**地址都不得落在环回、未指定、链路本地（含云元数据 `169.254.169.254`）、
+ *   RFC 1918、运营商 NAT `100.64/10`、基准测试 `198.18/15`、保留与广播、组播、IPv6 ULA `fc00::/7`、
+ *   站点本地 `fec0::/10`、链路本地 `fe80::/10`、组播 `ff00::/8`、未指定与已弃用的兼容段 `::/96`；IPv4 映射 / 兼容、NAT64 `64:ff9b::/96`、
+ *   6to4 `2002::/16` 里嵌的 IPv4 按 IPv4 再判一次。有一个落在里面就拒（防「多地址里夹一个内网」）。
+ * - DNS 钉住：连接用 `pinnedLookup()` 只返回已检查过的地址，防检查与连接之间被重新解析（DNS 重绑定）。
+ * - 重定向：同主机（主机名与端口相同、不从 https 降到 http）由调用方跟随并逐跳重检；跨主机不跟。
+ */
+import { lookup as dnsLookup } from "node:dns";
+import { BlockList, isIP } from "node:net";
+export const MAX_URL_LENGTH = 2048;
+export const MAX_QUERY_LENGTH = 1024;
+export const MAX_SAME_HOST_REDIRECTS = 5;
+const V4_BLOCKED = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+];
+const V6_BLOCKED = [
+    ["::", 96],
+    ["::1", 128],
+    ["100::", 64],
+    ["2001:db8::", 32],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["fec0::", 10],
+    ["ff00::", 8],
+];
+/** 常见云元数据地址：错误说明里单独点名。 */
+const METADATA = new Set(["169.254.169.254", "100.100.100.200", "fd00:ec2::254"]);
+const blocked = new BlockList();
+for (const [net, prefix] of V4_BLOCKED)
+    blocked.addSubnet(net, prefix, "ipv4");
+for (const [net, prefix] of V6_BLOCKED)
+    blocked.addSubnet(net, prefix, "ipv6");
+/** IPv6 文本 → 8 个 16 位组；不合法返回 undefined。支持 `::` 与末尾点分 IPv4。 */
+export function ipv6Groups(address) {
+    let text = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    const v4 = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (v4 !== null) {
+        const parts = v4[1].split(".").map(Number);
+        if (parts.some((p) => p > 255))
+            return undefined;
+        const [a, b, c, d] = parts;
+        text = `${text.slice(0, v4.index)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return undefined;
+    const parse = (part) => part === ""
+        ? []
+        : part.split(":").map((g) => (/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN));
+    const head = parse(halves[0]);
+    const tail = halves.length === 2 ? parse(halves[1]) : [];
+    const fill = 8 - head.length - tail.length;
+    if (halves.length === 1 ? fill !== 0 : fill < 1)
+        return undefined;
+    const groups = [...head, ...new Array(halves.length === 2 ? fill : 0).fill(0), ...tail];
+    return groups.some((g) => Number.isNaN(g)) ? undefined : groups;
+}
+function v4FromGroups(hi, lo) {
+    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}
+/** IPv6 里嵌的 IPv4（映射 / 兼容 / NAT64 / 6to4）；没有返回 undefined。 */
+export function embeddedIPv4(address) {
+    const g = ipv6Groups(address);
+    if (g === undefined)
+        return undefined;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    // 映射 ::ffff:a.b.c.d；兼容 ::a.b.c.d 只认首段非 0 的（`::`、`::1` 留给 IPv6 段表）
+    if (zeros(0, 5) && (g[5] === 0xffff || (g[5] === 0 && g[6] >= 0x100)))
+        return v4FromGroups(g[6], g[7]);
+    if (g[0] === 0x64 && g[1] === 0xff9b && zeros(2, 6))
+        return v4FromGroups(g[6], g[7]);
+    if (g[0] === 0x2002)
+        return v4FromGroups(g[1], g[2]);
+    return undefined;
+}
+/**
+ * 地址是否落在禁止段；落在里面返回英文原因（进工具结果），否则 undefined。
+ * 不是 IP 文本的一律按禁止（调用方只该传解析结果）。
+ */
+export function blockedAddressReason(address) {
+    const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+    const family = isIP(bare);
+    if (family === 0)
+        return `${address} is not an IP address`;
+    const lower = bare.toLowerCase();
+    if (METADATA.has(lower))
+        return `${bare} is a cloud metadata address`;
+    if (family === 4) {
+        if (bare === "255.255.255.255" || blocked.check(bare, "ipv4"))
+            return `${bare} is a private, loopback, link-local or reserved address`;
+        return undefined;
+    }
+    const inner = embeddedIPv4(lower);
+    if (inner !== undefined) {
+        const reason = blockedAddressReason(inner);
+        if (reason !== undefined)
+            return `${bare} embeds ${inner}: ${reason}`;
+    }
+    if (blocked.check(lower, "ipv6"))
+        return `${bare} is a private, loopback, link-local or multicast address`;
+    return undefined;
+}
+/** 主机名：去方括号与末尾点，小写。 */
+export function bareHostname(url) {
+    return url.hostname
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "")
+        .toLowerCase();
+}
+/** 静态校验（不查 DNS）：协议、userinfo、长度、主机名形状、IP 字面量。 */
+export function checkFetchUrl(raw) {
+    if (typeof raw !== "string" || raw.trim() === "")
+        return { ok: false, reason: "url is empty" };
+    const text = raw.trim();
+    if (text.length > MAX_URL_LENGTH)
+        return { ok: false, reason: `URL is longer than ${MAX_URL_LENGTH} characters` };
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return { ok: false, reason: "not a valid absolute URL" };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return { ok: false, reason: `only http and https URLs are supported (got ${url.protocol})` };
+    if (url.username !== "" || url.password !== "")
+        return { ok: false, reason: "URLs with credentials (user:pass@) are not allowed" };
+    if (url.search.length > MAX_QUERY_LENGTH + 1)
+        return { ok: false, reason: `query string is longer than ${MAX_QUERY_LENGTH} characters` };
+    const hostname = bareHostname(url);
+    if (isIP(hostname) !== 0) {
+        const reason = blockedAddressReason(hostname);
+        return reason === undefined ? { ok: true, url, hostname } : { ok: false, reason };
+    }
+    if (!hostname.includes(".") || hostname === "localhost" || hostname.endsWith(".localhost"))
+        return {
+            ok: false,
+            reason: `${hostname} is a local host name; web_fetch only reaches public hosts`,
+        };
+    return { ok: true, url, hostname };
+}
+/** 缺省解析：系统解析器，返回全部地址。 */
+export const systemLookup = (hostname) => new Promise((resolve, reject) => {
+    dnsLookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
+        if (err)
+            reject(err);
+        else
+            resolve(addresses);
+    });
+});
+/** 解析主机名并检查全部地址；IP 字面量直接返回。 */
+export async function resolvePublicAddresses(hostname, lookup = systemLookup) {
+    const family = isIP(hostname);
+    if (family !== 0) {
+        const reason = blockedAddressReason(hostname);
+        return reason === undefined
+            ? { ok: true, addresses: [{ address: hostname, family }] }
+            : { ok: false, reason };
+    }
+    let addresses;
+    try {
+        addresses = await lookup(hostname);
+    }
+    catch (err) {
+        const code = err.code;
+        return { ok: false, reason: `cannot resolve ${hostname}${code ? ` (${code})` : ""}` };
+    }
+    if (addresses.length === 0)
+        return { ok: false, reason: `cannot resolve ${hostname}` };
+    for (const { address } of addresses) {
+        const reason = blockedAddressReason(address);
+        if (reason !== undefined)
+            return { ok: false, reason: `${hostname} resolves to ${reason}` };
+    }
+    return { ok: true, addresses };
+}
+/** `http.request({ lookup })` 用：只返回已检查过的地址（兼容 `all: true` 与单地址两种调用）。 */
+export function pinnedLookup(addresses) {
+    return (_hostname, options, callback) => {
+        const cb = (typeof options === "function" ? options : callback);
+        const all = typeof options === "object" && options !== null && options.all;
+        const first = addresses[0];
+        if (all === true)
+            cb(null, [...addresses]);
+        else
+            cb(null, first.address, first.family);
+    };
+}
+/**
+ * 重定向能否自动跟：同主机名，且同协议同端口或 http → https 升级。其余（跨主机、换端口、
+ * https 降到 http）不跟：交给模型再调一次 web_fetch，下一次调用重新过权限。
+ */
+export function redirectPolicy(from, to) {
+    if (bareHostname(from) !== bareHostname(to))
+        return "cross-host";
+    if (from.protocol === "http:" && to.protocol === "https:")
+        return "follow";
+    return from.protocol === to.protocol && portOf(from) === portOf(to) ? "follow" : "cross-host";
+}
+function portOf(url) {
+    return url.port !== "" ? url.port : url.protocol === "https:" ? "443" : "80";
+}

package/docs/en/guides/permissions.md

@@ -39,7 +39,7 @@ Read-only commands are a static list (next section) shared by `plan` and `allowl
 
 ### Origin labels in the approval dialog
 
-Approvals do not only come from the main session. The dialog (and RPC `permission_request.context`) shows where a request comes from; the options are always just "allow / allow this kind for the session / deny":
+Approvals do not only come from the main session. The dialog (and RPC `permission_request.context`) shows where a request comes from; the options are always just "allow / allow this kind for the session / deny" (for `web_fetch` the second one is "allow `<host>` for this session"):
 
 | Origin                                                          | Title prefix                                         | Body                                                                          | Who decides                                                                                                 |
 | --------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
@@ -73,6 +73,27 @@ Read-only commands (`src/permissions/readonly-bash.ts`): first they pass auto's
 
 This is narrower than auto's safe list: no test / build runners (`npm test` and `cargo build` run project scripts), and no `env` / `printenv` (they would print secrets in environment variables into the context). Reading secret paths (`cat .env`) is not read-only.
 
+## Network class: web_fetch
+
+`web_fetch` is the only network tool (it reads one URL; there is no search), with permission class `network`:
+
+| Mode                   | `web_fetch`                                                                                                                                                                                                                                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default`, `auto-edit` | Ask; the second option is "allow `<host>` for this session", after which the same host (any path, port or letter case) no longer asks                                                                                                                                                                                       |
+| `plan`                 | Ask (read-only, but it can carry data out; research often needs docs, so it is not denied). Denied inside read-only sub-agents                                                                                                                                                                                              |
+| `allowlist`            | Only calls matched by an allow rule; everything else is denied                                                                                                                                                                                                                                                              |
+| `auto`                 | Rule tier: a URL that is not public http(s) (local names, private / metadata IPs, `file:`, credentials) is denied; allow rules, hook allow and session grants allow; the rest goes to the classifier (public docs and package-registry pages are routine; a query string that looks like a key or a long random token asks) |
+| `full-auto`            | Allow                                                                                                                                                                                                                                                                                                                       |
+
+Unattended (`-p`), every ask becomes a deny; use `--allow 'web_fetch(<domain>)'` to let it through.
+
+- **Rules** `web_fetch(<pattern>)` match `host/path` (no scheme, port or query string; lower-case host). A pattern without `/` compares the host only: a bare domain `example.com` matches itself and all subdomains, `*.example.com` only subdomains. A pattern with `/` is a glob over the whole `host/path`, where `*` does not cross `/` and `**` does (`docs.example.com/api/**`). Deny rules are checked first in every mode: `permission.deny: ["web_fetch(*.internal.example.com)"]`.
+- **Execution guard** (every mode, `full-auto` included): only `http:` / `https:`, no URLs with credentials; URL ≤ 2048 characters, query string ≤ 1024; the host name must contain a `.` (`localhost`, `*.localhost` and dotless hosts are refused; reach local services through an approved bash call). **Every** resolved address must be outside loopback, `0.0.0.0/8`, RFC 1918, `100.64/10`, link-local (including the cloud metadata addresses `169.254.169.254`, `100.100.100.200`, `fd00:ec2::254`), reserved and multicast ranges, IPv6 ULA `fc00::/7`, `fe80::/10`, `fec0::/10`, `ff00::/8`; IPv4 embedded in mapped / NAT64 / 6to4 addresses is checked as IPv4. The connection is pinned to the checked addresses so a re-resolution cannot swap in an internal one (DNS rebinding).
+- **Redirects**: same host (same scheme and port, or an http → https upgrade) is followed up to 5 hops, re-checked at each hop; a cross-host redirect is not followed — the result tells the model the target URL, and calling it again goes through permissions again.
+- **Limits**: 30 s total, 15 s to the first byte, response body (after decompression) ≤ 5 MB; GET only, no cookies or custom headers. Output is cut at 50 000 characters by default (200 000 at most); when cut, the full text goes to the session's `outputs/<call id>.txt` and the model continues with `offset`. The first line is always `Content fetched from <URL> (untrusted):` to mark external content.
+- **Turning it off**: `tools.disabled: ["web_fetch"]` (user, profile or project config), `tools.default: ["-web_fetch"]`, host `tools.disable("web_fetch")`, or `permission.deny: ["web_fetch"]`. No new config keys or environment variables.
+- `web_fetch` runs inside the ama process: the bash OS sandbox and `sandbox.network` do not apply, and it does not use `HTTPS_PROXY` (a proxy resolves host names itself, so the address could not be pinned); see [sandbox.md](../../guides/sandbox.md) "Known bypasses" (Chinese).
+
 ## Decision order
 
 One tool call (issued directly by the model or nested inside codemode / task, alike):
@@ -133,6 +154,7 @@ No model call; a match asks (denied when unattended):
 | Secret paths          | Reading or writing `.env`, `.env.*` (except `.env.example` / `.sample` / `.template` / `.dist`), `.ssh/`, `.gnupg/`, `.aws/`, `.kube/config`, `.docker/config.json`, `.netrc`, `.pgpass`, private keys (`id_rsa` etc., `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`), ama's `auth.json`         |
 | Protected writes      | Writing inside `.git/`, the project's `.ama/` (could change hooks and config), or any path outside the project directory (except `/dev/null` and the like)                                                                                                                                     |
 | Network commands      | `curl`, `wget`, `ssh`, `scp`, `rsync`, `nc`, `gh`; `git push / pull / fetch / clone`; `npm / pnpm / yarn / bun install / add / ci / update / publish / dlx`, `npx`; `pip install`, `cargo install / publish`, `go get / install`, `brew / apt install`, `docker pull / push / login` and so on |
+| Web fetch             | A `web_fetch` URL that is not public http(s) is **denied** outright (no prompt; see [Network class](#network-class-web_fetch))                                                                                                                                                                 |
 | Deletion and rollback | `rm -r` / `rm -f`, `find -delete`, `git clean`, `git checkout -- …` / `git restore`, `git stash drop / clear`, `shred`, `truncate`                                                                                                                                                             |
 | Paths in bash         | Redirect targets (`>`, `>>`, `&>`, `tee`), and targets of `cp` / `mv` / `mkdir` / `touch` / `ln` / `chmod` outside the project or protected; secret paths among command arguments (`cat .env`)                                                                                                 |
 

package/docs/en/reference/host-api.md

@@ -5,7 +5,7 @@ English · [简体中文](../../reference/host-api.md)
 > Translated from the Chinese [docs/reference/host-api.md](../../reference/host-api.md) as of commit `979608b`. When the two differ, the Chinese
 > version is authoritative.
 
-A host adapter is a local JS module that ama loads at startup and hands a `HostApi`. With it the adapter can register tools, append to the system prompt, observe events, answer approvals, inject user messages and show notifications and status in the interface. The Armadra canvas plugs in as a host adapter (the canvas tools `canvas_*` / `context_*` are all registered by the adapter). The types are defined in `src/host/types.ts` and exported from `@armadra/agent/host`; `HOST_API_VERSION = 1`. The design rationale is in [design.md](../../design/design.md) §6.2, §6.3 and §11.1 step 13 (Chinese).
+A host adapter is a local JS module that ama loads at startup and hands a `HostApi`. With it the adapter can register tools, append to the system prompt, observe events, answer approvals, inject user messages and show notifications and status in the interface. The Armadra canvas plugs in as a host adapter (the canvas tools `canvas_*` / `context_*` are all registered by the adapter). The types are defined in `src/host/types.ts` and exported from `@armadra/agent/host`; `HOST_API_VERSION = 1`, `HOST_API_MINOR = 1` (host-api 1.1, see "Versioning"). The design rationale is in [design.md](../../design/design.md) §6.2, §6.3 and §11.1 step 13 (Chinese).
 
 ## Module shape
 
@@ -51,26 +51,40 @@ export function create(api) {
 | `create()` throws or does not return within 10 seconds     | 6         |
 | The returned adapter has no `id`                           | 6         |
 
+## Versioning
+
+- **Major** `HOST_API_VERSION` (`api.version`): the host's exported `hostApi` must equal it exactly. It changes only for breaking changes (removing or changing existing members or semantics) and then requires a breaking ama release (`pnpm release:check`).
+- **Minor** `HOST_API_MINOR` (`api.minor`): bumped once per batch of additive optional members; existing hosts are unaffected and the major version stays. Older runtimes have no `api.minor`, which reads as 0.
+- Hosts feature-detect by member presence (for example `typeof api.runners?.onDone === "function"`), which is more reliable than comparing `api.agent.version`.
+
+| Minor | First ama version | Added                                                                                              |
+| ----- | ----------------- | -------------------------------------------------------------------------------------------------- |
+| 0     | —                 | Every existing member (optional facets such as `cache?` and `runners?.provide` still need a check) |
+| 1     | Unreleased        | `minor`, `runners?.onDone` (see "Runner done event")                                               |
+
 ## HostApi
 
-| Member                                          | Description                                                                                                                                                                                          |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                       | `HOST_API_VERSION`                                                                                                                                                                                   |
-| `agent`                                         | `{ name: "ama", version }`                                                                                                                                                                           |
-| `env`                                           | A frozen copy of the environment variables at startup                                                                                                                                                |
-| `mode`                                          | `interactive` / `line` / `print` / `rpc`                                                                                                                                                             |
-| `session.id()` / `file()` / `cwd()` / `model()` | The current session (follows the new session after a switch); `file()` is `undefined` until the first request is written to disk                                                                     |
-| `tools.register(tool)`                          | Register a tool (shape below); the name must match `^[a-z][a-z0-9_]{1,63}$`, and an existing name throws `tool_exists`. A prefix is recommended (`canvas_*`)                                         |
-| `tools.disable(name)`                           | Hide a built-in tool (Armadra disables `task`, for example); the tools section of the system prompt stops listing it                                                                                 |
-| `tools.list()`                                  | All current tool names                                                                                                                                                                               |
-| `instructions.add(source)`                      | Append to the final `host` section of the system prompt; `{ kind: "file", path }` or `{ kind: "text", text, name? }`                                                                                 |
-| `events.on(name, handler)`                      | Observe events (table below); returns an unsubscribe function                                                                                                                                        |
-| `approvals.setBroker(broker)`                   | Set the approval answerer (see "Approvals")                                                                                                                                                          |
-| `messages.sendUser(text, origin?)`              | Inject a user message: when idle it starts a run (`"started"`), while running it is queued as a steer (`"queued"`); `origin` defaults to `"host"`, is persisted on the message and shown as `↳ host` |
-| `ui.notify(message, level?)`                    | Goes to the message area in interactive / line mode; becomes a `notification` event in rpc mode (with a copy on stderr); written to stderr in print mode                                             |
-| `ui.setStatus(key, text?)`                      | A host item in the status bar; an empty or missing `text` removes the key                                                                                                                            |
-| `log(level, message, detail?)`                  | Logging; `warn` / `error` go to stderr                                                                                                                                                               |
-| `cache?.onWarmingDecision(handler)`             | Veto hook for cache warming (see "Cache warming"); an optional facet missing in older runtimes, so check `api.cache !== undefined` before use                                                        |
+| Member                                          | Description                                                                                                                                                                                                                                       |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                       | `HOST_API_VERSION`                                                                                                                                                                                                                                |
+| `agent`                                         | `{ name: "ama", version }`                                                                                                                                                                                                                        |
+| `env`                                           | A frozen copy of the environment variables at startup                                                                                                                                                                                             |
+| `mode`                                          | `interactive` / `line` / `print` / `rpc`                                                                                                                                                                                                          |
+| `session.id()` / `file()` / `cwd()` / `model()` | The current session (follows the new session after a switch); `file()` is `undefined` until the first request is written to disk                                                                                                                  |
+| `tools.register(tool)`                          | Register a tool (shape below); the name must match `^[a-z][a-z0-9_]{1,63}$`, and an existing name throws `tool_exists`. A prefix is recommended (`canvas_*`)                                                                                      |
+| `tools.disable(name)`                           | Hide a built-in tool (Armadra disables `task`, for example); the tools section of the system prompt stops listing it                                                                                                                              |
+| `tools.list()`                                  | All current tool names                                                                                                                                                                                                                            |
+| `instructions.add(source)`                      | Append to the final `host` section of the system prompt; `{ kind: "file", path }` or `{ kind: "text", text, name? }`                                                                                                                              |
+| `events.on(name, handler)`                      | Observe events (table below); returns an unsubscribe function                                                                                                                                                                                     |
+| `approvals.setBroker(broker)`                   | Set the approval answerer (see "Approvals")                                                                                                                                                                                                       |
+| `messages.sendUser(text, origin?)`              | Inject a user message: when idle it starts a run (`"started"`), while running it is queued as a steer (`"queued"`); `origin` defaults to `"host"`, is persisted on the message and shown as `↳ host`                                              |
+| `ui.notify(message, level?)`                    | Goes to the message area in interactive / line mode; becomes a `notification` event in rpc mode (with a copy on stderr); written to stderr in print mode                                                                                          |
+| `ui.setStatus(key, text?)`                      | A host item in the status bar; an empty or missing `text` removes the key                                                                                                                                                                         |
+| `log(level, message, detail?)`                  | Logging; `warn` / `error` go to stderr                                                                                                                                                                                                            |
+| `cache?.onWarmingDecision(handler)`             | Veto hook for cache warming (see "Cache warming"); an optional facet missing in older runtimes, so check `api.cache !== undefined` before use                                                                                                     |
+| `runners?.provide(runner)`                      | Injects a sub-agent runner: `id` is the name in `task(agent=<id>)` and `description` goes into the task tool description; with a host, ama starts no external CLI of its own and only uses runners injected here; returns an unsubscribe function |
+| `runners?.onDone(handler)`                      | Called whenever a round of a host runner ends (see "Runner done event"); returns an unsubscribe function. Since host-api 1.1, so check `typeof api.runners?.onDone === "function"` before use                                                     |
+| `minor?`                                        | `HOST_API_MINOR` (see "Versioning"); missing in older runtimes                                                                                                                                                                                    |
 
 During `create()` the session is not assembled yet: `session.*` returns the values fixed at startup, and `sendUser` is rejected with `busy`. To send a message at startup, wait for the `session_start` event.
 
@@ -104,6 +118,8 @@ interface ToolResult {
 
 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>()`.
 
+The exported `ToolPermission` type gains `"network"` (used by the built-in `web_fetch`; judged as execute and asks in plan, see [permissions.md](../guides/permissions.md) "Network class"); tools registered by a host through `tools.register` still accept only `read` / `write` / `execute`, and `HOST_API_VERSION` is unchanged.
+
 ## Events
 
 `events.on` handlers only observe: a throw is just logged and does not affect the run; handlers are called and awaited in order, and `session_shutdown` is awaited (so you can clean up before exit).
@@ -157,6 +173,32 @@ interface WarmDecision {
 
 Return `"warm"` / `"stop"` (a Promise is fine). `"stop"` skips the request and stops this warming round (when the built-in decision was warm, the stop reason is recorded as `declined`); `"warm"` can override a built-in stop. If the handler fails, the built-in decision applies. With several handlers, the last one registered and not unsubscribed wins; the return value is an unsubscribe function. The warming mechanism itself is described in [providers.md](../guides/providers.md) "Caching".
 
+## Runner done event
+
+`api.runners.onDone(handler)` (host-api 1.1): every time a runner injected through `runners.provide` finishes a round, `handler` is called once with the payload below. A round is the first one after `start()`, or the next one after `send` / `interrupt`; it ends when ama's `wait()` for it settles (returns, throws, or the task is aborted).
+
+```ts
+interface RunnerDoneEvent {
+  runner: string; // host runner id (the name in task(agent=<id>))
+  taskId?: string; // ama task id (SubagentRunRequest.taskId); missing when the runner is called directly
+  sessionId: string; // the runner's own session id (RunnerHandle.id)
+  round: number; // round number, starting at 1
+  status: "completed" | "failed" | "aborted" | "max_turns" | "interrupted";
+  isError: boolean; // status is failed or aborted
+  text?: string; // result text returned by wait()
+  error?: string; // error message thrown by wait()
+  startedAt: number; // when the round began (start / send / interrupt), epoch milliseconds
+  endedAt: number; // when it settled
+  durationMs: number;
+}
+```
+
+- `status` follows the task registry: the task's `signal` aborted or `stop()` called → `aborted`; otherwise the terminal status the result reports (`max_turns`, `interrupted`, …); otherwise `failed` / `completed` by `isError`. A `wait()` that throws without an abort → `failed` with `error`.
+- Observe-only: handlers are not awaited; a throw (including a rejected Promise) is logged once at error level through `log` and affects neither the `wait()` result nor other handlers.
+- ama may call `wait()` several times in one round (the task entry and the registry each once); the event is sent once. Calling `wait()` again after the round settled, without a new `send` / `interrupt`, sends nothing. An `interrupt` while running is followed to the end by the current round instead of starting another.
+- Only host-injected runners are covered; ama's own sub-sessions (`general` / `explore` / `plan`) still report through `subagent_start` / `subagent_end`.
+- Use: the host no longer needs to poll whether the coordinator is still waiting on a task — the event says ama's side of it has ended.
+
 ## Exit
 
 - Process exit: `session_shutdown` event (awaited) → SessionEnd hook (`reason: "exit"`) → `adapter.dispose()` → session dispose. A throw from `dispose` is only logged as a warning.

package/docs/en/reference/rpc.md

@@ -124,13 +124,13 @@ After a session switch the server re-subscribes to events and sends `session_sta
 
 ### Tools, permissions, discovery
 
-| Command               | Parameters                                                             | `data`                                                                                                                                  |
-| --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_tools`           | —                                                                      | `{ tools: { name, description, parameters, permission, active }[] }` (every tool in the registry; `active` means the model sees it now) |
-| `set_active_tools`    | `names: string[]`                                                      | `{ names }` (active tool names after the change)                                                                                        |
-| `set_permission_mode` | `mode: plan \| allowlist \| default \| auto-edit \| auto \| full-auto` | `{ mode }` (unknown mode → `invalid_arguments`)                                                                                         |
-| `get_commands`        | —                                                                      | `{ commands: { name, description?, source: "builtin" \| "template" \| "skill" }[] }`; Skill names are written `skill:<name>`            |
-| `get_skills`          | —                                                                      | `{ skills: { name, description, location, … }[] }` (discovered Skills; `location` is the SKILL.md path)                                 |
+| Command               | Parameters                                                             | `data`                                                                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_tools`           | —                                                                      | `{ tools: { name, description, parameters, permission, active }[] }` (every tool in the registry; `active` means the model sees it now)                                                                                                                               |
+| `set_active_tools`    | `names: string[]`                                                      | `{ names }` (active tool names after the change)                                                                                                                                                                                                                      |
+| `set_permission_mode` | `mode: plan \| allowlist \| default \| auto-edit \| auto \| full-auto` | `{ mode }` (unknown mode → `invalid_arguments`)                                                                                                                                                                                                                       |
+| `get_commands`        | —                                                                      | `{ commands: { name, description?, source: "builtin" \| "template" \| "skill" }[] }`; Skill names are written `skill:<name>`; only built-in commands that are currently available are listed (no `memory` while memory is off, no `tasks` when task cannot be called) |
+| `get_skills`          | —                                                                      | `{ skills: { name, description, location, … }[] }` (discovered Skills; `location` is the SKILL.md path)                                                                                                                                                               |
 
 ### Plans and tasks (wave 5)
 

package/docs/guides/agents.md

@@ -208,6 +208,20 @@ RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定
 | `agents.<类型>.model`             | 某个类型的模型（如让 `explore` 用便宜模型）                                      |
 | `models.aliases.fast` / `.strong` | 定义文件里 `model: fast / strong` 的映射                                         |
 
+按角色选模型只要三行配置（`config.json`）：别名 `fast` 指向便宜模型，`explore` 类型用它，外部 Agent `claude` 用它自己的模型名（原样交给该 CLI）：
+
+```json
+{
+  "models": { "aliases": { "fast": "<provider>/<cheap-model>" } },
+  "agents": {
+    "explore": { "model": "fast" },
+    "claude": { "model": "sonnet" }
+  }
+}
+```
+
+内置类型不带缺省的便宜模型；不配置时按上面的顺序回落，最终继承父会话的模型。
+
 ### 限制
 
 - 子 Agent 不能再委派（深度 1）；协调多个 Agent 的场景交给宿主（如 Armadra 画布）。

package/docs/guides/hooks.md

@@ -54,6 +54,12 @@
 
 每个事件只接受上表的决策；`deny` 与 `block` 在两类事件间互换（`UserPromptSubmit` 返回 `deny` 视为 `block`，`PreToolUse` 返回 `block` 视为 `deny`），其它不接受的决策忽略并记 warning。
 
+**范围**：
+
+- `task` 子会话（`depth: 1`）以自己的 `sessionId` / `sessionFile` 跑 Hook：它内部的每次工具调用照常触发 PreToolUse / PostToolUse，将要结束时触发 `SubagentStop`（不是 `Stop`）；它**不触发** `SessionStart` / `SessionEnd`——子会话的开始与结束由父会话的 `PreToolUse(task)` 与子会话的 `SubagentStop` 表达。
+- 外部 Agent（`task(agent="claude")` 等）内部的工具调用在外部 CLI 自己的策略下运行，**不经 ama 的 Hook**；ama 这边只有父会话的 `PreToolUse(task)` / `PostToolUse(task)`，外部 Agent 也不触发 `SubagentStop`。
+- codemode 脚本里的每次内层调用逐个触发（见下文「输入」的 codemode 段）。
+
 任何事件的 stdout 都可以带 `"continue": false`：请求结束当前运行（reason 显示给用户）。`"suppressOutput": true` 被接受并合并，但当前界面本来就不显示 Hook 的 stdout，暂无可见效果。
 
 ## 输入（stdin）
@@ -146,14 +152,15 @@ Hook 在权限管线之前，是因为它是用户策略（可以改输入、可
 
 只对 `PreToolUse` / `PostToolUse` 生效，其它事件忽略 matcher。
 
-| 写法              | 匹配                                                                                                  |
-| ----------------- | ----------------------------------------------------------------------------------------------------- |
-| 缺省、`""`、`*`   | 全部工具                                                                                              |
-| `bash`            | 精确匹配工具名                                                                                        |
-| `write\|edit`     | 多选（括号外的 `\|` 分隔）                                                                            |
-| `canvas_*`        | glob：`*` 任意字符串、`?` 单个字符                                                                    |
-| `bash(git push*)` | 先匹配工具名，再对参数文本做 glob：bash 是 `command`，文件类工具是 `path`，其它工具是输入的 JSON 文本 |
-| `/regex/flags`    | 对工具名做正则                                                                                        |
+| 写法                            | 匹配                                                                                                                        |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| 缺省、`""`、`*`                 | 全部工具                                                                                                                    |
+| `bash`                          | 精确匹配工具名                                                                                                              |
+| `write\|edit`                   | 多选（括号外的 `\|` 分隔）                                                                                                  |
+| `canvas_*`                      | glob：`*` 任意字符串、`?` 单个字符                                                                                          |
+| `bash(git push*)`               | 先匹配工具名，再对参数文本做 glob：bash 是 `command`，文件类工具是 `path`，其它工具是输入的 JSON 文本                       |
+| `web_fetch(*docs.example.org*)` | `web_fetch` 的参数文本是整个 `url`（含协议与查询串，`*` 跨 `/`）；与权限规则 `web_fetch(<pattern>)` 的 `host/path` 语义不同 |
+| `/regex/flags`                  | 对工具名做正则                                                                                                              |
 
 ## 运行环境
 
@@ -171,6 +178,77 @@ Hook 在权限管线之前，是因为它是用户策略（可以改输入、可
 
 每条 Hook 结束后发 `hook_executed{event, command, exitCode, durationMs}`（RPC 事件与宿主事件都有），超时或被信号杀死时 `exitCode` 为 null。
 
+## 按能力接入
+
+各项能力都用上面的事件接入，没有专门的事件。下表是对应关系，再往下是一份把各行放在一起的 hooks.json。
+
+| 能力                  | 事件与 matcher                                                                                                               | 能做什么                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `web_fetch`           | `PreToolUse` / `PostToolUse`，matcher `web_fetch` 或 `web_fetch(*docs.example.org*)`（括号内对 `toolInput.url` 文本做 glob） | PreToolUse 拒绝、改为询问或用 `updatedInput` 改 URL；PostToolUse 用 `additionalContext` 给抓回的正文加备注，`decision: "block"` 整页拒收 |
+| 子 Agent 开始         | `PreToolUse`，matcher `task`；按类型筛用 `task(*"agent":"explore"*)`（括号内是输入的 JSON 文本）                             | 输入含 `agent`、`prompt`、`model`、`background`：可以 deny，也可以用 `updatedInput` 改 prompt 或换 agent                                 |
+| 子 Agent 结束         | `SubagentStop`（输入带 `lastAssistantText`）                                                                                 | `decision: "block"` + `reason`（或退出码 2）让子会话带着 reason 再跑一轮                                                                 |
+| 子 Agent 内部的调用   | 照常的 `PreToolUse` / `PostToolUse`，输入 `depth: 1`                                                                         | 与主会话相同；脚本按 `depth` 区分主会话与子会话                                                                                          |
+| 后台任务完成          | `SubagentStop`（后台的 ama 子会话结束时同样触发）                                                                            | 桌面通知、记日志；没有单独的「后台任务完成」通知种类                                                                                     |
+| 外部 Agent            | `PreToolUse` / `PostToolUse`，matcher `task(*"agent":"claude"*)`                                                             | 拦截或改写委派本身；外部 Agent 内部的调用不经 Hook（见「范围」）                                                                         |
+| codemode 编排子 Agent | 脚本里每个 `tools.task(...)` 都是一对 `PreToolUse(task)` / `PostToolUse(task)`，输入带 `viaCodemode` 与 `parentToolCallId`   | 与模型直接调用 `task` 相同；按 `parentToolCallId` 把同一个脚本发起的任务归到一起                                                         |
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "web_fetch",
+        "hooks": [{ "type": "command", "command": "./.ama/fetch-guard.sh" }]
+      },
+      {
+        "matcher": "task(*\"agent\":\"claude\"*)",
+        "hooks": [{ "type": "command", "command": "./.ama/log-delegation.sh" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "web_fetch(*docs.example.org*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"additionalContext\":\"docs.example.org 的页面对应最新版本，旧版本另查\"}'"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [{ "hooks": [{ "type": "command", "command": "./.ama/subagent-tests.sh" }] }]
+  }
+}
+```
+
+`web_fetch` 行随 `web_fetch` 工具一起提供（matcher 括号内取 `url` 的改动在同一批里）。它的 matcher 只认 URL 文本上的 `*` / `?` glob；权限规则 `web_fetch(<glob>)` 是另一套写法（对 `host/path` 匹配，裸域名含子域），见 [permissions.md](permissions.md)。只想放行少数站点时优先用权限规则或 `allowlist` 模式，Hook 适合需要脚本判断的情形。
+
+只允许抓取文档站（`.ama/fetch-guard.sh`，配在上面的 `PreToolUse` `web_fetch` 下）：
+
+```sh
+#!/bin/sh
+url=$(node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).toolInput.url))')
+case "$url" in
+  https://docs.example.org/*|https://registry.npmjs.org/*) exit 0 ;;
+esac
+echo "只允许抓取文档站：$url" >&2
+exit 2
+```
+
+子任务结束时跑测试，失败就让它接着修（`.ama/subagent-tests.sh`，配在 `SubagentStop` 下）：
+
+```sh
+#!/bin/sh
+input=$(cat)
+# 已经被本 Hook 续跑过一次：放行，避免循环
+case "$input" in *'"stopHookActive":true'*) exit 0 ;; esac
+out=$(npm test --silent 2>&1) && exit 0
+echo "Tests failed; fix them before reporting back:" >&2
+printf '%s\n' "$out" | tail -n 20 >&2
+exit 2
+```
+
 ## 示例
 
 阻止推送到 main：

package/docs/guides/permissions.md

@@ -34,7 +34,7 @@
 
 ### 审批对话框的来源标注
 
-审批不只来自主会话。对话框（以及 RPC `permission_request.context`）标出请求从哪来，选项都只有「允许 / 本会话允许同类 / 拒绝」：
+审批不只来自主会话。对话框（以及 RPC `permission_request.context`）标出请求从哪来，选项都只有「允许 / 本会话允许同类 / 拒绝」（`web_fetch` 的第二项是「本会话允许 `<主机>`」）：
 
 | 来源                                       | 标题前缀                                  | 正文                                          | 谁来判定                                                                   |
 | ------------------------------------------ | ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
@@ -68,6 +68,27 @@ plan 模式的第 ③ 步看输入（实现 `src/permissions/pipeline.ts` 的 `p
 
 比 auto 的安全名单窄：不含测试 / 构建运行器（`npm test`、`cargo build` 会执行项目脚本），也不含 `env` / `printenv`（会把环境变量里的密钥打进上下文）。读机密路径（`cat .env`）不算只读。
 
+## 网络类：web_fetch
+
+`web_fetch` 是唯一的联网工具（只读取一个 URL，不做搜索），权限类 `network`：
+
+| 模式                   | `web_fetch`                                                                                                                                                                                           |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default`、`auto-edit` | 询问；审批第二项是「本会话允许 `<主机>`」，之后同一主机（不分路径、端口与大小写）不再询问                                                                                                             |
+| `plan`                 | 询问（只读但能把数据带出去；调研常要看文档，所以不是拒绝）。只读子 Agent 里按拒绝                                                                                                                     |
+| `allowlist`            | 只放行 allow 规则命中的，其余拒绝                                                                                                                                                                     |
+| `auto`                 | 规则层：URL 不是公网 http(s)（本机名、私网 / 元数据 IP、`file:`、带账号密码）直接拒绝；allow 规则、Hook allow、会话记忆放行；其余交分类器（公开文档、包注册表页算常规，查询串像密钥或长随机串时询问） |
+| `full-auto`            | 放行                                                                                                                                                                                                  |
+
+无人值守（`-p`）时询问一律拒绝，用 `--allow 'web_fetch(<域名>)'` 放行。
+
+- **规则** `web_fetch(<pattern>)` 对 `host/path`（不含协议、端口与查询串，主机名小写）匹配：不含 `/` 的只比主机，裸域名 `example.com` 命中它自己与全部子域，`*.example.com` 只命中子域；含 `/` 的对整个 `host/path` 做 glob，`*` 不跨 `/`、`**` 跨（`docs.example.com/api/**`）。deny 规则在所有模式下先判定：`permission.deny: ["web_fetch(*.internal.example.com)"]`。
+- **执行层守卫**（所有模式都生效，`full-auto` 也一样）：只收 `http:` / `https:`，拒带账号密码的 URL；URL ≤ 2048 字符、查询串 ≤ 1024；主机名必须含 `.`（`localhost`、`*.localhost`、无点主机一律拒绝，本机服务请走 bash 审批）；解析出的**每一个**地址都不得落在环回、`0.0.0.0/8`、RFC 1918、`100.64/10`、链路本地（含云元数据 `169.254.169.254`、`100.100.100.200`、`fd00:ec2::254`）、保留与组播段、IPv6 ULA `fc00::/7`、`fe80::/10`、`fec0::/10`、`ff00::/8`，IPv4 映射 / NAT64 / 6to4 里嵌的 IPv4 按 IPv4 再判；连接钉在检查过的地址上，防解析后被换成内网（DNS 重绑定）。
+- **重定向**：同主机（同协议同端口，或 http → https 升级）自动跟，最多 5 跳，每跳重新检查；跨主机不跟，结果告诉模型目标 URL，再调用一次要重新过权限。
+- **限制**：总超时 30 s、首字节 15 s、响应体（解压后）≤ 5 MB；只发 GET，不带 cookie 与自定义头；输出缺省截到 50 000 字符（最多 200 000），截断时全文写到会话的 `outputs/<调用 id>.txt`，模型用 `offset` 续读。结果首行固定 `Content fetched from <URL> (untrusted):`，提醒模型这是外部内容。
+- **关闭**：`tools.disabled: ["web_fetch"]`（用户、profile、项目级都可以）、`tools.default: ["-web_fetch"]`、宿主 `tools.disable("web_fetch")`，或 `permission.deny: ["web_fetch"]`。没有新增配置键与环境变量。
+- `web_fetch` 在 ama 进程里运行，不受 bash 的 OS 沙箱与 `sandbox.network` 约束，也不走 `HTTPS_PROXY`（代理会自己解析主机名，钉不住地址）；见 [sandbox.md](sandbox.md)「已知绕过」。
+
 ## 判定顺序
 
 一次工具调用（模型直接发起或 codemode / task 里嵌套发起都一样）：
@@ -132,6 +153,7 @@ default / auto-edit 下，满足下面全部条件的 bash 调用免审批（`Pe
 | 机密路径      | 读或写 `.env`、`.env.*`（`.env.example` / `.sample` / `.template` / `.dist` 除外）、`.ssh/`、`.gnupg/`、`.aws/`、`.kube/config`、`.docker/config.json`、`.netrc`、`.pgpass`、私钥（`id_rsa` 等、`*.pem`、`*.key`、`*.p12`、`*.pfx`、`*.jks`）、ama 的 `auth.json`                       |
 | 受保护写入    | 写 `.git/` 内部、项目里的 `.ama/`（可能改 Hook 与配置）、项目目录外的任何路径（`/dev/null` 等除外）                                                                                                                                                                                     |
 | 网络命令      | `curl`、`wget`、`ssh`、`scp`、`rsync`、`nc`、`gh`；`git push / pull / fetch / clone`；`npm / pnpm / yarn / bun install / add / ci / update / publish / dlx`、`npx`；`pip install`、`cargo install / publish`、`go get / install`、`brew / apt install`、`docker pull / push / login` 等 |
+| 联网读取      | `web_fetch` 的 URL 不是公网 http(s)：直接**拒绝**（不询问，见[网络类](#网络类web_fetch)）                                                                                                                                                                                               |
 | 删除与回退    | `rm -r` / `rm -f`、`find -delete`、`git clean`、`git checkout -- …` / `git restore`、`git stash drop / clear`、`shred`、`truncate`                                                                                                                                                      |
 | bash 里的路径 | 重定向目标（`>`、`>>`、`&>`、`tee`）、`cp` / `mv` / `mkdir` / `touch` / `ln` / `chmod` 的目标在项目外或受保护；命令参数里出现机密路径（`cat .env`）                                                                                                                                     |