@armadra/agent 0.5.1 → 0.6.1

package/docs/en/host-api.md

@@ -0,0 +1,167 @@
+# Host adapter API (@armadra/agent/host)
+
+English · [简体中文](../host-api.md)
+
+> Translated from the Chinese [docs/host-api.md](../host-api.md) as of commit `0065cf4`. 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.md) §6.2, §6.3 and §11.1 step 13 (Chinese).
+
+## Module shape
+
+```js
+// my-host.mjs
+export const hostApi = 1;
+export function create(api) {
+  if (!api.env.MY_HOST_ENABLED) return undefined; // not activated: ama falls back to plain standalone mode
+  api.tools.register({
+    name: "my_lookup",
+    description: "Look up a ticket by id.",
+    parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    permission: "read",
+    async execute(input) {
+      return { content: `ticket ${input.id}: …` };
+    },
+  });
+  api.instructions.add({
+    kind: "text",
+    name: "my-host",
+    text: "Tickets live in the tracker; use my_lookup.",
+  });
+  api.events.on("agent_settled", () => api.ui.setStatus("my-host", "idle"));
+  return { id: "my-host", dispose() {} };
+}
+```
+
+- Export `hostApi` (must equal `HOST_API_VERSION`) and `create(api)`; they may also sit on the default export (ESM `export default { hostApi, create }` or CJS `module.exports = { hostApi, create }`).
+- `create` activates the adapter by returning a `HostAdapter` (`{ id: string, dispose?() }` with a non-empty `id`); returning `undefined` means "not activated this time". It may be async.
+- `dispose()` is called on exit (after the `session_shutdown` event) and is idempotent.
+
+## Loading
+
+- Source: `--host <module>` or the profile's `host` (the command line wins); relative paths resolve against cwd.
+- `.mjs` uses dynamic `import()`; `.cjs` uses `require`; `.js` tries `require` first and falls back to `import()` on ESM errors (`ERR_REQUIRE_ESM` etc.). The single-file build `ama.cjs` can load ESM adapters too.
+- Timing: step 13 of the startup sequence, after config, resources, the model and the tool registry are ready and before the session is assembled. Tools and instructions registered in `create()` enter the system prompt and tool table of the first request, so the prefix is stable from the first request on.
+- Failures:
+
+| Case                                                       | Exit code |
+| ---------------------------------------------------------- | --------- |
+| File missing, loading throws, `hostApi` / `create` missing | 6         |
+| `hostApi` differs from `HOST_API_VERSION`                  | 78        |
+| `create()` throws or does not return within 10 seconds     | 6         |
+| The returned adapter has no `id`                           | 6         |
+
+## 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                                                        |
+
+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.
+
+### Tool definition
+
+```ts
+interface ToolDefinition<I = unknown> {
+  name: string;
+  label?: string; // TUI title
+  description: string;
+  parameters: JsonSchema;
+  permission: "read" | "write" | "execute"; // class used by the permission pipeline
+  executionMode?: "sequential" | "parallel"; // default: read runs in parallel, the rest sequentially
+  annotations?: { readOnly?: boolean; destructive?: boolean; openWorld?: boolean };
+  promptSnippet?: string; // one line in the system prompt's tools section
+  promptGuidelines?: string[]; // system prompt rules section
+  execute(input: I, ctx: ToolContext): Promise<ToolResult>;
+  renderCall?(input: I, width: number): string[];
+  renderResult?(result: ToolResult, width: number, expanded: boolean): string[];
+}
+interface ToolResult {
+  content: string | ContentBlock[];
+  isError?: boolean;
+  details?: unknown; // persisted, never enters the context
+  structured?: unknown; // return value of tools.<name>() in codemode scripts
+  terminate?: boolean; // the run ends early only when every result in the batch sets it
+}
+```
+
+`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`.
+
+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>()`.
+
+## 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).
+
+| Event                                                             | Payload                                                                                          | Source                                                                                                                                   |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `session_start`                                                   | `sessionId`, `sessionFile?`, `cwd`, `reason: startup \| resume \| new \| fork`                   | Startup and session switches                                                                                                             |
+| `before_agent_start`                                              | `prompt`                                                                                         | After the user prompt is expanded, before the run starts                                                                                 |
+| `agent_start` / `turn_start` / `turn_end` / `agent_before_settle` | `{}`                                                                                             | Runs and turns                                                                                                                           |
+| `agent_end`                                                       | `stopReason`, `willRetry`                                                                        |                                                                                                                                          |
+| `agent_settled`                                                   | `warning?`                                                                                       | The run has fully ended                                                                                                                  |
+| `tool_call`                                                       | `toolCallId`, `toolName`, `input`                                                                | A tool starts executing (permission already granted)                                                                                     |
+| `tool_result`                                                     | `toolCallId`, `toolName`, `isError`                                                              | A tool finished executing                                                                                                                |
+| `tool_approval_requested`                                         | `requestId`, `toolName`                                                                          | Approval needed                                                                                                                          |
+| `tool_approval_resolved`                                          | `requestId`, `decision`                                                                          | Approval decided                                                                                                                         |
+| `session_compact`                                                 | `tokensBefore`                                                                                   | Compaction succeeded                                                                                                                     |
+| `model_select`                                                    | `model: { provider, id }`                                                                        | Model switched                                                                                                                           |
+| `hook_executed`                                                   | `event`, `command`, `exitCode`, `durationMs`                                                     | Each command hook finished                                                                                                               |
+| `cache_miss`                                                      | `missedTokens`, `missedCost?`, `reason`, `detail?`, `idleMs`                                     | A cache miss (including those below the interface threshold)                                                                             |
+| `context_pressure`                                                | `percent`, `threshold: 70 \| 90`, `remainingTokens?`, `estimatedTurnsLeft?`                      | Context usage crossed 70% / 90%                                                                                                          |
+| `quota_update`                                                    | `provider`, `planType?`, `primary?`, `secondary?` (`{ usedPercent, resetsAt?, windowMinutes? }`) | ChatGPT subscription quota updated ([W6-O]; an exhausted quota has its own error code `quota_exceeded`, an expired login `auth_expired`) |
+| `session_shutdown`                                                | `{}`                                                                                             | Before exit (followed by the SessionEnd hook and `dispose`)                                                                              |
+
+For token-level streaming content or the full event stream, use RPC or the SDK's `subscribe`; host events are a trimmed set.
+
+## Approvals
+
+`approvals.setBroker({ ask(request, signal) })`: when a tool call needs confirmation, the approval chain asks **the host broker → the UI (TUI dialog / RPC client / SDK callback) → deny when nobody answers**, in that order.
+
+- `ask` answers by returning `"allow"` / `"deny"` / `"allow_session"`; returning `undefined` passes to the next answerer; a throw counts as deny.
+- `request`: `requestId`, `toolName`, `input`, `reason: "mode" | "dangerous" | "hook"`, `hookReason?`, `preview?` (the pre-execution preview, see [rpc.md](rpc.md) "Approvals"), `context?` (`depth > 0` means it comes from a `task` sub-agent; codemode inner calls carry `parentToolCallId`).
+- On timeout (10 minutes by default, `AMA_APPROVAL_TIMEOUT_MS`) or when the run is interrupted, `signal` aborts and the decision is deny. Approvals are serial: only one request waits at a time.
+- Timing: the broker is looked up at each approval, so it can be set in `create()` or set / replaced at any later time; the last `setBroker` wins.
+- The host broker only decides "who answers an ask"; it cannot loosen deny rules, command hook denies or dangerous-command detection ([design.md](../design.md) §6.3, Chinese).
+
+## Cache warming
+
+`api.cache.onWarmingDecision(handler)` calls `handler(decision)` with the built-in decision before every cache warming request:
+
+```ts
+interface WarmDecision {
+  action: "warm" | "stop"; // built-in decision
+  phase: "streaming" | "idle";
+  promptTokens: number; // input + cacheRead + cacheWrite of the last real request
+  warmCost: number | undefined; // cost of one warming request (USD)
+  missCost: number | undefined; // extra cost if the cache expires without warming
+  probability: number; // probability that another request follows after expiry: streaming 1, idle 0.15
+  reason?: string; // reason for stop
+}
+```
+
+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](providers.md) "Caching".
+
+## 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.
+- `/new`, `/resume`, `/fork` and RPC session switches: the adapter stays active and no `session_shutdown` is sent; the order is SessionEnd hook (`new` / `switch`) → old session dispose → `session_start` of the new session → SessionStart hook. `api.session.*` then points to the new session.
+
+## Embedding in Armadra
+
+Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host` points to its adapter (`ama-armadra.cjs`) and also carries instructions, skillDirs, hooksFile, authFile, sessionDir and `trustProject`. The adapter returns `undefined` when `ARMADRA_NODE_ID` is missing, so the same profile behaves as plain ama outside the canvas. Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.

