@amd-gaia/gaia 0.2.0 → 0.3.2

package/SKILL.md

@@ -65,7 +65,8 @@ A second sidecar started here would only fight the daemon's own for port 8141. U
 
 Other commands: `gaia fetch` (download + verify, print JSON, exit),
 `gaia serve` (sidecar alone), `gaia version` (per-component version, source URL,
-and platform matrix). Anything after a bare `--` goes to the TUI verbatim.
+and platform matrix). Unknown or misplaced launcher options are rejected;
+anything intended for the TUI goes after a bare `--` and is passed through verbatim.
 
 ### Where each binary comes from
 
@@ -117,6 +118,10 @@ Windows sidecar build**.
 | `linux-arm64`  | **no**  | yes |
 | `win32-arm64`  | **no**  | yes |
 
+The `linux-x64` sidecar needs **glibc 2.34 or newer** (Ubuntu 22.04, Debian 12,
+RHEL 9 or later); an older distro fails at launch, so check `ldd --version`
+before blaming the package.
+
 Resolving the sidecar on those two keys raises `PlatformError` naming the
 platform and the supported set. It is not silently skipped, and the TUI is never
 launched with no agent behind it. `npx @amd-gaia/gaia version` prints the matrix
@@ -127,9 +132,22 @@ for the version you have.
 The agent thinks with a model hosted by **Lemonade Server**, which this package
 does not install. Required before any query succeeds:
 
-1. Lemonade **10.2.0 or newer**, running (`lemonade-server serve`).
-2. The default model downloaded (`gaia download Gemma-4-E4B-it-GGUF`, or
-   `gaia init`).
+1. Lemonade **10.2.0 or newer**, running. GAIA's daemon starts and supervises
+   one, so `gaia daemon start` is normally all that is needed (`gaia init`
+   also installs and starts it on first run). Qwen3.8 Flash Next needs
+   **v2026.39.1 or newer**, the version `gaia init` installs; older servers
+   cannot load it.
+2. The machine's default chat model downloaded — run `gaia init`. It picks
+   `Qwen3.6-35B-A3B-GGUF` where a GPU holds it (~27 GB for models,
+   weights plus context cache — a 64 GB+ Strix Halo or a 32 GB GPU) and
+   `Gemma-4-E4B-it-GGUF` everywhere else, CPU-only PCs included, and records the pick as
+   `default_model` in `~/.gaia/config.json`. On 128 GB-class PCs the user may
+   switch to the multimodal `user.Qwen3.8-Flash-Next-GGUF` with `gaia config set
+   default_model`. `model.id` below names whichever this machine uses.
+   `gaia download` takes **no** model argument — naming one makes it exit 2. To
+   pull a single model instead, repeat the command `GET /v1/gaia/init` gives
+   you: it names the Lemonade client this machine actually has. Do not invent
+   one.
 
 Do not guess — ask the sidecar. `GET /v1/gaia/init` is a read-only preflight
 (it never pulls or loads) that probes Lemonade, compares its version to the
@@ -150,7 +168,9 @@ alone:
                 "min_version": "10.2.0", "compatible": null },
   "model":    { "id": "Gemma-4-E4B-it-GGUF", "present": false,
                 "loadable": null, "ctx_size": null },
-  "hint": "Local Lemonade Server is not reachable at … — start it with `lemonade-server serve`, or set LEMONADE_BASE_URL to a running server."
+  // The manual fallback ("Otherwise: …") is resolved for the host's Lemonade
+  // install (tray app, macOS app, systemd service, or CLI) — render it verbatim.
+  "hint": "Local Lemonade Server is not reachable at …. GAIA starts it automatically — run `gaia daemon start` if the background service is not running. Otherwise: Start the Lemonade app from Applications, then retry. Or set LEMONADE_BASE_URL to a running server. See https://amd-gaia.ai/docs/guides/gaia."
 }
 ```
 
@@ -216,6 +236,12 @@ await shutdown(proc);   // tree-kill; auto-cleanup also reaps on exit
   file path); read it from there, don't invent one. A 401 whose `detail` names
   both env vars means you sent the wrong token or none.
 
+  The programs the agent starts (shell commands, MCP servers, CLI installs and
+  sign-ins, native hub agents, media tools) never inherit this token
+  or GAIA's other internal credentials. To withhold your own variables from
+  them too, list the names in `GAIA_CHILD_ENV_DENY` (comma or space separated);
+  `GAIA_NO_DOTENV=1` stops the sidecar loading `.env` files.
+
 Or skip the code entirely and let the CLI own it:
 
 ```bash
