@semalt-ai/code 1.19.0 → 1.20.1

package/CLAUDE.md

@@ -1,100 +1,23 @@
 # semalt-code — CLI Agent
 
-Node.js CLI tool that lets AI agents interact with code via an iterative tool-use loop. **Minimal, vetted, pinned** runtime dependencies — historically zero; as of v1.9.0 the MCP SDK, and as of Task W.1 a small web-extraction set (`@mozilla/readability`, `linkedom`, `turndown`). See **Dependency & Supply-Chain Policy** below. Everything else uses Node.js built-ins.
+Node.js CLI tool that lets AI agents interact with code via an iterative tool-use
+loop (stream → extract tool calls → execute → repeat). **Minimal, vetted, pinned**
+runtime dependencies — everything else uses Node.js built-ins. Published as
+`@semalt-ai/code`; invokable as `semalt-code` or `semalt`. Also consumable as a
+library via the `createAgent` facade (`lib/sdk.js`).
 
-Published as `@semalt-ai/code`. Invokable as `semalt-code` or `semalt`.
+> **This file is auto-loaded as project memory — keep it lean.** Deep detail lives
+> in `docs/` (not auto-loaded):
+> - **`docs/ARCHITECTURE.md`** — per-subsystem internals (MCP, checkpoints, sandbox,
+>   web-fetch pipeline, SDK, subagents, hooks, git tools, …).
+> - **`docs/HISTORY.md`** — dependency-policy rationale, the long-form invariant
+>   reference, and the "Deferred / Not Yet Implemented" roadmap.
+> - **`docs/CONFIG.md`** — full per-key config reference + CLI flags/commands +
+>   slash commands + tool tags/operations + dashboard API endpoints.
 
----
-
-## Directory Layout
-
-```
-semalt-code/
-├── index.js           # Entry point: arg parsing, module wiring, command dispatch
-├── lib/
-│   ├── sdk.js         # Embedding SDK: createAgent() STABLE facade — assembles the loop/registries/permissions/sandbox per-instance (Task 5.2)
-│   ├── internals.js   # UNSTABLE building-blocks barrel exposed at the @semalt-ai/code/internals subpath (no semver guarantee) (Task 5.2)
-│   ├── api.js         # HTTP client for dashboard auth + OpenAI-compatible inference
-│   ├── agent.js       # Agent loop: stream → extract tools → execute → repeat
-│   ├── commands/      # CLI command handlers, split into cohesive modules
-│   │   ├── index.js        # createCommands: shared helpers + wires the groups below
-│   │   ├── registry.js     # Slash-command registry: single source for dispatch, /help, completion (+ custom-command registration)
-│   │   ├── custom.js       # Markdown custom-command loader: discovery, frontmatter, $ARGUMENTS/$1 rendering (Task 3.1)
-│   │   ├── history-utils.js# Pure saved-chat message helpers (clean orphaned tool msgs, …)
-│   │   ├── auth.js         # login / whoami / logout / auth set-key
-│   │   ├── mcp.js          # MCP server management: status/list formatters + add/remove config mutators + add-arg parser (Task 3.3)
-│   │   ├── oneshot.js      # code / edit / shell / models / init (non-interactive)
-│   │   ├── tasks.js        # Background tasks: run --background launcher + tasks list/status/result/kill/prune (Task 5.3)
-│   │   ├── chat.js         # cmdChat: builds the session ctx, wires the chat modules
-│   │   ├── chat-session.js # chat state: local + dashboard history sync, in-chat picker
-│   │   ├── chat-slash.js   # in-chat slash-command handlers
-│   │   └── chat-turn.js    # input/turn handler: picker nav, dispatch, agent run + TUI callbacks
-│   ├── tools.js       # File and shell operation implementations
-│   ├── tool_registry.js # Single per-tool registration: XML parseAttrs + native fromParams + execute + permission
-│   ├── tool_specs.js  # TOOL_SPECS: OpenAI-format parameter source of truth for every 'tool'-type tag
-│   ├── proc.js        # Platform-aware subprocess spawn + tree-kill helpers (shell-wrapper PID handling; +detached spawn / kill-by-PID / isProcessAlive for Task 5.3)
-│   ├── debug.js       # Two mutually-exclusive debug modes (--debug inline / --debug-file) wired once at startup
-│   ├── prompts.js     # System prompt for the LLM (tells it to use exec/read/write tags)
-│   ├── ui.js          # Barrel: re-exports the public surface of lib/ui/
-│   ├── ui/
-│   │   ├── ansi.js        # ANSI escape constants, THEME, color codes, SPINNER_DEFS
-│   │   ├── theme.js       # Shared chrome palette for non-content surfaces (status lines, debug blocks, meta)
-│   │   ├── utils.js       # getCols, getRows, stripAnsi, boxLine, insertCharAt, approxTokens, …
-│   │   ├── format.js      # Pure, side-effect-free formatters for tool-line chrome (inputs → string)
-│   │   ├── writer.js      # Single owner of process.stdout for the TUI (scrollback, modal band, status region)
-│   │   ├── messages.js    # Thin writer.scrollback wrappers for error categories + neutral system-line glyphs
-│   │   ├── diff.js        # renderDiff (LCS diff), renderMarkdown, _mdInline
-│   │   ├── stream.js      # StreamRenderer — live token-by-token terminal output
-│   │   ├── select.js      # interactiveSelect — modal-region select menu (redraws in place, never scrollback)
-│   │   ├── layout.js      # LayoutManager — terminal geometry, resize events
-│   │   ├── chat-history.js# ChatHistory — bubble rendering, scroll, streaming slots
-│   │   ├── web-activity.js# Collapses consecutive web ops (web_search→http_get) into one process-summary line; --debug keeps per-op lines (Task W.3)
-│   │   ├── status-bar.js  # FullStatusBar — animated TUI status line
-│   │   ├── input-field.js # InputField, parseKeySequence, SLASH_CMDS
-│   │   ├── terminal.js    # Process-level signal/exit wiring + terminal teardown for the TUI
-│   │   └── create-ui.js   # createUI factory + non-TTY no-op fallback
-│   ├── mcp/
-│   │   ├── boundary.js # CJS↔ESM boundary: dynamic import() of the ESM-only MCP SDK (stdio + HTTP/SSE transports) (Task 3.2/3.3)
-│   │   ├── client.js   # MCP manager: connect servers, discover tools, register namespaced into the registry, status (Task 3.3)
-│   │   └── oauth.js    # Keychain-backed OAuthClientProvider for remote MCP servers (Task 3.3)
-│   ├── hooks.js       # Lifecycle hooks: dispatch shell/prompt hooks at agent events (Task 3.4)
-│   ├── verify.js      # Self-verification: run a configured verify command at "done", advisory/enforcing (Task 4.2)
-│   ├── checkpoints.js # Checkpoints & rewind: per-write file snapshots + /rewind restore (code/conversation/both modes), turn linkage, external-mod check + restore-path guard re-validation (Task 4.3 / 4.3b)
-│   ├── sandbox.js     # OS sandbox: Seatbelt/bubblewrap policy gen + wrap, platform detection, fallback decision, binary network isolation (Task 4.4 / 4.4b)
-│   ├── skills.js      # Skills: discover SKILL.md, metadata-only injection, body on invocation (Task 3.5)
-│   ├── subagents.js   # Subagents: spawn_agent tool, .semalt/agents defs, isolated child loop, bounded parallel (Task 3.6)
-│   ├── background.js  # Background tasks: detached-process launcher + task registry (store/validate/launch/child/kill) — NOT an agent tool (Task 5.3)
-│   ├── images.js      # Multimodal image input: read+size-cap+isPathSafe+base64, provider content-part shaping, vision-capability resolution (Task 5.4)
-│   ├── web-extract.js # Web-fetch pipeline stage 1+2: content-type classify + Readability main-content extract + Turndown HTML→Markdown + token-budget cap (Task W.1)
-│   ├── web-summarize.js # Web-fetch pipeline stage 3: data-only untrusted-safe secondary-LLM summary request builder + runner (Task W.1)
-│   ├── memory.js      # Project memory: AGENTS.md/CLAUDE.md hierarchy loader (Task 2.3)
-│   ├── headless.js    # Headless -p/--print output: text/json/stream-json (Task 2.4)
-│   ├── pricing.js     # Per-model price table → cost (Task 2.6)
-│   ├── doctor.js      # /doctor self-diagnostics: checks + aggregation (Task 2.6)
-│   ├── payload.js     # Prompt-caching + reasoning_effort payload augmentation (Task 2.7)
-│   ├── compact.js     # Conversation compaction: select/summarize/replace (Task 2.7)
-│   ├── context.js     # Loads file/directory content into the prompt
-│   ├── config.js      # Read/write ~/.semalt-ai/config.json
-│   ├── permissions.js # Per-session approval tracking for tool calls (+ per-pattern rule resolution, Task 4.1)
-│   ├── permission-rules.js # Pure per-pattern rule engine: schema, canonicalization, resolvePermission (Task 4.1)
-│   ├── deny.js        # Destructive-command deny-list for shell calls
-│   ├── secrets.js     # API-key sourcing: env → OS keychain → config
-│   ├── args.js        # CLI argument parser
-│   ├── constants.js   # CONFIG_PATH, DEFAULT_CONFIG, DEFAULT_API_TIMEOUT_MS
-│   ├── audit.js       # Append-only audit log for all tool executions
-│   ├── storage.js     # Local session persistence and resume
-│   └── metrics.js     # Token counting, cost estimation, latency tracking
-├── scripts/
-│   └── lint.js        # Zero-dep lint: `node --check` over all sources
-├── test/
-│   └── smoke.test.js  # node:test smoke suite (version, deny-list, secret guard…)
-├── .github/workflows/ci.yml  # npm ci + npm audit + lint + test matrix (Linux/macOS/Windows × Node 18,20)
-├── examples/
-│   └── embed.js       # Runnable embedding example: createAgent + permission policy + close() (Task 5.2)
-├── package.json       # name: @semalt-ai/code; exports: '.' → lib/sdk.js (facade), './internals' → lib/internals.js; bin: semalt / semalt-code; deps: @modelcontextprotocol/sdk (pinned); scripts: lint, test
-├── package-lock.json  # committed lockfile — npm ci installs strictly from it
-└── README.md
-```
+The authoritative *runtime* sources for tool tags and CLI surface are
+`lib/tool_specs.js` / `lib/prompts.js` (tool tags) and `semalt-code --help` (CLI
+flags). `docs/CONFIG.md` mirrors them for humans.
 
 ---
 
@@ -103,7 +26,7 @@ semalt-code/
 | Component | Technology |
 |-----------|-----------|
 | Runtime | Node.js ≥ 18, CommonJS (`require`) |
-| Runtime deps | `@modelcontextprotocol/sdk` (pinned, ESM, via `lib/mcp/boundary.js`); `@mozilla/readability` + `linkedom` + `turndown` (pinned, web-fetch extraction, Task W.1) |
+| Runtime deps | `@modelcontextprotocol/sdk` (ESM, via `lib/mcp/boundary.js`); `@mozilla/readability` + `linkedom` + `turndown` (web-fetch extraction) — all exact-pinned |
 | HTTP | Built-in `http`/`https` modules |
 | Shell exec | `child_process.spawnSync` |
 | File I/O | `fs` module |
@@ -113,1799 +36,198 @@ semalt-code/
 
 ---
 