package/docs/en/permissions.md

@@ -0,0 +1,214 @@
+# Permission modes and auto decisions
+
+English · [简体中文](../permissions.md)
+
+> Translated from the Chinese [docs/permissions.md](../permissions.md) as of commit `ee89edb`. When the two differ, the
+> Chinese version is authoritative.
+
+This document covers ama's six permission modes, the decision order for every tool call, and how the three tiers of `auto` mode, "rule tier → static judgement → model classifier", decide between allowing and asking. The overall design is in [design.md](../design.md) §6.3 and §7 (Chinese); hook input and output are in [hooks.md](../hooks.md) (Chinese).
+
+## Modes
+
+| Value       | Display name       | Read | Write (inside the project)                      | Execute (bash etc.)                                         | When to use                                                                   |
+| ----------- | ------------------ | ---- | ----------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `default`   | Manual             | ✓    | ask                                             | ask                                                         | Default                                                                       |
+| `auto-edit` | Accept edits       | ✓    | ✓                                               | ask                                                         | You trust it to edit code but want to see each command                        |
+| `plan`      | Plan               | ✓    | deny                                            | read-only commands allowed, everything else denied          | Read-only research, then a plan for approval ([plan.md](../plan.md), Chinese) |
+| `auto`      | Auto               | ✓    | ✓ (protected paths and outside the project ask) | safe-list commands allowed, the rest judged by a classifier | Recommended: routine work is not interrupted, only risky steps ask            |
+| `full-auto` | Bypass permissions | ✓    | ✓                                               | ✓                                                           | Throwaway sandboxes, containers                                               |
+| `allowlist` | Allowlist only     | ✓    | only calls matching allow rules                 | read-only commands and calls matching allow rules           | CI: never asks; anything not listed is denied                                 |
+
+In every mode, deny rules and hook denies are checked first and deny outright; the dangerous-command list (`rm -rf /`, `git push --force`, `curl … | sh` and so on, see the README "Safety" section) always asks, which becomes deny under `allowlist` and when unattended.
+
+How to set it: `--permission-mode <value>`, config `permission.mode`, `/permission` (picker) or `Shift+Tab` in the interactive UI, RPC `set_permission_mode`, SDK `permission.mode`.
+
+### Strictness and project config
+
+From strictest to loosest: `plan < allowlist < default < auto-edit < auto < full-auto`. The project-level `.ama/config.json` can only move the mode towards stricter; in addition it **cannot set `auto` or `full-auto`** (these let ama decide by itself, or allow without any judgement, so they must be turned on by user config, the command line or a profile). Setting them there is ignored with a warning.
+
+`allowlist` sits between `plan` and `default`: the calls it allows are those `plan` allows (read-only tools, [read-only commands](#plan-mode-and-read-only-commands), `task`) plus those listed explicitly by allow rules; the set `default` allows contains it (read-only + allow rules), and everything else asks under `default` and is denied under `allowlist`. So `plan ⊆ allowlist ⊆ default`. Read tools are allowed under `allowlist` as in every other mode; to restrict even reads, use deny rules.
+
+Read-only commands are a static list (next section) shared by `plan` and `allowlist`, so the total order of strictness holds; allowing commands such as `ls` and `git log` under `allowlist` in CI is harmless. `task` is allowed in both modes: sub-sessions share the same permission pipeline, so a sub-agent can never do more than the parent session. With `plan.bash: "ask"`, plan asks for commands outside the list (`allowlist` never asks), and the set of "allowed without asking" still satisfies the inclusions above.
+
+### Interface
+
+- The status bar shows the display name: `mode:Auto`; `Bypass permissions` is yellow.
+- `/permission` without arguments opens a picker: titled `Mode`, each item "display name + one line of explanation", number shortcuts 1–6 on the right, a check on the current mode, `Default` on the default mode from config and `Recommended` on Auto. In line mode `/permission` prints the same list.
+- `Shift+Tab` cycles: Manual → Accept edits → Plan → Auto → Bypass permissions → Manual. `Allowlist only` is not in the cycle and must be chosen explicitly.
+- **Entering Bypass**: switching to Bypass in the interactive UI (Tab / Shift+Tab cycling, the `/permission` picker, `/permission full-auto`) first shows a confirmation dialog with "Cancel" selected by default; cancelling while cycling skips Bypass and returns to Manual, cancelling from the picker or command keeps the previous mode. Once confirmed in a run, it is not asked again. `--permission-mode full-auto` on the command line, user config and profiles do not prompt (those are explicit choices); line mode asks a `[y/N]` question; piped input, RPC `set_permission_mode` and ACP `session/set_mode` are the caller's responsibility and do not prompt. Details in [tui.md](tui.md) "Entering Bypass".
+
+### 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":
+
+| Origin                                                          | Title prefix                                         | Body                                                                          | Who decides                                                                                                 |
+| --------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Tool calls of a `task` sub-agent                                | `[task:explore]` (`[task]` when the type is unknown) | Same as the main session                                                      | The same permission pipeline; read-only types (`explore` / `plan`) are judged as plan and never prompt      |
+| Permission requests from external agents (claude / codex / ACP) | `[claude · session abc12345]`                        | The title, kind, paths involved and input summary given by the external agent | A human only: host → interface → deny when unattended; neither the auto classifier nor the model takes part |
+| First run of an external agent in this session                  | Title "first run of an external agent"               | An explanation (runs with your login in that CLI) and the mode                | allow / deny rules `task(<id>)` and `full-auto` let it through; otherwise a human decides (no classifier)   |
+
+"Allow for this session" of an external agent is remembered by that agent itself. In Manual mode the approval of a `task(agent=…)` call and the first-run confirmation are merged into one (see [agents.md](../agents.md), Chinese). The RPC `context` is `{ depth, taskId, origin }` ([rpc.md](rpc.md) "Approvals").
+
+## Plan mode and read-only commands
+
+Step ③ of plan mode looks at the input (implemented by `planDecision` in `src/permissions/pipeline.ts`); the flow and plan approval are in [plan.md](../plan.md) (Chinese):
+
+| Call                                  | Under plan                                                                                                                                               |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| read / grep / glob / ls               | Allowed                                                                                                                                                  |
+| `todo`                                | `get` allowed; `set` / `update` denied, with a hint to put the steps into `<proposed_plan>` (the list is generated from the plan on approval)            |
+| bash                                  | Per `plan.bash`: `readonly` (default) allows read-only commands and denies the rest; `ask` asks for the rest (denied when unattended); `deny` denies all |
+| write / edit etc.                     | Denied with guidance: `Plan mode is active: write/execute tools are disabled. Finish the plan with a <proposed_plan> block.`                             |
+| task                                  | Allowed (sub-sessions share the same pipeline and are in plan too; sub-sessions do not extract plan blocks)                                              |
+| deny rules, dangerous commands, hooks | Decided before the mode (unchanged)                                                                                                                      |
+
+Read-only commands (`src/permissions/readonly-bash.ts`): first they pass auto's static judgement (tokenizing, nested expansion, network / deletion / write targets / secret paths, command substitution, variable expansion, dotfile globs); then every segment must be on the list below, with no output redirection (except `/dev/null`), no nested shell (`sh -c`, `eval`, `xargs`, `find -exec`) or process substitution, and no environment assignment or wrapper command at the start of a segment (`GIT_EXTERNAL_DIFF=… git diff`, `env …`).
+
+| Command                                                                                     | Restrictions                                                                                                                                   |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ls cat head tail wc stat echo printf pwd which du basename dirname realpath true false cd` | —                                                                                                                                              |
+| `grep egrep fgrep`, `rg`, `fd`, `find`                                                      | `rg --pre`, `fd -x / -X / --exec*`, `find -exec / -ok / -delete / -fprint*` do not count                                                       |
+| `tree`, `file`, `jq`                                                                        | `tree -o`, `file -C`, `jq -i` do not count                                                                                                     |
+| `git status / log / show / diff / rev-parse / blame / ls-files / branch`                    | Only the git global options `-C` and `--no-pager` are allowed; `--output`, `--ext-diff`, `--textconv` and branch-changing options do not count |
+
+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.
+
+## Decision order
+
+One tool call (issued directly by the model or nested inside codemode / task, alike):
+
+```text
+schema validation
+→ command hook PreToolUse (deny vetoes; allow / ask go to the pipeline)
+→ permission pipeline:
+   ① rule tier (no model call)
+      deny rules (including built-in deny), hook deny                     → deny
+      dangerous-command list                                              → ask
+      [auto] protected paths, writes outside the project, network, deletion → ask
+      hook ask                                                            → ask
+      allow rules, hook allow, session memory                             → allow
+   ② mode
+      plan: read-only tools, read-only commands and task allowed, everything else denied (with plan.bash: ask, other commands ask)
+      default / auto-edit / full-auto: the usual mode truth table
+        [default / auto-edit] bash the mode would ask for: besides allow rules / hook allow / session memory,
+        approval-free inside the sandbox (see below) → allow; a hook ask still turns the result back into ask
+      allowlist: read-only tools, read-only commands and task allowed, everything else denied (Not in the allowlist)
+      auto: [with the sandbox active] a sandbox:false request to leave the sandbox → ask (after allow rules / hook allow / session memory)
+            static judgement (no model call) → allow; undecided → ③
+   ③ [auto] model classifier (sandboxed bash gets an os_sandbox input): allow → allow; ask / error / timeout → ask
+→ when asking, the approval chain runs (host broker → interface → deny when unattended)
+```
+
+- Later steps cannot loosen earlier results: allow rules cannot override dangerous commands or auto's rule tier, and the classifier only handles calls neither ① nor ② decided.
+- `allowlist` never asks: anything that would ask (dangerous commands, hook ask) is denied, with the denial text `Not in the allowlist` (text returned to the model is always English).
+- When unattended (`-p`, RPC without approvals), asking always means deny; in auto mode the classifier still runs first, and calls it judges allow are executed.
+
+### Approval-free commands inside the sandbox
+
+With `sandbox.bash: auto` and an OS sandbox on the machine that can restrict writes ([sandbox.md](../sandbox.md) "phase two", Chinese), bash runs through the sandbox. Under default / auto-edit, a bash call needs no approval (`PermissionVerdict.sandboxed: true`) when all of the following hold:
+
+1. It will run inside the sandbox: no `sandbox: false`;
+2. `sandbox.network: deny` (network access can exfiltrate data, so `allow` asks as usual);
+3. The command text (including nested commands in `sh -c`, `eval`, `xargs`, `find -exec`) touches no secret paths (`cat .env`, `~/.ssh/…`) and is not nested too deeply;
+4. It was not denied earlier by deny rules or a hook deny, is not on the dangerous-command list (`rm -rf` on paths outside the workspace, `git push --force`, `git reset --hard` etc. ask as usual), and no hook ask follows.
+
+| Mode               | bash inside the sandbox                                                                  | `sandbox: false` (leaving the sandbox)                                    |
+| ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| default, auto-edit | Allowed when the conditions above hold, otherwise ask                                    | Ask (allow rules, hook allow and session memory can allow)                |
+| auto               | Rule tier and static judgement as usual; the classifier gets an extra `os_sandbox` input | The rule tier asks (allow rules, hook allow and session memory can allow) |
+| plan, allowlist    | Unchanged                                                                                | Unchanged                                                                 |
+| full-auto          | Allowed                                                                                  | Allowed                                                                   |
+
+When unattended "ask" always means deny, so calls leaving the sandbox are denied in `-p`. auto does not allow sandboxed commands outright: its rule tier (network, deletion, protected paths, writes outside the project) is a deliberately finer line of defense than default's, and the classifier remains the last gate; the cost is that some commands default + sandbox would allow (`rm -r dist` in the workspace) still ask under auto.
+
+## The three tiers of auto
+
+### ① Rule tier
+
+No model call; a match asks (denied when unattended):
+
+| Category              | Contents                                                                                                                                                                                                                                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dangerous commands    | The whole list in `dangerous.ts` (shared by all modes)                                                                                                                                                                                                                                         |
+| 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 |
+| 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`)                                                                                                 |
+
+"The project directory" is the session cwd. File tools are judged by their `path` argument; bash is judged segment by segment with the same tokenizing and nested expansion as `dangerous.ts` (`sh -c`, `eval`, `xargs`, `find -exec`).
+
+### ② Static judgement
+
+No model call; allowed when satisfied:
+
+- Read-only tools (read, ls, grep, glob etc., `permission: "read"`).
+- write / edit with a target inside the project directory and not on a protected path (protected ones already asked in ①).
+- bash: every segment of the command (split at `&&`, `||`, `;`, `|`) is on the **safe list**, and
+  - there is no command substitution `$(…)`, backtick or `<(…)`;
+  - arguments contain no variable expansion `$X` and no globs that may match dotfiles (`.e*`);
+  - there is no nesting such as `sh -c` (shells, `eval` and `xargs` are not on the list).
+    Piping into safe commands (`cat a | grep b | wc -l`) is fine; piping into a shell is not on the list. Redirecting into the project is allowed; writing outside the project already asked in ①.
+- A matching allow rule (already allowed at the end of ①).
+
+The safe list (`src/permissions/auto-safe.ts`, each entry with positive and negative tests):
+
+| Command                                                                                                                                                                                                                                                                                                                                                             | Restrictions                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `ls`, `cat`, `head`, `tail`, `wc`, `grep`, `egrep`, `fgrep`, `rg`, `pwd`, `echo`, `printf`, `which`, `env` and `printenv` (printing only), `true`, `false`, `sort`, `cut`, `tr`, `diff`, `basename`, `dirname`, `realpath`, `stat`, `file`, `du`, `df`, `date`, `whoami`, `uname`, `cd` / `pushd` / `popd` (later relative paths resolve against the new directory) | `env FOO=1 cmd` is judged as `cmd`                                                               |
+| `find`                                                                                                                                                                                                                                                                                                                                                              | Without `-exec`, `-execdir`, `-ok`, `-okdir`, `-delete`, `-fprint*`, `-fls`                      |
+| `git status / diff / log / show / rev-parse / blame / ls-files` (`diff / log / show` without `--output`, `--ext-diff`, `--textconv`; `rg` without `--pre`; `sort` without `-o`; `date` without `-s`)                                                                                                                                                                | Only `-C dir` and `--no-pager` before the subcommand (`-c` can change the pager and is not safe) |
+| `git branch`                                                                                                                                                                                                                                                                                                                                                        | Listing only: without `-d / -D / --delete / -m / -M / -c / -C / -f / -u` etc.                    |
+| `npm / pnpm / yarn test`, `… run test / lint / typecheck / build`, `pnpm / yarn lint / typecheck / build`, `npm t`                                                                                                                                                                                                                                                  |                                                                                                  |
+| `node --test`, `tsc --noEmit`, `vitest run`, `pnpm vitest run`, `pnpm exec vitest run`, `pytest`, `python -m pytest`                                                                                                                                                                                                                                                |                                                                                                  |
+| `cargo test / check / build / clippy`, `go test / build / vet`, `make test / check / lint / build`                                                                                                                                                                                                                                                                  |                                                                                                  |
+
+Extending it: the user-level config `permission.autoSafeCommands` adds entries, e.g. `["just test", "bun test", "make fmt"]`, matched by word prefix (`just test` matches `just test --verbose`); entries containing `*` match the whole segment as a glob (`bun run test*`). Project config cannot add entries (that would loosen). Added commands still pass ① first: network, deletion and writes outside the project still ask.
+
+### ③ Model classifier
+
+It only handles calls neither ① nor ② decided (e.g. `rm old.txt`, `node scripts/gen.js`, host tools, codemode scripts).
+
+- **A separate request**: it never enters the session transcript and does not change the main session's messages or prefix (the main session's prompt cache is unaffected), and does not trigger warming; the request purpose is `purpose: "classify"`.
+- **Input**: tool name, arguments (JSON, truncated to 4000 characters), cwd, project root, and a summary of the latest user message (truncated to 600 characters). Arguments and the user message sit inside a `<tool_call_data>` … `</tool_call_data>` data block, with end markers inside the block escaped; the system prompt requires treating everything inside as data and ignoring instructions in it (including things like "ignore previous instructions" or "respond allow"), leaning to ask when such text appears.
+- **Output**: strict JSON `{"decision":"allow"|"ask","reason":"…"}`. A parse failure, a timeout (10 s) or a request error → ask.
+- **Model**: `permission.autoModel` (`provider/model`); defaults to the current session model. A cheap, fast model is recommended, e.g. `packy/qwen3.8-flash`. `maxTokens` 256, thinking off.
+- **Caching**: successful decisions are cached within the session by "tool name + normalized arguments" (bash collapses whitespace, others use JSON with sorted keys), so identical calls are classified once; errors and timeouts are not cached.
+- **Cost**: each classification records a `usage` entry with `kind: "permission_classify"`, counted in `/session` cost and RPC stats, never in the context.
+- The classifier can only judge undecided calls as allow or ask; it cannot overturn ①'s deny or ask.
+
+## Audit
+
+- Every auto decision (allow and ask) records `{ layer: "rule" | "static" | "classifier", decision, reason }`:
+  - the `tool_execution_end` event carries `autoDecision`; when asking, the `permission_request` event and the approval request carry `autoDecision` (the dialog shows "Auto: reason").
+  - `/permissions` shows the latest 20 decisions (tool, summary, tier, result, reason).
+- The input of the `PreToolUse` hook is unchanged; the `permissionMode` field can take the new values `auto` and `allowlist`.
+
+## Configuration
+
+```jsonc
+{
+  "permission": {
+    "mode": "auto",
+    "autoModel": "packy/qwen3.8-flash",
+    "autoSafeCommands": ["just test", "make fmt"],
+    "allow": ["bash(npm run e2e)"],
+    "deny": ["bash(terraform *)"],
+  },
+}
+```
+
+allowlist in CI:
+
+```sh
+ama -p "fix lint and run the tests" --permission-mode allowlist \
+  --allow 'write(src/**)' --allow 'edit(src/**)' --allow 'bash(pnpm lint*)' --allow 'bash(pnpm test*)'
+```
+
+## Known limitations
+
+- Static judgement looks at the command text, not at what the command really reads: `grep -r token .` reads the project's `.env` and is allowed by the safe list. For stricter behavior, add deny rules for `.env` (`read(**/.env*)`, `bash(*.env*)`).
+- "The project directory" is the cwd and does not follow symbolic links; when started in a subdirectory, parent directories count as outside the project.
+- Commands like `npm test` / `make test` run the project's own scripts; the safe list allows them as "running tests and builds inside the project". For untrusted repositories use `default` or `plan`.
+- Commands prefixed with `sudo` / `doas` are never safe, even when followed by a safe command (`sudo` itself is on the dangerous-command list and asks).
+- The classifier is a model's judgement, not a security boundary. The rule tier before it makes no model calls and can be reviewed; write deny rules for operations that are truly unacceptable.