@@ -226,7 +252,7 @@ curl http://127.0.0.1:8141/health
 ## 7. Call `POST /v1/gaia/query`
 
 This is the whole agent surface. There is **no typed query client** in this
-package — call it with plain `fetch`. Contract version **2.12**; the stream is
+package — call it with plain `fetch`. Contract version **2.24**; the stream is
 `text/event-stream` terminated by **exactly one** `final` or `error`.
 
 Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
@@ -235,11 +261,19 @@ Request body (`extra: "forbid"` — an unknown field is a **422**, not ignored):
 |---|---|---|
 | `query` | yes | Non-empty. |
 | `run_id` | yes | **You mint it**, and it must be a UUID (non-UUID → 422). It is the cancel handle, valid from the instant the request is sent. |
-| `context` | yes | Transcript slice, pushed in the body — may be `[]`, never absent. Each item `{ role, content }`; `role` ∈ `user` / `assistant` / `system` / `tool`. |
-| `session_id` | no | Contract ≥ 2.12. **Pass it.** The agent persists its indexed-document set per session — without it, it forgets a document between the turn that indexed it and the next question. |
+| `context` | yes | Transcript slice, pushed in the body — may be `[]`, never absent. Each item `{ role, content }`; `role` ∈ `user` / `assistant` / `system` / `tool`. If it doesn't fit beside the agent's prompt and tools in the model's window, the agent keeps the newest whole turns that do and says so in a `status` event; one turn bigger than that is kept with its longest messages cut. |
+| `session_id` | no | Contract ≥ 2.12. **Pass it.** The agent persists its indexed-document set per session — without it, it forgets a document between the turn that indexed it and the next question. 1–128 characters from `A-Z a-z 0-9 . _ -` (a UUID works); anything else is a **400**. |
+| `documents` | no | Contract ≥ 2.16. Absolute paths of the files the user attached to this conversation — send the whole set **every turn**. The agent indexes any it has not read yet before the turn runs, granting each exact file and not its folder. A relative path is a **422**. A missing file, a folder, or a refused secret is named as not indexed in the turn's `index_documents` step, and the turn still runs. |
+| `allowed_paths` | no | Contract ≥ 2.18. Absolute folder or file paths the conversation may read — the scope your UI shows. A new session gets exactly this scope; a retained session adds any entry it lacks and never drops one until the session ends. `GAIA_ALLOWED_PATHS` still narrows it. A relative path is a **422**. Omit it for the agent's default scope. |
+| `working_directory` | no | Contract ≥ 2.24. Absolute chat workspace used to resolve relative file paths for reads, writes, edits and approval prompts. It is separate from `allowed_paths`; a relative path is a **422**. Send the same folder the UI shows. |
+| `memory` | no | Contract ≥ 2.18. `"on"`, `"private"` or `"off"`. Under `"private"` or `"off"` the turn saves nothing to memory, including errors and lessons the agent saves on its own. A retained session keeps the last value: send it every turn. |
+| `internet_off` | no | Contract ≥ 2.23. `true` refuses web search and page fetches, the browser, connector, mailbox and Agent Hub tools and any call or shell command that contacts another host, with a message telling the model the internet is off for this chat; `false` allows them. A retained session keeps the last value: send it every turn. Omit it to leave the agent as it is. To change it mid-turn, `POST /v1/gaia/sessions/{session_id}/internet` with `{"internet_off": true}`; the next tool call follows it, and an unknown session is a **404**. Post it only once `/query` has answered, since the turn's own value replaces an earlier one; re-read the switch then and post it if it changed. |
+| `changes_turn_id` | no | Contract ≥ 2.19. Needs `session_id`. The agent copies each file before changing it, under `<GAIA home>/snapshots/<session_id>/<changes_turn_id>/`, so the turn can be reviewed and undone; the copies are complete before the terminal event. Format: 14 digits of local time, `-`, 8 hex digits (`YYYYmmddHHMMSS-xxxxxxxx`); anything else is a **422**. Omit it to copy nothing. |
+| `surface` | no | Contract ≥ 2.20. `"agent_ui"`, `"tui"` or `"cli"` — the front-end the turn comes from. With `"agent_ui"` the agent points recurring requests at the Agent UI's **Scheduled tasks** page. It also picks where a model-provider error tells the user to fix it; omitted (a headless caller), that is the model server the GAIA host uses (`LEMONADE_BASE_URL`). Read when a session is built. |
+| `reasoning` | no | Contract ≥ 2.22. `true` streams the model's reasoning as `reasoning` events (`{ delta }`), apart from `status` lines and the answer's `token`s. Join the deltas as they come: each keeps its own spacing. Omit it and reasoning folds into `status` lines as before. |
 | `can_answer_questions` | no | Set `false` for one-shot / batch runs so the agent resolves ambiguity itself instead of parking on a question nobody can see. |
