fmt: applied formatting

feat(rag): pluggable RagProvider abstraction with DuckDB and Qdrant drivers

.github/workflows/ci.yaml

@@ -36,6 +36,17 @@ jobs:
 
     - uses: Swatinem/rust-cache@v2
 
+    - name: Cache DuckDB Extensions
+      id: duckdb-extensions
+      uses: actions/cache@v4
+      with:
+        path: ~/.duckdb/extensions
+        key: duckdb-ext-${{ matrix.os }}-${{ hashFiles('Cargo.lock') }}
+
+    - name: Install DuckDB Extensions
+      if: steps.duckdb-extensions.outputs.cache-hit != 'true'
+      run: cargo test --all duckdb
+
     - name: Test
       run: cargo test --all
 

.gitignore

@@ -5,3 +5,4 @@
 .idea/
 /coyote.iml
 /.idea/
+.coyote

CHANGELOG.md

@@ -1,3 +1,49 @@
+## v0.8.3 (2026-08-03)
+
+### Fix
+
+- infinite loop bug when attempting to interrupt a prompt exchange right before a session compression
+- ctrl-c inside of an auto-continue loop created an infinite loop
+
+## v0.8.2 (2026-07-31)
+
+### Fix
+
+- sbx update doesn't allow undefined fields in sbx spec
+
+## v0.8.1 (2026-07-30)
+
+### Feat
+
+- ctrl-c interrupts ongoing prompt in a session, but lets the user inject more instructions mid-stream
+- improved function calling performance by allowing parallel tool calling
+- created the architect and gatekeeper agents for dramatically improved coding performance
+- Improved readability of session message exchange replays
+- apply --agent/--role/--rag/--model flags in --acp-server mode
+- add headless profile to sbx-kit spec
+- implement ACP user-interaction to request_permission bridge
+- implement ACP session/load and session/cancel
+- implement ACP session/prompt
+- add ACP server skeleton with stdout-purity test
+- add --headless flag for unattended operation
+
+### Fix
+
+- ctrl-c interruption doesn't discard session messages when throbber is showing
+- improper handling of fd-style globbing for directories in fs_glob
+- properly templated architect design doc path in starter commands
+- .copy works when sessions are resumed
+- ACP session/prompt now drives the full tool-execution loop
+- ACP spec conformance — ContentBlock prompt params and protocolVersion type
+- restore stdout output for standalone --headless mode
+- suppress tool-call display in headless mode; initialize session on session/new
+- skip stdin drain and set silent render mode when --acp-server is active
+- include graph-agent descriptions in .agent <TAB> completions
+
+### Refactor
+
+- move ACP server dispatch into run() for shared flag setup
+
 ## v0.8.0 (2026-07-25)
 
 ### Feat

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "coyote-ai"
-version = "0.8.0"
+version = "0.8.3"
 edition = "2024"
 authors = ["Alex Clarke <alex.j.tusa@gmail.com>"]
 description = "An all-in-one, batteries included LLM CLI Tool"
@@ -17,8 +17,9 @@ exclude = [".github", "CONTRIBUTING.md"]
 anyhow = "1.0.69"
 bytes = "1.4.0"
 clap = { version = "4.5.40", features = ["cargo", "derive", "wrap_help"] }
-comfy-table = { version = "7.2.2", features = ["custom_styling"] }
+comfy-table = { version = "7.1.4", features = ["custom_styling"] }
 dirs = "6.0.0"
+duckdb = { version = "1.10505.0", features = ["bundled"] }
 dunce = "1.0.5"
 futures-util = "0.3.29"
 inquire = "0.9.4"

Dockerfile

@@ -36,6 +36,21 @@ RUN set -euo pipefail; \
     install -m 0755 "$TMPDIR/usql_static" /usr/local/bin/usql; \
     rm -rf "$TMPDIR"
 
+RUN set -euo pipefail; \
+    DUCKDB_VERSION=1.5.5; \
+    case "${TARGETARCH}" in \
+      amd64) DUCKDB_ARCH=amd64 ;; \
+      arm64) DUCKDB_ARCH=arm64 ;; \
+      *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    TMPDIR=$(mktemp -d); \
+    curl -fsSL --retry 3 \
+      "https://github.com/duckdb/duckdb/releases/download/v${DUCKDB_VERSION}/duckdb_cli-linux-${DUCKDB_ARCH}.gz" \
+      -o "$TMPDIR/duckdb.gz"; \
+    gunzip "$TMPDIR/duckdb.gz"; \
+    install -m 0755 "$TMPDIR/duckdb" /usr/local/bin/duckdb; \
+    rm -rf "$TMPDIR"
+
 USER 1000
 
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \

README.md

@@ -70,6 +70,8 @@ Coyote requires the following tools to be installed on your system:
     * **Cargo:** `cargo install ast-grep --locked`
     * **npm:** `npm i -g @ast-grep/cli`
     * Optional: if `ast-grep` is not installed, the `ast_grep` tool reports it and agents fall back to `fs_grep`
+* [duckdb](https://duckdb.org/) (for fast, local RAGs)
+    * `curl https://install.duckdb.org | sh`
 
 These tools are used to provide various functionalities within Coyote, such as document processing, JSON manipulation,
 etc., and they are used within agents and tools.

assets/agents/.shared/utils.sh

@@ -40,15 +40,57 @@ _write_project_cache() {
 _detect_heuristic() {
   local dir="$1"
 
+  local runner="" runner_type="" runner_targets=""
+  if [[ -f "${dir}/Taskfile.yml" || -f "${dir}/Taskfile.yaml" || -f "${dir}/taskfile.yml" || -f "${dir}/taskfile.yaml" ]]; then
+    runner="task" runner_type="taskfile"
+    runner_targets=$( (cd "${dir}" && task --list-all 2>/dev/null | sed -n 's/^\* \([^:[:space:]]*\):.*/\1/p') || true)
+  elif [[ -f "${dir}/justfile" || -f "${dir}/Justfile" ]]; then
+    runner="just" runner_type="just"
+    runner_targets=$( (cd "${dir}" && just --summary 2>/dev/null | tr ' ' '\n') || true)
+  elif [[ -f "${dir}/Makefile" || -f "${dir}/makefile" || -f "${dir}/GNUmakefile" ]]; then
+    runner="make" runner_type="make"
+    local mk mkfiles=()
+    for mk in Makefile makefile GNUmakefile; do
+      [[ -f "${dir}/${mk}" ]] && mkfiles+=("${dir}/${mk}")
+    done
+    runner_targets=$(sed -n 's/^\([A-Za-z0-9_][A-Za-z0-9_.-]*\):\([^=].*\|\)$/\1/p' "${mkfiles[@]}" 2>/dev/null | sort -u || true)
+  fi
+  if [[ -n "${runner}" && -n "${runner_targets}" ]]; then
+    _pick_target() {
+      local c
+      for c in "$@"; do
+        if grep -qx "${c}" <<<"${runner_targets}"; then
+          echo "${runner} ${c}"
+          return 0
+        fi
+      done
+      echo ""
+    }
+    local r_build r_test r_check r_lint r_fmt
+    r_build=$(_pick_target build compile)
+    r_test=$(_pick_target test tests unit)
+    r_check=$(_pick_target check vet typecheck build)
+    r_lint=$(_pick_target lint fmt-check)
+    r_fmt=$(_pick_target fmt format)
+    if [[ -n "${r_build}${r_test}${r_check}${r_lint}${r_fmt}" ]]; then
+      echo "{\"type\":\"${runner_type}\",\"build\":\"${r_build}\",\"test\":\"${r_test}\",\"check\":\"${r_check}\",\"lint\":\"${r_lint}\",\"fmt\":\"${r_fmt}\"}"
+      return 0
+    fi
+  fi
+
   # Rust
   if [[ -f "${dir}/Cargo.toml" ]]; then
-    echo '{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check"}'
+    echo '{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check","lint":"cargo clippy --no-deps -- -D warnings","fmt":"cargo fmt"}'
     return 0
   fi
 
   # Go
   if [[ -f "${dir}/go.mod" ]]; then
-    echo '{"type":"go","build":"go build ./...","test":"go test ./...","check":"go vet ./..."}'
+    local go_lint=""
+    if compgen -G "${dir}/.golangci.*" &>/dev/null && command -v golangci-lint &>/dev/null; then
+      go_lint="golangci-lint run"
+    fi
+    echo "{\"type\":\"go\",\"build\":\"go build ./...\",\"test\":\"go test ./...\",\"check\":\"go vet ./...\",\"lint\":\"${go_lint}\",\"fmt\":\"gofmt -w .\"}"
     return 0
   fi
 
@@ -65,7 +107,25 @@ _detect_heuristic() {
     [[ -f "${dir}/pnpm-lock.yaml" ]] && pm="pnpm"
     [[ -f "${dir}/yarn.lock" ]] && pm="yarn"
 
-    echo "{\"type\":\"nodejs\",\"build\":\"${pm} run build\",\"test\":\"${pm} test\",\"check\":\"${pm} run lint\"}"
+    # Emit only scripts the manifest actually declares (same introspection
+    # contract as the runner tier: never guess a target into existence).
+    _pkg_script() {
+      local s
+      for s in "$@"; do
+        if jq -e --arg s "$s" '.scripts[$s] // empty' "${dir}/package.json" &>/dev/null; then
+          echo "${pm} run ${s}"
+          return 0
+        fi
+      done
+      echo ""
+    }
+    local p_build p_test p_check p_lint p_fmt
+    p_build=$(_pkg_script build compile)
+    p_test=$(_pkg_script test)
+    p_check=$(_pkg_script check typecheck tsc)
+    p_lint=$(_pkg_script lint)
+    p_fmt=$(_pkg_script fmt format prettier)
+    echo "{\"type\":\"nodejs\",\"build\":\"${p_build}\",\"test\":\"${p_test}\",\"check\":\"${p_check}\",\"lint\":\"${p_lint}\",\"fmt\":\"${p_fmt}\"}"
     return 0
   fi
 
@@ -82,7 +142,7 @@ _detect_heuristic() {
       check_cmd="uv run ruff check ."
     fi
 
-    echo "{\"type\":\"python\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"${check_cmd}\"}"
+    echo "{\"type\":\"python\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"${check_cmd}\",\"lint\":\"${check_cmd}\",\"fmt\":\"ruff format .\"}"
     return 0
   fi
 
@@ -144,17 +204,6 @@ _detect_heuristic() {
     return 0
   fi
 
-  # Generic build systems (last resort before LLM)
-  if [[ -f "${dir}/justfile" ]] || [[ -f "${dir}/Justfile" ]]; then
-    echo '{"type":"just","build":"just build","test":"just test","check":"just lint"}'
-    return 0
-  fi
-
-  if [[ -f "${dir}/Makefile" ]] || [[ -f "${dir}/makefile" ]] || [[ -f "${dir}/GNUmakefile" ]]; then
-    echo '{"type":"make","build":"make build","test":"make test","check":"make lint"}'
-    return 0
-  fi
-
   return 1
 }
 
@@ -218,7 +267,9 @@ _detect_with_llm() {
   local prompt
   prompt=$(cat <<-EOF
 
-		Analyze this project directory and determine the project type, primary language, and the correct shell commands to build, test, and check (lint/typecheck) it.
+		Analyze this project directory and determine the project type, primary language, and the correct shell commands to build, test, check (typecheck/vet), lint, and format it.
+
+		PRIORITY RULE: if the project declares its own task-runner interface (a Taskfile, justfile, Makefile, package.json scripts, or similar), those declared targets ARE the correct commands — prefer them over generic ecosystem defaults, and never invent a target the interface does not declare.
 
 		EOF
 	)
@@ -226,12 +277,12 @@ _detect_with_llm() {
   prompt+=$(cat <<-EOF
 
 		Respond with ONLY a valid JSON object. No markdown fences, no explanation, no extra text.
-		The JSON must have exactly these 4 keys:
-		{"type":"<language>","build":"<build command>","test":"<test command>","check":"<lint or typecheck command>"}
+		The JSON must have exactly these 6 keys:
+		{"type":"<language>","build":"<build command>","test":"<test command>","check":"<typecheck/vet command>","lint":"<lint command>","fmt":"<format command>"}
 
 		Rules:
 		- "type" must be a single lowercase word (e.g. rust, go, python, nodejs, java, ruby, elixir, cpp, c, zig, haskell, scala, kotlin, dart, swift, php, dotnet, etc.)
-		- If a command doesn't apply to this project, use an empty string, ""
+		- If a command doesn't apply to this project, use an empty string, "" — NEVER guess a command that might not exist; a wrongly-guessed command is worse than an empty one
 		- Use the most standard/common commands for the detected ecosystem
 		- If you detect a package manager lockfile, use that package manager (e.g. pnpm over npm)
 		EOF
@@ -244,7 +295,7 @@ _detect_with_llm() {
   llm_response=$(echo "${llm_response}" | grep -o '{[^}]*}' | head -1)
 
   if echo "${llm_response}" | jq -e '.type and .build != null and .test != null and .check != null' &>/dev/null; then
-    echo "${llm_response}" | jq -c '{type: (.type // "unknown"), build: (.build // ""), test: (.test // ""), check: (.check // "")}'
+    echo "${llm_response}" | jq -c '{type: (.type // "unknown"), build: (.build // ""), test: (.test // ""), check: (.check // ""), lint: (.lint // ""), fmt: (.fmt // "")}'
     return 0
   fi
 
@@ -258,7 +309,7 @@ detect_project() {
 
   local cached
   if cached=$(_read_project_cache "${dir}"); then
-    echo "${cached}" | jq -c '{type, build, test, check}'
+    echo "${cached}" | jq -c '{type, build, test, check, lint: (.lint // ""), fmt: (.fmt // "")}'
     return 0
   fi
 
@@ -286,6 +337,31 @@ detect_project() {
   echo '{"type":"unknown","build":"","test":"","check":""}'
 }
 
+# resolve_gate_dir maps a workspace root to the directory verification gates
+# must run in. A delivery-repo worker's workspace root holds only dotfiles
+# plus the clone, so gates aimed at the root detect nothing and silently
+# no-op. When the root has no project markers and exactly ONE first-level
+# git repo exists, gates run inside it; anything ambiguous stays at the root.
+resolve_gate_dir() {
+  local dir="${1:-.}"
+  local m
+  for m in Taskfile.yml Taskfile.yaml taskfile.yml Cargo.toml go.mod package.json pyproject.toml setup.py pom.xml build.gradle mix.exs Gemfile composer.json Makefile justfile Justfile CMakeLists.txt; do
+    if [[ -e "${dir}/${m}" ]]; then
+      echo "${dir}"
+      return 0
+    fi
+  done
+  local repos=() d
+  for d in "${dir}"/*/; do
+    [[ -d "${d}/.git" ]] && repos+=("${d}")
+  done
+  if [[ ${#repos[@]} -eq 1 ]]; then
+    echo "${repos[0]%/}"
+    return 0
+  fi
+  echo "${dir}"
+}
+
 ###########################
 ## FILE SEARCH UTILITIES ##
 ###########################

assets/agents/adversary/config.yaml

@@ -50,7 +50,7 @@ instructions: |
   You are given:
   1. **The diff** — pasted inline, or run `get_diff` (optionally `--base <ref>`) if told to fetch it.
   2. **The plan** — the task's Objective, Tasks, and especially its **Acceptance criteria**, pasted
-     inline (e.g. a BCP task `index.md` body + the relevant `PLAN-*.md` section), or a path to read.
+     inline (e.g. a task file's What/Steps/Acceptance criteria + the relevant plan section), or a path to read.
 
   If the plan / acceptance criteria are missing, STOP and say so: conformance cannot be judged
   without a spec. Do not invent criteria or guess intent.

assets/agents/architect/README.md

@@ -0,0 +1,182 @@
+# Architect
+
+A **design-doc orchestrator for any project**. Give it one high-level design doc; it decomposes the
+doc into a quality-gated plan and ~1-engineer-day task files, spawns **one
+[Sisyphus](../sisyphus/README.md) per task** on a single run branch, verifies each task with an
+adversarial plan-conformance check, and finishes with **one draft PR** (CI checks watched to green)
+plus tracked follow-up tasks for the manual work the code can't do for itself.
+
+Architect does **not** write feature code itself. It owns the *process*; Sisyphus owns each *task*.
+
+## The pipeline it drives
+
+```mermaid
+flowchart TD
+    user([Design doc]) --> architect["Architect<br/>design-doc orchestrator"]
+    architect --> orient["Phase A — Orient<br/>project conventions · build/test commands · design doc"]
+    orient --> design["Phase B — design-session<br/>plans_dir/PLAN-&lt;slug&gt;.md + 1-day task breakdown"]
+
+    design -. "grounding" .-> explore[["explore<br/>codebase grep<br/>× parallel"]]
+    design -. "unfamiliar libraries" .-> librarian[["librarian<br/>docs + OSS grep"]]
+    explore -. "findings ground<br/>the breakdown" .-> design
+    librarian -. "findings ground<br/>the breakdown" .-> design
+
+    design --> gatekeeper[["gatekeeper<br/>self-containedness audit<br/>(docker-container test)"]]
+    gatekeeper --> g1{"PLAN_GATE?"}
+    g1 -->|"LEAKY (≤ 2 cycles)"| amend["Answer the missing questions<br/>via explore / librarian / docs<br/>(user__ask only for business rules)<br/>→ amend the plan"]
+    amend --> gatekeeper
+    g1 -->|"LEAKY after 2 cycles"| escalate
+    g1 -->|"SEALED"| oracle[["oracle<br/>plan-review<br/>(executability)"]]
+
+    oracle --> g2{"PLAN_REVIEW?"}
+    g2 -->|"REJECT — fix complaints,<br/>re-submit SAME session"| oracle
+    g2 -->|"OKAY"| tasks["Phase D — materialize tasks<br/>plans_dir/tasks/TASK-NNN-*/ (task-tracking)"]
+
+    tasks --> branch["Phase E — run branch<br/>feat/PLAN-&lt;slug&gt; off base_branch"]
+    branch --> claim["Claim task (sequential, dependency order)<br/>status: in-progress + base SHA"]
+    claim --> sisyphus[["sisyphus<br/>implement ONE task on the run branch<br/>commit + push — NO PR"]]
+    sisyphus --> adversary[["adversary<br/>conformance check<br/>diff vs task base SHA"]]
+
+    adversary --> verdict{"ADVERSARIAL_REVIEW?"}
+    verdict -->|"DIVERGES — resume<br/>SAME sisyphus session (once)"| sisyphus
+    verdict -->|"still DIVERGES"| escalate
+    verdict -->|"CONFORMS"| taskdone["Close task<br/>status: complete · log commits + follow-ups"]
+
+    taskdone --> more{"More tasks?"}
+    more -->|"yes"| claim
+    more -->|"no"| finish["Phase F — full build + tests<br/>on the integrated run branch"]
+
+    finish --> pr["ONE DRAFT PR: run branch → base_branch<br/>(never marked ready — user reviews first)<br/>body: task checklist + Follow-up / manual actions"]
+    pr --> checks{"PR runs/checks<br/>green?"}
+    checks -->|"failure — resume responsible<br/>sisyphus session, fix, push"| checks
+    checks -->|"external flake /<br/>broken base branch"| escalate
+    checks -->|"green"| followups["Create follow-up task files<br/>(type: followup, pending)<br/>→ picked up by the user post-merge"]
+    followups --> backfill["Backfill PR link into PLAN + task logs<br/>PLAN status: implemented"]
+    backfill --> validate["task-tracking consistency checks"]
+    validate --> done([Run complete])
+
+    escalate([user__ask — escalate to user])
+
+    branch -. "parallel_tasks=1 (opt-in):<br/>per-task worktrees + task branches,<br/>merged one at a time with<br/>integration tests after every merge" .-> claim
+```
+
+## Where state lives
+
+Everything is file-based in **`plans_dir`** (default `plans/`, resolved against the project):
+
+```
+<plans_dir>/
+  PLAN-<slug>.md                  # problem / approach / alternatives / task breakdown
+  tasks/TASK-NNN-<slug>/
+    index.md                      # What / Steps / Acceptance criteria; status in frontmatter
+    log.md                        # append-only audit trail (branch, commits, follow-ups, PR)
+```
+
+- `plans_dir` **inside the repo** (default) → planning files ride the run branch and land in the PR
+  (self-documenting review).
+- `plans_dir` **absolute, outside the repo** (e.g. a common runs directory) → nothing planning-related
+  is ever committed.
+
+Disk is the durable store: task statuses, logs, and follow-ups survive context compression; chat
+history does not.
+
+## The three review gates
+
+| Gate | Agent | Question | When |
+|------|-------|----------|------|
+| Self-containedness | [`gatekeeper`](../gatekeeper/README.md) | "Can a context-free LLM implement from this plan alone?" | Before tasks exist |
+| Executability | `oracle` + `plan-review` | "Is the approach sound, verifiable, correctly ordered?" | After sealing |
+| Conformance | [`adversary`](../adversary/README.md) | "Is the built code what the plan asked for?" | After each task |
+
+## Key conventions it enforces
+
+- **One task = one engineer-day** — anything larger gets decomposed at the design stage.
+- **Task state on disk** — `status:` frontmatter lifecycle per the `task-tracking` skill; no state
+  lives only in chat.
+- **One run branch, one draft PR** — `feat/PLAN-<slug>` off `base_branch`; the PR is never opened
+  per-task, never non-draft, never marked ready-for-review (you flip it yourself).
+- **CI checks watched to green** — failures are routed back to the responsible Sisyphus session; the
+  run isn't done with red or pending checks.
+- **No plan references in code comments** — comments never cite the design doc, plan, phases, steps,
+  or TASK numbers (docs drift; comments rot). Plan references live in commit messages only.
+- **`.env` never lands in a repo** — only `.env.example` with placeholder keys; real values become a
+  follow-up.
+- **Follow-ups are tracked, never dropped** — every manual action (secrets, cloud roles, console
+  steps, cross-repo changes) is reported per task, logged durably, rolled into the PR's
+  `## Follow-up / manual actions` section (pre-merge items first), and materialized as
+  `type: followup` task files for you to pick up post-merge.
+
+## Usage
+
+```sh
+# From the target project root (default autonomy: full)
+coyote -a architect --agent-variable design_doc docs/design/my-feature.md \
+  "Implement this design doc end to end"
+
+# Approve the task breakdown once, then run autonomously
+coyote -a architect \
+  --agent-variable design_doc docs/design/my-feature.md \
+  --agent-variable autonomy plan-gate \
+  "Decompose and implement"
+
+# Different project / plans outside the repo / PR against a non-main base
+coyote -a architect \
+  --agent-variable project_dir ~/code/my-service \
+  --agent-variable plans_dir ~/architect-runs/my-service \
+  --agent-variable base_branch develop \
+  --agent-variable design_doc ~/docs/big-refactor.md \
+  "Run the pipeline"
+```
+
+### Variables
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `project_dir` | `.` | The target repo — the only WRITE target for feature code. |
+| `plans_dir` | `plans` | Where PLAN + task files live. Relative → in-repo (rides the PR); absolute → outside git. |
+| `design_doc` | *(empty)* | Path to the design doc; asked for if unset. |
+| `base_branch` | `main` | Branch the run branch forks from and the PR targets. |
+| `autonomy` | `full` | `full` (no gates) · `plan-gate` (approve breakdown once) · `phase-gate` (approve each task). |
+| `parallel_tasks` | `0` | `0` = sequential (default) · `1` = opt-in worktree-parallel execution for eligible tasks. |
+| `auto_confirm` | `1` | Skip the shell confirm guard (needed for non-interactive autonomous runs). |
+
+## Autonomy
+
+Fully autonomous end-to-end by default — it halts only for genuine blockers: scope-changing
+ambiguity or unresolved design questions, a task that fails after Sisyphus's own recovery (consults
+Oracle, then escalates), and any destructive/irreversible action. Use `plan-gate` or `phase-gate`
+to insert approval checkpoints.
+
+## Parallel task execution (opt-in)
+
+By default (`parallel_tasks: 0`) tasks run **sequentially** on the single run branch. Setting
+`parallel_tasks: 1` enables worktree-based parallelism:
+
+- Eligible tasks (mutually unblocked, plan-declared file-disjoint, max 3 concurrent) each get an
+  isolated `git worktree` + task branch forked from the run branch tip.
+- Tasks touching **migrations, generated code, or dependency manifests/lockfiles** are never
+  parallel-eligible — shared hotspots collide even when the plan calls tasks independent.
+- Architect integrates: completed task branches merge into the run branch **one at a time**, with a
+  full build + test run after every merge. Conflicts go back to that task's Sisyphus session to
+  rebase and re-verify.
+- Worktrees and task branches are cleaned up after each clean merge. Phase F (single draft PR +
+  CI-check watch) is unchanged in both modes.
+
+## Sub-agents it spawns
+
+| Agent | Used for |
+|-------|----------|
+| [`sisyphus`](../sisyphus/README.md) | Implement ONE task's code (its own explore→coder→verify→review loop). One per task. |
+| [`gatekeeper`](../gatekeeper/README.md) | Plan self-containedness gate (`PLAN_GATE: SEALED/LEAKY`). |
+| [`adversary`](../adversary/README.md) | Per-task plan-conformance verdict (`ADVERSARIAL_REVIEW: CONFORMS/DIVERGES`). |
+| [`oracle`](../oracle/README.md) | Plan review (`plan-review`); diagnosis when a task fails after Sisyphus recovery. |
+| [`explore`](../explore/README.md) | Ground the design/plan in real code; read other local repos for library usage and call sites. |
+| [`librarian`](../librarian/README.md) | External docs / OSS examples for unfamiliar libraries. |
+
+## Related skills
+
+- [`design-session`](../../skills/design-session/SKILL.md) — design doc → grounded proposal → PLAN + sized breakdown.
+- [`task-tracking`](../../skills/task-tracking/SKILL.md) — the task-file schema, lifecycle, and consistency checks.
+- [`plan-gatekeeping`](../../skills/plan-gatekeeping/SKILL.md) — the gatekeeper's self-containedness manifest.
+- [`plan-authoring`](../../skills/plan-authoring/SKILL.md) / [`plan-review`](../../skills/plan-review/SKILL.md) — plan schema + oracle's executability review.
+- [`adversarial-review`](../../skills/adversarial-review/SKILL.md) — the adversary's conformance methodology.

assets/agents/architect/config.yaml

@@ -0,0 +1,460 @@
+name: architect
+description: |
+  Design-doc orchestrator for any project. Consumes a high-level design doc, decomposes it into a
+  gated plan (gatekeeper self-containedness + oracle plan-review) and ~1-engineer-day task files,
+  spawns one Sisyphus per task on a single run branch, verifies each with an adversarial
+  plan-conformance check, and finishes with ONE draft PR (CI checks watched to green) plus tracked
+  follow-up tasks. Task state lives on disk in a plans directory, so runs survive context compression.
+version: 2.0.0
+agent_session: temp
+auto_continue: true
+max_auto_continues: 100
+inject_todo_instructions: true
+
+can_spawn_agents: true
+spawnable_agents:
+  - sisyphus
+  - oracle
+  - explore
+  - librarian
+  - adversary
+  - gatekeeper
+max_concurrent_agents: 10
+max_agent_depth: 10
+inject_spawn_instructions: true
+summarization_threshold: 100000
+
+skills_enabled: true
+enabled_skills:
+  - design-session
+  - task-tracking
+  - plan-authoring
+  - delegation-protocol
+  - git-master
+  - parallel-research
+
+variables:
+  - name: project_dir
+    description: Absolute path to the target project repo — the ONLY write target for feature code
+    default: '.'
+  - name: plans_dir
+    description: Where the PLAN file and task dirs live. Relative paths resolve against project_dir (and then ride the run branch into the PR); an absolute path outside the repo keeps planning files out of git entirely.
+    default: 'plans'
+  - name: design_doc
+    description: Path to the high-level design doc to implement (absolute, or relative to project_dir)
+    default: ''
+  - name: base_branch
+    description: The branch the run branch forks from and the PR targets
+    default: 'main'
+  - name: autonomy
+    description: 'How autonomous the run is: full (no gates), plan-gate (approve breakdown once, then autonomous), phase-gate (approve each task)'
+    default: full
+  - name: auto_confirm
+    description: Auto-confirm command execution (1 = skip the shell guard_operation TTY prompt, needed for non-interactive autonomous runs)
+    default: '1'
+  - name: parallel_tasks
+    description: 'Opt-in worktree-based parallel task execution: 0 = sequential (default, one task at a time on the run branch), 1 = eligible tasks run as concurrent Sisyphus agents in isolated git worktrees, merged back one at a time'
+    default: '0'
+
+global_tools:
+  - ast_grep.sh
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - fs_patch.sh
+  - fs_mkdir.sh
+  - execute_command.sh
+
+instructions: |
+  You are **Architect** — an orchestrator that takes a single high-level design doc and drives it
+  end-to-end to implementation on ANY project. You do NOT write feature code yourself. You decompose,
+  gate the plan, delegate one task to one **Sisyphus** sub-agent, verify conformance, track state on
+  disk, and finish with a single draft PR — repeating until the entire design doc is implemented.
+
+  ## Ground rules — READ BEFORE ANYTHING
+
+  **Write target.** ALL feature code goes in {{project_dir}}. You and your sub-agents MAY freely READ
+  other local repos/directories (internal libraries, legacy patterns, call sites, shared contracts)
+  — reading is encouraged; WRITING anywhere but {{project_dir}} is a scope violation. If the design
+  genuinely requires writing outside {{project_dir}}, STOP and escalate; likely it's a follow-up.
+
+  **Git model — one run branch, one draft PR.** All work lands on a single RUN BRANCH
+  (`feat/PLAN-<slug>`, forked from {{base_branch}}), and exactly ONE DRAFT PR is opened at the END of
+  the run (Phase F) covering the entire design doc — NEVER one PR per task, NEVER a push to
+  {{base_branch}}. Before any `git push`/branch/PR, confirm you are in {{project_dir}}
+  (`git remote get-url origin`).
+
+  **Task state lives on disk.** {{plans_dir}} (relative → resolved against {{project_dir}}, riding
+  the run branch into the PR; absolute → outside git entirely) holds `PLAN-<slug>.md` and
+  `tasks/TASK-NNN-*/`. The `task-tracking` skill defines the schema and lifecycle — load it before
+  touching task files. Disk is your durable store; chat history is not.
+
+  **Read the project's own conventions at startup** — `CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING.md`
+  at the project root. When this prompt and those files disagree on project conventions, the
+  project's files win; note the discrepancy to the user.
+
+  ## Autonomy mode: {{autonomy}}
+
+  - **full** — run the entire pipeline with no approval gates. Only stop for a genuine blocker
+    (ambiguity that changes scope, a task that fails after Sisyphus's own recovery, missing critical
+    info, any destructive action). This is the default.
+  - **plan-gate** — after the breakdown is SEALED + OKAY'd, present it ONCE via `user__confirm`
+    before creating any tasks. Then run all tasks autonomously.
+  - **phase-gate** — present each task's result via `user__confirm` before starting the next.
+
+  Even in `full`, you MUST still stop for: scope-changing ambiguity, a task that fails after
+  Sisyphus's own recovery, and any destructive action (`rm -rf`, force-push, dropping data, deleting
+  branches). Exception: in parallel mode, removing a task's worktree and deleting its task branch
+  AFTER its merge landed and integration tests passed is routine documented cleanup, not a
+  destructive action.
+
+  ## The pipeline (drive this to completion)
+
+  ### Phase A — Orient (once, at startup)
+
+  1. Run `date -u '+%Y-%m-%d %H:%M:%S %Z (%A)'` — trust the shell clock, not the prompt date.
+  2. In {{project_dir}}: `git pull` on {{base_branch}}; read the project's orientation docs
+     (`CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING.md` / `README.md`) and note build/test commands.
+  3. Read the design doc ({{design_doc}} if set; otherwise ask the user for the path).
+  4. `skill__list`, then load `design-session` and `plan-authoring` for decomposition, and
+     `task-tracking` before any task files exist.
+  5. Build a durable todo list — one item per pipeline stage and, once tasks exist, one per TASK-NNN.
+     Embed spawned session_ids in todo text (e.g. `todo__add "Implement TASK-002 (sisyphus
+     ses_abc123)"`) so they survive context compression.
+
+  ### Phase B — Design decomposition
+
+  Load and follow the `design-session` skill against the design doc. This produces
+  `{{plans_dir}}/PLAN-<slug>.md` with Problem, Scope, Approach, Alternatives, Constraints/risks,
+  Open questions, and a **Task breakdown** where **each task is sized to ~1 engineer-day** (decompose
+  anything bigger NOW).
+
+  Ground the breakdown in real code: fan out `explore` agents (load `parallel-research`) across
+  {{project_dir}} — and `librarian` for unfamiliar external libraries — to confirm the design's
+  assumptions before sizing. Do NOT guess file/symbol names — verify them.
+
+  In `full` autonomy, if the design session surfaces open questions you cannot answer from the doc or
+  the codebase, ask the user (`user__ask`); an unresolved question that changes scope is a hard stop
+  even in `full`.
+
+  ### Phase C — Plan quality gates (BOTH mandatory before any tasks)
+
+  Two independent gates, in order. A plan is finalized ONLY when it is both SEALED and OKAY.
+
+  **Gate 1 — Self-containedness (`gatekeeper`).** The plan must pass the "docker container" test:
+  every question a context-free implementer will hit is answered inline or delegated via a verified
+  pointer to code/docs (where infra code goes, DB tech/target, layout to mirror, test commands, ...).
+
+  > `agent__spawn --agent gatekeeper --prompt "Audit this plan for self-containedness. Return
+  > SEALED/LEAKY. Plan: {{plans_dir}}/PLAN-<slug>.md. Target project: {{project_dir}}."`
+
+  On **`PLAN_GATE: LEAKY`**: ANSWER every missing question yourself — fan out `explore`/`librarian`,
+  read the referenced docs, and only `user__ask` for questions that genuinely cannot be answered from
+  code/docs (business rules, priority calls). Amend the PLAN with the answers (inline or as verified
+  pointers), then re-submit to the SAME gatekeeper session (`agent__spawn --session_id <id>`). Still
+  LEAKY on the SAME questions after 2 amend cycles → STOP and escalate. FRICTION-only verdicts: you
+  may seal at your discretion — note the accepted findings in the plan.
+
+  On **`PLAN_GATE: SEALED`**: proceed to Gate 2.
+
+  **Gate 2 — Executability (`oracle` + `plan-review`).** Runs AFTER sealing, so oracle reviews the
+  amended, self-contained plan:
+
+  > `agent__spawn --agent oracle --prompt "Load skills plan-review and plan-authoring. Review the
+  > plan at {{plans_dir}}/PLAN-<slug>.md — its task breakdown and approach — for ground-truth
+  > accuracy against {{project_dir}}, one-engineer-day sizing, dependency ordering, and
+  > verifiability. Return PLAN_REVIEW: OKAY or REJECT with line-referenced complaints."`
+
+  On **REJECT**: fix the specific complaints and re-submit to the SAME oracle session. If a fix
+  materially changes the plan's context, re-run the gatekeeper once on the amended plan.
+  On **OKAY**: set the PLAN's frontmatter `status: active` and proceed. (`plan-gate` autonomy:
+  present the SEALED+OKAY'd breakdown to the user here.)
+
+  Do not materialize tasks from a plan that is unsealed, unreviewed, or rejected.
+
+  ### Phase D — Materialize tasks
+
+  Load `task-tracking`. For each row of the approved breakdown, create
+  `{{plans_dir}}/tasks/TASK-NNN-<slug>/` (`index.md` with What/Steps/Acceptance criteria derived
+  from the plan, `status: pending`, `blocked_by` from the breakdown; `log.md` with a `created`
+  entry). Numbering per the skill (scan max+1). Add one todo item per task, in dependency order.
+  If {{plans_dir}} is inside {{project_dir}}, commit the planning files once the run branch exists
+  (they ride the PR); keep planning commits separate from feature commits (`chore(plan): ...`).
+
+  ### Phase E — Per-task implementation loop (one Sisyphus per task)
+
+  For each task, respecting `blocked_by` ordering (a blocked task waits for its blockers to reach
+  `status: complete`):
+
+  0. **Create the RUN BRANCH (once, before the FIRST task).** In {{project_dir}}:
+     `git checkout {{base_branch}} && git pull && git checkout -b feat/PLAN-<slug> && git push -u
+     origin feat/PLAN-<slug>`. Record the branch name in a todo item. If it already exists (resumed
+     run), `git checkout` + `git pull` instead — never recreate it.
+
+  1. **Claim it.** Per `task-tracking`: `status: in-progress`, log `started`. Record the task's BASE
+     SHA — `git -C {{project_dir}} rev-parse HEAD` on the run branch — in the todo item AND the
+     `started` log entry; the adversary needs it to diff THIS task's work in isolation.
+
+  2. **Delegate the CODE work to ONE Sisyphus.** Load `delegation-protocol`, then spawn with a
+     self-contained prompt — Sisyphus has NOT seen this conversation:
+
+     ```
+     agent__spawn --agent sisyphus --prompt "
+     ## TASK
+     Implement TASK-NNN (<title>) in the project at {{project_dir}}. This is one one-engineer-day
+     slice of PLAN-<slug>. ALL code you WRITE goes in {{project_dir}}. You MAY freely READ other
+     local repos/directories to understand internal libraries, legacy patterns, call sites, and
+     conventions — just do not write to them.
+
+     ## SOURCE OF TRUTH
+     - Task file: {{plans_dir}}/tasks/TASK-NNN-<slug>/index.md (read its What / Steps / Acceptance
+       criteria — implement EXACTLY these, nothing more)
+     - Plan: {{plans_dir}}/PLAN-<slug>.md
+     - Conventions: the project's CLAUDE.md / AGENTS.md / CONTRIBUTING.md — READ BEFORE CODING.
+
+     ## EXPECTED OUTCOME
+     Every acceptance criterion met; build + full test suite green in {{project_dir}}; the work
+     committed and pushed to the EXISTING run branch feat/PLAN-<slug> (already checked out). Do NOT
+     open a PR — one draft PR for the whole design doc is opened at the end of the run by the
+     orchestrator.
+
+     ## MUST DO
+     - Work on the CURRENT branch (feat/PLAN-<slug>). git pull before starting.
+     - Match the project's existing patterns and conventions.
+     - Derive tests from the task's Acceptance criteria.
+     - Commit with messages referencing the task ID (e.g. "feat(TASK-NNN): ..."), push to the run
+       branch, and report the commit SHA(s).
+     - End your final summary with a "FOLLOW-UPS:" section listing every manual or out-of-scope
+       action this work requires that you could NOT perform yourself — secrets to create, cloud
+       roles/policies to provision (especially in OTHER repos), console steps, per-environment
+       config, teams to coordinate with. One line each: WHAT, WHERE (repo/system), WHY, and WHEN
+       (pre-merge / post-merge / post-deploy). Write "FOLLOW-UPS: none" if there are none. Do NOT
+       attempt these yourself and do NOT silently skip them.
+
+     ## MUST NOT DO
+     - Do NOT open a PR. Do NOT create or switch branches. Do NOT merge or rebase onto {{base_branch}}.
+     - Do NOT reference the plan, design doc, phases, steps, or TASK numbers in CODE COMMENTS
+       (e.g. "// Phase 2 of PLAN-foo", "// per step 3", "// TASK-002"). Docs change over time, so
+       such comments rot into opaque noise. Comments explain the code on its own terms; plan
+       references belong in COMMIT MESSAGES, which are immutable history.
+     - NEVER commit a `.env` file to ANY repo. If the work needs env config, commit a `.env.example`
+       with placeholder keys (no real values) and ensure `.env` is gitignored. Provisioning the real
+       values is a FOLLOW-UPS item, not a commit.
+     - Do NOT implement other tasks' scope. Do NOT edit files under {{plans_dir}}.
+     - Do NOT write code outside {{project_dir}} (reading elsewhere is fine).
+     - Do NOT push to {{base_branch}}. Do NOT suppress errors or delete failing tests.
+     - Do NOT diverge from the task's stated scope; if the plan is wrong, STOP and report back.
+
+     ## CONTEXT
+     <paste the task's index.md body and the relevant PLAN section here verbatim — plus any code
+     snippets explore found showing the patterns to follow>
+     "
+     ```
+
+     Record the returned `session_id` in the task's todo item immediately.
+
+  3. **Wait for Sisyphus.** Do not poll `agent__collect` on a running agent — do non-overlapping work
+     (e.g. prep the next task's context) or end your response and wait for the completion
+     notification, then `agent__collect`.
+
+  4. **Verify against the plan (divergence check).** When Sisyphus returns, do NOT trust its
+     self-report — get an INDEPENDENT conformance verdict:
+     - **Spawn `adversary`** with the diff base and the criteria pasted in:
+
+       ```
+       agent__spawn --agent adversary --prompt "Adversarially review the changes for TASK-NNN against
+       its plan. Return CONFORMS/DIVERGES.
+
+       DIFF: run get_diff --base <the task's BASE SHA recorded at claim time> in {{project_dir}} —
+       this isolates THIS task's commits on the shared run branch from earlier tasks' work.
+
+       PLAN — acceptance criteria to check against:
+       <paste the task index.md body + the relevant PLAN-<slug>.md section VERBATIM>"
+       ```
+
+     - **`ADVERSARIAL_REVIEW: DIVERGES`** → treat it as a blocker: resume the SAME Sisyphus session
+       (`agent__spawn --session_id <id> --prompt "Fix these plan-conformance failures: <adversary
+       complaints, verbatim>"`) — do not spawn a fresh one. Re-run `adversary` ONCE after the fix to
+       confirm it now CONFORMS. If it still DIVERGES on the same criteria, STOP and escalate to the
+       user with the adversary's complaints. If the adversary says the PLAN itself is the root cause,
+       escalate — do not silently change scope.
+     - **`ADVERSARIAL_REVIEW: CONFORMS`** → conformance satisfied. Also confirm the stated test
+       commands pass (run them if feasible) before closing.
+     - If Sisyphus reports failure after its own recovery, surface the evidence and consult `oracle`
+       for diagnosis before deciding whether to retry, re-scope, or escalate.
+
+  5. **Close the task.** Per `task-tracking`: check off Steps + Acceptance criteria (verified, not
+     aspirational); log `completed` with the run branch + this task's commit SHA(s); if Sisyphus
+     reported FOLLOW-UPS, copy them VERBATIM into the completed entry under a "Follow-ups:" line
+     (disk is the durable store — Phase F rolls these up from the logs); set `status: complete`.
+     If {{plans_dir}} rides the repo, commit the task-file updates to the run branch
+     (`chore(plan): complete TASK-NNN`).
+
+  6. Mark the todo item `todo__done`. Move to the next task.
+
+  **Execution mode — parallel_tasks={{parallel_tasks}}.**
+
+  **Sequential mode (parallel_tasks=0, the DEFAULT).** Tasks run SEQUENTIALLY. All tasks share ONE
+  run branch and ONE working tree in {{project_dir}} — concurrent Sisyphus agents would interleave
+  edits and race pushes. Do NOT run code tasks in parallel. Parallelism is fine for read-only work
+  (explore/librarian fan-outs, prepping the next task's context) while a Sisyphus runs. Everything
+  in steps 0-6 above applies exactly as written.
+
+  ### Parallel mode (ONLY when parallel_tasks=1)
+
+  Steps 0-6 above still govern each task; this section changes ONLY the isolation and integration
+  mechanics. When parallel_tasks=0, IGNORE this section entirely.
+
+  **Eligibility (ALL must hold to run a set of tasks concurrently):**
+  1. The tasks are mutually unblocked — no `blocked_by` edges between them.
+  2. The plan declares them file-disjoint (different packages/directories, no shared files).
+  3. NONE of them touches a shared hotspot: DB migrations (sequential numbering collides),
+     generated code (regeneration collides), or dependency manifests/lockfiles (`go.mod`,
+     `package.json`/lockfiles, `Cargo.toml`, ...). A task touching any of these is NEVER
+     parallel-eligible — run it sequentially between parallel batches.
+  4. Cap concurrent code tasks at 3. Ineligible or doubtful → sequential. When in doubt, sequential.
+
+  **Per-task isolation (replaces "work on the run branch" in step 2's prompt):**
+  - At claim time, create a worktree + task branch forked from the run branch tip:
+    `git -C {{project_dir}} worktree add .worktrees/task-NNN -b feat/PLAN-<slug>-task-NNN
+    feat/PLAN-<slug>`. The recorded BASE SHA (step 1) is the fork point.
+  - In the Sisyphus delegation prompt, replace the project path with the worktree path
+    ({{project_dir}}/.worktrees/task-NNN) and the branch with the task branch. Sisyphus commits and
+    pushes the TASK branch. All other prompt sections unchanged — still no PRs, still no
+    creating/switching branches (the worktree arrives already on its branch).
+  - Run the adversary check in the worktree: `get_diff --base <BASE SHA>` — identical semantics to
+    sequential mode.
+
+  **Integration (architect is the integrator; merges are ALWAYS one at a time):**
+  1. When a task's Sisyphus finishes AND its adversary check CONFORMS, merge in the PRIMARY checkout:
+     `git checkout feat/PLAN-<slug> && git merge --no-ff feat/PLAN-<slug>-task-NNN`.
+  2. Run the FULL build + test suite on the run branch after EVERY merge — the task was verified
+     against its fork point, not against siblings' merged work. A post-merge failure is an
+     integration defect: resume the responsible task's Sisyphus session with the failure verbatim.
+  3. Merge conflict → abort the merge, resume that task's Sisyphus session with the conflict
+     verbatim (it rebases its task branch onto the current run branch, re-verifies, re-pushes), then
+     retry the merge. Two failed conflict cycles on the same task → STOP and escalate.
+  4. Only after the merge lands AND the integration build+tests are green: push the run branch, close
+     the task (step 5), and clean up — `git worktree remove .worktrees/task-NNN` and delete the task
+     branch (local + remote).
+
+  Phase F is UNCHANGED (same single draft PR from the run branch). Before opening it, verify no
+  stale worktrees or task branches remain (`git worktree list`); clean up any leftovers.
+
+  ### Phase F — Finish (single draft PR for the whole design doc)
+
+  When every task is `status: complete`:
+  1. In {{project_dir}} on the run branch: confirm the FULL build + test suite is green one final
+     time (the integrated result of all tasks). Failures are yours to drive to resolution (resume
+     the responsible Sisyphus session) before any PR exists.
+  2. **Roll up follow-ups, then open the ONE PR — ALWAYS as a DRAFT** (`gh pr create --draft`) from
+     `feat/PLAN-<slug>` → {{base_branch}}. First collect every "Follow-ups:" line from the completed
+     tasks' `log.md` files. Title: `PLAN-<slug>: <design doc title>`. Body MUST contain, in order:
+     - the plan's Problem/Approach summary,
+     - a checklist of every TASK-NNN (title + commit SHAs),
+     - a **`## Follow-up / manual actions`** section: one checkbox line per follow-up (WHAT, WHERE,
+       WHY, WHEN — pre-merge items FIRST and clearly marked), or "None." if there are none. This
+       section is the reviewer's contract for what the code does NOT do by itself.
+     Report the PR URL. NEVER mark it ready for review — the user reviews the draft first and flips
+     it when THEY decide teammates should see it.
+  3. **Watch the PR checks until green.** Poll `gh pr checks <number>` (re-run every few minutes, or
+     use `--watch`) until every run/check completes. On ANY failure: read the failing check's log
+     (`gh run view --log-failed`), resume the responsible Sisyphus session with the failure verbatim,
+     let it fix + push to the run branch, then re-check. Repeat until all checks pass. A failure that
+     is demonstrably external (infra flake, unrelated broken {{base_branch}}) → note it in the PR
+     body and escalate to the user instead of blind-retrying. Do NOT finish the run with failing or
+     still-pending checks.
+  4. **Create follow-up tasks** so follow-ups are trackable work, not just PR prose: per
+     `task-tracking`, one task per follow-up item (group small related items), `type: followup`,
+     `status: pending`, with the WHAT/WHERE/WHY/WHEN and which TASK-NNN surfaced it. Then edit the
+     PR body's Follow-up section to append each created TASK id to its checkbox line. Do NOT
+     implement these yourself — creating them IS the deliverable; the user picks them up after the
+     merge.
+  5. Set `PLAN-<slug>.md` frontmatter `status: implemented`, add the PR link and a
+     `**Follow-ups:** TASK-NNN, ...` line when any exist; append a `pr-opened` entry to every
+     completed task's `log.md`. If {{plans_dir}} rides the repo, commit these planning updates to
+     the run branch (`chore(plan): ...`) — they become part of the PR.
+  6. Run the `task-tracking` consistency checks; fix anything you introduced.
+  7. Report: the PLAN, every TASK-NNN with its commits, the single draft PR URL with checks green,
+     the follow-up TASKs created (with their WHEN), and anything deferred/escalated. STOP.
+
+  ## Durable state (survive context compression)
+
+  Long runs compress. Anything that lives ONLY in chat is lost. Keep it durable:
+  - **Todo list**: task progress AND resumable Sisyphus `session_id`s (embed in item text).
+  - **{{plans_dir}} on disk**: PLAN frontmatter, task `index.md` statuses, `log.md` entries ARE the
+    run state. After a suspected compression, re-read `todo__list` and the task statuses — trust
+    disk, not memory.
+  - User-approved decisions get one durable line (todo text or the PLAN file) so you don't
+    re-litigate them.
+
+  ## Delegation targets
+
+  | Agent | Use for |
+  |-------|---------|
+  | `sisyphus` | Implement ONE task's code in {{project_dir}} (its own explore/coder/verify/review loop). One per task. |
+  | `explore` | Ground the design/plan in real code in {{project_dir}}; read other local repos for library usage/legacy patterns/call sites. Fan out in parallel. |
+  | `librarian` | External docs/OSS examples for unfamiliar libraries the design touches. |
+  | `oracle` | Plan review (`plan-review`), and diagnosis when a task fails after Sisyphus recovery. |
+  | `gatekeeper` | Plan self-containedness gate (Phase C Gate 1): audits the PLAN for the "docker container" standard, returns SEALED/LEAKY with the missing implementer questions. |
+  | `adversary` | Post-implementation plan-conformance verdict per task (CONFORMS/DIVERGES). |
+
+  ## Escalation handling
+
+  If `pending_escalations` appears in a tool result, a spawned Sisyphus is blocked on user input.
+  Answer from context if you can, else prompt the user, then `agent__reply_escalation` to unblock the
+  child. Do not leave a child hanging.
+
+  ## Anti-patterns (BLOCKING)
+
+  - Opening a PER-TASK PR → the design doc gets exactly ONE PR, opened in Phase F.
+  - Opening the PR as non-draft, or marking the draft ready-for-review → the user flips it himself
+    after his own review.
+  - Finishing the run while PR checks are failing or still pending → the run is not done until
+    checks are green.
+  - Pushing to {{base_branch}}, or creating branches beyond the run branch (and, in parallel mode
+    ONLY, its per-task worktree branches).
+  - WRITING outside {{project_dir}} → wrong write target (reading elsewhere is fine).
+  - Materializing tasks from a plan the gatekeeper marked LEAKY (or never audited), or that Oracle
+    rejected (or never reviewed).
+  - Marking a task complete without the adversary's CONFORMS verdict and verified acceptance criteria.
+  - Code comments referencing the plan/design doc/phases/steps/TASK numbers → docs drift, comments
+    rot; plan references live in commit messages only.
+  - A `.env` file landing in any repo → only `.env.example` with placeholder keys is committable;
+    `.env` stays gitignored and real values are a follow-up.
+  - Dropping a Sisyphus-reported follow-up (not logged in the task's log.md, not in the PR's
+    Follow-up section, no follow-up task created) → manual actions get forgotten and the service
+    breaks at deploy time.
+  - Attempting a follow-up yourself (creating secrets, provisioning cloud roles, touching other
+    repos) instead of recording it → these are out of scope BY DEFINITION; record, don't do.
+  - Spawning a fresh Sisyphus for a follow-up/fix instead of resuming its `session_id`.
+  - Polling `agent__collect` on a running agent.
+  - Writing files via `execute_command` (heredocs, `cat >`, `echo >`) instead of `fs_write`/`fs_patch`.
+  - Losing a Sisyphus `session_id` or a follow-up to chat-only memory.
+
+  ## Hard blocks (NEVER)
+
+  - Destructive/irreversible actions (`rm -rf`, force-push, dropping data, deleting branches) without
+    explicit user confirmation (parallel-mode post-merge worktree/task-branch cleanup excepted).
+  - Leaving code broken or a task half-done after a failure — reconcile, or escalate cleanly.
+  - Fabricating task completion — the acceptance criteria, the commits on the run branch, and the
+    final PR are the evidence.
+
+  ## Available Tools
+  {{__tools__}}
+
+  ## Context
+  - Project (WRITE target): {{project_dir}}
+  - Plans dir: {{plans_dir}}
+  - Design doc: {{design_doc}}
+  - Base branch: {{base_branch}}
+  - Autonomy: {{autonomy}}
+  - Parallel tasks: {{parallel_tasks}} (0 = sequential, 1 = worktree-parallel)
+  - OS: {{__os__}}  Shell: {{__shell__}}  CWD: {{__cwd__}}  Now: {{__now__}}
+
+conversation_starters:
+  - 'Implement the design doc at {{design_doc}} end to end'
+  - 'Decompose this design doc into a plan and tasks, then drive them to completion'
+  - 'Run the full design-to-PR pipeline on {{design_doc}}'

assets/agents/coder/graph.yaml

@@ -227,6 +227,11 @@ nodes:
          on unfamiliar lints, etc.).
       4. No dead code, no commented-out blocks, no premature abstractions.
       5. End your turn when editing is done. The graph runs verification next.
+      6. VERIFICATION HONESTY: never state that a check, lint, build, or test
+         passed unless you paste its literal command and exit code. A gate
+         that did not run is UNVERIFIED — say so. An honest failure report
+         always beats a success-shaped one; a false "passed" poisons every
+         downstream consumer of your report.
 
       Project directory: {{project_dir}}
     prompt: |
@@ -248,7 +253,7 @@ nodes:
       - fs_write
       - fs_patch
       - execute_command
-    max_iterations: 30
+    max_iterations: 100
     state_updates:
       last_node_output: '{{output}}'
     fallback: end_failure

assets/agents/coder/scripts/verify_build.sh

@@ -13,6 +13,7 @@ else
 fi
 
 project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+project_dir=$(resolve_gate_dir "$project_dir")
 
 if [[ -n "${BUILD_CMD:-}" ]]; then
   cmd="$BUILD_CMD"
@@ -24,7 +25,7 @@ fi
 if [[ -z "$cmd" || "$cmd" == "null" ]]; then
   jq -nc '{
     "build_ok": true,
-    "build_output": "(no build/check command available for this project type)",
+    "build_output": "(GATE NOT RUN: no build/check command configured or detected. This is NOT evidence that the build passed — set BUILD_CMD, and never report the build as verified.)",
     "_next": "verify_tests"
   }'
   exit 0

assets/agents/coder/scripts/verify_tests.sh

@@ -13,6 +13,7 @@ else
 fi
 
 project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+project_dir=$(resolve_gate_dir "$project_dir")
 
 if [[ -n "${TEST_CMD:-}" ]]; then
   cmd="$TEST_CMD"
@@ -24,7 +25,7 @@ fi
 if [[ -z "$cmd" || "$cmd" == "null" ]]; then
   jq -nc '{
     "tests_ok": true,
-    "tests_output": "(no test command available for this project type)",
+    "tests_output": "(GATE NOT RUN: no test command configured or detected. This is NOT evidence that tests passed — set TEST_CMD, and never report the suite as green.)",
     "_next": "self_review"
   }'
   exit 0

assets/agents/gatekeeper/README.md

@@ -0,0 +1,77 @@
+# Gatekeeper
+
+A **plan self-containedness gate**. Audits a plan against the "sealed container" standard before it
+is finalized:
+
+> A context-free LLM implementer must be able to execute the plan using ONLY what is on the page —
+> every question it will hit mid-implementation is either **answered inline** or **delegated via a
+> verified pointer** to the exact code/docs where the answer lives.
+
+Where [`plan-review`](../../skills/plan-review/SKILL.md) (via `oracle`) judges the *approach*
+(executability, verifiability, ordering), `gatekeeper` audits the *context*: does the implementer
+know where infrastructure code goes, what DB tech to use (RDS vs in-cluster Postgres), which
+directory layout to mirror, what commands verify the work — or at least where to look?
+
+## The three review gates
+
+| Gate | Agent | Question | When |
+|------|-------|----------|------|
+| Self-containedness | `gatekeeper` | "Can a context-free LLM implement from this file alone?" | Before the plan is finalized |
+| Executability | `oracle` + `plan-review` | "Is the approach sound, verifiable, correctly ordered?" | Before the plan is promoted |
+| Conformance | [`adversary`](../adversary/README.md) | "Is the built code what the plan asked for?" | After implementation |
+
+## How it audits
+
+Driven by the [`plan-gatekeeping`](../../skills/plan-gatekeeping/SKILL.md) skill:
+
+1. Walks a 10-category manifest: code placement, infrastructure, data layer, interfaces/contracts,
+   conventions/tooling, testing/verification, dependencies/ordering, config/secrets, scope
+   boundaries, settled decisions.
+2. For each category: answered inline, delegated via pointer, or **missing**.
+3. **Verifies every pointer** with read-only tools — the path exists AND actually covers the claimed
+   topic. A pointer to a file that never mentions the topic is a leak wearing a pointer costume.
+4. Phrases each gap as the question the implementer would actually ask, tagged **BLOCKING** (will
+   guess wrong) or **FRICTION** (will waste time rediscovering).
+
+## Verdict (blocking)
+
+```
+PLAN_GATE: SEALED
+Categories audited: N applicable, all answered or pointed.
+```
+
+```
+PLAN_GATE: LEAKY
+Missing questions (N):
+1. [infrastructure] Where do I put the Terraform for the new service DB — infra/rds/ or a separate repo? — BLOCKING — plan says "provision a database" with no target — add inline: "RDS via infra/rds/, mirror rate_cards.tf"
+Broken pointers (if any):
+- "see docs/db.md for conventions" — path missing
+```
+
+`LEAKY` blocks finalization. The caller (typically `architect`) answers the questions — by exploring
+the code repos, reading docs, or asking the user — amends the plan, and re-submits to the SAME
+gatekeeper session until it seals.
+
+## Usage
+
+Spawned by `architect` during design-doc decomposition (Phase B/C), before the `oracle` plan-review:
+
+```sh
+agent__spawn --agent gatekeeper --prompt "Audit this plan for self-containedness. Return SEALED/LEAKY.
+
+Plan: <plans_dir>/PLAN-<slug>.md
+Target project: <project_dir>"
+```
+
+Ad-hoc use against any plan file:
+
+```sh
+coyote -a gatekeeper --agent-variable project_dir ~/code/my-service \
+  "Audit plans/PLAN-my-feature.md for self-containedness"
+```
+
+## Related
+
+- [`plan-gatekeeping`](../../skills/plan-gatekeeping/SKILL.md) — the manifest + methodology it runs on.
+- [`architect`](../architect/README.md) — the orchestrator that gates plans through it.
+- [`adversary`](../adversary/README.md) — the post-implementation conformance counterpart.

assets/agents/gatekeeper/config.yaml

@@ -0,0 +1,99 @@
+name: gatekeeper
+description: Plan self-containedness gate - audits a plan against the "sealed container" standard (every implementer question answered inline or via a verified pointer to code/docs) and returns a blocking PLAN_GATE SEALED/LEAKY verdict with the missing questions. Designed to be delegated to by architect before plans are finalized.
+version: 2.0.0
+
+auto_continue: true
+max_auto_continues: 15
+inject_todo_instructions: true
+
+skills_enabled: true
+enabled_skills:
+  - plan-gatekeeping
+
+variables:
+  - name: project_dir
+    description: Absolute path to the project the plan targets - the ground truth for pointer verification
+    default: '.'
+
+global_tools:
+  - ast_grep.sh
+  - fs_read.sh
+  - fs_cat.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+
+instructions: |
+  You are the plan gatekeeper. You audit ONE plan for **self-containedness** before it is finalized:
+  the "sealed container" test. A context-free LLM implementer must be able to execute the plan using
+  ONLY what is on the page — every question it will hit mid-implementation must be answered inline or
+  delegated via a verified pointer to the exact code/docs where the answer lives. Your output is the
+  list of questions the plan FAILS to answer, and a blocking verdict.
+
+  You are NOT the approach reviewer (`plan-review` judges executability/verifiability of the design).
+  You audit completeness of CONTEXT. A brilliant approach with no answer to "where does the infra
+  code go?" or "managed RDS or an in-cluster Postgres container?" fails your gate.
+
+  ## Step 0: Load the skill
+
+  Before anything else, `skill__load` `plan-gatekeeping`. It carries your methodology: the
+  answer-or-pointer rule, the 10-category manifest (code placement, infrastructure, data layer,
+  interfaces, conventions, testing, dependencies, config/secrets, scope, settled decisions), pointer
+  verification, severity tagging, and the exact verdict format. The skill body is your source of
+  truth; these instructions handle workflow and I/O.
+
+  ## Input (the spawn prompt IS your entire context)
+
+  You are given a plan to audit — pasted inline or as a path to read. You may also be told which
+  project the plan targets; default ground truth is {{project_dir}}. Any other local repos/docs the
+  plan points into are readable for pointer verification.
+
+  If no plan is provided, STOP and say so.
+
+  ## Workflow
+
+  1. Load `plan-gatekeeping`.
+  2. Read the plan in full (`fs_cat` for the whole file — do not audit a truncated view).
+  3. Walk EVERY manifest category. For each: answered inline, delegated via pointer, or MISSING.
+     Mark inapplicable categories explicitly.
+  4. Verify every pointer with the read-only tools: the path exists AND the target actually covers
+     the claimed topic. Check "mirror the layout of X" claims against X itself.
+  5. Phrase each gap as the QUESTION the implementer would actually ask, tag it BLOCKING or
+     FRICTION, and suggest the fix — an inline answer or a pointer you have VERIFIED resolves.
+  6. Emit the verdict in the skill's exact format.
+
+  ## Output — verdict (MANDATORY, exact format)
+
+  End with EXACTLY one of these sentinels so the caller can route on it:
+
+  ```
+  PLAN_GATE: SEALED
+  Categories audited: N applicable, all answered or pointed.
+  ```
+
+  ```
+  PLAN_GATE: LEAKY
+  Missing questions (N):
+  1. [category] <implementer's actual question> — [BLOCKING|FRICTION] — <why they get stuck> — <suggested fix>
+  Broken pointers (if any):
+  - <pointer> — <path missing | doesn't cover topic>
+  ```
+
+  ## Rules
+
+  1. **You are read-only.** Never modify the plan. You produce questions; the author owns the fixes.
+  2. **Questions, not complaints.** "Infra section is thin" is noise. "Where do I put the Terraform
+     for the new database — {{project_dir}}/infra/ or a separate repo?" is signal.
+  3. **Verify every pointer you check AND every pointer you suggest.** Recommending an unverified
+     pointer is the same leak you exist to catch.
+  4. **BLOCKING findings always mean LEAKY.** Only-FRICTION findings: note the caller may seal at
+     their discretion.
+  5. **Do not re-litigate the approach.** Coherent-but-underdocumented means the fix is context.
+  6. Be terse and decisive. Three BLOCKING questions beat fifteen nitpicks.
+
+  ## Context
+  - Project (ground truth): {{project_dir}}
+  - CWD: {{__cwd__}}
+
+  ## Available Tools
+  {{__tools__}}

assets/agents/librarian/graph.yaml

@@ -88,7 +88,6 @@ nodes:
     prompt: |
       Research prompt: {{initial_prompt}}
     tools: []
-    temperature: 0.1
     output_schema:
       type: object
       properties:
@@ -180,7 +179,6 @@ nodes:
     tools:
       - mcp:ddg-search
     max_iterations: 15
-    temperature: 0.1
     state_updates:
       search_output: "{{output}}"
     fallback: synthesize
@@ -251,7 +249,6 @@ nodes:
     tools:
       - mcp:personal-github
     max_iterations: 15
-    temperature: 0.1
     state_updates:
       oss_output: "{{output}}"
     fallback: synthesize
@@ -338,7 +335,6 @@ nodes:
     tools:
       - fetch_url_via_curl
     max_iterations: 20
-    temperature: 0.1
     state_updates:
       findings: "{{output}}"
     fallback: final_format

assets/agents/sisyphus/config.yaml

@@ -266,6 +266,12 @@ instructions: |
 
   **No evidence = not complete.** Mark a todo `completed` only after evidence is collected.
 
+  ### Verification honesty (NON-NEGOTIABLE)
+
+  - Never state that a lint, build, or test passed unless you can paste its literal command and exit code. A gate that did not run is UNVERIFIED — report it as not run, never as "covered by" something else.
+  - Never reuse a verification claim from an earlier report (yours or another agent's) without re-running the command yourself. Prior reports are unverified context, not evidence.
+  - An honest failure — "gate X failed / could not run, here is the verbatim error" — is an acceptable, preferable deliverable. A success-shaped report with missing evidence poisons every downstream consumer.
+
   ### Independent code review (post-coder, non-trivial work)
 
   After completing delegated `coder` work, spawn `code-reviewer` for an independent review pass if ANY of these are true:

assets/agents/sisyphus/sbx-mixin.yaml

@@ -1,11 +1,38 @@
-schemaVersion: '1'
+schemaVersion: '2'
 kind: mixin
 name: sisyphus-ddg
 description: >
-  Allows Sisyphus to hit all domains since it utilizes the DuckDuckGo
-  MCP server. This allows the MCP server to actually perform web searches
-  on arbitrary domains and retrieve info for the agent.
+  Allows Sisyphus to reach DuckDuckGo plus a curated set of common
+  content domains for its web-search MCP server. Schema v2 removed
+  the bare '*' allow-all, so frequently fetched result domains are
+  enumerated here.
 
-network:
-  allowedDomains:
-    - '*'
+agentInstructions:
+  content: |
+    Web search runs against an enumerated network allow list. If fetching a
+    search result is blocked by network policy, ask the user to run
+    `sbx policy allow network <domain>` on the host to extend it.
+
+permissions:
+  network:
+    allow:
+      # DuckDuckGo search endpoints used by the ddg-search MCP server
+      - 'duckduckgo.com'
+      - 'html.duckduckgo.com'
+      - 'lite.duckduckgo.com'
+      # Common content/result domains fetched from search results
+      # ('*.host' matches exactly one label and not the bare host itself)
+      - '*.wikipedia.org'
+      - 'github.com'
+      - '*.githubusercontent.com'
+      - 'stackoverflow.com'
+      - '*.stackexchange.com'
+      - 'developer.mozilla.org'
+      - 'docs.python.org'
+      - 'doc.rust-lang.org'
+      - 'docs.rs'
+      - 'crates.io'
+      - 'pypi.org'
+      - 'www.npmjs.com'
+      # Jina reader fallback for fetching arbitrary pages as markdown
+      - 'r.jina.ai'

assets/agents/step-runner/graph.yaml

@@ -439,6 +439,12 @@ nodes:
       staleness report, gate decisions, and fix loop history. Downstream
       plan updates come from the sweep results.
 
+      VERIFICATION HONESTY: evidence marked "GATE NOT RUN" means that gate
+      is UNVERIFIED — record it as not run; never paraphrase a skipped gate
+      as covered, passing, or handled elsewhere. A handoff that admits an
+      unverified gate is correct; one that dresses it up as verified poisons
+      every downstream reader.
+
       Then append durable, step-independent facts (if any) to {{notes_path}}
       - create the file if missing, never rewrite existing entries.
 

assets/agents/step-runner/scripts/verify_build.sh

@@ -13,6 +13,7 @@ else
 fi
 
 project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+project_dir=$(resolve_gate_dir "$project_dir")
 
 if [[ -n "${BUILD_CMD:-}" ]]; then
   cmd="$BUILD_CMD"
@@ -24,7 +25,7 @@ fi
 if [[ -z "$cmd" || "$cmd" == "null" ]]; then
   jq -nc '{
     "build_ok": true,
-    "build_output": "(no build/check command available for this project type)",
+    "build_output": "(GATE NOT RUN: no build/check command configured or detected. This is NOT evidence that the build passed — set BUILD_CMD, and never report the build as verified.)",
     "_next": "verify_tests"
   }'
   exit 0

assets/agents/step-runner/scripts/verify_format_lint.sh

@@ -13,19 +13,18 @@ else
 fi
 
 project_dir=$(echo "$state" | jq -r '.project_dir // "."')
-project_type=$(detect_project "$project_dir" | jq -r '.type // "unknown"')
+project_dir=$(resolve_gate_dir "$project_dir")
+project_info=$(detect_project "$project_dir")
+project_type=$(echo "$project_info" | jq -r '.type // "unknown"')
 
 format_cmd="${FORMAT_CMD:-}"
 if [[ -z "$format_cmd" ]]; then
-  case "$project_type" in
-    rust) format_cmd="cargo fmt" ;;
-    go) format_cmd="gofmt -w ." ;;
-    python) command -v ruff &>/dev/null && format_cmd="ruff format ." ;;
-  esac
+  format_cmd=$(echo "$project_info" | jq -r '.fmt // ""')
 fi
+if [[ "$format_cmd" == "null" ]]; then format_cmd=""; fi
 
 if [[ -z "$format_cmd" ]]; then
-  format_output="(no format command configured for project type '$project_type'; skipped. Set FORMAT_CMD to enable.)"
+  format_output="(GATE NOT RUN: no format command configured or detected for project type '$project_type'. This is NOT evidence that formatting is clean. Set FORMAT_CMD to enable.)"
 else
   fmt_rc=0
   fmt_out=$(cd "$project_dir" && eval "$format_cmd" 2>&1) || fmt_rc=$?
@@ -37,12 +36,18 @@ fi
 
 lint_cmd="${LINT_CMD:-}"
 if [[ -z "$lint_cmd" ]]; then
+  lint_cmd=$(echo "$project_info" | jq -r '.lint // ""')
+fi
+# The skip message must read as a WARNING, never a reassurance: the previous
+# wording ("linting is covered by the build/check command") was quoted
+# verbatim by workers as false evidence that linting passed
+if [[ -z "$lint_cmd" || "$lint_cmd" == "null" ]]; then
   jq -nc \
     --arg fo "$format_output" \
     '{
       "format_output": $fo,
       "lint_ok": true,
-      "lint_output": "(no LINT_CMD configured; linting is covered by the build/check command)",
+      "lint_output": "(GATE NOT RUN: no lint command configured or detected. This is NOT evidence that linting passed — set LINT_CMD or add a Taskfile lint target, and never report linting as covered.)",
       "_next": "verify_build"
     }'
   exit 0

assets/agents/step-runner/scripts/verify_tests.sh

@@ -13,6 +13,7 @@ else
 fi
 
 project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+project_dir=$(resolve_gate_dir "$project_dir")
 
 if [[ -n "${TEST_CMD:-}" ]]; then
   cmd="$TEST_CMD"
@@ -24,7 +25,7 @@ fi
 if [[ -z "$cmd" || "$cmd" == "null" ]]; then
   jq -nc '{
     "tests_ok": true,
-    "tests_output": "(no test command available for this project type)",
+    "tests_output": "(GATE NOT RUN: no test command configured or detected. This is NOT evidence that tests passed — set TEST_CMD, and never report the suite as green.)",
     "_next": "edge_case_sweep"
   }'
   exit 0

assets/functions/sbx-mixin.yaml

@@ -1,4 +1,4 @@
-schemaVersion: "1"
+schemaVersion: '2'
 kind: mixin
 name: built-in-tools
 description: >
@@ -6,39 +6,39 @@ description: >
   global tools and the default MCP server set. Auto-applied by Coyote's sbx
   mixin discovery when running `coyote --sandbox`.
 
-network:
-  allowedDomains:
-    # fetch_url_via_jina + jina reader fallback
-    - "r.jina.ai:443"
-    # get_current_weather (.sh, .py, .ts)
-    - "wttr.in:443"
-    # search_arxiv (the .sh tool still uses http://, so :80 is required until fixed)
-    - "export.arxiv.org:443"
-    - "export.arxiv.org:80"
-    # search_arxiv + search_wikipedia may follow DOI redirects
-    - "doi.org:443"
-    # search_wikipedia
-    - "en.wikipedia.org:443"
-    # search_wolframalpha
-    - "api.wolframalpha.com:443"
-    # web_search_perplexity
-    - "api.perplexity.ai:443"
-    # web_search_tavily
-    - "api.tavily.com:443"
-    # send_twilio
-    - "api.twilio.com:443"
-    # MCP: github (built-in mcp.json: api.githubcopilot.com)
-    - "api.githubcopilot.com:443"
-    # MCP: atlassian (built-in mcp.json: mcp-remote -> mcp.atlassian.com)
-    - "mcp.atlassian.com:443"
-    # MCP: ddg-search (built-in mcp.json: uvx duckduckgo-mcp-server)
-    - "duckduckgo.com:443"
-    - "html.duckduckgo.com:443"
-    - "lite.duckduckgo.com:443"
-    # MCP: npx-based servers (mcp-remote) pull from npm
-    - "registry.npmjs.org:443"
-    # MCP: docker server may pull images from common registries
-    - "ghcr.io:443"
-    - "registry-1.docker.io:443"
-    - "auth.docker.io:443"
-    - "production.cloudflare.docker.com:443"
+permissions:
+  network:
+    allow:
+      # fetch_url_via_jina + jina reader fallback
+      - 'r.jina.ai'
+      # get_current_weather (.sh, .py, .ts)
+      - 'wttr.in'
+      # search_arxiv (the .sh tool still uses http://, so :80 is required until fixed)
+      - 'export.arxiv.org'
+      - 'export.arxiv.org:80'
+      # search_arxiv + search_wikipedia may follow DOI redirects
+      - 'doi.org'
+      # search_wikipedia
+      - 'en.wikipedia.org'
+      # search_wolframalpha
+      - 'api.wolframalpha.com'
+      # web_search_perplexity
+      - 'api.perplexity.ai'
+      # web_search_tavily
+      - 'api.tavily.com'
+      # send_twilio
+      - 'api.twilio.com'
+      # MCP: github (built-in mcp.json: api.githubcopilot.com)
+      - 'api.githubcopilot.com'
+      # MCP: atlassian (built-in mcp.json: mcp-remote -> mcp.atlassian.com)
+      - 'mcp.atlassian.com'
+      # MCP: ddg-search (built-in mcp.json: uvx duckduckgo-mcp-server)
+      - 'duckduckgo.com'
+      - 'html.duckduckgo.com'
+      - 'lite.duckduckgo.com'
+      # MCP: npx-based servers (mcp-remote) pull from npm
+      - 'registry.npmjs.org'
+      # MCP: docker server may pull images from common registries
+      - 'ghcr.io'
+      - 'registry-1.docker.io'
+      - 'auth.docker.io'

assets/functions/tools/fs_glob.sh

@@ -33,7 +33,18 @@ main() {
             --exclude '.build' \
             2>/dev/null | head -n "$MAX_RESULTS") || true
     else
-        results=$(find "$search_path" -type f -name "$glob_pattern" \
+        local name_pattern dir_prefix effective_search
+        name_pattern="${glob_pattern##*/}"
+        [[ -z "$name_pattern" || "$name_pattern" == "**" ]] && name_pattern="*"
+        if [[ "$glob_pattern" == */* ]]; then
+            dir_prefix="${glob_pattern%%\**}"
+            dir_prefix="${dir_prefix%/}"
+            effective_search="${search_path}${dir_prefix:+/$dir_prefix}"
+        else
+            effective_search="$search_path"
+        fi
+        [[ -d "$effective_search" ]] || effective_search="$search_path"
+        results=$(find "$effective_search" -type f -name "$name_pattern" \
             -not -path '*/.git/*' \
             -not -path '*/node_modules/*' \
             -not -path '*/target/*' \

assets/sbx-kit/files/home/.config/git/hooks/pre-commit

@@ -0,0 +1,21 @@
+#!/bin/sh
+if [ -z "$SSH_AUTH_SOCK" ]; then
+    echo "WARNING: [git-ssh-sign] no SSH agent — cannot sign commits"
+fi
+
+KEY=$(ssh-add -L 2>/dev/null | head -1)
+
+if [ -z "$KEY" ]; then
+    echo "WARNING: [git-ssh-sign] no keys in SSH agent — cannot sign commits"
+fi
+
+KEY_FILE="/home/agent/.config/git/signing_key.pub"
+mkdir -p "$(dirname "$KEY_FILE")"
+printf '%s\n' "$KEY" > "$KEY_FILE"
+EMAIL=$(git config user.email 2>/dev/null || echo "agent@sandbox.local")
+printf '%s %s\n' "$EMAIL" "$KEY" > "/home/agent/.config/git/allowed_signers"
+
+local_hook="$(git rev-parse --git-dir)/hooks/pre-commit"
+if [ -x "$local_hook" ]; then
+    exec "$local_hook" "$@"
+fi

assets/sbx-kit/spec.yaml

@@ -4,7 +4,7 @@
 #   sbx create --kit ./sbx-kit/ coyote --name testing .
 #   sbx cp $HOME/.config/coyote/ testing:/home/agent/.config/
 #   sbx run testing --kit ./sbx-kit/
-schemaVersion: '1'
+schemaVersion: '2'
 kind: sandbox
 name: coyote
 displayName: Coyote
@@ -13,199 +13,256 @@ description: >
   CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros.
 
 sandbox:
-  image: 'darkalex17/coyote:v0.8.0'
-  aiFilename: COYOTE.md
-  entrypoint:
-    run: ['bash', '-lc', 'exec /home/agent/.cargo/bin/coyote']
+  image: 'darkalex17/coyote:v0.8.3'
+  entrypoint: ['bash', '-lc', 'exec /home/agent/.cargo/bin/coyote']
 
-network:
-  # Proxy-managed LLM providers: the proxy substitutes `proxy-managed` for
-  # the env var inside the sandbox and rewrites the auth header per
-  # serviceAuth at request time. Multiple domains may map to one service
-  # (e.g. jina) so they share a single credential.
-  serviceDomains:
-    api.openai.com: openai
-    api.anthropic.com: anthropic
-    generativelanguage.googleapis.com: gemini
-    api.cohere.ai: cohere
-    api.groq.com: groq
-    openrouter.ai: openrouter
-    api.ai21.com: ai21
-    api.cloudflare.com: cloudflare
-    api.deepinfra.com: deepinfra
-    api.deepseek.com: deepseek
-    api.mistral.ai: mistral
-    api.perplexity.ai: perplexity
-    api.voyageai.com: voyageai
-    api.x.ai: xai
-    api.jina.ai: jina
-    r.jina.ai: jina
-    qianfan.baidubce.com: ernie
-    api.hunyuan.cloud.tencent.com: hunyuan
-    api.minimax.chat: minimax
-    api.moonshot.cn: moonshot
-    dashscope.aliyuncs.com: qianwen
-    open.bigmodel.cn: zhipuai
-  serviceAuth:
-    openai:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    anthropic:
-      headerName: x-api-key
-      valueFormat: '%s'
-    gemini:
-      headerName: x-goog-api-key
-      valueFormat: '%s'
-    cohere:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    groq:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    openrouter:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    ai21:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    cloudflare:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    deepinfra:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    deepseek:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    mistral:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    perplexity:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    voyageai:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    xai:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    jina:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    ernie:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    hunyuan:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    minimax:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    moonshot:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    qianwen:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-    zhipuai:
-      headerName: Authorization
-      valueFormat: 'Bearer %s'
-  allowedDomains:
-    # Coyote release + self-update + model-registry sync
-    - 'github.com:443'
-    - 'api.github.com:443'
-    - 'raw.githubusercontent.com:443'
-    - 'objects.githubusercontent.com:443'
-    - '*.githubusercontent.com:443'
-    # Package managers and developer tools (cargo, uv, pip — useful at runtime for user installs)
-    - 'crates.io:443'
-    - 'static.crates.io:443'
-    - 'pypi.org:443'
-    - 'files.pythonhosted.org:443'
-    - 'astral.sh:443'
-    - 'sh.rustup.rs:443'
-    - 'static.rust-lang.org:443'
+permissions:
+  network:
+    allow:
+      # Coyote release + self-update + model-registry sync
+      - 'github.com'
+      - 'api.github.com'
+      - 'raw.githubusercontent.com'
+      - 'objects.githubusercontent.com'
+      - '*.githubusercontent.com'
+      # Package managers and developer tools (cargo, uv, pip — useful at runtime for user installs)
+      - 'crates.io'
+      - 'static.crates.io'
+      - 'pypi.org'
+      - 'files.pythonhosted.org'
+      - 'astral.sh'
+      - 'sh.rustup.rs'
+      - 'static.rust-lang.org'
 
-    # LLM model OAuth + API endpoints
-    - 'claude.ai:443'
-    - 'console.anthropic.com:443'
-    - 'accounts.google.com:443'
-    # *.googleapis.com covers oauth2 + userinfo + VertexAI regional endpoints
-    # (*-aiplatform.googleapis.com). Do not narrow without re-checking VertexAI.
-    - '*.googleapis.com:443'
+      # LLM model OAuth + API endpoints
+      - 'claude.ai'
+      - 'console.anthropic.com'
+      - 'accounts.google.com'
+      # *.googleapis.com covers oauth2 + userinfo + VertexAI regional endpoints
+      # (*-aiplatform.googleapis.com). Do not narrow without re-checking VertexAI.
+      - '*.googleapis.com'
 
-    # Bedrock and GitHub Models use signed / GitHub-PAT auth that the proxy
-    # cannot rewrite. Domains are allow-listed; credentials must be injected
-    # separately (see README "Extending").
-    - '*.amazonaws.com:443'
-    - 'models.inference.ai.azure.com:443'
+      # Bedrock and GitHub Models use signed / GitHub-PAT auth that the proxy
+      # cannot rewrite; credentials must be injected separately (see README
+      # "Extending"). NOTE: '*.amazonaws.com' matches exactly ONE label, so
+      # two-label regional Bedrock hosts must be enumerated explicitly
+      # ('**.' is declared but not yet enforced by sbx). Add your region
+      # via a mixin if it's missing below.
+      - '*.amazonaws.com'
+      - 'bedrock-runtime.us-east-1.amazonaws.com'
+      - 'bedrock-runtime.us-east-2.amazonaws.com'
+      - 'bedrock-runtime.us-west-2.amazonaws.com'
+      - 'bedrock-runtime.eu-west-1.amazonaws.com'
+      - 'bedrock-runtime.eu-central-1.amazonaws.com'
+      - 'bedrock-runtime.ap-southeast-2.amazonaws.com'
+      - 'bedrock-runtime.ap-northeast-1.amazonaws.com'
+      - 'models.inference.ai.azure.com'
 
+      # Proxy-managed LLM provider APIs. Every credentials[].apiKey.inject
+      # domain below MUST also appear here. sbx does not derive allow entries
+      # from inject rules.
+      - 'api.openai.com'
+      - 'api.anthropic.com'
+      - 'generativelanguage.googleapis.com'
+      - 'api.cohere.ai'
+      - 'api.groq.com'
+      - 'openrouter.ai'
+      - 'api.ai21.com'
+      - 'api.cloudflare.com'
+      - 'api.deepinfra.com'
+      - 'api.deepseek.com'
+      - 'api.mistral.ai'
+      - 'api.perplexity.ai'
+      - 'api.voyageai.com'
+      - 'api.x.ai'
+      - 'api.jina.ai'
+      - 'r.jina.ai'
+      - 'qianfan.baidubce.com'
+      - 'api.hunyuan.cloud.tencent.com'
+      - 'api.minimax.chat'
+      - 'api.moonshot.cn'
+      - 'dashscope.aliyuncs.com'
+      - 'open.bigmodel.cn'
+
+# Proxy-managed LLM providers: inside the sandbox each apiKey env var holds
+# the `proxy-managed` sentinel; the proxy injects the real value into the
+# request header per the inject rules at request time. Values are bound by
+# the user via credential bindings (`sbx secret set <service>`); Coyote
+# pre-seeds them from its vault at launch. Multiple domains may map to one
+# service (e.g. jina) so they share a single credential.
 credentials:
-  sources:
-    openai:
-      env:
-        - OPENAI_API_KEY
-    anthropic:
-      env:
-        - ANTHROPIC_API_KEY
-    gemini:
-      env:
-        - GEMINI_API_KEY
-        - GOOGLE_API_KEY
-    cohere:
-      env:
-        - COHERE_API_KEY
-    groq:
-      env:
-        - GROQ_API_KEY
-    openrouter:
-      env:
-        - OPENROUTER_API_KEY
-    ai21:
-      env:
-        - AI21_API_KEY
-    cloudflare:
-      env:
-        - CLOUDFLARE_API_KEY
-    deepinfra:
-      env:
-        - DEEPINFRA_API_KEY
-    deepseek:
-      env:
-        - DEEPSEEK_API_KEY
-    mistral:
-      env:
-        - MISTRAL_API_KEY
-    perplexity:
-      env:
-        - PERPLEXITY_API_KEY
-    voyageai:
-      env:
-        - VOYAGE_API_KEY
-    xai:
-      env:
-        - XAI_API_KEY
-    jina:
-      env:
-        - JINA_API_KEY
-    ernie:
-      env:
-        - ERNIE_API_KEY
-    hunyuan:
-      env:
-        - HUNYUAN_API_KEY
-    minimax:
-      env:
-        - MINIMAX_API_KEY
-    moonshot:
-      env:
-        - MOONSHOT_API_KEY
-    qianwen:
-      env:
-        - DASHSCOPE_API_KEY
-    zhipuai:
-      env:
-        - ZHIPUAI_API_KEY
+  - service: openai
+    description: OpenAI API key, injected on api.openai.com
+    apiKey:
+      name: OPENAI_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.openai.com
+          scheme: bearer
+  - service: anthropic
+    description: Anthropic API key, injected as x-api-key on api.anthropic.com
+    apiKey:
+      name: ANTHROPIC_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.anthropic.com
+          header: x-api-key
+          format: '%s'
+  - service: gemini
+    description: Google Gemini API key, injected as x-goog-api-key on generativelanguage.googleapis.com
+    apiKey:
+      name: GEMINI_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: generativelanguage.googleapis.com
+          header: x-goog-api-key
+          format: '%s'
+  - service: cohere
+    description: Cohere API key, injected on api.cohere.ai
+    apiKey:
+      name: COHERE_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.cohere.ai
+          scheme: bearer
+  - service: groq
+    description: Groq API key, injected on api.groq.com
+    apiKey:
+      name: GROQ_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.groq.com
+          scheme: bearer
+  - service: openrouter
+    description: OpenRouter API key, injected on openrouter.ai
+    apiKey:
+      name: OPENROUTER_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: openrouter.ai
+          scheme: bearer
+  - service: ai21
+    description: AI21 Labs API key, injected on api.ai21.com
+    apiKey:
+      name: AI21_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.ai21.com
+          scheme: bearer
+  - service: cloudflare
+    description: Cloudflare Workers AI API key, injected on api.cloudflare.com
+    apiKey:
+      name: CLOUDFLARE_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.cloudflare.com
+          scheme: bearer
+  - service: deepinfra
+    description: DeepInfra API key, injected on api.deepinfra.com
+    apiKey:
+      name: DEEPINFRA_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.deepinfra.com
+          scheme: bearer
+  - service: deepseek
+    description: DeepSeek API key, injected on api.deepseek.com
+    apiKey:
+      name: DEEPSEEK_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.deepseek.com
+          scheme: bearer
+  - service: mistral
+    description: Mistral API key, injected on api.mistral.ai
+    apiKey:
+      name: MISTRAL_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.mistral.ai
+          scheme: bearer
+  - service: perplexity
+    description: Perplexity API key, injected on api.perplexity.ai
+    apiKey:
+      name: PERPLEXITY_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.perplexity.ai
+          scheme: bearer
+  - service: voyageai
+    description: Voyage AI API key, injected on api.voyageai.com
+    apiKey:
+      name: VOYAGE_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.voyageai.com
+          scheme: bearer
+  - service: xai
+    description: xAI (Grok) API key, injected on api.x.ai
+    apiKey:
+      name: XAI_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.x.ai
+          scheme: bearer
+  - service: jina
+    description: Jina API key, injected on api.jina.ai and r.jina.ai
+    apiKey:
+      name: JINA_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.jina.ai
+          scheme: bearer
+        - domain: r.jina.ai
+          scheme: bearer
+  - service: ernie
+    description: Baidu ERNIE API key, injected on qianfan.baidubce.com
+    apiKey:
+      name: ERNIE_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: qianfan.baidubce.com
+          scheme: bearer
+  - service: hunyuan
+    description: Tencent Hunyuan API key, injected on api.hunyuan.cloud.tencent.com
+    apiKey:
+      name: HUNYUAN_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.hunyuan.cloud.tencent.com
+          scheme: bearer
+  - service: minimax
+    description: MiniMax API key, injected on api.minimax.chat
+    apiKey:
+      name: MINIMAX_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.minimax.chat
+          scheme: bearer
+  - service: moonshot
+    description: Moonshot AI API key, injected on api.moonshot.cn
+    apiKey:
+      name: MOONSHOT_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: api.moonshot.cn
+          scheme: bearer
+  - service: qianwen
+    description: Alibaba Qianwen (DashScope) API key, injected on dashscope.aliyuncs.com
+    apiKey:
+      name: DASHSCOPE_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: dashscope.aliyuncs.com
+          scheme: bearer
+  - service: zhipuai
+    description: Zhipu AI (GLM) API key, injected on open.bigmodel.cn
+    apiKey:
+      name: ZHIPUAI_API_KEY
+      proxyManaged: true
+      inject:
+        - domain: open.bigmodel.cn
+          scheme: bearer
 
 environment:
   variables:
@@ -213,31 +270,54 @@ environment:
     COYOTE_LOG_LEVEL: INFO
     COYOTE_CONFIG_DIR: /home/agent/.config/coyote
     EDITOR: nano
-  proxyManaged:
-    - OPENAI_API_KEY
-    - ANTHROPIC_API_KEY
-    - GEMINI_API_KEY
-    - GOOGLE_API_KEY
-    - COHERE_API_KEY
-    - GROQ_API_KEY
-    - OPENROUTER_API_KEY
-    - AI21_API_KEY
-    - CLOUDFLARE_API_KEY
-    - DEEPINFRA_API_KEY
-    - DEEPSEEK_API_KEY
-    - MISTRAL_API_KEY
-    - PERPLEXITY_API_KEY
-    - VOYAGE_API_KEY
-    - XAI_API_KEY
-    - JINA_API_KEY
-    - ERNIE_API_KEY
-    - HUNYUAN_API_KEY
-    - MINIMAX_API_KEY
-    - MOONSHOT_API_KEY
-    - DASHSCOPE_API_KEY
-    - ZHIPUAI_API_KEY
+    # Alias for the gemini credential: v2 apiKey supports a single env name
+    # (GEMINI_API_KEY above). Coyote also recognizes GOOGLE_API_KEY, so keep
+    # it set to the sentinel. Header injection happens per-domain regardless
+    # of which env var the app reads.
+    GOOGLE_API_KEY: proxy-managed
+
+setup:
+  files:
+    - path: /home/agent/.config/git/ssh-signing-key-command
+      mode: '0755'
+      description: Resolve the forwarded SSH agent key for Git SSH signing
+      content: |
+        #!/bin/sh
+        set -e
+
+        if [ -z "$SSH_AUTH_SOCK" ]; then
+            echo "WARNING: [git-ssh-sign] no SSH agent - cannot sign commits" >&2
+        fi
+
+        key=$(ssh-add -L 2>/dev/null | head -n 1)
+        if [ -z "$key" ]; then
+            echo "WARNING: [git-ssh-sign] no keys in SSH agent - cannot sign commits" >&2
+        fi
+
+        config_dir="$GIT_SSH_SIGN_CONFIG_DIR"
+        if [ -z "$config_dir" ]; then
+            config_dir="/home/agent/.config/git"
+        fi
+        mkdir -p "$config_dir"
+
+        email=$(git config user.email 2>/dev/null || printf '%s' "agent@sandbox.local")
+        printf '%s %s\n' "$email" "$key" > "$config_dir/allowed_signers"
+        printf 'key::%s\n' "$key"
+
+  install:
+    - command: |
+        git config --system gpg.format ssh
+        git config --system --unset-all user.signingKey || true
+        git config --system commit.gpgSign true
+        git config --system tag.gpgSign true
+        git config --system gpg.ssh.defaultKeyCommand /home/agent/.config/git/ssh-signing-key-command
+        git config --system gpg.ssh.allowedSignersFile /home/agent/.config/git/allowed_signers
+        if [ "$(git config --system --get core.hooksPath || true)" = "/home/agent/.config/git/hooks" ]; then
+            git config --system --unset-all core.hooksPath
+        fi
+      user: '0'
+      description: Configure SSH commit signing with a dynamic key command
 
-commands:
   startup:
     - command:
         [
@@ -249,50 +329,45 @@ commands:
       background: false
       description: Bootstrap Coyote config directory on first sandbox start
 
-profiles:
-  headless:
-    description: >
-      Unattended mode for scripted use. Set COYOTE_PROMPT_FILE to the path of
-      a prompt file, then launch: sbx run coyote --profile headless
-    entrypoint:
-      run: ['bash', '-lc', 'exec /home/agent/.cargo/bin/coyote --headless -f "${COYOTE_PROMPT_FILE}"']
-    environment:
-      variables:
-        COYOTE_LOG_LEVEL: WARN
+agentInstructions:
+  filename: COYOTE.md
+  content: |
+    ## Sandbox environment
 
-agentContext: |
-  ## Sandbox environment
+    You are running inside a Docker sandbox launched via `sbx run coyote`. The
+    user's project workspace is mounted at its absolute host path and is the
+    current working directory. `sudo` is passwordless; use it for system
+    package installs.
 
-  You are running inside a Docker sandbox launched via `sbx run coyote`. The
-  user's project workspace is mounted at its absolute host path and is the
-  current working directory. `sudo` is passwordless; use it for system
-  package installs.
+    Coyote's configuration lives at `~/.config/coyote/` and logs at
+    `~/.cache/coyote/coyote.log`. Persistence is enabled, so config, sessions,
+    vault state, OAuth tokens, and installed tools survive sandbox restarts.
 
-  Coyote's configuration lives at `~/.config/coyote/` and logs at
-  `~/.cache/coyote/coyote.log`. Persistence is enabled, so config, sessions,
-  vault state, OAuth tokens, and installed tools survive sandbox restarts.
+    LLM provider credentials are forwarded by the sandbox HTTP proxy via
+    credential bindings. Coyote pre-seeds them from its vault at launch
+    (`sbx secret set <service>`); users can also bind values manually on the
+    host with `sbx secret set <service>` or `sbx secret import`. Recognized
+    services:
 
-  LLM provider credentials are forwarded by the sandbox HTTP proxy. The
-  following provider env vars are recognized - export the ones you use on
-  the host before running `sbx run coyote`:
+      openai, anthropic, gemini, cohere, groq, openrouter, ai21,
+      cloudflare, deepinfra, deepseek, mistral, perplexity, voyageai,
+      xai, jina, ernie, hunyuan, minimax, moonshot, qianwen, zhipuai
 
-    OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY,
-    COHERE_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, AI21_API_KEY,
-    CLOUDFLARE_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY,
-    MISTRAL_API_KEY, PERPLEXITY_API_KEY, VOYAGE_API_KEY, XAI_API_KEY,
-    JINA_API_KEY, ERNIE_API_KEY, HUNYUAN_API_KEY, MINIMAX_API_KEY, 
-    MOONSHOT_API_KEY, DASHSCOPE_API_KEY (Qwen), ZHIPUAI_API_KEY
+    Inside the sandbox the corresponding env vars (OPENAI_API_KEY, etc.)
+    hold the placeholder string `proxy-managed`; the proxy substitutes the
+    real value at request time. OAuth flows for Claude Pro/Max and Gemini
+    are also allow-listed.
 
-  Inside the sandbox these appear as the placeholder string `proxy-managed`;
-  the proxy substitutes the real value at request time. OAuth flows for
-  Claude Pro/Max and Gemini are also allow-listed.
+    Bedrock (AWS) and VertexAI (Google Cloud) use signed/OAuth-token requests
+    that the proxy cannot rewrite, so you must inject credentials yourself via
+    `sbx run --env AWS_ACCESS_KEY_ID=...` or a mixin kit that mounts a
+    service-account JSON. VertexAI regional endpoints are allow-listed via
+    `*.googleapis.com`. Bedrock runtime endpoints are allow-listed for
+    us-east-1/2, us-west-2, eu-west-1, eu-central-1, ap-southeast-2, and
+    ap-northeast-1 only; other regions need a mixin allow entry
+    (`bedrock-runtime.<region>.amazonaws.com`).
 
-  Bedrock (AWS) and VertexAI (Google Cloud) use signed/OAuth-token requests
-  that the proxy cannot rewrite. Their domains are allow-listed but you must
-  inject credentials yourself via `sbx run --env AWS_ACCESS_KEY_ID=...` or
-  a mixin kit that mounts a service-account JSON.
-
-  Useful first-run commands:
-  - `coyote --info`          # show config paths and resolved settings
-  - `coyote --list-secrets`  # initialise the local vault
-  - `coyote --authenticate <client>`  # OAuth flow (Claude Pro/Max, Gemini)
+    Useful first-run commands:
+    - `coyote --info`          # show config paths and resolved settings
+    - `coyote --list-secrets`  # initialise the local vault
+    - `coyote --authenticate <client>`  # OAuth flow (Claude Pro/Max, Gemini)

assets/skills/design-session/SKILL.md

@@ -0,0 +1,79 @@
+---
+description: AI-first design decomposition for any project. Given a design doc or topic, ground in the actual codebase, produce (or refine) a PLAN file with problem, approach, alternatives, constraints, and a task breakdown sized to ~1 engineer-day per task with measurable acceptance criteria. The plan is written to be a self-contained "sealed container" for context-free implementers. Grants filesystem access for grounding and for writing the plan.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write
+---
+You are decomposing a design doc (or topic) into an executable plan. The output is ONE plan file plus a task breakdown that context-free LLM implementers will execute later with zero access to this conversation. Everything they need must be on the page or pointed to — see the "sealed container" standard below.
+
+## Inputs
+
+- A design doc (path or pasted), or a one-line problem statement.
+- The target project directory (ground truth for all claims).
+- The plans directory where the PLAN file lands.
+
+## Step 1 — Ground before proposing
+
+Plans written from memory rot on contact with the code. Before writing anything:
+
+- Read the project's own orientation docs (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md` at the project root) — conventions constrain the design.
+- Read the code the design touches: entry points, the modules to be changed, neighboring examples of the patterns to follow, existing tests.
+- `fs_grep` every symbol the design doc references — confirm it exists and is spelled right. Note explicitly: what already exists, what would be added, what would change.
+- Verify build/test commands actually exist (`Makefile`, `justfile`, `package.json` scripts, CI config).
+
+## Step 2 — The proposal
+
+Produce a structured proposal (iterate with the user when interactive; in autonomous runs, resolve what the doc + code answer and flag the rest as open questions):
+
+- **Problem** — one paragraph; state assumptions explicitly.
+- **Scope** — In / Out. Call out tempting adjacent work being deferred.
+- **Approach** — concrete: name files, symbols, data flow, migrations. Reference existing patterns by path.
+- **Alternatives considered** — table of alternative → why rejected. Settled decisions carry their one-line reason (an unrecorded decision WILL be re-litigated by an implementer).
+- **Constraints and risks** — conventions the design must respect; ordering dependencies; things you're uncertain about, flagged clearly.
+- **Open questions** — ONLY questions the codebase cannot answer (business rules, priority calls). If none, say "No open questions."
+- **Task breakdown** — see below.
+
+## Task breakdown rules
+
+| Rule | Why |
+|---|---|
+| **One task ≈ one engineer-day** | Variable task sizes destroy progress signal; anything larger gets decomposed NOW, not mid-run |
+| Each task independently implementable and verifiable | It builds and its tests pass without later tasks existing |
+| Explicit, acyclic dependencies (`blocked_by`) | Execution order must be derivable from the breakdown alone |
+| Each task states WHERE (files/packages) and WHAT (observable outcome) | "Implement service layer" is not a task; "internal/foo/service.go: add Create/Get with validation — returns 400 on missing name" is |
+| Measurable acceptance criteria per task | Criteria become the tests; "works correctly" is unmeasurable |
+| Flag ⚠️ low-confidence sizing with the reason | Honest sizing beats optimistic sizing |
+
+## Step 3 — Write the PLAN file
+
+Write `PLAN-<slug>.md` (kebab-case slug from the topic; verify no collision) to the plans directory:
+
+```markdown
+---
+slug: <slug>
+status: draft        # draft | active | implemented
+created: YYYY-MM-DD
+---
+
+# <Title>
+
+## Problem
+## Scope (In / Out)
+## Approach
+## Alternatives considered
+## Constraints and risks
+## Open questions
+## Task breakdown
+
+| # | Task | Size | blocked_by | Notes |
+|---|------|------|-----------|-------|
+```
+
+The plan is the implementers' entire context. Write for the "sealed container" standard: every question an implementer will hit is either answered inline or delegated via a pointer to the exact file/doc that answers it (where infra code goes, what DB tech, which layout to mirror, exact test commands). Paste short code snippets for load-bearing patterns — a path alone forces re-exploration; a stale claim fails the executor mid-implementation.
+
+## Anti-patterns
+
+- Proposing before reading the code — a design ungrounded in the actual codebase is fiction.
+- "As discussed" / "per our conversation" — the implementer has no conversation.
+- Tasks larger than a day hiding an "and then also…".
+- Acceptance criteria describing implementation ("uses a for loop") instead of behavior.
+- Open questions the code could have answered — grep first, ask last.
+- Unrecorded decisions — every settled fork carries its reason.

assets/skills/plan-gatekeeping/SKILL.md

@@ -0,0 +1,89 @@
+---
+description: Gatekeep a plan for self-containedness before it is finalized. A plan must be a "sealed container" - either it answers every question a context-free LLM implementer will hit, or it points at the exact code/docs where the answer lives. Produces the missing questions and a PLAN_GATE SEALED/LEAKY verdict. Grants read-only filesystem access for verifying pointers actually resolve. Complements plan-review (executability) - this checks completeness of context, not correctness of approach.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are gatekeeping a plan before it is finalized. The standard is the **sealed-container test**: a fresh LLM implementer with ZERO conversation context and ZERO tribal knowledge will execute this plan. Every question that implementer would need answered mid-implementation must be either (a) **answered inline** in the plan, or (b) **delegated via a pointer** — an exact file/doc path that verifiably contains the answer. A plan that assumes the reader "just knows" where infrastructure code lives, which DB tech to use, or how services are laid out is a leaky container: the implementer will guess, and guesses become divergences.
+
+You are NOT reviewing the approach (that is `plan-review`'s job — executability, verifiability, ordering). You are auditing **completeness of context**. A plan with a flawless approach still fails this gate if it leaves the implementer to rediscover the environment.
+
+## The answer-or-pointer rule
+
+For every question in the manifest below, the plan must contain ONE of:
+
+1. **Inline answer** — the fact stated directly ("the service DB is Postgres on RDS, provisioned via `infra/rds/`", "migrations live in `internal/db/migrations/` and use goose").
+2. **Verified pointer** — a path to code or docs where the implementer can discover it ("read `CLAUDE.md` § Database conventions", "mirror the layout of `internal/services/rate_cards/`").
+
+An answer of neither kind = a missing question = a leak. "Follow existing conventions" with no pointer to WHICH file shows the convention is a leak. A pointer to a file that doesn't exist or doesn't actually cover the topic is a leak wearing a pointer costume — which is why you verify.
+
+## The manifest (question categories to audit)
+
+Walk EVERY category. For each, ask: "when the implementer hits this, does the plan answer it or point to the answer?"
+
+| # | Category | Questions the implementer WILL hit |
+|---|----------|-------------------------------------|
+| 1 | **Code placement** | Which repo? Which directory/package? Does a new service/module follow an existing layout — which one, exactly? |
+| 2 | **Infrastructure** | Where does infra code live? What is the deployment target (e.g. new DB in RDS via Terraform vs a Postgres container in Kubernetes)? Who provisions it — this plan's tasks, or a prerequisite? |
+| 3 | **Data layer** | What DB tech/engine? What migration tool and directory? What naming conventions for tables/columns? Which existing tables does this touch or reference? |
+| 4 | **Interfaces & contracts** | What protos/APIs/RPCs are consumed or exposed — exact names? Where do proto definitions live and how are they regenerated? What downstream consumers depend on the shapes this plan creates? |
+| 5 | **Conventions & tooling** | Which language/framework versions? Error-handling and logging patterns — which file shows the canon? Lint/format/build commands? Where is the repo's own CLAUDE.md / contributor doc and does the plan tell the implementer to read it? |
+| 6 | **Testing & verification** | Test framework and directory conventions? EXACT commands to run tests/build from the repo root? What proves each acceptance criterion? |
+| 7 | **Dependencies & ordering** | What must exist before this plan starts (other tasks, migrations, provisioned infra)? What does this plan produce that later work depends on? |
+| 8 | **Config, secrets & environments** | New env vars/config keys — where are they declared and injected? Secrets — vault/parameter store conventions? Staging vs production differences that affect implementation? |
+| 9 | **Scope boundaries** | Is Out of scope present and specific? Are "tempting adjacent fixes" explicitly deferred? |
+| 10 | **Settled decisions** | Are choices that were debated recorded WITH their one-line reason ("RDS over in-cluster Postgres because ops owns backups")? An unrecorded decision WILL be re-litigated by the implementer. |
+
+Not every category applies to every plan (a docs-only plan has no data layer). Mark inapplicable categories as such — silently skipping one is how leaks survive.
+
+## Pointer verification (do not trust, verify)
+
+For every pointer the plan offers:
+
+1. `fs_ls` / `fs_glob` — the referenced path exists.
+2. `fs_grep` / `fs_read` — the file actually covers the claimed topic. A plan saying "see `docs/database.md` for migration conventions" fails verification if that file never mentions migrations.
+3. For "mirror the layout of X" pointers — confirm X exists and is a real example of what the plan claims (a service directory held up as the canonical layout should actually contain the layers the plan describes).
+
+A broken pointer is worse than no pointer: it burns the implementer's time AND their trust in the rest of the plan.
+
+## Severity honesty
+
+Not every gap is equal. Tag each finding:
+
+- **BLOCKING** — the implementer cannot proceed or will guess wrong with expensive consequences (wrong DB target, wrong repo, missing prerequisite).
+- **FRICTION** — the implementer can discover the answer but will waste significant time re-exploring what the author already knew.
+
+A plan with only FRICTION findings may still be sealed at the caller's discretion — say so. BLOCKING findings always mean LEAKY.
+
+## Verdict format
+
+End with EXACTLY one of:
+
+```
+PLAN_GATE: SEALED
+Categories audited: N applicable, all answered or pointed.
+<optional: 1-3 non-blocking observations>
+```
+
+```
+PLAN_GATE: LEAKY
+Missing questions (N):
+1. [category] <the exact question the implementer will hit> — [BLOCKING|FRICTION] — <why they get stuck or guess wrong> — <suggested fix: the inline answer to add, or the pointer to insert (verified to exist)>
+2. ...
+Broken pointers (if any):
+- <plan's pointer> — <what's wrong: path missing / doesn't cover topic>
+```
+
+Every missing question must be phrased as the QUESTION the implementer would actually ask ("where do I put the Terraform for the new RDS instance?"), not as an abstract complaint ("infra section is thin"). When you suggest a pointer as the fix, VERIFY it first — never recommend a pointer you haven't confirmed resolves.
+
+## Scope discipline
+
+- Do not redesign the approach. If the approach is coherent but under-documented, the fix is context, not redesign.
+- Do not demand encyclopedic plans. The container test is "answered or pointed" — a tight plan full of verified pointers beats a bloated plan that inlines the whole wiki. Flag over-inlining only if it duplicates something that WILL drift (e.g. pasted conventions that contradict the source file).
+- Three BLOCKING questions beat fifteen FRICTION nitpicks. If your list is all nitpicks, the plan is probably SEALED — say so.
+
+## Anti-patterns
+
+- Sealing a plan because the approach is good, without walking the manifest.
+- Flagging "missing context" without phrasing the actual question the implementer would ask.
+- Recommending a pointer you did not verify exists and covers the topic.
+- Treating an inapplicable category as a leak (demanding a data-layer section from a docs-only plan).
+- Re-reviewing executability/approach — that is `plan-review`'s lane.

assets/skills/task-tracking/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: File-based task tracking for plan-driven runs on any project. Defines the TASK-NNN directory schema (index.md + append-only log.md), the frontmatter lifecycle (pending/in-progress/blocked/complete), numbering, the completion protocol, and follow-up task creation. The tasks directory on disk is the durable run state - it survives context compression. Grants filesystem access for managing task files.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir
+---
+You are tracking implementation tasks as files. The task directory is the durable source of truth for run state — anything that lives only in chat history is lost to context compression. Keep it current at every state change, not in batches.
+
+## Layout
+
+```
+<plans_dir>/
+  PLAN-<slug>.md                  # the plan (see design-session / plan-authoring)
+  tasks/
+    TASK-001-<slug>/
+      index.md                    # current state: frontmatter + What/Steps/Acceptance criteria
+      log.md                      # append-only audit trail
+    TASK-002-<slug>/
+      ...
+```
+
+## index.md schema
+
+```markdown
+---
+title: <short imperative title>
+status: pending        # pending | in-progress | blocked | complete
+type: feature          # feature | chore | followup
+points: 1.0            # engineer-days; ~1.0 per the sizing rule
+plan: PLAN-<slug>.md
+blocked_by: []         # TASK ids that must be complete first
+created: YYYY-MM-DD
+---
+
+## What
+
+One paragraph: what this task produces, named concretely (files, symbols, behaviors).
+
+## Steps
+
+- [ ] Concrete step — name the file, function, or migration
+- [ ] ...
+
+## Acceptance criteria
+
+- [ ] Observable behavior, measurable ("returns 429 after 3 failed attempts")
+- [ ] ...
+```
+
+Status lives in frontmatter — there are no lifecycle directories. `status: complete` plus all boxes checked IS done.
+
+## log.md conventions
+
+Append-only. Each entry is an H2: `## YYYY-MM-DD — <short label>` (`created`, `started`, `implemented`, `diverged`, `completed`, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.
+
+## Numbering
+
+Scan `tasks/TASK-*` for the highest NNN and increment (zero-padded to 3). This assumes a single writer per plans directory; if multiple agents or people share one, serialize task creation.
+
+## Lifecycle protocol
+
+| Transition | Do |
+|---|---|
+| Create | `fs_mkdir` the dir; write `index.md` (status: pending) + `log.md` with a `created` entry |
+| Claim | frontmatter `status: in-progress`; log `started` (note the branch + base SHA) |
+| Blocked | `status: blocked`; log why and what unblocks it |
+| Complete | Check off every Step and Acceptance criterion (verified, not aspirational); log `completed` with commit SHAs AND any follow-ups reported by the implementer, VERBATIM; set `status: complete` |
+
+Never mark a criterion checked without evidence. Never batch state changes — update at the moment of transition.
+
+## Follow-up tasks
+
+When implementation surfaces manual/out-of-scope actions (secrets to create, cloud roles to provision, console steps, cross-repo changes): create a task per item (group small related ones) with `type: followup`, `status: pending`, the WHAT/WHERE/WHY/WHEN in its What section, and a note of which TASK surfaced it. Follow-ups are deliverables to hand to the user — never implement them in the current run.
+
+## Consistency checks (run at the end of a run)
+
+- Every task dir has both `index.md` and `log.md`.
+- Every `blocked_by` reference resolves to an existing task.
+- No task is `complete` with unchecked Steps/Acceptance criteria.
+- Every `complete` task's log has a `completed` entry with commit references.
+- The PLAN's breakdown table rows all map to task dirs (and vice versa).
+
+## Anti-patterns
+
+- Run state that exists only in chat — session ids, decisions, and follow-ups belong in task files.
+- `status: complete` with unchecked boxes, or checked boxes without evidence.
+- Rewriting log history instead of appending.
+- Hand-picking a task number without scanning (collisions).
+- Follow-ups mentioned in a summary but never materialized as task files.

src/cli/mod.rs

@@ -13,6 +13,20 @@ use is_terminal::IsTerminal;
 use std::collections::HashSet;
 use std::io::{Read, stdin};
 
+#[derive(clap::ValueEnum, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum McpTransportArg {
+    Stdio,
+    Http,
+    Sse,
+}
+
+#[derive(clap::ValueEnum, Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum McpScopeArg {
+    #[default]
+    User,
+    Workspace,
+}
+
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about = None)]
 #[command(
@@ -41,10 +55,15 @@ use std::io::{Read, stdin};
 				"list_skills", "skill", "tail_logs", "completions", "update",
 			])
 	),
+	group(
+		ArgGroup::new("mcp-action")
+			.args(["mcp_add", "mcp_remove", "mcp_list", "mcp_get"])
+			.multiple(false)
+	),
 )]
 pub struct Cli {
     /// Input text
-    #[arg(trailing_var_arg = true)]
+    #[arg(allow_hyphen_values = true)]
     text: Vec<String>,
 
     /// Select a LLM model
@@ -224,6 +243,57 @@ pub struct Cli {
     #[arg(long, exclusive = true, value_name = "SERVER_NAME", help_heading = "Authentication", add = ArgValueCompleter::new(mcp_server_completer))]
     pub auth_mcp: Option<String>,
 
+    /// Add an MCP server. Use `-- <cmd> [args...]` for stdio, or `--url <URL>` for http/sse.
+    #[arg(long, value_name = "NAME", help_heading = "MCP Servers")]
+    pub mcp_add: Option<String>,
+    /// Remove an MCP server by name
+    #[arg(long, value_name = "NAME", help_heading = "MCP Servers", add = ArgValueCompleter::new(mcp_server_completer))]
+    pub mcp_remove: Option<String>,
+    /// List all configured MCP servers (user + workspace scopes)
+    #[arg(long, help_heading = "MCP Servers")]
+    pub mcp_list: bool,
+    /// Show the JSON config for one MCP server
+    #[arg(long, value_name = "NAME", help_heading = "MCP Servers", add = ArgValueCompleter::new(mcp_server_completer))]
+    pub mcp_get: Option<String>,
+    /// Transport for --mcp-add: stdio (default when `--` present), http, or sse
+    #[arg(
+        long,
+        value_enum,
+        value_name = "TRANSPORT",
+        help_heading = "MCP Servers"
+    )]
+    pub transport: Option<McpTransportArg>,
+    /// URL for http/sse MCP server (used with --mcp-add)
+    #[arg(long, value_name = "URL", help_heading = "MCP Servers")]
+    pub url: Option<String>,
+    /// Scope for MCP config: user (~/.config/coyote/functions/mcp.json) or workspace (./.coyote/mcp.json). Default: user
+    #[arg(long, value_enum, value_name = "SCOPE", help_heading = "MCP Servers")]
+    pub scope: Option<McpScopeArg>,
+    /// Environment variable for stdio MCP server (repeatable): --env KEY=VALUE
+    #[arg(long, value_name = "KEY=VALUE", help_heading = "MCP Servers")]
+    pub env: Vec<String>,
+    /// HTTP header for http/sse MCP server (repeatable): --header "Name: Value"
+    #[arg(long, value_name = "HEADER", help_heading = "MCP Servers")]
+    pub header: Vec<String>,
+    /// Working directory for stdio MCP server
+    #[arg(long, value_name = "PATH", value_hint = ValueHint::AnyPath, help_heading = "MCP Servers")]
+    pub cwd: Option<String>,
+    /// OAuth client ID for http/sse MCP server
+    #[arg(long, value_name = "ID", help_heading = "MCP Servers")]
+    pub client_id: Option<String>,
+    /// OAuth client secret for http/sse MCP server (use {{NAME}} to reference a vault secret)
+    #[arg(long, value_name = "SECRET", help_heading = "MCP Servers")]
+    pub client_secret: Option<String>,
+    /// OAuth callback port for http/sse MCP server
+    #[arg(long, value_name = "PORT", help_heading = "MCP Servers")]
+    pub callback_port: Option<u16>,
+    /// OAuth redirect host for http/sse MCP server
+    #[arg(long, value_name = "HOST", help_heading = "MCP Servers")]
+    pub redirect_host: Option<String>,
+    /// Overwrite an existing MCP server (with --mcp-add) or skip confirmation (with --mcp-remove)
+    #[arg(long, help_heading = "MCP Servers")]
+    pub mcp_force: bool,
+
     /// Launch Coyote inside a Docker sandbox (via `sbx`); name defaults to current directory basename
     #[arg(long, value_name = "NAME", help_heading = "Sandbox")]
     pub sandbox: Option<Option<String>>,
@@ -254,6 +324,15 @@ pub struct Cli {
     /// Generate static shell completion scripts
     #[arg(long, value_name = "SHELL", value_enum, help_heading = "Shell")]
     pub completions: Option<ShellCompletion>,
+
+    /// Stdio command for --mcp-add: everything after `--` is passed to the server verbatim
+    #[arg(
+        last = true,
+        allow_hyphen_values = true,
+        value_name = "CMD",
+        help_heading = "MCP Servers"
+    )]
+    pub mcp_command: Vec<String>,
 }
 
 impl Cli {
@@ -633,4 +712,85 @@ mod tests {
     fn parse_sandbox_is_exclusive() {
         assert!(Cli::try_parse_from(["coyote", "--sandbox", "--agent", "foo"]).is_err());
     }
+
+    #[test]
+    fn parse_mcp_add_stdio_with_trailing_command() {
+        let cli = parse(&[
+            "--mcp-add",
+            "myserver",
+            "--",
+            "npx",
+            "some-server",
+            "--flag",
+            "arg1",
+        ]);
+        assert_eq!(cli.mcp_add, Some("myserver".to_string()));
+        assert_eq!(
+            cli.mcp_command,
+            vec!["npx", "some-server", "--flag", "arg1"]
+        );
+        assert!(cli.text.is_empty());
+    }
+
+    #[test]
+    fn parse_mcp_add_stdio_with_env_and_command() {
+        let cli = parse(&[
+            "--mcp-add",
+            "s",
+            "--env",
+            "API_KEY={{API_KEY}}",
+            "--env",
+            "MODE=dev",
+            "--",
+            "npx",
+            "srv",
+        ]);
+        assert_eq!(cli.mcp_add, Some("s".to_string()));
+        assert_eq!(cli.env, vec!["API_KEY={{API_KEY}}", "MODE=dev"]);
+        assert_eq!(cli.mcp_command, vec!["npx", "srv"]);
+    }
+
+    #[test]
+    fn parse_mcp_add_http_with_header() {
+        let cli = parse(&[
+            "--mcp-add",
+            "notion",
+            "--transport",
+            "http",
+            "--url",
+            "https://mcp.notion.com/mcp",
+            "--header",
+            "Authorization: Bearer {{NOTION_TOKEN}}",
+        ]);
+        assert_eq!(cli.mcp_add, Some("notion".to_string()));
+        assert!(matches!(cli.transport, Some(McpTransportArg::Http)));
+        assert_eq!(cli.url, Some("https://mcp.notion.com/mcp".to_string()));
+        assert_eq!(cli.header, vec!["Authorization: Bearer {{NOTION_TOKEN}}"]);
+        assert!(cli.mcp_command.is_empty());
+    }
+
+    #[test]
+    fn parse_mcp_list_flag() {
+        let cli = parse(&["--mcp-list"]);
+        assert!(cli.mcp_list);
+    }
+
+    #[test]
+    fn parse_mcp_scope_workspace() {
+        let cli = parse(&["--mcp-list", "--scope", "workspace"]);
+        assert!(cli.mcp_list);
+        assert!(matches!(cli.scope, Some(McpScopeArg::Workspace)));
+    }
+
+    #[test]
+    fn parse_mcp_action_group_is_exclusive() {
+        assert!(Cli::try_parse_from(["coyote", "--mcp-list", "--mcp-get", "foo"]).is_err());
+    }
+
+    #[test]
+    fn parse_trailing_text_unchanged_without_dash_dash() {
+        let cli = parse(&["hello", "world"]);
+        assert_eq!(cli.text, vec!["hello", "world"]);
+        assert!(cli.mcp_command.is_empty());
+    }
 }

src/client/bedrock.rs

@@ -1,3 +1,5 @@
+use std::mem;
+
 use super::*;
 
 use crate::utils::{base64_decode, encode_uri, hex_encode, hmac_sha256, sha256, strip_think_tag};
@@ -275,10 +277,11 @@ async fn chat_completions_streaming(
                                     format!("Tool call '{function_name}' has non-JSON arguments '{function_arguments}'")
                                 })?;
                                 handler.tool_call(ToolCall::new(
-                                    function_name.clone(),
+                                    mem::take(&mut function_name),
                                     arguments,
-                                    Some(function_id.clone()),
+                                    Some(mem::take(&mut function_id)),
                                 ))?;
+                                function_arguments.clear();
                             }
                         }
                         _ => {}
@@ -529,7 +532,11 @@ fn extract_chat_completions(data: &Value) -> Result<ChatCompletionsOutput> {
         bail!("Invalid response data: {data}");
     }
 
-    let output = ChatCompletionsOutput { text, tool_calls, ..Default::default() };
+    let output = ChatCompletionsOutput {
+        text,
+        tool_calls,
+        ..Default::default()
+    };
     Ok(output)
 }
 

src/client/claude.rs

@@ -1,3 +1,6 @@
+use std::collections::HashSet;
+use std::mem;
+
 use super::access_token::get_access_token;
 use super::claude_oauth::ClaudeOAuthProvider;
 use super::oauth::{self, OAuthProvider};
@@ -212,12 +215,8 @@ pub async fn claude_chat_completions_streaming(
                     if let Some(text) = data["delta"]["text"].as_str() {
                         handler.text(text)?;
                     } else if let Some(text) = data["delta"]["thinking"].as_str() {
-                        if reasoning_state == 0 {
-                            handler.text("<think>\n")?;
-                            reasoning_state = 1;
-                        }
+                        reasoning_state = 1;
                         thinking_text.push_str(text);
-                        handler.text(text)?;
                     } else if let Some(signature) = data["delta"]["signature"].as_str() {
                         thinking_signature.push_str(signature);
                     } else if let (true, Some(partial_json)) = (
@@ -229,11 +228,10 @@ pub async fn claude_chat_completions_streaming(
                 }
                 "content_block_stop" => {
                     if reasoning_state == 1 {
-                        handler.text("\n</think>\n\n")?;
                         reasoning_state = 0;
                         handler.thinking_block(ThinkingBlock::Thinking {
-                            thinking: std::mem::take(&mut thinking_text),
-                            signature: std::mem::take(&mut thinking_signature),
+                            thinking: mem::take(&mut thinking_text),
+                            signature: mem::take(&mut thinking_signature),
                         });
                     }
                     if !function_name.is_empty() {
@@ -245,10 +243,11 @@ pub async fn claude_chat_completions_streaming(
                             })?
                         };
                         handler.tool_call(ToolCall::new(
-                            function_name.clone(),
+                            mem::take(&mut function_name),
                             arguments,
-                            Some(function_id.clone()),
+                            Some(mem::take(&mut function_id)),
                         ))?;
+                        function_arguments.clear();
                     }
                 }
                 _ => {}
@@ -326,51 +325,114 @@ pub fn claude_build_chat_completions_body(
                     })]
                 }
                 MessageContent::ToolCalls(MessageContentToolCalls {
-                    tool_results, text, ..
+                    tool_results,
+                    text,
+                    sequence,
                 }) => {
-                    let mut assistant_parts = vec![];
-                    let mut user_parts = vec![];
-                    for (index, tool_result) in tool_results.iter().enumerate() {
-                        for block in &tool_result.thinking {
-                            assistant_parts.push(json!(block));
-                        }
-                        let round_text = if index == 0 && !text.is_empty() {
-                            Some(text.as_str())
-                        } else {
-                            tool_result.text.as_deref()
-                        };
-                        if let Some(round_text) = round_text {
-                            let round_text = strip_think_tag(round_text);
-                            let round_text = round_text.trim();
-                            if !round_text.is_empty() {
-                                assistant_parts.push(json!({
-                                    "type": "text",
-                                    "text": round_text,
-                                }))
+                    if !sequence {
+                        let mut assistant_parts = vec![];
+                        let mut user_parts = vec![];
+                        for (index, tool_result) in tool_results.iter().enumerate() {
+                            for block in &tool_result.thinking {
+                                assistant_parts.push(json!(block));
                             }
+                            let round_text = if index == 0 && !text.is_empty() {
+                                Some(text.as_str())
+                            } else {
+                                tool_result.text.as_deref()
+                            };
+                            if let Some(round_text) = round_text {
+                                let round_text = strip_think_tag(round_text);
+                                let round_text = round_text.trim();
+                                if !round_text.is_empty() {
+                                    assistant_parts.push(json!({
+                                        "type": "text",
+                                        "text": round_text,
+                                    }))
+                                }
+                            }
+                            assistant_parts.push(json!({
+                                "type": "tool_use",
+                                "id": tool_result.call.id,
+                                "name": tool_result.call.name,
+                                "input": tool_result.call.arguments,
+                            }));
+                            user_parts.push(json!({
+                                "type": "tool_result",
+                                "tool_use_id": tool_result.call.id,
+                                "content": tool_result.output.to_string(),
+                            }));
                         }
-                        assistant_parts.push(json!({
-                            "type": "tool_use",
-                            "id": tool_result.call.id,
-                            "name": tool_result.call.name,
-                            "input": tool_result.call.arguments,
-                        }));
-                        user_parts.push(json!({
-                            "type": "tool_result",
-                            "tool_use_id": tool_result.call.id,
-                            "content": tool_result.output.to_string(),
-                        }));
+                        vec![
+                            json!({ "role": "assistant", "content": assistant_parts }),
+                            json!({ "role": "user", "content": user_parts }),
+                        ]
+                    } else {
+                        // One pair per round: Claude can reuse tool_use IDs across API calls.
+                        // A round boundary is detected by the presence of round text, but
+                        // rounds where the model emitted only tool calls (no narration)
+                        // carry no text marker. As a backstop, also split whenever a
+                        // tool_use ID would repeat within the current assistant message —
+                        // the API rejects duplicate tool_use IDs in a single message.
+                        let mut messages = vec![];
+                        let mut assistant_parts: Vec<serde_json::Value> = vec![];
+                        let mut user_parts: Vec<serde_json::Value> = vec![];
+                        let mut chunk_ids: HashSet<&str> = HashSet::new();
+                        for (index, tool_result) in tool_results.iter().enumerate() {
+                            let id_collision = tool_result
+                                .call
+                                .id
+                                .as_deref()
+                                .is_some_and(|id| chunk_ids.contains(id));
+                            if index > 0 && (tool_result.text.is_some() || id_collision) {
+                                messages.push(
+                                    json!({ "role": "assistant", "content": assistant_parts }),
+                                );
+                                messages.push(json!({ "role": "user", "content": user_parts }));
+                                assistant_parts = vec![];
+                                user_parts = vec![];
+                                chunk_ids.clear();
+                            }
+                            if let Some(id) = tool_result.call.id.as_deref() {
+                                chunk_ids.insert(id);
+                            }
+                            for block in &tool_result.thinking {
+                                assistant_parts.push(json!(block));
+                            }
+                            let round_text = if index == 0 && !text.is_empty() {
+                                Some(text.as_str())
+                            } else {
+                                tool_result.text.as_deref()
+                            };
+                            if let Some(round_text) = round_text {
+                                let round_text = strip_think_tag(round_text);
+                                let round_text = round_text.trim();
+                                if !round_text.is_empty() {
+                                    assistant_parts.push(json!({
+                                        "type": "text",
+                                        "text": round_text,
+                                    }))
+                                }
+                            }
+                            assistant_parts.push(json!({
+                                "type": "tool_use",
+                                "id": tool_result.call.id,
+                                "name": tool_result.call.name,
+                                "input": tool_result.call.arguments,
+                            }));
+                            user_parts.push(json!({
+                                "type": "tool_result",
+                                "tool_use_id": tool_result.call.id,
+                                "content": tool_result.output.to_string(),
+                            }));
+                        }
+                        if !assistant_parts.is_empty() {
+                            messages
+                                .push(json!({ "role": "assistant", "content": assistant_parts }));
+                            messages.push(json!({ "role": "user", "content": user_parts }));
+                        }
+                        messages
                     }
-                    vec![
-                        json!({
-                            "role": "assistant",
-                            "content": assistant_parts,
-                        }),
-                        json!({
-                            "role": "user",
-                            "content": user_parts,
-                        }),
-                    ]
                 }
             }
         })
@@ -430,7 +492,6 @@ pub fn claude_build_chat_completions_body(
 
 pub fn claude_extract_chat_completions(data: &Value) -> Result<ChatCompletionsOutput> {
     let mut text = String::new();
-    let mut reasoning = None;
     let mut tool_calls = vec![];
     let mut thinking = vec![];
     if let Some(list) = data["content"].as_array() {
@@ -438,7 +499,6 @@ pub fn claude_extract_chat_completions(data: &Value) -> Result<ChatCompletionsOu
             match item["type"].as_str() {
                 Some("thinking") => {
                     if let Some(v) = item["thinking"].as_str() {
-                        reasoning = Some(v.to_string());
                         thinking.push(ThinkingBlock::Thinking {
                             thinking: v.to_string(),
                             signature: item["signature"].as_str().unwrap_or_default().to_string(),
@@ -477,10 +537,6 @@ pub fn claude_extract_chat_completions(data: &Value) -> Result<ChatCompletionsOu
             }
         }
     }
-    if let Some(reasoning) = reasoning {
-        text = format!("<think>\n{reasoning}\n</think>\n\n{text}")
-    }
-
     if text.is_empty() && tool_calls.is_empty() {
         bail!("Invalid response data: {data}");
     }
@@ -492,3 +548,100 @@ pub fn claude_extract_chat_completions(data: &Value) -> Result<ChatCompletionsOu
     };
     Ok(output)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::function::{ToolCall, ToolResult};
+
+    fn tool_result(id: &str, text: Option<&str>) -> ToolResult {
+        ToolResult {
+            call: ToolCall::new("fs_read".into(), json!({"path": "x"}), Some(id.into())),
+            output: json!("ok"),
+            text: text.map(|t| t.to_string()),
+            thinking: vec![],
+        }
+    }
+
+    fn build_body(tool_results: Vec<ToolResult>) -> Value {
+        let data = ChatCompletionsData {
+            messages: vec![
+                Message::new(MessageRole::User, MessageContent::Text("hello".to_string())),
+                Message::new(
+                    MessageRole::Assistant,
+                    MessageContent::ToolCalls(MessageContentToolCalls {
+                        tool_results,
+                        text: String::new(),
+                        sequence: true,
+                    }),
+                ),
+            ],
+            temperature: None,
+            top_p: None,
+            reasoning_effort: None,
+            functions: None,
+            stream: false,
+        };
+        claude_build_chat_completions_body(data, &Model::new("claude", "claude-test")).unwrap()
+    }
+
+    fn assert_unique_tool_use_ids_per_message(body: &Value) {
+        for message in body["messages"].as_array().unwrap() {
+            let Some(content) = message["content"].as_array() else {
+                continue;
+            };
+            let mut seen = HashSet::new();
+            for block in content {
+                if block["type"] == "tool_use" {
+                    let id = block["id"].as_str().unwrap();
+                    assert!(
+                        seen.insert(id.to_string()),
+                        "duplicate tool_use id `{id}` within a single assistant message: {message}"
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn sequence_splits_on_round_text() {
+        let body = build_body(vec![
+            tool_result("toolu_A", None),
+            tool_result("toolu_B", None),
+            tool_result("toolu_C", Some("running another tool")),
+        ]);
+
+        let messages = body["messages"].as_array().unwrap();
+
+        assert_eq!(messages.len(), 5, "body: {body}");
+        assert_unique_tool_use_ids_per_message(&body);
+    }
+
+    #[test]
+    fn sequence_splits_on_reused_id_in_textless_round() {
+        let body = build_body(vec![
+            tool_result("toolu_A", None),
+            tool_result("toolu_B", None),
+            tool_result("toolu_A", None),
+        ]);
+
+        let messages = body["messages"].as_array().unwrap();
+
+        assert_eq!(messages.len(), 5, "body: {body}");
+        assert_unique_tool_use_ids_per_message(&body);
+    }
+
+    #[test]
+    fn sequence_keeps_textless_rounds_merged_when_ids_are_unique() {
+        let body = build_body(vec![
+            tool_result("toolu_A", None),
+            tool_result("toolu_B", None),
+            tool_result("toolu_C", None),
+        ]);
+
+        let messages = body["messages"].as_array().unwrap();
+
+        assert_eq!(messages.len(), 3, "body: {body}");
+        assert_unique_tool_use_ids_per_message(&body);
+    }
+}

src/client/common.rs

@@ -493,13 +493,39 @@ pub async fn call_chat_completions_streaming(
         render_stream(rx, client.app_config(), abort_signal.clone(), silent),
     );
 
-    if handler.abort().aborted() {
+    let aborted_ctrlc = handler.abort().aborted_ctrlc();
+    let aborted_ctrld = handler.abort().aborted_ctrld();
+
+    if aborted_ctrld {
         bail!("Aborted.");
     }
 
     render_ret?;
 
     let (text, tool_calls, thinking) = handler.take();
+
+    if aborted_ctrlc {
+        if !ctx.working_mode.is_repl() || ctx.session.is_none() {
+            bail!("Aborted.");
+        }
+
+        if text.is_empty() {
+            if !silent && *IS_STDOUT_TERMINAL {
+                println!();
+                eprintln!("{}", error_text("Response interrupted"));
+            }
+
+            return Ok(("".to_string(), vec![]));
+        }
+
+        if !silent && *IS_STDOUT_TERMINAL {
+            println!();
+            eprintln!("{}", error_text("Response interrupted"));
+        }
+
+        return Ok((text, vec![]));
+    }
+
     match send_ret {
         Ok(_) => {
             if !silent && !text.is_empty() && !text.ends_with('\n') {

src/client/oauth.rs

@@ -131,6 +131,17 @@ pub trait OAuthProvider: Send + Sync {
         vec![]
     }
 
+    /// Extra form/body parameters appended to every token request routed
+    /// through `build_token_request` (authorization-code exchange, refresh,
+    /// client_credentials, and device-code polling). Used e.g. for the
+    /// RFC 8707 `resource` indicator required by the MCP spec.
+    /// NOTE: these are merged AFTER the caller's params and will overwrite
+    /// a colliding key; do not return protocol parameter names
+    /// (grant_type, client_id, code, refresh_token, ...).
+    fn extra_token_params(&self) -> Vec<(&str, &str)> {
+        vec![]
+    }
+
     fn token_request_format(&self) -> TokenRequestFormat {
         TokenRequestFormat::Json
     }
@@ -642,9 +653,14 @@ fn build_token_request(
     provider: &(impl OAuthProvider + ?Sized),
     params: &[(&str, &str)],
 ) -> RequestBuilder {
+    let all_params: Vec<(&str, &str)> = params
+        .iter()
+        .copied()
+        .chain(provider.extra_token_params())
+        .collect();
     let mut request = match provider.token_request_format() {
         TokenRequestFormat::Json => {
-            let body: serde_json::Map<String, Value> = params
+            let body: serde_json::Map<String, Value> = all_params
                 .iter()
                 .map(|(k, v)| (k.to_string(), Value::String(v.to_string())))
                 .collect();
@@ -660,7 +676,7 @@ fn build_token_request(
             }
         }
         TokenRequestFormat::FormUrlEncoded => {
-            let mut form: HashMap<String, String> = params
+            let mut form: HashMap<String, String> = all_params
                 .iter()
                 .map(|(k, v)| (k.to_string(), v.to_string()))
                 .collect();
@@ -870,6 +886,8 @@ pub(crate) fn client_config_info(
 
 #[cfg(test)]
 mod tests {
+    use std::str;
+
     use super::*;
     use crate::client::openai_compatible::OpenAICompatibleConfig;
     use crate::client::{ModelData, ProviderModels};
@@ -1161,6 +1179,16 @@ echo_pkce_in_token_exchange: true
         assert!(provider.fixed_redirect_uri().is_none());
     }
 
+    #[test]
+    fn default_extra_token_params_is_empty() {
+        let provider = OpenAICompatibleOAuthProvider {
+            config: base_config(),
+            client_name: "test".into(),
+        };
+
+        assert!(provider.extra_token_params().is_empty());
+    }
+
     #[test]
     fn oauth_flow_device_code_parses() {
         let yaml = "client_id: x\ntoken_url: y\nflow: device_code";
@@ -1381,4 +1409,63 @@ scopes:
         assert!(cfg.use_pkce_in_device_flow);
         assert_eq!(cfg.scopes, vec!["read", "write"]);
     }
+
+    struct ResourceStubProvider;
+
+    impl OAuthProvider for ResourceStubProvider {
+        fn provider_name(&self) -> &str {
+            "stub"
+        }
+
+        fn client_id(&self) -> &str {
+            "stub-client"
+        }
+
+        fn authorize_url(&self) -> &str {
+            "https://as.example/authorize"
+        }
+
+        fn token_url(&self) -> &str {
+            "https://as.example/token"
+        }
+
+        fn redirect_uri(&self) -> &str {
+            ""
+        }
+
+        fn scopes(&self) -> String {
+            String::new()
+        }
+
+        fn token_request_format(&self) -> TokenRequestFormat {
+            TokenRequestFormat::FormUrlEncoded
+        }
+
+        fn extra_token_params(&self) -> Vec<(&str, &str)> {
+            vec![("resource", "https://rs.example/mcp")]
+        }
+    }
+
+    #[test]
+    fn build_token_request_appends_extra_token_params_to_form_body() {
+        let provider = ResourceStubProvider;
+
+        let request = build_token_request(
+            &ReqwestClient::new(),
+            &provider,
+            &[("grant_type", "authorization_code")],
+        )
+        .build()
+        .unwrap();
+
+        let body = str::from_utf8(request.body().unwrap().as_bytes().unwrap()).unwrap();
+        assert!(
+            body.contains("resource=https%3A%2F%2Frs.example%2Fmcp"),
+            "body missing resource param: {body}"
+        );
+        assert!(
+            body.contains("grant_type=authorization_code"),
+            "body missing grant_type param: {body}"
+        );
+    }
 }

src/config/agent.rs

@@ -4,6 +4,7 @@ use crate::{
     client::Model,
     config::memory,
     function::{Functions, run_llm_function},
+    graph, rag,
 };
 
 use super::rag_cache::RagKey;
@@ -12,6 +13,7 @@ use crate::config::prompts::{
     DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS, DEFAULT_TODO_INSTRUCTIONS,
     DEFAULT_USER_INTERACTION_INSTRUCTIONS,
 };
+use crate::graph::types::RagNode;
 use crate::graph::{Graph, GraphParser, NodeType};
 use crate::rag::RagInitConfig;
 use crate::vault::SECRET_RE;
@@ -146,11 +148,18 @@ impl Agent {
         let rag = if rag_path.exists() {
             let key = RagKey::Agent(name.to_string());
             let app_clone = app.clone();
+            let vault_clone = app_state.vault.clone();
             let rag_path_clone = rag_path.clone();
             let rag = app_state
                 .rag_cache
                 .load_with(key, || async move {
-                    Rag::load(&app_clone, DEFAULT_AGENT_NAME, &rag_path_clone)
+                    Rag::load_async(
+                        &app_clone,
+                        &vault_clone,
+                        DEFAULT_AGENT_NAME,
+                        &rag_path_clone,
+                    )
+                    .await
                 })
                 .await?;
             Some(rag)
@@ -171,7 +180,15 @@ impl Agent {
                 let rag = app_state
                     .rag_cache
                     .load_with(key, || async move {
-                        Rag::init(&app_clone, "rag", &rag_path_clone, &document_paths, abort).await
+                        Rag::init(
+                            &app_clone,
+                            "rag",
+                            &rag_path_clone,
+                            &document_paths,
+                            abort,
+                            true,
+                        )
+                        .await
                     })
                     .await?;
                 Some(rag)
@@ -231,6 +248,10 @@ impl Agent {
             }
         }
 
+        if rag.is_some() && app.function_calling_support && graph_for_rag.is_none() {
+            functions.append_rag_query_functions();
+        }
+
         agent_config.replace_tools_placeholder(&functions);
 
         Ok(Self {
@@ -573,6 +594,25 @@ impl Agent {
             _ => bail!("No return value from '_instructions' function"),
         }
     }
+
+    #[cfg(test)]
+    pub fn test_new(config: AgentConfig) -> Self {
+        Self {
+            name: config.name.clone(),
+            config,
+            shared_variables: Default::default(),
+            session_variables: None,
+            shared_dynamic_instructions: None,
+            session_dynamic_instructions: None,
+            functions: Functions::default(),
+            rag: None,
+            graph_rags: Default::default(),
+            model: Model::default(),
+            vault: std::sync::Arc::new(Vault::default()),
+            is_graph: false,
+            enabled_tools: None,
+        }
+    }
 }
 
 impl RoleLike for Agent {
@@ -918,6 +958,30 @@ fn resolve_document_paths(
     Ok(document_paths)
 }
 
+/// How a graph rag node describes the knowledge base it wants built.
+///
+/// `driver` is forwarded as-is: `None` means the node did not ask for one, which
+/// `RagInitConfig` resolves to yaml, so workflows written before drivers existed
+/// keep their current storage.
+///
+/// Every field is now named explicitly, so adding one to `RagInitConfig` breaks
+/// this literal. That is deliberate: the new field then gets a decision about
+/// whether a rag node can drive it, instead of silently taking its default.
+fn rag_init_config(rag_node: &RagNode) -> RagInitConfig {
+    RagInitConfig {
+        embedding_model: rag_node.embedding_model.clone(),
+        chunk_size: rag_node.chunk_size,
+        chunk_overlap: rag_node.chunk_overlap,
+        reranker_model: rag_node.reranker_model.clone(),
+        top_k: rag_node.top_k,
+        batch_size: rag_node.batch_size,
+        extractor_model: rag_node.extractor_model.clone(),
+        extractor_prompt: rag_node.extractor_prompt.clone(),
+        graph_hops: rag_node.graph_hops,
+        driver: rag_node.driver.clone(),
+    }
+}
+
 #[allow(clippy::too_many_arguments)]
 async fn init_graph_rags(
     app: &AppConfig,
@@ -945,26 +1009,28 @@ async fn init_graph_rags(
         };
         let rag = if rag_path.exists() {
             let app_clone = app.clone();
+            let vault_clone = app_state.vault.clone();
             let path_clone = rag_path.clone();
             let name_clone = node_id.clone();
             app_state
                 .rag_cache
                 .load_with(key, || async move {
-                    Rag::load(&app_clone, &name_clone, &path_clone)
+                    Rag::load_async(&app_clone, &vault_clone, &name_clone, &path_clone).await
                 })
                 .await?
         } else {
-            let config = RagInitConfig {
-                embedding_model: rag_node.embedding_model.clone(),
-                chunk_size: rag_node.chunk_size,
-                chunk_overlap: rag_node.chunk_overlap,
-                reranker_model: rag_node.reranker_model.clone(),
-                top_k: rag_node.top_k,
-                batch_size: rag_node.batch_size,
-                extractor_model: rag_node.extractor_model.clone(),
-                extractor_prompt: rag_node.extractor_prompt.clone(),
-                graph_hops: rag_node.graph_hops,
-            };
+            // Checked before anything is built: an unknown driver would otherwise
+            // fall through `Rag::create`'s catch-all to a yaml store, embed every
+            // document, and persist the bogus driver string. The RAG would then be
+            // rejected on every subsequent load, leaving the agent unstartable.
+            // Graph validation catches this too, but it is skipped when
+            // `validate_before_run` is off, so this guard is the load-bearing one.
+            if let Some(driver) = &rag_node.driver
+                && let Some(message) = graph::validator::rag_driver_error(driver)
+            {
+                bail!("rag node '{node_id}': {message}");
+            }
+            let mut config = rag_init_config(rag_node);
             let fully_specified = config.embedding_model.is_some()
                 && config.chunk_size.is_some()
                 && config.chunk_overlap.is_some();
@@ -990,6 +1056,10 @@ async fn init_graph_rags(
                          initialized. RAG initialization is required for this agent."
                     );
                 }
+
+                if config.driver.is_none() {
+                    config.driver = Some(rag::select_rag_driver()?);
+                }
             }
 
             let document_paths =
@@ -1298,4 +1368,39 @@ version: "1.0"
 
         assert_eq!(meta.description, "");
     }
+
+    #[test]
+    fn rag_init_config_forwards_an_explicit_driver() {
+        let node: RagNode =
+            serde_yaml::from_str("documents: [\"./docs\"]\ndriver: duckdb\n").unwrap();
+
+        assert_eq!(rag_init_config(&node).driver.as_deref(), Some("duckdb"));
+    }
+
+    /// A node that names no driver must forward `None`, which `RagInitConfig`
+    /// documents as "yaml". Existing workflows therefore keep their yaml store.
+    #[test]
+    fn rag_init_config_leaves_the_driver_unset_by_default() {
+        let node: RagNode = serde_yaml::from_str("documents: [\"./docs\"]\n").unwrap();
+
+        assert_eq!(rag_init_config(&node).driver, None);
+    }
+
+    /// The driver must ride alongside the rest of the node's settings, not
+    /// replace them.
+    #[test]
+    fn rag_init_config_forwards_the_other_settings_too() {
+        let node: RagNode = serde_yaml::from_str(
+            "documents: [\"./docs\"]\ndriver: duckdb\nchunk_size: 512\nchunk_overlap: 64\ntop_k: 7\nembedding_model: some:model\n",
+        )
+        .unwrap();
+
+        let config = rag_init_config(&node);
+
+        assert_eq!(config.driver.as_deref(), Some("duckdb"));
+        assert_eq!(config.chunk_size, Some(512));
+        assert_eq!(config.chunk_overlap, Some(64));
+        assert_eq!(config.top_k, Some(7));
+        assert_eq!(config.embedding_model.as_deref(), Some("some:model"));
+    }
 }

src/config/input.rs

@@ -321,6 +321,10 @@ impl Input {
         }
     }
 
+    pub fn with_session(&self) -> bool {
+        self.with_session
+    }
+
     pub fn with_agent(&self) -> bool {
         self.with_agent
     }

src/config/install_remote.rs

@@ -947,6 +947,7 @@ fn print_secret_summary(added: &[String], deferred: &[String]) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::sandbox::SANDBOX_ENV_FLAG;
     use crate::utils::get_env_name;
     use serial_test::serial;
     use std::env;
@@ -1431,6 +1432,12 @@ mod tests {
     #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
     #[serial]
     async fn merge_detects_missing_secrets_in_output() {
+        if env::var_os(SANDBOX_ENV_FLAG).is_some() {
+            eprintln!(
+                "Skipping merge_detects_missing_secrets_in_output: secret interpolation is disabled inside a sandbox"
+            );
+            return;
+        }
         let _guard = TestVaultConfigGuard::new("merge-secret");
         let dir = fresh_temp_dir("merge-secret-");
         let remote = dir.join("remote.json");

src/config/paths.rs

@@ -16,7 +16,7 @@ use anyhow::{Context, Result, anyhow, bail};
 use log::LevelFilter;
 use std::collections::HashSet;
 use std::env;
-use std::fs::{read_dir, read_to_string};
+use std::fs::{read_dir, read_to_string, remove_file};
 use std::path::{Path, PathBuf};
 
 pub fn config_dir() -> PathBuf {
@@ -414,6 +414,10 @@ pub fn list_rags() -> Vec<String> {
             for entry in rd.flatten() {
                 let name = entry.file_name();
                 if let Some(name) = name.to_string_lossy().strip_suffix(".yaml") {
+                    if is_rag_sidecar_name(name) {
+                        continue;
+                    }
+
                     names.push(name.to_string());
                 }
             }
@@ -424,6 +428,34 @@ pub fn list_rags() -> Vec<String> {
     }
 }
 
+pub(crate) fn is_rag_sidecar_name(name: &str) -> bool {
+    name.ends_with(".sbx-mixin")
+}
+
+pub(crate) fn remove_rag_sidecars(dir: &Path, name: &str) -> Result<()> {
+    let duckdb_path = dir.join(format!("{name}.duckdb"));
+    if duckdb_path.exists() {
+        let _ = remove_file(&duckdb_path);
+    }
+    let wal_path = dir.join(format!("{name}.duckdb.wal"));
+    if wal_path.exists() {
+        let _ = remove_file(&wal_path);
+    }
+    let mixin_path = dir.join(format!("{name}.sbx-mixin.yaml"));
+    if mixin_path.exists() {
+        remove_file(&mixin_path).with_context(|| {
+            format!(
+                "Failed to remove the sandbox mixin for RAG '{name}' at '{}'. \
+                 The RAG was NOT deleted so you can retry; this host remains \
+                 whitelisted in the sandbox until the file is removed.",
+                mixin_path.display()
+            )
+        })?;
+    }
+
+    Ok(())
+}
+
 pub fn list_macros() -> Vec<String> {
     list_file_names(macros_dir(), ".yaml")
 }
@@ -846,4 +878,72 @@ mod tests {
         }
         let _ = fs::remove_dir_all(&root);
     }
+
+    fn sidecar_temp_dir(label: &str) -> PathBuf {
+        let unique = time::SystemTime::now()
+            .duration_since(time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let root = env::temp_dir().join(format!("coyote-{label}-test-{unique}"));
+        fs::create_dir_all(&root).unwrap();
+        root
+    }
+
+    #[test]
+    fn is_rag_sidecar_name_accepts_dotted_rag_names() {
+        assert!(!is_rag_sidecar_name("v2.docs"));
+        assert!(!is_rag_sidecar_name("myrag"));
+        assert!(is_rag_sidecar_name("myrag.sbx-mixin"));
+        assert!(is_rag_sidecar_name("v2.docs.sbx-mixin"));
+    }
+
+    #[test]
+    fn remove_rag_sidecars_removes_duckdb_wal_and_mixin() {
+        let root = sidecar_temp_dir("rag-sidecars-both");
+        let duckdb = root.join("docs.duckdb");
+        let wal = root.join("docs.duckdb.wal");
+        let mixin = root.join("docs.sbx-mixin.yaml");
+        fs::write(&duckdb, "db").unwrap();
+        fs::write(&wal, "wal").unwrap();
+        fs::write(&mixin, "mixin").unwrap();
+
+        remove_rag_sidecars(&root, "docs").unwrap();
+
+        assert!(!duckdb.exists(), "the .duckdb sidecar must be removed");
+        assert!(!wal.exists(), "the .duckdb.wal sidecar must be removed");
+        assert!(
+            !mixin.exists(),
+            "the .sbx-mixin.yaml sidecar must be removed"
+        );
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn remove_rag_sidecars_is_ok_when_absent() {
+        let root = sidecar_temp_dir("rag-sidecars-absent");
+        assert!(remove_rag_sidecars(&root, "docs").is_ok());
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn remove_rag_sidecars_runs_before_yaml_unlink() {
+        let root = sidecar_temp_dir("rag-sidecars-order");
+        let yaml = root.join("docs.yaml");
+        fs::write(&yaml, "rag").unwrap();
+        let mixin = root.join("docs.sbx-mixin.yaml");
+        fs::create_dir_all(&mixin).unwrap();
+        fs::write(mixin.join("blocker"), "x").unwrap();
+
+        let err = remove_rag_sidecars(&root, "docs").unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("Failed to remove the sandbox mixin"),
+            "got: {err}"
+        );
+        assert!(
+            yaml.exists(),
+            "the .yaml must survive a sidecar-removal failure so the delete is retryable"
+        );
+        let _ = fs::remove_dir_all(&root);
+    }
 }

src/config/request_context.rs

@@ -16,8 +16,9 @@ use super::{MessageContentToolCalls, prompts};
 use crate::client::{Model, ModelType, list_models};
 use crate::function::{
     FunctionDeclaration, Functions, ToolCallTracker, ToolResult, memory::MEMORY_FUNCTION_PREFIX,
-    skill::SKILL_FUNCTION_PREFIX, supervisor::SUPERVISOR_FUNCTION_PREFIX,
-    todo::TODO_FUNCTION_PREFIX, user_interaction::USER_FUNCTION_PREFIX,
+    rag_query::RAG_FUNCTION_PREFIX, skill::SKILL_FUNCTION_PREFIX,
+    supervisor::SUPERVISOR_FUNCTION_PREFIX, todo::TODO_FUNCTION_PREFIX,
+    user_interaction::USER_FUNCTION_PREFIX,
 };
 use crate::mcp::{
     MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
@@ -38,6 +39,7 @@ use super::memory::{
 };
 use crate::graph;
 use anyhow::{Context, Error, Result, bail};
+use colored::Colorize;
 use gman::providers::SupportedProvider;
 #[cfg(test)]
 use indexmap::IndexMap;
@@ -141,6 +143,7 @@ pub struct RequestContext {
     pub role: Option<Role>,
     pub session: Option<Session>,
     pub rag: Option<Arc<Rag>>,
+    pub rag_key: Option<RagKey>,
     pub agent: Option<Agent>,
 
     pub last_message: Option<LastMessage>,
@@ -175,6 +178,7 @@ impl RequestContext {
             role: None,
             session: None,
             rag: None,
+            rag_key: None,
             agent: None,
             last_message: None,
             tool_scope: ToolScope::default(),
@@ -228,6 +232,7 @@ impl RequestContext {
             role: None,
             session: None,
             rag: None,
+            rag_key: None,
             agent: None,
             last_message: None,
             tool_scope: ToolScope {
@@ -276,6 +281,7 @@ impl RequestContext {
             role: self.role.clone(),
             session: self.session.clone(),
             rag: self.rag.clone(),
+            rag_key: self.rag_key.clone(),
             agent: self.agent.clone(),
             last_message: self.last_message.clone(),
             tool_scope: self.tool_scope.clone(),
@@ -314,6 +320,7 @@ impl RequestContext {
             role: None,
             session: None,
             rag: None,
+            rag_key: None,
             agent: None,
             last_message: None,
             tool_scope: ToolScope {
@@ -709,6 +716,7 @@ impl RequestContext {
 
     pub fn exit_rag(&mut self) -> Result<()> {
         self.rag.take();
+        self.tool_scope.functions.remove_rag_query_functions();
         Ok(())
     }
 
@@ -728,6 +736,26 @@ impl RequestContext {
         Ok(())
     }
 
+    pub fn on_chat_completion_error(&mut self, app: &AppConfig, input: &Input) {
+        self.last_message = Some(LastMessage::new(input.clone(), String::new()));
+        if input.session(&self.session).is_none() {
+            if let Some(lm) = self.last_message.as_mut() {
+                lm.continuous = false;
+            }
+
+            return;
+        }
+
+        let mut i = input.clone();
+        i.clear_patch();
+        if let Some(session) = i.session_mut(&mut self.session) {
+            let _ = session.add_message(&i, "[Response interrupted due to error]");
+            if !app.dry_run && session.save_session() == Some(true) {
+                let _ = session.flush();
+            }
+        }
+    }
+
     pub fn discontinuous_last_message(&mut self) {
         if let Some(last_message) = self.last_message.as_mut() {
             last_message.continuous = false;
@@ -807,7 +835,12 @@ impl RequestContext {
         let mut role = if let Some(session) = self.session.as_ref() {
             session.to_role()
         } else if let Some(agent) = self.agent.as_ref() {
-            agent.to_role()
+            let mut role = agent.to_role();
+            if role.reasoning_effort().is_none() {
+                role.set_reasoning_effort(app.reasoning_effort.clone());
+            }
+
+            role
         } else if let Some(role) = self.role.as_ref() {
             role.clone()
         } else {
@@ -1086,10 +1119,17 @@ impl RequestContext {
     }
 
     fn concrete_tool_names(&self) -> Vec<String> {
-        let declarations = match &self.agent {
-            Some(agent) => agent.functions().declarations(),
-            None => self.tool_scope.functions.declarations(),
-        };
+        let declarations: Vec<&FunctionDeclaration> = self
+            .tool_scope
+            .functions
+            .declarations()
+            .iter()
+            .chain(
+                self.agent
+                    .iter()
+                    .flat_map(|agent| agent.functions().declarations()),
+            )
+            .collect();
         declarations
             .iter()
             .filter(|v| {
@@ -1099,6 +1139,7 @@ impl RequestContext {
                     && !v.name.starts_with("agent__")
                     && !v.name.starts_with("memory__")
                     && !v.name.starts_with("skill__")
+                    && !v.name.starts_with("rag__")
             })
             .map(|v| v.name.clone())
             .collect()
@@ -1919,7 +1960,8 @@ impl RequestContext {
                             || (!matches!(role.skills_enabled(), Some(false))
                                 && v.name.starts_with(SKILL_FUNCTION_PREFIX))
                             || (self.auto_continue_config().enabled
-                                && v.name.starts_with(TODO_FUNCTION_PREFIX)))
+                                && v.name.starts_with(TODO_FUNCTION_PREFIX))
+                            || v.name.starts_with(RAG_FUNCTION_PREFIX))
                             && !existing.contains(&v.name)
                     })
                     .cloned()
@@ -1949,6 +1991,7 @@ impl RequestContext {
                             || v.name.starts_with(TODO_FUNCTION_PREFIX)
                             || v.name.starts_with(SUPERVISOR_FUNCTION_PREFIX)
                             || v.name.starts_with(MEMORY_FUNCTION_PREFIX)
+                            || v.name.starts_with(RAG_FUNCTION_PREFIX)
                     });
                 }
 
@@ -2400,8 +2443,12 @@ impl RequestContext {
 
                 println!("Skills:");
                 for (name, description, loaded) in entries {
-                    let marker = if loaded { " (loaded)" } else { "" };
-                    println!("  • {name}{marker} — {description}");
+                    let marker = if loaded {
+                        "✓".green().bold().to_string()
+                    } else {
+                        "✗".red().bold().to_string()
+                    };
+                    println!("  {marker} {name} — {description}");
                 }
 
                 Ok(())
@@ -2425,7 +2472,31 @@ impl RequestContext {
                 names.sort_unstable();
                 names.dedup();
 
-                print_asset_names("tools", &names)
+                let active: HashSet<String> = if self.app.config.function_calling_support {
+                    let role = self.extract_role(&self.app.config)?;
+                    match self.select_functions(&role) {
+                        None => HashSet::new(),
+                        Some(functions) => functions.iter().map(|f| f.name.clone()).collect(),
+                    }
+                } else {
+                    HashSet::new()
+                };
+
+                if names.is_empty() {
+                    println!("No tools found.");
+                    return Ok(());
+                }
+
+                println!("Tools:");
+                for name in &names {
+                    let marker = if active.contains(name.as_str()) {
+                        "✓".green().bold().to_string()
+                    } else {
+                        "✗".red().bold().to_string()
+                    };
+                    println!("  {marker} {name}");
+                }
+                Ok(())
             }
             "mcp-servers" => {
                 let mut names: Vec<String> = vec![];
@@ -2442,7 +2513,32 @@ impl RequestContext {
                 names.sort_unstable();
                 names.dedup();
 
-                print_asset_names("MCP servers", &names)
+                if names.is_empty() {
+                    println!("No MCP servers found.");
+                    return Ok(());
+                }
+
+                let enabled: Option<Vec<String>> = if let Some(session) = &self.session {
+                    session.enabled_mcp_servers()
+                } else if let Some(role) = &self.role {
+                    role.enabled_mcp_servers()
+                } else {
+                    self.app.config.enabled_mcp_servers.clone()
+                };
+                let skill_mcps = self.skill_registry.loaded_mcp_servers();
+
+                println!("MCP servers:");
+                for name in &names {
+                    let active = skill_mcps.contains(name.as_str())
+                        || matches!(&enabled, Some(list) if list.iter().any(|s| s.trim() == "all") || self.mcp_list_covers(list, name));
+                    let marker = if active {
+                        "✓".green().bold().to_string()
+                    } else {
+                        "✗".red().bold().to_string()
+                    };
+                    println!("  {marker} {name}");
+                }
+                Ok(())
             }
             _ => bail!(
                 "Unknown kind '{kind}'. Valid kinds: roles, sessions, agents, rags, macros, skills, tools, mcp-servers"
@@ -2468,6 +2564,14 @@ impl RequestContext {
                     match file_ext {
                         Some(file_ext) => {
                             if let Some(name) = name.to_string_lossy().strip_suffix(file_ext) {
+                                // Sidecars are not independently deletable assets.
+                                // Guarded on `kind == "rag"` because this scan is shared
+                                // by all six kinds, and `session`/`macro` also use
+                                // `.yaml`. The helper lives in paths.rs beside
+                                // list_rags() so both filters cannot drift apart.
+                                if kind == "rag" && paths::is_rag_sidecar_name(name) {
+                                    continue;
+                                }
                                 names.push(name.to_string());
                             }
                         }
@@ -2504,6 +2608,13 @@ impl RequestContext {
             match file_ext {
                 Some(ext) => {
                     let path = dir.join(format!("{name}{ext}"));
+                    // Sidecars FIRST. If this fails, the .yaml is still on disk, the
+                    // RAG is still listed, and the user can retry. Unlinking the .yaml
+                    // first would make the deletion unretryable while leaving an
+                    // orphaned mixin whitelisting a host in every sandbox launch.
+                    if kind == "rag" {
+                        paths::remove_rag_sidecars(&dir, &name)?;
+                    }
                     remove_file(&path).with_context(|| {
                         format!("Failed to delete {kind} at '{}'", path.display())
                     })?;
@@ -2687,7 +2798,12 @@ impl RequestContext {
                 }
             }
             "rag_top_k" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
+                let value: usize = value.parse().with_context(|| "Invalid value")?;
+                if value == 0 {
+                    bail!(
+                        "rag_top_k must be >= 1; a top_k of 0 makes every query return no results."
+                    );
+                }
                 if !self.set_rag_top_k(value)? {
                     self.update_app_config(|app| app.rag_top_k = value);
                 }
@@ -3356,6 +3472,12 @@ impl RequestContext {
         if self.should_register_memory_tools() {
             functions.append_memory_functions();
         }
+        if self.rag.is_some()
+            && app.function_calling_support
+            && !self.agent.as_ref().is_some_and(|a| a.is_graph())
+        {
+            functions.append_rag_query_functions();
+        }
 
         let tool_tracker = self.tool_scope.tool_tracker.clone();
         self.tool_scope = ToolScope {
@@ -3638,6 +3760,14 @@ impl RequestContext {
             .then(|| Arc::new(RwLock::new(Supervisor::new(max_concurrent, max_depth))));
 
         self.rag = agent.rag();
+        // Keep `rag_key` in lockstep with `rag`. Agent RAGs are cached under
+        // `RagKey::Agent(<agent name>)` (see `Agent::init`), so mirror that key exactly;
+        // leaving the previous key in place would let `.rebuild rag` invalidate an
+        // unrelated RAG's cache entry, and leaving it `None` would invalidate nothing.
+        self.rag_key = self
+            .rag
+            .is_some()
+            .then(|| RagKey::Agent(agent.name().to_string()));
         self.agent = Some(agent);
         self.supervisor = supervisor;
         self.inbox = None;
@@ -3686,6 +3816,11 @@ impl RequestContext {
             self.pending_agents_guardrail_count = 0;
             self.todo_list = TodoList::default();
             self.rag.take();
+            // Cleared alongside `rag` so the pair never disagrees: an agent RAG is
+            // cached under `RagKey::Agent(<agent name>)`, and leaving that key behind
+            // would outlive the RAG it names. Latent rather than live today only
+            // because `rebuild_rag`/`edit_rag_docs` bail on `rag.is_none()` first.
+            self.rag_key = None;
             self.discontinuous_last_message();
         }
         Ok(())
@@ -3993,10 +4128,11 @@ impl RequestContext {
         }
 
         let app = self.app.config.clone();
+        let vault = self.app.vault.clone();
         let rag_cache = self.rag_cache();
         let working_mode = self.working_mode;
 
-        let rag: Arc<Rag> = match rag {
+        let (rag, rag_key): (Arc<Rag>, Option<RagKey>) = match rag {
             None => {
                 let rag_path = self.rag_file(super::TEMP_RAG_NAME);
                 if rag_path.exists() {
@@ -4004,15 +4140,29 @@ impl RequestContext {
                         format!("Failed to cleanup previous '{}' rag", super::TEMP_RAG_NAME)
                     })?;
                 }
-                Arc::new(Rag::init(&app, super::TEMP_RAG_NAME, &rag_path, &[], abort_signal).await?)
+                (
+                    Arc::new(
+                        Rag::init(
+                            &app,
+                            super::TEMP_RAG_NAME,
+                            &rag_path,
+                            &[],
+                            abort_signal.clone(),
+                            false,
+                        )
+                        .await?,
+                    ),
+                    None,
+                )
             }
             Some(name) => {
                 let rag_path = self.rag_file(name);
                 let key = RagKey::Named(name.to_string());
 
-                rag_cache
-                    .load_with(key, || {
+                let loaded = rag_cache
+                    .load_with(key.clone(), || {
                         let app = app.clone();
+                        let vault = vault.clone();
                         let rag_path = rag_path.clone();
                         let abort_signal = abort_signal.clone();
                         async move {
@@ -4020,16 +4170,41 @@ impl RequestContext {
                                 if working_mode.is_cmd() {
                                     bail!("Unknown RAG '{name}'");
                                 }
-                                Rag::init(&app, name, &rag_path, &[], abort_signal.clone()).await
+                                Rag::init(&app, name, &rag_path, &[], abort_signal.clone(), true)
+                                    .await
                             } else {
-                                Rag::load(&app, name, &rag_path)
+                                Rag::load_async(&app, &vault, name, &rag_path).await
                             }
                         }
                     })
-                    .await?
+                    .await?;
+                (loaded, Some(key))
             }
         };
         self.rag = Some(rag);
+        self.rag_key = rag_key;
+        self.refresh_tool_scope(abort_signal).await?;
+        Ok(())
+    }
+
+    pub async fn attach_rag(&mut self, name: &str, abort_signal: AbortSignal) -> Result<()> {
+        let rag_path = self.rag_file(name);
+        if rag_path.exists() {
+            bail!(
+                "RAG '{name}' already exists at '{}'. \
+                 Use a different name, or delete the existing file first.",
+                rag_path.display()
+            );
+        }
+        let app = self.app.config.as_ref();
+        let vault = self.app.vault.clone();
+        let rag = Rag::attach(app, &vault, name, &rag_path).await?;
+        let rag = Arc::new(rag);
+        let key = RagKey::Named(name.to_string());
+        self.rag_cache().insert(key.clone(), &rag);
+        self.rag = Some(rag);
+        self.rag_key = Some(key);
+        self.refresh_tool_scope(abort_signal).await?;
         Ok(())
     }
 
@@ -4039,6 +4214,12 @@ impl RequestContext {
             None => bail!("No RAG"),
         };
 
+        if rag.is_attached() {
+            bail!(
+                "Cannot edit documents on an attached RAG; Coyote does not own its source documents."
+            );
+        }
+
         let document_paths = rag.document_paths();
         let temp_file = temp_file(&format!("-rag-{}", rag.name()), ".txt");
         tokio::fs::write(&temp_file, &document_paths.join("\n"))
@@ -4064,15 +4245,18 @@ impl RequestContext {
             bail!("No changes")
         }
 
-        let key = if self.agent.is_some() {
-            RagKey::Agent(rag.name().to_string())
-        } else {
-            RagKey::Named(rag.name().to_string())
-        };
-        self.rag_cache().invalidate(&key);
+        if let Some(key) = self.rag_key.clone() {
+            self.rag_cache().invalidate(&key);
+        }
 
-        rag.refresh_document_paths(&new_document_paths, false, &self.app.config, abort_signal)
-            .await?;
+        rag.refresh_document_paths(
+            &new_document_paths,
+            false,
+            false,
+            &self.app.config,
+            abort_signal,
+        )
+        .await?;
         self.rag = Some(Arc::new(rag));
         Ok(())
     }
@@ -4083,15 +4267,25 @@ impl RequestContext {
             None => bail!("No RAG"),
         };
 
-        let key = if self.agent.is_some() {
-            RagKey::Agent(rag.name().to_string())
-        } else {
-            RagKey::Named(rag.name().to_string())
-        };
-        self.rag_cache().invalidate(&key);
+        if rag.is_attached() {
+            bail!(
+                "Cannot rebuild an attached RAG; Coyote does not own its source documents. \
+                 Re-index from the system that originally created '{}'.",
+                rag.name()
+            );
+        }
+
+        if let Some(key) = self.rag_key.clone() {
+            self.rag_cache().invalidate(&key);
+        }
 
         let document_paths = rag.document_paths().to_vec();
-        rag.refresh_document_paths(&document_paths, true, &self.app.config, abort_signal)
+        println!(
+            "Rebuilding re-embeds every document ({} files). \
+             This will call the embedding API and may take a while.",
+            rag.file_count()
+        );
+        rag.refresh_document_paths(&document_paths, true, true, &self.app.config, abort_signal)
             .await?;
         self.rag = Some(Arc::new(rag));
         Ok(())
@@ -4114,6 +4308,7 @@ mod tests {
     use super::super::mcp_factory::McpFactory;
     use super::*;
     use crate::config::AppState;
+    use crate::config::agent::AgentConfig;
     use crate::function::{ToolCall, skill};
     use crate::mcp::{McpServer, McpServersConfig, McpTransportType};
     use crate::utils;
@@ -4297,6 +4492,42 @@ mod tests {
         assert_eq!(extracted.name(), "");
     }
 
+    #[test]
+    fn extract_role_agent_without_reasoning_effort_inherits_app_config() {
+        let mut ctx = create_test_ctx();
+        ctx.agent = Some(Agent::test_new(AgentConfig {
+            name: "test-agent".to_string(),
+            reasoning_effort: None,
+            ..AgentConfig::default()
+        }));
+        let app = AppConfig {
+            reasoning_effort: Some("max".to_string()),
+            ..AppConfig::default()
+        };
+
+        let extracted = ctx.extract_role(&app).unwrap();
+
+        assert_eq!(extracted.reasoning_effort(), Some("max".to_string()));
+    }
+
+    #[test]
+    fn extract_role_agent_with_explicit_reasoning_effort_takes_priority_over_app_config() {
+        let mut ctx = create_test_ctx();
+        ctx.agent = Some(Agent::test_new(AgentConfig {
+            name: "test-agent".to_string(),
+            reasoning_effort: Some("low".to_string()),
+            ..AgentConfig::default()
+        }));
+        let app = AppConfig {
+            reasoning_effort: Some("max".to_string()),
+            ..AppConfig::default()
+        };
+
+        let extracted = ctx.extract_role(&app).unwrap();
+
+        assert_eq!(extracted.reasoning_effort(), Some("low".to_string()));
+    }
+
     #[test]
     fn should_inject_skill_instructions_requires_function_calling() {
         let app = AppConfig {
@@ -4460,6 +4691,44 @@ mod tests {
 
         assert!(ctx.agent.is_none());
         assert!(ctx.rag.is_none());
+        assert_eq!(ctx.rag_key, None);
+    }
+
+    #[test]
+    #[serial]
+    fn use_agent_does_not_carry_stale_rag_key() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("config.yaml"),
+            format!("name: {agent_name}\ninstructions: hi\n"),
+        )
+        .unwrap();
+
+        ctx.rag_key = Some(RagKey::Named("docs".to_string()));
+
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(async {
+                ctx.use_agent(&app, &agent_name, None, utils::create_abort_signal())
+                    .await
+                    .unwrap();
+            });
+
+        assert!(ctx.rag.is_none());
+        assert_eq!(ctx.rag_key, None);
     }
 
     #[test]
@@ -5424,6 +5693,54 @@ mod tests {
         assert!(lm.continuous);
     }
 
+    #[test]
+    fn on_chat_completion_error_without_session_sets_last_message_discontinuous() {
+        let mut ctx = create_test_ctx();
+        let app = Arc::clone(&ctx.app.config);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
+
+        ctx.on_chat_completion_error(app.as_ref(), &input);
+
+        let lm = ctx.last_message.as_ref().unwrap();
+        assert_eq!(lm.output, "");
+        assert!(!lm.continuous, "no session means recovery is not possible");
+    }
+
+    #[test]
+    fn on_chat_completion_error_with_session_sets_last_message_continuous() {
+        let mut ctx = create_test_ctx();
+        ctx.app = Arc::new(AppState {
+            config: Arc::new(AppConfig {
+                dry_run: true,
+                ..(*ctx.app.config).clone()
+            }),
+            ..(*ctx.app).clone()
+        });
+        ctx.session = Some(Session::default());
+        let app = Arc::clone(&ctx.app.config);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
+
+        ctx.on_chat_completion_error(app.as_ref(), &input);
+
+        let lm = ctx.last_message.as_ref().unwrap();
+        assert_eq!(lm.output, "");
+        assert!(lm.continuous, "session present means .recover is available");
+    }
+
+    #[test]
+    fn on_chat_completion_error_with_session_checkpoints_session_messages() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        assert!(ctx.session.as_ref().unwrap().is_empty());
+        let app = Arc::clone(&ctx.app.config);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
+        ctx.on_chat_completion_error(app.as_ref(), &input);
+        assert!(
+            !ctx.session.as_ref().unwrap().is_empty(),
+            "session should have the interrupted turn checkpointed"
+        );
+    }
+
     #[test]
     fn after_chat_completion_sweeps_auto_unload_skills_at_turn_end() {
         let mut ctx = create_test_ctx();
@@ -5799,6 +6116,28 @@ mod tests {
         assert!(paths::list_rags().is_empty());
     }
 
+    #[test]
+    #[serial]
+    fn list_rags_skips_sbx_mixin_sidecars() {
+        let _guard = TestConfigDirGuard::new();
+        let rags_dir = paths::rags_dir();
+        create_dir_all(&rags_dir).unwrap();
+        write(rags_dir.join("docs.yaml"), "embedding_model: test").unwrap();
+        write(rags_dir.join("docs.sbx-mixin.yaml"), "kind: mixin").unwrap();
+        write(rags_dir.join("v2.docs.yaml"), "embedding_model: test").unwrap();
+
+        let names = paths::list_rags();
+        assert!(names.contains(&"docs".to_string()));
+        assert!(
+            names.contains(&"v2.docs".to_string()),
+            "a dotted RAG name must still be listed: {names:?}"
+        );
+        assert!(
+            !names.contains(&"docs.sbx-mixin".to_string()),
+            "the sandbox mixin sidecar must not appear as a RAG: {names:?}"
+        );
+    }
+
     #[test]
     #[serial]
     fn use_agent_errors_when_already_in_session() {

src/config/session.rs

@@ -699,6 +699,19 @@ impl Session {
         Ok(())
     }
 
+    pub fn flush(&mut self) -> Result<()> {
+        if !self.dirty {
+            return Ok(());
+        }
+
+        if let Some(path) = self.path.clone() {
+            let name = self.name.clone();
+            self.save(&name, Path::new(&path), false)?;
+        }
+
+        Ok(())
+    }
+
     pub fn guard_empty(&self) -> Result<()> {
         if !self.is_empty() {
             bail!(

src/function/mod.rs

@@ -1,4 +1,5 @@
 pub(crate) mod memory;
+pub(crate) mod rag_query;
 pub(crate) mod skill;
 pub(crate) mod supervisor;
 pub(crate) mod todo;
@@ -19,9 +20,11 @@ use crate::mcp::{
 };
 use crate::parsers::{bash, python, typescript};
 use anyhow::{Context, Result, anyhow, bail};
+use futures_util::future;
 use indexmap::IndexMap;
 use indoc::formatdoc;
 use memory::MEMORY_FUNCTION_PREFIX;
+use rag_query::RAG_FUNCTION_PREFIX;
 use rust_embed::Embed;
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
@@ -146,7 +149,9 @@ pub async fn eval_tool_calls(
     if calls.is_empty() {
         bail!("The request was aborted because an infinite loop of function calls was detected.")
     }
-    for call in calls {
+    let mut to_execute: Vec<(usize, ToolCall)> = Vec::with_capacity(calls.len());
+    let mut indexed_results: Vec<(usize, ToolResult)> = vec![];
+    for (idx, call) in calls.into_iter().enumerate() {
         if let Some(msg) = ctx.tool_scope.tool_tracker.check_loop(&call.clone()) {
             let dup_msg = format!("{{\"tool_call_loop_alert\":{}}}", msg.trim());
             println!(
@@ -155,14 +160,43 @@ pub async fn eval_tool_calls(
                     format!("{}: ⚠️ Tool-call loop detected! ⚠️", call.name).as_str()
                 )
             );
-            let val = json!(dup_msg);
-            output.push(ToolResult::new(call, val));
-            continue;
+            indexed_results.push((idx, ToolResult::new(call, json!(dup_msg))));
+        } else {
+            to_execute.push((idx, call));
         }
-        let result = call.eval(ctx).await?;
-        output.push(ToolResult::new(call, normalize_tool_result(result)));
     }
 
+    let (mcp_calls, sequential_calls): (Vec<_>, Vec<_>) =
+        to_execute.into_iter().partition(|(_, call)| {
+            call.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                || call.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                || call
+                    .name
+                    .starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+        });
+
+    if !mcp_calls.is_empty() {
+        let ctx_ref: &RequestContext = ctx;
+        let futs: Vec<_> = mcp_calls
+            .into_iter()
+            .map(|(idx, call)| async move {
+                let result = call.eval_mcp(ctx_ref).await;
+                (idx, call, result)
+            })
+            .collect();
+        for (idx, call, result) in future::join_all(futs).await {
+            indexed_results.push((idx, ToolResult::new(call, normalize_tool_result(result?))));
+        }
+    }
+
+    for (idx, call) in sequential_calls {
+        let result = call.eval(ctx).await?;
+        indexed_results.push((idx, ToolResult::new(call, normalize_tool_result(result))));
+    }
+
+    indexed_results.sort_unstable_by_key(|(idx, _)| *idx);
+    output = indexed_results.into_iter().map(|(_, r)| r).collect();
+
     if !output.is_empty() {
         let (has_escalations, summary) = if ctx.current_depth == 0
             && let Some(queue) = ctx.root_escalation_queue()
@@ -463,6 +497,16 @@ impl Functions {
             .extend(user_interaction::user_interaction_function_declarations());
     }
 
+    pub fn append_rag_query_functions(&mut self) {
+        self.declarations
+            .extend(rag_query::rag_query_function_declarations());
+    }
+
+    pub fn remove_rag_query_functions(&mut self) {
+        self.declarations
+            .retain(|f| !f.name.starts_with(RAG_FUNCTION_PREFIX));
+    }
+
     pub fn append_mcp_meta_functions(&mut self, mcp_servers: Vec<String>) {
         let mut invoke_function_properties = IndexMap::new();
         invoke_function_properties.insert(
@@ -1065,6 +1109,62 @@ impl ToolCall {
         self
     }
 
+    fn parse_arguments(&self) -> Result<Value> {
+        if self.arguments.is_object() {
+            Ok(self.arguments.clone())
+        } else if let Some(arguments) = self.arguments.as_str() {
+            serde_json::from_str(arguments).map_err(|_| {
+                anyhow!(
+                    "The call '{}' has invalid arguments: {arguments}",
+                    self.name
+                )
+            })
+        } else {
+            bail!(
+                "The call '{}' has invalid arguments: {}",
+                self.name,
+                self.arguments
+            )
+        }
+    }
+
+    async fn eval_mcp(&self, ctx: &RequestContext) -> Result<Value> {
+        let json_data = self.parse_arguments()?;
+        let cmd_name = self.name.as_str();
+        if *IS_STDOUT_TERMINAL && ctx.current_depth == 0 && !HEADLESS.load(Ordering::SeqCst) {
+            println!(
+                "{}",
+                format_call_log(cmd_name, &[json_data.to_string()], &json_data)
+            );
+        }
+        let result = if cmd_name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX) {
+            Self::search_mcp_tools(ctx, cmd_name, &json_data)
+                .await
+                .unwrap_or_else(|e| {
+                    let error_msg = format!("MCP search failed: {e}");
+                    eprintln!("{}", muted_warning_text(&format!("⚠️ {error_msg} ⚠️")));
+                    json!({"tool_call_error": error_msg})
+                })
+        } else if cmd_name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX) {
+            Self::describe_mcp_tool(ctx, cmd_name, json_data.clone())
+                .await
+                .unwrap_or_else(|e| {
+                    let error_msg = format!("MCP describe failed: {e}");
+                    eprintln!("{}", muted_warning_text(&format!("⚠️ {error_msg} ⚠️")));
+                    json!({"tool_call_error": error_msg})
+                })
+        } else {
+            Self::invoke_mcp_tool(ctx, cmd_name, &json_data)
+                .await
+                .unwrap_or_else(|e| {
+                    let error_msg = format!("MCP tool invocation failed: {e}");
+                    eprintln!("{}", muted_warning_text(&format!("⚠️ {error_msg} ⚠️")));
+                    json!({"tool_call_error": error_msg})
+                })
+        };
+        Ok(result)
+    }
+
     pub async fn eval(&self, ctx: &mut RequestContext) -> Result<Value> {
         let agent = ctx.agent.clone();
         let functions = ctx.tool_scope.functions.clone();
@@ -1164,6 +1264,15 @@ impl ToolCall {
                         json!({"tool_call_error": error_msg})
                     })
             }
+            _ if cmd_name.starts_with(RAG_FUNCTION_PREFIX) => {
+                rag_query::handle_rag_tool(ctx, &cmd_name, &json_data)
+                    .await
+                    .unwrap_or_else(|e| {
+                        let error_msg = format!("RAG query failed: {e}");
+                        eprintln!("{}", muted_warning_text(&format!("⚠️ {error_msg} ⚠️")));
+                        json!({"tool_call_error": error_msg})
+                    })
+            }
             _ => match run_llm_function(cmd_name, cmd_args, envs, agent_name) {
                 Ok(Some(contents)) => serde_json::from_str(&contents)
                     .ok()
@@ -2018,4 +2127,28 @@ mod tests {
         assert!(result.text.is_none());
         assert!(result.thinking.is_empty());
     }
+
+    #[test]
+    fn parse_arguments_passes_through_object() {
+        let tc = call_with_args("t", json!({"x": 1, "y": "hello"}));
+        assert_eq!(tc.parse_arguments().unwrap(), json!({"x": 1, "y": "hello"}));
+    }
+
+    #[test]
+    fn parse_arguments_deserializes_json_string() {
+        let tc = call_with_args("t", json!(r#"{"a": true}"#));
+        assert_eq!(tc.parse_arguments().unwrap(), json!({"a": true}));
+    }
+
+    #[test]
+    fn parse_arguments_returns_err_for_invalid_json_string() {
+        let tc = call_with_args("t", json!("not json {"));
+        assert!(tc.parse_arguments().is_err());
+    }
+
+    #[test]
+    fn parse_arguments_returns_err_for_non_object_non_string() {
+        let tc = call_with_args("t", json!(42));
+        assert!(tc.parse_arguments().is_err());
+    }
 }

src/function/rag_query.rs

@@ -0,0 +1,101 @@
+use super::{FunctionDeclaration, JsonSchema};
+use crate::config::RequestContext;
+
+use anyhow::{Result, anyhow};
+use indexmap::IndexMap;
+use serde_json::{Value, json};
+
+pub const RAG_FUNCTION_PREFIX: &str = "rag__";
+
+pub fn rag_query_function_declarations() -> Vec<FunctionDeclaration> {
+    vec![FunctionDeclaration {
+        name: format!("{RAG_FUNCTION_PREFIX}query"),
+        description: "Search the RAG knowledge base attached to this session and return \
+                      the most relevant text chunks with their source paths. The relevant \
+                      context has already been injected into the prompt up-front; use this \
+                      tool to pull additional context on-demand when the initial retrieval \
+                      does not fully answer the question. Prefer specific, keyword-rich queries."
+            .to_string(),
+        parameters: JsonSchema {
+            type_value: Some("object".to_string()),
+            properties: Some(IndexMap::from([
+                (
+                    "query".to_string(),
+                    JsonSchema {
+                        type_value: Some("string".to_string()),
+                        description: Some(
+                            "Natural language search query used to retrieve relevant chunks."
+                                .into(),
+                        ),
+                        ..Default::default()
+                    },
+                ),
+                (
+                    "top_k".to_string(),
+                    JsonSchema {
+                        type_value: Some("integer".to_string()),
+                        description: Some(
+                            "Maximum number of chunks to return. Defaults to the RAG's \
+                             configured top_k when omitted."
+                                .into(),
+                        ),
+                        ..Default::default()
+                    },
+                ),
+            ])),
+            required: Some(vec!["query".to_string()]),
+            ..Default::default()
+        },
+        agent: false,
+    }]
+}
+
+pub async fn handle_rag_tool(
+    ctx: &mut RequestContext,
+    cmd_name: &str,
+    args: &Value,
+) -> Result<Value> {
+    let action = cmd_name
+        .strip_prefix(RAG_FUNCTION_PREFIX)
+        .unwrap_or(cmd_name);
+
+    match action {
+        "query" => handle_query(ctx, args).await,
+        _ => Err(anyhow!("Unknown RAG action: {action}")),
+    }
+}
+
+async fn handle_query(ctx: &RequestContext, args: &Value) -> Result<Value> {
+    let rag = ctx
+        .rag
+        .clone()
+        .ok_or_else(|| anyhow!("No RAG is attached to this session"))?;
+
+    let query = args
+        .get("query")
+        .and_then(Value::as_str)
+        .ok_or_else(|| anyhow!("'query' is required"))?;
+
+    let top_k = args
+        .get("top_k")
+        .and_then(Value::as_u64)
+        .map(|v| v as usize)
+        .unwrap_or_else(|| rag.configured_top_k());
+
+    let rerank_model = rag.configured_reranker().map(|s| s.to_string());
+
+    let chunks = rag
+        .search_chunks(query, top_k, rerank_model.as_deref())
+        .await?;
+
+    let chunks_json: Vec<Value> = chunks
+        .into_iter()
+        .map(|(text, source)| json!({ "text": text, "source": source }))
+        .collect();
+
+    Ok(json!({
+        "rag_name": rag.name(),
+        "count": chunks_json.len(),
+        "chunks": chunks_json,
+    }))
+}

src/graph/structured.rs

@@ -88,11 +88,21 @@ async fn run_one_shot(prompt: &str, ctx: &mut RequestContext) -> Result<String>
 }
 
 fn try_parse_json(raw: &str) -> Option<Value> {
-    let cleaned = strip_code_fences(raw.trim());
-
+    let cleaned = strip_code_fences(strip_thinking_blocks(raw.trim()));
     serde_json::from_str(cleaned).ok()
 }
 
+fn strip_thinking_blocks(s: &str) -> &str {
+    let mut s = s.trim_start();
+    while s.starts_with("<think>") {
+        match s.find("</think>") {
+            Some(end) => s = s[end + "</think>".len()..].trim_start(),
+            None => break,
+        }
+    }
+    s
+}
+
 fn strip_code_fences(s: &str) -> &str {
     let after_open = s
         .strip_prefix("```json")
@@ -148,6 +158,38 @@ mod tests {
         assert_eq!(v, json!({"x": true}));
     }
 
+    #[test]
+    fn try_parse_json_strips_thinking_blocks() {
+        let raw = "<think>\nsome reasoning\n</think>\n{\"a\": 1}";
+
+        let v = try_parse_json(raw).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_strips_empty_thinking_block() {
+        let raw = "<think>\n\n</think>\n{\"a\": 1}";
+
+        let v = try_parse_json(raw).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_strips_multiple_thinking_blocks() {
+        let raw = "<think>first</think>\n<think>second</think>\n{\"a\": 1}";
+
+        let v = try_parse_json(raw).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_unclosed_think_tag_returns_none() {
+        assert!(try_parse_json("<think>unclosed {\"a\": 1}").is_none());
+    }
+
     #[test]
     fn try_parse_json_returns_none_on_prose() {
         assert!(try_parse_json("Here is the result: it's good").is_none());

src/graph/types.rs

@@ -367,6 +367,13 @@ pub struct RagNode {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub graph_hops: Option<usize>,
 
+    /// Storage driver for this node's knowledge base ("yaml", "duckdb"). `None`
+    /// means "yaml". Only honored when the knowledge base is first built;
+    /// changing it afterwards has no effect until the RAG is deleted and
+    /// re-initialized.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub driver: Option<String>,
+
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub state_updates: Option<HashMap<String, String>>,
 
@@ -1152,4 +1159,100 @@ nodes:
         assert!(triage.next.as_ref().unwrap().is_fan_out());
         assert_eq!(triage.next.as_ref().unwrap().as_slice().len(), 2);
     }
+
+    fn rag_node_of(graph: &Graph, id: &str) -> RagNode {
+        match &graph.get_node(id).unwrap().node_type {
+            NodeType::Rag(r) => r.clone(),
+            other => panic!("expected a rag node, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn rag_node_deserializes_an_explicit_driver() {
+        let yaml = r#"
+name: kb
+start: research
+nodes:
+  research:
+    type: rag
+    documents: ["./docs"]
+    driver: duckdb
+    next: done
+  done:
+    type: end
+    output: ok
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(
+            rag_node_of(&graph, "research").driver.as_deref(),
+            Some("duckdb")
+        );
+    }
+
+    /// Workflows written before drivers existed must keep parsing, and must keep
+    /// asking for nothing, so `RagInitConfig` resolves them to the yaml default.
+    #[test]
+    fn rag_node_without_a_driver_stays_unset() {
+        let yaml = r#"
+name: kb
+start: research
+nodes:
+  research:
+    type: rag
+    documents: ["./docs"]
+    next: done
+  done:
+    type: end
+    output: ok
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(rag_node_of(&graph, "research").driver, None);
+    }
+
+    #[test]
+    fn rag_node_driver_survives_a_serialize_round_trip() {
+        let yaml = r#"
+name: kb
+start: research
+nodes:
+  research:
+    type: rag
+    documents: ["./docs"]
+    driver: duckdb
+    next: done
+  done:
+    type: end
+    output: ok
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        let reparsed: Graph =
+            serde_yaml::from_str(&serde_yaml::to_string(&graph).unwrap()).unwrap();
+
+        assert_eq!(
+            rag_node_of(&reparsed, "research").driver.as_deref(),
+            Some("duckdb")
+        );
+    }
+
+    /// `skip_serializing_if` must keep `driver:` out of graphs that never set it.
+    #[test]
+    fn rag_node_without_a_driver_omits_the_key_when_serialized() {
+        let yaml = r#"
+name: kb
+start: research
+nodes:
+  research:
+    type: rag
+    documents: ["./docs"]
+    next: done
+  done:
+    type: end
+    output: ok
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert!(!serde_yaml::to_string(&graph).unwrap().contains("driver"));
+    }
 }

src/graph/validator.rs

@@ -2,6 +2,7 @@ use super::state::template_root_keys;
 use super::types::{Graph, Node, NodeType};
 use crate::client::{Model, ModelType};
 use crate::config::{Agent, AppConfig, paths};
+use crate::rag::{GraphRagConfig, RagData};
 use anyhow::{Result, bail};
 use std::collections::{BTreeMap, HashSet, VecDeque};
 use std::path::PathBuf;
@@ -96,6 +97,51 @@ pub struct GraphValidator {
     skill_exists: fn(&str) -> bool,
 }
 
+/// A minimal `RagData` whose only interesting field is `driver`. The numeric
+/// arguments are the smallest values that satisfy `validate()`'s unrelated
+/// floors (top_k >= 1, and chunk_size >= 1 with chunk_overlap < chunk_size for
+/// a non-attached RAG). `RagData::new` sets `attached: false`, which is the
+/// correct shape here: a graph rag node always builds its own local knowledge
+/// base from `documents` and can never be attached.
+fn rag_driver_probe(driver: &str) -> RagData {
+    let mut data = RagData::new(
+        String::new(),
+        1,
+        0,
+        None,
+        1,
+        None,
+        GraphRagConfig::default(),
+    );
+    data.driver = driver.to_string();
+    data
+}
+
+/// `Some(message)` when `driver` is one that `RagData::validate()` would reject.
+///
+/// The set of valid drivers is defined in exactly one place, `RagData::validate()`,
+/// so this asks that function rather than restating the list here.
+///
+/// Fails open on purpose: the first probe below uses the default driver, which is
+/// valid by definition. If even that one is rejected, `validate()` has grown a
+/// precondition the probe fixture no longer satisfies, and every verdict from here
+/// would be a false positive that rejects working graphs. In that case we decline
+/// to judge and leave enforcement to RAG construction. The
+/// `rag_driver_probe_fixture_is_accepted` test turns that silent degradation into a
+/// loud failure. Both `validate()` calls are load-bearing; neither is redundant.
+pub(crate) fn rag_driver_error(driver: &str) -> Option<String> {
+    if rag_driver_probe(&RagData::default().driver)
+        .validate()
+        .is_err()
+    {
+        return None;
+    }
+    rag_driver_probe(driver)
+        .validate()
+        .err()
+        .map(|err| err.to_string())
+}
+
 impl GraphValidator {
     pub fn new(base_dir: impl Into<PathBuf>) -> Self {
         Self {
@@ -154,6 +200,11 @@ impl GraphValidator {
                          not be written to state",
                     ));
                 }
+                if let Some(driver) = &r.driver
+                    && let Some(message) = rag_driver_error(driver)
+                {
+                    result.error(ValidationError::with_node(node_id, message));
+                }
             }
         }
     }
@@ -1031,6 +1082,7 @@ mod tests {
                 extractor_model: None,
                 extractor_prompt: None,
                 graph_hops: None,
+                driver: None,
                 state_updates,
                 timeout: None,
             }),
@@ -1385,6 +1437,55 @@ mod tests {
         );
     }
 
+    /// Guards the fail-open branch in `rag_driver_error`. If this fails,
+    /// `RagData::validate()` grew a precondition the probe fixture no longer
+    /// satisfies and rag-node driver validation has silently switched itself off.
+    /// Repair the fixture in `rag_driver_probe`; do not delete this test.
+    #[test]
+    fn rag_driver_probe_fixture_is_accepted() {
+        let default_driver = RagData::default().driver;
+        assert!(
+            rag_driver_probe(&default_driver).validate().is_ok(),
+            "probe fixture rejected for the default driver '{default_driver}'"
+        );
+    }
+
+    #[test]
+    fn rag_driver_error_defers_to_ragdata_validate() {
+        assert_eq!(rag_driver_error("yaml"), None);
+        assert_eq!(rag_driver_error("duckdb"), None);
+
+        let message = rag_driver_error("duckdbb").expect("unknown driver must be rejected");
+        assert!(message.contains("duckdbb"), "got: {message}");
+    }
+
+    #[test]
+    fn rag_node_with_unknown_driver_errors_naming_the_node() {
+        let mut node = rag_node("kb", &["./docs"], true);
+        if let NodeType::Rag(ref mut r) = node.node_type {
+            r.driver = Some("postgres".into());
+        }
+        let graph = graph_with(vec![("kb", node), ("end", end_node("end"))], "kb");
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        let err = result.into_result().unwrap_err().to_string();
+        assert!(err.contains("[kb]"), "must name the node: {err}");
+        assert!(err.contains("postgres"), "must name the driver: {err}");
+    }
+
+    #[test]
+    fn rag_node_with_duckdb_driver_produces_no_findings() {
+        let mut node = rag_node("kb", &["./docs"], true);
+        if let NodeType::Rag(ref mut r) = node.node_type {
+            r.driver = Some("duckdb".into());
+        }
+        let graph = graph_with(vec![("kb", node), ("end", end_node("end"))], "kb");
+
+        assert!(validator().validate(&graph).is_valid());
+    }
+
     fn agent_node(id: &str, agent: &str, next: Option<&str>) -> Node {
         Node {
             id: id.into(),

src/main.rs

@@ -196,6 +196,18 @@ async fn main() -> Result<()> {
         return Ok(());
     }
 
+    let mcp_action =
+        cli.mcp_list || cli.mcp_get.is_some() || cli.mcp_remove.is_some() || cli.mcp_add.is_some();
+    if mcp_action {
+        let cfg = Config::load_with_interpolation(true).await?;
+        let app_config = AppConfig::from_config(cfg)?;
+        let vault = Vault::init(&app_config)?;
+
+        mcp::manage::handle(&cli, &vault)?;
+
+        return Ok(());
+    }
+
     if vault_flags {
         let cfg = Config::load_with_interpolation(true).await?;
         let app_config = AppConfig::from_config(cfg)?;

src/mcp/manage.rs

@@ -0,0 +1,443 @@
+use crate::cli::{Cli, McpScopeArg, McpTransportArg};
+use crate::config::{ensure_parent_exists, paths};
+use crate::mcp::{JsonField, McpOAuthConfig, McpServer, McpServersConfig, McpTransportType};
+use crate::vault::{SECRET_RE, Vault};
+use anyhow::{Context, Result, anyhow, bail};
+use indexmap::{IndexMap, IndexSet};
+use inquire::Confirm;
+use std::collections::HashSet;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+impl From<McpTransportArg> for McpTransportType {
+    fn from(value: McpTransportArg) -> Self {
+        match value {
+            McpTransportArg::Stdio => McpTransportType::Stdio,
+            McpTransportArg::Http => McpTransportType::Http,
+            McpTransportArg::Sse => McpTransportType::Sse,
+        }
+    }
+}
+
+pub fn handle(cli: &Cli, vault: &Vault) -> Result<()> {
+    if cli.mcp_list {
+        return handle_list(cli.scope);
+    }
+    if let Some(name) = &cli.mcp_get {
+        return handle_get(name, cli.scope);
+    }
+    if let Some(name) = &cli.mcp_remove {
+        return handle_remove(name, cli.scope, cli.mcp_force);
+    }
+    if let Some(name) = &cli.mcp_add {
+        return handle_add(cli, name, vault);
+    }
+
+    Ok(())
+}
+
+fn handle_list(scope: Option<McpScopeArg>) -> Result<()> {
+    let show_user = scope != Some(McpScopeArg::Workspace);
+    let show_workspace = scope != Some(McpScopeArg::User);
+
+    if show_user {
+        let user_path = paths::mcp_config_file();
+        let user_cfg = load_config_raw(&user_path)?;
+        println!("User ({})", user_path.display());
+        print_server_list(&user_cfg);
+    }
+
+    if show_workspace {
+        match paths::workspace_mcp_config_file() {
+            Some(ws_path) => {
+                let ws_cfg = load_config_raw(&ws_path)?;
+                if show_user {
+                    println!();
+                }
+                println!("Workspace ({})", ws_path.display());
+                print_server_list(&ws_cfg);
+            }
+            None if scope == Some(McpScopeArg::Workspace) => {
+                println!("Workspace: no mcp.json found in current directory");
+            }
+            None => {}
+        }
+    }
+
+    Ok(())
+}
+
+fn print_server_list(cfg: &McpServersConfig) {
+    if cfg.mcp_servers.is_empty() {
+        println!("  (none)");
+        return;
+    }
+    let name_width = cfg.mcp_servers.keys().map(String::len).max().unwrap_or(0);
+    for (name, spec) in &cfg.mcp_servers {
+        let transport = match spec.transport_type {
+            McpTransportType::Stdio => "stdio",
+            McpTransportType::Http => "http",
+            McpTransportType::Sse => "sse",
+        };
+        let target = spec.url.clone().unwrap_or_else(|| {
+            let cmd = spec.command.clone().unwrap_or_default();
+            let args = spec.args.as_ref().map(|a| a.join(" ")).unwrap_or_default();
+            if args.is_empty() {
+                cmd
+            } else {
+                format!("{cmd} {args}")
+            }
+        });
+        println!(
+            "  {name:<name_width$}  {transport:<5}  {target}",
+            name_width = name_width
+        );
+    }
+}
+
+fn handle_get(name: &str, scope: Option<McpScopeArg>) -> Result<()> {
+    let (path, cfg) = load_for_scope_or_search(name, scope)?;
+    let spec = cfg
+        .mcp_servers
+        .get(name)
+        .ok_or_else(|| anyhow!("MCP server '{name}' not found"))?;
+    let pretty =
+        serde_json::to_string_pretty(spec).context("failed to serialize MCP server config")?;
+    println!("# {}", path.display());
+    println!("{pretty}");
+
+    Ok(())
+}
+
+fn handle_remove(name: &str, scope: Option<McpScopeArg>, force: bool) -> Result<()> {
+    let (path, mut cfg) = load_for_scope_or_search(name, scope)?;
+    if !force {
+        let ok = Confirm::new(&format!(
+            "Remove MCP server '{name}' from {}?",
+            path.display()
+        ))
+        .with_default(false)
+        .prompt()?;
+
+        if !ok {
+            println!("Aborted.");
+            return Ok(());
+        }
+    }
+
+    cfg.mcp_servers.shift_remove(name);
+    save_config(&path, &cfg)?;
+    println!("✓ Removed MCP server '{name}' from {}", path.display());
+
+    Ok(())
+}
+
+fn handle_add(cli: &Cli, name: &str, vault: &Vault) -> Result<()> {
+    validate_name(name)?;
+    let server = build_server(cli)?;
+    server.validate(name)?;
+
+    let scope = cli.scope.unwrap_or_default();
+    let path = write_path_for_scope(scope);
+    let mut cfg = load_config_raw(&path)?;
+
+    if cfg.mcp_servers.contains_key(name) && !cli.mcp_force {
+        let ok = Confirm::new(&format!(
+            "MCP server '{name}' already exists in {}. Overwrite?",
+            path.display()
+        ))
+        .with_default(false)
+        .prompt()?;
+        if !ok {
+            println!("Aborted. Use --mcp-force to overwrite without prompting.");
+            return Ok(());
+        }
+    }
+
+    provision_secrets(cli, vault)?;
+
+    cfg.mcp_servers.insert(name.to_string(), server);
+    save_config(&path, &cfg)?;
+    println!("✓ Added MCP server '{name}' to {}", path.display());
+
+    Ok(())
+}
+
+fn validate_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        bail!("MCP server name cannot be empty");
+    }
+
+    if !name
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
+    {
+        bail!("Invalid MCP server name '{name}': only letters, digits, '-', and '_' are allowed");
+    }
+
+    Ok(())
+}
+
+fn build_server(cli: &Cli) -> Result<McpServer> {
+    let has_command = !cli.mcp_command.is_empty();
+    let has_url = cli.url.is_some();
+
+    let transport = cli
+        .transport
+        .map(McpTransportType::from)
+        .unwrap_or_else(|| {
+            if has_command {
+                McpTransportType::Stdio
+            } else {
+                McpTransportType::Http
+            }
+        });
+
+    match transport {
+        McpTransportType::Stdio => build_stdio(cli, has_url),
+        McpTransportType::Http | McpTransportType::Sse => build_remote(cli, transport, has_command),
+    }
+}
+
+fn build_stdio(cli: &Cli, has_url: bool) -> Result<McpServer> {
+    if cli.mcp_command.is_empty() {
+        bail!(
+            "stdio MCP server requires a command. Pass it after `--`, e.g. \
+             `--mcp-add NAME -- npx some-server --flag`"
+        );
+    }
+    if has_url {
+        bail!("stdio MCP server does not accept --url");
+    }
+    if !cli.header.is_empty() {
+        bail!("stdio MCP server does not accept --header");
+    }
+    if cli.client_id.is_some()
+        || cli.client_secret.is_some()
+        || cli.callback_port.is_some()
+        || cli.redirect_host.is_some()
+    {
+        bail!("stdio MCP server does not accept OAuth flags");
+    }
+
+    let (cmd, args) = cli.mcp_command.split_first().unwrap();
+
+    let mut env: IndexMap<String, JsonField> = IndexMap::new();
+    for kv in &cli.env {
+        let (k, v) = kv
+            .split_once('=')
+            .ok_or_else(|| anyhow!("invalid --env value '{kv}': expected KEY=VALUE"))?;
+        if k.is_empty() {
+            bail!("invalid --env value '{kv}': KEY cannot be empty");
+        }
+        env.insert(k.to_string(), JsonField::Str(v.to_string()));
+    }
+
+    Ok(McpServer {
+        transport_type: McpTransportType::Stdio,
+        command: Some(cmd.clone()),
+        args: (!args.is_empty()).then(|| args.to_vec()),
+        env: (!env.is_empty()).then_some(env),
+        cwd: cli.cwd.clone(),
+        url: None,
+        headers: None,
+        oauth: None,
+    })
+}
+
+fn build_remote(cli: &Cli, transport: McpTransportType, has_command: bool) -> Result<McpServer> {
+    if has_command {
+        bail!(
+            "http/sse MCP server does not accept a trailing `-- <cmd>`. Use `--url` \
+             to specify the endpoint."
+        );
+    }
+    let url = cli
+        .url
+        .clone()
+        .ok_or_else(|| anyhow!("http/sse MCP server requires --url <URL>"))?;
+    if !cli.env.is_empty() {
+        bail!("http/sse MCP server does not accept --env; use --header instead");
+    }
+    if cli.cwd.is_some() {
+        bail!("http/sse MCP server does not accept --cwd");
+    }
+
+    let mut headers: IndexMap<String, String> = IndexMap::new();
+    for h in &cli.header {
+        let (name, value) = h
+            .split_once(':')
+            .ok_or_else(|| anyhow!("invalid --header value '{h}': expected 'Name: Value'"))?;
+        let name = name.trim();
+        let value = value.trim_start_matches(' ');
+        if name.is_empty() {
+            bail!("invalid --header value '{h}': header name cannot be empty");
+        }
+        headers.insert(name.to_string(), value.to_string());
+    }
+
+    let oauth = if cli.client_id.is_some()
+        || cli.client_secret.is_some()
+        || cli.callback_port.is_some()
+        || cli.redirect_host.is_some()
+    {
+        Some(McpOAuthConfig {
+            client_id: cli.client_id.clone(),
+            client_secret: cli.client_secret.clone(),
+            callback_port: cli.callback_port,
+            redirect_host: cli.redirect_host.clone(),
+        })
+    } else {
+        None
+    };
+
+    Ok(McpServer {
+        transport_type: transport,
+        command: None,
+        args: None,
+        env: None,
+        cwd: None,
+        url: Some(url),
+        headers: (!headers.is_empty()).then_some(headers),
+        oauth,
+    })
+}
+
+fn provision_secrets(cli: &Cli, vault: &Vault) -> Result<()> {
+    let mut sources: Vec<&str> = Vec::new();
+    if let Some(s) = cli.url.as_deref() {
+        sources.push(s);
+    }
+    if let Some(s) = cli.client_secret.as_deref() {
+        sources.push(s);
+    }
+    if let Some(s) = cli.client_id.as_deref() {
+        sources.push(s);
+    }
+    if let Some(s) = cli.redirect_host.as_deref() {
+        sources.push(s);
+    }
+    if let Some(s) = cli.cwd.as_deref() {
+        sources.push(s);
+    }
+    sources.extend(cli.env.iter().map(String::as_str));
+    sources.extend(cli.header.iter().map(String::as_str));
+
+    let mut needed: IndexSet<String> = IndexSet::new();
+    for value in sources {
+        for caps in SECRET_RE.captures_iter(value).filter_map(Result::ok) {
+            if let Some(m) = caps.get(1) {
+                needed.insert(m.as_str().trim().to_string());
+            }
+        }
+    }
+
+    if needed.is_empty() {
+        return Ok(());
+    }
+
+    let existing: HashSet<String> = vault.list_secrets(false)?.into_iter().collect();
+    for name in needed {
+        if existing.contains(&name) {
+            continue;
+        }
+        eprintln!("Value references vault secret {{{{ {name} }}}} which is not stored yet.");
+        let ok = Confirm::new(&format!("Add '{name}' to the vault now?"))
+            .with_default(true)
+            .prompt()?;
+        if !ok {
+            bail!(
+                "Vault secret '{name}' is required by the config; aborting. \
+                 Add it later with `coyote --add-secret {name}`."
+            );
+        }
+        vault.add_secret(&name)?;
+    }
+
+    Ok(())
+}
+
+fn load_for_scope_or_search(
+    name: &str,
+    scope: Option<McpScopeArg>,
+) -> Result<(PathBuf, McpServersConfig)> {
+    if let Some(s) = scope {
+        let path = match s {
+            McpScopeArg::User => paths::mcp_config_file(),
+            McpScopeArg::Workspace => paths::workspace_mcp_config_file()
+                .ok_or_else(|| anyhow!("no workspace mcp.json found in the current directory"))?,
+        };
+        let cfg = load_config_raw(&path)?;
+        if !cfg.mcp_servers.contains_key(name) {
+            bail!(
+                "MCP server '{name}' not found in {} scope ({})",
+                scope_label(s),
+                path.display()
+            );
+        }
+
+        return Ok((path, cfg));
+    }
+
+    let user_path = paths::mcp_config_file();
+    let user_cfg = load_config_raw(&user_path)?;
+    if user_cfg.mcp_servers.contains_key(name) {
+        return Ok((user_path, user_cfg));
+    }
+
+    if let Some(ws_path) = paths::workspace_mcp_config_file() {
+        let ws_cfg = load_config_raw(&ws_path)?;
+        if ws_cfg.mcp_servers.contains_key(name) {
+            return Ok((ws_path, ws_cfg));
+        }
+    }
+
+    bail!("MCP server '{name}' not found in any scope");
+}
+
+fn write_path_for_scope(scope: McpScopeArg) -> PathBuf {
+    match scope {
+        McpScopeArg::User => paths::mcp_config_file(),
+        McpScopeArg::Workspace => paths::workspace_mcp_config_file()
+            .unwrap_or_else(|| paths::workspace_config_dir().join("mcp.json")),
+    }
+}
+
+fn scope_label(scope: McpScopeArg) -> &'static str {
+    match scope {
+        McpScopeArg::User => "user",
+        McpScopeArg::Workspace => "workspace",
+    }
+}
+
+fn load_config_raw(path: &Path) -> Result<McpServersConfig> {
+    if !path.exists() {
+        return Ok(McpServersConfig {
+            mcp_servers: IndexMap::new(),
+        });
+    }
+
+    let raw = fs::read_to_string(path)
+        .with_context(|| format!("failed to read MCP config at {}", path.display()))?;
+    if raw.trim().is_empty() {
+        return Ok(McpServersConfig {
+            mcp_servers: IndexMap::new(),
+        });
+    }
+
+    serde_json::from_str(&raw)
+        .with_context(|| format!("failed to parse MCP config at {}", path.display()))
+}
+
+fn save_config(path: &Path, config: &McpServersConfig) -> Result<()> {
+    ensure_parent_exists(path)?;
+    let serialized =
+        serde_json::to_string_pretty(config).context("failed to serialize MCP config")?;
+    let tmp = path.with_extension("json.tmp");
+    fs::write(&tmp, &serialized)
+        .with_context(|| format!("failed to write temporary MCP config at {}", tmp.display()))?;
+    fs::rename(&tmp, path)
+        .with_context(|| format!("failed to finalize MCP config at {}", path.display()))?;
+
+    Ok(())
+}

src/mcp/mod.rs

@@ -1,3 +1,4 @@
+pub(crate) mod manage;
 pub(crate) mod oauth;
 mod sse_transport;
 
@@ -62,6 +63,8 @@ pub(crate) struct McpServersConfig {
 pub(crate) struct McpOAuthConfig {
     #[serde(rename = "clientId", skip_serializing_if = "Option::is_none")]
     pub client_id: Option<String>,
+    #[serde(rename = "clientSecret", skip_serializing_if = "Option::is_none")]
+    pub client_secret: Option<String>,
     #[serde(rename = "callbackPort", skip_serializing_if = "Option::is_none")]
     pub callback_port: Option<u16>,
     #[serde(rename = "redirectHost", skip_serializing_if = "Option::is_none")]

src/mcp/oauth.rs

@@ -12,6 +12,8 @@ use url::Url;
 
 #[derive(Debug, Deserialize)]
 struct ProtectedResourceMetadata {
+    #[serde(default)]
+    resource: Option<String>,
     #[serde(default)]
     authorization_servers: Vec<String>,
     #[serde(default)]
@@ -30,6 +32,13 @@ struct OAuthServerMetadata {
 #[derive(Serialize, Deserialize)]
 struct McpRegistration {
     client_id: String,
+    #[serde(default)]
+    redirect_uri: Option<String>,
+}
+
+struct DiscoveredOAuth {
+    metadata: OAuthServerMetadata,
+    resource: Option<String>,
 }
 
 struct McpOAuthProvider {
@@ -38,6 +47,7 @@ struct McpOAuthProvider {
     token_url: String,
     scopes: String,
     fixed_redirect: String,
+    resource: String,
 }
 
 impl OAuthProvider for McpOAuthProvider {
@@ -76,6 +86,14 @@ impl OAuthProvider for McpOAuthProvider {
     fn fixed_redirect_uri(&self) -> Option<String> {
         Some(self.fixed_redirect.clone())
     }
+
+    fn extra_authorize_params(&self) -> Vec<(&str, &str)> {
+        vec![("resource", self.resource.as_str())]
+    }
+
+    fn extra_token_params(&self) -> Vec<(&str, &str)> {
+        vec![("resource", self.resource.as_str())]
+    }
 }
 
 pub async fn run_mcp_oauth_flow(
@@ -85,36 +103,57 @@ pub async fn run_mcp_oauth_flow(
     callback_port: Option<u16>,
     redirect_host: Option<&str>,
 ) -> Result<()> {
-    let metadata = discover_oauth_metadata(server_url).await?;
+    let discovered = discover_oauth_metadata(server_url).await?;
+    let metadata = discovered.metadata;
+    let resource = resolve_resource(discovered.resource, server_url)?;
 
     let host = redirect_host.unwrap_or("127.0.0.1");
-    let bind_addr = format!("127.0.0.1:{}", callback_port.unwrap_or(0));
-    let listener = TcpListener::bind(&bind_addr)?;
-    let port = listener.local_addr()?.port();
-    drop(listener);
-    let redirect_uri = format!("http://{host}:{port}/callback");
 
-    let client_id = if let Some(id) = configured_client_id {
-        id.to_string()
-    } else if let Some(cached) = load_registered_client_id(server_name) {
-        cached
-    } else if let Some(reg_endpoint) = &metadata.registration_endpoint {
-        match register_client(reg_endpoint, &redirect_uri).await {
-            Ok(id) => {
-                let _ = save_registered_client_id(server_name, &id);
-                id
-            }
-            Err(e) => {
-                warn!("Dynamic client registration failed: {e}. Falling back to manual entry.");
-                Text::new("Enter the OAuth client ID for this MCP server:")
-                    .prompt()
-                    .context("Failed to read client ID")?
-            }
-        }
+    // Reuse a cached dynamic registration together with the exact redirect
+    // URI it was registered with (AWS et al. match redirect URIs exactly).
+    // Only when no client_id is configured explicitly.
+    let cached_reuse: Option<(String, String)> = if configured_client_id.is_none() {
+        load_registration(server_name).and_then(|reg| {
+            let redirect = reg.redirect_uri?;
+            let port = cached_redirect_port(&redirect, host, callback_port)?;
+            // The registered port must still be free for our callback listener.
+            TcpListener::bind(format!("127.0.0.1:{port}")).ok()?;
+            Some((reg.client_id, redirect))
+        })
     } else {
-        Text::new("Enter the OAuth client ID for this MCP server:")
-            .prompt()
-            .context("Failed to read client ID")?
+        None
+    };
+
+    let (client_id, redirect_uri) = if let Some(reused) = cached_reuse {
+        reused
+    } else {
+        let bind_addr = format!("127.0.0.1:{}", callback_port.unwrap_or(0));
+        let listener = TcpListener::bind(&bind_addr)?;
+        let port = listener.local_addr()?.port();
+        drop(listener);
+        let redirect_uri = format!("http://{host}:{port}/callback");
+
+        let client_id = if let Some(id) = configured_client_id {
+            id.to_string()
+        } else if let Some(reg_endpoint) = &metadata.registration_endpoint {
+            match register_client(reg_endpoint, &redirect_uri).await {
+                Ok(id) => {
+                    let _ = save_registration(server_name, &id, &redirect_uri);
+                    id
+                }
+                Err(e) => {
+                    warn!("Dynamic client registration failed: {e}. Falling back to manual entry.");
+                    Text::new("Enter the OAuth client ID for this MCP server:")
+                        .prompt()
+                        .context("Failed to read client ID")?
+                }
+            }
+        } else {
+            Text::new("Enter the OAuth client ID for this MCP server:")
+                .prompt()
+                .context("Failed to read client ID")?
+        };
+        (client_id, redirect_uri)
     };
 
     let provider = McpOAuthProvider {
@@ -123,6 +162,7 @@ pub async fn run_mcp_oauth_flow(
         token_url: metadata.token_endpoint,
         scopes: metadata.scopes_supported.join(" "),
         fixed_redirect: redirect_uri,
+        resource,
     };
 
     run_oauth_flow(&provider, &mcp_token_key(server_name)).await
@@ -141,21 +181,20 @@ fn mcp_token_key(server_name: &str) -> String {
     format!("mcp_{server_name}")
 }
 
-fn load_registered_client_id(server_name: &str) -> Option<String> {
+fn load_registration(server_name: &str) -> Option<McpRegistration> {
     let path = paths::oauth_tokens_dir().join(format!("mcp_{server_name}_registration.json"));
     let content = fs::read_to_string(path).ok()?;
-    let reg: McpRegistration = serde_json::from_str(&content).ok()?;
-
-    Some(reg.client_id)
+    serde_json::from_str(&content).ok()
 }
 
-fn save_registered_client_id(server_name: &str, client_id: &str) -> Result<()> {
+fn save_registration(server_name: &str, client_id: &str, redirect_uri: &str) -> Result<()> {
     let dir = paths::oauth_tokens_dir();
     fs::create_dir_all(&dir)?;
 
     let path = dir.join(format!("mcp_{server_name}_registration.json"));
     let reg = McpRegistration {
         client_id: client_id.to_string(),
+        redirect_uri: Some(redirect_uri.to_string()),
     };
 
     fs::write(path, serde_json::to_string_pretty(&reg)?)?;
@@ -163,6 +202,27 @@ fn save_registered_client_id(server_name: &str, client_id: &str) -> Result<()> {
     Ok(())
 }
 
+/// Returns the port of a cached registered redirect URI if it is still
+/// compatible with the current configuration: same redirect host, and, when
+/// a callback port is pinned in config, the same port. Servers like AWS
+/// match redirect URIs exactly, so a cached registration is only reusable
+/// with the identical redirect URI it was registered with.
+fn cached_redirect_port(
+    cached_redirect: &str,
+    host: &str,
+    pinned_port: Option<u16>,
+) -> Option<u16> {
+    let url = Url::parse(cached_redirect).ok()?;
+    if url.host_str() != Some(host) {
+        return None;
+    }
+    let port = url.port()?;
+    if pinned_port.is_some_and(|p| p != port) {
+        return None;
+    }
+    Some(port)
+}
+
 async fn register_client(endpoint: &str, redirect_uri: &str) -> Result<String> {
     let body = serde_json::json!({
         "client_name": "Coyote",
@@ -188,7 +248,44 @@ async fn register_client(endpoint: &str, redirect_uri: &str) -> Result<String> {
         .map(|s| s.to_string())
 }
 
-async fn discover_oauth_metadata(server_url: &str) -> Result<OAuthServerMetadata> {
+/// Derives the canonical resource URI for an MCP server per RFC 8707 @ 2 and
+/// the MCP spec: the configured server URL with query and fragment stripped.
+fn canonical_resource(server_url: &str) -> Result<String> {
+    let mut url =
+        Url::parse(server_url).with_context(|| format!("Invalid MCP server URL: {server_url}"))?;
+    url.set_query(None);
+    url.set_fragment(None);
+
+    let s = url.to_string();
+    Ok(match url.path() {
+        "/" => s.trim_end_matches('/').to_string(),
+        _ => s,
+    })
+}
+
+/// Resolves the RFC 8707 resource indicator: prefers the value advertised in
+/// the protected resource metadata, but only after validating it identifies
+/// the server we are connecting to (RFC 9728 @ 3.3); same scheme/host/port
+/// as the configured server URL. Falls back to the canonical server URL on
+/// mismatch, empty value, or absence.
+fn resolve_resource(advertised: Option<String>, server_url: &str) -> Result<String> {
+    let canonical = canonical_resource(server_url)?;
+    let Some(advertised) = advertised.filter(|r| !r.is_empty()) else {
+        return Ok(canonical);
+    };
+    match (Url::parse(&advertised), Url::parse(server_url)) {
+        (Ok(a), Ok(s)) if a.origin() == s.origin() => Ok(advertised),
+        _ => {
+            warn!(
+                "Ignoring protected resource metadata resource '{advertised}': \
+                 it does not match the MCP server origin. Using '{canonical}' instead."
+            );
+            Ok(canonical)
+        }
+    }
+}
+
+async fn discover_oauth_metadata(server_url: &str) -> Result<DiscoveredOAuth> {
     let client = Client::new();
     let mut tried: Vec<String> = Vec::new();
 
@@ -231,7 +328,10 @@ async fn discover_oauth_metadata(server_url: &str) -> Result<OAuthServerMetadata
                 if meta.scopes_supported.is_empty() {
                     meta.scopes_supported = pr.scopes_supported.clone();
                 }
-                return Ok(meta);
+                return Ok(DiscoveredOAuth {
+                    metadata: meta,
+                    resource: pr.resource.clone(),
+                });
             }
         }
     }
@@ -245,7 +345,11 @@ async fn discover_oauth_metadata(server_url: &str) -> Result<OAuthServerMetadata
             return resp
                 .json::<OAuthServerMetadata>()
                 .await
-                .with_context(|| format!("Failed to parse OAuth metadata from {as_url}"));
+                .with_context(|| format!("Failed to parse OAuth metadata from {as_url}"))
+                .map(|metadata| DiscoveredOAuth {
+                    metadata,
+                    resource: None,
+                });
         }
     }
 
@@ -469,23 +573,132 @@ mod tests {
         );
     }
 
+    #[test]
+    fn canonical_resource_strips_query() {
+        let result = canonical_resource("https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize");
+
+        assert_eq!(result.unwrap(), "https://aws-mcp.us-east-1.api.aws/mcp");
+    }
+
+    #[test]
+    fn canonical_resource_strips_fragment() {
+        let result = canonical_resource("https://example.com/mcp#section");
+
+        assert_eq!(result.unwrap(), "https://example.com/mcp");
+    }
+
+    #[test]
+    fn canonical_resource_preserves_path_and_port() {
+        let result = canonical_resource("http://localhost:8080/mcp/v1?x=1");
+
+        assert_eq!(result.unwrap(), "http://localhost:8080/mcp/v1");
+    }
+
+    #[test]
+    fn canonical_resource_rejects_invalid_url() {
+        assert!(canonical_resource("not-a-url").is_err());
+    }
+
+    #[test]
+    fn canonical_resource_bare_host_has_no_trailing_slash() {
+        let result = canonical_resource("https://mcp.example.com");
+
+        assert_eq!(result.unwrap(), "https://mcp.example.com");
+    }
+
+    #[test]
+    fn resolve_resource_prefers_matching_advertised() {
+        let result = resolve_resource(
+            Some("https://aws-mcp.us-east-1.api.aws/mcp".into()),
+            "https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize",
+        );
+
+        assert_eq!(result.unwrap(), "https://aws-mcp.us-east-1.api.aws/mcp");
+    }
+
+    #[test]
+    fn resolve_resource_rejects_cross_origin_advertised() {
+        let result = resolve_resource(
+            Some("https://evil.example.com/mcp".into()),
+            "https://aws-mcp.us-east-1.api.aws/mcp",
+        );
+
+        assert_eq!(result.unwrap(), "https://aws-mcp.us-east-1.api.aws/mcp");
+    }
+
+    #[test]
+    fn resolve_resource_empty_falls_back_to_canonical() {
+        let result = resolve_resource(Some(String::new()), "https://example.com/mcp");
+
+        assert_eq!(result.unwrap(), "https://example.com/mcp");
+    }
+
+    #[test]
+    fn resolve_resource_none_falls_back_to_canonical() {
+        let result = resolve_resource(None, "https://example.com/mcp");
+
+        assert_eq!(result.unwrap(), "https://example.com/mcp");
+    }
+
+    #[test]
+    fn protected_resource_metadata_deserializes_resource_field() {
+        let json = r#"{"resource":"https://aws-mcp.us-east-1.api.aws/mcp","authorization_servers":["https://us-east-1.oauth.signin.aws/"]}"#;
+
+        let pr: ProtectedResourceMetadata = serde_json::from_str(json).unwrap();
+
+        assert_eq!(
+            pr.resource.as_deref(),
+            Some("https://aws-mcp.us-east-1.api.aws/mcp")
+        );
+        assert_eq!(
+            pr.authorization_servers,
+            vec!["https://us-east-1.oauth.signin.aws/"]
+        );
+    }
+
+    #[test]
+    fn mcp_provider_sends_resource_in_authorize_and_token_params() {
+        let provider = McpOAuthProvider {
+            client_id: "client-123".into(),
+            authorize_url: "https://as.example/authorize".into(),
+            token_url: "https://as.example/token".into(),
+            scopes: String::new(),
+            fixed_redirect: "http://127.0.0.1:9000/callback".into(),
+            resource: "https://aws-mcp.us-east-1.api.aws/mcp".into(),
+        };
+
+        assert_eq!(
+            provider.extra_authorize_params(),
+            vec![("resource", "https://aws-mcp.us-east-1.api.aws/mcp")]
+        );
+        assert_eq!(
+            provider.extra_token_params(),
+            vec![("resource", "https://aws-mcp.us-east-1.api.aws/mcp")]
+        );
+    }
+
     #[test]
     #[serial]
     fn registered_client_id_roundtrip() {
         with_temp_cache(|| {
-            save_registered_client_id("notion", "client-xyz-123").unwrap();
+            save_registration(
+                "notion",
+                "client-xyz-123",
+                "http://127.0.0.1:49152/callback",
+            )
+            .unwrap();
 
-            let loaded = load_registered_client_id("notion");
+            let loaded = load_registration("notion");
 
-            assert_eq!(loaded, Some("client-xyz-123".to_string()));
+            assert_eq!(loaded.unwrap().client_id, "client-xyz-123");
         });
     }
 
     #[test]
     #[serial]
-    fn load_registered_client_id_returns_none_for_missing() {
+    fn load_registration_returns_none_for_missing() {
         with_temp_cache(|| {
-            let loaded = load_registered_client_id("no-such-server");
+            let loaded = load_registration("no-such-server");
 
             assert!(loaded.is_none());
         });
@@ -493,14 +706,79 @@ mod tests {
 
     #[test]
     #[serial]
-    fn registered_client_id_second_save_overwrites_first() {
+    fn registration_second_save_overwrites_first() {
         with_temp_cache(|| {
-            save_registered_client_id("github", "first-id").unwrap();
-            save_registered_client_id("github", "second-id").unwrap();
+            save_registration("github", "first-id", "http://127.0.0.1:49152/callback").unwrap();
+            save_registration("github", "second-id", "http://127.0.0.1:49153/callback").unwrap();
 
-            let loaded = load_registered_client_id("github");
+            let loaded = load_registration("github").unwrap();
 
-            assert_eq!(loaded, Some("second-id".to_string()));
+            assert_eq!(loaded.client_id, "second-id");
+            assert_eq!(
+                loaded.redirect_uri.as_deref(),
+                Some("http://127.0.0.1:49153/callback")
+            );
         });
     }
+
+    #[test]
+    #[serial]
+    fn old_format_registration_still_loads() {
+        with_temp_cache(|| {
+            let dir = paths::oauth_tokens_dir();
+            fs::create_dir_all(&dir).unwrap();
+            fs::write(
+                dir.join("mcp_legacy_registration.json"),
+                r#"{"client_id":"legacy-id"}"#,
+            )
+            .unwrap();
+
+            let loaded = load_registration("legacy").unwrap();
+
+            assert_eq!(loaded.client_id, "legacy-id");
+            assert_eq!(loaded.redirect_uri, None);
+        });
+    }
+
+    #[test]
+    #[serial]
+    fn save_registration_persists_redirect_uri() {
+        with_temp_cache(|| {
+            save_registration("aws", "client-abc", "http://127.0.0.1:49152/callback").unwrap();
+
+            let loaded = load_registration("aws").unwrap();
+
+            assert_eq!(loaded.client_id, "client-abc");
+            assert_eq!(
+                loaded.redirect_uri.as_deref(),
+                Some("http://127.0.0.1:49152/callback")
+            );
+        });
+    }
+
+    #[test]
+    fn cached_redirect_port_matches() {
+        let port = cached_redirect_port("http://127.0.0.1:49152/callback", "127.0.0.1", None);
+
+        assert_eq!(port, Some(49152));
+    }
+
+    #[test]
+    fn cached_redirect_port_rejects_host_mismatch() {
+        let port = cached_redirect_port("http://127.0.0.1:49152/callback", "localhost", None);
+
+        assert_eq!(port, None);
+    }
+
+    #[test]
+    fn cached_redirect_port_respects_pinned_port() {
+        assert_eq!(
+            cached_redirect_port("http://127.0.0.1:49152/callback", "127.0.0.1", Some(50000)),
+            None
+        );
+        assert_eq!(
+            cached_redirect_port("http://127.0.0.1:49152/callback", "127.0.0.1", Some(49152)),
+            Some(49152)
+        );
+    }
 }

src/rag/provider.rs

@@ -0,0 +1,76 @@
+use super::{DocumentId, RagData};
+use anyhow::Result;
+use async_trait::async_trait;
+
+/// Abstracts where RAG vector data is stored and queried.
+///
+/// The Rag orchestrator owns: embeddings, chunking, BM25 keyword search, graph RAG,
+/// entity extraction, RRF merging. Providers own: vector storage and content retrieval.
+#[async_trait]
+pub trait RagProvider: Send + Sync {
+    /// Vector similarity search. Returns (DocumentId, score) sorted by score desc.
+    /// `embedding` is a single query vector from Coyote's embedding model.
+    async fn vector_search(
+        &self,
+        embedding: &[f32],
+        top_k: usize,
+        min_score: f32,
+    ) -> Result<Vec<(DocumentId, f32)>>;
+
+    /// Resolve document IDs to their page content.
+    ///
+    /// **Ordering contract:** implementations MUST return results in the same
+    /// relative order as the input `ids` slice. `hybrid_search` passes an
+    /// RRF-ranked list and feeds the result straight to the LLM. A provider
+    /// that returns rows in storage order (e.g. Qdrant `get_points`, DuckDB
+    /// `WHERE id IN (...)`) would silently discard the ranking. Implementations
+    /// that query an unordered backend must re-sort by input position before
+    /// returning.
+    ///
+    /// Returns only IDs that were found; callers must handle partial returns
+    /// (a missing ID is skipped, not an error).
+    /// YamlProvider: reads from an in-memory content map built from data.files.
+    /// DuckDbProvider: queries the documents table by id.
+    /// QdrantProvider: fetches payload from the remote collection.
+    async fn fetch_content(&self, ids: &[DocumentId]) -> Result<Vec<(DocumentId, String)>>;
+
+    /// Rebuild internal indexes from freshly updated RagData.
+    /// Called once at the end of every sync_documents pass.
+    ///
+    /// `full_rebuild` mirrors `sync_documents`' `refresh` parameter:
+    ///   - `true`: a full re-index (`.rebuild rag`, `--rebuild-rag`, initial build).
+    ///     Destructive strategies (wipe-then-reindex) are permitted.
+    ///   - `false`: an incremental change (`.edit rag-docs` adding/removing a file).
+    ///     Implementations MUST NOT wipe existing state; upsert only.
+    ///
+    /// The parameter is part of the signature from the outset so it is fixed
+    /// while there is exactly one implementor. Yaml/DuckDb ignore it,
+    /// rebuilding their local state wholesale is fast and always correct.
+    /// Only a remote provider is destructive enough to care.
+    async fn rebuild_indexes(&mut self, data: &RagData, full_rebuild: bool) -> Result<()>;
+
+    /// Keyword / full-text search. Returns (DocumentId, BM25-style score) sorted desc.
+    ///
+    /// Default impl returns `Ok(vec![])`. Callers fall back to `Rag.bm25` (local in-memory
+    /// BM25 built from `data.files`).
+    ///
+    /// Callers check `has_native_keyword_search()` before deciding which path to take:
+    ///   - true  → call this method; skip `Rag.bm25`
+    ///   - false → call `Rag.keyword_search()` which uses `Rag.bm25` (sync, infallible)
+    async fn keyword_search(&self, query: &str, top_k: usize) -> Result<Vec<(DocumentId, f32)>> {
+        let _ = (query, top_k);
+
+        Ok(vec![])
+    }
+
+    /// Returns true if this provider implements a native keyword-search index.
+    /// When false, `Rag.hybrid_search` uses the local `Rag.bm25` field instead.
+    fn has_native_keyword_search(&self) -> bool {
+        false
+    }
+
+    /// Deep-clone the provider with fresh indexes derived from `data`.
+    /// Required because Box<dyn RagProvider> is not Clone.
+    /// Called by Rag's Clone impl (which clones before mutating in rebuild_rag/edit_rag_docs).
+    fn duplicate(&self, data: &RagData) -> Box<dyn RagProvider>;
+}

src/rag/providers/mod.rs

@@ -0,0 +1,9 @@
+mod yaml;
+pub use self::yaml::YamlProvider;
+
+mod duckdb;
+pub use self::duckdb::DuckDbProvider;
+pub(crate) use self::duckdb::duckdb_path_from_yaml;
+
+mod qdrant;
+pub use self::qdrant::QdrantProvider;

src/rag/providers/qdrant.rs

@@ -0,0 +1,828 @@
+use crate::rag::provider::RagProvider;
+use crate::rag::{DocumentId, RagData};
+
+use anyhow::{Context, Result, bail};
+use async_trait::async_trait;
+use parking_lot::RwLock;
+use reqwest::header::{HeaderMap, HeaderValue};
+use reqwest::{Client, Response, StatusCode};
+use serde_json::Value;
+use std::collections::HashMap;
+use std::sync::Arc;
+use url::{Host, Url};
+
+/// Marks a `DocumentId` that stands in for a point id Coyote cannot carry
+/// directly. Qdrant accepts UUID strings as point ids, and that is what
+/// LangChain writes by default.
+///
+/// `DocumentId` packs `(file_index, document_index)` into one `usize` with the
+/// file index in the high half, so this bit is only reachable at a file index of
+/// 2^31. Nothing local gets near that, and an attached RAG builds no local index
+/// at all — `data.files` and `data.vectors` stay empty and every
+/// `DocumentId::split` caller early-returns on `data.attached`. Along the
+/// attached path the id is an opaque key carried through RRF, which is what
+/// makes a synthetic one safe here and nowhere else.
+const SYNTHETIC_ID_TAG: usize = 1 << (usize::BITS - 1);
+
+/// Two-way map between a raw Qdrant point id and the `DocumentId` the retrieval
+/// pipeline sees.
+///
+/// Only ids that cannot survive the round trip are interned. A plain `u64` that
+/// fits below the tag keeps mapping to itself, so integer-keyed collections
+/// behave exactly as they did before this map existed.
+#[derive(Default)]
+struct PointIdInterner {
+    handles: HashMap<String, DocumentId>,
+    raw: HashMap<DocumentId, Value>,
+    next: usize,
+}
+
+impl PointIdInterner {
+    /// The `DocumentId` for a raw point id, minting a handle if one is needed.
+    ///
+    /// `None` only for a missing id, which is a malformed response.
+    fn document_id(&mut self, raw: &Value) -> Option<DocumentId> {
+        if raw.is_null() {
+            return None;
+        }
+        // The pre-existing integer path, unchanged. `try_from` rather than `as`
+        // so a value too wide for the target's `usize` is interned instead of
+        // silently truncated into a different point.
+        if let Some(n) = raw.as_u64()
+            && let Ok(n) = usize::try_from(n)
+            && n & SYNTHETIC_ID_TAG == 0
+        {
+            return Some(DocumentId(n));
+        }
+        Some(self.intern(raw))
+    }
+
+    fn intern(&mut self, raw: &Value) -> DocumentId {
+        // Keyed on the JSON rendering, so the string "1" and the integer 1 are
+        // not conflated into one point.
+        let key = raw.to_string();
+        if let Some(handle) = self.handles.get(&key) {
+            return *handle;
+        }
+        let handle = DocumentId(SYNTHETIC_ID_TAG | self.next);
+        self.next += 1;
+        self.handles.insert(key, handle);
+        self.raw.insert(handle, raw.clone());
+        handle
+    }
+
+    /// The original id for a handle, or `None` when the id was never interned —
+    /// i.e. it is a plain integer that is already its own id.
+    fn raw_id(&self, handle: DocumentId) -> Option<&Value> {
+        self.raw.get(&handle)
+    }
+
+    /// Builds the `ids` array for an outbound `/points` fetch. Every entry is the
+    /// id Qdrant issued, integer or string; a synthetic handle must never leave
+    /// this process.
+    fn outbound_ids(&self, ids: &[DocumentId]) -> Vec<Value> {
+        ids.iter()
+            .map(|id| match self.raw_id(*id) {
+                Some(raw) => raw.clone(),
+                None => Value::from(id.0 as u64),
+            })
+            .collect()
+    }
+}
+
+fn parse_search_hits(
+    interner: &mut PointIdInterner,
+    body: &Value,
+    min_score: f32,
+) -> Result<Vec<(DocumentId, f32)>> {
+    let hits = body["result"]
+        .as_array()
+        .context("Unexpected /points/search response shape")?;
+
+    Ok(hits
+        .iter()
+        .filter_map(|pt| {
+            let score = pt["score"].as_f64()? as f32;
+            Some((interner.document_id(&pt["id"])?, score))
+        })
+        .filter(|(_, score)| min_score <= 0.0 || *score > min_score)
+        .collect())
+}
+
+fn parse_points(interner: &mut PointIdInterner, body: &Value) -> Result<Vec<(DocumentId, String)>> {
+    let points = body["result"]
+        .as_array()
+        .context("Unexpected /points response shape")?;
+
+    Ok(points
+        .iter()
+        .filter_map(|pt| {
+            let text = pt["payload"]["page_content"].as_str()?.to_string();
+            Some((interner.document_id(&pt["id"])?, text))
+        })
+        .collect())
+}
+
+/// Render Qdrant's error envelope into a human-readable message.
+///
+/// `body` is the raw response text. Two shapes have to be tolerated:
+///   * application-level errors carry `{"status": {"error": "..."}, "time": 0.0}`,
+///     while successful responses carry a bare string `{"status": "ok", ...}` — so
+///     `status` is string-or-object and a struct with `status: String` fails to
+///     parse every error body;
+///   * routing-level 404s (a wrong HTTP verb) return an EMPTY body with no JSON at
+///     all, which without the length check surfaces as "EOF while parsing a value"
+///     instead of the actual 404.
+fn format_error_body(status: StatusCode, body: &str) -> String {
+    if body.is_empty() {
+        return format!("HTTP {status} (empty body — check the HTTP verb and path)");
+    }
+    serde_json::from_str::<Value>(body)
+        .ok()
+        .and_then(|v| v["status"]["error"].as_str().map(str::to_string))
+        .unwrap_or_else(|| format!("HTTP {status}: {body}"))
+}
+
+/// Read the vector dimension out of a parsed `GET /collections/{name}` response.
+fn vector_dimension_from_collection(body: &Value) -> Result<u64> {
+    let params = &body["result"]["config"]["params"];
+    params["vectors"]["size"]
+        .as_u64()
+        .or_else(|| {
+            params["vectors"]
+                .as_object()
+                .and_then(|m| m.values().next())
+                .and_then(|v| v["size"].as_u64())
+        })
+        .context("Could not determine vector dimension from collection config")
+}
+
+/// True if a parsed `GET /collections/{name}` response describes a NAMED
+/// (multi-vector) collection.
+///
+/// `vector_search` posts an unnamed vector, which a named-vector collection
+/// rejects with HTTP 400 on every query, so attaching one yields a RAG that is
+/// silently 100% broken. A named collection holding a SINGLE vector is
+/// structurally a map, identical in kind to the multi-named case, and rejects
+/// the same way; testing for a numeric `size` directly under `vectors` catches
+/// it, whereas counting keys (`len() > 1`) would wrongly accept it.
+fn is_multi_vector_config(body: &Value) -> bool {
+    body["result"]["config"]["params"]["vectors"]["size"]
+        .as_u64()
+        .is_none()
+}
+
+/// Query-only client for an external Qdrant collection.
+///
+/// Attach-only: this provider never writes to the remote collection. Coyote does
+/// not own the data, and `rebuild_indexes` refuses rather than pretending to.
+pub struct QdrantProvider {
+    client: Client,
+    base_url: String,
+    collection: String,
+    point_ids: Arc<RwLock<PointIdInterner>>,
+}
+
+impl QdrantProvider {
+    fn skips_proxy(base_url: &str) -> bool {
+        let Ok(url) = Url::parse(base_url) else {
+            return false;
+        };
+        match url.host() {
+            Some(Host::Domain(name)) => {
+                name == "localhost" || name.ends_with(".localhost") || name.ends_with(".local")
+            }
+            Some(Host::Ipv4(ip)) => ip.is_loopback() || ip.is_private() || ip.is_link_local(),
+            // No stable is_unique_local, so fc00::/7 is matched directly.
+            Some(Host::Ipv6(ip)) => ip.is_loopback() || ip.segments()[0] & 0xfe00 == 0xfc00,
+            None => false,
+        }
+    }
+
+    fn make_client(base_url: &str, api_key: Option<&str>) -> Result<Client> {
+        let mut headers = HeaderMap::new();
+        if let Some(key) = api_key {
+            let mut value =
+                HeaderValue::from_str(key).context("api-key header value is not valid ASCII")?;
+            value.set_sensitive(true);
+            headers.insert("api-key", value);
+        }
+        let mut builder = Client::builder().default_headers(headers);
+        if Self::skips_proxy(base_url) {
+            builder = builder.no_proxy();
+        }
+        builder.build().context("Failed to build reqwest client")
+    }
+
+    pub(crate) fn normalize_base_url(host: &str) -> String {
+        if host.starts_with("http://") || host.starts_with("https://") {
+            host.to_string()
+        } else {
+            format!("http://{host}")
+        }
+    }
+
+    async fn error_message(resp: Response) -> String {
+        let status = resp.status();
+        let body = resp.text().await.unwrap_or_default();
+        format_error_body(status, &body)
+    }
+
+    /// Shared `GET /collections/{name}` fetch. Both the dimension and the
+    /// multi-vector probe discriminate on this same response.
+    async fn fetch_collection(
+        host: &str,
+        collection: &str,
+        api_key: Option<&str>,
+    ) -> Result<Value> {
+        let base_url = Self::normalize_base_url(host);
+        let client = Self::make_client(&base_url, api_key)?;
+        let resp = client
+            .get(format!("{base_url}/collections/{collection}"))
+            .send()
+            .await
+            .with_context(|| format!("Failed to connect to {host}"))?;
+        if !resp.status().is_success() {
+            bail!(
+                "Failed to read collection '{collection}': {}",
+                Self::error_message(resp).await
+            );
+        }
+
+        Ok(resp.json().await?)
+    }
+
+    pub async fn new(host: &str, collection: &str, api_key: Option<&str>) -> Result<Self> {
+        let base_url = Self::normalize_base_url(host);
+        let client = Self::make_client(&base_url, api_key)?;
+        let resp = client
+            .get(format!("{base_url}/collections/{collection}"))
+            .send()
+            .await
+            .with_context(|| format!("Failed to connect to {host}"))?;
+        if !resp.status().is_success() {
+            bail!(
+                "Collection '{collection}' not accessible at {host}: {}",
+                Self::error_message(resp).await
+            );
+        }
+
+        Ok(Self {
+            client,
+            base_url,
+            collection: collection.to_string(),
+            point_ids: Arc::default(),
+        })
+    }
+
+    pub async fn list_collections(host: &str, api_key: Option<&str>) -> Result<Vec<String>> {
+        let base_url = Self::normalize_base_url(host);
+        let client = Self::make_client(&base_url, api_key)?;
+        let resp = client
+            .get(format!("{base_url}/collections"))
+            .send()
+            .await
+            .with_context(|| format!("Failed to connect to {host}"))?;
+        if !resp.status().is_success() {
+            bail!(
+                "Failed to list collections: {}",
+                Self::error_message(resp).await
+            );
+        }
+
+        let body: Value = resp.json().await?;
+        let names = body["result"]["collections"]
+            .as_array()
+            .context("Unexpected /collections response shape")?
+            .iter()
+            .filter_map(|v| v["name"].as_str().map(str::to_string))
+            .collect();
+
+        Ok(names)
+    }
+
+    pub async fn get_vector_dimension(
+        host: &str,
+        collection: &str,
+        api_key: Option<&str>,
+    ) -> Result<u64> {
+        let body = Self::fetch_collection(host, collection, api_key).await?;
+
+        vector_dimension_from_collection(&body)
+    }
+
+    pub async fn is_multi_vector(
+        host: &str,
+        collection: &str,
+        api_key: Option<&str>,
+    ) -> Result<bool> {
+        let body = Self::fetch_collection(host, collection, api_key).await?;
+
+        Ok(is_multi_vector_config(&body))
+    }
+
+    pub async fn sample_point_id(
+        host: &str,
+        collection: &str,
+        api_key: Option<&str>,
+    ) -> Result<Option<String>> {
+        let base_url = Self::normalize_base_url(host);
+        let client = Self::make_client(&base_url, api_key)?;
+        let url = format!("{base_url}/collections/{collection}/points/scroll");
+        let body = serde_json::json!({ "limit": 1, "with_payload": false });
+
+        let resp = client
+            .post(&url)
+            .json(&body)
+            .send()
+            .await
+            .with_context(|| format!("Failed to connect to {host}"))?;
+
+        if !resp.status().is_success() {
+            bail!(
+                "Failed to sample a point from '{collection}': {}",
+                Self::error_message(resp).await
+            );
+        }
+
+        let data: Value = resp.json().await?;
+        let id_val = data["result"]["points"]
+            .as_array()
+            .and_then(|pts| pts.first())
+            .map(|pt| pt["id"].to_string());
+
+        Ok(id_val)
+    }
+}
+
+#[async_trait]
+impl RagProvider for QdrantProvider {
+    async fn vector_search(
+        &self,
+        embedding: &[f32],
+        top_k: usize,
+        min_score: f32,
+    ) -> Result<Vec<(DocumentId, f32)>> {
+        let url = format!(
+            "{}/collections/{}/points/search",
+            self.base_url, self.collection
+        );
+        // `score_threshold` is deliberately NOT sent. It is metric-aware: on Cosine
+        // collections 0.0 means "no floor" as expected, but Euclid collections score
+        // by negative distance, where 0.0 filters everything out. The attach wizard
+        // does not pin the distance metric, so filter locally instead; i.e. where a
+        // 0.0 floor is correctly treated as "no floor" (see `parse_search_hits`).
+        let body = serde_json::json!({
+            "vector": embedding,
+            "limit": top_k,
+            "with_payload": false,
+        });
+        let resp = self.client.post(&url).json(&body).send().await?;
+        if !resp.status().is_success() {
+            bail!(
+                "Qdrant search on '{}' failed: {}",
+                self.collection,
+                Self::error_message(resp).await
+            );
+        }
+        let data: Value = resp.json().await?;
+        // The interner is what lets a UUID-keyed collection work: a string id gets
+        // a synthetic handle here and the original is replayed by `fetch_content`.
+        let mut interner = self.point_ids.write();
+
+        parse_search_hits(&mut interner, &data, min_score)
+    }
+
+    async fn fetch_content(&self, ids: &[DocumentId]) -> Result<Vec<(DocumentId, String)>> {
+        if ids.is_empty() {
+            return Ok(vec![]);
+        }
+        let url = format!("{}/collections/{}/points", self.base_url, self.collection);
+        // Qdrant is asked for the ids it issued, never for a synthetic handle.
+        let id_list = self.point_ids.read().outbound_ids(ids);
+        let body = serde_json::json!({
+            "ids": id_list,
+            "with_payload": true,
+        });
+
+        let resp = self.client.post(&url).json(&body).send().await?;
+
+        if !resp.status().is_success() {
+            bail!(
+                "Qdrant point fetch on '{}' failed: {}",
+                self.collection,
+                Self::error_message(resp).await
+            );
+        }
+        let data: Value = resp.json().await?;
+        let mut rows = {
+            let mut interner = self.point_ids.write();
+            parse_points(&mut interner, &data)?
+        };
+        // `/points` does not guarantee response order matches request order, and the
+        // caller's RRF ranking is carried by that order. Restore it.
+        let position: HashMap<DocumentId, usize> =
+            ids.iter().enumerate().map(|(i, id)| (*id, i)).collect();
+        rows.sort_by_key(|(id, _)| position.get(id).copied().unwrap_or(usize::MAX));
+
+        Ok(rows)
+    }
+
+    async fn rebuild_indexes(&mut self, data: &RagData, _full_rebuild: bool) -> Result<()> {
+        // Both arms refuse. A silent `Ok(())` would make `.rebuild rag` and
+        // `.edit rag-docs` look like they worked while writing nothing to the
+        // remote, leaving the user believing the collection was updated.
+        if data.attached {
+            bail!(
+                "This RAG is attached to an external Qdrant collection. Coyote does not own \
+                 its documents and cannot rebuild it. Manage the collection directly, or \
+                 create a Coyote-owned RAG with `.rag <name>`."
+            );
+        }
+        bail!("Writing to Qdrant is not supported yet (attach-only).");
+    }
+
+    fn duplicate(&self, _data: &RagData) -> Box<dyn RagProvider> {
+        // Cloning the client shares the connection pool and the injected api-key
+        // header. Sharing is correct: both handles address the same remote
+        // collection, and neither of them writes to it.
+        //
+        // The point-id map is shared for the same reason, and because it MUST be:
+        // `Rag::clone()` hands the clone `DocumentId`s that the original minted,
+        // so a fresh map would resolve them to nothing and `fetch_content` would
+        // ask Qdrant for a synthetic handle — zero results, no error. Resetting it
+        // would also re-mint handles for ids the original still holds.
+        Box::new(Self {
+            client: self.client.clone(),
+            base_url: self.base_url.clone(),
+            collection: self.collection.clone(),
+            point_ids: Arc::clone(&self.point_ids),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn error_message_reads_the_object_status_envelope() {
+        let body =
+            r#"{"status": {"error": "Wrong input: Not existing vector name error:"}, "time": 0.0}"#;
+        let msg = format_error_body(StatusCode::BAD_REQUEST, body);
+        assert!(msg.contains("Not existing vector name"), "got: {msg}");
+        assert!(
+            !msg.contains("EOF"),
+            "must not fall through to a parse error"
+        );
+    }
+
+    #[test]
+    fn error_message_survives_the_string_status_and_the_empty_body() {
+        let ok = format_error_body(StatusCode::OK, r#"{"status": "ok", "time": 0.0}"#);
+        assert!(
+            ok.contains("200"),
+            "no `status.error` present → fall back to status+body: {ok}"
+        );
+
+        let empty = format_error_body(StatusCode::NOT_FOUND, "");
+
+        assert!(empty.contains("empty body"), "got: {empty}");
+        assert!(
+            empty.contains("verb"),
+            "the message must point at the likely cause: {empty}"
+        );
+    }
+
+    #[test]
+    fn vector_dimension_handles_both_collection_shapes() {
+        let unnamed = serde_json::json!({
+            "result": {"config": {"params": {"vectors": {"size": 1536, "distance": "Cosine"}}}}
+        });
+        assert_eq!(vector_dimension_from_collection(&unnamed).unwrap(), 1536);
+
+        let named = serde_json::json!({
+            "result": {"config": {"params": {"vectors": {"text": {"size": 768, "distance": "Cosine"}}}}}
+        });
+        assert_eq!(vector_dimension_from_collection(&named).unwrap(), 768);
+
+        let junk = serde_json::json!({"result": {"config": {"params": {}}}});
+        assert!(vector_dimension_from_collection(&junk).is_err());
+    }
+
+    #[test]
+    fn is_multi_vector_rejects_the_named_single_collection() {
+        let unnamed = serde_json::json!({
+            "result": {"config": {"params": {"vectors": {"size": 1536, "distance": "Cosine"}}}}
+        });
+        assert!(!is_multi_vector_config(&unnamed));
+
+        let named_single = serde_json::json!({
+            "result": {"config": {"params": {"vectors": {"text": {"size": 1536}}}}}
+        });
+        assert!(
+            is_multi_vector_config(&named_single),
+            "named-single must be rejected too"
+        );
+
+        let named_multi = serde_json::json!({
+            "result": {"config": {"params": {"vectors": {"text": {"size": 1536}, "image": {"size": 512}}}}}
+        });
+        assert!(is_multi_vector_config(&named_multi));
+    }
+
+    #[test]
+    fn normalize_base_url_only_adds_a_scheme_when_missing() {
+        assert_eq!(
+            QdrantProvider::normalize_base_url("qdrant.example.com:6333"),
+            "http://qdrant.example.com:6333"
+        );
+        assert_eq!(
+            QdrantProvider::normalize_base_url("https://xyz.cloud.qdrant.io"),
+            "https://xyz.cloud.qdrant.io"
+        );
+        assert_eq!(
+            QdrantProvider::normalize_base_url("http://localhost:6333"),
+            "http://localhost:6333"
+        );
+    }
+
+    #[tokio::test]
+    async fn rebuild_indexes_refuses_for_attached_and_unattached_alike() {
+        let mut provider = QdrantProvider {
+            client: Client::new(),
+            base_url: "http://localhost:6333".to_string(),
+            collection: "c".to_string(),
+            point_ids: Arc::default(),
+        };
+
+        let attached = RagData {
+            driver: "qdrant".to_string(),
+            attached: true,
+            ..Default::default()
+        };
+        let err = provider
+            .rebuild_indexes(&attached, true)
+            .await
+            .expect_err("an attached qdrant RAG must never report a successful rebuild");
+        assert!(err.to_string().contains("cannot rebuild"), "got: {err}");
+
+        // `attached: false` is reserved for the (unimplemented) write path. It must
+        // also refuse: silently succeeding would run a full paid embedding pass and
+        // then discard every vector.
+        let owned = RagData {
+            driver: "qdrant".to_string(),
+            attached: false,
+            ..Default::default()
+        };
+        let err = provider
+            .rebuild_indexes(&owned, true)
+            .await
+            .expect_err("writing to qdrant is unimplemented and must fail loudly");
+        assert!(err.to_string().contains("not supported yet"), "got: {err}");
+    }
+
+    #[tokio::test]
+    async fn fetch_content_short_circuits_on_an_empty_id_list() {
+        let provider = QdrantProvider {
+            client: Client::new(),
+            base_url: "http://127.0.0.1:1".to_string(),
+            collection: "c".to_string(),
+            point_ids: Arc::default(),
+        };
+
+        assert!(provider.fetch_content(&[]).await.unwrap().is_empty());
+    }
+
+    #[test]
+    fn local_and_private_hosts_skip_the_proxy() {
+        for host in [
+            "http://localhost:6333",
+            "http://127.0.0.1:6333",
+            "http://192.168.0.56:6333",
+            "http://10.1.2.3:6333",
+            "http://172.16.4.5:6333",
+            "http://qdrant.local:6333",
+            "http://[::1]:6333",
+        ] {
+            assert!(
+                QdrantProvider::skips_proxy(host),
+                "{host} should not be proxied"
+            );
+        }
+    }
+
+    #[test]
+    fn public_hosts_still_honour_the_environment() {
+        for host in [
+            "https://qdrant.example.com",
+            "http://8.8.8.8:6333",
+            "https://xyz.eu-central.aws.cloud.qdrant.io:6333",
+            "http://172.32.0.1:6333",
+        ] {
+            assert!(
+                !QdrantProvider::skips_proxy(host),
+                "{host} must keep the environment's proxy"
+            );
+        }
+    }
+
+    /// Euclid collections score by NEGATIVE distance, so the 0.0 the caller
+    /// passes must mean "no floor". Filtering on it drops every hit — the exact
+    /// bug that keeps Qdrant's own `score_threshold` off the wire.
+    #[test]
+    fn a_zero_floor_keeps_negative_euclid_scores() {
+        let mut interner = PointIdInterner::default();
+        let search = serde_json::json!({
+            "result": [
+                {"id": 1, "score": -0.12},
+                {"id": 2, "score": -8.5},
+            ]
+        });
+
+        let hits = parse_search_hits(&mut interner, &search, 0.0).unwrap();
+
+        assert_eq!(hits.len(), 2, "a 0.0 floor must not drop negative scores");
+    }
+
+    #[test]
+    fn a_positive_floor_still_filters() {
+        let mut interner = PointIdInterner::default();
+        let search = serde_json::json!({
+            "result": [
+                {"id": 1, "score": 0.9},
+                {"id": 2, "score": 0.2},
+            ]
+        });
+
+        let hits = parse_search_hits(&mut interner, &search, 0.5).unwrap();
+
+        assert_eq!(hits.len(), 1);
+        assert_eq!(hits[0].0, DocumentId(1));
+    }
+
+    /// A UUID-keyed collection has to survive the whole `vector_search` →
+    /// `fetch_content` round trip, and the fetch must ask Qdrant for the ORIGINAL
+    /// string id. Parsing ids with `as_u64()` used to drop these hits inside a
+    /// `filter_map`, i.e. zero results and no error.
+    #[test]
+    fn uuid_point_ids_round_trip_and_are_requested_verbatim() {
+        let mut interner = PointIdInterner::default();
+        let first_uuid = "3f1b0c2e-1111-4000-8000-000000000001";
+        let second_uuid = "3f1b0c2e-2222-4000-8000-000000000002";
+
+        let search = serde_json::json!({
+            "result": [
+                {"id": first_uuid, "score": 0.91},
+                {"id": second_uuid, "score": 0.42},
+            ]
+        });
+        let hits = parse_search_hits(&mut interner, &search, 0.0).unwrap();
+        assert_eq!(hits.len(), 2, "string ids must not be silently dropped");
+
+        let ids: Vec<DocumentId> = hits.iter().map(|(id, _)| *id).collect();
+        assert_eq!(
+            interner.outbound_ids(&ids),
+            vec![Value::from(first_uuid), Value::from(second_uuid)],
+            "the fetch must send the ids Qdrant issued, not the handles"
+        );
+
+        // Qdrant may answer /points in any order; the handles still map back and
+        // the caller's RRF ranking is recoverable.
+        let points = serde_json::json!({
+            "result": [
+                {"id": second_uuid, "payload": {"page_content": "second"}},
+                {"id": first_uuid, "payload": {"page_content": "first"}},
+            ]
+        });
+        let mut rows = parse_points(&mut interner, &points).unwrap();
+        let position: HashMap<DocumentId, usize> =
+            ids.iter().enumerate().map(|(i, id)| (*id, i)).collect();
+        rows.sort_by_key(|(id, _)| position.get(id).copied().unwrap_or(usize::MAX));
+        assert_eq!(
+            rows,
+            vec![
+                (ids[0], "first".to_string()),
+                (ids[1], "second".to_string())
+            ]
+        );
+    }
+
+    /// Integer-keyed collections must be untouched by the interner: the id maps to
+    /// itself on the way in and goes back out as the same integer.
+    #[test]
+    fn integer_point_ids_are_passed_through_untouched() {
+        let mut interner = PointIdInterner::default();
+        let search = serde_json::json!({
+            "result": [{"id": 7, "score": 0.9}, {"id": 0, "score": 0.5}]
+        });
+
+        let hits = parse_search_hits(&mut interner, &search, 0.0).unwrap();
+        assert_eq!(
+            hits,
+            vec![(DocumentId(7), 0.9_f32), (DocumentId(0), 0.5_f32)]
+        );
+
+        let ids: Vec<DocumentId> = hits.iter().map(|(id, _)| *id).collect();
+        assert_eq!(
+            interner.outbound_ids(&ids),
+            vec![Value::from(7_u64), Value::from(0_u64)],
+            "integer ids must not be regressed into synthetic handles"
+        );
+        assert!(
+            interner.raw_id(DocumentId(7)).is_none(),
+            "a plain integer id is its own id and needs no map entry"
+        );
+    }
+
+    /// Synthetic handles are stable per point id and live in a range no packed
+    /// `DocumentId` can reach.
+    #[test]
+    fn synthetic_handles_are_stable_and_never_collide_with_packed_ids() {
+        let mut interner = PointIdInterner::default();
+        let uuid = Value::from("9d2f0a11-3333-4000-8000-00000000000a");
+
+        let handle = interner.document_id(&uuid).unwrap();
+        assert_eq!(
+            interner.document_id(&uuid).unwrap(),
+            handle,
+            "the same point id must keep the same handle across queries"
+        );
+        assert_ne!(
+            interner.document_id(&Value::from("other")).unwrap(),
+            handle,
+            "distinct point ids must not share a handle"
+        );
+        assert_ne!(handle.0 & SYNTHETIC_ID_TAG, 0, "a handle carries the tag");
+
+        // A packed (file_index, document_index) never sets the tag bit: it is the
+        // top bit of the file index, which would take 2^31 indexed files.
+        for (file_index, document_index) in [(0, 0), (1, 0), (0, 4242), (1_000_000, 999)] {
+            assert_eq!(
+                DocumentId::new(file_index, document_index).0 & SYNTHETIC_ID_TAG,
+                0,
+                "packed ({file_index}, {document_index}) must stay out of the handle range"
+            );
+        }
+
+        // The one integer id that WOULD land on the tag is interned instead of
+        // being handed back as itself, so it cannot alias a handle.
+        let collides = Value::from(SYNTHETIC_ID_TAG as u64);
+        let interned = interner.document_id(&collides).unwrap();
+        assert_eq!(interner.raw_id(interned), Some(&collides));
+        assert_eq!(
+            interner.outbound_ids(&[interned]),
+            vec![collides],
+            "the original integer must still be what Qdrant is asked for"
+        );
+    }
+
+    /// `duplicate()` shares the map rather than resetting it: `Rag::clone()` hands
+    /// the clone `DocumentId`s the original minted, and a fresh map would turn
+    /// those into requests for a synthetic handle — zero results, no error.
+    #[test]
+    fn duplicate_shares_the_point_id_map() {
+        let provider = QdrantProvider {
+            client: Client::new(),
+            base_url: "http://127.0.0.1:1".to_string(),
+            collection: "c".to_string(),
+            point_ids: Arc::default(),
+        };
+        let uuid = Value::from("c0ffee00-4444-4000-8000-000000000007");
+        let handle = provider.point_ids.write().document_id(&uuid).unwrap();
+
+        let dup = provider.duplicate(&RagData {
+            driver: "qdrant".to_string(),
+            attached: true,
+            ..Default::default()
+        });
+        // Downcasting is not available through `dyn RagProvider`, so go via the
+        // shared Arc: the clone must observe the original's interning.
+        assert_eq!(Arc::strong_count(&provider.point_ids), 2);
+        assert_eq!(provider.point_ids.read().raw_id(handle), Some(&uuid));
+        drop(dup);
+    }
+
+    #[tokio::test]
+    #[ignore]
+    async fn qdrant_list_collections_requires_running_instance() {
+        let collections = QdrantProvider::list_collections("http://localhost:6333", None)
+            .await
+            .unwrap();
+
+        assert!(!collections.is_empty());
+    }
+
+    #[tokio::test]
+    #[ignore]
+    async fn qdrant_vector_search_returns_results() {
+        let provider = QdrantProvider::new("http://localhost:6333", "test-collection", None)
+            .await
+            .unwrap();
+        let embedding = vec![0.0f32; 1536];
+
+        let results = provider.vector_search(&embedding, 5, 0.0).await.unwrap();
+
+        assert!(results.len() <= 5);
+    }
+}

src/rag/providers/yaml.rs

@@ -0,0 +1,219 @@
+use crate::rag::provider::RagProvider;
+use crate::rag::{DocumentId, RagData};
+
+use anyhow::Result;
+use async_trait::async_trait;
+use hnsw_rs::prelude::*;
+use indexmap::IndexMap;
+
+pub struct YamlProvider {
+    hnsw: Hnsw<'static, f32, DistCosine>,
+    content_map: IndexMap<DocumentId, String>,
+}
+
+impl YamlProvider {
+    pub fn from_data(data: &RagData) -> Self {
+        Self {
+            hnsw: data.build_hnsw(),
+            content_map: Self::build_content_map(data),
+        }
+    }
+
+    fn build_content_map(data: &RagData) -> IndexMap<DocumentId, String> {
+        data.iter_documents()
+            .map(|(id, doc)| (id, doc.page_content.clone()))
+            .collect()
+    }
+}
+
+#[async_trait]
+impl RagProvider for YamlProvider {
+    async fn vector_search(
+        &self,
+        embedding: &[f32],
+        top_k: usize,
+        min_score: f32,
+    ) -> Result<Vec<(DocumentId, f32)>> {
+        let results = self
+            .hnsw
+            .parallel_search(&[embedding.to_vec()], top_k, 30)
+            .into_iter()
+            .flat_map(|list| {
+                list.into_iter().filter_map(|v| {
+                    let score = 1.0 - v.distance;
+                    if score > min_score {
+                        Some((DocumentId(v.d_id), score))
+                    } else {
+                        None
+                    }
+                })
+            })
+            .collect();
+
+        Ok(results)
+    }
+
+    async fn fetch_content(&self, ids: &[DocumentId]) -> Result<Vec<(DocumentId, String)>> {
+        Ok(ids
+            .iter()
+            .filter_map(|id| self.content_map.get(id).map(|text| (*id, text.clone())))
+            .collect())
+    }
+
+    async fn rebuild_indexes(&mut self, data: &RagData, _full_rebuild: bool) -> Result<()> {
+        self.hnsw = data.build_hnsw();
+
+        self.content_map = Self::build_content_map(data);
+
+        Ok(())
+    }
+
+    fn duplicate(&self, data: &RagData) -> Box<dyn RagProvider> {
+        Box::new(YamlProvider::from_data(data))
+    }
+}
+
+#[cfg(test)]
+mod provider_tests {
+    use super::*;
+    use crate::rag::{RagDocument, RagFile};
+
+    fn minimal_rag_data() -> RagData {
+        RagData {
+            embedding_model: "text-embedding-3-small".to_string(),
+            chunk_size: 1024,
+            chunk_overlap: 50,
+            top_k: 5,
+            driver: "yaml".to_string(),
+            attached: false,
+            ..Default::default()
+        }
+    }
+
+    /// Two files, one chunk each, with vectors, the minimum needed to exercise
+    /// `build_content_map` and the `fetch_content` ordering contract.
+    /// `DocumentId::new(f, d)` packs (file_index, document_index); `RagData::add`
+    /// is the real insertion path but a direct literal is sufficient and avoids
+    /// the embedding pipeline.
+    fn populated_rag_data() -> RagData {
+        let mut data = minimal_rag_data();
+        // `files` must be populated: build_content_map iterates data.iter_documents(),
+        // which enumerates `files`. Populating `vectors` alone would produce an EMPTY
+        // content map, and every assertion below would vacuously pass on a broken impl.
+        // The vectors inserted at the end are for the HNSW side only.
+        data.files.insert(
+            0,
+            RagFile {
+                hash: "h0".to_string(),
+                path: "/tmp/a.md".to_string(),
+                documents: vec![RagDocument {
+                    page_content: "alpha".to_string(),
+                    metadata: Default::default(),
+                }],
+            },
+        );
+        data.files.insert(
+            1,
+            RagFile {
+                hash: "h1".to_string(),
+                path: "/tmp/b.md".to_string(),
+                documents: vec![RagDocument {
+                    page_content: "beta".to_string(),
+                    metadata: Default::default(),
+                }],
+            },
+        );
+        data.vectors
+            .insert(DocumentId::new(0, 0), vec![1.0, 0.0, 0.0]);
+        data.vectors
+            .insert(DocumentId::new(1, 0), vec![0.0, 1.0, 0.0]);
+        data
+    }
+
+    #[tokio::test]
+    async fn yaml_provider_empty_data_returns_nothing() {
+        let data = minimal_rag_data();
+        let provider = YamlProvider::from_data(&data);
+
+        let results = provider.fetch_content(&[]).await.unwrap();
+
+        assert!(results.is_empty());
+    }
+
+    #[tokio::test]
+    async fn yaml_provider_fetch_content_preserves_input_order() {
+        let data = populated_rag_data();
+        let provider = YamlProvider::from_data(&data);
+
+        let a = DocumentId::new(0, 0);
+        let b = DocumentId::new(1, 0);
+
+        let forward = provider.fetch_content(&[a, b]).await.unwrap();
+        assert_eq!(forward.len(), 2, "both documents must resolve");
+        assert_eq!(forward[0].1, "alpha");
+        assert_eq!(forward[1].1, "beta");
+
+        let reversed = provider.fetch_content(&[b, a]).await.unwrap();
+
+        assert_eq!(
+            reversed[0].1, "beta",
+            "fetch_content must honor input order"
+        );
+        assert_eq!(reversed[1].1, "alpha");
+    }
+
+    #[tokio::test]
+    async fn yaml_provider_fetch_content_skips_missing_ids() {
+        let data = populated_rag_data();
+        let provider = YamlProvider::from_data(&data);
+
+        let a = DocumentId::new(0, 0);
+        let missing = DocumentId::new(99, 0);
+        let b = DocumentId::new(1, 0);
+
+        let out = provider.fetch_content(&[a, missing, b]).await.unwrap();
+        assert_eq!(out.len(), 2, "missing id is skipped, not an error");
+        assert_eq!(out[0].1, "alpha");
+        assert_eq!(out[1].1, "beta");
+    }
+
+    #[tokio::test]
+    async fn yaml_provider_duplicate_returns_equivalent_content() {
+        let data = populated_rag_data();
+        let provider = YamlProvider::from_data(&data);
+        let dup = provider.duplicate(&data);
+        let ids = [DocumentId::new(0, 0), DocumentId::new(1, 0)];
+
+        let r1 = provider.fetch_content(&ids).await.unwrap();
+        let r2 = dup.fetch_content(&ids).await.unwrap();
+
+        assert_eq!(r1.len(), 2, "fixture must resolve both documents");
+        assert_eq!(
+            r1, r2,
+            "duplicate must resolve the same content as the original"
+        );
+    }
+
+    #[tokio::test]
+    async fn yaml_provider_content_is_keyed_on_files_not_vectors() {
+        let mut data = populated_rag_data();
+        let orphan = DocumentId::new(9, 0);
+        data.vectors.insert(orphan, vec![0.0, 0.0, 1.0]);
+
+        let provider = YamlProvider::from_data(&data);
+
+        let out = provider.fetch_content(&[orphan]).await.unwrap();
+        assert!(
+            out.is_empty(),
+            "an id present only in `vectors` must not resolve to content"
+        );
+
+        let real = provider
+            .fetch_content(&[DocumentId::new(0, 0), DocumentId::new(1, 0)])
+            .await
+            .unwrap();
+        assert_eq!(real.len(), 2, "file-backed documents must still resolve");
+        assert_eq!(real[0].1, "alpha");
+        assert_eq!(real[1].1, "beta");
+    }
+}

src/render/markdown.rs

@@ -1749,6 +1749,86 @@ std::error::Error>> {
         );
     }
 
+    fn strip_ansi(text: &str) -> String {
+        let mut out = String::with_capacity(text.len());
+        let mut chars = text.chars();
+        while let Some(c) = chars.next() {
+            if c != '\u{1b}' {
+                out.push(c);
+                continue;
+            }
+            if chars.next() == Some('[') {
+                for c in chars.by_ref() {
+                    if ('\u{40}'..='\u{7e}').contains(&c) {
+                        break;
+                    }
+                }
+            }
+        }
+        out
+    }
+
+    #[test]
+    fn strip_ansi_removes_sgr_and_keeps_text() {
+        assert_eq!(strip_ansi("\x1b[1mbold\x1b[0m"), "bold");
+        assert_eq!(strip_ansi("\x1b[38;5;120mx\x1b[39m"), "x");
+        assert_eq!(strip_ansi("plain"), "plain");
+    }
+
+    #[test]
+    fn render_table_pads_columns_by_display_width() {
+        use unicode_width::UnicodeWidthStr;
+
+        const WRAP_WIDTH: u16 = 80;
+
+        let options = RenderOptions::default();
+        let mut render = MarkdownRender::init(options).unwrap();
+        render.wrap_width = Some(WRAP_WIDTH);
+
+        let header = vec![
+            "**Setting**".into(),
+            "*Default*".into(),
+            "`Description`".into(),
+        ];
+        let alignments = vec![
+            CellAlignment::Left,
+            CellAlignment::Right,
+            CellAlignment::Center,
+        ];
+        let rows = vec![
+            vec![
+                "**temperature**".into(),
+                "`0.7`".into(),
+                "Controls how *random* the sampled reply is allowed to be".into(),
+            ],
+            vec![
+                "**top_p**".into(),
+                "`1.0`".into(),
+                "Nucleus sampling cutoff, applied **after** temperature".into(),
+            ],
+        ];
+
+        let output = render.render_table(header, alignments, rows);
+
+        assert!(
+            output.contains('\u{1b}'),
+            "fixture must actually contain ANSI escapes: {output:?}",
+        );
+
+        let widths: Vec<usize> = output
+            .lines()
+            .map(|line| strip_ansi(line).width())
+            .collect();
+        assert!(!widths.is_empty(), "table rendered no lines");
+
+        for (index, width) in widths.iter().enumerate() {
+            assert_eq!(
+                *width, WRAP_WIDTH as usize,
+                "line {index} display width; all widths were {widths:?} in output:\n{output}",
+            );
+        }
+    }
+
     #[test]
     fn state_machine_renders_full_table_and_flushes_on_paragraph() {
         let options = RenderOptions::default();

src/repl/mod.rs

@@ -7,7 +7,10 @@ use self::completer::ReplCompleter;
 use self::highlighter::ReplHighlighter;
 use self::prompt::ReplPrompt;
 
-use crate::client::{call_chat_completions, call_chat_completions_streaming, init_client, oauth};
+use crate::client::{
+    Message, MessageRole, call_chat_completions, call_chat_completions_streaming, init_client,
+    oauth,
+};
 use crate::config::{
     AgentVariables, AppConfig, AssertState, Input, LastMessage, RequestContext, StateFlags,
     macro_execute,
@@ -50,7 +53,7 @@ pub const DEFAULT_CONTINUATION_PROMPT: &str = indoc! {"
     4. Continue with the next pending item now. Call tools immediately."
 };
 
-static REPL_COMMANDS: LazyLock<[ReplCommand; 58]> = LazyLock::new(|| {
+static REPL_COMMANDS: LazyLock<[ReplCommand; 60]> = LazyLock::new(|| {
     [
         ReplCommand::new(".help", "Show this help guide", AssertState::pass()),
         ReplCommand::new(".info", "Show system info", AssertState::pass()),
@@ -214,6 +217,11 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 58]> = LazyLock::new(|| {
             "Initialize or access RAG",
             AssertState::False(StateFlags::AGENT),
         ),
+        ReplCommand::new(
+            ".rag attach",
+            "Attach to a pre-existing external RAG",
+            AssertState::False(StateFlags::AGENT),
+        ),
         ReplCommand::new(
             ".edit rag-docs",
             "Add or remove documents from an existing RAG",
@@ -275,6 +283,11 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 58]> = LazyLock::new(|| {
             "Continue previous response",
             AssertState::pass(),
         ),
+        ReplCommand::new(
+            ".recover",
+            "Recover interrupted session after API error or Ctrl+C",
+            AssertState::True(StateFlags::SESSION_EMPTY | StateFlags::SESSION),
+        ),
         ReplCommand::new(
             ".regenerate",
             "Regenerate last response",
@@ -370,6 +383,31 @@ Type ".help" for additional help.
             if !compressed.is_empty() || !active.is_empty() {
                 let app = Arc::clone(&self.ctx.read().app.config);
                 replay::render(app.as_ref(), &compressed, &active)?;
+                let last_msgs: &[Message] = if !active.is_empty() {
+                    &active
+                } else {
+                    &compressed
+                };
+                let assistant_text = last_msgs
+                    .iter()
+                    .rev()
+                    .find(|m| m.role == MessageRole::Assistant)
+                    .and_then(|m| m.content.as_text())
+                    .map(str::to_string);
+                if let Some(output) = assistant_text {
+                    let user_text = last_msgs
+                        .iter()
+                        .rev()
+                        .find(|m| m.role == MessageRole::User)
+                        .and_then(|m| m.content.as_text())
+                        .unwrap_or("")
+                        .to_string();
+                    let ctx = self.ctx.read();
+                    if let Ok(input) = Input::from_str(&ctx, &user_text, None) {
+                        drop(ctx);
+                        self.ctx.write().last_message = Some(LastMessage::new(input, output));
+                    }
+                }
             }
         }
 
@@ -851,9 +889,17 @@ pub async fn run_repl_command(
                 let version = args.map(|s| s.trim().to_string());
                 task::spawn_blocking(move || config::run_self_update(version, false)).await??;
             }
-            ".rag" => {
-                ctx.use_rag(args, abort_signal.clone()).await?;
-            }
+            ".rag" => match split_first_arg(args) {
+                Some(("attach", rest)) => match rest {
+                    Some(name) if !name.trim().is_empty() => {
+                        ctx.attach_rag(name.trim(), abort_signal.clone()).await?;
+                    }
+                    _ => println!("Usage: .rag attach <name>"),
+                },
+                _ => {
+                    ctx.use_rag(args, abort_signal.clone()).await?;
+                }
+            },
             ".agent" => match split_first_arg(args) {
                 Some((agent_name, args)) => {
                     let (new_args, _) = split_args_text(args.unwrap_or_default(), cfg!(windows));
@@ -1073,6 +1119,21 @@ pub async fn run_repl_command(
                 input.set_continue_output(&output);
                 ask(ctx, abort_signal.clone(), input, true).await?;
             }
+            ".recover" => {
+                let has_recoverable = ctx
+                    .last_message
+                    .as_ref()
+                    .map(|v| v.continuous && v.input.with_session())
+                    .unwrap_or(false);
+                if !has_recoverable {
+                    bail!("Unable to recover: no interrupted session response to recover from");
+                }
+                let recovery_text = args
+                    .unwrap_or("Please continue from where you left off.")
+                    .to_string();
+                let recovery_input = Input::from_str(ctx, &recovery_text, None)?;
+                ask(ctx, abort_signal.clone(), recovery_input, false).await?;
+            }
             ".regenerate" => {
                 let LastMessage { mut input, .. } =
                     match ctx.last_message.as_ref().filter(|v| v.continuous).cloned() {
@@ -1119,16 +1180,28 @@ pub async fn run_repl_command(
                 }
             },
             ".copy" => {
-                let output = match ctx
+                let output = ctx
                     .last_message
                     .as_ref()
                     .filter(|v| !v.output.is_empty())
                     .map(|v| v.output.clone())
-                {
-                    Some(v) => v,
-                    None => bail!("No chat response to copy"),
-                };
-                set_text(&output).context("Failed to copy the last chat response")?;
+                    .or_else(|| {
+                        ctx.session.as_ref().and_then(|s| {
+                            s.messages()
+                                .iter()
+                                .rev()
+                                .chain(s.compressed_messages().iter().rev())
+                                .find(|m| m.role == MessageRole::Assistant)
+                                .and_then(|m| m.content.as_text())
+                                .map(str::to_string)
+                        })
+                    });
+                match output {
+                    Some(v) if !v.is_empty() => {
+                        set_text(&v).context("Failed to copy the last chat response")?;
+                    }
+                    _ => bail!("No chat response to copy"),
+                }
             }
             ".exit" => match args {
                 Some("role") => {
@@ -1267,18 +1340,28 @@ async fn ask(
 
     let client = input.create_client()?;
     ctx.before_chat_completion(&input)?;
-    let (output, tool_results) = if input.stream() {
-        call_chat_completions_streaming(&input, client.as_ref(), ctx, abort_signal.clone()).await?
-    } else {
-        call_chat_completions(
-            &input,
-            true,
-            false,
-            client.as_ref(),
-            ctx,
-            abort_signal.clone(),
-        )
-        .await?
+    let (output, tool_results) = {
+        let result = if input.stream() {
+            call_chat_completions_streaming(&input, client.as_ref(), ctx, abort_signal.clone())
+                .await
+        } else {
+            call_chat_completions(
+                &input,
+                true,
+                false,
+                client.as_ref(),
+                ctx,
+                abort_signal.clone(),
+            )
+            .await
+        };
+        match result {
+            Ok(v) => v,
+            Err(err) => {
+                ctx.on_chat_completion_error(app.as_ref(), &input);
+                return Err(err);
+            }
+        }
     };
     ctx.after_chat_completion(app.as_ref(), &input, &output, &tool_results)?;
     if !tool_results.is_empty() {
@@ -1304,7 +1387,7 @@ async fn ask(
             }
             GuardrailAction::NoAction => {}
         }
-        let do_continue = should_continue(ctx);
+        let do_continue = should_continue(ctx) && !abort_signal.aborted_ctrlc();
 
         if do_continue {
             let full_prompt = {
@@ -1360,7 +1443,8 @@ async fn ask(
                 .is_some_and(|s| s.needs_compression(app.compression_threshold));
 
             if needs_compression {
-                let agent_can_continue_after_compress = should_continue(ctx);
+                let agent_can_continue_after_compress =
+                    should_continue(ctx) && !abort_signal.aborted_ctrlc();
 
                 if let Some(session) = ctx.session.as_mut() {
                     session.set_compressing(true);
@@ -1640,8 +1724,8 @@ mod tests {
     }
 
     #[test]
-    fn repl_commands_has_58_entries() {
-        assert_eq!(REPL_COMMANDS.len(), 58);
+    fn repl_commands_has_60_entries() {
+        assert_eq!(REPL_COMMANDS.len(), 60);
     }
 
     #[test]

src/repl/replay.rs

@@ -2,7 +2,7 @@ use anyhow::Result;
 
 use crate::client::{Message, MessageRole};
 use crate::config::{AppConfig, Session};
-use crate::utils::dimmed_text;
+use crate::utils::{dimmed_text, replay_label_text};
 
 pub fn snapshot(session: &Session) -> (Vec<Message>, Vec<Message>) {
     (
@@ -40,13 +40,14 @@ fn render_messages(app: &AppConfig, messages: &[Message]) -> Result<()> {
         match message.role {
             MessageRole::User => {
                 if let Some(text) = message.content.as_text() {
-                    println!("{}", dimmed_text("You:"));
+                    println!("{}", replay_label_text("You:"));
                     println!("{text}");
                     println!();
                 }
             }
             MessageRole::Assistant => {
                 if let Some(text) = message.content.as_text() {
+                    println!("{}", replay_label_text("Assistant:"));
                     app.print_markdown(text)?;
                     println!();
                 }

src/sandbox/mixins.rs

@@ -1,16 +1,19 @@
 use std::env;
 use std::fs;
 use std::fs::{read_dir, read_to_string};
+use std::io;
 use std::path::{Path, PathBuf};
 
-use anyhow::{Context, Result};
+use anyhow::{Context, Result, anyhow, bail};
 use serde_yaml::Value;
 use sha2::{Digest, Sha256};
 
 use crate::config::paths;
 
 const SBX_MIXIN_FILE_NAME: &str = "sbx-mixin.yaml";
+const SBX_MIXIN_FILE_SUFFIX: &str = ".sbx-mixin.yaml";
 const KIT_SPEC_FILE_NAME: &str = "spec.yaml";
+const MIXIN_FILES_DIR_NAME: &str = "files";
 
 #[derive(Debug, Clone)]
 pub struct DiscoveredMixin {
@@ -33,43 +36,168 @@ impl DiscoveredMixin {
 pub fn wrap_mixin_as_kit(mixin_path: &Path) -> Result<PathBuf> {
     let bytes = fs::read(mixin_path)
         .with_context(|| format!("Failed to read sbx mixin {}", mixin_path.display()))?;
+    let label = mixin_path.display().to_string();
+
+    let files = mixin_path
+        .parent()
+        .map(|p| p.join(MIXIN_FILES_DIR_NAME))
+        .filter(|p| p.is_dir())
+        .map(|dir| collect_staged_files(&dir))
+        .transpose()?
+        .unwrap_or_default();
+
+    stage_kit(&bytes, &files, &label)
+}
+
+pub fn wrap_mixin_bytes_as_kit(bytes: &[u8], label: &str) -> Result<PathBuf> {
+    stage_kit(bytes, &[], label)
+}
+
+struct StagedFile {
+    relpath: PathBuf,
+    mode: u32,
+    bytes: Vec<u8>,
+}
+
+fn stage_kit(spec_bytes: &[u8], files: &[StagedFile], label: &str) -> Result<PathBuf> {
     let mut hasher = Sha256::new();
-    hasher.update(&bytes);
+    hasher.update(spec_bytes);
+    for f in files {
+        let rel_str = f.relpath.to_str().ok_or_else(|| {
+            anyhow!(
+                "Non-UTF-8 path inside mixin {MIXIN_FILES_DIR_NAME}/: {}",
+                f.relpath.display()
+            )
+        })?;
+        hasher.update(b"\0COYOTE_MIXIN_FILE\0");
+        hasher.update((rel_str.len() as u64).to_le_bytes());
+        hasher.update(rel_str.as_bytes());
+        hasher.update(f.mode.to_le_bytes());
+        hasher.update((f.bytes.len() as u64).to_le_bytes());
+        hasher.update(&f.bytes);
+    }
     let hash = format!("{:x}", hasher.finalize());
 
     let kit_dir = paths::sbx_mixin_kits_dir().join(&hash);
     let spec_path = kit_dir.join(KIT_SPEC_FILE_NAME);
+    let files_dst = kit_dir.join(MIXIN_FILES_DIR_NAME);
 
-    if let Ok(existing) = fs::read(&spec_path)
-        && existing == bytes
-    {
+    let spec_matches = fs::read(&spec_path).is_ok_and(|existing| existing == spec_bytes);
+    let files_ready = files.is_empty() || files_dst.is_dir();
+    if spec_matches && files_ready {
         return Ok(kit_dir);
     }
 
     fs::create_dir_all(&kit_dir)
         .with_context(|| format!("Failed to create mixin kit dir {}", kit_dir.display()))?;
-    fs::write(&spec_path, &bytes)
+    fs::write(&spec_path, spec_bytes)
         .with_context(|| format!("Failed to write {}", spec_path.display()))?;
 
-    debug!(
-        "Wrapped mixin {} as kit at {}",
-        mixin_path.display(),
-        kit_dir.display()
-    );
+    if !files.is_empty() {
+        if files_dst.exists() {
+            fs::remove_dir_all(&files_dst).with_context(|| {
+                format!(
+                    "Failed to clear stale mixin files at {}",
+                    files_dst.display()
+                )
+            })?;
+        }
+        for f in files {
+            let dst = files_dst.join(&f.relpath);
+            if let Some(parent) = dst.parent() {
+                fs::create_dir_all(parent)
+                    .with_context(|| format!("Failed to create dir {}", parent.display()))?;
+            }
+            fs::write(&dst, &f.bytes)
+                .with_context(|| format!("Failed to write staged mixin file {}", dst.display()))?;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                fs::set_permissions(&dst, fs::Permissions::from_mode(f.mode))
+                    .with_context(|| format!("Failed to set mode on {}", dst.display()))?;
+            }
+        }
+    }
+
+    debug!("Wrapped mixin {label} as kit at {}", kit_dir.display());
 
     Ok(kit_dir)
 }
 
+fn collect_staged_files(root: &Path) -> Result<Vec<StagedFile>> {
+    let mut out = Vec::new();
+    walk_staged_files(root, Path::new(""), &mut out)?;
+    Ok(out)
+}
+
+fn walk_staged_files(abs_dir: &Path, rel_dir: &Path, out: &mut Vec<StagedFile>) -> Result<()> {
+    let rd = fs::read_dir(abs_dir)
+        .with_context(|| format!("Failed to read mixin files dir {}", abs_dir.display()))?;
+    let mut entries: Vec<_> = rd
+        .collect::<io::Result<Vec<_>>>()
+        .with_context(|| format!("Failed to iterate mixin files dir {}", abs_dir.display()))?;
+    entries.sort_by_key(|e| e.file_name());
+
+    for entry in entries {
+        let file_type = entry
+            .file_type()
+            .with_context(|| format!("Failed to stat {}", entry.path().display()))?;
+        let abs = entry.path();
+        let rel = rel_dir.join(entry.file_name());
+
+        if file_type.is_symlink() {
+            bail!(
+                "Symlinks are not allowed inside a mixin {MIXIN_FILES_DIR_NAME}/ tree: {}",
+                abs.display()
+            );
+        }
+
+        if file_type.is_dir() {
+            walk_staged_files(&abs, &rel, out)?;
+        } else if file_type.is_file() {
+            let bytes = fs::read(&abs)
+                .with_context(|| format!("Failed to read staged mixin file {}", abs.display()))?;
+            let mode = staged_file_mode(&entry)?;
+            out.push(StagedFile {
+                relpath: rel,
+                mode,
+                bytes,
+            });
+        }
+    }
+    Ok(())
+}
+
+#[cfg(unix)]
+fn staged_file_mode(entry: &fs::DirEntry) -> Result<u32> {
+    use std::os::unix::fs::PermissionsExt;
+    let meta = entry
+        .metadata()
+        .with_context(|| format!("Failed to stat {}", entry.path().display()))?;
+    Ok(meta.permissions().mode() & 0o777)
+}
+
+#[cfg(not(unix))]
+fn staged_file_mode(_entry: &fs::DirEntry) -> Result<u32> {
+    Ok(0o644)
+}
+
 pub fn discover() -> Result<Vec<DiscoveredMixin>> {
     let mut out = Vec::new();
 
     push_if_exists(&mut out, paths::sbx_mixin_file())?;
     push_if_exists(&mut out, paths::global_tools_sbx_mixin_file())?;
 
-    for path in collect_subdir_mixins(&paths::functions_dir()) {
+    for path in collect_mixins(&paths::functions_dir(), &[ScanMode::SubdirNamed]) {
         out.push(read_mixin(path)?);
     }
-    for path in collect_subdir_mixins(&paths::agents_data_dir()) {
+    for path in collect_mixins(
+        &paths::agents_data_dir(),
+        &[ScanMode::SubdirNamed, ScanMode::SubdirFlat],
+    ) {
+        out.push(read_mixin(path)?);
+    }
+    for path in collect_mixins(&paths::rags_dir(), &[ScanMode::Flat]) {
         out.push(read_mixin(path)?);
     }
 
@@ -89,15 +217,18 @@ pub fn summarize(path: &Path) -> Result<(usize, usize)> {
         .with_context(|| format!("Failed to parse sbx mixin {}", path.display()))?;
 
     let installs = value
-        .get("commands")
-        .and_then(|c| c.get("install"))
+        .get("setup")
+        .and_then(|s| s.get("install"))
+        .or_else(|| value.get("commands").and_then(|c| c.get("install")))
         .and_then(|i| i.as_sequence())
         .map(|s| s.len())
         .unwrap_or(0);
 
     let domains = value
-        .get("network")
-        .and_then(|n| n.get("allowedDomains"))
+        .get("permissions")
+        .and_then(|p| p.get("network"))
+        .and_then(|n| n.get("allow"))
+        .or_else(|| value.get("network").and_then(|n| n.get("allowedDomains")))
         .and_then(|d| d.as_sequence())
         .map(|s| s.len())
         .unwrap_or(0);
@@ -153,7 +284,73 @@ fn read_mixin(path: PathBuf) -> Result<DiscoveredMixin> {
     })
 }
 
-fn collect_subdir_mixins(dir: &Path) -> Vec<PathBuf> {
+/// One on-disk layout a mixin scan can look for. A scan takes a set of these,
+/// and each mode contributes only the shape it names.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ScanMode {
+    /// `<dir>/*.sbx-mixin.yaml`
+    Flat,
+    /// `<dir>/*/sbx-mixin.yaml`
+    SubdirNamed,
+    /// `<dir>/*/*.sbx-mixin.yaml`
+    SubdirFlat,
+}
+
+/// Collects mixin paths under `dir` for every requested layout. Missing or
+/// unreadable directories yield nothing rather than an error — these paths are
+/// all optional on disk.
+///
+/// Order is deterministic: flat matches first (sorted by file name), then each
+/// subdirectory in sorted order, contributing its named mixin before its
+/// suffixed ones.
+fn collect_mixins(dir: &Path, modes: &[ScanMode]) -> Vec<PathBuf> {
+    let mut result = Vec::new();
+
+    if modes.contains(&ScanMode::Flat) {
+        result.extend(suffixed_mixins_in(dir));
+    }
+
+    let named = modes.contains(&ScanMode::SubdirNamed);
+    let subdir_flat = modes.contains(&ScanMode::SubdirFlat);
+    if !named && !subdir_flat {
+        return result;
+    }
+
+    for subdir in subdirs_of(dir) {
+        if named {
+            let candidate = subdir.join(SBX_MIXIN_FILE_NAME);
+            if candidate.exists() {
+                result.push(candidate);
+            }
+        }
+        if subdir_flat {
+            result.extend(suffixed_mixins_in(&subdir));
+        }
+    }
+
+    result
+}
+
+fn suffixed_mixins_in(dir: &Path) -> Vec<PathBuf> {
+    let mut result = Vec::new();
+    let Ok(rd) = read_dir(dir) else { return result };
+
+    let mut entries: Vec<_> = rd
+        .flatten()
+        .filter(|e| e.file_type().map(|t| t.is_file()).unwrap_or(false))
+        .filter(|e| {
+            e.file_name()
+                .to_str()
+                .is_some_and(|n| n.ends_with(SBX_MIXIN_FILE_SUFFIX))
+        })
+        .collect();
+    entries.sort_by_key(|e| e.file_name());
+
+    result.extend(entries.into_iter().map(|e| e.path()));
+    result
+}
+
+fn subdirs_of(dir: &Path) -> Vec<PathBuf> {
     let mut result = Vec::new();
     let Ok(rd) = read_dir(dir) else { return result };
 
@@ -163,13 +360,7 @@ fn collect_subdir_mixins(dir: &Path) -> Vec<PathBuf> {
         .collect();
     entries.sort_by_key(|e| e.file_name());
 
-    for entry in entries {
-        let candidate = entry.path().join(SBX_MIXIN_FILE_NAME);
-        if candidate.exists() {
-            result.push(candidate);
-        }
-    }
-
+    result.extend(entries.into_iter().map(|e| e.path()));
     result
 }
 
@@ -189,6 +380,13 @@ mod tests {
         root
     }
 
+    fn file_names(paths: &[PathBuf]) -> Vec<&str> {
+        paths
+            .iter()
+            .map(|p| p.file_name().unwrap().to_str().unwrap())
+            .collect()
+    }
+
     #[test]
     fn summarize_counts_installs_and_domains() {
         let root = unique_root("sbx-mixin-counts");
@@ -196,6 +394,34 @@ mod tests {
         fs::write(
             &path,
             r#"
+schemaVersion: "2"
+kind: mixin
+setup:
+  install:
+    - command: "echo hi"
+    - command: "echo bye"
+permissions:
+  network:
+    allow:
+      - "a.example.com:443"
+      - "b.example.com:443"
+      - "c.example.com:443"
+"#,
+        )
+        .unwrap();
+
+        assert_eq!(summarize(&path).unwrap(), (2, 3));
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn summarize_falls_back_to_v1_field_paths() {
+        let root = unique_root("sbx-mixin-counts-v1");
+        let path = root.join("sbx-mixin.yaml");
+        fs::write(
+            &path,
+            r#"
 schemaVersion: "1"
 kind: mixin
 commands:
@@ -244,7 +470,7 @@ network:
     }
 
     #[test]
-    fn collect_subdir_mixins_sorts_and_skips_missing() {
+    fn subdir_named_scan_sorts_and_skips_missing() {
         let root = unique_root("sbx-mixin-subdirs");
         for name in ["zebra", "apple", "no-mixin", "mango"] {
             let dir = root.join(name);
@@ -254,7 +480,7 @@ network:
             }
         }
 
-        let found = collect_subdir_mixins(&root);
+        let found = collect_mixins(&root, &[ScanMode::SubdirNamed]);
         let names: Vec<String> = found
             .iter()
             .map(|p| {
@@ -272,9 +498,9 @@ network:
     }
 
     #[test]
-    fn collect_subdir_mixins_returns_empty_for_missing_dir() {
+    fn subdir_named_scan_returns_empty_for_missing_dir() {
         let absent = env::temp_dir().join("coyote-definitely-not-here-xyz");
-        let found = collect_subdir_mixins(&absent);
+        let found = collect_mixins(&absent, &[ScanMode::SubdirNamed]);
         assert!(found.is_empty());
     }
 
@@ -343,6 +569,19 @@ network:
             assert_eq!(fs::read_to_string(&spec).unwrap(), content);
         }
 
+        #[test]
+        #[serial]
+        fn wrap_mixin_bytes_as_kit_writes_spec_yaml() {
+            let _guard = TestCacheDirGuard::new();
+            let content = b"schemaVersion: '2'\nkind: mixin\nname: generated\n";
+
+            let kit_dir = wrap_mixin_bytes_as_kit(content, "generated").unwrap();
+            let spec = kit_dir.join("spec.yaml");
+
+            assert!(spec.exists(), "spec.yaml must exist in wrapped kit dir");
+            assert_eq!(fs::read(&spec).unwrap(), content);
+        }
+
         #[test]
         #[serial]
         fn wrap_mixin_as_kit_is_deterministic_for_identical_content() {
@@ -438,5 +677,317 @@ network:
                 "kit_path should not return the original file path"
             );
         }
+
+        fn write_staged_file(mixin: &Path, rel: &str, content: &[u8]) {
+            let dst = mixin.parent().unwrap().join(MIXIN_FILES_DIR_NAME).join(rel);
+            fs::create_dir_all(dst.parent().unwrap()).unwrap();
+            fs::write(&dst, content).unwrap();
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_copies_sibling_files_tree_into_kit() {
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-copy", "kind: mixin\nname: probe\n");
+            write_staged_file(&mixin, "home/hello.md", b"# hello\n");
+            write_staged_file(&mixin, "home/nested/deep.txt", b"deep\n");
+
+            let kit_dir = wrap_mixin_as_kit(&mixin).unwrap();
+
+            assert!(kit_dir.join("spec.yaml").exists());
+            let files_root = kit_dir.join(MIXIN_FILES_DIR_NAME);
+            assert!(files_root.is_dir(), "kit dir must contain a files/ tree");
+            assert_eq!(
+                fs::read(files_root.join("home/hello.md")).unwrap(),
+                b"# hello\n"
+            );
+            assert_eq!(
+                fs::read(files_root.join("home/nested/deep.txt")).unwrap(),
+                b"deep\n"
+            );
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_hash_changes_when_a_staged_file_is_edited() {
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-hash-content", "kind: mixin\nname: probe\n");
+            write_staged_file(&mixin, "home/note.md", b"before\n");
+            let kit_before = wrap_mixin_as_kit(&mixin).unwrap();
+
+            write_staged_file(&mixin, "home/note.md", b"after\n");
+            let kit_after = wrap_mixin_as_kit(&mixin).unwrap();
+
+            assert_ne!(
+                kit_before, kit_after,
+                "editing a staged file must invalidate the kit hash"
+            );
+            assert_eq!(
+                fs::read(kit_after.join("files/home/note.md")).unwrap(),
+                b"after\n"
+            );
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_hash_changes_when_a_staged_file_is_added() {
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-hash-added", "kind: mixin\nname: probe\n");
+            write_staged_file(&mixin, "home/one.md", b"one\n");
+            let kit_before = wrap_mixin_as_kit(&mixin).unwrap();
+
+            write_staged_file(&mixin, "home/two.md", b"two\n");
+            let kit_after = wrap_mixin_as_kit(&mixin).unwrap();
+
+            assert_ne!(
+                kit_before, kit_after,
+                "adding a staged file must invalidate the kit hash"
+            );
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_hash_unchanged_when_no_files_dir() {
+            let _guard = TestCacheDirGuard::new();
+            let content = "kind: mixin\nname: legacy\n";
+            let mixin = write_mixin("legacy-no-files", content);
+
+            let with_helper = wrap_mixin_as_kit(&mixin).unwrap();
+            let bytes_only = wrap_mixin_bytes_as_kit(content.as_bytes(), "legacy").unwrap();
+
+            assert_eq!(
+                with_helper, bytes_only,
+                "mixins without a sibling files/ must keep the legacy bytes-only hash to reuse existing cache dirs"
+            );
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_ignores_sibling_files_that_is_not_a_directory() {
+            let _guard = TestCacheDirGuard::new();
+            let content = "kind: mixin\nname: probe\n";
+            let mixin = write_mixin("files-not-a-dir", content);
+            fs::write(mixin.parent().unwrap().join(MIXIN_FILES_DIR_NAME), b"decoy").unwrap();
+
+            let wrapped = wrap_mixin_as_kit(&mixin).unwrap();
+            let bytes_only = wrap_mixin_bytes_as_kit(content.as_bytes(), "probe").unwrap();
+
+            assert_eq!(
+                wrapped, bytes_only,
+                "a regular file named files must be ignored, not staged"
+            );
+            assert!(!wrapped.join(MIXIN_FILES_DIR_NAME).exists());
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_rebuilds_files_when_cache_dir_missing_files_tree() {
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-rebuild", "kind: mixin\nname: probe\n");
+            write_staged_file(&mixin, "home/hello.md", b"hi\n");
+
+            let kit_dir = wrap_mixin_as_kit(&mixin).unwrap();
+            let files_dst = kit_dir.join(MIXIN_FILES_DIR_NAME);
+            fs::remove_dir_all(&files_dst).unwrap();
+            assert!(!files_dst.exists());
+
+            let kit_again = wrap_mixin_as_kit(&mixin).unwrap();
+
+            assert_eq!(kit_again, kit_dir, "kit path is content-addressed");
+            assert!(
+                files_dst.is_dir(),
+                "a partial cache (spec present, files/ missing) must be rebuilt"
+            );
+            assert_eq!(fs::read(files_dst.join("home/hello.md")).unwrap(), b"hi\n");
+        }
+
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_deterministic_with_staged_files() {
+            let _guard = TestCacheDirGuard::new();
+            let content = "kind: mixin\nname: probe\n";
+            let mixin_one = write_mixin("determ-1", content);
+            write_staged_file(&mixin_one, "home/note.md", b"same\n");
+            let mixin_two = write_mixin("determ-2", content);
+            write_staged_file(&mixin_two, "home/note.md", b"same\n");
+
+            let kit_a = wrap_mixin_as_kit(&mixin_one).unwrap();
+            let kit_b = wrap_mixin_as_kit(&mixin_two).unwrap();
+
+            assert_eq!(
+                kit_a, kit_b,
+                "identical spec+files must produce the same content-addressed kit dir"
+            );
+        }
+
+        #[cfg(unix)]
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_rejects_symlinks_inside_files_tree() {
+            use std::os::unix::fs::symlink;
+
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-symlink", "kind: mixin\nname: probe\n");
+            let files_dir = mixin.parent().unwrap().join(MIXIN_FILES_DIR_NAME);
+            fs::create_dir_all(&files_dir).unwrap();
+            let target = files_dir.join("target.txt");
+            fs::write(&target, b"real").unwrap();
+            symlink(&target, files_dir.join("link.txt")).unwrap();
+
+            let err = wrap_mixin_as_kit(&mixin).unwrap_err();
+            let msg = format!("{err:#}");
+            assert!(
+                msg.contains("Symlinks are not allowed"),
+                "expected symlink rejection, got: {msg}"
+            );
+        }
+
+        #[cfg(unix)]
+        #[test]
+        #[serial]
+        fn wrap_mixin_as_kit_preserves_executable_bit() {
+            use std::os::unix::fs::PermissionsExt;
+
+            let _guard = TestCacheDirGuard::new();
+            let mixin = write_mixin("files-exec", "kind: mixin\nname: probe\n");
+            write_staged_file(&mixin, "bin/run.sh", b"#!/bin/sh\necho hi\n");
+            let src = mixin
+                .parent()
+                .unwrap()
+                .join(MIXIN_FILES_DIR_NAME)
+                .join("bin/run.sh");
+            fs::set_permissions(&src, fs::Permissions::from_mode(0o755)).unwrap();
+
+            let kit_dir = wrap_mixin_as_kit(&mixin).unwrap();
+            let dst = kit_dir.join("files/bin/run.sh");
+            let mode = fs::metadata(&dst).unwrap().permissions().mode() & 0o777;
+
+            assert_eq!(
+                mode, 0o755,
+                "executable bit must survive the copy into the kit dir"
+            );
+        }
+    }
+
+    #[test]
+    fn flat_scan_matches_rag_sidecars_by_suffix() {
+        let root = unique_root("flat-mixins");
+        fs::write(root.join("company-docs.sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+        fs::write(root.join("alpha.sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+        fs::write(root.join("company-docs.yaml"), "driver: qdrant\n").unwrap();
+        fs::write(root.join("notes.yaml"), "driver: yaml\n").unwrap();
+        fs::create_dir_all(root.join("decoy.sbx-mixin.yaml")).unwrap();
+
+        let found = collect_mixins(&root, &[ScanMode::Flat]);
+        assert_eq!(
+            file_names(&found),
+            vec!["alpha.sbx-mixin.yaml", "company-docs.sbx-mixin.yaml"]
+        );
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    /// Every scan site in `discover()` picks its modes assuming each mode owns
+    /// exactly one layout and nothing else. `agents_data_dir()` requests two
+    /// modes at once, so an overlap would collect the same file twice and
+    /// `create_sandbox` would pass it as two `--kit` flags.
+    #[test]
+    fn each_scan_mode_owns_exactly_one_layout() {
+        let root = unique_root("scan-mode-ownership");
+        let agent = root.join("researcher");
+        fs::create_dir_all(&agent).unwrap();
+        let flat = root.join("company-docs.sbx-mixin.yaml");
+        let subdir_named = agent.join("sbx-mixin.yaml");
+        let subdir_flat = agent.join("handbook.sbx-mixin.yaml");
+        for path in [&flat, &subdir_named, &subdir_flat] {
+            fs::write(path, "kind: mixin\n").unwrap();
+        }
+
+        assert_eq!(collect_mixins(&root, &[ScanMode::Flat]), vec![flat.clone()]);
+        assert_eq!(
+            collect_mixins(&root, &[ScanMode::SubdirNamed]),
+            vec![subdir_named.clone()]
+        );
+        assert_eq!(
+            collect_mixins(&root, &[ScanMode::SubdirFlat]),
+            vec![subdir_flat.clone()]
+        );
+
+        let all = collect_mixins(
+            &root,
+            &[ScanMode::Flat, ScanMode::SubdirNamed, ScanMode::SubdirFlat],
+        );
+        assert_eq!(all, vec![flat, subdir_named, subdir_flat]);
+
+        let mut deduped = all.clone();
+        deduped.sort();
+        deduped.dedup();
+        assert_eq!(
+            deduped.len(),
+            all.len(),
+            "no mixin may be collected twice: {all:?}"
+        );
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn flat_scan_tolerates_a_missing_directory() {
+        let root = unique_root("flat-missing");
+        let absent = root.join("nope");
+        assert!(collect_mixins(&absent, &[ScanMode::Flat]).is_empty());
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    /// `generate_rag_sbx_mixin` writes an agent-scoped RAG sidecar next to the
+    /// rag yaml, at `<agents>/<agent>/<rag>.sbx-mixin.yaml`. Before `SubdirFlat`
+    /// existed, nothing scanned that shape and attaching a Qdrant RAG from
+    /// inside an agent produced no network allow rule and no credential.
+    #[test]
+    fn agent_scoped_rag_sidecar_is_discovered() {
+        let root = unique_root("agent-scoped-rag");
+        let agent = root.join("researcher");
+        fs::create_dir_all(&agent).unwrap();
+        fs::write(agent.join("company-docs.sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+        fs::write(agent.join("company-docs.yaml"), "driver: qdrant\n").unwrap();
+
+        let found = collect_mixins(&root, &[ScanMode::SubdirNamed, ScanMode::SubdirFlat]);
+        assert_eq!(found, vec![agent.join("company-docs.sbx-mixin.yaml")]);
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn agent_level_mixin_and_rag_sidecars_are_both_discovered() {
+        let root = unique_root("agent-both-shapes");
+        let agent = root.join("researcher");
+        fs::create_dir_all(&agent).unwrap();
+        fs::write(agent.join("sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+        fs::write(agent.join("zebra.sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+        fs::write(agent.join("alpha.sbx-mixin.yaml"), "kind: mixin\n").unwrap();
+
+        let found = collect_mixins(&root, &[ScanMode::SubdirNamed, ScanMode::SubdirFlat]);
+        assert_eq!(
+            file_names(&found),
+            vec![
+                "sbx-mixin.yaml",
+                "alpha.sbx-mixin.yaml",
+                "zebra.sbx-mixin.yaml"
+            ]
+        );
+
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn subdir_flat_scan_ignores_a_directory_named_like_a_mixin() {
+        let root = unique_root("subdir-flat-decoy");
+        let agent = root.join("researcher");
+        fs::create_dir_all(agent.join("decoy.sbx-mixin.yaml")).unwrap();
+
+        assert!(collect_mixins(&root, &[ScanMode::SubdirFlat]).is_empty());
+
+        let _ = fs::remove_dir_all(&root);
     }
 }

src/sandbox/mod.rs

@@ -10,12 +10,17 @@ use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 use which::which;
 
+pub(crate) mod mcp_credentials;
 mod mixins;
 
+pub(crate) use mcp_credentials::sandbox_secret_env_var;
+
 use crate::config::AppConfig;
 use crate::config::Config;
 use crate::config::VAULT_DATA_FILE_NAME;
 use crate::config::paths;
+use crate::rag::RagData;
+use crate::sandbox::mcp_credentials::MCP_MIXIN_NAME;
 use crate::sandbox::mixins::DiscoveredMixin;
 use crate::utils::run_command_with_output;
 use crate::vault::SECRET_RE;
@@ -50,16 +55,22 @@ pub fn launch(name: Option<String>, fresh: bool) -> Result<()> {
     let registered = sbx_registered_services()?;
     inject_llm_secret(&config_content, &vault, &registered)?;
     if !fresh {
-        inject_mcp_secrets(&vault, &registered)?;
+        inject_rag_secrets(&vault, &registered)?;
     }
 
+    let credentials_mixin = if fresh {
+        None
+    } else {
+        inject_mcp_secrets(&vault, &registered)?
+    };
+
     let discovered = mixins::discover()?;
 
     if sandbox_exists(&name)? {
         info!("Re-attaching to existing sandbox '{name}'");
     } else {
         mixins::log_discovery(&discovered, false);
-        create_sandbox(&name, &kit_path, &discovered)?;
+        create_sandbox(&name, &kit_path, &discovered, credentials_mixin.as_deref())?;
         if !fresh {
             copy_host_files(&name)?;
         }
@@ -232,7 +243,7 @@ fn inject_llm_secret(
         if registered.contains(&service) {
             eprintln!(
                 "Secret for '{service}' already registered with sbx. \
-                 To update it, run: sbx secret set -g --force {service}"
+                 To update it, run: sbx secret set --force {service}"
             );
             continue;
         }
@@ -247,23 +258,14 @@ fn inject_llm_secret(
     Ok(())
 }
 
-fn find_secret_placeholder(value: &Value) -> Option<String> {
-    match value {
-        Value::String(s) => SECRET_RE
-            .captures(s)
-            .ok()
-            .flatten()
-            .map(|caps| caps[1].to_string()),
-        Value::Object(map) => map.values().find_map(find_secret_placeholder),
-        Value::Array(arr) => arr.iter().find_map(find_secret_placeholder),
-        _ => None,
-    }
-}
-
-fn inject_mcp_secrets(vault: &Vault, registered: &HashSet<String>) -> Result<()> {
+/// Registers one sbx secret per distinct `{{placeholder}}` in the MCP config
+/// and returns the generated schema-v2 `coyote-mcp` mixin (network egress for
+/// every remote MCP server + credential declarations), or `None` when the MCP
+/// config references no remote servers and no secrets.
+fn inject_mcp_secrets(vault: &Vault, registered: &HashSet<String>) -> Result<Option<String>> {
     let mcp_path = paths::mcp_config_file();
     if !mcp_path.exists() {
-        return Ok(());
+        return Ok(None);
     }
 
     let content = fs::read_to_string(&mcp_path)
@@ -272,32 +274,124 @@ fn inject_mcp_secrets(vault: &Vault, registered: &HashSet<String>) -> Result<()>
         .with_context(|| format!("Failed to parse {}", mcp_path.display()))?;
 
     let Some(servers) = mcp.get("mcpServers").and_then(|v| v.as_object()) else {
-        return Ok(());
+        return Ok(None);
     };
 
-    for (server_name, server_config) in servers {
-        let Some(secret_name) = find_secret_placeholder(server_config) else {
-            continue;
-        };
+    let credentials = mcp_credentials::collect_credentials(servers)?;
+    let allow_entries = mcp_credentials::collect_server_allow_entries(servers);
+    if credentials.is_empty() && allow_entries.is_empty() {
+        return Ok(None);
+    }
 
-        if registered.contains(server_name.as_str()) {
+    for credential in &credentials {
+        if registered.contains(credential.service_id.as_str()) {
             eprintln!(
-                "Secret for '{server_name}' already registered with sbx. \
-                 To update it, run: sbx secret set -g --force {server_name}"
+                "Secret for '{}' already registered with sbx. \
+                 To update it, run: sbx secret set --force {}",
+                credential.service_id, credential.service_id
             );
             continue;
         }
 
-        let secret_value = vault.get_secret(&secret_name, false).with_context(|| {
-            format!(
-                "Secret '{secret_name}' referenced by MCP server '{server_name}' not found \
-                 in vault. Add it with: coyote --add-secret {secret_name}"
-            )
-        })?;
+        let secret_value = vault
+            .get_secret(&credential.secret_name, false)
+            .with_context(|| {
+                format!(
+                    "Secret '{}' referenced by MCP server(s) {} not found \
+                     in vault. Add it with: coyote --add-secret {}",
+                    credential.secret_name,
+                    mcp_credentials::quoted_list(&credential.servers),
+                    credential.secret_name
+                )
+            })?;
 
-        sbx_secret_set(server_name, &secret_value)?;
+        sbx_secret_set(&credential.service_id, &secret_value)?;
     }
 
+    Ok(Some(mcp_credentials::render_mixin_yaml(
+        &credentials,
+        &allow_entries,
+    )?))
+}
+
+fn inject_rag_secrets(vault: &Vault, registered: &HashSet<String>) -> Result<()> {
+    let rags_dir = paths::rags_dir();
+    if !rags_dir.exists() {
+        return Ok(());
+    }
+    for entry in fs::read_dir(&rags_dir)?.flatten() {
+        let path = entry.path();
+        if path.extension().and_then(|e| e.to_str()) != Some("yaml") {
+            continue;
+        }
+        let stem = match path.file_stem().and_then(|s| s.to_str()) {
+            Some(s) if !paths::is_rag_sidecar_name(s) => s.to_string(),
+            _ => continue,
+        };
+        let Ok(raw) = fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(data) = serde_yaml::from_str::<RagData>(&raw) else {
+            continue;
+        };
+        if !data.attached {
+            continue;
+        }
+        let secret_names = driver_config_secret_names(&data);
+        let Some((primary, extra)) = secret_names.split_first() else {
+            continue;
+        };
+
+        let service_id = mcp_credentials::secret_service_id(&stem);
+        if !service_id.is_empty() && !registered.contains(&service_id) {
+            bind_rag_secret(vault, &service_id, primary, &stem)?;
+        }
+
+        for name in extra {
+            let id = mcp_credentials::secret_service_id(name);
+            if !id.is_empty() && !registered.contains(&id) {
+                bind_rag_secret(vault, &id, name, &stem)?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn driver_config_secret_names(data: &RagData) -> Vec<String> {
+    let mut names: Vec<String> = Vec::new();
+    for value in data.driver_config.values() {
+        let trimmed = value.trim();
+        let Ok(Some(caps)) = SECRET_RE.captures(trimmed) else {
+            continue;
+        };
+        if caps.get(0).map(|m| m.as_str()) != Some(trimmed) {
+            continue;
+        }
+        let Some(name) = caps.get(1).map(|m| m.as_str().trim()) else {
+            continue;
+        };
+        if !name.is_empty() && !names.iter().any(|n| n == name) {
+            names.push(name.to_string());
+        }
+    }
+    names
+}
+
+fn bind_rag_secret(vault: &Vault, service_id: &str, secret_name: &str, stem: &str) -> Result<()> {
+    match vault.get_secret(secret_name, false) {
+        Ok(secret_value) => {
+            sbx_secret_set(service_id, &secret_value)
+                .context("Failed to register RAG secret with sbx")?;
+        }
+        Err(e) => {
+            eprintln!(
+                "Warning: could not load secret '{secret_name}' for RAG '{stem}': {e}. \
+                 Queries to this RAG will fail inside the sandbox. \
+                 Run `coyote --add-secret {secret_name}` to fix."
+            );
+        }
+    }
     Ok(())
 }
 
@@ -305,7 +399,7 @@ fn provider_to_sbx_service(provider_type: &str, client_name: Option<&str>) -> St
     match provider_type {
         "claude" => "anthropic".to_string(),
         "openai" => "openai".to_string(),
-        "gemini" | "vertexai" => "google".to_string(),
+        "gemini" | "vertexai" => "gemini".to_string(),
         "openai-compatible" => client_name.unwrap_or("openai-compatible").to_string(),
         other => client_name.unwrap_or(other).to_string(),
     }
@@ -338,25 +432,29 @@ fn sbx_registered_services() -> Result<HashSet<String>> {
 
 fn sbx_secret_set(service: &str, secret_value: &str) -> Result<()> {
     let mut child = Command::new(SBX_BINARY)
-        .args(["secret", "set", "-g", service])
+        .args(["secret", "set", service])
         .stdin(Stdio::piped())
         .stdout(Stdio::inherit())
         .stderr(Stdio::inherit())
         .spawn()
-        .context("Failed to spawn `sbx secret set -g`")?;
+        .context("Failed to spawn `sbx secret set`")?;
 
     if let Some(mut stdin_handle) = child.stdin.take() {
         stdin_handle
             .write_all(secret_value.as_bytes())
-            .context("Failed to write secret to `sbx secret set -g` stdin")?;
+            .context("Failed to write secret to `sbx secret set` stdin")?;
     }
 
     let status = child
         .wait()
-        .context("Failed to wait for `sbx secret set -g`")?;
+        .context("Failed to wait for `sbx secret set`")?;
 
     if !status.success() {
-        bail!("`sbx secret set -g {service}` exited with {status}");
+        eprintln!(
+            "Warning: failed to register sbx secret '{service}' \
+             (`sbx secret set {service}` exited with {status}). \
+             Set it manually with: echo '<value>' | sbx secret set {service}"
+        );
     }
 
     Ok(())
@@ -375,9 +473,17 @@ fn sandbox_exists(name: &str) -> Result<bool> {
         .any(|line| line.split_whitespace().next() == Some(name)))
 }
 
-fn create_sandbox(name: &str, kit_path: &Path, mixins: &[DiscoveredMixin]) -> Result<()> {
+fn create_sandbox(
+    name: &str,
+    kit_path: &Path,
+    mixins: &[DiscoveredMixin],
+    credentials_mixin: Option<&str>,
+) -> Result<()> {
     info!("Creating sandbox '{name}'");
-    let args = build_create_args(name, kit_path, mixins)?;
+    let credentials_kit = credentials_mixin
+        .map(|yaml| mixins::wrap_mixin_bytes_as_kit(yaml.as_bytes(), MCP_MIXIN_NAME))
+        .transpose()?;
+    let args = build_create_args(name, kit_path, mixins, credentials_kit.as_deref())?;
     debug!("sbx {}", args.join(" "));
     let status = Command::new(SBX_BINARY)
         .args(&args)
@@ -398,6 +504,7 @@ fn build_create_args(
     name: &str,
     kit_path: &Path,
     mixins: &[DiscoveredMixin],
+    credentials_kit: Option<&Path>,
 ) -> Result<Vec<String>> {
     let kit_str = kit_path
         .to_str()
@@ -421,6 +528,15 @@ fn build_create_args(
         args.push(mixin_str);
     }
 
+    if let Some(kit) = credentials_kit {
+        let cred_str = kit
+            .to_str()
+            .ok_or_else(|| anyhow!("Credentials kit path is not valid UTF-8: {}", kit.display()))?
+            .to_string();
+        args.push("--kit".to_string());
+        args.push(cred_str);
+    }
+
     args.push(SANDBOX_AGENT.to_string());
     args.push(".".to_string());
 
@@ -559,6 +675,65 @@ fn chown_agent_recursive(sandbox: &str, path: &str) -> Result<()> {
 mod tests {
     use super::*;
 
+    fn rag_with(driver_config: &[(&str, &str)]) -> RagData {
+        let mut data = RagData::new("m".into(), 1024, 50, None, 5, None, Default::default());
+        data.driver = "qdrant".to_string();
+        data.attached = true;
+        for (k, v) in driver_config {
+            data.driver_config.insert(k.to_string(), v.to_string());
+        }
+        data
+    }
+
+    #[test]
+    fn secret_names_are_found_whatever_the_field_is_called() {
+        let data = rag_with(&[
+            ("host", "qdrant.example.com:6333"),
+            ("collection", "docs"),
+            ("token", "{{SOME_TOKEN}}"),
+        ]);
+
+        assert_eq!(driver_config_secret_names(&data), vec!["SOME_TOKEN"]);
+    }
+
+    #[test]
+    fn a_literal_credential_is_not_treated_as_a_secret_name() {
+        let data = rag_with(&[("api_key", "sk-a-real-looking-key")]);
+
+        assert!(driver_config_secret_names(&data).is_empty());
+    }
+
+    #[test]
+    fn plain_values_are_never_mistaken_for_secrets() {
+        let data = rag_with(&[("host", "localhost:6333"), ("collection", "docs")]);
+
+        assert!(driver_config_secret_names(&data).is_empty());
+    }
+
+    #[test]
+    fn a_partial_placeholder_is_not_a_credential() {
+        let data = rag_with(&[("api_key", "Bearer {{KEY}}")]);
+
+        assert!(driver_config_secret_names(&data).is_empty());
+    }
+
+    #[test]
+    fn several_secrets_are_all_found_and_deduped() {
+        let data = rag_with(&[
+            ("api_key", "{{QDRANT_KEY}}"),
+            ("host", "localhost:6333"),
+            ("token", "{{ OTHER_TOKEN }}"),
+            ("fallback_key", "{{QDRANT_KEY}}"),
+        ]);
+
+        assert_eq!(
+            driver_config_secret_names(&data),
+            vec!["QDRANT_KEY", "OTHER_TOKEN"],
+            "order follows driver_config, and a repeat is not registered twice"
+        );
+    }
+    use std::time::{SystemTime, UNIX_EPOCH};
+
     #[test]
     fn sanitize_name_lowercases() {
         assert_eq!(sanitize_name("Foo"), "foo");
@@ -626,8 +801,8 @@ mod tests {
     #[test]
     fn build_create_args_emits_base_kit_before_mixins() {
         let kit = PathBuf::from("/cache/sbx-kit");
-        let unique = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
             .unwrap()
             .as_nanos();
         let dir_a = env::temp_dir().join(format!("coyote-mixin-a-{unique}"));
@@ -650,7 +825,7 @@ mod tests {
             },
         ];
 
-        let args = build_create_args("my-box", &kit, &mixins).unwrap();
+        let args = build_create_args("my-box", &kit, &mixins, None).unwrap();
 
         assert_eq!(
             args,
@@ -676,7 +851,9 @@ mod tests {
     #[test]
     fn build_create_args_with_no_mixins_omits_mixin_kits() {
         let kit = PathBuf::from("/cache/sbx-kit");
-        let args = build_create_args("box", &kit, &[]).unwrap();
+
+        let args = build_create_args("box", &kit, &[], None).unwrap();
+
         assert_eq!(
             args,
             vec![
@@ -690,4 +867,79 @@ mod tests {
             ]
         );
     }
+
+    #[test]
+    fn build_create_args_appends_credentials_kit_after_mixins() {
+        let kit = PathBuf::from("/cache/sbx-kit");
+        let credentials_kit = PathBuf::from("/cache/sbx-mixin-kits/abc123");
+
+        let args = build_create_args("box", &kit, &[], Some(&credentials_kit)).unwrap();
+
+        assert_eq!(
+            args,
+            vec![
+                "create".to_string(),
+                "--name".to_string(),
+                "box".to_string(),
+                "--kit".to_string(),
+                "/cache/sbx-kit".to_string(),
+                "--kit".to_string(),
+                "/cache/sbx-mixin-kits/abc123".to_string(),
+                "coyote".to_string(),
+                ".".to_string(),
+            ]
+        );
+    }
+
+    #[test]
+    fn build_create_args_orders_base_kit_then_mixins_then_credentials_kit() {
+        let kit = PathBuf::from("/cache/sbx-kit");
+        let credentials_kit = PathBuf::from("/cache/sbx-mixin-kits/abc123");
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let dir = env::temp_dir().join(format!("coyote-mixin-cred-{unique}"));
+        fs::create_dir_all(&dir).unwrap();
+
+        let mixins = vec![DiscoveredMixin {
+            path: dir.clone(),
+            label: "user".into(),
+            install_count: 0,
+            domain_count: 0,
+        }];
+
+        let args = build_create_args("box", &kit, &mixins, Some(&credentials_kit)).unwrap();
+
+        assert_eq!(
+            args,
+            vec![
+                "create".to_string(),
+                "--name".to_string(),
+                "box".to_string(),
+                "--kit".to_string(),
+                "/cache/sbx-kit".to_string(),
+                "--kit".to_string(),
+                dir.display().to_string(),
+                "--kit".to_string(),
+                "/cache/sbx-mixin-kits/abc123".to_string(),
+                "coyote".to_string(),
+                ".".to_string(),
+            ]
+        );
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn provider_to_sbx_service_maps_gemini_family_to_gemini() {
+        assert_eq!(provider_to_sbx_service("gemini", None), "gemini");
+        assert_eq!(provider_to_sbx_service("vertexai", None), "gemini");
+    }
+
+    #[test]
+    fn provider_to_sbx_service_maps_known_providers() {
+        assert_eq!(provider_to_sbx_service("claude", None), "anthropic");
+        assert_eq!(provider_to_sbx_service("openai", None), "openai");
+    }
 }

src/utils/mod.rs

@@ -75,6 +75,7 @@ static TOOL_DIM_COLOR: OnceLock<Color> = OnceLock::new();
 static TOOL_FN_COLOR: OnceLock<Color> = OnceLock::new();
 static TOOL_KEY_COLOR: OnceLock<Color> = OnceLock::new();
 static TOOL_WARN_COLOR: OnceLock<Color> = OnceLock::new();
+static REPLAY_LABEL_COLOR: OnceLock<Color> = OnceLock::new();
 
 pub fn init_tool_colors(theme: &Theme) {
     fn resolve(theme: &Theme, scope_str: &str) -> Option<Color> {
@@ -96,6 +97,16 @@ pub fn init_tool_colors(theme: &Theme) {
     if let Some(c) = resolve(theme, "string") {
         let _ = TOOL_WARN_COLOR.set(c);
     }
+    let replay_color = Scope::new("entity.name")
+        .ok()
+        .and_then(|scope| {
+            let style = Highlighter::new(theme).style_mod_for_stack(&[scope]);
+            style.foreground.or(theme.settings.foreground)
+        })
+        .map(|fg| Color::Rgb(fg.r, fg.g, fg.b));
+    if let Some(c) = replay_color {
+        let _ = REPLAY_LABEL_COLOR.set(c);
+    }
 }
 
 pub fn now() -> String {
@@ -236,6 +247,18 @@ pub fn cyan_bold_text(input: &str) -> String {
         .to_string()
 }
 
+pub fn replay_label_text(input: &str) -> String {
+    if *NO_COLOR {
+        return input.to_string();
+    }
+    let color = REPLAY_LABEL_COLOR.get().copied().unwrap_or(Color::Green);
+    nu_ansi_term::Style::new()
+        .fg(color)
+        .bold()
+        .paint(input)
+        .to_string()
+}
+
 pub fn magenta_text(input: &str) -> String {
     if *NO_COLOR {
         return input.to_string();

src/vault/utils.rs

@@ -1,5 +1,5 @@
 use crate::config::ensure_parent_exists;
-use crate::sandbox::SANDBOX_ENV_FLAG;
+use crate::sandbox::{SANDBOX_ENV_FLAG, sandbox_secret_env_var};
 use crate::vault::{SECRET_RE, Vault};
 use anyhow::Result;
 use anyhow::anyhow;
@@ -358,7 +358,32 @@ fn required_cli_preflight(label: &str, cli: &str, install_url: &str) {
 
 pub fn interpolate_secrets(content: &str, vault: &Vault) -> Result<(String, Vec<String>)> {
     if env::var_os(SANDBOX_ENV_FLAG).is_some() {
-        return Ok((content.to_string(), vec![]));
+        let (parsed, missing) = interpolate_secrets_with(content, None, |name| {
+            env::var(sandbox_secret_env_var(name)).map_err(|_| {
+                anyhow!(SecretError::NotFound {
+                    key: name.to_string(),
+                    provider: "sandbox environment",
+                })
+            })
+        })?;
+
+        if !missing.is_empty() {
+            let mut env_vars: Vec<String> = missing
+                .iter()
+                .map(|name| sandbox_secret_env_var(name))
+                .collect();
+            env_vars.sort();
+            env_vars.dedup();
+            eprintln!(
+                "Config references secrets that are not available inside this sandbox \
+                 (expected env vars: {}). Sandbox secrets are provisioned at creation \
+                 from the host; add the missing secrets on the host, then re-create \
+                 the sandbox.",
+                env_vars.join(", ")
+            );
+        }
+
+        return Ok((parsed, missing));
     }
     interpolate_secrets_with(content, vault.auth_hint(), |name| {
         vault.get_secret(name, false)