@semalt-ai/code 1.19.0 → 1.20.0

package/docs/CONFIG.md

@@ -0,0 +1,340 @@
+# semalt-code — Config & CLI Reference
+
+> Full per-key config reference, the CLI command/flag reference, in-chat slash
+> commands, tool tags, tool operations, and dashboard API endpoints. **Not
+> auto-loaded** as project memory. The authoritative runtime sources are
+> `--help`, `lib/tool_specs.js`, `lib/prompts.js`, `lib/config.js`, and
+> `lib/api.js`; this file mirrors them for humans.
+
+---
+
+## 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). Per-tool recs
+                          (json toolCalls[] / stream-json tool events) carry the
+                          legacy { tool, args, ok, ms } PLUS additive descriptor
+                          fields (status, category, durationMs, target, attrs,
+                          meta, error, noDuration, detail). See ARCHITECTURE.md.
+-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 125); 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 |
+
+---
+
+
+### 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"/>  <!-- path may also be a specific file or a directory; non-path values are treated as a glob -->
+<grep pattern="T.PICKUP" path="/abs/path/to/file.js"/>  <!-- search one explicit file (like search_in_file, but regex+ripgrep) -->
+<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>
+<edit_file path="/file" line="42" end_line="48">multi-line\nblock replacing lines 42–48</edit_file>
+<search_in_file path="/file">regex pattern</search_in_file>
+<replace_in_file path="/file" search="foo(x)" replace="bar(y)"></replace_in_file>
+<replace_in_file path="/file" search="old" replace="new" replace_all="true"></replace_in_file>
+<replace_in_file path="/file" search="id=\d+" replace="id=0" regex="true">g</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`.
+
+---
+
+
+## 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` | Exact string replacement (Claude Code Edit model). The search is matched **literally by default** — verbatim, no regex, at any length — so paste exact code incl. `( ) { } . [ ]`. The match must be **unique**: not-found → **error** (file unchanged); >1 match → **error** unless `replace_all="true"`. Returns the honest replaced count, plus a `warning` if the search string still remains after replacing. `regex="true"` opts into regex mode (inline content = `flags`; bounded by a nested-quantifier guard + 1000-char cap) — the uniqueness guard still applies (`g` flag or `replace_all` to replace many) |
+| `edit_file` | Replace a line, or a contiguous line range, in a file by 1-based number. Optional `end_line` replaces lines `line..end_line` wholesale with the content (a regex-free block edit; pairs with a numbered `read_file` slice) |
+| `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 |
+
+---
+
+
+## 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.
+
+```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,
+  "diff_max_lines":      50,
+  "shell_preview_lines": 5,
+  "max_iterations":      125,
+  "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
+    }
+  ]
+}
+```
+
+- `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`.
+- `diff_max_lines` caps the **changed** (`+`/`-`) lines shown in a file-edit diff (default 50). Every mutating file edit (`write_file`/`append_file`/`edit_file`/`replace_in_file`) renders its diff **at execution time** — decoupled from the permission modal, so an **auto-approved** edit shows its changes exactly like a manually-approved one, and the diff is shown **exactly once** per edit (the modal carries only a compact description, never the full diff). A small edit (or a series of small edits, each short) renders in full; one large edit shows **head+tail** of the changed lines (first ~60% + last ~40%, mirroring `max_output_lines`) with a `… K more changed lines (N total)` notice. Loaded history (`--resume` / `/history` / `/chats`) is **not** replayed — only new edits render diffs. UI-only (`renderDiff` / `buildExecutionDiff` in `lib/ui/diff.js`); the model-facing tool result is unchanged.
+- `shell_preview_lines` caps the **chrome preview** of `shell`/MCP/subagent output (default 5; Output Refactor Phase 5). A successful tool's output renders **in moderation** below the result line: the first `shell_preview_lines` lines (each fitted to one physical row) followed by a **static** `… N more lines` hint, where **N is exact** (total − previewed). The preview is collapsed and **non-interactive** — there is no in-terminal way to expand it (full viewing of large output is deferred to the planned full-screen transcript viewer). Output of `≤ shell_preview_lines` lines shows fully with no hint. **Diffs are exempt** — file edits render expanded to `diff_max_lines`, and **errors render expanded** (full body), since both are things the user explicitly wants to see. **UI-only** (`formatOutputPreview` in `lib/ui/format.js`, rendered via `lib/ui/render-operation.js` / committed via `lib/ui/chat-history.js`); the model still receives the **full** output via `boundToolOutput` — this preview never touches model context.
+- `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 125; `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.
+- `models[].native_tools` (bool, default **true**) — only an explicit `false`/`0`/`"false"`/`"0"` opts the profile out of native function-calling (the XML tool-tag rail). Resolved by `isNativeToolsActive()`.
+- `models[].inline_reasoning` (bool, **optional**, default unset) — live-narration safety assertion for the **native rail only**. Some models inline their reasoning into `delta.content` (Qwen3-style bare text terminated by an orphan `</think>`), indistinguishable from narration until the boundary arrives; to avoid leaking that hidden reasoning, leading content is buffered until a positive boundary. Setting `inline_reasoning: false` asserts **this model never inlines reasoning** — so on the native rail its narration streams **live, token-by-token, from token 1**. Leave it **unset** (or `true`) when unsure: the agent then keeps the safe buffered-until-boundary behavior. Independently, if the model emits a structured `reasoning_content` delta this turn, the gate opens live regardless of this flag (positive evidence the reasoning channel is in use). Only an explicit boolean is persisted (`getInlineReasoning()`); the XML rail ignores this key entirely.
+- `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.
+
+---
+