-| `model` | no | Overrides the model id — only when the run builds a fresh agent. On a retained `session_id` the agent already exists, so a model that differs from the one it was built with is a **409**, not an override. |
-| `provider` | no | Local inference only — anything but `"lemonade"` is a **400**. |
+| `model` | no | Overrides the model id. On a retained `session_id` a different model is **switched in place** (contract ≥ 2.14), keeping the conversation and any loaded skills; a switch that fails is a **409** and leaves the session on its previous model. |
+| `provider` | no | `"lemonade"` (the default backend) or `"claude"`, which sends the conversation to Anthropic's API instead of the local server. Anything else is a **400**. When you name it, `model` must agree: under `"claude"` it must be a `claude-*` id, under `"lemonade"` it must not be. A mismatch is a **400**, on a new session or an existing one. Omit it and the `model` decides instead — a `claude-*` id alone reaches Anthropic, any other id runs locally — so there is nothing to mismatch. On a retained `session_id`, naming a different provider switches the session to it in place, onto `model` or, without one, the provider's default model; omitting both leaves the session where it is. |
 | `max_steps` | no | ≥ 1. |
 
 ```ts
@@ -295,13 +329,14 @@ The canonical event shapes, as emitted:
 
 | Event | Shape |
 |---|---|
-| `status` | `{ type, message }` — progress and reasoning narration |
+| `status` | `{ type, message, phase?, words?, chars?, queue? }` — progress and reasoning narration. `phase` (`loading_model`, `downloading_model`, `reading`, `reasoning`, `tool_call`, `model_queue`) names what the model is doing; show it as the live line, not as narration. `model_queue` means the turn is waiting for the model behind another request: it repeats every ~2 s with a `queue` object (`event`, `position`, `queue_length`, `holder`, `holder_model`, `waited_s`), so its steady arrival means queued, not stuck |
 | `token` | `{ type, delta }` — answer text to append |
-| `tool_call` | `{ type, tool, args }` |
-| `tool_result` | `{ type, tool, data, render? }` |
-| `needs_confirmation` | `{ type, run_id, action, summary }` — no `confirm_url`; see §8 |
+| `reasoning` | `{ type, delta }` — the model's reasoning, only when the request set `reasoning: true` (contract ≥ 2.22); join the deltas as they come and keep them apart from the answer |
+| `tool_call` | `{ type, tool, args, mcp_server?, mcp_server_label?, mcp_tool? }` — an MCP tool names its connector (`mcp_server_label`, e.g. `"Git"`) and the server's own tool name (`mcp_tool`, e.g. `"git_log"`); label the call with those, not the prefixed `tool` |
+| `tool_result` | `{ type, tool, data, render? }` — an MCP tool that returned text carries it in `data.mcp_output` (`{ text, truncated }`); a `search_web` result lists its hits in `data.sources` (`[{ title, url }]`) |
+| `needs_confirmation` | `{ type, run_id, action, summary, confirm_id?, always_scope?, risk?, tool_label?, args?, args_truncated?, prompt_context? }` — answer it, or it ends the run; see §8. `summary` shortens long code; `args` is the call itself, exactly the arguments the model sent, each value capped at 64,000 characters (`args_truncated: true` when one was cut — don't auto-approve a call you can't fully see). What GAIA adds to the prompt is in `prompt_context`, never `args`: `working_directory` (where a shell call runs, when the model's arguments don't say), `risk_note` (why GAIA's checks don't cover the call) and `file_path` (the absolute path a write lands at, when the model gave a relative one) |
 | `needs_input` | `{ type, run_id, request_id, question, options[], allow_free_text, sensitive, respond_url, timeout_seconds? }` |
-| `final` | `{ type, answer, usage? }` — terminal |
+| `final` | `{ type, answer, usage?, failed?, context?, context_error?, performance? }` — terminal. `failed: true`: the model failed mid-turn and `answer` says what was and wasn't done; show it as an error, not a result. `context` / `context_error` and `performance` (the turn's step timings) are optional; see SPEC §5.1 |
 | `error` | `{ type, detail, status }` — terminal, surface `detail` verbatim |
 
 Rules a client must respect:
@@ -313,52 +348,133 @@ Rules a client must respect:
   guarantees one; a close without one means something broke on your side.
 - **Answer `needs_input`, don't restart.** The run is parked on the *same*
   stream. `POST /v1/gaia/query/{run_id}/respond` with
-  `{ request_id, response }` and keep reading the existing stream — a fresh
+  `{ request_id, value }` and keep reading the existing stream — a fresh
   `/query` POST abandons the paused run. Unknown run → **404**; a `request_id` that
   is no longer pending → **409** (both loud, never a silent drop). Render each
   option's `description`, and mask the input when `sensitive` is set.
 - **Cancel with `POST /v1/gaia/query/{run_id}/cancel`.** It returns
   `{ run_id, cancelled }` — an unknown id reports `cancelled: false` with a
   **200**, not a 404, because a cancel racing a normal completion is expected.
-  Dropping the HTTP connection also cancels the run.
-
-## 8. Over `/v1/gaia/query`, confirmation-gated tools are **refused, not prompted**
+  Dropping the HTTP connection also cancels the run. A run stopped mid-answer
+  ends with an empty `final`, and no `token` follows the cancel, so keep the
+  text the `token` events already delivered. Text not yet sent when the
+  cancel lands is dropped, not delivered late.
+- **Add to a running turn with `POST /v1/gaia/query/{run_id}/followup`**
+  (contract ≥ 2.15, body `{ text }`). The run is not interrupted and no second
+  turn starts: the agent folds the text in at its next step boundary and
+  answers it alongside what it was already doing. Unknown run → **404**, an
+  agent that cannot take one → **409**; both are loud, so hold the message
+  rather than telling the user it was sent. `/query` is stateless, so put a
+  delivered follow-up into the next turn's `context` yourself, between that
+  turn's question and its answer.
+
+## 8. Over `/v1/gaia/query`, a gated tool asks — when you can answer
 
 Read this before you design a workflow around it. This section is about the HTTP
 surface — the agent's other transport can collect an approval; see SPEC §5.5.
 
-Seven of the agent's 71 tools mutate the machine and need explicit approval
-before they run. Five sit in the base `TOOLS_REQUIRING_CONFIRMATION` set —
+Twelve of the agent's 95 tools mutate the machine and need explicit approval
+before they run. Nine sit in the base `TOOLS_REQUIRING_CONFIRMATION` set —
 **`write_file`**, **`edit_file`**, **`run_shell_command`**,
-**`execute_python_file`**, and **`notify_desktop`**, which spawns a PowerShell
-child on Windows to draw the notification — and the flagship adds two of its
-own, **`install_skill`** and **`remove_skill`**, because installing a skill
-writes third-party code under `~/.gaia/skills` and removing one deletes it.
-Everything else — reading, indexing, querying, web fetching, memory — runs
-without asking.
-
-Over `/v1/gaia/query` there is **no way to collect an approval**, so the stream
-does not prompt. When the agent reaches one of those tools it emits a
-`needs_confirmation` event, and the server **immediately follows it with a
-terminal `final`** whose `answer` says it stopped before running that action,
-then cancels the run. There is no `confirm_url`, no resume, and no
-`/query/{run_id}/confirm` endpoint — it is a deliberate deny-by-default stub, not
-an oversight.
-
-Concretely, your client sees:
+**`wait_for_condition`**, which re-runs a shell command until it succeeds,
+**`execute_python_file`**, **`run_python`**, **`notify_desktop`**, which spawns
+a PowerShell child on Windows to draw the notification, and **`install_cli`** /
+**`sign_in_cli`**, which install software and sign a CLI in to the user's
+account — and the flagship adds three of its own
+(`CONFIRMATION_REQUIRED_TOOLS`): **`install_skill`**, **`capture_skill`**, and
+**`remove_skill`**, because installing or capturing a skill writes third-party
+content under `~/.gaia/skills` and removing one deletes it. A capture that does
+land is additionally **code-inert**: its instructions load, but any
+`tools.py`/scripts stay unregistered until a human runs
+`gaia skill promote <name>` in a terminal. Everything else — reading,
+indexing, querying, web fetching, memory, and the read-only `check_cli_setup`
+— runs without asking. A write or edit inside the agent's own scratch
+folder (`gaia-scratch-…` under the system temp folder) runs without asking too,
+so running a script from it asks every time and carries no `always_scope`. So does a shell command run there or naming a path there, and a script handed a scratch path as an argument.
+
+The eight live-browser tools are gated by a **hook**, not a set, so a name
+alone does not tell you whether a call will ask. `browser_login` always asks.
+`browser_click` / `browser_type` ask when the call acts inside a session the
+run signed in to, or when the target element's label reads irreversible, and
+run unasked on the open web. The hook **fails closed**: if the browser cannot
+be asked what state it is in, the call is treated as authenticated and prompts.
+Design a workflow around the approval path, not around a fixed tool list.
+
+**Contract ≥ 2.14 can answer one.** Send a `session_id` and leave
+`can_answer_questions` unset (or `true`). The stream emits `needs_confirmation`
+carrying a `confirm_id` and then **stays open** while the agent waits:
+
+```
+data: {"type":"needs_confirmation","run_id":"…","action":"run_shell_command","summary":"python -m pytest -q tests/\nCan run any code, with your permissions.","confirm_id":"…","always_scope":"pytest (runs the test code it finds)","risk":"execute"}
+```
+
+Answer it on the same run, then keep reading the stream:
+
+```
+POST /v1/gaia/query/{run_id}/tool_decision
+{ "decision": "allow" | "deny" | "always" | "timeout", "confirm_id": "…" }
+```
+
+`summary` is the command or call itself, shown once — your UI supplies the
+question. For a shell command it can carry two more lines: `in <folder>` when
+the command runs outside the workspace, and one plain sentence on what a `write`
+or `execute` command can do. Show it as-is. A CLI a skill would grant (`git
+commit`, `python script.py`) with no such skill loaded arrives here as a prompt,
+not a refusal. So does a command GAIA's own checks don't cover (`git push`,
+`python -c`, a path outside the project): its `summary` is the exact line the
+shell will run, unshortened, then `in <folder>`, then a risk sentence, and it
+carries no `always_scope` — offer allow-once and deny only. `allow` runs that
+line once; the next call asks again. `risk` says what the call does (`read`, `write`, `execute`,
+`destructive`); label by it rather than by tool name, since `run_shell_command`
+is `pytest` on one call and `rm -rf` on the next. `always` grants the family
+named in `always_scope` for the rest of the session (`pytest` covers every
+spelling of a test run) — say so in your UI, because it stops asking; no
+`always_scope` means don't offer it. If your prompt expires unanswered, send
+`timeout`, not `deny`: it still refuses, but the agent tells the user the
+request timed out instead of claiming they said no. Unknown run → **404**; a
+prompt that is no longer pending → **409**; any other decision → **422**. All loud,
+never a silent drop. Send `confirm_id`: without it a late answer resolves
+whichever prompt replaced the one it was typed against.
+
+To stop being asked for a whole session:
+
+```
+POST /v1/gaia/sessions/{session_id}/bypass
+{ "enabled": true }
+```
+
+It applies to the very next gated tool, including one in a turn already running,
+and an unknown session is a **404** rather than a new one. A malformed
+`session_id` is a **400**, same as on `/query`.
+
+**That bypass stops the prompts; it does not open the shell.** The stdio
+transport's `--bypass-permissions` does both — it runs gated tools unasked *and*
+lifts the shell tool's guardrails (redirection and the other shell-only
+operators, the read-only binary allowlist, the rate limit). That second half is
+arbitrary code execution, appropriate for one local parent on a private pipe and
+not for a bound socket, so it stays on stdio: HTTP sessions never lift the shell
+gates, and the request body rejects unknown fields so a client cannot ask. See
+SPEC §5.5.
+
+So a shell command past those gates (a delete, `git add`) is never run unasked
+under bypass. On a run someone can answer (`can_answer_questions` not `false`,
+with a `session_id`) it emits `needs_confirmation` and waits for
+`/tool_decision`, exactly as with bypass off; commands that need no approval
+still run unasked. A run nobody can answer refuses it, as below.
+
+**A run nobody can answer is still refused.** With `can_answer_questions: false`,
+or with no `session_id`, the server emits `needs_confirmation`, follows it
+immediately with a terminal `final` saying it stopped before running the action,
+and cancels the run:
 
 ```