-## Dependency & Supply-Chain Policy (Task 3.2)
-
-The project ran **zero runtime dependencies** through Phase 2. Adopting the official
-MCP SDK (`@modelcontextprotocol/sdk`) in v1.9.0 ends that era. The invariant is now
-**minimal, vetted, pinned dependencies** — not "no dependencies."
-
-**When a runtime dependency is allowed.** Every new runtime dependency must be:
-
-1. **Minimal** — preferred only when a Node.js built-in genuinely cannot do the job.
-   The bar for the *first* dependency was high on purpose; the bar for the next one
-   is the same. Dev-only tooling is still avoided (we lint with `node --check` and
-   test with `node:test`).
-2. **Justified** — a one-line rationale recorded here (see below) and in the PR.
-3. **Pinned to an exact version** — no `^`/`~`/ranges in `package.json`. Upgrades are
-   deliberate, reviewed commits, never silent on `npm install`.
-4. **Reviewed** — adding/bumping a dependency is a reviewed change, and the
-   regenerated `package-lock.json` is committed in the same PR.
-
-**Rationale for the web-extraction deps (Task W.1, all pinned exact).** The
-web-fetch pipeline (see **Web Fetch Pipeline** below) turns raw HTML into
-main-content Markdown — reliably parsing real-world malformed HTML, scoring the
-main article over chrome, and emitting clean Markdown are each large, bug-prone
-surfaces where a hand-rolled regex approach is exactly the wrong call (quality is
-the whole point). The chosen libraries are the reference implementations:
-- **`@mozilla/readability` (`0.6.0`)** — Firefox Reader View's extractor; the
-  de-facto standard for "main content of a page." MIT. **Zero transitive deps.**
-- **`turndown` (`7.2.4`)** — the reference HTML→Markdown converter. MIT. One
-  transitive dep (`@mixmark-io/domino`, a DOM impl).
-- **`linkedom` (`0.18.12`)** — a light DOM for Readability to operate on
-  (`jsdom` is far heavier and unnecessary here). MIT. Transitive footprint:
-  `css-select`, `css-what`, `boolbase`, `nth-check`, `domhandler`,
-  `domelementtype`, `domutils`, `dom-serializer`, `entities`, `cssom`,
-  `htmlparser2`, `html-escaper`, `uhyphen` (`canvas` is an *optional* dep, left
-  uninstalled). **Total added: ~18 packages, `npm audit` clean (0 advisories).**
-All three are loaded directly (CommonJS-compatible) from `lib/web-extract.js` —
-no ESM boundary needed (unlike the MCP SDK).
-
-**Rationale for `@modelcontextprotocol/sdk` (pinned `1.29.0`).** MCP is an open
-protocol with a non-trivial wire contract (JSON-RPC framing, capability negotiation,
-transport lifecycle, schema validation). Reimplementing it by hand would be a large,
-bug-prone surface to own and keep in spec. The **official** SDK is the reference
-implementation, MIT-licensed, and tracks the spec — exactly the case where a vetted
-dependency beats a built-in reimplementation. It is the foundation Task 3.3 builds the
-MCP client on.
-
-**ESM/CJS boundary.** The SDK is **ESM-only** (`"type": "module"`); this project is
-CommonJS. A CJS module cannot `require()` an ESM-only package. The entire codebase
-stays CommonJS — the SDK is loaded in exactly one place, `lib/mcp/boundary.js`, via
-dynamic `import()`, which re-exposes a CJS-friendly async surface (`loadSdk`,
-`createClient`, `createStdioTransport`). No other module imports the SDK directly.
-See **MCP Boundary** below.
-
-**Lockfile + CI guardrails.** `package-lock.json` is committed. CI (`.github/workflows/ci.yml`) runs:
-- `npm ci` — installs strictly from the lockfile; fails on package.json↔lockfile drift (integrity).
-- `npm audit --omit=dev --audit-level=high` — fails the build on a **HIGH or CRITICAL**
-  advisory in the **runtime** (production) dependency tree. Dev deps are excluded
-  (there are none today).
-
-**Audit-findings policy.** When `npm audit` flags an advisory:
-
-- **Critical / High** → **blocking.** CI fails. Resolve before merge by bumping to a
-  patched pinned version (regenerate + commit the lockfile), or — if no fix exists —
-  removing/replacing the dependency. A temporary, time-boxed exception requires an
-  explicit `npm audit` allow-list entry **with a written justification and a tracking
-  issue**; it is not the default.
-- **Moderate / Low** → **non-blocking** (the `--audit-level=high` gate lets them pass)
-  but **tracked**: open an issue and address on the next dependency-maintenance pass.
-  Do not raise the gate to fail on these without agreement — noisy gates get ignored.
-- **Routine maintenance** → periodically run `npm audit` and `npm outdated`; dependency
-  bumps follow the pinning + review rules above.
-
----
-
-## MCP Boundary (`lib/mcp/boundary.js`, Task 3.2)
-
-The single bridge between the CommonJS codebase and the ESM-only MCP SDK. It loads the
-SDK via dynamic `import()` (memoized — evaluated at most once per process, lazily on
-first use) and re-exposes a small async surface:
-
-- `loadSdk()` → `{ Client, StdioClientTransport }` (the named exports we consume).
-- `createClient(clientInfo?, options?)` → instantiates an MCP `Client` (does **not**
-  connect; transport + handshake are Task 3.3). Defaults `clientInfo` to this CLI's
-  `{ name, version }` and declares no capabilities.
-- `createStdioTransport(params)` → a `StdioClientTransport` for a local server subprocess.
-- `isSdkAvailable()` → synchronous resolvability check, used by the smoke test to **skip
-  gracefully** (never fail) when the dependency isn't installed (e.g. an offline runner).
-- `DEFAULT_CLIENT_INFO`, `_reset()` (test seam).
-
-**Invariant:** the SDK is imported **only** here. Anywhere else in the codebase, reach
-MCP through this module and keep using `require()`. Do not migrate the project to ESM.
-Smoke-tested by `test/mcp-boundary.test.js`.
-
-As of Task 3.3 the boundary also builds **HTTP/SSE** transports
-(`createStreamableHttpTransport`, `createSseTransport`) and merges caller `env`
-over `getDefaultEnvironment()` for stdio so a launched server keeps PATH/HOME.
-
----
-
-## MCP Client (`lib/mcp/client.js`, Task 3.3)
-
-Connects to the MCP servers under `config.mcp.servers`, discovers each server's
-tools, and registers them into the runtime tool registry under the namespace
-**`mcp__<server>__<tool>`** so they dispatch through the *same* agent loop as
-built-ins. The manager (`createMcpManager`) owns connect/discover/register,
-per-server status, and shutdown.
-
-- **Transports:** `stdio` (local subprocess) and `http`/`sse` (remote). Inferred
-  as `http` when a `url` is set and no `transport` is given.
-- **Dynamic registry:** discovered tools are registered via the new dynamic API
-  in `lib/tool_registry.js` (`registerDynamicTool` / `dynamicToolEntries` /
-  `dynamicToolSpecs`). This set is **kept separate** from the static
-  `TOOL_REGISTRY` so the load-time parity check in `lib/constants.js` (which runs
-  before any server connects) is never affected. `entryForAction`/`fromInvoke`
-  consult dynamic tools *after* the static set, so a dynamic tool can never
-  shadow a built-in. Dynamic specs are merged into the native function-calling
-  `tools` array in `api.js`, and into the XML `extractToolCalls` pass.
-- **Security posture (load-bearing):**
-  - MCP tool **results are untrusted** — `lib/agent.js` wraps `mcp__*` results in
-    the same `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` fence used for `http_get`.
-  - MCP tool **results are token-capped before entering context (Task W.8)** —
-    `formatMcpResult` (`lib/agent.js`) caps the result text with `capToTokens` at
-    the **stricter** `mcp.max_result_tokens` budget (default **10000**) **before**
-    wrapping it in the fence, so a server returning a huge payload can't blow
-    context. The result's size is third-party-controlled, hence the stricter
-    budget; the truncation notice sits **inside** the fence with the capped
-    content and the untrusted perimeter is unchanged (capping never weakens it).
-  - MCP tools **require approval by default** — their permission descriptor is
-    non-null, so they are NOT auto-allowed by the `--allow-*` tiers. Opt-in per
-    server via `allow: ["toolA", …]` or `allowAll: true` in the server spec
-    (a matching tool's descriptor then returns null, like a read-only tool).
-- **OAuth (`lib/mcp/oauth.js`):** remote servers with `oauth: true` get a
-  keychain-backed `OAuthClientProvider`. Tokens, the dynamically-registered
-  client info, and the PKCE verifier are stored in the OS keychain
-  (service `semalt-code-mcp`, namespaced per server) — **never in plaintext
-  config**, reusing the generic keychain helpers added to `lib/secrets.js`.
-- **Graceful degradation:** a server that fails to launch/connect is recorded as
-  `failed` in status with its error, a warning is logged, and the CLI continues —
-  one bad server never blocks the others or crashes startup. A `disabled: true`
-  server is skipped entirely.
-- **Management:** `semalt-code mcp list|status|add|remove|auth` (`lib/commands/mcp.js`)
-  and the in-chat `/mcp` status view. `mcp add` writes a server spec to config;
-  `mcp remove` deletes it and clears any stored OAuth material; `mcp auth` runs
-  the OAuth flow for a remote server.
-
-**Scope: interactive chat only (load-bearing limitation).** `connectAll()` is invoked
-in exactly two places — `cmdChat` (`lib/commands/chat.js`, the interactive session) and
-the `mcp list|status` management commands (`lib/commands/index.js`). The one-shot/headless
-entry points (`code`/`edit`/`shell` in `lib/commands/oneshot.js` and `-p/--print` via
-`lib/headless.js`) **never construct an MCP manager**, so MCP tools are **not available**
-in those modes — only built-in tools dispatch there. "MCP in headless / one-shot" is a
-**deferred** item (see **Deferred / Not Yet Implemented**), not a bug.
-
-**Config (`config.mcp.servers[name]`):** `transport` (`stdio`|`http`|`sse`),
-`command`/`args`/`env`/`cwd` (stdio), `url`/`headers`/`oauth` (remote),
-`allow`/`allowAll` (approval opt-in), `disabled`.
-
-Tested by `test/mcp-client.test.js` (real SDK client ↔ a local mock stdio server
-in `test/harness/mock-mcp-server.js`: discovery, namespacing, registry dispatch,
-untrusted wrapping, approval-by-default + allow opt-in, graceful degradation) and
-`test/mcp-oauth.test.js` (keychain token round-trip via an injected store).
-
----
-
-## CLI Commands
-
-```
-semalt-code                            # interactive chat (default)
-semalt-code chat                       # interactive chat (explicit)
-semalt-code code <prompt>              # one-shot task with optional file context
-semalt-code edit <file> <instruction>  # targeted file edit
-semalt-code shell <command>            # run shell, optionally ask LLM to analyze output
-semalt-code run --background <prompt>   # launch a detached background agent task (Task 5.3)
-semalt-code tasks list|status|result|kill|prune  # manage background tasks (Task 5.3)
-semalt-code login                      # browser-based device auth against dashboard
-semalt-code logout                     # clear stored auth_token
-semalt-code whoami                     # show authenticated user
-semalt-code models                     # interactive model selector (fetches from dashboard)
-semalt-code init [options]             # create/update ~/.semalt-ai/config.json
-semalt-code audit                      # print last 50 audit log entries
-semalt-code rewind [seq] [code|conversation|both]  # list checkpoints / restore files and/or conversation (latest session; default both)
-semalt-code sandbox                    # show OS sandbox status (mode, tool, availability, install hint)
-semalt-code doctor                     # self-diagnostics (config, dashboard, model, audit, key, memory)
-semalt-code config [set <key> <val>]   # show or update config keys
-semalt-code auth set-key [key]         # store API key in the OS keychain (not plaintext)
-semalt-code mcp list|status|add|remove|auth   # manage MCP servers (Task 3.3)
-```
-
-### Common Flags
-
-```
--m, --model <name>        override model for this invocation
--p, --print               headless one-shot mode (no interactive chat)
---output-format <fmt>     text | json | stream-json (implies -p)
--r, --resume <chat-id>    resume a dashboard chat by ID
--f, --file <path>         load file or directory as context
---image <path>            attach an image (PNG/JPEG/WebP/GIF) to the turn;
-                          repeatable. Read through isPathSafe, size-capped,
-                          base64-encoded. Sent to a vision model only — a
-                          text-only model errors loudly (Task 5.4)
--a, --analyze             have LLM analyze shell output (used with `shell`)
---dry-run                 preview file edits without writing
---api-base <url>          LLM API base URL (overrides config)
---api-key <key>           API key (overrides config)
---dashboard-url <url>     dashboard base URL (overrides config)
---default-model <name>    set default model in config
---show-think              display model reasoning (thinking) content
---debug                   inline debug: per-iteration debug block in chat history (TUI-safe)
---debug-file <path>       extended debug: per-iteration block + raw SSE chunks
-                          + request body dumps written to <path>, nothing to stdout.
-                          Mutually exclusive with --debug.
---allow-fs                auto-approve all filesystem operations
---allow-exec              auto-approve shell command execution
---allow-net               auto-approve network operations
---allow-all               auto-approve everything (use carefully)
---allow-anywhere          allow writes outside CWD / sensitive dirs (NOT secret-file reads)
---no-network              kernel-level no-network for sandboxed shell commands
-                          (bwrap --unshare-net / Seatbelt deny network*). Binary
-                          on/off — no host proxy, no allowlist, no TLS interception.
-                          Same as sandbox.network "off" in config. Human-only.
---dangerously-skip-permissions  the ONLY full opt-out: auto-approve all, disable deny-list
-                          and secret-file guard. Required to auto-approve in non-TTY mode.
---readonly                block all file-mutating tools (write_file, append_file,
-                          edit_file, replace_in_file, delete_file, make_dir,
-                          remove_dir, move_file, copy_file, upload, download).
-                          File TOOLS only — shell side effects are NOT constrained
-                          by --readonly (so read-only commands like `ls`/`git status`
-                          still run); shell writes are confined by the OS sandbox +
-                          deny-list, the correct layer for that.
---plan                    plan mode: propose a plan, withhold mutating tools until approved
---reasoning-effort <lvl>  minimal|low|medium|high — sent only for reasoning models
---prompt-caching          send cache_control markers on the stable prefix (opt-in)
---max-iterations <n>      cap agent-loop iterations per turn (default 50); 0 or
-                          "unlimited" removes the cap (power-user choice)
---no-verify               skip self-verification (config.verify) for this run,
-                          in both advisory and enforcing modes (Task 4.2)
--v, --version             print version
--h, --help                print help
-```
-
-### In-Chat Slash Commands
-
-| Command | Effect |
-|---------|--------|
-| `/help` | List slash commands |
-| `/file <path>` | Attach file or directory to context |
-| `/image <path>` | Stage an image (PNG/JPEG/WebP/GIF) for your next message (Task 5.4) |
-| `/history` | Browse and load a local saved session |
-| `/chats` | Browse and resume a saved chat from the dashboard |
-| `/new` | Start a fresh conversation (detach from current saved chat) |
-| `/model [name]` | Show or switch model |
-| `/models` | Interactive model picker from dashboard |
-| `/shell <cmd>` or `!<cmd>` | Execute shell command |
-| `/compact` | Summarize older turns into a compact summary (preserving recent/pinned), shrinking the context; shows before/after token counts |
-| `/memory` | Show which AGENTS.md/CLAUDE.md project-memory files are loaded and their paths |
-| `/mcp` | Show MCP server connection status and the tools each exposes |
-| `/skills` | List available skills (metadata only; each skill's body loads on invocation) |
-| `/<skill-name>` | Invoke a skill — loads its SKILL.md body into context and submits it to the agent |
-| `/plan` | Toggle plan mode — agent proposes a plan and withholds mutating tools until you run `/plan` again to approve |
-| `/rewind` | List file checkpoints, or `/rewind <seq>` / `/rewind last` to restore one. Optional mode `code` \| `conversation` \| `both` (default **both**) restores files, history, or the linked state; append `force` to override out-of-band edits (force does NOT bypass the restore-path guards). **File-tool changes only — shell side effects are not reversible.** |
-| `/doctor` | Run self-diagnostics: config + resolved layers, dashboard reachability, model/context, audit writability, key source, memory |
-| `/sandbox` | Show OS sandbox status: mode (auto/off), the detected tool (Seatbelt/bubblewrap), whether it's available, the **network mode** (on / kernel-level none), the effective posture (`ON (net:on\|off)`), and an install hint when unavailable |
-| `/clear` | Reset conversation history |
-| `/approve` | Toggle auto-approval of tool calls |
-| `/config` | Print current config |
-| `/login` | Start device auth flow |
-| `/whoami` | Show current user |
-| `/logout` | Clear auth token |
-| `exit` / `quit` | Exit |
-
----
-
-## Agent Loop (`lib/agent.js`)
-
-Iterations per user turn are capped (default **50**). The cap is overridable via
-`--max-iterations <n>` / `config.max_iterations`; **`--max-iterations 0`** (or
-`"unlimited"`) opts into a deliberately unbounded loop (power-user choice).
-`DEFAULT_MAX_ITERATIONS` (`lib/constants.js`, = 50) is the single source of truth:
-it seeds `DEFAULT_CONFIG.max_iterations` and is the factory default of
-`runAgentLoop(...)`, so a caller that omits the value still gets a real cap rather
-than `Infinity`. Entry points (`oneshot.js`, `chat-turn.js`, headless) resolve the
-config value through `resolveMaxIterations()` (the `0` sentinel → `Infinity`).
-When the cap is reached, the loop **stops gracefully**: it surfaces a clear,
-user-visible warning naming the limit and how to raise it, returns
-`stopReason: "max_iterations"`, and headless `json`/`stream-json` carry that
-`stopReason` in their envelope (`"end_turn"` on a normal finish, `"verify_failed"`
-when enforcing self-verification exhausts its attempts — see **Self-Verification**).
-Subagents keep their own separate cap of 12 (`lib/subagents.js`).
-
-At the loop's **natural end** (final answer, no tool calls — the agent declares
-done), optional **self-verification** (Task 4.2, `lib/verify.js`) may run a
-configured command before the turn is accepted; in enforcing mode a failing verify
-returns the agent to the loop (bounded by `verify.max_attempts`). See
-**Self-Verification** for the full contract.
-
-```
-1. Send messages[] to LLM via chatStream()
-2. Stream response tokens to terminal (StreamRenderer)
-3. After full response: extract tool-call tags from text
-4. If no tool tags → done
-5. For each tag: request user permission (once / always / no)
-6. Execute approved operations via ToolExecutor (wrapped in try/catch)
-7. Append tool results to messages[]
-8. Goto 1
-```
-
-Each tool dispatch is wrapped in try/catch; errors print a warning and continue to the next tag rather than aborting the loop.
-
-### Tool Tags (parsed from LLM text)
-
-```xml
-<exec>shell command here</exec>
-<shell>shell command here</shell>
-<read_file>/absolute/or/relative/path</read_file>
-<read_file path="/path/to/file"/>
-<read_file path="/path/to/file" start_line="100" end_line="200" show_line_numbers="true"/>
-<write_file path="/path/to/file">file content here</write_file>
-<create_file path="/path/to/file">file content here</create_file>
-<append_file path="/path/to/file">content to append</append_file>
-<list_dir>/path/to/dir</list_dir>
-<search_files pattern="*.ts" dir="src"/>
-<grep pattern="TODO" path="*.js" ignore_case="true"/>
-<glob pattern="src/**/*.ts"/>
-<delete_file>/path/to/file</delete_file>
-<make_dir>/path/to/dir</make_dir>
-<remove_dir>/path/to/dir</remove_dir>
-<get_env>ENV_VAR_NAME</get_env>
-<set_env name="VAR" value="value"/>
-<move_file src="/old/path" dst="/new/path"/>
-<copy_file src="/src/path" dst="/dst/path"/>
-<edit_file path="/file" line="42">replacement line content</edit_file>
-<search_in_file path="/file">regex pattern</search_in_file>
-<replace_in_file path="/file" search="old" replace="new"></replace_in_file>
-<download>https://example.com/file.zip</download>
-<download path="dist/file.zip">https://example.com/file.zip</download>
-<upload path="/local/path">base64encodedcontent</upload>
-<file_stat>/path/to/file</file_stat>
-<http_get url="https://example.com/api"/>
-<web_search query="how do tariffs work" count="5"/>
-<ask_user question="What is your preferred language?"/>
-<spawn_agent agent="reviewer">Review the diff in src/ for correctness bugs</spawn_agent>
-<git_status/>
-<git_diff staged="true" path="src"/>
-<git_log count="10"/>
-<git_add paths="a.txt b.txt"/>
-<git_commit message="Fix the parser" all="true"/>
-<git_branch name="feature-x"/>
-<git_checkout name="main" create="true"/>
-<git_worktree op="add" path="../wt" branch="feature"/>
-<store_memory key="project_lang">TypeScript</store_memory>
-<recall_memory key="project_lang"/>
-<list_memories/>
-<system_info/>
-```
-
-The system prompt (`lib/prompts.js`) instructs the LLM to use exactly these tags. Do not change tag names without updating both `prompts.js` and the parser in `agent.js`.
-
----
-
-## Lifecycle Hooks (`lib/hooks.js`, Task 3.4)
-
-Users map agent-lifecycle events to **shell commands** (or static **prompt** text)
-under `config.hooks` (user + project, merged via Task 2.2). Events:
-`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`.
-
-- **Dispatch points** (`lib/agent.js`): `UserPromptSubmit` fires once before the
-  loop for the latest user prompt; `PreToolUse`/`PostToolUse` fire per tool call
-  (honoring an optional `matcher` against the tool tag); `Stop` fires once when a
-  turn ends (not on user abort). `PreCompact` fires in the compaction sites
-  (`chat-slash.js` `/compact`, `chat-turn.js` auto-compact) before summarizing.
-- **Exit-code semantics:** a **non-zero** exit from a `PreToolUse` hook **blocks**
-  the tool — it does not run and the hook's stdout/stderr is fed back to the agent
-  as the reason (the loop continues with the next call). Exit **zero allows**; any
-  non-empty stdout (from any event) is surfaced to the agent as feedback.
-- **Security (load-bearing):** hook commands are shell, so each is checked against
-  the Phase 0 **deny-list** (`lib/deny.js`) before running — a hit is skipped,
-  never run, and does not block the tool. Command hooks then run through the **same
-  OS sandbox** as every other shell call (Pre-Task 5.0a, `resolveSandboxedSpawn` in
-  `lib/sandbox.js`) with the identical fail-safe fallback (failIfUnavailable hard
-  error / human approval / refuse); a sandbox refusal is contained like a timeout
-  (not run, logged, does not block the tool). **Prompt** hooks execute no shell, so
-  the sandbox does not apply to them. Hook output entering the agent is
-  **untrusted** — fenced in the same `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` delimiter
-  as `http_get`/MCP results (`lib/prompts.js` governs both).
-- **Project can only NARROW (Pre-Task 5.0a):** a project-layer
-  (`.semalt/config.json`, attacker-controllable in a cloned repo) **command** hook
-  is **quarantined** — dropped before any runner sees it (`loadHookLayers`,
-  consumed by `lib/config.js loadConfig`), with a one-time warning. A project may
-  add only **prompt** hooks (text injection, already untrusted). User-layer
-  (`~/.semalt-ai`) hooks are trusted as before. The layers are read **separately**
-  (raw configs, not the shallow-merged view), mirroring `loadRuleLayers`.
-- **Containment:** hooks run via `spawnSync` with a timeout (`timeout_ms`, default
-  30 s). Timeouts and any failure are contained — a bad hook logs and the loop
-  continues, never crashing.
-- **Payload to hooks:** env vars (`SEMALT_HOOK_EVENT`, `SEMALT_TOOL_NAME`,
-  `SEMALT_TOOL_INPUT`, `SEMALT_TOOL_RESULT`, `SEMALT_USER_PROMPT`) plus a JSON
-  payload on stdin.
-
-**Hook definition:** `{ type: "command"|"prompt", command|prompt, matcher?, timeout_ms? }`.
-`matcher` (PreToolUse/PostToolUse) is `*`/absent = all, else a `|`-separated list
-of anchored regexes matched against the tool tag (e.g. `"shell|exec"`, `"mcp__.*"`).
-`createHookRunner({ getConfig, spawn?, log?, onUnsandboxed?, sandbox? })` is the
-injectable dispatcher; `normalizeHooks`/`hookMatches`/`loadHookLayers` are pure.
-Tested by `test/hooks.test.js` (unit, injected spawn + pass-through sandbox),
-`test/hooks-agent.test.js` (real loop + mock-LLM + real spawn, sandbox off:
-PreToolUse block, PostToolUse observe, UserPromptSubmit inject, deny-list skip,
-failure containment, Stop firing), `test/hooks-verify-sandbox.test.js` (sandbox
-routing: fallback refuse/hard-error/approve + REAL bwrap out-of-CWD block,
-deny-list-before-sandbox, prompt-hook-unaffected), and
-`test/config-quarantine.test.js` (project command-hook quarantine, prompt kept).
-
-## Self-Verification (`lib/verify.js`, Task 4.2)
-
-When the agent declares a task done (the loop's natural end — a final answer with
-no tool calls), an optional configured **verify command** is run and its result
-fed back. Two modes, **default advisory**:
-
-- **advisory** (default): run the command once when the agent finishes, append the
-  fenced result to context as information, and **end the turn regardless** of
-  pass/fail. Advisory **never blocks**.
-- **enforcing**: a pass ends the turn; a **failing** verify returns the agent to
-  the loop with the fenced result so it can fix the problem, and it cannot finish
-  until verify passes — **bounded** (see below).
-
-**Bounding (load-bearing).** Enforcing has its own **verify-attempt limit**
-(`max_attempts`, default 3) — a *precise* bound distinct from the coarse iteration
-cap. After N failed verifies the loop terminates with the dedicated stop reason
-**`verify_failed`** (not by grinding to `max_iterations`). So enforcing always
-terminates via one of: verify-pass, the verify-attempt limit, or the iteration cap
-— never unbounded.
-
-**Verify is shell — treated like a hook** (`lib/verify.js` mirrors `lib/hooks.js`):
-- **Deny-list first** — the command passes through the Phase 0 deny-list
-  (`lib/deny.js`) before running; a hit is refused (never run) and reported as a
-  non-passing verify.
-- **OS sandbox (Pre-Task 5.0a)** — after the deny-list the command is wrapped by
-  the **same** OS sandbox as every other shell call (`resolveSandboxedSpawn`),
-  with the identical fail-safe fallback (failIfUnavailable hard error / human
-  approval / refuse). A sandbox refusal is reported as a non-passing verify —
-  never a silent unsandboxed run.
-- **Project can only NARROW (Pre-Task 5.0a)** — a project-layer
-  (`.semalt/config.json`) `verify.command` is **quarantined** (`loadVerifyLayers`,
-  consumed by `lib/config.js loadConfig`, with a one-time warning): the effective
-  verify is the **user layer's**, full stop. A cloned repo can never introduce or
-  alter the executable verify command.
-- **Timeout** — runs via `spawnSync` with `timeout_ms` (default 120 s). A hung
-  verify (e.g. a stuck `npm test`) is killed and treated as a **failed** verify —
-  it never hangs the agent.
-- **Untrusted output** — the command output (a failing test name could carry an
-  injection) is fenced in the same `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` delimiter as
-  hook/MCP/`http_get` output before it enters context.
-- **Success is exit-code based** — exit == `expected_exit_code` (default 0) is a
-  pass. **stdout is never parsed** for success patterns (avoids brittleness).
-- **Contained** — a spawn failure is a non-passing verify, never a crash.
-
-**Config (`config.verify`):** `{ mode: "advisory"|"enforcing", command, timeout_ms,
-expected_exit_code, max_attempts }`. Empty `command` → the feature is a **no-op**.
-**`--no-verify`** is a one-off skip honored in both modes (→ `verifyStatus: skipped`).
-
-**Surfacing.** `runAgentLoop` returns `verifyStatus` (`"skipped"|"passed"|"failed"`)
-alongside `stopReason`; headless `json`/`stream-json` carry both in the envelope.
-**Subagents never trigger verify** — it is a top-level gate on the user's task, so
-child loops run with `noVerify: true`.
-
-`normalizeVerify`, `createVerifyRunner` (now also accepting `onUnsandboxed?`/
-`sandbox?`), and `loadVerifyLayers` are injectable/unit-testable. Tested by
-`test/verify.test.js` (normalizer + runner with a pass-through sandbox: exit-code
-success, custom expected code, deny-list refusal, timeout, no-op/skip, untrusted
-fencing), `test/verify-agent.test.js` (real loop + mock-LLM + real spawn, sandbox
-off: advisory feeds result and ends, enforcing pass, fail-then-pass re-entry,
-exhaust→`verify_failed`, timeout, deny-list, `--no-verify`, no-command no-op,
-headless `verifyStatus`), `test/hooks-verify-sandbox.test.js` (sandbox routing:
-fallback refuse/hard-error/approve + REAL bwrap out-of-CWD block, deny-list-first),
-and `test/config-quarantine.test.js` (project `verify.command` quarantine).
-
-## Checkpoints & Rewind (`lib/checkpoints.js`, Task 4.3 / 4.3b)
-
-Before each **file-tool mutation** the affected file's prior state is snapshotted
-so `/rewind` (and `semalt-code rewind`) can restore it. Restoration is a straight
-**content-restore** (write the prior bytes back, or delete a file that did not
-exist before) — never a fragile reverse-diff replay. Task 4.3b adds
-**restore-path guard re-validation** and **three restore modes**
-(code/conversation/both) — see the two subsections at the end of this section.
-
-Rewind is **human-only — there is NO rewind tool in the registry** (static,
-dynamic, `TOOL_SPECS`, or `TAG_REGISTRY`), asserted by a test. A tool-triggerable
-rewind would be a low-value escalation surface (an agent could rewind past a
-newly-added `deny` rule); `/rewind` and `semalt-code rewind` are the only entries.
-
-**Scope limit (load-bearing, surfaced to the user).** Checkpoints cover
-**file-tool mutations only**: `write`, `append`, `edit_file`, `replace_in_file`,
-`delete_file`, `move_file`, `copy_file`, `upload` (`CHECKPOINTABLE_ACTIONS`).
-**Shell side effects are NOT reversible** — a command that created a file, touched
-a DB, or hit the network is out of scope. `/rewind` output and the docs say so
-plainly (`SCOPE_NOTICE`); a false sense of "full undo" is worse than no undo.
-Directory ops (`make_dir`/`remove_dir`) are not snapshotted either.
-
-**Capture point.** Capture happens in the executor (`agentExecFile`, `lib/tools.js`)
-**after** the permission gate approves and **before** the mutation runs:
-`beginCapture(action, args)` reads prior state pre-mutation; `commit()` runs only
-on a `status:'ok'` result. So a **denied/withheld** call (refused at the gate, in
-plan mode, or by the executor's own `--readonly`/sandbox/dry-run guards) produces
-**no checkpoint**. Capture is **fail-safe**: a snapshot failure (disk full,
-EACCES) warns and returns null — the mutation **still proceeds**, never blocked.
-
-**Subagents are checkpointed into the parent session.** A subagent reuses the
-parent's `agentExecFile`, so its mutations flow through the **same** store and are
-rewindable from the parent. The subagent's child runner is built **without** a
-`checkpoints` binding, so it never resets the turn linkage — a child's mutations
-stay linked to the **parent's** current turn (the 4.2 inheritance finding, here
-*wanted*).
-
-**On-disk layout.** `~/.semalt-ai/checkpoints/<session>/<seq>.json`, one record
-per mutation:
-
-```json
-{
-  "version": 1, "seq": 1, "session": "abcd1234", "ts": "…", "action": "write",
-  "turn": { "turnId": "turn-1", "promptId": "…", "promptIndex": 3, "messageCountAtStart": 4 },
-  "targets": [
-    { "path": "/abs/p", "role": "primary", "existedBefore": true, "isDir": false,
-      "oversize": false, "rewindable": true, "priorContentB64": "…", "priorMode": 420,
-      "afterExists": true, "afterHash": "<sha256 of what the agent left>" }
-  ],
-  "rewindable": true
-}
-```
-
-**Conversation linkage (load-bearing).** Every checkpoint records its `turn`
-linkage (`turnId`/`promptId`/`promptIndex`/`messageCountAtStart`) set by the agent
-loop at turn start (`lib/agent.js`). **Task 4.3b builds conversation-rewind on
-exactly this schema — the on-disk format was NOT changed** (a record written by
-the 4.3 code still rewinds under 4.3b, asserted by a test). Do not remove these
-fields.
-
-**Delete & move reversal.** Each target is restored to its prior state generically:
-`existedBefore` → write the prior bytes back (so **delete** recreates the file);
-`!existedBefore` → remove the file if it now exists (so a **created** file is
-deleted). A **move** records two targets — `move_src` (existed → restored to
-origin) and `move_dst` (its prior state, deleted if it didn't exist) — so rewind
-returns the file to its origin. A **copy** records only `copy_dst` (src untouched).
-
-**External-modification integrity.** Each target stores the **after-state** the
-agent left (existence + content hash). Before overwriting, `/rewind` compares the
-current file against the **latest** agent-left after-state for that path (across
-the session, so the agent's own later writes aren't mistaken for an out-of-band
-edit). A file changed externally is **reported and NOT clobbered** — the rewind is
-blocked with a `force` hint; `{ force: true }` (CLI/in-chat `force`) overrides.
-
-**Retention + size cap (mandatory).** A per-file cap (`max_file_bytes`, default
-5 MB): an oversize file (or a directory) is **not** snapshotted — recorded
-`rewindable:false` so rewind reports it as unavailable rather than exhausting disk
-— and the mutation still proceeds. A per-session retention cap (`max_per_session`,
-default 100) prunes the oldest checkpoints. (Session-scoped now; the schema's `ts`
-leaves room to move to time-based pruning later.)
-
-**Surfacing.** Each commit and rewind writes a `checkpoint` row to the audit log
-(`logCheckpoint`, `lib/audit.js`) and emits a `checkpoint:<seq>` log line.
-`semalt-code rewind` targets the **most-recently-active session**
-(`latestSession`); in chat `/rewind` uses the current session (the store's id is
-realigned to the chat `session.id` at startup).
-
-**Config (`config.checkpoints`):** `{ enabled (true), max_file_bytes (5 MB),
-max_per_session (100) }` — normalized in `lib/config.js`. The store
-(`createCheckpointStore`) is injectable (`fs`/`now`/`log`/`audit`/`rootDir`/
-`restoreGuard`) and exhaustively unit-tested by `test/checkpoints.test.js`
-(normalizer, capture pre-mutation, no-commit→no-checkpoint, restore, rewind-to-seq,
-delete/move reversal, external-mod block+force, size cap, retention prune,
-fail-safe, turn-linkage, scope notice, **+ 4.3b: guard re-validation, the three
-modes, turn-boundary cutting, orphan-free native map, human-only, on-disk
-unchanged**) and `test/checkpoints-agent.test.js` (real loop + mock-LLM: top-level
-write checkpointed + rewound, denied call → no checkpoint, **subagent mutation
-checkpointed in the parent session and rewindable**).
-
-### Restore-path guard re-validation (Task 4.3b, Part 1)
-
-The restore path does NOT blindly re-write the prior bytes. Before each
-write/delete, the target path is re-checked against the **current** guards via an
-injected `restoreGuard` (wired in `index.js` from the same primitives the executors
-use): **`isPathSafe`** (CWD confinement / `--allow-anywhere`), the **secret-file
-guard** (`isProtectedSecretPath`), the **protected-config write guard**
-(`isProtectedConfigPath`, 5.0b), and any active **`deny` permission rule**
-(`permissionManager.resolveRule`, 4.1). A target the guards now forbid — e.g. a
-path that was inside the CWD at capture but is now covered by a `deny` rule, or
-`--allow-anywhere` is no longer set — is **refused and skipped** (surfaced in the
-`refused[]` result and the audit line), **not** aborting the rest of the rewind.
-This holds whether or not `force` is used: **`force` overrides only the
-external-modification check, never the guards.** A `restoreGuard` that throws fails
-**closed** (refused). The store's own unit tests default `restoreGuard` to allow
-(a no-op), preserving the 4.3 behavior when none is injected.
-
-### Conversation-rewind + restore modes (Task 4.3b, Part 2)
-
-`/rewind <seq> [code|conversation|both]` (default **both**); same syntax for
-`semalt-code rewind`. The `turnId`/`promptId`/`promptIndex` linkage maps a
-checkpoint to its conversation point.
-
-- **code** — files only (the original 4.3 behavior); conversation untouched.
-- **conversation** — session history only; files untouched.
-- **both** (default) — files restored to the checkpoint **and** history truncated
-  to the matching turn together — the coherent linked state (code-without-
-  conversation leaves the agent amnesiac about how it got there;
-  conversation-without-code leaves it reasoning over stale files).
-
-**Turn-boundary cutting (load-bearing).** Conversation restore truncates history
-back to the **start of the turn** that produced the checkpoint — the cut always
-lands on a `user` message boundary (`planConversationRewind` →
-`locateTurnStart`/`snapToTurnBoundary`), **never mid-`tool_call`/`tool-result`
-pair**, so the restored history has **no orphaned `tool_call`** and the native
-function-calling map stays consistent (the 4.0c invariant; `findOrphanedToolCalls`
-asserts it in tests, including a native-path case). Locating the turn is robust to
-index shifts (compaction): it prefers matching the recorded `promptId` (a hash of
-the turn's user prompt) and falls back to `promptIndex`/`messageCountAtStart`,
-snapping a stale mid-turn index back to the boundary.
-
-**Post-rewind message policy: DISCARD.** The messages after the rewind point are
-**removed from active history** (the truncated array replaces `ctx.messages` in
-chat, or the saved session file for `semalt-code rewind`). They are returned as
-`conversation.removed` for transparency / optional archival but are **not retained**
-by the store or re-persisted. The store never owns the conversation — `rewind`
-takes the live `messages` array and **returns** the truncated `conversation.messages`
-for the caller to apply.
-
-## OS Sandbox (`lib/sandbox.js`, Task 4.4 / 4.4b)
-
-Wraps **every shell command (and its child processes)** in a kernel-enforced
-filesystem **and (binary) network** jail so confinement is the OS's job, not trust
-or pattern-matching. It is an **additional boundary UNDER** the deny-list
-(`lib/deny.js`), per-pattern permissions (Task 4.1), `--readonly`, and `isPathSafe`
-— defense in depth. All of those still run; the sandbox catches what they miss.
-
-**Binary network isolation (Task 4.4b).** A sandboxed command has either **normal
-network** (the default — otherwise `npm install`/`pip` are unusable) or **NONE**,
-kernel-enforced: bwrap `--unshare-net` (a fresh network namespace with no real
-interfaces) on Linux, a Seatbelt `(deny network*)` clause on macOS. There is
-deliberately **no host proxy, no domain allowlist, and no TLS interception** (so
-Go binaries like `gh`/`gcloud` are unaffected). This is **on/off per sandboxed
-command, not "allow github, block the rest."**
-
-> **Why binary, not a domain allowlist (the state-of-the-art lesson).** The
-> reference implementation (Claude Code) shipped a domain-allowlist network
-> sandbox via a host-side SOCKS/HTTP proxy. It was bypassed **completely, twice, by
-> two independent researchers, over 5.5 months** — because OS enforcement correctly
-> pins the agent to localhost, but the egress decision is delegated to a host-side
-> proxy with full network privileges, and fooling the proxy makes the **host** dial
-> out. Documented failures: (a) `allowedDomains: []` (most-restrictive intent) read
-> as "allow all" via an `allowedDomains.length > 0` check — a **fail-open**
-> (CVE-2025-66479); (b) a JS-vs-libc hostname-parser differential (`endsWith()`);
-> (c) TLS MITM in the proxy broke Go binaries. The proxy also rode on an abandoned
-> dependency in the security path. We choose **binary** isolation to remove that
-> entire class of bypass *by construction*. Domain-granularity is **deferred**
-> (see **Deferred / Not Yet Implemented**), with this rationale recorded.
-
-**Anti-fail-open (constraint, the `allowedDomains:[]` lesson).** Network defaults
-**on**, but the moment a human **touches** the network setting — `sandbox.network`
-in config, or the `--no-network` flag — that is an "isolation-requested" context,
-and there anything not **exactly** `"on"` (empty / missing-in-an-object /
-malformed / a typo / `false` / `null`) resolves to the **safe isolated state
-(no-network)**, never silently back to network (`normalizeSandbox`). The
-intended-most-restrictive input is the most-restrictive outcome. *Limitation:*
-no-network is enforced **by the jail**, so it only applies to **sandboxed**
-commands — a `mode: "off"` or human-approved-unavailable run has the host network
-(reported honestly as `net:on`).
-
-**Chokepoint (unified Pre-Task 5.0a).** The sandbox decision lives in the shared
-`resolveSandboxedSpawn` shim (`lib/sandbox.js`) — folding the config×detection
-decision, the command wrapping, and the fail-safe fallback into one async
-resolution the caller spawns. **Every** shell-executing path routes through it:
-`agentExecShell` (`lib/tools.js`, the `exec`/`shell` tool — both XML and native
-tags converge here), **self-verification** (`lib/verify.js`), and **command-type
-lifecycle hooks** (`lib/hooks.js`). So the model has **no path that runs a command
-outside the sandbox** — the previously-unsandboxed verify/hook `spawnSync` paths
-are now covered (the gap the re-audit found). Prompt hooks execute no shell and so
-are unaffected.
-
-**Platforms.**
-- **macOS** → Seatbelt via `sandbox-exec` (built-in; an SBPL policy is generated
-  per call).
-- **Linux / WSL2** → `bwrap` (bubblewrap, unprivileged user namespaces).
-- **Native Windows / WSL1** → no OS primitive (bwrap needs namespaces WSL1 lacks;
-  native Windows has none) → the sandbox is **unavailable**; the fallback applies.
-
-**Policy model (what's allowed / denied).** Reads are allowed broadly (whole FS
-readable). Writes are confined to the **working directory** (+ a writable temp
-dir). With `--allow-anywhere` the whole FS becomes writable **except** the
-protected paths, which stay read-only regardless. bwrap: `--ro-bind / /` (or
-`--bind / /` for allow-anywhere) → fresh `--proc /proc` + `--dev /dev` → `--bind`
-the writable roots → `--ro-bind` the protected paths **last** (so they win on
-overlap, e.g. cwd == `$HOME`) → `--chdir`. Seatbelt mirrors this with
-last-match-wins SBPL: `(allow default)` → deny all writes → re-allow writable
-roots → re-deny protected. **Network:** when network is `off`, bwrap prepends
-`--unshare-net` and Seatbelt adds `(deny network*)` right after `(allow default)`
-(last-match-wins keeps it denied); when `on` (the default) neither is emitted.
-
-**The three real-CVE constraints it enforces:**
-1. **The agent can NEVER disable the sandbox — or widen network access.** No
-   tool/flag/config the *model* can reach turns the sandbox off **or flips
-   no-network back to network**. `sandbox.mode` / `sandbox.network` live in the
-   human-edited user/project config; the only runtime signals are human-typed CLI
-   flags (`--dangerously-skip-permissions`, `--no-network`) or config. Call-level
-   options the model might influence cannot flip the decision (proven by tests —
-   including one passing a `{ network: 'on' }` call option that is ignored under a
-   no-network jail).
-2. **config / hooks / secrets are READ-ONLY inside the jail — including
-   not-yet-existing files** (CVE-2026-25725). The whole `~/.semalt-ai` dir, the
-   secret dirs (`~/.ssh`/`~/.aws`/`~/.gnupg`), `/etc`, **and every project
-   `.semalt` dir from the CWD up to the repo root** (Pre-Task 5.0b) are bound
-   read-only, so a sandboxed process cannot **create** a missing `config.json`
-   (or `agents`/hooks) — under `~/.semalt-ai` *or* the in-CWD `.semalt` — to
-   inject host-privileged execution. The protected-config dir set is
-   single-sourced as `protectedConfigDirs` (`lib/constants.js`) and shared by the
-   jail (`protectedPaths`) and the host write guard (see below).
-3. **procfs / symlink / `..` rewrites are confined on the RESOLVED real path**
-   (the `/proc/self/root` bypass). bwrap mounts a fresh `/proc` and the kernel
-   enforces every bind on the resolved path; protected paths are
-   `realpath()`-canonicalized before binding. (The deny-list got a matching fix —
-   see below.)
-
-**Fallback (fail-safe, defaults safe).** If the sandbox can't start (missing
-bwrap, unsupported platform) the command is **never silently run unsandboxed**:
-- default (`auto`) → fall back to a **human approval** (`onUnsandboxed`, injected
-  by `index.js`, never reachable by the model); with **no approver** (non-TTY /
-  headless / tests) the command is **REFUSED**.
-- `sandbox.failIfUnavailable: true` → a **hard error** (strict gate) instead.
-- `sandbox.mode: "off"` (a deliberate human opt-out) → run unsandboxed, status
-  `off`. `--dangerously-skip-permissions` (human-only) bypasses all safety,
-  sandbox included.
-
-**Child-process confinement.** The bwrap/`sandbox-exec` process is the
-process-group leader (`spawnWithGroup`), so the existing `lib/proc.js`
-tree-kill/abort plumbing tears down the **whole jailed subtree**, and a spawned
-subprocess (e.g. an `npm install` postinstall hook) is bound by the same jail.
-
-**Surfacing.** Each shell result carries `sandbox: 'on' | 'off' | 'unavailable'`
-**and `network: 'on' | 'off'`** fields; both appear in `--debug` (shell debug rows
-— `sandbox:` and `net:`) and the audit log (the `exec` row's input + a
-`sandbox-blocked`/`sandbox-refused` result status when the fallback blocks).
-`/sandbox` and `semalt-code sandbox` print the full status report including the
-effective network mode (`effective: ON (net:on|off)`).
-
-**Config (`config.sandbox`):** `{ mode: "auto"|"off", failIfUnavailable: bool,
-network: "on"|"off" }` — normalized by `normalizeSandbox` (`lib/sandbox.js`).
-`auto`/`network:"on"` by default; `mode:"off"` and `network:"off"` are
-**human-only** settings (plus the `--no-network` CLI flag, read once at module load
-in `lib/tools.js` and from argv in the shared shim). Detection (`detectSandbox`) is
-**cached** per process and fully injectable (`platform`/`which`/`probe`/`readFile`)
-so every platform path is unit-testable. The shared `resolveSandboxedSpawn` shim
-(Pre-Task 5.0a) is the universal entry both `agentExecShell` and the verify/hook
-paths call; it threads the network mode through `decideSandbox` →
-`wrapCommand` → the policy builders. Tested by `test/sandbox.test.js` (normalizer
-incl. the **anti-fail-open** malformed-network case, detection per platform,
-policy/argv generation incl. `--unshare-net` / `(deny network*)`, wrap, decision
-network mode, status report), `test/sandbox-agent.test.js` (executor fallback:
-refuse-on-unavailable, failIfUnavailable hard gate, approver yes/no, mode-off, no
-model-reachable bypass, deny-list still fires under the layer, **a REAL no-network
-jail surfaces `net:off` and a `{network:'on'}` call option cannot re-enable it**),
-`test/sandbox-integration.test.js` (REAL bwrap/sandbox-exec jails — out-of-dir
-write blocked, not-yet-existing config denied, nested-protected wins,
-`/proc/self/root` confined, child confinement, broad reads, **no-network blocked +
-paired network-on reachable + composes-with-fs + child inherits no-network** —
-**skips gracefully** when the primitive is absent), and
-`test/hooks-verify-sandbox.test.js` (the same shim applied to verify + command
-hooks: fallback rules + REAL kernel out-of-CWD block + **REAL no-network jail for
-verify and hook commands**).
-
-## Project Memory (`lib/memory.js`, Task 2.3)
-
-On session start, `getSystemPrompt()` appends project-local instruction files to the base prompt as a distinct, clearly-marked `<<<PROJECT_MEMORY>>>` section (trusted project context, not untrusted external content). Files are loaded in this hierarchy, all that exist, in order:
-
-1. **global** — `~/.semalt-ai/AGENTS.md`
-2. **project root** — `<repo root>/AGENTS.md` (repo root = nearest `.git` ancestor)
-3. **cwd** — `<cwd>/AGENTS.md` (only when the CWD is nested below the repo root)
-
-At each level **`CLAUDE.md` is an alias for `AGENTS.md`** — `AGENTS.md` wins when both exist, and the ignored `CLAUDE.md` is reported. Total size is bounded (`DEFAULT_MEMORY_MAX_BYTES` = 32 KB); oversized memory is truncated with a visible notice. With no memory files present, the system prompt is byte-for-byte the pre-2.3 prompt. `/memory` lists the loaded files and their resolved paths. A full system-prompt override (`--system-prompt <file>`) bypasses memory auto-loading.
-
----
-
-## Multimodal Image Input (`lib/images.js`, Task 5.4)
-
-Accept **image input** (screenshots, mockups, diagrams) so the agent can *see*.
-**Input only** — formats **PNG, JPEG, WebP, GIF**. PDF is **deferred**; image
-**generation** is out of scope entirely.
-
-- **Entry points (all three):** `--image <path>` (repeatable) on the CLI/headless
-  (`lib/args.js` → `opts.image`, attached in `cmdCode`, `lib/commands/oneshot.js`),
-  the in-chat **`/image <path>`** command (stages into `ctx.pendingImages`,
-  consumed + cleared by the next user turn — `chat-slash.js`/`chat-turn.js`), and
-  the SDK facade `agent.run(prompt, { images: [...] })` (`lib/sdk.js`, accepts file
-  paths **or** pre-encoded `{ media_type, data }` records). Each image is read
-  through **`isPathSafe`** (same guard as every file read), **size-checked**,
-  **base64-encoded**, and its **media type detected from magic bytes** (extension
-  fallback). Images attach to the **latest user turn** as an internal `images`
-  field on the message — the rest of the loop (tools, permissions, headless
-  envelope) is unchanged.
-
-- **Provider-specific content-part shape (constraint #1).** `lib/api.js` builds
-  the right encoding per endpoint at the wire, stripping the internal `images`
-  field:
-  - **OpenAI-style** (default): `{ type:"image_url", image_url:{ url:
-    "data:<media_type>;base64,<data>" } }`.
-  - **Anthropic-style**: `{ type:"image", source:{ type:"base64", media_type,
-    data } }`.
-  `selectImageFormat(config, model)` chooses by precedence: (1) the matching
-  `models[]` profile's `image_format`, (2) top-level `config.image_format`, (3)
-  heuristic — an Anthropic-native `api_base` → `anthropic`, else `openai` (the
-  project's OpenAI-compatible lingua franca). Same per-profile mechanism that
-  handles the MiniMax/Qwen quirks.
-
-- **Vision capability — FAIL LOUD, never silently drop (constraint #2).**
-  `resolveVisionCapability(config, model)` returns `true` / `false` / `null`.
-  `false` (a profile/config marked `vision:false`, or a well-known text-only
-  family — embeddings/whisper/tts/moderation) → `chatStream` **throws a clear
-  error before any request is sent** ("Model X is not vision-capable…") and the
-  image is **never** stripped from the payload. `true` (a `vision:true` profile or
-  a known vision family) → proceed. `null` (unknown) → proceed and let the
-  endpoint reject cleanly. Capability comes from config/model metadata where
-  available; otherwise the endpoint error surfaces.
-
-- **Size cap + path safety (constraint #3).** `image_max_bytes` (default **5 MB**)
-  caps the **raw** bytes before base64 (which inflates ~33%); over the cap is a
-  **clear error**, not an opaque endpoint failure. `isPathSafe` confines reads to
-  the CWD / refuses sensitive dirs exactly like other file reads.
-
-- **Config:** `image_max_bytes` (int), `image_format` (`''`|`anthropic`|`openai`);
-  per-`models[]`-profile `vision` (bool) and `image_format`. Detection/format/
-  capability/shaping live in `lib/images.js` (pure, exhaustively unit-tested).
-
-Tested by `test/images.test.js` (magic-byte detection per format incl.
-header-beats-extension; read path — size cap, `isPathSafe` refusal, unsupported,
-missing; both provider shapes; format-selection precedence; vision-capability
-fail-loud; transform helpers) and `test/images-api.test.js` (REAL api client / SDK
-↔ mock-LLM: OpenAI-style + Anthropic-style parts on the wire; **a text-only model
-errors and sends NO request — image not silently dropped — paired with a vision
-model accepting it**; a plain text turn still sends string content; the SDK
-`images` option reads a real file and the out-of-CWD path is refused).
-
----
-
-## Web Fetch Pipeline (`lib/web-extract.js` + `lib/web-summarize.js`, Task W.1 / W.1b)
-
-`http_get` no longer dumps raw HTML into context **by default** (the old behavior
-put up to 256 KB ≈ 60–80k tokens of verbatim page into the model). It runs a
-pipeline whose depth is selected by a three-level **`mode` enum** (Task W.1b):
-
-- **`summarized`** (default) — extract → Markdown → secondary-LLM summary; only
-  the compact summary enters context. For find/answer tasks.
-- **`extracted`** — extract → Markdown, **no** summary. For reading an
-  article/doc verbatim or grabbing an exact snippet/quote.
-- **`raw`** — **bypass extraction entirely**; return the **original** fetched
-  HTML/content, token-capped + fenced. For analyzing a page's HTML/CSS/JS/markup/
-  structure — the one task extraction destroys (W.1 had removed this access; W.1b
-  restores it as an explicit mode). The raw short-circuit lives at the top of
-  `processWebContent` (before `extractContent`); **`capToTokens` and the untrusted
-  fence still apply** (raw HTML is token-heavier, so the budget matters more).
-
-**Mode resolution / precedence (no ambiguity).** An explicit `mode` wins over the
-deprecated boolean aliases, which win over the `web.summarize` config default.
-The aliases `summarize="false"` and `raw="true"` both map to **`extracted`**
-(kept for back-compat — `raw="true"` still does **not** return raw HTML; use
-`mode="raw"`). Resolved both at parse time (`_httpGetOpts`/`_httpGetOptsFromParams`)
-and defensively in `http_get`'s execute (legacy booleans may arrive directly on
-the call-opts). `WEB_FETCH_MODES` (`lib/tool_registry.js`) is the canonical enum.
-
-For the `summarized`/`extracted` (non-raw) modes the stages are:
-
-1. **Extract + convert (`lib/web-extract.js`).** Classify by content-type (with a
-   light sniff fallback). For **HTML**: **Mozilla Readability** extracts the main
-   article (dropping nav/sidebar/footer/ads/scripts), then **Turndown** converts
-   it to clean Markdown. **JSON / plain-text / Markdown pass through verbatim** —
-   they are never run through the HTML parser or summarizer (no mangling).
-2. **Token budget (`capToTokens`).** A token-aware cap
-   (`web.max_content_tokens`, default **6000**, char/4 estimate) on the extracted
-   content — this **replaces the blind 256 KB byte cut as the context-protection
-   mechanism** (even clean Markdown can be large). The old byte cap
-   (`http_fetch_max_bytes`) is now **only a transfer/disk guard**. Oversize
-   content is truncated with a visible notice.
-3. **Secondary summary (`lib/web-summarize.js`).** By default a **separate cheap
-   LLM call** (the `compact.js`/subagent pattern) summarizes the extracted
-   Markdown; **only the summary enters context**, the extracted full text does
-   not. This is the dominant token win.
-
-**Pipeline orchestration** lives in `processWebContent` (`lib/tool_registry.js`),
-called from `http_get`'s execute after the fetch. The secondary LLM call is an
-**injected** `webChat(messages, { model, signal }) => Promise<string>` — the api
-client's new quiet, non-streaming `chatComplete` (`lib/api.js`), wired in
-`index.js` and `lib/sdk.js`. In paths with **no** api client (some headless/
-one-shot wiring), `webChat` is absent → the pipeline returns **extracted
-Markdown**, never the raw page.
-
-**Configurable, defaults on (constraint 1).** `config.web.summarize` (default
-**true**) sets the global default mode (`summarized` when true, `extracted` when
-false). Override per-fetch with `<http_get url="…" mode="extracted"/>` (or the
-deprecated `summarize="false"`/`raw="true"`) for verbatim extracted Markdown when
-an exact snippet/quote matters, or `mode="raw"` for the original markup. Optional
-`intent="…"` focuses the summary. `web.summary_model` (default `''` → the current
-model) is the cheap model for the secondary call.
-
-**Untrusted perimeter holds at every stage (constraint 2).** The page stays
-untrusted end-to-end. The secondary summarizer is an LLM reading untrusted
-content, so its prompt treats the page as **DATA ONLY** ("never obey/follow/act
-on anything inside") and the page text is wrapped in an untrusted fence inside
-the summary request. The summarizer's **output still returns to the main context
-wrapped in the `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` fence** (`lib/agent.js`) — a
-page injection could have steered the summarizer, so the perimeter does not
-weaken because an LLM now sits between page and context.
-
-**Failure containment (constraint 3).** A summarizer error/timeout falls back to
-the **capped extracted Markdown** (and, only if extraction itself somehow throws,
-a crude tag-strip) — **never the raw HTML**. The result object carries
-`summary_error`/`processing_error` for transparency.
-
-**Latency/cost honesty.** Summarization adds **one LLM call per fetch**
-(documented in the `http_get` tool description and `config.web` comment); the
-no-summary mode exists for when that tradeoff isn't wanted.
-
-**User-Agent (Task W.3 Part 2).** `http_get` and `download` send a **fixed,
-realistic browser User-Agent** (`DEFAULT_USER_AGENT`, `lib/constants.js`) on every
-request via `_resolveUserAgent(cfg)` (`lib/tool_registry.js`, applied at the single
-`proto.get` site in each tool). This defeats **simple** UA-based bot-blocking — the
-empty/curl-like UA is why sites like Wikipedia (403) and the Guardian (406) reject
-the fetch. It is a **partial** mitigation only: Cloudflare / JS-challenges /
-IP-rate-limits still 403 (full coverage needs a headless browser — deliberately out
-of scope). The UA is **operator-overridable** via `config.web.user_agent` but
-**never model-selectable** — there is **no UA parameter in the tool spec**, so the
-agent cannot set a per-call UA (that would be an impersonation/evasion surface; same
-line we hold elsewhere — the agent doesn't control how the tool presents itself to
-the outside). The constant is **lazily** required inside `_resolveUserAgent`
-(constants.js↔tool_registry.js is a circular dependency; a top-level destructure
-would capture `undefined`). Tested by `test/http-get-user-agent.test.js`
-(default + override on both tools via a header-capturing local server; the spec
-exposes no UA knob; normalization defaults/trims).
-
-**Result shape.** `http_get` returns `{ status_code, body, bytes, kind, mode,
-extracted, summarized, content_tokens, content_truncated, transfer_capped,
-title?, summary_error? }`. `body` is the summary, the extracted Markdown, or (in
-`raw` mode) the original token-capped content. The `lib/agent.js` formatter notes
-the mode (`summarized` / `extracted Markdown` / `raw <kind> (verbatim, capped)` /
-`<kind> (verbatim)`) in the visible prefix, still inside the untrusted fence.
-
-Tested by `test/web-extract.test.js` (classification, extraction drops
-chrome/scripts/ads, ≥3× extraction-only token reduction, JSON/text pass-through,
-token cap + notice, data-only summary-request framing),
-`test/web-fetch-agent.test.js` (real local fixture server + real extraction +
-mock summarizer: summarize-on → only the summary enters context, **≥10× token
-reduction vs raw HTML**, summarize-off → capped extracted Markdown, **injection
-in the page does not steer the summarizer and stays fenced as data**, summarizer
-failure → fallback to extracted Markdown never raw HTML, no-summarizer path,
-JSON/text pass-through, token-budget cap; **+ W.1b: `mode="raw"` returns the
-original HTML (markup intact) capped, `extracted`≡legacy `summarize=false`,
-`summarized`≡default, legacy `raw="true"`→extracted, precedence mode>boolean**),
-and `test/web-fetch-mode.test.js` (W.1b unit: alias-resolution precedence XML +
-native, the raw short-circuit returning original markup + still token-capped +
-no summarizer call, the spec exposing the three-mode enum).
-
----
-
-## Web Search (`web_search` tool, Task W.2b)
-
-A **separate `web_search` tool** closes the URL-guessing gap: the agent **searches**
-for candidate pages (snippets via SearXNG through the backend) and then **fetches
-the relevant one(s)** with `http_get` (the W.1 pipeline). Clean two-step
-separation — `web_search` *finds*, `http_get` *reads* — replacing blind
-multi-fetch with targeted fetch.
-
-- **Backend-backed (`dashboardSearch`, `lib/api.js`).** `web_search` calls the
-  backend `POST /api/search` (W.2a — authenticates the existing Bearer token,
-  queries SearXNG, returns `{ results: [{title,url,snippet}, …] }`).
-  `dashboardSearch(query, { count })` is modeled byte-for-byte on
-  `dashboardListModels` (`requireAuthToken()` → `requestJson(dashboardUrl('/api/search'), …)`)
-  and is injected into the tool executor as `webSearch` (wired in `index.js` and
-  `lib/sdk.js`, exactly like the W.1 `webChat`).
-- **Backend-unavailable is a clean tool error, never a crash (the http_get-fix
-  lesson).** The backend runs on another machine and may be down / unreachable /
-  timing out / returning a non-2xx or `{error}` envelope; auth or dashboard
-  config may be missing. The executor catches **every** failure mode — including
-  the *synchronous* `requireAuthToken()` throw — and returns
-  `{ error: "web search unavailable: <reason>" }`. **Nothing throws out of the
-  executor**, proven paired with a healthy-backend positive.
-- **The spec drives search→fetch (this is what prevents the "fetch everything"
-  mess).** The model-facing `web_search` description (`lib/tool_specs.js`) says:
-  this returns *candidate* results (title/url/snippet, **not** page content) —
-  read the snippets, pick the most relevant one or few, and fetch **only those**
-  with `http_get` (`mode="summarized"` to read, `mode="raw"` for markup); **do NOT
-  fetch every result**.
-- **Untrusted + gated like `http_get`.** Titles/snippets are third-party content,
-  so the result is wrapped in the same `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` fence
-  (`lib/agent.js`) as `http_get`/MCP results. The permission descriptor matches
-  `http_get` (`actionType: 'net'`, gated — not a privileged path; performs no
-  mutation).
-- **Compact + bounded.** Output is a compact `{title,url,snippet}` list (small
-  token cost vs fetching pages). `count` is optional, bounded client-side
-  (`_clampSearchCount`, ≤ 10) before the call and clamped again by the backend;
-  the surfaced list is never re-expanded past the request.
-- **Scope (like MCP / W.1 summarizer).** `webSearch` is wired only where an api
-  client exists (interactive chat + the SDK). In headless/one-shot paths without
-  one, `web_search` returns a clean "no backend client configured" tool error.
-
-A single registration object in `lib/tool_registry.js` (spec + native
-`fromParams` + XML `parseXml` + `execute` + `permission`) with matching
-`lib/tool_specs.js`, `lib/constants.js` (TAG_REGISTRY parity), and `lib/prompts.js`
-entries. Tested by `test/web-search.test.js` (offline, mocked `webSearch`): compact
-list from a healthy backend; XML ↔ native dispatch parity; **every backend failure
-mode → clean tool error with no exception escaping, paired with a positive**;
-missing-auth / no-client / empty-query clean errors; untrusted fence proven
-end-to-end through the real agent loop; the spec's search→fetch guidance; `count`
-passthrough + bounding.
-
----
-
-## Web-Activity Output Summary (`lib/ui/web-activity.js`, Task W.3 Part 1)
-
-A web task now runs `web_search` (find) → targeted `http_get` (read), which used
-to print **one tool line per operation** (a noisy `tool · web_search` / `net · GET …`
-list). The **default** chat view now **collapses a run of consecutive web ops into
-a single process-summary line** that reads as one process:
-
-```
-✓ web · search "коррупционные скандалы…" · 2 queries · 3 sources read · 1 blocked
-```
-
-- **Scope: `web_search` + `http_get` only.** `download` is a file-save (not a page
-  read for the search→fetch flow) and keeps its own line; all **non-web** tools
-  render exactly as before.
-- **`--debug` keeps the full per-operation lines** — the collapser is bypassed in
-  debug mode (`sessionCtx.debugMode` in `lib/commands/chat-turn.js`), so every
-  `tool · web_search` / `net · GET … · status · size` row is still shown. Nothing
-  is lost, just hidden by default.
-- **Failures are visible, never dropped.** An `http_get` that timed out OR returned
-  **≥ 400** (a 403/406 is a real block even though the fetch completed) is counted
-  as **"blocked"**; a failed `web_search` (backend down) shows as **"search failed"**
-  (`opSucceeded`). The compact view never silently omits a source that didn't load.
-- **Display only — the audit log is unchanged.** Per-operation `logToolCall` rows
-  are written in the executors (untouched); this is purely the chat-render path.
-- **Runtime model.** `createWebActivityTracker({ writerModule })` (per turn) owns
-  one writer **activity** entry per group of consecutive web ops, updating it in
-  place as ops complete and committing a **single** final summary to scrollback on
-  `flush()`. Tools run sequentially in the agent loop, so at most one group is open
-  (no concurrency). The group is flushed when a non-web tool starts (so its summary
-  lands above that tool's line) and once more at turn end (`finally`). Pure helpers
-  (`aggregateWebOps`, `webSummaryText`, `formatWebSummaryLine`, `renderWebActivity`)
-  are zero-dep and unit-tested.
-
-Tested by `test/web-activity.test.js`: scope (`isWebTool`); the 403/timeout
-"blocked" classification; the pure summary text reflecting query count / sources
-read / failures; `renderWebActivity` default→one collapsed line vs `--debug`→full
-per-op lines (status codes + URLs present); and the stateful tracker collapsing a
-multi-op group into exactly one committed line (fresh group after flush; flush
-no-op when empty).
-
----
-
-## Custom Slash Commands (`lib/commands/custom.js`, Task 3.1)
-
-Users define slash commands as Markdown files — no code. At chat startup `cmdChat` discovers them and registers them into the registry (the single source of truth), so `resolveCommand`/completion/`/help` see them alongside built-ins.
-
-- **Discovery**: `~/.semalt-ai/commands/*.md` (global) then the nearest `.semalt/commands/*.md` (project, via the Task 2.2 upward walk bounded by the repo root). Filename → command name (`review.md` → `/review`).
-- **Frontmatter** (optional, `---`-delimited): `description`, `argument-hint`, `aliases`. The body is the prompt template.
-- **Rendering**: `$ARGUMENTS` (full arg string) and `$1`/`$2`/… (whitespace-split positionals), single-pass so injected args are not re-expanded.
-- **Precedence**: project overrides global on name collision; **built-ins always win** over customs (a colliding custom is dropped with a startup warning).
-- **Invocation**: handled inline by the turn handler (`chat-turn.js`) — the rendered template is submitted to the agent as a **user prompt, never executed as code**. Custom commands are therefore excluded from `commandNames()` (the slash-handler parity check) since they need no handler.
-
----
-
-## Skills (`lib/skills.js`, Task 3.5)
-
-Skills package reusable methodology as a folder containing a `SKILL.md` (frontmatter `name`/`description` + a Markdown body) and, optionally, assets/scripts. The defining behavior is **progressive disclosure**: only each skill's **name + description** is ever injected into the system prompt; the **body loads into context only when the skill is invoked**, so skills don't bloat the prompt.
-
-- **Discovery**: `~/.semalt-ai/skills/<name>/SKILL.md` (global) then the nearest `.semalt/skills/<name>/SKILL.md` (project, via the upward walk bounded by the repo root). The folder name → invocation slug (`deep-research/` → `/deep-research`); slugs are lowercased and hyphenated.
-- **Progressive disclosure (load-bearing)**: `discoverSkills` returns **metadata only** — no body field. `getSystemPrompt` appends a `<<<SKILLS>>>` metadata block (name + description per skill) after the project-memory block. `loadSkillBody(spec)` is the **only** place a body is read, and it runs at **invocation time**, not discovery. Proven by `test/skills.test.js` and `test/skills-chat.test.js`.
-- **Precedence**: project overrides global on slug collision; **built-ins always win**, and skills also defer to already-registered custom commands (a colliding skill is dropped with a startup warning).
-- **Size bounding**: total metadata is bounded (`DEFAULT_SKILLS_MAX_BYTES` = 16 KB) with a visible truncation notice. With **no skills present the system prompt is byte-for-byte unchanged**.
-- **Invocation**: skills register into the registry (`registerSkills`) flagged `skill: true`, carrying the `skillPath` (not the body). The turn handler (`chat-turn.js`) loads the body on `/<skill>`, renders `$ARGUMENTS`/`$1` (reusing `lib/commands/custom.js`), appends the skill's assets-directory path, and submits it to the agent as a **user prompt, never executed as code**. Skills are excluded from `commandNames()` (handled inline, no handler). `/skills` lists loaded skills and their disclosure state.
-
----
-
-## Subagents (`lib/subagents.js`, Task 3.6)
-
-A **subagent** is a second agent loop run with its **own isolated message history**. It exists to keep the parent context clean: noisy work (research, reading large files, review) runs in the child and **only the child's final result returns to the parent** — the parent never absorbs the child's intermediate turns. Built directly on the `runAgentLoop` factory: a child runner is just another `createAgentRunner` instance wired with **wrapped executors** that enforce the child's allowed-tool set, sharing the parent's permission manager.
-
-- **`spawn_agent` tool** — registered as a **dynamic** tool (`registerDynamicTool` in `index.js`, like MCP), so it dispatches through the same agent loop and stays **out of the static parity check** (`lib/constants.js`). Native schema + XML (`<spawn_agent agent="x">prompt</spawn_agent>` or a JSON body) both resolve to `['spawn_agent', params]`. Available in interactive chat **and** headless one-shot runs.
-- **Custom agent definitions** — `~/.semalt-ai/agents/<name>.md` (global) then the nearest `.semalt/agents/<name>.md` (project, via the repo-root-bounded upward walk); project wins on slug collision. Frontmatter: `name`, `model`, `tools` (a.k.a. `allowed-tools`), `description`; the Markdown body is the child's **system prompt**. Invoke by name: `spawn_agent({ agent: "reviewer", prompt })`.
-- **Parallel execution** — pass `tasks: [...]` (or an array) to run independent subagents with **bounded concurrency** (a fixed-size worker pool; cap from `config.subagents.max_concurrency`, default 3, clamped 1–16).
-- **Security (load-bearing, Phase 0):**
-  - **No privilege escalation** — the child uses the **same** `permissionManager`, so it can never auto-approve anything the parent wouldn't (a child mutating tool in non-TTY without `--allow-*`/skip is refused, just like the parent).
-  - **Tool constraint** — a def's `tools` list restricts the child; the wrapped `agentExecShell`/`agentExecFile` **hard-refuse** anything outside the set (enforced at the executor, so it holds for both the XML and native paths and gives the child feedback).
-  - **No recursion** — a child can never invoke `spawn_agent` (refused by the executor + dropped from any allowed-tool set).
-  - **Untrusted result** — a subagent's returned text is fenced in the `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` delimiter (`lib/agent.js`), like `http_get`/MCP/hook output, because a child may have read external data.
-  - **Result token-capped (Task W.8)** — `formatSubagentResult` (`lib/agent.js`) caps the child's final text with `capToTokens` at the **generous** `subagents.max_result_tokens` budget (default **20000**) before fencing — a safety net against a verbose child, distinct from and strictly larger than the MCP budget (the child's result is our own deliberate, synthesized answer). The truncation notice signals the result was long. Isolation / no-escalation are unchanged — this bounds the *returned text size* only.
-- **Config** — `subagents` is normalized to `{ max_concurrency, max_result_tokens }` (defaults 3 / 20000). Tested by `test/subagents.test.js` (discovery/frontmatter, allowed-tool resolution, bounded pool, the tool entry), `test/subagents-agent.test.js` (real child loop ↔ mock-LLM: isolation, untrusted fencing, tool constraint, permission inheritance), and `test/result-cap.test.js` (W.8: result cap + fence + budgets-differ).
-
----
-
-## Background Tasks (`lib/background.js`, Task 5.3)
-
-Run an agent task as a **detached background process** that survives the terminal
-closing, with a task registry to list, inspect, collect, and terminate it. Each
-background task is its **own process** — its own `process.cwd()`, its own dynamic
-tool registry, its own everything — which **sidesteps the documented in-process
-multi-instance global-state limits** of the embedding SDK (Task 5.2): isolation
-comes for free from the process boundary. The child reuses the **stable
-`createAgent` facade** internally.
-
-- **Launch (CLI/SDK, human-initiated):** `semalt-code run --background "<prompt>"`
-  (`cmdRun`, `lib/commands/tasks.js` → `launchBackground`, `lib/background.js`),
-  or programmatically via `launchBackground(...)`. Policy flags (`--allow-*`,
-  `--readonly`, `--dangerously-skip-permissions`, `-m`) are read **at launch**.
-- **Manage:** `semalt-code tasks list|status <id>|result <id>|kill <id>|prune`
-  (`cmdTasks`). `result` prints the standard headless envelope; `prune` removes
-  finished + stale entries.
-
-**Validate before detach (constraint 4, load-bearing).** After forking there is
-**no terminal to surface errors to**, so `launchBackground` runs `validateLaunch`
-**synchronously before any process is spawned** — config validity (`api_base`, a
-resolvable model), permission-policy shape (rule `tool`/`action`/single-matcher),
-and sandbox availability (only a hard error when `failIfUnavailable`). An optional
-injected `probeModel` covers reachability. A validation failure **throws in the
-parent and spawns nothing** — no orphan (proven by the spawn-spy test).
-
-**Launch-fixed, refuse-by-default posture (constraint 1).** A background task has
-**no TTY and no human to ask**, so its permission policy is set at launch and can
-**never** fall through to an interactive prompt. The child builds its agent via
-`createAgent` with the launch policy; with **no policy the default REFUSES every
-mutating/effectful tool** (read-only tools still run), inheriting the 5.2 embedded
-perimeter. The **OS sandbox + destructive-command deny-list stay ON** in the child
-unless an opt-out is passed **explicitly at launch** (`sandbox.mode: 'off'`, or
-`--dangerously-skip-permissions`, which is propagated into the child's argv so
-`lib/tools.js` honors it for the deny-list/secret/config guards). An unavailable
-sandbox in `auto` mode **refuses** the command (no human to approve).
-
-**IPC via files, not a live channel (constraint 3).** The detached child writes
-**NDJSON** progress + a result envelope into the task dir; the parent reads them
-on `collect`. This survives the terminal closing and needs no live IPC.
-
-**Task store layout — `~/.semalt-ai/tasks/<id>/`** (`createTaskStore`, injectable
-`fs`/`now`/`rootDir`; atomic `meta.json` writes via temp+rename):
-- `spec.json` — the launch spec the child reads (prompt, apiBase, model, cwd,
-  policy, sandbox, maxIterations). **No secrets on disk** — the API key is passed
-  to the child via its **env** (`SEMALT_API_KEY`), never written here.
-- `meta.json` — registry record / current status snapshot `{ id, pid, status,
-  started_at, finished_at, prompt_summary, model, policy_summary, stopReason?,
-  error? }`.
-- `events.ndjson` — append-only progress log (one JSON object per line, like the
-  audit log): `status` / `tool` (with `ok` + a `detail` excerpt on failure, e.g. a
-  deny-list refusal) / `warning` / `error` / `result`.
-- `result.json` — the final headless envelope `{ result, toolCalls, usage, cost,
-  stopReason, verifyStatus }`.
-
-**Orphan lifecycle (constraint 2).** `proc.js` gains `spawnDetached` (session
-leader + `stdio: 'ignore'` + `unref()`), `killTreeByPid(pid, signal)` (POSIX
-negative-PID group kill / Windows `taskkill /T`, used by `tasks kill` after the
-launcher has exited), and `isProcessAlive(pid)` (`process.kill(pid, 0)`,
-EPERM = alive). A task marked `running` whose PID is no longer alive is **computed
-as `stale`** (`effectiveStatus`) — never persisted as a lie — so zombies never
-accumulate invisibly: `tasks list` flags them and `prunableIds`/`prune` clean them
-up. `killTask` SIGTERMs the recorded PID, waits a grace period, escalates to
-SIGKILL if still alive, then marks the record `terminated`.
-
-**Tool-exposure decision (constraint 5) — NOT an agent tool, deliberately.**
-Background-launch is reachable **only** from the human-initiated CLI/SDK surface;
-there is **no `run_background`/`spawn_background` tag, no `TOOL_SPECS` entry, and
-nothing in the static or dynamic tool registry** (asserted by a test). Rationale:
-a model-reachable background launcher would be a **privilege-escalation surface**
-— the agent could fork a fresh process to escape its own permission perimeter (the
-subagent no-escalation rule, 4.5). Subagents already give the model in-process
-parallelism while **sharing the parent permission manager**; background tasks
-serve a different, human-owned need, so keeping the launcher off the tool surface
-removes the escalation question entirely. *If* a future task exposes such a tool,
-it MUST inherit and not exceed the launching agent's posture.
-
-Tested by `test/background.test.js`: store CRUD + list ordering; validation flags
-empty prompt / missing model / malformed policy / strict-unavailable sandbox;
-**validation failure spawns no process (no orphan)**; launch persists spec+record,
-detaches via an injected spawn, defaults sandbox ON with explicit opt-out and the
-key carried via env (not disk); **real `createAgent` ↔ mock-LLM** child completes
-and writes the envelope; **safe posture** (no policy refuses a write, paired with
-an allow rule permitting it); **deny-list active inside the background process**;
-stale detection + prune; `killTask` tree-kills + marks terminated; a **real
-detached process** is alive then tree-killable by PID; an **E2E real detached
-`__bg-exec` child** runs the agent and writes the envelope; and the
-**no-background-tool** decision.
-
----
-
-## Native Git Tools (`lib/tool_registry.js`, Task 5.1)
-
-First-class git tools for the common operations where structured results help the
-agent; the long tail (rebase, reflog, cherry-pick, stash, submodule, remote ops…)
-stays in the **sandboxed** generic shell. Each tool is a single registration object
-(spec + native `fromParams` + XML `parseXml` + `execute` + `permission`) alongside
-every other tool — same `TOOL_SPECS` / `TAG_REGISTRY` parity guard, same
-`[action, opts]` dispatch over both the XML and native rails.
-
-- **The eight tools.** Read-only: `git_status`, `git_diff`, `git_log`. Mutating:
-  `git_add`, `git_commit`, `git_branch`, `git_checkout`. Infrastructure:
-  `git_worktree` (create/list/remove worktrees for parallel agents in isolated
-  trees). Everything else is plain shell.
-- **Structured output.** They shell out to `git` (no new dependency) but **parse the
-  output into structured results** the model can act on:
-  - `git_status` → `{ branch, staged:[{path,status}], unstaged:[…], untracked:[…], clean, summary }`
-    (porcelain v1 + `--branch`).
-  - `git_diff` → `{ staged, files:[{file, additions, deletions, hunks:[{header, lines}]}], additions, deletions, raw, summary }`.
-  - `git_log` → `{ commits:[{hash, short, author, email, date, subject}], count, summary }`
-    (a fresh repo with no commits degrades to an empty list, not an error).
-  - `git_add` → `{ added, summary }`; `git_commit` → `{ hash, short, branch, summary }`;
-    `git_branch` (list) → `{ branches:[{name,current}], current }`, (create/delete) →
-    `{ created|deleted, summary }`; `git_checkout` → `{ branch, created, summary }`;
-    `git_worktree` → `{ op, worktrees|path|branch, summary }`.
-  The model sees a `summary` string (`formatFileResult` surfaces it); structured
-  fields are returned for callers/tests.
-- **Permission posture by operation type (constraint).** Read-only tools — and the
-  **list** ops of `git_branch`/`git_worktree` — return a **null** permission
-  descriptor (no prompt). Mutating tools return a descriptor, honor `--readonly`
-  (`git_add`/`git_commit`/`git_branch`/`git_checkout`/`git_worktree` ∈
-  `READONLY_BLOCKED`), and pass through the per-pattern rule layer (a `deny` rule
-  refuses them; an `allow` rule lets them run). Git tools are **not** in any
-  `--allow-*` tier, so they are never auto-approved by a coarse tier flag.
-- **Confinement (constraint).** Every git invocation runs through
-  `ctx.agentExecShell` — the **same** sandbox + deny-list chokepoint as `<shell>` —
-  so git gets no privileged path around confinement. Arguments are shell-quoted
-  (platform-aware) before the command string is handed to the chokepoint; the
-  deny-list/sandbox remain the security boundary.
-- **`git_commit` message is the agent's, structured.** `message` is required and
-  must be non-empty; an empty/whitespace message **errors without committing**
-  (never a placeholder commit).
-- **Destructive-git ↔ checkpoint honesty (load-bearing).** Checkpoints (Task 4.3)
-  snapshot **file-tool** mutations only. `git_checkout` (and any reset-like effect)
-  can overwrite or discard uncommitted working-tree changes that checkpoints never
-  captured — **git-discarded changes are NOT recoverable via `/rewind`.** This is
-  stated in the tool descriptions (`TOOL_SPECS`), the permission prompt text, and
-  here; do not imply `/rewind` covers git.
-- **Graceful degradation.** Not-a-repo and git-absent return a clear `{ error }`
-  (mapped from the git output), never a crash.
-
-Tested by `test/git-tools.test.js` (real `git init` temp repo, sandbox off):
-structured status/diff/log; read-only descriptors don't prompt while mutating ones
-do; add+commit produces a real commit (hash matches the log) and an empty message
-errors with no commit; branch/checkout switch; the **paired** `--readonly` block +
-non-readonly success and the **paired** per-pattern `deny`/`allow` resolution;
-worktree add/list/remove; not-a-repo and git-absent degrade gracefully; the
-checkpoint-scope caveat is present in the description; XML ↔ native tuple parity.
-
----
-
-## Embedding SDK (`lib/sdk.js` + `lib/internals.js`, Task 5.2)
-
-The project is consumable as a **library**, not only an executable, with a
-**two-tier surface physically separated by `package.json` `exports`** (not just
-documented):
-
-- **Stable facade** — `require('@semalt-ai/code')` → `{ createAgent }` (main
-  entry, `exports['.']` → `lib/sdk.js`). The supported, semver-stable contract.
-- **Unstable building blocks** — `require('@semalt-ai/code/internals')`
-  (`exports['./internals']` → `lib/internals.js`) re-exports `createAgentRunner`,
-  `createApiClient`, `createToolExecutor`, the registries, config, etc., behind a
-  loud **NO STABILITY GUARANTEE** notice and an `__unstable__: true` marker.
-  Internal refactors don't break facade consumers because the boundary is the
-  `exports` map. Both subpaths resolve for `require` **and** `import` (CJS named
-  exports via ESM interop — the project stays CommonJS).
-
-**`createAgent(options)` → `{ run, on, off, close, getConfig, cwd, closed }`.**
-- `run(prompt, opts?)` executes a prompt to completion and returns the **headless
-  envelope** `{ result, toolCalls, usage, cost, stopReason, verifyStatus }` (built
-  by reusing `createHeadlessSink`), plus `messages` for multi-turn continuation
-  (`run(next, { messages })`). Accepts `images: [...]` (file paths or pre-encoded
-  `{ media_type, data }` records) to attach images to the turn (Task 5.4 — read
-  through `isPathSafe`, size-capped, sent only to a vision model). Streams via
-  `on(event, cb)` —
-  `token`/`assistant`/`tool`/`tool-start`/`error`/`warning`/`done`. Chrome is
-  suppressed for the run (`setUIActive`) so the host's stdout stays clean.
-- It assembles a **per-instance** config closure, api client, permission manager,
-  tool executor, and agent runner — no shared module-global config between two
-  `createAgent` instances.
-
-**Programmatic permission perimeter — defaults safe (load-bearing).** No TTY in
-embedded use, so the policy is programmatic:
-- `approve(call) → boolean|Promise<boolean>` — an async approver (the programmatic
-  equivalent of the interactive prompt), wired through a new `approver` option on
-  `createPermissionManager`. Consulted only when the gate would otherwise refuse
-  for lack of a way to ask, so it never widens what a tier already granted;
-  throwing/falsy = no (fail closed).
-- `rules: [...]` (or `{ user, project }`) — preset allow/deny/ask rules reusing the
-  Task 4.1 engine (host rules are the **user** layer = trusted; `loadProjectRules:
-  true` adds the on-disk project layer, which can still only **narrow**).
-- `allow: ['fs'|'exec'|'net'|'sys'|'all']`, `readonly: true` — coarse tiers.
-- **With NO policy the default is to REFUSE every mutating/effectful tool**
-  (read-only tools still run), mirroring non-TTY — never auto-approve.
-
-**Sandbox/deny-list stay on; opt-out is explicit (load-bearing).** The OS sandbox
-defaults to `auto` (on) and the destructive-command deny-list + secret/config
-guards stay active in embedded mode — **not** disabled by the absence of a TTY.
-Disabling is deliberate, documented opt-in: `sandbox: { mode: 'off' }`,
-`onUnsandboxed` to permit an unsandboxed run when the kernel primitive is missing,
-and `dangerouslySkipPermissions: true` for the gate (still cannot bypass a `deny`
-rule or the deny-list). By default the SDK does **not** read the operator's
-`~/.semalt-ai/config.json` (`loadUserConfig: true` opts in).
-
-**Lifecycle.** `createAgent` may open resources (MCP servers — connected lazily on
-first `run` when `config.mcp.servers` is set). Hosts **must** call `await
-close()`, which shuts down the MCP manager and removes listeners; `run()` after
-`close()` throws.
-
-**Multi-instance — documented module-global limitations (constraint 4).** Per-
-instance config is isolated, but a few surfaces are process-global because they
-were built for the single-process CLI: the **dynamic tool registry**
-(`lib/tool_registry.js _dynamic`, where MCP + `spawn_agent` register) is shared;
-`isPathSafe` / the deny-list / secret+config guards read `process.cwd()` and
-`process.argv` **once at module load** (so the deny-list opt-out needs the host
-process launched with `--dangerously-skip-permissions`); and the chrome-suppress
-flag is process-wide. Fully-isolated agents → separate processes. This is stated
-honestly in the README rather than papered over.
-
-Documented in README **Embedding SDK**; runnable `examples/embed.js`. Tested by
-`test/sdk.test.js` (real `createAgent` ↔ mock-LLM: envelope shape; **safe default
-refuses a mutating write with no policy** + paired positives via approver and via
-an allow rule; deny-list still blocks under an approving gate; sandbox default-on
-vs explicit opt-out; per-instance config isolation; `close()` disconnects a REAL
-stdio MCP server; run-after-close throws; the `exports` map resolves both
-subpaths).
-
----
-
-## Tool Operations (`lib/tools.js`)
-
-All operations request permission before execution unless auto-approved.
-**Shell/exec output entering the model context is bounded** by a head+tail line
-cap (`config.max_output_lines`, default 50) plus a token safety net
-(`config.max_output_tokens`, default 10000) — Task W.6, `capShellOutput` in
-`lib/agent.js`; see the shell-output-bounding note under **Key Patterns &
-Invariants**. Other tools cap their own output as documented per-action.
-
-| Action | Description |
-|--------|-------------|
-| `read` | Read file content, **paginated** (Task W.7): default returns the first `read_line_cap` (~2000) lines; over the cap the model-facing result ends with a `[PARTIAL]` notice giving the total and the `start_line` for the next page. `start_line`/`end_line` read an explicit slice (also line-capped). `show_line_numbers` (default off) prefixes absolute 1-based numbers for driving `edit_file`. A token safety net (`read_max_tokens`) bounds pathological long lines. Byte cap (`max_file_size_kb`) is now a backstop, not the primary bound |
-| `write` | Write file (creates parent dirs) |
-| `append` | Append to file |
-| `list_dir` | List directory contents |
-| `delete_file` | Delete file |
-| `make_dir` | Create directory (recursive) |
-| `remove_dir` | Remove directory (recursive) |
-| `move_file` | Move/rename file |
-| `copy_file` | Copy file |
-| `search_files` | Find files matching glob pattern |
-| `grep` | Regex search file contents across the tree; **serializes the structured matches (`file:line:text`) into context** so the agent can navigate to a slice instead of reading whole files (Task W.5 — previously the result was dropped and the model got `"grep: done"`). `output_mode`: `content` (default, `file:line:text`), `files_with_matches` (unique paths), `count` (per-file + total). Bounded by `head_limit` (default 100, `lib/constants.js`) + optional `offset`, with a truncation notice when more matched. Honors `.gitignore`, skips binaries + `node_modules`/`.git`; uses ripgrep when present with an identical pure-Node fallback |
-| `glob` | List files matching a glob; **serializes the relative-path list into context** (Task W.5 — previously `"glob: done"`), bounded by `head_limit` (default 100) + `offset` with a truncation notice |
-| `search_in_file` | Regex search within file |
-| `replace_in_file` | Replace text in file (regex, optional flags) |
-| `edit_file` | Replace a specific line number in a file |
-| `get_env` / `set_env` | Read/write environment variables |
-| `download` | HTTP GET → save to file. Confined like every other write path: optional `path` destination defaults to the CWD basename, routed through `isPathSafe` + the secret-file guard, refused under `--readonly`, and size-capped (`download_max_bytes`) — exceeding the cap aborts the stream and removes the partial file. Sends the fixed browser User-Agent (`config.web.user_agent`, Task W.3) |
-| `upload` | Write base64-encoded content to file |
-| `file_stat` | Stat a file (size, mtime, type, mode) |
-| `http_get` | HTTP GET → **web-fetch pipeline** (Task W.1 / W.1b): a three-level `mode` enum — `summarized` (default: Readability extract → Turndown Markdown → secondary-LLM summary, only the compact result enters context), `extracted` (extracted Markdown verbatim, no summary), `raw` (the **original** fetched HTML/content, token-capped — for analyzing markup/CSS/JS/structure). Deprecated `summarize="false"`/`raw="true"` ≡ `mode="extracted"`; `intent="…"` focuses the summary. JSON/plain-text pass through. Sends the fixed browser User-Agent (`config.web.user_agent`, Task W.3 — operator-overridable, never model-selectable). See **Web Fetch Pipeline** |
-| `web_search` | Search the web via the backend `POST /api/search` (SearXNG, Task W.2b): returns a **compact** `{title,url,snippet}` list so the agent picks relevant results and fetches them with `http_get` instead of guessing URLs / fetching every page. Backend-unavailable (down/unreachable/timeout/non-2xx/`{error}`/no-auth/no-config) degrades to a clean tool error — never a crash. Results are fenced as untrusted. `count` is optional + bounded. **Interactive chat / SDK only** (needs the api client; no-op clean error in headless/oneshot wiring without one) |
-| `ask_user` | Prompt user for input; auto-answers 'y' in non-TTY mode |
-| `store_memory` | Persist a key/value pair to `~/.semalt-ai/memory.json` |
-| `recall_memory` | Read a key from `~/.semalt-ai/memory.json` |
-| `list_memories` | List all stored memory keys |
-| `system_info` | Return platform, arch, hostname, memory, Node version, cwd |
-| `spawn_agent` | Launch an isolated child agent loop (optionally a named `.semalt/agents` def, model override, or parallel `tasks[]`); returns only the child's final result, fenced as untrusted (Task 3.6) |
-| `git_status` | Structured working-tree status (staged/unstaged/untracked + branch). Read-only (Task 5.1) |
-| `git_diff` | Structured diff (files, hunks, +/- counts); `staged` for the index diff, optional `path`. Read-only |
-| `git_log` | Recent commits as structured records (hash/short/author/email/date/subject); `count`, optional `path`. Read-only |
-| `git_add` | Stage changes (`paths` or `all`). Mutating |
-| `git_commit` | Commit with a **required non-empty** `message` (empty → error, never a placeholder); returns the new hash + branch. Mutating |
-| `git_branch` | List branches (no `name`, read-only) or create/delete one (`name`, with `delete`/`force`). Create/delete is mutating |
-| `git_checkout` | Switch to a branch/ref (`create` for `-b`, `force` for `-f`). Mutating. **Can discard uncommitted changes — NOT recoverable via `/rewind`** |
-| `git_worktree` | `op: list` (read-only) / `add` (optional new `branch`) / `remove` (`force`) linked worktrees for parallel agents. add/remove mutating |
-
----
-
-## Context Compaction & Payload Tuning (`lib/compact.js`, `lib/payload.js`, Task 2.7)
-
-**`/compact`** is a real LLM summarization turn: `selectForCompaction` splits history into a head to summarize and a recent tail (plus pinned messages) to keep, the model summarizes the head (`summarizationRequest` → `chatSync`), and `buildCompactedMessages` rebuilds `pinned + summary + tail`. Before/after token counts are shown. **Auto-compaction** runs the same path in `chat-turn.js` when `shouldAutoCompact` fires (usage past 85% of a known limit), complementing — not duplicating — api.js `trimToTokenBudget` (which drops rather than summarizes). All selection/replacement logic is pure and unit-tested.
-
-**Prompt caching** (`config.prompt_caching` / `--prompt-caching`): `applyPromptCaching` adds `cache_control:{type:'ephemeral'}` to the stable prefix (last system message + last tool) in the request body — opt-in, so it's never sent to endpoints that reject it. **`reasoning_effort`** (`config.reasoning_effort` / `--reasoning-effort`): `applyReasoningEffort` adds the param only for reasoning models (`supportsReasoningEffort` heuristic, or `reasoning_effort_force`). Both are applied in `api.js doRequest` and proven present/absent by request-body tests.
-
----
-
-## Self-Diagnostics & Cost (`lib/doctor.js`, `lib/pricing.js`, Task 2.6)
-
-**`/doctor`** (and `semalt-code doctor`) aggregate pass/warn/fail checks: config validity + resolved layers (2.2), API-key source (Phase 0), selected model + whether its context limit is known, dashboard reachability, audit-log writability, and loaded project-memory files (2.3). `aggregateChecks`/`formatDoctorReport` are pure; `diagnose` injects the impure gatherers. Overall = fail if any fail, else warn if any warn, else pass.
-
-**Cost** (`lib/pricing.js`): a per-model price table (USD per 1,000,000 tokens) × token usage. `priceForModel` matches exact then longest-substring; `config.pricing` (`{ "<model>": { input, output } }`) overrides/extends the built-in table. `computeCost` returns `null` for an unknown price and `formatCost` renders that as **"unknown"** — never a fake `$0`. `show_cost` defaults **on**; cost appears in the status bar (`setCost`) and in headless `json` output. All cost math and doctor aggregation are unit-tested.
-
----
-
-## Plan Mode (Task 2.5)
-
-`--plan` (one-shot/headless) and `/plan` (in-chat toggle) gate execution: while active, the agent investigates with read-only tools and proposes a plan, but every **mutating** tool is withheld until the user approves. The mutating-vs-read-only split comes straight from the **permission descriptor** in the tool registry — `describePermission(call)` returns `null` for read-only tools and a descriptor for effectful ones — not from string-matching tool names (`lib/agent.js`). Withheld calls are recorded in the loop's `withheldActions` return and surfaced via the `onPlanWithhold` callback. In chat, `/plan` toggles `ctx.planMode` (threaded into the loop as `getPlanMode`); toggling it back off is the approval — the agent then executes with the plan already in context. `/clear` discards. A `PLAN_MODE_NOTICE` (`lib/prompts.js`) is appended to the system prompt while active.
-
----
-
-## Per-Pattern Permissions (`lib/permission-rules.js`, Task 4.1)
-
-Rich permission rules that layer **on top of** the coarse `--allow-fs`/`--allow-exec`/`--allow-net` tiers, `--readonly`, and the per-session "always for `<tag>`". A rule matches on a **tool** *and* (optionally) its **arguments** and resolves to one of `allow` / `deny` / `ask`. The whole resolver (`lib/permission-rules.js`) is **pure** and exhaustively unit-tested (`test/permission-rules.test.js`); the gate wiring is proven end-to-end against the mock LLM (`test/permission-rules-agent.test.js`).
-
-**Rule schema** — under `permissions.rules` in user (`~/.semalt-ai/config.json`) and project (`.semalt/config.json`) config:
+## Directory Layout
 
-```json
-{ "permissions": { "rules": [
-  { "tool": "shell",      "pattern": "git *",                "action": "allow" },
-  { "tool": "shell",      "pattern": "/curl.*\\| *sh/",      "action": "deny"  },
-  { "tool": "write_file", "path":    "src/**",               "action": "allow" },
-  { "tool": "read_file",  "path":    "**/*.env",             "action": "ask"   },
-  { "tool": "http_get",   "url":     "https://internal/*",   "action": "allow" }
-] } }
 ```
-
-- **`tool`** — required. Matched (as a glob, so `*` / `mcp__*` work) against **both** the canonical action and the public tag (`shell`↔`exec`, `write`↔`write_file`, …).
-- **One matcher key** — `pattern` (command, greedy glob), `path` (segment-aware glob: `*` stops at `/`, `**` crosses), `url`, or generic `match`. Omit for a tool-only rule. Supplying more than one is malformed.
-- **Glob vs regex by syntax** — a value wrapped in `/…/` (optional `imsuy` flags) is a **regex**; anything else is a **glob**.
-- **`action`** — `allow` | `deny` | `ask`.
-
-**Precedence (total + deterministic).** Within a layer: most-specific rule wins (specificity = literal-char count; a literal `tool` outweighs `*`); among equal specificity, **deny > ask > allow** — so the result is **order-independent**. Across layers the **most-restrictive** decision wins (`deny` > `ask` > `allow` > none). No rule matching → `null`, falling back to the tier/descriptor default.
-
-**Project can only NARROW (the security core).** `.semalt/config.json` is attacker-controllable (cloned repos). The two layers are loaded **separately** (`loadRuleLayers`, NOT the shallow-merged config) and `resolvePermission` **drops every project `allow` rule before resolution** — structurally, so a project rule can only ever contribute `deny`/`ask` and can never grant a permission the user layer didn't. Proven adversarially (`ADVERSARIAL: project allow(shell *) does NOT grant shell…`).
-
-**Other load-bearing properties:**
-- **Canonicalize before matching** — `normalizeCall` resolves `..`, symlinks (`fs.realpathSync`), and absolute/relative forms (matching on both, posix-normalized) so `write(src/../../etc/passwd)` cannot satisfy an `allow` scoped to `src/**`.
-- **Regex safety / fail closed** — a pathological or invalid pattern is dropped at load (ReDoS heuristic + bounded subject length); a matcher that errors at runtime **never grants** (erroring `allow` → no-match) and **still restricts** (erroring `deny`/`ask` → match); a malformed rule is dropped with a startup warning.
-- **Compose, never bypass** — rules sit *alongside* the Phase 0 controls. An `allow` rule auto-approves the *gate* but the call still passes through the unbypassable **deny-list** (`agentExecShell`), the **secret-file guard**, **`--readonly`**, and `isPathSafe` in the executors — an `allow` can never re-enable what those forbid (proven by the `COMPOSE:` tests).
-- **`deny` beats `--dangerously-skip-permissions`** — an explicit user `deny` rule is a fail-closed hard stop honored even under skip (unlike the heuristic deny-list, which skip disables); `allow`/`ask` are subsumed by skip's auto-approve.
-
-**Integration.** `index.js` loads the layers and passes them to `createPermissionManager({ rules, cwd })`. The agent gate (`lib/agent.js`) calls `permissionManager.resolveRule(call)` for **every** tool call (covering XML *and* native — they converge on the same `[action, ...args]` tuple): `deny` hard-blocks (the model gets the reason and adapts), `allow`/`ask` thread into `askPermission(...)` (allow auto-approves what a tier wouldn't; `ask` forces a prompt a tier would skip — refused in non-TTY). Matched rules surface in `--debug` (a `perm_rule:` row) and the audit log (`rule-denied:<reason>`).
-
----
-
-## Headless Output (`lib/headless.js`, Task 2.4)
-
-`-p/--print` runs a one-shot agent task non-interactively; `--output-format` selects the surface (and implies `-p`):
-
-- **text** (default) — current human output.
-- **json** — a single JSON object `{ result, toolCalls: [...], usage, cost, stopReason, verifyStatus }` to stdout, nothing else.
-- **stream-json** — newline-delimited JSON events (`{type:'assistant'|'tool'|'result', …}`), one per line, for piping. The terminal `result` event carries `stopReason` and `verifyStatus`.
-
-Machine modes (`json`/`stream-json`) suppress all chrome via `setUIActive(true)` for the run — the two headless chrome sinks (tools' `_log` ✓/✗ lines and the write/append permission diff) both honor that flag — so stdout stays byte-pure (no ANSI). `runHeadless` takes an injectable `write` sink so the formatter is unit-testable. `cost` is `null` until the price table lands in Task 2.6. Phase 0 safety is unchanged: headless still refuses deny-listed/interactive-approval actions unless `--dangerously-skip-permissions`. Usage: `semalt-code -p --output-format json "your task"` or `semalt-code code -p --output-format stream-json "…"`.
-
----
-
-## Audit Log (`lib/audit.js`)
-
-Every tool execution is appended to `~/.semalt-ai/audit.log` as NDJSON:
-```json
-{"ts":"2026-01-01T00:00:00.000Z","tag":"exec","input":"{\"command\":\"ls\"}","approved":true,"result":"ok"}
+semalt-code/
+├── index.js                # Entry point: arg parsing, module wiring, command dispatch
+├── lib/
+│   ├── sdk.js              # Embedding SDK: createAgent() STABLE facade (assembles loop/registries/permissions/sandbox per-instance)
+│   ├── internals.js        # UNSTABLE building-blocks barrel (@semalt-ai/code/internals subpath; no semver guarantee)
+│   ├── api.js              # HTTP client: dashboard auth + OpenAI-compatible inference (chatStream/chatComplete/dashboard*)
+│   ├── agent.js            # Agent loop; boundToolOutput chokepoint; untrusted fencing; XML+native tuple convergence
+│   ├── commands/           # CLI + in-chat command handlers: registry (dispatch/help/completion), custom commands,
+│   │   #                     auth, mcp mgmt, oneshot (code/edit/shell/models/init), tasks, chat session/slash/turn
+│   ├── tools.js            # File + shell operation impls; agentExecShell chokepoint; secret/config path guards
+│   ├── tool_registry.js    # Per-tool registration: XML parseAttrs + native fromParams + execute + permission; git tools; web-fetch pipeline
+│   ├── tool_specs.js       # TOOL_SPECS: OpenAI-format parameter source of truth for every 'tool' tag
+│   ├── proc.js             # Platform-aware subprocess spawn + tree-kill (+ detached spawn / kill-by-PID / isProcessAlive)
+│   ├── debug.js            # Two debug modes (--debug inline / --debug-file), wired once at startup
+│   ├── prompts.js          # System prompt: tool-tag inventory + untrusted-content rules + navigation guidance
+│   ├── ui.js / ui/         # Terminal UI: raw-ANSI writer, stream renderer, status bar, diff, select, layout, web-activity collapse
+│   ├── mcp/                # boundary.js (sole CJS↔ESM bridge), client.js (manager), oauth.js (keychain provider)
+│   ├── hooks.js            # Lifecycle hooks (shell/prompt) at agent events; deny-listed + sandboxed; project command-hooks quarantined
+│   ├── verify.js           # Self-verification: run a configured command at "done", advisory/enforcing; deny-listed + sandboxed
+│   ├── checkpoints.js      # Per-write file snapshots + /rewind (code/conversation/both); turn linkage; restore-path guard re-validation
+│   ├── sandbox.js          # OS sandbox: Seatbelt/bubblewrap policy gen + wrap; resolveSandboxedSpawn shim; binary network isolation
+│   ├── skills.js           # Skills: discover SKILL.md, metadata-only injection, body on invocation
+│   ├── subagents.js        # spawn_agent tool: isolated child loop sharing parent permissions; bounded parallel
+│   ├── background.js       # Detached background-task launcher + registry (NOT an agent tool)
+│   ├── images.js           # Multimodal image input: read+size-cap+isPathSafe+base64, provider shaping, vision-capability resolution
+│   ├── web-extract.js      # Web-fetch stage 1+2: classify + Readability extract + Turndown HTML→Markdown + token cap
+│   ├── web-summarize.js    # Web-fetch stage 3: data-only untrusted-safe secondary-LLM summary
+│   ├── memory.js           # Project memory: AGENTS.md/CLAUDE.md hierarchy loader (this file)
+│   ├── headless.js         # Headless -p/--print output: text/json/stream-json
+│   ├── pricing.js          # Per-model price table → cost
+│   ├── doctor.js           # /doctor self-diagnostics: checks + aggregation
+│   ├── payload.js          # Prompt-caching + reasoning_effort payload augmentation
+│   ├── compact.js          # Conversation compaction: select/summarize/replace
+│   ├── context.js          # Loads file/directory content into the prompt
+│   ├── config.js           # Read/write ~/.semalt-ai/config.json; 4-layer merge; executable-quarantine re-resolution
+│   ├── permissions.js      # Per-session approval tracking (+ per-pattern rule resolution)
+│   ├── permission-rules.js # Pure per-pattern rule engine: schema, canonicalization, resolvePermission
+│   ├── deny.js             # Destructive-command deny-list for shell calls
+│   ├── secrets.js          # API-key sourcing: env → OS keychain → config; generic keychain helpers
+│   ├── args.js             # CLI argument parser
+│   ├── constants.js        # CONFIG_PATH, DEFAULT_CONFIG, TAG_REGISTRY ↔ TOOL_SPECS parity check, protectedConfigDirs
+│   ├── audit.js            # Append-only audit log for all tool executions
+│   ├── storage.js          # Local session persistence and resume
+│   └── metrics.js          # Token counting, cost estimation, latency tracking, split context counter
+├── scripts/lint.js         # Zero-dep lint: `node --check` over all sources
+├── test/                   # node:test suites (smoke + per-subsystem)
+├── examples/embed.js       # Runnable embedding example: createAgent + permission policy + close()
+├── package.json            # exports: '.' → sdk.js, './internals' → internals.js; bin: semalt / semalt-code
+├── package-lock.json       # committed lockfile (npm ci installs strictly from it)
+└── README.md
 ```
 
-View the last 50 entries with `semalt-code audit`. Checkpoint activity (Task 4.3) is recorded as a `checkpoint` row (`logCheckpoint`) when prior file state is snapshotted before a mutation and on rewind.
-
----
-
-## Session Storage (`lib/storage.js`)
-
-Local chat sessions are saved to `~/.semalt-ai/sessions/` as JSON files named `<timestamp>-<id>.json`. Use `/history` in-chat to browse and load any saved local session. To resume a **dashboard** chat by ID, pass `-r/--resume <chat-id>` (loaded via `dashboardGetChat`).
-
-> **Not auto-resumed.** There is no startup prompt that offers to resume the most recent session (e.g. "< 24 h old"). Resuming is always explicit — `/history` for local sessions, `--resume <id>` for dashboard chats. See **Deferred / Not Yet Implemented**.
-
----
-
-## Metrics (`lib/metrics.js`)
-
-`Metrics` is instantiated per `runAgentLoop` call and tracks per-turn token usage, latency, and total session duration. A summary box is printed on exit (SIGINT or natural quit) and after `cmdCode` runs. Use `/compact` in-chat to see the live summary.
-
-### Split context counter (Variant B, display-only)
-
-The counter shows the real measured context alongside an **estimated** base/working
-breakdown. The API returns `usage.prompt_tokens` **pre-summed** — it never splits
-the prompt into base (system prompt + tool specs) vs working (history + tool
-results) — so the split **cannot be measured; it is estimated**.
-
-- **Both halves are `char/4` estimates from the SAME estimator** (`estimateContextSplit`
-  in `lib/api.js`), so they sum consistently — the point of **Variant B** (no
-  "real − estimate" mixing where `working` would look measured but secretly carry
-  the base estimate's error). `base = estimate(system messages) + estimate(serialized
-  tool schema)`; `working = estimate(every non-system message)` — the part that grows.
-- **The real `prompt_tokens` is the anchor of truth, shown WITHOUT a `~`.** The
-  estimated split sits alongside it with a `~` prefix. Status line format:
-  `~12k working · ~5.6k base · 17,600 / 200,000 tok (9%)` (working first; the real
-  total/limit/percent carries no `~`). The Session Summary adds an `Est. split:`
-  row under the measured `Token limit:` row.
-- **Recomputed PER REQUEST** in `chatStream`'s `finalize()` from the payload
-  ACTUALLY sent (`trimmedMessages` post-retry + `payload.tools`), so it stays
-  correct when MCP connects, plan mode toggles (`PLAN_MODE_NOTICE`), or dynamic
-  tools change the base mid-session — never a frozen value.
-- **XML mode:** `payload.tools` is absent (tools are embedded in the system prompt
-  string), so estimating the actual system message still captures the tool weight —
-  the base is **never silently zero**.
-- **Threading:** attached to the `chatStream` result as `context_estimate`
-  (`{ base, working }`) → `metrics.endTurn(usage, model, contextEstimate)` (stored
-  per turn, exposed via `contextBaseEst()`/`contextWorkingEst()`) → `onMetricsUpdate`
-  (`baseEst`/`workingEst`) → `statusBar.updateMetrics`/`_buildTokenField`.
-- **Headless/JSON/SDK:** `usageFromMetrics` (`lib/headless.js`) adds **additive**
-  `context_base_est` / `context_working_est` fields (last turn) — the existing real
-  `prompt_tokens`/`total_tokens`/`context_tokens` fields are unchanged.
-- **Display-only:** changes nothing about what's sent to the model or what's
-  counted; it just shows the existing real total split into an honest estimated
-  breakdown. Tested by `test/context-split.test.js` (estimator base/working +
-  sum-consistency + XML-no-tools + per-request recompute incl. MCP-tools-grow and
-  plan-mode-notice; Metrics store/expose; status-line format with `~` on estimates
-  and none on the real total; additive headless fields with no envelope regression).
-
----
-
-## API Client (`lib/api.js`)
-
-Handles two distinct concerns:
-
-**Inference** (OpenAI-compatible):
-- `chatStream(messages, model, opts)` → streams tokens, calls `onToken`, returns `{ content, usage }`
-- URL: `config.api_base` normalized to include `/v1` if missing
-- Supports `reasoning_content` field for extended-thinking models
-
-**Dashboard** (cli.semalt.ai backend):
-- `requestCliLogin()` → `POST /api/auth/cli/request`
-- `getCliLoginStatus(id, token)` → `POST /api/auth/cli/status`
-- `dashboardWhoAmI()` → `GET /api/auth/me`
-- `dashboardLogout()` → `POST /api/auth/logout`
-- `dashboardListModels()` → `GET /api/models`
-- `dashboardGetModelForCli(id)` → `GET /api/models/{id}/cli`
-- `dashboardCreateChat(title, modelDbId)` → `POST /api/chats`
-- `dashboardListChats()` → `GET /api/chats`
-- `dashboardGetChat(id)` → `GET /api/chats/{id}`
-- `dashboardSaveMessages(chatId, messages)` → `POST /api/chats/{id}/messages/batch`
-- `dashboardSearch(query, { count })` → `POST /api/search` (SearXNG-backed web search, Task W.2b; backs the `web_search` tool)
-
-All dashboard calls send `Authorization: Bearer <auth_token>` from config.
-
 ---
 
-## Config File (`~/.semalt-ai/config.json`)
-
-Managed by `lib/config.js`. Normalized on every load. The config directory is created automatically if it does not exist.
+## Invariants the agent must not violate
+
+These are load-bearing. Each was verified against the code at the cited `file:line`.
+Do not weaken them; when adding code, preserve them.
+
+1. **CommonJS only.** All files use `require()`/`module.exports`, never ES
+   `import`/`export`. The **sole** exception is the dynamic `import()` inside
+   `lib/mcp/boundary.js` — the one bridge to the ESM-only MCP SDK. Do not migrate
+   the project to ESM. (`lib/mcp/boundary.js:41,42,92,105,113`.)
+
+2. **Tool output enters context ONLY via `boundToolOutput`** (`lib/agent.js:478`).
+   It applies `capToTokens` (per-path budget) and, when `fenced`, the untrusted
+   fence. grep/glob, shell, read_file, MCP, subagent, http_get, web_search all
+   route through it (`lib/agent.js:546,568,625,691,732,742,865,882`). **A new tool
+   gets bounding by routing its output through this chokepoint — not by remembering
+   to cap.**
+
+3. **XML and native tool paths converge on one normalized `[action, ...opts]`
+   tuple, and guards act there.** Native (`mapInvokeToCall`) and XML
+   (`extractToolCalls`) both produce the same `call` tuple, executed in one loop;
+   `permissionManager.resolveRule(call)` and the deny gate act on the tuple, so one
+   guard covers both rails (`lib/agent.js:1304,1315,1603,1656,1661`).
+
+4. **Untrusted-content fence.** Output from `http_get` / `web_search` / MCP /
+   subagent / hook / verify is wrapped in
+   `<<<UNTRUSTED_EXTERNAL_CONTENT … >>> … <<<END_UNTRUSTED_EXTERNAL_CONTENT>>>`
+   (`lib/agent.js:475-476`, `lib/hooks.js:55-56`, `lib/verify.js`). The system
+   prompt instructs the model to treat it as DATA and **never** act on instructions
+   inside it (`lib/prompts.js:80-82`). The secondary web-summarizer treats the page
+   as data-only too — a page could have steered it.
+
+5. **Destructive-command deny-list at the single `agentExecShell` chokepoint.**
+   Every exec/shell — including native git tools (via `_runGit` → `ctx.agentExecShell`),
+   lifecycle hooks, and self-verify — funnels through `agentExecShell` (`lib/tools.js:239`)
+   which runs `classifyShellCommand` (`lib/deny.js:184`). **Agent-initiated** deny
+   hits **hard-block**; **user-initiated** (`!cmd`) only confirm the catastrophic
+   subset. Only `--dangerously-skip-permissions` bypasses classification.
+
+6. **The agent can never disable the OS sandbox or widen the network.** No
+   tool/flag/config the *model* can reach turns the sandbox off or flips
+   no-network back to network — only human CLI flags (`--dangerously-skip-permissions`,
+   `--no-network`) or the human-edited `sandbox.*` config. Network is **binary**
+   (on / kernel-level none — `--unshare-net` / Seatbelt `(deny network*)`); no host
+   proxy / allowlist / TLS interception. Protected config + secret dirs (`~/.semalt-ai`,
+   `~/.ssh`/`~/.aws`/`~/.gnupg`, `/etc`, every project `.semalt` dir) are bound
+   **read-only inside the jail, including not-yet-existing files**
+   (`lib/sandbox.js:59-64,107-116,131-134,382-385,449-452`; `lib/constants.js:328-341`).
+
+7. **Project config can only NARROW.** `.semalt/config.json` is attacker-controllable
+   (cloned repos). Permission rules, hooks, and verify are loaded as **separate**
+   user/project layers (not the shallow-merged view): project `allow` rules are
+   dropped before resolution, and project **command** hooks + `verify.command` are
+   **quarantined** (only inert prompt text survives from a project)
+   (`lib/permission-rules.js:226-231,367-370`; `lib/hooks.js:114-131`;
+   `lib/verify.js:213-222`; `lib/config.js:360-376`).
+
+8. **Secret-file read guard + config-write guard.** File tools refuse reads of
+   protected secret files (`isProtectedSecretPath`) and writes into `~/.semalt-ai`
+   + project `.semalt` dirs (`isProtectedConfigPath`), **including not-yet-existing
+   files**. Neither is overridable by `--allow-anywhere` — only by
+   `--dangerously-skip-permissions` (`lib/tools.js:85-89,109-119`;
+   `lib/constants.js:328-341`).
+
+9. **Permissions are per-session, never persisted.** `PermissionManager` is created
+   fresh per invocation with in-memory state; approvals never hit disk. In **non-TTY**
+   mode, calls needing interactive confirmation are **refused** (not auto-approved)
+   unless an `--allow-*` tier pre-approved the tag or `--dangerously-skip-permissions`
+   is set (`lib/permissions.js:29,38-41,221-236,292-295`).
+
+10. **Tool-tag names stay in sync across all three surfaces.** A load-time parity
+    check (`assertToolSpecParity`, `lib/constants.js:449-492`) asserts
+    `TAG_REGISTRY` ↔ `TOOL_SPECS` ↔ `TOOL_REGISTRY` and that every entry has both an
+    `execute` and a `permission`. The `agent.js` parser and `prompts.js` inventory
+    both consume `TAG_REGISTRY`. **Rename a tag atomically in `prompts.js`,
+    `agent.js`, `tool_specs.js`, and the registry** or the parity check throws at load.
+
+11. **Checkpoints/rewind cover file-tool mutations ONLY.** `CHECKPOINTABLE_ACTIONS`
+    (`lib/checkpoints.js:62-65`) = write/append/edit_file/replace_in_file/delete_file/
+    move_file/copy_file/upload. **Shell side effects and git discards (`git_checkout`)
+    are NOT reversible** — do not imply `/rewind` covers them. Rewind is
+    **human-only**: there is **no rewind tool** in the static/dynamic registry,
+    `TOOL_SPECS`, or `TAG_REGISTRY` (`/rewind` and `semalt-code rewind` are the only
+    entries).
+
+12. **Subagents/MCP grant no privilege escalation.** A subagent shares the **parent's**
+    `permissionManager` (cannot auto-approve what the parent wouldn't) and **cannot
+    recurse** (`spawn_agent` is refused/dropped for children). MCP tools **require
+    approval by default** (opt-in per server). Both subagent and MCP results are
+    **untrusted-fenced and token-capped** before entering context (MCP 10k stricter,
+    subagent 20k generous) (`lib/subagents.js:186,297-299,328`; `lib/mcp/client.js:105-110`;
+    `lib/constants.js:130-131`).
+
+13. **Minimal, pinned dependencies.** Prefer Node built-ins. Any runtime dep must be
+    minimal, justified, **exact-pinned** (no `^`/`~`), and reviewed, with the
+    regenerated `package-lock.json` committed in the same PR. Today: only the four
+    listed in Tech Stack, all exact-pinned (`package.json`). See `docs/HISTORY.md`
+    for the supply-chain policy and rationale.
+
+---
+
+## Build / Run / Test / Lint / Publish
 
-```json
-{
-  "api_base":            "http://127.0.0.1:8800",
-  "api_key":             "any",
-  "dashboard_url":       "https://cli.semalt.ai",
-  "auth_token":          "",
-  "default_model":       "default",
-  "dashboard_model_id":  null,
-  "temperature":         0.7,
-  "request_timeout_ms":  900000,
-  "stream":              true,
-  "theme":               "dark",
-  "max_file_size_kb":    51200,
-  "read_line_cap":       2000,
-  "read_max_tokens":     25000,
-  "command_timeout_ms":  30000,
-  "max_output_lines":    50,
-  "max_output_tokens":   10000,
-  "max_iterations":      50,
-  "show_token_count":    true,
-  "show_cost":           false,
-  "context_length":      null,
-  "models": [
-    {
-      "name":           "local-llama",
-      "api_base":       "http://127.0.0.1:11434",
-      "api_key":        "any",
-      "model":          "llama3",
-      "context_length": 8192
-    }
-  ]
-}
+```bash
+node index.js chat        # run locally (interactive chat)
+npm test                  # node --test (the test/ suite)
+npm run lint              # node --check over all sources (zero-dep lint)
+npm link                  # symlink for global use during dev
+npm publish --access public   # publish to npm (bump package.json version first)
 ```
 
-- `api_base` is normalized to always include `/v1`.
-- Legacy key `semalt_base_url` is migrated to `api_base` on load.
-- `auth_token` is written by `semalt-code login` and cleared by `logout`.
-- `dashboard_model_id` is the integer PK of the active model in `available_models`; written when a model is selected via `/models`. Required for chat history sync — if null, history sync is silently skipped.
-- `max_file_size_kb` is the `read_file` **byte backstop** (Task W.7; default raised to **50 MB** = 51200 KB). It is **no longer the primary bound** — a large line-readable file **paginates** (`read_line_cap`) rather than hard-refusing; this ceiling only rules out slurping a multi-GB file whole into memory. Lower it to hard-refuse smaller files.
-- `read_line_cap` (Task W.7) caps the lines `read_file` returns per page and the width of an explicit `start_line` window (default 2000). Over the cap, the result carries a `[PARTIAL]` notice with the total and the next `start_line`.
-- `read_max_tokens` (Task W.7) is the token safety net on a `read_file` page (default 25000) — bounds the pathological few-but-enormous-lines case the line cap misses, reusing the web pipeline's `capToTokens`.
-- `command_timeout_ms` caps shell command execution time (default 30 s).
-- `max_output_lines` caps the lines of shell/exec output that enter the model context (default 50), applied as a **head+tail** split (Task W.6 — first ~60% + last ~40%, middle elided) at the context boundary, not just in the UI. Also caps the UI render and HTTP response lines.
-- `max_output_tokens` is the token safety net on shell/exec output entering context (default 10000; Task W.6) — bounds the few-but-huge-lines case the line cap misses. Applied after the line cap via the web pipeline's `capToTokens`.
-- `download_max_bytes` caps how many bytes the `download` tool may stream to disk (default 100 MB). Exceeding it aborts the request and removes the partial file, so no truncated artifact is left behind.
-- `web` — normalized to `{ summarize, summary_model, max_content_tokens, user_agent }` (Task W.1 / W.1b / W.3). The `http_get` web-fetch pipeline: `summarize` (default **true**) sets the default `mode` (`summarized` when true, `extracted` when false) — a secondary cheap-LLM summary of the extracted Markdown so only the compact result enters context. Override per-fetch with `mode="extracted"` (verbatim Markdown; deprecated aliases `summarize="false"`/`raw="true"`) or `mode="raw"` (original token-capped HTML/content, for markup/CSS/JS analysis). `summary_model` (`''` → current model) is the cheap model for that call. `max_content_tokens` (default 6000) caps the content fed to the summarizer/context **in every mode incl. raw** — the token-budget that **replaces** the blind `http_fetch_max_bytes` cut as context protection (the byte cap is now only a transfer guard). `user_agent` (Task W.3 Part 2; `''` → the fixed `DEFAULT_USER_AGENT`, a current mainstream-browser string) is the **operator override** for the `http_get`/`download` User-Agent — a **human-only** setting (there is **no UA parameter in the tool spec**, so the agent can never set a per-call UA, an impersonation/evasion surface we deliberately don't expose). A realistic UA defeats only **simple** UA-based bot-blocking (sites that 403/406 an empty/curl-like UA); Cloudflare / JS-challenges / IP-rate-limits still 403 — full coverage would need headless rendering (deferred). See **Web Fetch Pipeline** above.
-- `image_max_bytes` caps the **raw** bytes of an attached image before base64-encoding (default 5 MB; base64 inflates ~33%). Over the cap is a clear error, not an opaque endpoint rejection. `image_format` (`''`|`anthropic`|`openai`) forces the provider content-part shape; `''` selects it heuristically per endpoint. Per-`models[]`-profile `vision` (bool) and `image_format` override for that profile. See **Multimodal Image Input** above (Task 5.4).
-- `max_iterations` caps agent-loop iterations per user turn (default 50; `DEFAULT_MAX_ITERATIONS` in `constants.js`). A positive integer caps the loop; `0` (the stored "unlimited" sentinel — config.json can't hold `Infinity`) removes the cap. `--max-iterations <n>` overrides it (accepts `0`/`unlimited`); entry points resolve the value via `resolveMaxIterations()`. Reaching the cap stops the loop gracefully (warning + `stopReason: "max_iterations"`).
-- `show_token_count` controls whether token count is shown in the status bar.
-- `show_cost` reserved for future cost-display feature.
-- `context_length` / `models[].context_length` — token limit used for context-usage bar, warnings, and proactive trimming. Self-calibrating: when a request triggers a context-overflow 400 (`"context length is only N"`), `api.js` parses the real window, persists it to `config.context_length` (and to the matching `models[]` entry), and trims to ~90% of it on subsequent calls. The value is never cached in memory only — a restart keeps the learned limit.
-- Local `models[]` entries override dashboard models when selected.
-- `mcp` — normalized to `{ servers: {}, max_result_tokens }`. `servers` maps a server name → its launch/connection spec (transport, command/args/env/cwd or url/headers/oauth, allow/allowAll, disabled). Empty by default; no MCP server is connected until a user adds an entry. `max_result_tokens` (Task W.8, default **10000**) is the **stricter** token cap applied to an MCP tool result before it enters context (third-party / untrusted) — applied inside the untrusted fence. Consumed by the MCP client (`lib/mcp/client.js`, Task 3.3) and `formatMcpResult` (`lib/agent.js`) — see **MCP Client** above.
-- `hooks` — normalized (`normalizeHooks` in `lib/hooks.js`) to a map with one array per known event (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`). Each entry is `{ type: "command"|"prompt", command|prompt, matcher?, timeout_ms? }`. Empty by default. Consumed by the agent loop — see **Lifecycle Hooks** above. **NOTE (Pre-Task 5.0a):** `loadConfig` re-resolves hooks from the user/project layers SEPARATELY (`loadHookLayers`) and quarantines project-layer **command** hooks (a cloned repo can only add **prompt** hooks) — this shallow-merged value is not the executable security path.
-- `subagents` — normalized to `{ max_concurrency, max_result_tokens }` (defaults 3 (clamped 1–16) / 20000). `max_concurrency` bounds the parallel-execution pool for the `spawn_agent` tool; `max_result_tokens` (Task W.8, default **20000**) is the **generous** token cap on a subagent's final text before it enters the parent context (a safety net against a verbose child, strictly larger than the MCP cap). See **Subagents** above.
-- `permissions` — normalized (shape-only) to `{ rules: [] }`. Per-pattern permission rules (`{ tool, action, and one of pattern|path|url|match }`). **Enforcement reads the user and project layers SEPARATELY** via `loadRuleLayers` (`lib/permission-rules.js`) — the merged `config.permissions` here is display/normalization only — because the project layer can only **narrow** the user posture, never widen it. See **Per-Pattern Permissions** above.
-- `checkpoints` — normalized (`normalizeCheckpoints` in `lib/checkpoints.js`) to `{ enabled, max_file_bytes, max_per_session }`. Per-write file snapshots under `~/.semalt-ai/checkpoints/<session>/` powering `/rewind`. Enabled by default; `max_file_bytes` (5 MB) is the per-file snapshot cap (oversize → rewind unavailable, not disk exhaustion); `max_per_session` (100) is the retention cap (oldest pruned). File-tool changes only — shell side effects are not reversible. See **Checkpoints & Rewind** above.
-- `sandbox` — normalized (`normalizeSandbox` in `lib/sandbox.js`) to `{ mode, failIfUnavailable, network }`. OS-level filesystem **+ binary network** sandbox for shell commands (Seatbelt on macOS, bubblewrap on Linux/WSL2). `mode` `auto` (default — jail when available) or `off` (a **human-only** opt-out the agent can never set); `failIfUnavailable` makes a missing/unusable sandbox a hard error instead of a human-approval fallback; `network` `on` (default — sandboxed commands keep normal egress) or `off` (kernel-level no-network: `--unshare-net` / Seatbelt `(deny network*)`; also via the `--no-network` flag). **Binary on/off — no host proxy, no domain allowlist, no TLS interception.** Anti-fail-open: a present-but-malformed `network` value resolves to `off`, never silently to network. See **OS Sandbox** above.
-- `verify` — normalized (`normalizeVerify` in `lib/verify.js`) to `{ mode, command, timeout_ms, expected_exit_code, max_attempts }`. Self-verification: when the agent declares a task done, optionally run `command` and feed the result back. `mode` advisory (default) never blocks; `enforcing` returns the agent to the loop on a failing verify, bounded by `max_attempts` (default 3) then `stopReason: "verify_failed"`. Empty `command` → no-op; `--no-verify` skips for one run. Success is exit-code based (`expected_exit_code`, default 0). See **Self-Verification** above. **NOTE (Pre-Task 5.0a):** `loadConfig` re-resolves verify from the user/project layers SEPARATELY (`loadVerifyLayers`) and quarantines a project-layer `verify.command` — the effective command can only come from the trusted user layer.
-
-### Config hierarchy (Task 2.2)
-
-`loadConfig()` merges four layers, lowest to highest precedence:
-
-1. **User** — `~/.semalt-ai/config.json`
-2. **Project** — `.semalt/config.json`, the nearest one found by walking up from the CWD to the repo root (the directory holding `.git` is the last checked)
-3. **Environment** — `SEMALT_API_BASE` → `api_base`, `SEMALT_MODEL` → `default_model`, `HTTPS_PROXY`/`HTTP_PROXY` → `https_proxy`/`http_proxy`. **Proxy intent is parsed and exposed in config, but not yet consumed:** `api.js` does **not** route requests through a proxy agent, so setting `HTTPS_PROXY`/`HTTP_PROXY` currently has **no effect on outbound HTTP** (relevant on corporate networks). Proxy consumption is a **deferred** item — see **Deferred / Not Yet Implemented**.
-4. **CLI flags** — `--api-base`, `--api-key`, `--dashboard-url`, `--default-model`
-
-The merge is a pure function (`mergeConfigLayers`) with each layer produced by a pure extractor (`envConfigLayer`, `flagsConfigLayer`, `loadProjectConfig`), so every combination is unit-testable. **API-key sourcing is NOT part of this merge** — it stays in `lib/secrets.js` (`SEMALT_API_KEY` env → OS keychain → `config.api_key`), preserving the Phase 0 precedence.
-
-**Persistence is user-file-only.** `configSet` writes against the user file, and the runtime `setConfig`/learned-context-length persistence rebases through `userLayerForPersist` — only keys a caller actually changed land in `config.json`, so a project/env/flag override is never baked into the user's global config.
-
----
-
-## Key Patterns & Invariants
-
-- **Minimal, pinned dependencies**: prefer Node.js built-ins; a runtime dependency must be minimal, justified, pinned to an exact version, and reviewed (see **Dependency & Supply-Chain Policy**). Today: `@modelcontextprotocol/sdk` (MCP) and the web-extraction set `@mozilla/readability` + `linkedom` + `turndown` (Task W.1).
-- **CommonJS**: all files use `require()`/`module.exports`. Do not use ES `import`/`export`. The one exception is the **dynamic** `import()` inside `lib/mcp/boundary.js`, which is the sole bridge to the ESM-only MCP SDK — the project itself stays CommonJS.
-- **Streaming**: `api.js` manually parses `text/event-stream`. The parser in `chatStream()` handles partial JSON lines — be careful editing it.
-- **Permissions are per-session**: `PermissionManager` resets on each CLI invocation. Approvals never persist to disk. In non-TTY mode tool calls that would normally need interactive confirmation are **refused** (not auto-approved) unless `--dangerously-skip-permissions` is set, or the tag is pre-approved by an `--allow-*` tier flag.
-- **Destructive-command deny-list** (`lib/deny.js`): every shell call (`exec`/`shell`) passes through `classifyShellCommand()` at the single chokepoint in `agentExecShell`, in *all* modes and regardless of `--allow-*` flags. Handling depends on the **initiator**:
-  - **Agent-initiated** (the model asked, the default): any deny-list hit is a **hard block** — `rm -rf`, `curl … | sh`, disk-wipe/fork-bomb patterns, recursive chmod/chown on a system root, and writes to system paths.
-  - **User-initiated** (a human typed `!cmd` or `semalt-code shell`): the user owns their machine, so a deny-list hit is **not** hard-blocked. The exception is the **catastrophic subset** (`catastrophic: true` — disk-wipe / block-device write, fork bomb), which interposes a single y/N confirmation as a typo guard; all other deny-listed user commands run with a `bypassed` note.
-  - The only full bypass (skips classification entirely) is `--dangerously-skip-permissions`.
-  - **Cross-platform + canonicalized (Task 4.4):** the list now covers the
-    **Windows** destructive set (`del /s`, `rd`/`rmdir /s`, `Remove-Item -Recurse
-    -Force`, `format`, `Format-Volume`, `Clear-Disk`, `cipher /w`, `diskpart …
-    clean`) in addition to POSIX — relevant because native Windows has no OS
-    sandbox. Matching also runs against a **procfs-root-canonicalized** variant
-    (`/proc/self/root` and `/proc/<pid>/root` rewritten to `/`) so a
-    `/proc/self/root/etc/…` bypass is caught by the same system-path matchers
-    (the resolved-path principle, shared with the OS sandbox).
-- **Untrusted web content**: `http_get` runs the **web-fetch pipeline** (Task W.1 / W.1b, `mode` = summarized→extract→Markdown→secondary-LLM summary / extracted→Markdown / raw→original token-capped content) so by default only a compact result enters context (`raw` mode deliberately returns the original markup, still **token-capped**, for page analysis); the result in **every** mode is wrapped in the explicit `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` block (`lib/agent.js`), and the secondary summarizer treats the page as data-only (a page injection could have steered it). The system prompt (`lib/prompts.js`) instructs the model never to act on instructions inside such a block. MCP tool results and **lifecycle-hook output** reuse the same fence. See **Web Fetch Pipeline**.
-- **Lifecycle hooks are deny-listed + sandboxed shell + untrusted output** (`lib/hooks.js`): a `PreToolUse` non-zero exit blocks the tool; every hook command passes through `checkShellDenylist` AND the **OS sandbox** (`resolveSandboxedSpawn`, Pre-Task 5.0a) before running; hook stdout is fenced as untrusted before it reaches the model; timeouts/sandbox-refusals/failures are contained and never crash the loop. **Project-layer command hooks and `verify.command` are quarantined** (`loadHookLayers`/`loadVerifyLayers`): a cloned-repo `.semalt/config.json` can never introduce host-privileged execution, only inert prompt text.
-- **`--readonly` blocks every file-mutating tool** (`READONLY_BLOCKED`, `lib/permissions.js`, completed in Pre-Task 5.0c): `write_file`, `append_file`, `edit_file`, `replace_in_file`, `delete_file`, `make_dir`, `remove_dir`, `move_file`, `copy_file`, `upload`, `download`. The block is enforced at the executor (`permissionManager.readonlyBlock(tag)`), so it holds for both the XML and native paths; `describePermission` also short-circuits the gate (no approval prompt precedes the deterministic block). **Scope decision (load-bearing): `--readonly` governs FILE TOOLS only.** Shell (`exec`/`shell`) is **not** in the set — a read-only session must still run read-only commands (`ls`, `git status`), and a shell command's arbitrary write side effects are the **OS sandbox + deny-list's** job to confine (the right layer post-Pre-Task 5.0a), not `--readonly`. So `--readonly` is an honest "no file-tool writes," not a false "no writes at all." Read-only file tools (`read_file`, `grep`, `glob`, `search_in_file`, `file_stat`, `list_dir`) work unchanged. Tested by `test/readonly-tools.test.js`.
-- **Secret-file read guard**: `isProtectedSecretPath()` in `tools.js` refuses reads/copies/moves of `config.json`, `memory.json`, and `audit.log` via file tools — **not** overridable by `--allow-anywhere` (only by `--dangerously-skip-permissions`).
-- **Config-write guard** (`isProtectedConfigPath()` in `tools.js`, Pre-Task 5.0b): the write-side companion to the read guard. Every write executor (`write_file`, `append_file`, `edit_file`, `replace_in_file`, `move_file`/`copy_file` **dst**, `upload`, `download`) refuses to write into the **protected-config set** — the whole `~/.semalt-ai` dir **and** every project `.semalt` dir from the CWD up to the repo root, **including files that do not yet exist** (directory-prefix matched on the resolved path, so a missing `.semalt/config.json`/`agents/*.md`/hook is covered). The set is defined once as `protectedConfigDirs` (`lib/constants.js`) and shared with the OS sandbox's `protectedPaths`. Same bypass policy as the read guard: **not** overridable by `--allow-anywhere`, only by `--dangerously-skip-permissions` (human-only). This guards the **agent's** file tools and the sandboxed shell — a human editing their own config in an editor is unaffected. Tested by `test/config-write-guard*.test.js`, `test/path-guards.test.js`, and the kernel case in `test/sandbox-integration.test.js`.
-- **Per-pattern permission rules** (`lib/permission-rules.js`, Task 4.1): allow/deny/ask rules matching tool + argument (glob/regex), layered user→project. **Project rules can only NARROW** — every project `allow` is structurally dropped before resolution, so a cloned-repo `.semalt/config.json` can never widen the user posture. Precedence is total/deterministic (deny>ask>allow, most-specific then most-restrictive). Arguments are canonicalized (`..`/symlink/abs-rel) before matching; pathological/malformed rules fail closed; an `allow` never bypasses the deny-list, secret guard, `--readonly`, or `isPathSafe` (those stay in the executors). A `deny` rule holds even under `--dangerously-skip-permissions`. See **Per-Pattern Permissions** above.
-- **Checkpoints & rewind** (`lib/checkpoints.js`, Task 4.3 / 4.3b): before each file-tool mutation the file's prior state is snapshotted (post-gate, pre-mutation, in `agentExecFile`) so `/rewind` can restore it — **file-tool changes only; shell side effects are not reversible.** Capture is fail-safe (a snapshot failure never blocks the mutation); a denied/withheld call produces no checkpoint; subagent mutations are checkpointed into the parent session. Delete/move are reversed explicitly; an external-modification check warns/asks before clobbering out-of-band edits. A per-file size cap and per-session retention are enforced. **Rewind is human-only (no rewind tool in the registry).** Task 4.3b: the restore path **re-validates the current guards** (`isPathSafe`/secret/protected-config/`deny` rule) per target — a now-forbidden path is refused/skipped, and `force` overrides only the external-mod check, not the guards; **three restore modes** `code`/`conversation`/`both` (default both) restore files, history, or the linked state, with conversation truncation cutting on **turn boundaries** (no orphaned `tool_call`; discard policy) — all on the **unchanged** on-disk schema. See **Checkpoints & Rewind** above.
-- **Native git tools** (`lib/tool_registry.js`, Task 5.1): eight first-class git tools shelling out through the **same** `agentExecShell` sandbox + deny-list chokepoint as `<shell>` (no privileged path around confinement), parsing output into structured results. Read-only (`git_status`/`git_diff`/`git_log`, plus the *list* ops of `git_branch`/`git_worktree`) return a null permission descriptor; mutating (`git_add`/`git_commit`/`git_branch`/`git_checkout`/`git_worktree` add/remove) require approval, honor `--readonly`, and pass the per-pattern rules. `git_commit` requires a real non-empty message (empty → error, never a placeholder). **Destructive-git ↔ checkpoint honesty:** git operations are NOT reversible via `/rewind` (checkpoints snapshot file-tool mutations only) — stated in the descriptions and prompt text. Not-a-repo / git-absent degrade gracefully. See **Native Git Tools** above.
-- **API-key sourcing** (`lib/secrets.js`): precedence is `SEMALT_API_KEY` env → OS keychain (macOS `security` / Linux `secret-tool` / Windows PasswordVault) → `config.json`. Keys from env/keychain are never written back to config; `configShow` reports only `api_key_source`. Store a key with `semalt-code auth set-key`.
-- **Token counting is approximate**: `estimateTokens()` divides char count by 4. It is used only for the `/compact` display — do not rely on it for hard limits.
-- **Context trimming is proactive when a limit is known**: `chatStream()` uses the in-process `_sessionInputLimits` learned from a prior 400 overflow first, then falls back to `config.context_length * 0.9`. When neither is set, no pre-flight trim runs and the client relies on the reactive 400/413 handler (which then persists the discovered window). `Metrics.tokenLimitStatus()` returns `{ used, limit: null }` until a limit is learned, so the status bar shows "N tok · limit unknown" instead of hiding the line.
-- **Shell/exec output entering context is bounded** (Task W.6, `capShellOutput` in `lib/agent.js`): the model-facing shell result is double-bounded — a **head+tail line cap** (`max_output_lines`, default 50, split first ~60% + last ~40% via `OUTPUT_HEAD_RATIO`) eliding the middle, **then** a **token safety net** (`max_output_tokens`, default 10000, reusing the web pipeline's `capToTokens`) so a few enormous lines (minified JS, a binary `cat`) can't blow context. The elision notice teaches the W.5-enabled redirect-to-file→grep pattern. **The exit code stays on its own line, so truncating output VOLUME never hides the command's OUTCOME** (a non-zero exit / failure is always surfaced). Applied at the context boundary in the agent loop — distinct from the **UI** cap (`lib/ui/diff.js`, display only), which stays. Before W.6 the cap was UI-only and the model received the **entire** unbounded stdout+stderr (the #1 context risk). Pure helper, unit-tested on the model-facing text + a real-loop assertion (`test/shell-output-cap.test.js`). MCP/subagent output bounding is Task W.8 (below); W.9 unifies all the paths into a shared chokepoint.
-- **MCP & subagent results entering context are bounded** (Task W.8, `formatMcpResult`/`formatSubagentResult` in `lib/agent.js`): the last two unbounded paths. Both apply `capToTokens` (the W.5–W.7 standard) to the result text **before** wrapping it in the `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` fence, with **distinct budgets reflecting their nature**: **MCP is stricter** (`mcp.max_result_tokens`, default **10000**) because the payload size is third-party/server-controlled and untrusted — the riskiest path; **subagent is generous** (`subagents.max_result_tokens`, default **20000**) because the child's final text is our own deliberate, synthesized answer (a safety net against a verbose child). For MCP the truncation notice sits **inside** the fence with the capped content — capping never weakens the untrusted perimeter; subagent isolation / no-escalation (3.6/4.5) are unchanged (this bounds returned-text size only). A small result passes through fully, no notice. Pure helpers, unit-tested on the model-facing/parent-facing text incl. the fence-still-present and budgets-differ cases + real-loop assertions (`test/result-cap.test.js`).
-- **`read_file` is paginated** (Task W.7, `formatReadResult` in `lib/agent.js`): `read_file` used to dump the **whole file verbatim** into context (`File <path>:\n` + the entire content); the only guard was a hard byte refusal at `max_file_size_kb`. Worst case ~128k tokens for a 500 KB file. Now the **model-facing** result is paginated, mirroring the Claude Code standard: under a **line cap** (`read_line_cap`, default **2000**) the file reads **byte-for-byte as before** (no regression for the common small-file case); over the cap it returns the first page + a **`[PARTIAL]` notice** — `Showing lines 1–2000 of 5234. Read more with start_line=2001.` **`start_line`/`end_line`** (on both XML + native rails; absent → null, tuple parity) read an explicit slice, **also line-capped** so a huge explicit range can't dump everything. A **token safety net** (`read_max_tokens`, default **25000**, reusing the web pipeline's `capToTokens`) bounds the pathological few-but-enormous-lines case (one 100 KB minified line) the line cap misses — consistent with W.6's double-bound. The bound is applied at the **context boundary** in the formatter (the executor still returns the full content, like W.5/W.6); pagination — not the byte cap — is the primary bound, so `max_file_size_kb` is now a **backstop** (raised default **50 MB**) ruling out a multi-GB whole-file slurp (lower it to hard-refuse smaller files). **Line numbers are OPTIONAL, default OFF** (`show_line_numbers`): the **Step 0 finding** is that `edit_file` is **line-number-based** (`lines[N-1]=content`) while `replace_in_file` is **match-based** (regex on a search string) — a mix — so always-on numbers would corrupt copyable snippets for the match path **and** cost ~1.7× per read; the param turns absolute 1-based numbers on (aligned with `edit_file`'s addressing) for when the agent wants line refs to drive an edit. Line indexing matches `edit_file`'s `split('\n')` exactly, so the read→edit loop stays aligned. Pure helper, unit-tested on the model-facing text incl. the no-regression small-file case + the PARTIAL large-file case + rail parity + read→edit alignment (`test/read-paginate.test.js`).
-- **grep/glob results are serialized + bounded** (Task W.5, `formatGrepResult`/`formatGlobResult` in `lib/agent.js`): `formatFileResult` now has `case 'grep'`/`case 'glob'` that turn the structured engine result into model-facing text — closing a correctness bug where both fell through the default and the model received `"grep: done"`/`"glob: done"` (the data was computed and even shown in the UI, but never entered context, making grep-first navigation impossible). grep `output_mode` (`content`/`files_with_matches`/`count`) is model-selectable via the spec; `head_limit` (default `DEFAULT_GREP_HEAD_LIMIT`/`DEFAULT_GLOB_HEAD_LIMIT` = 100) + optional `offset` bound what reaches the model — the engine's 1000/5000 internal caps were never a context bound (the result was dropped before it reached context). Over-limit serialization carries a truncation notice telling the agent how to narrow (refine the pattern, switch to `count`/`files_with_matches`, or raise `head_limit`); under-limit results show fully with no notice. The executors (`lib/tool_registry.js`) normalize and attach `output_mode`/`head_limit`/`offset` onto the result; the serializers are pure and tested on the **model-facing** text (`test/grep-glob-serialize.test.js`, incl. the real-loop regression).
-- **Tool output enters context ONLY via the `boundToolOutput` chokepoint** (Task W.9, `lib/agent.js`): the size analogue of the `resolveSandboxedSpawn` sandbox chokepoint. W.5–W.8 each bounded a previously-unbounded path, but the `capToTokens`-+-fence step was duplicated ad-hoc in five places — the original bugs (grep/glob `"done"`, shell/MCP/subagent unbounded) were all the **same class**: a path that put output into context without bounding it. `boundToolOutput(text, { budget, notice, fenced })` is the **single application point**: it applies `capToTokens` with the path's **budget** and **notice** function and (when `fenced`) wraps in the `<<<UNTRUSTED_EXTERNAL_CONTENT>>>` fence. **grep/glob, shell, read_file, MCP, subagent — and http_get/web_search — all route through it.** The per-path policy is **deliberately distinct and NOT flattened**: budgets (MCP 10k < subagent 20k < read 25k; shell 10k; grep/glob `DEFAULT_GREP_GLOB_MAX_TOKENS` 10k — a new token net so a few huge minified match lines can't blow context, the W.6 lesson applied to grep's count-bound), notice wording (shell teaches redirect→grep, read teaches narrow-the-range, …), and the fence flag (MCP/subagent/web fenced; file/shell not). **Refactor-safe:** model-facing outputs are byte-identical to W.5–W.8 (the W.5–W.8 test suites pass unchanged); http_get/web_search bodies are already token-capped upstream so they pass **no budget** (fence only). **Structural regression prevention:** a new tool gets bounding by *routing* its output through the chokepoint, not by *remembering* to cap. Pure helper, unit-tested on the chokepoint behavior, per-path policy, the bound-by-construction invariant, and equivalence (`test/output-chokepoint.test.js`). The system prompt's `LOCAL_NAVIGATION_NOTICE` (`lib/prompts.js`, both templates) — now actionable post-W.5 — steers the grep-first / read-slice pattern: locate with `grep`/`glob` (`count`/`files_with_matches` modes), then `read_file` only the relevant `start_line`/`end_line` slice; redirect large command output to a file and grep it.
-- **Bounded agent iterations**: the primary loop caps at `config.max_iterations` (default 50, via `DEFAULT_MAX_ITERATIONS` in `constants.js`), overridable with `--max-iterations <n>`; `--max-iterations 0`/`"unlimited"` removes the cap deliberately. Reaching the cap stops gracefully (clear message + `stopReason: "max_iterations"`), never silently. Subagents have their own cap of 12.
-- **Malformed tags are skipped**: each tool dispatch in the agent loop is wrapped in try/catch; errors emit a warning line and continue to the next tool call.
-
----
-
-## Deferred / Not Yet Implemented
-
-This section exists because false documentation has burned this project before (a
-"max 10 iterations" invariant that never existed; coverage assumed but absent). The
-items below are things a reader might reasonably expect from the docs or from peer
-tools but that the code **does not do today**. They are listed honestly so nobody
-builds on a feature that isn't there. Each is marked **Planned (Phase 4+)** —
-on the roadmap — or **Out of scope** — no current plan.
-
-**Gaps the re-audit found in existing behavior:**
-
-- **MCP in headless / one-shot** — *Planned (Phase 4+).* `connectAll()` runs only in
-  interactive `cmdChat` (and the `mcp` management commands); `code`/`edit`/`shell`/`-p`
-  never connect a manager, so MCP tools are unavailable there. See **MCP Client → Scope**.
-- **Session auto-resume** — *Planned (Phase 4+).* Sessions are saved, but there is no
-  startup prompt offering to resume the most recent (< 24 h) session. Resume is always
-  explicit: `/history` (local) or `--resume <id>` (dashboard). See **Session Storage**.
-- **Corporate-proxy consumption** — *Planned (Phase 4+).* `HTTPS_PROXY`/`HTTP_PROXY`
-  are parsed into config but `api.js` does not route requests through a proxy agent,
-  so they have no effect on outbound HTTP. See **Config hierarchy → Environment**.
-
-**Phase 4 roadmap (Planned, in the stated order):**
-
-- **Per-pattern permissions** — ✅ **Done (Task 4.1).** Rich allow/deny/ask rules
-  matching tool + argument (glob/regex), layered user→project. See **Per-Pattern
-  Permissions** above.
-- **Self-verification** — ✅ **Done (Task 4.2).** When the agent declares done,
-  optionally run a configured verify command (advisory feeds the result back;
-  enforcing returns the agent to the loop until verify passes, bounded by
-  `max_attempts` → `verify_failed`). See **Self-Verification** above.
-- **Checkpoints / rewind** — ✅ **Done (Task 4.3 file half + Task 4.3b
-  conversation + restore re-validation).** Per-write file snapshots before each
-  file-tool mutation; `/rewind` restores prior content (last or to a chosen
-  sequence), with delete/move handled and an external-modification check that never
-  silently clobbers out-of-band edits. **File-tool changes only — shell side
-  effects are not reversible.** Task 4.3b closed the last deferred 4.3 security
-  finding (the restore path now **re-validates the current
-  isPathSafe/secret/protected-config/`deny`-rule guards** per target — `force`
-  overrides only the external-mod check) and added **three restore modes**
-  (`code`/`conversation`/`both`, default both) using the existing turn-linkage,
-  with conversation truncation cutting on **turn boundaries** (no orphaned
-  `tool_call`; discard policy) on the **unchanged** on-disk schema. Rewind stays
-  **human-only** (no rewind tool registered). See **Checkpoints & Rewind** above.
-- **OS sandbox** — ✅ **Done (Task 4.4 filesystem + Task 4.4b network).** Real
-  OS-level confinement for shell commands: Seatbelt (macOS) / bubblewrap
-  (Linux/WSL2) jail every command and its children, confining writes to the working
-  dir and keeping `~/.semalt-ai`/secrets/`/etc` read-only (incl. not-yet-existing
-  files), with a fail-safe ask-or-block fallback when the primitive is absent and no
-  model-reachable way to disable it. **Network isolation is now done as well —
-  binary on/off** (bwrap `--unshare-net` / Seatbelt `(deny network*)`), no host
-  proxy / no domain allowlist / no TLS interception, anti-fail-open default. See
-  **OS Sandbox** above.
-
-**Done since:**
-
-- **Native git tooling** — ✅ **Done (Task 5.1).** Eight first-class git tools
-  (`git_status`/`git_diff`/`git_log` read-only; `git_add`/`git_commit`/`git_branch`/
-  `git_checkout` mutating; `git_worktree` infrastructure) shelling out through the
-  sandbox + deny-list chokepoint with structured results. The long tail stays in the
-  generic shell. See **Native Git Tools** above.
-- **Embedding SDK** — ✅ **Done (Task 5.2).** Two-tier library surface separated by
-  `package.json` `exports`: the stable `createAgent` facade (main entry) and the
-  unstable building blocks (`/internals`). Programmatic permission policy that
-  defaults to refusing mutations; sandbox/deny-list stay on with explicit opt-out;
-  `close()` teardown; per-instance config (process-global limits documented). See
-  **Embedding SDK** above.
-- **Background tasks** — ✅ **Done (Task 5.3).** `run --background` launches a
-  detached agent process (own process = own global state, reusing the
-  `createAgent` facade) with a launch-fixed, refuse-by-default policy and
-  sandbox/deny-list on; a file-based task registry (`~/.semalt-ai/tasks/`) drives
-  `tasks list|status|result|kill|prune`. Validation runs before detach (no
-  orphans); stale/dead tasks are detectable and prunable; kill tree-kills by PID.
-  Background-launch is intentionally NOT an agent tool. See **Background Tasks**
-  above.
-- **Multimodal image input** — ✅ **Done (Task 5.4).** PNG/JPEG/WebP/GIF attach via
-  `--image` (repeatable), in-chat `/image`, and the SDK `images` option; read
-  through `isPathSafe`, size-capped (`image_max_bytes`), base64-encoded, media
-  type detected from magic bytes. The provider content-part shape (Anthropic-style
-  vs OpenAI-style) is selected per profile/heuristic; a text-only model fails loud
-  (the image is never silently dropped). PDF input deferred; generation out of
-  scope. See **Multimodal Image Input** above.
-
-**Planned, not yet scheduled:**
-
-- **Cost caps** — hard spend limits per session/turn (today cost is *displayed* via
-  `lib/pricing.js`, never enforced).
-- **Auto-update** — self-updating the CLI (today: `npm install -g` manually).
-- **XDG / `%APPDATA%` config dirs** — honoring platform config-dir conventions instead
-  of the fixed `~/.semalt-ai/`.
-- **Domain-allowlist network policy** — *deliberately deferred, may stay out of
-  scope.* Task 4.4b ships **binary** network isolation (on / kernel-level none); a
-  per-domain allowlist ("allow github.com, block the rest") is **not** implemented
-  and is **not** a planned increment by default. **Rationale:** domain-granularity
-  requires a host-side egress proxy with full network privileges, which is the
-  exact design the reference implementation shipped and that was **bypassed
-  completely, twice, over 5.5 months** (allowedDomains fail-open CVE-2025-66479, a
-  hostname-parser differential, and TLS-MITM breaking Go binaries). We will only
-  revisit this if it can be done **without** a host proxy / TLS interception (e.g.
-  a kernel/eBPF egress filter on resolved IPs) — until then, binary isolation is
-  the robust posture. See **OS Sandbox → Why binary**.
-- **Native-Windows / WSL1 sandbox** — no OS primitive today (bwrap needs the
-  user/mount namespaces WSL1 lacks; native Windows has none). On those platforms
-  the sandbox degrades to the fail-safe fallback (ask-or-block); the Windows
-  deny-list (now covered, Task 4.4) is the remaining shell guard there.
-
-**Out of scope (no current plan):**
-
-- **Multimodal — image *input*** is ✅ **Done (Task 5.4)** — PNG/JPEG/WebP/GIF
-  attached via `--image` / `/image` / the SDK `images` option, sent provider-
-  specifically to vision models (text-only models fail loud). See **Multimodal
-  Image Input** above. Still out of scope: **PDF input** (deferred), **audio
-  input**, and **image/audio *generation* / output**.
-- **Background / cloud / scheduling** — long-running background agents, cloud execution,
-  or cron-style scheduling.
-- **OpenTelemetry** — OTel traces/metrics export.
-- **Managed policy** — centrally-administered org policy enforcement.
-- **Native notifications** — OS-level desktop notifications.
+Version lives in `package.json`; bump it with every published change. CI
+(`.github/workflows/ci.yml`) runs `npm ci` + `npm audit --omit=dev
+--audit-level=high` + lint + the test matrix.
 
 ---
 
-## Development & Publishing
-
-```bash
-# Run locally
-node index.js chat
-
-# Symlink for global use during dev
-npm link
+## Keeping this file up-to-date
 
-# Publish to npm
-npm publish --access public
-```
-
-Version is in `package.json`. Bump it with every published change.
-
----
+This file is **auto-loaded as project memory and capped at 32 KB** — keep it lean so
+it loads in full. **Runtime-essential operational facts and the invariants above go
+here; rationale, per-task history, per-subsystem deep detail, and the full config/CLI
+reference go in `docs/`** (not auto-loaded). Do not let this file re-bloat.
 
-## Keeping This File Up-to-Date
+Update **this file** when:
+- A new `lib/` module is added (update the Directory Layout one-liner).
+- A **load-bearing invariant** changes — and re-verify the cited `file:line`.
+- The Node version requirement or runtime-dependency set changes.
+- The build/run/test/lint/publish commands change.
 
-Update this file when:
-- A new CLI command or slash command is added (update the commands tables).
-- A new tool action is added to `tools.js` (update the Tool Operations table).
-- The agent loop behavior changes (max iterations, tag format, approval flow).
-- A new `lib/` module is added.
-- The config schema changes (new keys, renamed keys, migration logic).
-- A runtime dependency is added, removed, or version-bumped (update **Dependency & Supply-Chain Policy** and the rationale list; commit the regenerated lockfile).
-- A new dashboard API call is added to `api.js`.
-- The system prompt in `prompts.js` changes in a way that affects tool-tag syntax.
-- The Node.js version requirement changes.
+Update **`docs/`** when:
+- A subsystem's internals change → `docs/ARCHITECTURE.md`.
+- A config key, CLI flag, slash command, or tool tag/operation changes →
+  `docs/CONFIG.md` (and the runtime source: `lib/config.js` / `lib/args.js` /
+  `lib/tool_specs.js` / `lib/prompts.js`).
+- A design decision, dependency rationale, or roadmap item changes → `docs/HISTORY.md`.
 
-When renaming or removing a tool tag, update **both** `prompts.js` and `agent.js` atomically and note it here.
+When renaming or removing a tool tag, update **`prompts.js` and `agent.js`
+atomically** (invariant 10) and reflect it in `docs/CONFIG.md`.