-data: {"type":"needs_confirmation","run_id":"…","action":"write_file","summary":"Run 'write_file'?"}
 data: {"type":"final","answer":"I stopped before running 'write_file' because it needs your explicit approval, and this streaming surface cannot collect that yet. …"}
 ```
 
-So: **`/query` cannot run any of those seven tools.** If your integration needs
-that, drive the agent from a surface that can prompt — its stdio transport is the
-one that can, because its control channel carries an approval back to a turn
-already in flight (SPEC §5.5) — or perform the mutation yourself from your own
-code and let the agent do the reading and reasoning. Treat `needs_confirmation`
-as an early warning that the run is about to end, not as a question you can
-answer.
+That is deny-by-default, not an oversight: parking a batch run on a prompt
+nobody will ever see reads as a hang. So a one-shot integration cannot run those
+nine tools — pass a `session_id` and answer, or perform the mutation from your
+own code and let the agent do the reading and reasoning.
 
 ## 9. File-access scope
 
@@ -378,10 +494,21 @@ come back as a structured error naming the file and the reason, so do not plan a
 integration around reading a credential file or editing a shell rc — perform
 those from your own code.
 
-**In 0.1.1 narrowing it is a construction-time setting only.** The packaged
-sidecar exposes no flag or env var for `allowed_paths` (its CLI accepts only
-`--host` and `--port`), so restricting the scope means embedding `GaiaAgent` in
-your own Python process:
+The agent also gets its own scratch directory for throwaway scripts and
+intermediate files, so they stay out of the user's project. It is created per
+agent under the system temp dir, deleted when the agent closes, and is the only
+part of the temp dir the agent may use.
+
+**To narrow it for a run, set `GAIA_ALLOWED_PATHS`** in the environment the
+sidecar starts in — absolute folders joined with `;` on Windows and `:` elsewhere.
+The scope becomes the overlap with the default; an entry outside it is ignored
+with a warning and never widens it, and out-of-scope paths are refused without a
+prompt, even under full access. The scratch directory stays writable. An empty,
+relative or missing entry stops the sidecar at startup. It confines the agent's
+tools, not code they run: a `run_python` script or shell command can still read
+anything the OS user can, so isolating a run from files it must not see needs a
+separate OS user, container or VM. Embedding `GaiaAgent` lets you pass an explicit
+list instead (the variable still narrows it):
 
 ```python
 from gaia_agent.agent import GaiaAgent, GaiaAgentConfig
@@ -401,7 +528,8 @@ matching bodies in full — the rest collapse to a one-line menu entry, and the
 model (or the user) re-activates one by calling `load_skill` on it again.
 `GAIA_DYNAMIC_SKILLS=0` disables the per-turn selection (every loaded body
 renders every turn); `GAIA_DYNAMIC_SKILLS_TAU=<float>` overrides the match
-threshold. Manifest `skills:` entries are always-on and never collapse. If the
+threshold. Manifest `skills:` entries are always-on and never collapse, and a
+turn with only always-on skills loaded embeds nothing. If the
 embedder is unavailable, selection disables itself for the session and every
 body renders — capability is never silently lost to a failed match.
 
@@ -411,7 +539,17 @@ turn — budget for it. It is not a task recipe but the agent's honesty floor: d
 not claim work you did not do, do not present empty output as a result, do not
 substitute a near-miss and report success. Those failures corrupt an answer
 whatever the task is, which is why it cannot live in an opt-in bundle. It
-declares no tools, and its body measures 676 tokens (tiktoken `cl100k`).
+declares no tools, and its body measures 790 tokens (tiktoken `cl100k`).
+
+**`document-extract` ships bundled but not enabled.** `gaia-voice` routes a
+request for every item in a document to it, and it drives
+`extract_document_items` and `save_extracted_items` so a long transcript yields
+a complete, source-quoted inventory rather than a summary. A skill turns that
+inventorying on only by listing `extract_document_items` in `tools_required`;
+wording such as "find every call site" in another skill does not. Loading it
+registers the tools at once, so `load_skill` never reports them missing; coverage
+is enforced only when the request itself names a source document or asks for
+every item, and a file the user named as a deliverable is never a source.
 
 **No skill *set* loads.** `gaia-agent.yaml` ships its `skill_sets:` and
 `default_skill_set:` blocks **commented out** — following the email agent's
@@ -419,10 +557,12 @@ precedent, because loading several skill bodies into every prompt costs tokens
 and no eval has measured that trade for this agent yet. Re-enabling is
 uncommenting two blocks; no code change.
 
-So today there is nothing for `GAIA_SKILL_SET` to select — leave it unset. Once
-a release declares sets, `GAIA_SKILL_SET` is the selection channel for the
-packaged sidecar (its CLI accepts only `--host` and `--port`), and an undeclared
-name raises naming the valid sets rather than falling back to a default. Beyond
+So today there is nothing for `GAIA_SKILL_SET` to select — leave it unset; any
+value stops the agent at startup (the sidecar exits non-zero before binding its
+port). Once a release declares sets, `GAIA_SKILL_SET` is the selection channel
+for the packaged sidecar (its CLI accepts only `--host` and `--port`), and an
+undeclared name stops startup naming the valid sets rather than falling back to
+a default. Beyond
 `gaia-voice`, do not design around a skill being on by default.
 
 ## 11. The project map — two things it costs you
@@ -437,12 +577,13 @@ Two consequences an integrator needs to plan for:
 
 - **Up to 600 prompt tokens, every turn.** That is the enforced ceiling
   (1.8% of the NPU profile's 32K window), not a typical value — budget it
-  alongside `gaia-voice`'s 676.
-- **A background embedding pass on first contact with a new repository.** If
-  the repo has no [code index](https://amd-gaia.ai/docs/guides/code-index), the
-  map starts one in a background thread so semantic search is ready when it is
-  needed. On a large monorepo that is minutes of local embedding.
-  `GAIA_PROJECT_MAP_AUTO_INDEX=0` turns it off.
+  alongside `gaia-voice`'s 790.
+- **An embedding pass on the first semantic code search.** If the repo has no
+  [code index](https://amd-gaia.ai/docs/guides/code-index), the first
+  `search_code_index` builds it, then searches. On a large monorepo that one
+  search takes minutes of local embedding; a task that never searches pays
+  nothing. `GAIA_PROJECT_MAP_AUTO_INDEX=1` builds it in the background at task
+  start instead.
 
 The sidecar's CLI accepts only `--host` and `--port`, so pointing the map at a
 specific project means `GAIA_PROJECT_ROOT=/path/to/repo` in its environment, or
@@ -450,6 +591,11 @@ specific project means `GAIA_PROJECT_ROOT=/path/to/repo` in its environment, or
 a VCS checkout nor holds a recognised manifest gets **no map** — that is the
 designed answer, not a failure.
 
+The same root check also decides whether the shell rides along: when it
+resolves to a repository, `run_shell_command` is offered on every turn instead
+of only when semantic selection guesses the request sounds like a shell
+request. No repository, no change.
+
 ## 12. Ports
 
 | Service | Port |
@@ -494,7 +640,7 @@ There is no silent null.
   reachable"** means Lemonade isn't running or isn't reachable — not a bug in
   this package. Start it, or set `LEMONADE_BASE_URL`.
 - **`needs_confirmation` is followed by a refusal and the run ends.** See §8.
-  The seven gated tools are unreachable **over `/query`** — the agent itself can
+  The nine gated tools are unreachable **over `/query`** — the agent itself can
   run them on a transport that can prompt (SPEC §5.5).
 - **A placeholder hash in `binaries.lock.json` blocks the fetch before any
   network call.** Between releases that is the *expected* state — it is not a
@@ -516,9 +662,9 @@ There is no silent null.
   temp dir) is dropped, and a **shared** bin directory is moved to the end
   instead of removed, so the `python3` / `lemonade-server` / real `gaia` beside
   it stay reachable. If the Python CLI isn't installed anywhere, the daemon never
-  comes up. It must also be **0.23.1+**: an older core's daemon starts fine but
-  has no sidecar entry for this agent, which reads as a UI with a dead agent
-  rather than as a version problem.
+  comes up. It must also be **0.25.2+**: an older core's daemon starts fine but
+  cannot run this agent, which reads as a UI with a dead agent rather than as
+  a version problem.
 - **The TUI is installed as `gaia-tui`, never `gaia`** — the terminal-hub artifact
   *is* called `gaia-<platform>`, and a file named `gaia` in a cache directory would
   shadow the npm bin shim. The lock's `filename` and `executable` differ for that
@@ -547,7 +693,7 @@ Then, in another terminal:
 
 ```bash
 curl -s http://127.0.0.1:8141/health          # {"status":"ok","service":"gaia-agent-gaia"}
-curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.12","agentVersion":"0.1.1"}
+curl -s http://127.0.0.1:8141/version         # {"apiVersion":"2.24","agentVersion":"0.3.1"}
 curl -s http://127.0.0.1:8141/v1/gaia/init    # 200 + "ready":true, or 503 + a "hint"
 curl -N -X POST http://127.0.0.1:8141/v1/gaia/query \
   -H 'content-type: application/json' \
@@ -574,14 +720,17 @@ finish (or close an idle session) and retry the same `/query`.
 - **409 — the `run_id` is still in flight.** You mint it, so mint a fresh UUID
   per request; reusing one would leave the earlier run with no way to be
   cancelled.
-- **409 — `model` differs from what this `session_id` was built with.** Only
-  construction reads a model, so it cannot be applied to the retained agent.
-  Omit `model` to stay on the session's current one, or start a new
-  `session_id` to switch.
+- **409 — the model switch itself failed** (a missing Claude credential, an
+  unknown local model). The session stays on its previous model, so this is a
+  failed request rather than a broken session; `detail` names the reason.
 - **400 — the `Host` header is absent or empty.** The loopback check fails
   closed, so omitting the header is refused rather than served. Send
   `Host: 127.0.0.1:<port>`; every real HTTP client already does.
 
+**After cancelling a turn, send the next `/query` on that session straight
+away.** It is held until the stopped turn's model call returns (up to 240 s),
+then runs. A session whose running turn was NOT cancelled still answers `409`.
+
 For the full wire contract, lock schema, exit codes, and timeout table, see
 [`SPEC.md`](./SPEC.md). For the user-facing overview, see [`README.md`](./README.md)
 and <https://amd-gaia.ai/docs/guides/gaia>.
@@ -591,7 +740,26 @@ and <https://amd-gaia.ai/docs/guides/gaia>.
 The stdio TUI supports `/provider` for Local, Fireworks AI, and AMD LLM Gateway.
 Keys are entered in a masked field and sent directly to local Lemonade's runtime
 auth API, never as agent queries. `/model` lists supported discovered cloud and
-downloaded local models; `/model fireworks.gemma-4-31b-it` selects Gemma 4 31B IT
+downloaded local models, marking the configured default with `(default)`;
+`/model fireworks.gemma-4-31b-it` selects Gemma 4 31B IT
 when available. Cloud chat sends conversation history to the selected provider;
 embeddings remain on Lemonade. The status event names the actual provider and
 marks remote inference. This is a TUI/stdio capability, not an HTTP query command.
+
+## Developer engineering mode
+
+Available only when GAIA was started with `--developer-mode` (or
+`GAIA_DEVELOPER_MODE=1`). If the engineering tools are missing, say that developer
+mode is off; don't route around it with shell or file tools. When describing a
+handoff, claim only what happened:
+
+- Context was shared only after the user approved that exact snapshot in the prompt.
+  Approval can't be remembered, so each share or append asks again.
+- Opening the coding app never creates or submits a task, and for Codex it doesn't
+  prefill a prompt either. Never say the context was "posted" or "sent" to Codex;
+  give the user the directory and the prompt to paste.
+- Preview and test results come from the coding app. Report them as app-reported,
+  not as checks GAIA ran.
+- Revoking stops future reads; it cannot recall data already delivered.
+
+See the [usage guide](https://amd-gaia.ai/docs/guides/harness-engineering).