chore: bump Cargo.toml to 0.7.0

bump: version 0.6.0 → 0.7.0 [skip ci]
feat: added a memory option to .set tab completions
2026-06-18 22:01:38 +00:00 · 2026-06-18 22:01:35 +00:00 · 2026-06-18 15:50:23 -06:00 · 2026-06-18 14:32:07 -06:00 · 2026-06-18 14:30:55 -06:00 · 2026-06-18 13:01:38 -06:00
93 changed files with 9702 additions and 1371 deletions
@@ -1,3 +1,127 @@
 ## v0.7.0 (2026-06-18)
 ### Feat
 - added a memory option to .set tab completions
 - Added a diagnostic .info tools subcommand to make it easier to see what tools are enabled in all contexts
 - Added additional info outputs for enabled skills and sbx directories
 - directly execute shell commands from within the REPL
 - created mixin kit for built-in functions and MCP servers
 - Added sbx mixins for the secrets providers so users can also bootstrap those as well.
 - added support for loading sbx mixins that are dynamically discovered in the users workspace and config directory
 - Added a --fresh flag to let users create a truly bare bones sandbox without bootstrapping their config
 - initial built-in sandboxing support powered by Docker sbx
 - Added the ability to auto-bootstrap workspace memory when in git repos
 - Added explicit guardrail handling for pending agents
 - auto-append memory to memory index and don't necessarily require the LLM to remember to do it after a write
 - Added an --init-memory [global|workspace] flag to easily and quickly enable memory
 - added memory global configuration settings to the output of --info and .info
 - added .set memory REPL commands to control memory injection and applied formatting
 - Create the built-in memory management tools
 - Append the memory system prompts (readonly or r/w) to the system prompt when applicable
 - Created the --no-memory CLI flag to disable memory for this invocation
 - Added the memory configuration properties and storage to the main app config, roles, sessions, and agents.
 - initial scaffolding of a memory system
 ### Fix
 - rebuild the tool scope after dynamically updating the skills_enabled value in the REPL
 - properly resolve Windows-based local vault password file locations and bootstrap them into the sandbox when possible
 - auto-translation of user-prefixed Mac and Linux paths for the vault password file when running inside a sandbox
 - don't attempt to auto complete .vault list in the REPL; that's the end of the command
 - buffer tool stdout as well as stderr so that any tools that error to stdout are captured and included in the response to the model, enabling the model to see what went wrong and to reason about how to fix it.
 - auto-bootstrapped memory was accidentally putting the MEMORY.md directly in the repo root rather than .coyote/memory/MEMORY.md
 - improved the fs_patch script description and added improved error handling to it.
 - added in forgotten require_max_tokens to the fable model
 - append memory functions to non-graph based agents on init
 - when auto_continue is disabled via the .set auto_continue false command, it should strip the todo functions from the list of functions
 - use rawPredict for non-streaming Claude requests
 ### Refactor
 - Migrated the .skills command completion to use StateFlags and updated the help messages
 ## v0.6.0 (2026-06-05)
 ### Feat
 - added skill hint prompt injection and configuration
 - Fallthrough on missing secrets during mcp.json merging
 - validate visible_skills field at config load time
 - implemented reflexion (sorta) in sisyphus for significant code changes to delegate to the code-reviewer agent
 - improved explore agent
 - removed conditional fallback of LLM_*_RAW_JSON from built-ins
 - updated enabled_skills handling to support both list and comma-separated strings
 - added new REPL set commands for toggling skills and changing what skills are enabled
 - upgraded to the latest version of mcp-remote
 - fs_grep now works with both files and directories
 - improved code reviewer agents with skills
 - added round trip validation for vault providers to ensure permissions and authentication
 - created new first-time run wizard for secrets provider
 - vault_password_file or nothing at all is shorthand for just using the local gman provider for secret management
 - refactored gman usage to be generic and work with various vault providers and use the SupportedProvider enum directly for configurations
 - created initial parity gman generalization for vault provider
 - Refactored the sisyhpus agent system to utilize the new skills system to improve performance and reliability
 - llm graph nodes support skills
 - updated sisyphus and coder tools
 - removed potentially confusing tab completions for .skill
 - .edit skill <name> support from within the REPL
 - Added skills_dir to the info output of Coyote
 - Created a few auto built-in skills
 - Added support for auto_unload skills during chat
 - cleaned up skill implementation
 - support multiple skill flags to load multiple skills at CLI startup
 - Modified --skill CLI to allow users to specify skills to start the REPL or CLI with.
 - added CLI --skill flag for modifying skills easily
 - REPL integration with skills
 - dynamic loading/unloading of skill tools and MCP servers whenever load_skill/unload_skill are invoked
 - created built-in functions for listing, loading, and unloading skills
 - implemented the skills policy to track available skills per context
 - added remote install and install support for skills
 - created the skill registry
 - decided to make skills persist to disk like agents and not in-memory like built-in roles
 - scaffold skill module
 ### Fix
 - disable skills for specific built-in roles
 - redirect stderr into user's /dev/tty for guards
 - azure doesn't support underscores in key vault
 - accidental regression on enabled_skills being empty = all
 - greedy secrets regex caused multiple secrets on one line to fail
 - add agent context check to skill visibility validation
 - enforced global visible_skills in llm node validation and improved skill loading error handling across the project
 - restore agent skill policy on error during effective policy calculation
 - apply the same validation for skill filenames on list_skills as happens everywhere else
 - the vault's init_bare should try to load the provisioned secret_provider from the config file without also interpolating any of the rest of the configuration file. It should only fail if the user has not yet created a configuration file; i.e. done a first-time run.
 - the vault roundtrip test used characters that are unsupported by some major secrets providers
 - fixed tool filtering logic for skills and user functions in agents
 - privilege leak when unloading skills and leaving tool scope untouched
 - When bootstrapping an app config to interpolate secrets, clone the secrets provider configuration as well so config secrets stored in remote vaults can be used properly
 - forgot to move back up the vault probe value error to be before the delete
 - don't silently fail on skill role composition extraction in llm nodes
 - set -euo pipefail for the temp script in execute_command.sh tool
 - added forgotten skill name validation to has_skill to prevent side-channel attacks
 - use unique values for the secrets round trip verification
 - stop interpolating a line if any errors occur
 - added path validation for skill names
 - effective_policy unconditionally overwrote skill values for role-like structs
 - updated execute_command to not mangle heredocs and also added explicit instructions to the coder and sisyphus agents to use fs_write and fs_patch over execute_command when writing files
 - llm nodes accidentally skipped skill_registry::effective_role because I was passing an inline role instead
 - updated temperature values for all agents and roles
 - added back in require_max_tokens for new Claude models
 - skill support also requires function calling to be enabled
 - non_tty tests break on some TTY terminals
 - skill loading on agents
 - forgot to bootstrap skills on REPL startup
 - remove now deprecated .skill edit command
 ### Refactor
 - removed redundant skill name validation from has_skill function
 - support both CSV and list formats for enabled_tools
 - Support both CSV and list formats for enabled_mcp_servers
 ## v0.5.0 (2026-05-27)
 ### Feat
@@ -1,6 +1,6 @@
 [package]
 name = "coyote-ai"
-version = "0.5.0"
+version = "0.7.0"
 edition = "2024"
 authors = ["Alex Clarke <alex.j.tusa@gmail.com>"]
 description = "An all-in-one, batteries included LLM CLI Tool"
@@ -58,6 +58,8 @@ http = "1.1.0"
 indexmap = { version = "2.2.6", features = ["serde"] }
 hmac = "0.12.1"
 aws-smithy-eventstream = "0.60.4"
 aws-smithy-types = "=1.4.9"
 time = "=0.3.47"
 urlencoding = "2.1.3"
 json-patch = { version = "4.0.0", default-features = false }
 bitflags = "2.5.0"
@@ -91,7 +93,7 @@ tree-sitter-python = "0.25.0"
 tree-sitter-typescript = "0.23"
 colored = "3.0.0"
 clap_complete = { version = "4.5.58", features = ["unstable-dynamic"] }
-gman = "0.4.1"
+gman = "0.5.0"
 clap_complete_nushell = "4.5.9"
 open = "5"
 rand = { version = "0.10.0", features = ["default"] }
@@ -25,6 +25,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
 * [REPL](https://github.com/Dark-Alex-17/coyote/wiki/REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Coyote.
  * [Custom REPL Prompt](https://github.com/Dark-Alex-17/coyote/wiki/REPL-Prompt): Customize the REPL prompt to provide useful contextual information.
 * [Vault](https://github.com/Dark-Alex-17/coyote/wiki/Vault): Securely store and manage sensitive information such as API keys and credentials.
 * [Sandboxes](https://github.com/Dark-Alex-17/coyote/wiki/Sandboxes): Launch Coyote inside an isolated [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) with one command. Host config and vault credentials are projected in automatically; everything else is delegated to the `sbx` CLI.
 * [Shell Integrations](https://github.com/Dark-Alex-17/coyote/wiki/Shell-Integrations): Seamlessly integrate Coyote with your shell environment for enhanced command-line assistance.
 * [Function Calling](https://github.com/Dark-Alex-17/coyote/wiki/Tools): Leverage function calling capabilities to extend Coyote's functionality with custom tools
    * [Creating Custom Tools](https://github.com/Dark-Alex-17/coyote/wiki/Custom-Tools): You can create your own custom tools to enhance Coyote's capabilities.
@@ -36,7 +37,9 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
 * [Macros](https://github.com/Dark-Alex-17/coyote/wiki/Macros): Automate repetitive tasks and workflows with Coyote "scripts" (macros).
 * [RAG](https://github.com/Dark-Alex-17/coyote/wiki/RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation.
 * [Sessions](https://github.com/Dark-Alex-17/coyote/wiki/Sessions): Manage and persist conversational contexts and settings across multiple interactions.
 * [Memory](https://github.com/Dark-Alex-17/coyote/wiki/Memory): Persistent file-based memory that survives across sessions. Bootstrap with `coyote --init-memory [global|workspace]`.
 * [Roles](https://github.com/Dark-Alex-17/coyote/wiki/Roles): Customize model behavior for specific tasks or domains.
 * [Skills](https://github.com/Dark-Alex-17/coyote/wiki/Skills): Modular knowledge or capability packs the LLM can load and unload mid-conversation. Multiple skills compose; instructions stack, tools and MCPs union.
 * [Agents](https://github.com/Dark-Alex-17/coyote/wiki/Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
    * [Graph Agents](https://github.com/Dark-Alex-17/coyote/wiki/Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns).
 * [Todo System](https://github.com/Dark-Alex-17/coyote/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models.
@@ -1,7 +1,6 @@
 name: code-reviewer
 description: CodeRabbit-style code reviewer - spawns per-file reviewers, synthesizes findings
-version: 1.0.0
+version: 2.0.0
 temperature: 0.1
 auto_continue: true
 max_auto_continues: 20
@@ -11,6 +10,11 @@ can_spawn_agents: true
 max_concurrent_agents: 10
 max_agent_depth: 2
 skills_enabled: true
 enabled_skills:
  - delegation-protocol
  - parallel-research
 variables:
  - name: project_dir
    description: Project directory to review
@@ -18,6 +22,7 @@ variables:
 global_tools:
  - fs_read.sh
  - fs_cat.sh
  - fs_grep.sh
  - fs_glob.sh
  - execute_command.sh
@@ -25,32 +30,62 @@ global_tools:
 instructions: |
  You are a code review orchestrator, similar to CodeRabbit. You coordinate per-file reviews and produce a unified report.
  ## Step 0: Load orchestration skills
  Before doing anything else, call `skill__load` for `delegation-protocol` and `parallel-research`. They carry the methodology you need:
  - **`delegation-protocol`** — how to write delegation prompts that give the sub-agent its full context (TASK / EXPECTED OUTCOME / MUST DO / MUST NOT DO / CONTEXT). Apply this format when spawning each file-reviewer.
  - **`parallel-research`** — the spawn-and-wait protocol, the anti-duplication rule (don't redo work you delegated), and the rule about ending your response and letting the system notify you on agent completion.
  Both skills are always-on for this agent's workflow. Skill bodies are your source of truth for HOW to delegate and HOW to coordinate parallel work; this agent's instructions handle the CodeRabbit-specific shape.
  ## Workflow
  1. **Get the diff:** Run `get_diff` to get the git diff (defaults to staged changes, falls back to unstaged)
  2. **Parse changed files:** Extract the list of files from the diff
  3. **Create todos:** One todo per phase (get diff, spawn reviewers, collect results, synthesize report)
-  4. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel
+  4. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel. Apply the `delegation-protocol` structured prompt format.
  5. **Broadcast sibling roster:** Send each file-reviewer a message with all sibling IDs and their file assignments
-  6. **Collect all results:** Wait for each file-reviewer to complete
+  6. **Collect all results:** Per `parallel-research`, do not poll. End your response after spawns + roster; the system will notify you when agents complete.
  7. **Synthesize:** Combine all findings into a CodeRabbit-style report
  ## Spawning File Reviewers
-  For each changed file, spawn a file-reviewer with a prompt containing:
+  Apply the `delegation-protocol` structured prompt format. Each spawn gets the full TASK / EXPECTED OUTCOME / MUST DO / MUST NOT DO / CONTEXT sections — the file-reviewer hasn't seen the codebase or the broader PR; the spawn prompt IS its entire context.
  - The file path
  - The relevant diff hunk(s) for that file
  - Instructions to review it
  ```
-  agent__spawn --agent file-reviewer --prompt "Review the following diff for <file_path>:
+  agent__spawn --agent file-reviewer --prompt "
  ## TASK
  Review the git diff for <file_path>. Produce structured findings per your output format.
  ## EXPECTED OUTCOME
  A REVIEW_COMPLETE-terminated report following your standard format:
  - ## File: <file_path>
  - ### Summary (1-2 sentences)
  - ### Findings (each with severity, lines, description, suggestion)
  - ### Cross-File Concerns (or 'None')
  ## MUST DO
  - Load `code-review` and `ai-slop-remover` skills before reading any code
  - Apply both skill checklists to the diff
  - Use targeted fs_read with offset/limit; max 5 file reads
  - End with REVIEW_COMPLETE
  ## MUST NOT DO
  - Do not modify files (you are read-only)
  - Do not review unchanged code unrelated to the diff
  - Do not omit findings to keep the report short
  ## CONTEXT
  Project: {{project_dir}}
  File under review: <file_path>
  Diff:
  <diff content for this file>
-
+  "
  Focus on bugs, security issues, logic errors, and style. Use the severity format (🔴🟡🟢💡).
  End with REVIEW_COMPLETE."
  ```
  Paste the actual diff hunk(s) inline — the reviewer can't see your context. If you have prior knowledge of the change's intent (PR description, ticket), include it in CONTEXT.
  ## Sibling Roster Broadcast
  After spawning ALL file-reviewers (collecting their IDs), send each one a message with the roster:
@@ -117,6 +152,7 @@ instructions: |
  3. **Don't review code yourself:** Delegate ALL review work to file-reviewers
  4. **Preserve severity tags:** Don't downgrade or remove severity from file-reviewer findings
  5. **Include ALL findings:** Don't summarize away specific issues
  6. **File reads:** If you do read a file directly (e.g. to verify a finding before synthesis), `fs_read` returns a TRUNCATED view with line numbers (default 2000 lines, long lines cut at 2000 chars). Use `fs_cat` only when you need the FULL untruncated contents of a file.
  ## Context
  - Project: {{project_dir}}
@@ -4,8 +4,6 @@ description: |
  bounded fix-loop until verified. Designed to be delegated to by sisyphus.
 version: "1.0"
 temperature: 0.1
 global_tools:
  - fs_cat.sh
  - fs_ls.sh
@@ -13,6 +11,14 @@ global_tools:
  - fs_patch.sh
  - execute_command.sh
 skills_enabled: true
 enabled_skills:
  - ai-slop-remover
  - code-review
  - git-master
  - frontend-ui-ux
  - verification-gates
 variables:
  - name: project_dir
    description: |
@@ -40,6 +46,10 @@ initial_state:
  files_to_create: []
  risks: []
  complexity_score: 0
  review_attempts: 0
  max_review_attempts: 1
  review_clean: true
  review_notes: ""
 start: resolve_paths
@@ -145,16 +155,36 @@ nodes:
    id: implement
    type: llm
    description: Write code via fs tools. Bounded tool-call loop.
    skills_enabled: true
    enabled_skills:
      - ai-slop-remover
      - code-review
      - git-master
      - frontend-ui-ux
      - verification-gates
    instructions: |
      You are a senior engineer. Implement the plan by writing code via
      tools. Follow existing patterns in the codebase.
      ## Skills
      Use `skill__list` to see what's available, then `skill__load` the ones
      that fit the work: `ai-slop-remover` always, `frontend-ui-ux` when
      touching UI, `git-master` when touching history, `verification-gates`
      to remember what evidence is required. Unload when a phase ends.
      ## Writing code
      1. Use `fs_patch` for surgical edits to existing files.
      2. Use `fs_write` for new files or full rewrites.
-      3. NEVER output code to chat. Always use tools.
+      3. NEVER write files via `execute_command`. Do not use `cat >`,
-      4. ALWAYS pass ABSOLUTE paths to fs_write and fs_patch. Relative
+         `cat >>`, `echo >`, `printf >`, `tee`, heredocs (`<<EOF`), or
         `python3 -c "open(...).write(...)"`. Shell-based file writes
         break on multi-line content, special characters, quoted strings,
         and nested language blocks. `fs_write` and `fs_patch` handle
         these correctly because they don't go through shell parsing.
      4. NEVER output code to chat. Always use tools.
      5. ALWAYS pass ABSOLUTE paths to fs_write and fs_patch. Relative
         paths resolve against the coyote invocation directory (not the
         project dir), which is rarely what you want. The project root
         is {{project_dir}}.
@@ -241,6 +271,73 @@ nodes:
    timeout: 5
    fallback: end_failure
  self_review:
    id: self_review
    type: llm
    description: Skill-driven self-review of the diff. Catches AI slop, dishonest naming, suppressed errors. Bounded to max_review_attempts.
    skills_enabled: true
    enabled_skills:
      - code-review
      - ai-slop-remover
    instructions: |
      You are reviewing the diff you just produced. Load `code-review` and
      `ai-slop-remover` via `skill__load` and apply their checklists STRICTLY.
      Flag ONLY concrete issues:
        - Correctness bugs or uncovered edge cases
        - Suppressed errors (as any, @ts-ignore, #[allow(...)] on unfamiliar
          lints, empty catch blocks)
        - Dishonest naming (get_X that mutates, returns wrong type, etc.)
        - Useless comments that restate the code
        - AI slop (filler prose, multi-paragraph docstrings, defensive
          handling of impossible cases)
      Do NOT flag:
        - Style preferences if the pattern matches existing code in the repo
        - Things the build/tests already verified
        - "Could be more elegant" without a concrete bug
      Be terse. The orchestrator wants signal, not noise. If you find nothing
      blocking, set review_clean=true and leave review_notes empty.
      Project directory: {{project_dir}}
    prompt: |
      ## Files to review
      Modified: {{files_to_modify}}
      Created: {{files_to_create}}
      ## What the implementation was supposed to do
      {{plan_summary}}
      Read each file's changed region. Apply the review skills. Output your verdict.
    tools:
      - fs_cat
      - fs_ls
      - execute_command
    max_iterations: 15
    output_schema:
      type: object
      properties:
        review_clean:
          type: boolean
          description: True if no blocker issues were found.
        review_notes:
          type: string
          description: Concrete issues found, one per line as file:line - description. Empty when review_clean is true.
      required: [review_clean, review_notes]
    state_updates:
      last_node_output: "{{output}}"
    fallback: end_success
    next: route_review_result
  route_review_result:
    id: route_review_result
    type: script
    description: Routes based on review_clean and review_attempts budget. End on clean or budget exhausted; loop to implement otherwise.
    script: scripts/route_review_result.sh
    timeout: 5
    fallback: end_success
  end_success:
    id: end_success
    type: end
@@ -0,0 +1,58 @@
 #!/usr/bin/env bash
 set -euo pipefail
 if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
  state=$(cat "$GRAPH_STATE_FILE")
 elif [[ -n "${GRAPH_STATE:-}" ]]; then
  state="$GRAPH_STATE"
 else
  state='{}'
 fi
 review_clean=$(echo "$state" | jq -r '.review_clean // true')
 review_attempts=$(echo "$state" | jq -r '.review_attempts // 0')
 max_review_attempts=$(echo "$state" | jq -r '.max_review_attempts // 1')
 review_notes=$(echo "$state" | jq -r '.review_notes // ""')
 if [[ "$review_clean" != "true" && "$review_clean" != "false" ]]; then
  echo "ERROR: review_clean must be boolean ('true'/'false'); got: $review_clean" >&2
  exit 1
 fi
 if ! [[ "$review_attempts" =~ ^[0-9]+$ ]]; then
  echo "ERROR: review_attempts must be a non-negative integer; got: $review_attempts" >&2
  exit 1
 fi
 if ! [[ "$max_review_attempts" =~ ^[0-9]+$ ]]; then
  echo "ERROR: max_review_attempts must be a non-negative integer; got: $max_review_attempts" >&2
  exit 1
 fi
 if [[ "$review_clean" == "true" ]]; then
  jq -nc '{"_next": "end_success"}'
  exit 0
 fi
 if (( review_attempts >= max_review_attempts )); then
  jq -nc \
    --arg n "$review_notes" \
    '{
      "_next": "end_success",
      "review_notes_unresolved": ("Shipped with unresolved review notes (budget exhausted):\n" + $n)
    }'
  exit 0
 fi
 next_review=$((review_attempts + 1))
 fix_instr=$(printf '## Self-review feedback (attempt %d of %d)\n\nThe code review found concrete issues. Address them with minimal edits. Do not refactor unrelated code.\n\n%s' \
  "$next_review" "$max_review_attempts" "$review_notes")
 jq -nc \
  --argjson n "$next_review" \
  --arg fi "$fix_instr" \
  '{
    "review_attempts": $n,
    "fix_instructions": $fi,
    "_next": "implement"
  }'
@@ -25,7 +25,7 @@ if [[ -z "$cmd" || "$cmd" == "null" ]]; then
  jq -nc '{
    "tests_ok": true,
    "tests_output": "(no test command available for this project type)",
-    "_next": "end_success"
+    "_next": "self_review"
  }'
  exit 0
 fi
@@ -40,7 +40,7 @@ if (( exit_code == 0 )); then
    '{
      "tests_ok": true,
      "tests_output": ("Ran: " + $cmd + "\n\n" + $out),
-      "_next": "end_success"
+      "_next": "self_review"
    }'
 else
  jq -nc \
@@ -15,8 +15,6 @@ description: |
 version: "1.0"
 temperature: 0.0
 global_tools:
  - web_search_coyote.sh
  - fetch_url_via_curl.sh
@@ -1,7 +1,10 @@
 name: explore
-description: Fast codebase exploration agent - finds patterns, structures, and relevant files
+description: Fast codebase exploration agent - finds patterns, structures, and relevant files. Designed to be fanned out 2-5 in parallel by orchestrators.
-version: 1.0.0
+version: 3.0.0
-temperature: 0.1
+
 skills_enabled: true
 enabled_skills:
  - ai-slop-remover
 variables:
  - name: project_dir
@@ -12,6 +15,7 @@ mcp_servers:
  - ddg-search
 global_tools:
  - fs_read.sh
  - fs_cat.sh
  - fs_grep.sh
  - fs_glob.sh
  - fs_ls.sh
@@ -19,57 +23,91 @@ global_tools:
 instructions: |
  You are a codebase explorer. Your job: Search, find, report. Nothing else.
-  ## Your Mission
+  ## Step 0: Load your skills
-  Given a search task, you:
+  At the start of every exploration, call `skill__load` for `ai-slop-remover`. Your findings go directly into the orchestrator's synthesis, so concise, slop-free output is the contract. Apply the skill's standards to your final findings block:
  1. Search for relevant files and patterns
  2. Read key files to understand structure
  3. Report findings concisely
  4. Signal completion with EXPLORE_COMPLETE
-  ## File Reading Strategy (IMPORTANT - minimize token usage)
+  - No filler ("It's important to note that…", "Let me explain…"). Just the finding.
  - No flattery, no padding, no status updates about your process.
  - No multi-paragraph commentary — bullet points with code snippets are enough.
-  1. **Find first, read second** - Never read a file without knowing why
+  ## You may be one of many parallel explorers
  2. **Use grep to locate** - `fs_grep --pattern "struct User" --include "*.rs"` finds exactly where things are
  3. **Use glob to discover** - `fs_glob --pattern "*.rs" --path src/` finds files by name
  4. **Read targeted sections** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads only lines 50-79
  5. **Never read entire large files** - If a file is 500+ lines, read the relevant section only
-  ## Available Actions
+  Orchestrators (like Sisyphus) often fan out 2-5 explore agents at once, each covering a different angle of the same question. Assume you are ONE narrow slice of a larger investigation. Stay strictly within YOUR slice as defined by the prompt — don't broaden scope to cover what other parallel explorers might be handling.
-  - `fs_grep --pattern "struct User" --include "*.rs"` - Find content across files
+  If the prompt says "find auth middleware", you find auth middleware. You do NOT also tour the routing layer, the error system, and the database connection pool. Narrow scope is the contract.
  - `fs_glob --pattern "*.rs" --path src/` - Find files by name pattern
  - `fs_read --path "src/main.rs"` - Read a file (with line numbers)
  - `fs_read --path "src/main.rs" --offset 100 --limit 50` - Read lines 100-149 only
  - `get_structure` - See project layout
  - `search_content --pattern "struct User"` - Agent-level content search
-  ## Output Format
+  ## Investigation methodology
-  Always end your response with a findings summary:
+  Before searching, build a quick mental model. Then narrow in. Then read.
  1. **Frame the question.** What kind of artifact am I looking for? Symbols (struct/class/function)? File patterns? Configuration? Implementation details? Tests? Different artifact kinds use different tools.
  2. **Find first, read second.** Never `fs_read` a file without knowing why you're reading it.
  3. **Build a directory mental model with `fs_ls` and `fs_glob`** — `fs_ls src/` to see what's there; `fs_glob '**/*.rs' src/` to see which files exist by name.
  4. **Locate symbols with `fs_grep`** — for finding where things live across the codebase. `fs_grep --pattern "fn handle_request" --include "*.rs"` is faster than reading files.
  5. **Read targeted sections with `fs_read --offset/--limit`** — `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79 only. `fs_read` adds line numbers but TRUNCATES long lines (over 2000 chars) and caps output at 2000 lines by default.
  6. **Use `fs_cat` only when you need the full untruncated file** — rare in exploration. If you reach for `fs_cat`, ask whether `fs_grep` + targeted `fs_read` would answer your question with less context spend.
  7. **Never read entire large files** — for files 500+ lines, read the relevant section only.
  ## Available actions
  - `fs_grep --pattern "struct User" --include "*.rs"` — find content across files in a directory tree
  - `fs_grep --pattern "TODO" --path "src/main.rs"` — find content within a single file (--include is ignored in this mode)
  - `fs_glob --pattern "*.rs" --path src/` — find files by name pattern
  - `fs_read --path "src/main.rs"` — read a TRUNCATED view with line numbers (default 2000 lines, lines over 2000 chars cut off)
  - `fs_read --path "src/main.rs" --offset 100 --limit 50` — read lines 100-149 only (line numbers; truncation rules still apply)
  - `fs_cat --path "src/main.rs"` — read the FULL untruncated file (no line numbers); use only when you actually need every line
  - `fs_ls --path "src/"` — list directory contents
  ## When to use the web (ddg-search MCP)
  Rarely. You are a CODEBASE explorer, not a web researcher. Use the web only when the codebase references an external library/framework whose documented behavior is the answer to the question (e.g., "how does Tokio's #[tokio::main] expand"), and the answer isn't in the local code. For internal questions ("how does OUR auth work"), grep the codebase — never the web.
  ## Output format
  Always end your response with a structured findings block. Sisyphus reads this verbatim and may paste sections directly into delegation prompts for a coder agent, so the structure matters:
  ```
  FINDINGS:
-  - [Key finding 1]
+  - [One-line concrete fact about what you found]
-  - [Key finding 2]
+  - [Another one-line fact]
-  - Relevant files: [list]
+  - Relevant files: [list of paths, no commentary]
  Code patterns (paste actual lines):
  - From `path/to/file.ext` lines N-M:
    <5-20 lines of actual code that show the pattern>
  - From `path/to/other.ext` lines N-M:
    <another snippet>
  Open questions (only if any):
  - [Anything you couldn't determine and the orchestrator should clarify or delegate elsewhere]
  EXPLORE_COMPLETE
  ```
  Pasting actual code lines (5-20 per pattern) lets the orchestrator hand snippets directly to a coder agent without re-exploration. That is the entire point of your existence in a parallel research phase. File paths alone make downstream delegation impossible — the coder would have to re-do your work.
  ## Rules
-  1. **Be fast** - Don't read every file, read representative ones
+  1. **Be fast.** Don't read every file, read representative ones.
-  2. **Be focused** - Answer the specific question asked
+  2. **Stay in your slice.** Narrow scope is the contract.
-  3. **Be concise** - Report findings, not your process
+  3. **Be concise.** Report findings, not your process. Apply the `ai-slop-remover` skill to your output.
-  4. **Never modify files** - You are read-only
+  4. **Never modify files.** You are read-only.
-  5. **Limit reads** - Max 5 file reads per exploration
+  5. **Limit reads.** Target around 5 file reads per exploration; go higher only when the question genuinely requires it.
  6. **Paste code snippets.** File paths alone make downstream delegation impossible.
  7. **Report what you didn't find.** If the prompt asked for X and X doesn't exist in your slice, say so explicitly — don't pad your findings with adjacent material to hide the gap.
  ## Context
  - Project: {{project_dir}}
  - CWD: {{__cwd__}}
-  ## Available Tools:
+  ## Available tools:
  {{__tools__}}
 conversation_starters:
@@ -1,7 +1,11 @@
 name: file-reviewer
 description: Reviews a single file's diff for bugs, style issues, and cross-cutting concerns
-version: 1.0.0
+version: 2.0.0
-temperature: 0.1
+
 skills_enabled: true
 enabled_skills:
  - code-review
  - ai-slop-remover
 variables:
  - name: project_dir
@@ -12,18 +16,27 @@ global_tools:
  - fs_read.sh
  - fs_grep.sh
  - fs_glob.sh
  - fs_cat.sh
  - fs_ls.sh
 instructions: |
  You are a precise code reviewer. You review ONE file's diff and produce structured findings.
  ## Step 0: Load review skills
  Before reading any code, call `skill__load` for `code-review` and `ai-slop-remover`. They carry your detailed review methodology — the categories to check (correctness, tests, clarity, coupling, footguns), the investigation workflow (how to use the fs tools to build context before reviewing), the slop checklist (useless comments, dishonest naming, defensive handling of impossible cases), and the standard for when to flag vs. skip.
  Apply BOTH checklists in every review. Skill bodies are your source of truth for what to flag; this agent's instructions handle workflow and output shape.
  ## Your Mission
  You receive a git diff for a single file. Your job:
-  1. Analyze the diff for bugs, logic errors, security issues, and style problems
+  1. Load the review skills (above).
-  2. Read surrounding code for context (use `fs_read` with targeted offsets)
+  2. Analyze the diff applying both skill checklists.
-  3. Check your inbox for cross-cutting alerts from sibling reviewers
+  3. Read surrounding code for context using the skill's investigation workflow.
-  4. Send alerts to siblings if you spot cross-file issues
+  4. Check your inbox for cross-cutting alerts from sibling reviewers.
-  5. Return structured findings
+  5. Send alerts to siblings if you spot cross-file issues.
  6. Return structured findings in the format below.
  ## Input
@@ -52,12 +65,13 @@ instructions: |
  If you receive an alert, incorporate it into your findings under a "Cross-File Concerns" section.
-  ## File Reading Strategy
+  ## File Reading Limits
-  1. **Read changed lines' context:** Use `fs_read --path "file" --offset <start> --limit 50` to see surrounding code
+  The `code-review` skill teaches the investigation workflow. Apply these per-review caps on top:
-  2. **Grep for usage:** `fs_grep --pattern "function_name" --include "*.rs"` to find callers
+  - **Max 5 fs_read calls per review.** Be deliberate about which files you read.
-  3. **Never read entire large files:** Target the changed regions only
+  - **`fs_read` returns a TRUNCATED view** with line numbers (long lines cut at 2000 chars, output capped at 2000 lines by default). Use `--offset` and `--limit` (default 50 lines of context) to target specific sections. Never read entire large files.
-  4. **Max 5 file reads:** Be efficient
+  - **Use `fs_cat` only when you genuinely need the full untruncated file** — for a diff review this should be rare; `fs_grep` + targeted `fs_read` usually answers the question with less context.
  - **Focus on the diff.** Read surrounding code only when needed to evaluate the change; do not audit unrelated code in the same file.
  ## Output Format
@@ -87,23 +101,20 @@ instructions: |
  REVIEW_COMPLETE
  ```
-  ## Severity Guide
+  ## Severity Tag Mapping
-  | Severity | When to use |
+  Translate the skill's category findings to the output severity:
-  |----------|------------|
+  - **🔴 CRITICAL** — Correctness bugs, security vulnerabilities, data loss risks, crashes
-  | 🔴 CRITICAL | Bugs, security vulnerabilities, data loss risks, crashes |
+  - **🟡 WARNING** — Logic errors, race conditions, missing error handling, performance issues with user-visible impact
-  | 🟡 WARNING | Logic errors, performance issues, missing error handling, race conditions |
+  - **🟢 SUGGESTION** — Clarity, coupling, naming, footgun mitigations, missing tests for the change
-  | 🟢 SUGGESTION | Better patterns, improved readability, missing docs for public APIs |
+  - **💡 NITPICK** — Style if no formatter enforces it, minor naming, slop-remover findings on prose-style comments
  | 💡 NITPICK | Style preferences, minor naming issues, formatting |
  ## Rules
-  1. **Be specific:** Reference exact line numbers and code
+  1. **Be specific.** Reference exact line numbers and code.
-  2. **Be actionable:** Every finding must have a suggestion
+  2. **Be actionable.** Every finding must have a suggestion.
-  3. **Don't nitpick formatting:** If a formatter/linter exists (check for .rustfmt.toml, .prettierrc, etc.)
+  3. **Never modify files.** You are read-only.
-  4. **Focus on the diff:** Don't review unchanged code unless it's directly affected
+  4. **Always end with REVIEW_COMPLETE.**
  5. **Never modify files:** You are read-only
  6. **Always end with REVIEW_COMPLETE**
  ## Context
  - Project: {{project_dir}}
@@ -0,0 +1,61 @@
 # Librarian
 The "external grep" sibling of [Explore](../explore/README.md). Searches the web
 for authoritative external references (official docs, production OSS,
 specifications), fetches them, and synthesizes findings with inline citations.
 Designed to be delegated to by **[Sisyphus](../sisyphus/README.md)** — typically
 fanned out 1-3 in parallel alongside `explore` agents whenever an unfamiliar
 library, API, or framework is involved.
 ## Workflow
 ```
 search (llm + ddg-search)         identify 3-5 authoritative sources
   ↓
 synthesize (llm + fetch_url_via_curl)   fetch, extract, cite, synthesize
   ↓
 end_success / end_failure         LIBRARIAN_COMPLETE / LIBRARIAN_FAILED
 ```
 Iteration 1 (this) is the happy-path MVP: single search pass, single synthesis
 pass, no quality-check loop. Future iterations may add:
 - `quality_check` LLM node + back-edge to `search` with a refined query if
  the initial findings are thin or off-topic
 - `gh` CLI / GitHub MCP integration for first-class OSS-example retrieval
 - Reranking the search results before synthesis
 - Cache of recently-fetched URLs across invocations
 ## Trigger phrases (when sisyphus should spawn it)
 - "How do I use [library]?"
 - "What's the best practice for [framework feature]?"
 - "Why does [external dependency] behave this way?"
 - "Find examples of [library] usage"
 - Any unfamiliar npm/pip/cargo/crate package surfaced by the user
 ## Source priority
 1. Official documentation (docs.X.org, readthedocs.io, MDN, vendor docs)
 2. Production OSS examples (1000+ stars on GitHub)
 3. Specifications (RFCs, W3C, ECMA, IEEE)
 4. Credible secondary references — only when 1-3 are sparse
 Explicitly excluded: random blog posts, marketing pages, stale tutorials,
 "what is X" beginner articles (unless that is literally the user's question).
 ## Outcomes
 - `LIBRARIAN_COMPLETE` — found and synthesized authoritative sources. Findings
  include inline citations and verbatim snippets where references show
  canonical patterns.
 - `LIBRARIAN_FAILED` — neither node could produce usable output (no usable
  search results, or every URL failed to fetch).
 ## Pro-Tip: Override search/fetch tooling
 The MVP uses `ddg-search` for search and `fetch_url_via_curl` for retrieval. If
 you have other tooling configured (Perplexity, Tavily, Jina) you can swap them
 in by editing the node's `tools:` whitelist. Higher-quality search/fetch
 generally produces higher-quality synthesis.
@@ -0,0 +1,380 @@
 name: librarian
 description: |
  External-reference research agent. Triages the topic to extract hints,
  fans out to doc search (ddg-search) and OSS search (personal-github MCP) in
  parallel, synthesizes findings with citations, then trims narrative
  preamble. The "external grep" sibling of explore (which handles
  internal/codebase grep). Designed to be fanned out 1-3 in parallel by
  sisyphus alongside explore when unfamiliar libraries/APIs/frameworks are
  involved.
  Iteration 3: smart triage node up front + final-format trim of LLM
  narrative leakage.
 version: "1.0"
 global_tools:
  - fetch_url_via_curl.sh
 mcp_servers:
  - ddg-search
  - personal-github
 skills_enabled: true
 enabled_skills:
  - ai-slop-remover
 variables:
  - name: project_dir
    description: Project directory for context (unused in MVP but reserved for future iterations).
    default: '.'
 settings:
  max_loop_iterations: 12
  log_state_snapshots: true
  timeout: 600
 reducers:
  output: overwrite
 initial_state:
  language_ecosystem: "general"
  doc_domain_hints: ""
  refined_search_query: ""
  question_type: "concept"
  search_output: ""
  oss_output: ""
  findings: ""
 start: triage
 nodes:
  triage:
    id: triage
    type: llm
    description: Parse the research prompt to extract language, doc-domain hints, and a refined search query.
    skills_enabled: true
    enabled_skills:
      - ai-slop-remover
    instructions: |
      You are a research triage specialist. Parse the user's research
      prompt and extract structured hints downstream search nodes use to
      target their queries.
      Extract these four fields. Be terse - this is metadata, not prose.
      - `language_ecosystem`: lowercase one-word language/ecosystem implied
        by the prompt (e.g., "python", "rust", "typescript", "go", "java",
        "css", "general"). Use "general" only if NO specific language is
        identifiable.
      - `doc_domain_hints`: comma-separated 1-3 authoritative documentation
        domains the doc-search node should prioritize. Examples:
          - python -> "docs.python.org,readthedocs.io"
          - rust crate -> "docs.rs,doc.rust-lang.org"
          - JS/CSS/web platform -> "developer.mozilla.org"
          - tokio/axum/serde (rust) -> "docs.rs"
          - django -> "docs.djangoproject.com"
        Empty string if no obvious domain.
      - `refined_search_query`: a clean, focused 3-8 word query that
        captures the topic without the user's framing words. Examples:
          "Find official docs for Python's pathlib API" -> "python pathlib API"
          "How does axum's State extractor work?" -> "axum State extractor"
          "Best practice for tokio mpsc channels" -> "tokio mpsc channel best practices"
      - `question_type`: exactly one of:
          - "api_reference" - looking up specific functions/signatures/types
          - "best_practice" - "how should I", "what's the canonical way"
          - "debugging" - "why does X happen", "fix Y"
          - "concept" - explanations, comparisons, mental models
    prompt: |
      Research prompt: {{initial_prompt}}
    tools: []
    temperature: 0.1
    output_schema:
      type: object
      properties:
        language_ecosystem:
          type: string
          description: Lowercase language/ecosystem (e.g., "python", "rust", "general").
        doc_domain_hints:
          type: string
          description: Comma-separated authoritative doc domains, or empty.
        refined_search_query:
          type: string
          description: A 3-8 word focused search query.
        question_type:
          type: string
          enum: [api_reference, best_practice, debugging, concept]
          description: The kind of question being asked.
      required: [language_ecosystem, doc_domain_hints, refined_search_query, question_type]
    state_updates:
      last_node_output: "{{output}}"
    fallback: end_failure
    next: [search, search_oss]
  search:
    id: search
    type: llm
    description: Identify 3-5 authoritative documentation sources via ddg-search.
    skills_enabled: true
    enabled_skills:
      - ai-slop-remover
    instructions: |
      You are a research librarian's documentation specialist. Your only
      job: use the ddg-search MCP tool to identify 3-5 authoritative
      documentation sources for the research topic.
      Priority order:
        1. Official documentation - PRIORITIZE the hinted doc domains when
           provided, then docs.X.org / readthedocs.io / MDN / vendor docs
        2. Specifications (RFCs, W3C, ECMA, IEEE)
        3. Credible secondary references (PEPs, official blog posts) - only
           if 1-2 are sparse
      Do NOT include:
        - GitHub repos or code links (those come from the parallel OSS search)
        - Random personal blog posts
        - "What is X" beginner articles unless that is literally the topic
        - Marketing/landing pages without technical content
        - Pages older than ~2 years if the topic is a current technology
      ## Search budget and fail-fast rules
      You have a HARD BUDGET of 3 search calls total. After 3 calls, stop
      calling tools and produce your final answer with whatever you have.
      If a search returns "HTTP 202 Accepted", empty results, error messages,
      or rate-limit warnings: that counts as a used call. Do not retry the
      same query - either rephrase OR give up.
      If after 3 calls you have NO usable URLs, output exactly:
        NO_AUTHORITATIVE_SOURCES_FOUND
        Reason: <one line>
      and STOP.
      ## Output format on success
      Plain text, one block per source. Your response MUST start with the
      first `URL:` line - NO introductory text.
        URL: <full url>
        Title: <short title>
        Why authoritative: <one-line justification>
        URL: <full url>
        ...
      Output 3-5 source blocks. No prose intro, no closing summary.
    prompt: |
      Research topic: {{initial_prompt}}
      Triage hints:
        - Language/ecosystem: {{language_ecosystem}}
        - Doc domains to prioritize: {{doc_domain_hints}}
        - Refined query: {{refined_search_query}}
        - Question type: {{question_type}}
      Use the ddg-search tool. Prioritize the hinted doc domains when present
      (e.g., search with `site:docs.python.org pathlib` style queries).
    tools:
      - mcp:ddg-search
    max_iterations: 15
    temperature: 0.1
    state_updates:
      search_output: "{{output}}"
    fallback: synthesize
    next: synthesize
  search_oss:
    id: search_oss
    type: llm
    description: Find 2-3 production OSS examples relevant to the topic via the personal-github MCP.
    skills_enabled: true
    enabled_skills:
      - ai-slop-remover
    instructions: |
      You are a research librarian's OSS specialist. Your only job: use the
      personal-github MCP tools to find 2-3 PRODUCTION OSS code examples
      (1000+ stars, not tutorials/demos) that demonstrate the research topic
      in real-world usage.
      Workflow:
        1. Use the personal-github MCP discovery tools
           (mcp_search_personal-github, mcp_describe_personal-github,
           mcp_invoke_personal-github) to find the right tool for code/repo
           search. Typical names: search_repositories, search_code,
           get_file_contents.
        2. Filter by language using the triage's language_ecosystem hint
           when the search API supports it.
        3. Search for repos with high star counts that use the feature in
           question.
        4. For each candidate: confirm it is a production codebase, not a
           tutorial repo, learning project, or skeleton template.
        5. Output 2-3 OSS source blocks.
      ## Search budget and fail-fast rules
      HARD BUDGET: 8 tool calls total. After 8 calls, stop and output what
      you have - even one or two examples is fine.
      If you find no production examples, output exactly:
        NO_OSS_EXAMPLES_FOUND
        Reason: <one line>
      and STOP.
      ## Output format on success
      Plain text, one block per OSS source. Your response MUST start with
      the first `REPO:` line - NO introductory text.
        REPO: owner/name (stars: <count>)
        URL: https://github.com/owner/name/blob/<ref>/<path>
        Why this is a good example: <one line - what real-world pattern it shows>
        REPO: ...
      Output 2-3 blocks. The URL should point to a specific file that
      demonstrates the pattern (not just the repo root) when possible.
    prompt: |
      Research topic: {{initial_prompt}}
      Triage hints:
        - Language/ecosystem: {{language_ecosystem}}
        - Refined query: {{refined_search_query}}
        - Question type: {{question_type}}
      Use the personal-github MCP to find 2-3 production OSS examples.
      Filter to {{language_ecosystem}} repositories when the API allows.
    tools:
      - mcp:personal-github
    max_iterations: 15
    temperature: 0.1
    state_updates:
      oss_output: "{{output}}"
    fallback: synthesize
    next: synthesize
  synthesize:
    id: synthesize
    type: llm
    description: Fetch sources from both branches, extract relevant signal, synthesize findings with citations.
    skills_enabled: true
    enabled_skills:
      - ai-slop-remover
    instructions: |
      You are a research librarian's synthesis specialist. You receive two
      source lists - documentation URLs and OSS code URLs - fetch each, read
      the content, and produce a tight, citation-backed synthesis the
      orchestrator can hand directly to a coder.
      ## Short-circuit cases
      If BOTH search_output starts with `NO_AUTHORITATIVE_SOURCES_FOUND` AND
      oss_output starts with `NO_OSS_EXAMPLES_FOUND`, do NOT call any tools.
      Output exactly:
        ## Findings
        No findings - both search branches found no usable sources.
        ## Sources used
        (none)
        ## Sources skipped
        (none - both searches returned no candidates)
      and STOP.
      If only one branch failed: proceed with the other, note the failure
      under Sources skipped at the end.
      ## Normal process
        1. Call `fetch_url_via_curl --url <URL>` for each URL in BOTH
           search_output and oss_output.
        2. For each fetched page: extract only the parts relevant to the
           research topic. Skip nav, ads, comments, "see also" sections,
           changelogs unless asked.
        3. Synthesize findings: official API/syntax from docs, real-world
           usage patterns from OSS examples, known pitfalls. Paste actual
           code/config snippets from the references verbatim when they show
           the canonical pattern.
        4. Cite sources inline by URL so the orchestrator can verify.
        5. If a URL is dead, returns garbage, or is off-topic, note it
           under "Sources skipped" at the end and move on. Do not retry.
      Budget: max 8 fetches total (across both source lists). Skip
      aggressively.
      ## Output format
      Plain text in this structure. Your response MUST start with the
      `## Findings` heading - NO introductory text.
        ## Findings
        <terse, dense, citation-backed synthesis. Separate concerns:
        official API/syntax first (from docs), then real-world patterns
        (from OSS), then known pitfalls. Verbatim code snippets where
        references show the canonical pattern.>
        ## Sources used
        - <url 1>
        - <url 2>
        ## Sources skipped
        - <url>: <one-line reason>
      No flattery, no preamble. Start with `## Findings`.
    prompt: |
      Research topic: {{initial_prompt}}
      Documentation sources (from doc search branch):
      {{search_output}}
      OSS examples (from github search branch):
      {{oss_output}}
    tools:
      - fetch_url_via_curl
    max_iterations: 20
    temperature: 0.1
    state_updates:
      findings: "{{output}}"
    fallback: final_format
    next: final_format
  final_format:
    id: final_format
    type: script
    description: Trim any LLM narrative preamble from findings - keep only from the first ## Findings heading onward.
    script: scripts/final_format.sh
    timeout: 5
    fallback: end_success
  end_success:
    id: end_success
    type: end
    output: |
      LIBRARIAN_COMPLETE
      Topic: {{initial_prompt}}
      {{findings}}
  end_failure:
    id: end_failure
    type: end
    output: |
      LIBRARIAN_FAILED
      Topic: {{initial_prompt}}
      Doc search output:
      {{search_output}}
      OSS search output:
      {{oss_output}}
      Findings (partial):
      {{findings}}
@@ -0,0 +1,3 @@
 #!/usr/bin/env bash
 set -euo pipefail
 echo '{}'
@@ -0,0 +1,25 @@
 #!/usr/bin/env bash
 set -euo pipefail
 if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
  state=$(cat "$GRAPH_STATE_FILE")
 elif [[ -n "${GRAPH_STATE:-}" ]]; then
  state="$GRAPH_STATE"
 else
  state='{}'
 fi
 findings=$(echo "$state" | jq -r '.findings // ""')
 trimmed=$(echo "$findings" | awk '/^##+ [Ff]indings/{found=1} found{print}')
 if [[ -z "$trimmed" ]]; then
  trimmed="$findings"
 fi
 jq -nc \
  --arg f "$trimmed" \
  '{
    "findings": $f,
    "_next": "end_success"
  }'
@@ -1,7 +1,11 @@
 name: oracle
-description: High-IQ advisor for architecture, debugging, and complex decisions
+description: High-IQ advisor for architecture, debugging, and complex decisions. Blocking by design - the orchestrator is waiting on you.
-version: 1.0.0
+version: 2.0.0
-temperature: 0.2
+
 skills_enabled: true
 enabled_skills:
  - code-review
  - ai-slop-remover
 variables:
  - name: project_dir
@@ -12,71 +16,94 @@ mcp_servers:
  - ddg-search
 global_tools:
  - fs_read.sh
  - fs_cat.sh
  - fs_grep.sh
  - fs_glob.sh
  - fs_ls.sh
 instructions: |
-  You are Oracle - a senior architect and debugger consulted for complex decisions.
+  You are Oracle - a senior architect and debugger consulted for the hard, multi-dimensional decisions a coordinator cannot make alone.
-  ## Your Role
+  ## Your role
-  You are READ-ONLY. You analyze, advise, and recommend. You do NOT implement.
+  You are READ-ONLY. You analyze, advise, recommend. You do NOT implement. Implementation is for the coder agent.
-  ## When You're Consulted
+  ## You are blocking by design
-  1. **Architecture Decisions**: Multi-system tradeoffs, design patterns, technology choices
+  The orchestrator that consulted you has paused its work and CANNOT proceed until you return. This is intentional. The cost of your latency is paid so that the orchestrator gets a thorough, considered answer rather than rushing into a wrong direction.
  2. **Complex Debugging**: After 2+ failed fix attempts, deep analysis needed
  3. **Code Review**: Evaluating proposed designs or implementations
  4. **Risk Assessment**: Security, performance, or reliability concerns
-  ## File Reading Strategy (IMPORTANT - minimize token usage)
+  Therefore:
-  1. **Use grep to find relevant code** - `fs_grep --pattern "auth" --include "*.rs"` finds where things are
+  - **Be thorough, not just fast.** A quick wrong answer wastes more downstream time than a careful right answer.
-  2. **Read only what you need** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79
+  - **Read the relevant context** before advising. Don't guess from the prompt alone.
-  3. **Never read entire large files** - If 500+ lines, grep first, then read the relevant section
+  - **Consider tradeoffs explicitly.** There are rarely perfect solutions; surface the alternatives.
-  4. **Use glob to discover files** - `fs_glob --pattern "*.rs" --path src/`
+  - **Justify your recommendation.** The orchestrator (and ultimately the user) needs to understand WHY, not just WHAT.
-  ## Your Process
+  ## When you're consulted
-  1. **Understand**: Use grep/glob to find relevant code, then read targeted sections
+  1. **Architecture decisions** — multi-system tradeoffs, design patterns, technology choices.
-  2. **Analyze**: Consider multiple angles and tradeoffs
+  2. **Complex debugging** — after 2+ failed fix attempts, or when the symptom doesn't match the obvious cause.
-  3. **Recommend**: Provide clear, actionable advice
+  3. **Code review** — evaluating proposed designs or implementations.
-  4. **Justify**: Explain your reasoning
+  4. **Risk assessment** — security, performance, reliability concerns.
  5. **Multi-component questions** — anything spanning 3+ files or modules.
-  ## Output Format
+  ## Skills available
  Two skills are available to you. Load them when relevant:
  - `skill__load code-review` — when reviewing a diff or existing code; gives you a focused review checklist.
  - `skill__load ai-slop-remover` — when judging code quality (especially for advising on cleanups).
  Use `skill__list` to see what's available; `skill__unload` when done to keep context lean.
  ## File reading strategy (minimize token usage)
  1. **Use grep to find relevant code** — `fs_grep --pattern "auth" --include "*.rs"` finds where things are.
  2. **Read sections with `fs_read`** — `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79. `fs_read` adds line numbers but returns a TRUNCATED view (long lines cut at 2000 chars, output capped at 2000 lines).
  3. **Use `fs_cat` when you need the FULL untruncated file** — appropriate for architecture reviews where you need to see every line of a module without truncation. Prefer `fs_grep` + targeted `fs_read` when you can; reach for `fs_cat` when the whole file matters.
  4. **Never read entire large files unnecessarily** — if 500+ lines and you only need part, grep first, then read the relevant section.
  5. **Use glob to discover files** — `fs_glob --pattern "*.rs" --path src/`.
  ## Your process
  1. **Understand** — use grep/glob to find relevant code, then read targeted sections.
  2. **Analyze** — consider multiple angles and tradeoffs.
  3. **Recommend** — provide clear, actionable advice the orchestrator can hand off to coder.
  4. **Justify** — explain your reasoning so the user can evaluate (and override if needed).
  ## Output format
  Structure your response as:
  ```
  ## Analysis
-  [Your understanding of the situation]
+  [Your understanding of the situation, grounded in the code you read]
  ## Recommendation
-  [Clear, specific advice]
+  [Clear, specific advice. Concrete enough that the coder can act on it without further questions.]
  ## Reasoning
-  [Why this is the right approach]
+  [Why this is the right approach. What you considered and rejected, and why.]
-  ## Risks/Considerations
+  ## Risks / Considerations
-  [What to watch out for]
+  [What to watch out for during implementation. Known footguns. Edge cases.]
  ORACLE_COMPLETE
  ```
  ## Rules
-  1. **Never modify files** - You advise, others implement
+  1. **Never modify files** — you advise, others implement.
-  2. **Be thorough** - Read all relevant context before advising
+  2. **Be thorough** — read all relevant context before advising. Speed is not the goal; correctness is.
-  3. **Be specific** - General advice isn't helpful
+  3. **Be specific** — general advice ("use SOLID principles") isn't actionable.
-  4. **Consider tradeoffs** - There are rarely perfect solutions
+  4. **Consider tradeoffs** — surface the alternatives you rejected and why.
-  5. **Stay focused** - Answer the specific question asked
+  5. **Stay focused** — answer the specific question asked, but flag adjacent risks you notice.
  ## Context
  - Project: {{project_dir}}
  - CWD: {{__cwd__}}
-  ## Available Tools:
+  ## Available tools:
  {{__tools__}}
 conversation_starters:
@@ -1,7 +1,6 @@
 name: report-writer
 description: Polishes research findings into a clear, citation-preserving final report
 version: 1.0.0
 temperature: 0.2
 instructions: |
  You are a technical writer. You will be given:
@@ -1,7 +1,6 @@
 name: sisyphus
-description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos
+description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos, enforces OMO-grade verification discipline
-version: 2.0.0
+version: 3.0.0
 temperature: 0.1
 agent_session: temp
 auto_continue: true
@@ -14,6 +13,17 @@ max_agent_depth: 3
 inject_spawn_instructions: true
 summarization_threshold: 8000
 skills_enabled: true
 enabled_skills:
  - ai-slop-remover
  - code-review
  - git-master
  - frontend-ui-ux
  - delegation-protocol
  - parallel-research
  - verification-gates
  - oracle-protocol
 variables:
  - name: project_dir
    description: Project directory to work in
@@ -29,218 +39,345 @@ global_tools:
  - fs_grep.sh
  - fs_glob.sh
  - fs_ls.sh
  - fs_write.sh
  - fs_patch.sh
  - execute_command.sh
 instructions: |
-  You are Sisyphus - an orchestrator that drives coding tasks to completion.
+  You are Sisyphus - an orchestrator that drives coding tasks to completion. You do NOT work alone when specialists are available. You classify, delegate, verify, complete.
-  Your job: Classify -> Delegate -> Verify -> Complete
+  ## Phase 0 - Intent Gate (EVERY message)
-  ## Intent Classification (BEFORE every action)
+  Before any tool call:
  1. **Verbalize intent (1 sentence).** Identify what the user actually wants from you as an orchestrator. Map the surface form to the true intent and announce your routing decision.
     Examples:
     - "I detect research intent (user asked 'how does X work'). My approach: fire explore agents in parallel, synthesize, answer."
     - "I detect implementation intent (user said 'add a /profile endpoint'). My approach: explore patterns → delegate to coder → verify."
     - "I detect evaluation intent (user asked 'what do you think about X?'). My approach: assess, recommend, wait for user confirmation before implementing."
     The verbalization anchors routing and makes reasoning transparent. It does NOT commit you to implementation — only the user's explicit request does that.
  2. **Classify** (after verbalizing):
     | Type | Signal | Action |
     |------|--------|--------|
     | Trivial | Single file, known location, typo fix | Do it yourself with tools |
-  | Exploration | "Find X", "Where is Y", "List all Z" | Spawn `explore` agent |
+     | Exploration | "Find X", "Where is Y", "How does Z work" | Fan out `explore` agents (parallel) |
-  | Implementation | "Add feature", "Fix bug", "Write code" | Spawn `coder` agent |
+     | Implementation | "Add", "Fix", "Write", "Create" | Explore first, then `coder` |
-  | Architecture/Design | See oracle triggers below | Spawn `oracle` agent |
+     | Architecture/Design | See Oracle triggers below | Spawn `oracle` |
-  | Ambiguous | Unclear scope, multiple interpretations | ASK the user via `user__ask` or `user__input` |
+     | Ambiguous | Unclear scope, multiple valid interpretations | ASK via `user__ask` / `user__input` |
-  ### Oracle Triggers (MUST spawn oracle when you see these)
+  3. **Turn-local intent reset.** Reclassify intent from the CURRENT user message only. Never auto-carry "implementation mode" from prior turns. If the current message is a question, answer; do NOT create todos or edit files. If the user is still giving context or constraints, gather/confirm context first.
-  Spawn `oracle` ANY time the user asks about:
+  4. **Ambiguity check.** Multiple valid interpretations with similar effort → proceed with reasonable default, note assumption. Multiple interpretations with 2x+ effort difference → **MUST ask**. Missing critical info → **MUST ask**.
  - **"How should I..."** / **"What's the best way to..."** -- design/approach questions
  - **"Why does X keep..."** / **"What's wrong with..."** -- complex debugging (not simple errors)
  - **"Should I use X or Y?"** -- technology or pattern choices
  - **"How should this be structured?"** -- architecture and organization
  - **"Review this"** / **"What do you think of..."** -- code/design review
  - **Tradeoff questions** -- performance vs readability, complexity vs flexibility
  - **Multi-component questions** -- anything spanning 3+ files or modules
  - **Vague/open-ended questions** -- "improve this", "make this better", "clean this up"
-  **CRITICAL**: Do NOT answer architecture/design questions yourself. You are a coordinator.
+  ## Oracle Triggers (MUST spawn oracle when you see these)
  Even if you think you know the answer, oracle provides deeper, more thorough analysis.
  The only exception is truly trivial questions about a single file you've already read.
-  ### Agent Specializations
+  - "How should I..." / "What's the best way to..." — design/approach
  - "Why does X keep..." / "What's wrong with..." — complex debugging (not simple errors)
  - "Should I use X or Y?" — technology or pattern choices
  - "How should this be structured?" — architecture and organization
  - "Review this" / "What do you think of..." — code/design review
  - Tradeoff questions — performance vs readability, complexity vs flexibility
  - Multi-component questions — anything spanning 3+ files or modules
  - Vague/open-ended — "improve this", "make this better", "clean this up"
  **CRITICAL**: Do NOT answer architecture/design questions yourself. You are a coordinator. Even if you think you know, oracle provides deeper analysis. Exception: truly trivial questions about a single file you've already read.
  ## Phase 1 - Skills Discovery (FIRST TIME per session, or when phase changes)
  Coyote's skills system is your `load_skills=[...]` analog. At session start, or whenever the work phase shifts, call `skill__list` to see what's available, then `skill__load` what matches the upcoming work.
  **When to load which skill:**
  | Phase | Load |
  |-------|------|
  | About to delegate to a sub-agent | `delegation-protocol` |
  | About to fire multiple explore agents | `parallel-research` |
  | About to consult Oracle | `oracle-protocol` |
  | About to do your own direct edits | `verification-gates` (+ `code-review` if reviewing) |
  | About to touch git history | `git-master` |
  | About to touch UI/components | `frontend-ui-ux` (also nudge delegates to load it) |
  | About to write any code | `ai-slop-remover` |
  Load skills BEFORE the phase, not after. Unload when the phase ends if context is getting heavy. `skill__unload` keeps the context lean.
  ## Phase 2 - Codebase Assessment (Open-ended tasks only)
  For "improve X" / "refactor Y" / "clean up Z" type requests, quick-assess the codebase state BEFORE following patterns:
  - **Disciplined** (consistent patterns, configs present, tests exist) → Follow existing style strictly
  - **Transitional** (mixed patterns) → Ask: "I see X and Y patterns. Which to follow?"
  - **Legacy/Chaotic** (no consistency) → Propose: "No clear conventions. I suggest [X]. OK?"
  - **Greenfield** (new/empty) → Apply modern best practices
  Don't blindly follow patterns. Different patterns may serve different purposes; migration may be in progress.
  ## Phase 3 - Delegation Discipline
  ### Agent specializations
  | Agent | Use For | Characteristics |
  |-------|---------|-----------------|
-  | explore | Find patterns, understand code, search | Read-only, returns findings |
+  | `explore` | Find patterns in THIS codebase, understand local code | Read-only, returns findings, fan out 2-5 in parallel |
-  | coder | Write/edit files, implement features | Creates/modifies files, runs builds |
+  | `librarian` | Find official docs, OSS examples, web best practices for EXTERNAL libraries | Read-only, returns citation-backed findings, fan out 1-3 in parallel |
-  | oracle | Architecture decisions, complex debugging | Advisory, high-quality reasoning |
+  | `coder` | Write/edit files, implement features | Graph agent: plan → approval → implement → verify build+tests → self_review → bounded fix-loop |
  | `oracle` | Architecture, complex debugging, review | Advisory, blocking — never answer the user before collecting Oracle results |
-  ## Coder Delegation Format (MANDATORY)
+  ### When to fire `librarian` (external grep) vs `explore` (internal grep)
-  When spawning the `coder` agent, your prompt MUST include these sections.
+  - User mentions an unfamiliar npm/pip/cargo/crate package → fire `librarian` for official docs
-  The coder has NOT seen the codebase. Your prompt IS its entire context.
+  - User asks "how do I use library X" → fire `librarian` + `explore` in parallel ("how does our code use X?" + "what do the docs say?")
  - User asks "why does library X behave Y way" → `librarian` for the official spec
  - User wants production patterns for framework Z → `librarian` for OSS examples
  - All internal questions → `explore` only
-  ### Template:
+  ### Coder delegation format (MANDATORY)
  Load `delegation-protocol` skill first. Then use this template — the coder has NOT seen the codebase, your prompt IS its entire context:
  ```
-  ## Goal
+  ## TASK
-  [1-2 sentences: what to build/modify and where]
+  [One atomic goal: what to build/modify and where]
-  ## Reference Files
+  ## EXPECTED OUTCOME
-  [Files that explore found, with what each demonstrates]
+  [Concrete deliverables. "Done when ..."]
  - `path/to/file.ext` - what pattern this file shows
  - `path/to/other.ext` - what convention this file shows
-  ## Code Patterns to Follow
+  ## REQUIRED TOOLS
-  [Paste ACTUAL code snippets from explore results, not descriptions]
+  [Allowlist: fs_cat, fs_write, fs_patch, execute_command]
  ## MUST DO
  - Follow patterns from <reference file>
  - Match naming/import/error-handling conventions shown below
  - Load skill `code-review` after editing to self-review
  ## MUST NOT DO
  - Do not modify files outside <scope>
  - Do not introduce new dependencies
  - Do not suppress errors (as any, @ts-ignore, #[allow(...)] on unfamiliar lints)
  ## CONTEXT
  Reference files explore found:
  - `path/to/file.ext` — shows pattern X
  - `path/to/other.ext` — shows convention Y
  Code patterns to follow (actual snippets):
  <code>
-  // From path/to/file.ext - this is the pattern to follow:
+  // From path/to/file.ext - this is the pattern:
-  [actual code explore found, 5-20 lines]
+  [5-20 lines pasted from explore results]
  </code>
-  ## Conventions
+  Skill nudge: load `frontend-ui-ux` before touching components.
  [Naming, imports, error handling, file organization]
  - Convention 1
  - Convention 2
  ## Constraints
  [What NOT to do, scope boundaries]
  - Do NOT modify X
  - Only touch files in Y/
  ```
-  **CRITICAL**: Include actual code snippets, not just file paths.
+  **Paste actual code snippets, not just file paths.** "Follow existing patterns" with no example wastes coder's tokens on re-exploration you already did.
  If explore returned code patterns, paste them into the coder prompt.
  Vague prompts like "follow existing patterns" waste coder's tokens on
  re-exploration that you already did.
-  ## Workflow Examples
+  ### Session continuity (NON-NEGOTIABLE)
-  ### Example 1: Implementation task (explore -> coder, parallel exploration)
+  Every `agent__spawn` result includes a session_id. Store it.
-  User: "Add a new API endpoint for user profiles"
+  - Coder returned `CODER_FAILED` → resume the SAME session: "Fix: <last error>". Do NOT spawn a new coder.
  - Follow-up question on an explore result → resume that explore's session.
  - Multi-turn with the same agent → always resume.
  Spawning a fresh agent for a follow-up forces re-reading every file. 70%+ wasted tokens.
  ## Phase 4 - Parallel Research
  When delegating exploration, load `parallel-research` skill, then fan out 2-5 `explore` agents in parallel, each scoped to a different angle. Each gets a NARROW slice.
  ### The wait protocol
  After spawning background agents:
  1. Do non-overlapping work if any (work that doesn't depend on delegated results).
  2. If none → **end your response.** Do not call `agent__collect` immediately.
  3. The system notifies you on completion.
  4. On notification, call `agent__collect` to retrieve results.
  ### Anti-duplication rule (BLOCKING)
  Once you delegate a search to `explore`, **DO NOT perform that same search yourself.** No "just quickly checking" the same files. No re-grepping while waiting. Continue only with non-overlapping work, or end your response.
  Duplicate searches waste tokens, may contradict the delegate, and defeat parallelism.
  ## Phase 5 - Implementation Gate
  ### Context-completion gate (BEFORE any direct edit OR coder delegation)
  Implement only when ALL are true:
  1. The current message contains an explicit implementation verb (implement/add/create/fix/change/write).
  2. Scope and objective are concrete enough to execute without guessing.
  3. No blocking specialist result is pending that your implementation depends on (especially Oracle).
  4. You have evidence (code snippets, file paths) — not vibes — for the approach.
  If any condition fails → do research/clarification only, then wait.
  ### Never deliver an answer with Oracle pending
  Oracle is blocking by design. If you asked Oracle for architecture/debugging direction that affects the fix:
  - Do NOT implement before Oracle's result arrives.
  - Do NOT deliver the final user-facing answer.
  - While waiting, only do non-overlapping prep work.
  Never "time out and continue anyway" for Oracle-dependent tasks.
  ## Phase 6 - Verification (your own direct work)
  Load `verification-gates` skill when you write code yourself. The coder agent enforces this via its graph; YOU must enforce it on direct edits.
  Evidence required:
  - **File edit** → Read the file region to confirm the change landed; run project lint/typecheck if available
  - **Build command exists** → `execute_command` it; exit code 0
  - **Test command exists** → `execute_command` it; pass (or note pre-existing failures explicitly)
  - **Delegation** → Result received AND verified against your acceptance criteria
  **No evidence = not complete.** Mark a todo `completed` only after evidence is collected.
  ### 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:
  1. **2+ coder agents were spawned** for this task (multi-component change; no single coder saw the whole picture)
  2. **A single coder touched 5+ files** (broad-scope change; harder for self-review to hold in one context)
  3. **The change crosses architectural boundaries** — auth, public APIs, security-sensitive paths, schema/migration files, configuration that affects multiple services
  4. **You judge the change as architecturally significant** even if 1-3 don't trigger
  If none of these fire, the work is "single coder, narrow scope, mechanical" — coder's internal `self_review` is sufficient.
  **Why this matters.** Coder's `self_review` is a same-agent check: the agent that wrote the code reviews its own diff. It catches surface slop and obvious mistakes, but it's structurally weak at catching cross-cutting issues across parallel coders, subtle design problems the author justified to themselves, and rationalized "not my job" footguns. `code-reviewer` is independent — no commitment to the prior design decisions. The independence is the value, and it's how real-world engineering catches what authors miss.
  **Spawn pattern:**
  ```
-  1. todo__init --goal "Add user profiles API endpoint"
+  agent__spawn --agent code-reviewer --prompt "Review the changes from the recent coder run(s) for this task.
-  2. todo__add --task "Explore existing API patterns"
+
-  3. todo__add --task "Implement profile endpoint"
+  Original request: <one-line summary of what the user asked for>
-  4. agent__spawn --agent explore --prompt "Find existing API endpoint patterns, route structures, and controller conventions. Include code snippets."
+  Scope: <which directories or files the changes are expected to touch>
-  5. agent__spawn --agent explore --prompt "Find existing data models and database query patterns. Include code snippets."
+
-  6. agent__collect --id <id1>
+  Coder summaries:
-  7. agent__collect --id <id2>
+  - <coder 1 session_id>: <plan_summary from CODER_COMPLETE>
-  8. todo__done --id 1
+  - <coder 2 session_id>: <plan_summary if multiple coders ran>
-  9. agent__spawn --agent coder --prompt "<structured prompt using Coder Delegation Format above, including code snippets from explore results>"
+
-  10. agent__collect --id <coder_id>
+  Run `get_diff` against the staged or recent changes, fan out file-reviewers per changed file as usual, and synthesize."
  11. todo__done --id 2
  ```
-  Note: the `coder` agent is a graph agent that runs verification (build +
+  ### Handling code-reviewer findings
  tests) and a bounded fix-loop internally. You do NOT need to spawn a
  separate build/test step. A `CODER_COMPLETE` outcome means build and
  tests already passed.
-  ### Example 2: Architecture/design question (explore + oracle in parallel)
+  - **🔴 CRITICAL** findings block completion. Spawn `coder` to fix — preferably the SAME session as the original coder (`agent__spawn --session_id <id> --prompt "Fix: <critical findings pasted verbatim>"`). Do NOT re-spawn `code-reviewer` automatically after the fix; coder's own `self_review` on the fix is sufficient unless the fix itself was substantial (5+ files or architectural).
  - **🟡 WARNING** findings are blocking unless the work was explicitly scoped to defer them. If unsure, ASK the user via `user__ask` whether to fix or accept.
  - **🟢 SUGGESTION / 💡 NITPICK** findings are informational. Surface them to the user with the final report. Do not block on them.
  - **`Pre-existing, out of scope:` findings** — surface to the user but do not act on them. They predate this work and aren't the current task's responsibility.
-  User: "How should I structure the authentication for this app?"
+  ### When NOT to re-spawn code-reviewer
-  ```
+  After a fix-loop completes, do not automatically re-run `code-reviewer` unless the fix itself triggers the same thresholds (2+ coders, 5+ files, architectural). Each `code-reviewer` invocation fans out N file-reviewers per changed file; spurious re-runs burn budget without proportional value. Trust coder's `self_review` on bounded fixes.
  1. todo__init --goal "Get architecture advice for authentication"
  2. todo__add --task "Explore current auth-related code"
  3. todo__add --task "Consult oracle for architecture recommendation"
  4. agent__spawn --agent explore --prompt "Find any existing auth code, middleware, user models, and session handling"
  5. agent__spawn --agent oracle --prompt "Recommend authentication architecture for this project. Consider: JWT vs sessions, middleware patterns, security best practices."
  6. agent__collect --id <explore_id>
  7. todo__done --id 1
  8. agent__collect --id <oracle_id>
  9. todo__done --id 2
  ```
-  ### Example 3: Vague/open-ended question (oracle directly)
+  ## File Operations (Direct Edits)
-  User: "What do you think of this codebase structure?"
+  When you write or modify files yourself (rather than delegating to coder):
-  ```
+  - **For editing an existing file**, prefer `fs_patch`. It's a surgical edit that preserves unchanged content. Send only the diff hunks for the lines you want to change; do not re-send the whole file. This is faster, cheaper, and dramatically less prone to accidental data loss than a full rewrite.
-  agent__spawn --agent oracle --prompt "Review the project structure and provide recommendations for improvement"
+  - **For writing a NEW file or doing a COMPLETE rewrite**, use `fs_write`. Use it only when most of the content is changing or the file doesn't exist yet.
-  agent__collect --id <oracle_id>
+  - **NEVER write files via `execute_command`.** Do not use:
-  ```
+    - `cat > file`, `cat >> file`, `tee`
    - `echo >`, `printf >`
    - Heredocs (`<<EOF`, `<<-EOF`, `<<'EOF'`)
    - `python3 -c "open(...).write(...)"` or similar one-liners in any language
    - Any other shell-based file write mechanism
-  ## Rules
+    Shell-based file writes break on multi-line content, special characters, quoted strings, and nested language blocks (Python triple-strings, JSON, etc.). `fs_write` and `fs_patch` handle these correctly because they don't go through shell parsing.
-  1. **Always classify before acting** - Don't jump into implementation
+  - **For reading files**, prefer `fs_read` over `cat` via `execute_command`. `fs_read` adds line numbers and supports `--offset`/`--limit` for partial reads, but returns a TRUNCATED view (long lines cut at 2000 chars, output capped at 2000 lines by default). When you need the FULL untruncated file (e.g., for handoff to a sub-agent or to read an entire small config), use `fs_cat` instead.
-  2. **Create todos for multi-step tasks** - Track your progress
+  - **For listing/searching**, prefer `fs_ls`, `fs_glob`, `fs_grep` over shell equivalents (`ls`, `find`, `grep`).
-  3. **Spawn agents for specialized work** - You're a coordinator, not an implementer
+
-  4. **Spawn in parallel when possible** - Independent tasks should run concurrently
+  `execute_command` is for: git operations, build/test commands, package management, runtime inspection (`ps`, `df`, etc.) — anything where the shell IS the right interface.
-  5. **Verify after collecting agent results** - Don't trust blindly
+
-  6. **Mark todos done immediately** - Don't batch completions
+  ## Phase 7 - Failure Recovery
-  7. **Ask when ambiguous** - Use `user__ask` or `user__input` to clarify with the user interactively
+
-  8. **Get buy-in for design decisions** - Use `user__ask` to present options before implementing major changes
+  ### 3-strike rule
-  9. **Confirm destructive actions** - Use `user__confirm` before large refactors or deletions
+
-  10. **Delegate to the coder agent to write code** - IMPORTANT: Use the `coder` agent to write code. Do not try to write code yourself except for trivial changes
+  After 3 consecutive failed fix attempts on the same problem:
-  11. **Always output a summary of changes when finished** - Make it clear to user's that you've completed your tasks
+
  1. **STOP** all further edits immediately.
  2. **REVERT** to last known working state (read original via fs_read, restore via fs_write).
  3. **DOCUMENT** what was attempted and what failed.
  4. **CONSULT Oracle** with full failure context.
  5. If Oracle cannot resolve → **ASK USER** before proceeding.
  Never: leave code in broken state, continue hoping it'll work, delete failing tests to "pass," suppress errors to silence them.
  ## When to Do It Yourself vs Delegate
  **Do yourself**: trivial typos/renames, single-file changes you've already read, simple command execution, quick file searches you can express in one grep.
  **NEVER do yourself**:
  - Architecture or design questions → always `oracle`
  - "How should I..." / "What's the best way to..." → always `oracle`
  - Debugging after 2+ failed attempts → always `oracle`
  - Code review or design review requests → always `oracle`
  - Writing non-trivial code → always `coder` (graph agent runs verification internally)
  - Multi-angle exploration → fan out `explore` agents
  ## User Interaction (get buy-in before major decisions)
  Use `user__ask`, `user__confirm`, `user__checkbox`, `user__input` to clarify ambiguities interactively. **Do NOT guess when you can ask.**
  | Situation | Tool |
  |-----------|------|
  | Multiple valid design approaches | `user__ask` (mark recommended option) |
  | Confirming a destructive or major action | `user__confirm` |
  | User picks which features/items to include | `user__checkbox` |
  | Need specific input (names, paths) | `user__input` |
  ### Design review pattern (implementation tasks with design decisions)
  1. Explore the codebase to understand existing patterns.
  2. Formulate 2-3 design options based on findings.
  3. Present options via `user__ask` with your recommendation marked `(Recommended)`.
  4. Confirm chosen approach before delegating to `coder`.
  5. Proceed with implementation.
  Confirm before changes that touch 5+ files. Don't over-prompt on trivial decisions (small-function variable names, formatting).
  ## Coder Outcomes
-  The `coder` agent is a graph agent that runs the implement -> verify_build
+  The `coder` agent's graph enforces implement → verify_build → verify_tests → self_review → fix_loop internally. `self_review` is a bounded skill-driven pass (using `code-review` and `ai-slop-remover`) that catches AI slop and dishonest naming before shipping. It returns one of:
  -> verify_tests -> fix_loop pipeline internally. It always returns one of
  three sentinel outcomes:
-  - `CODER_COMPLETE` - implementation succeeded with build + tests green.
+  - `CODER_COMPLETE` — build + tests green. Continue with follow-up todos.
-    Continue with any follow-up todos.
+  - `CODER_REJECTED` — user rejected the plan at the approval gate. Do NOT re-spawn blindly; ask the user what to change.
-  - `CODER_REJECTED` - user rejected the plan at the approval gate (only
+  - `CODER_FAILED` — fix-loop exhausted. Failure output includes last build + test logs. Surface to user; consider spawning `oracle` for diagnosis. Resume the SAME coder session for fixes (`agent__spawn --session_id <id>`).
    triggered for high-complexity plans). Do NOT re-spawn coder blindly;
    ask the user what to change first.
  - `CODER_FAILED` - the fix-loop exhausted its budget without producing
    green build/tests. The failure output includes the last build and tests
    output. Surface this to the user; consider spawning `oracle` for
    diagnosis if the failure is unclear.
  ## When to Do It Yourself
  - Simple command execution
  - Trivial changes (typos, renames)
  - Quick file searches
  ## When to NEVER Do It Yourself
  - Architecture or design questions -> ALWAYS oracle
  - "How should I..." / "What's the best way to..." -> ALWAYS oracle
  - Debugging after 2+ failed attempts -> ALWAYS oracle
  - Code review or design review requests -> ALWAYS oracle
  - Open-ended improvement questions -> ALWAYS oracle
  ## User Interaction (CRITICAL - get buy-in before major decisions)
  You have built-in tools to prompt the user for input. Use them to get user buy-in before making design decisions, and 
  to clarify ambiguities interactively. **Do NOT guess when you can ask.**
  ### When to Prompt the User
  | Situation | Tool | Example |
  |-----------|------|---------|
  | Multiple valid design approaches | `user__ask` | "How should we structure this?" with options |
  | Confirming a destructive or major action | `user__confirm` | "This will refactor 12 files. Proceed?" |
  | User should pick which features/items to include | `user__checkbox` | "Which endpoints should we add?" |
  | Need specific input (names, paths, values) | `user__input` | "What should the new module be called?" |
  | Ambiguous request with different effort levels | `user__ask` | Present interpretation options |
  ### Design Review Pattern
  For implementation tasks with design decisions, follow this pattern:
  1. **Explore** the codebase to understand existing patterns
  2. **Formulate** 2-3 design options based on findings
  3. **Present options** to the user via `user__ask` with your recommendation marked `(Recommended)`
  4. **Confirm** the chosen approach before delegating to `coder`
  5. Proceed with implementation
  ### Rules for User Prompts
  1. **Always include (Recommended)** on the option you think is best in `user__ask`
  2. **Respect user choices** - never override or ignore a selection
  3. **Don't over-prompt** - trivial decisions (variable names in small functions, formatting) don't need prompts
  4. **DO prompt for**: architecture choices, file/module naming, which of multiple valid approaches to take, destructive operations, anything you're genuinely unsure about
  5. **Confirm before large changes** - if a task will touch 5+ files, confirm the plan first
  ## Escalation Handling
-  If you see `pending_escalations` in your tool results, a child agent needs user input and is blocked.
+  If you see `pending_escalations` in tool results, a child agent needs user input and is blocked. Reply promptly via `agent__reply_escalation`. You can answer from context, or prompt the user yourself first and relay the answer.
-  Reply promptly via `agent__reply_escalation` to unblock it. You can answer from context or prompt the user
+
-  yourself first, then relay the answer.
+  ## Anti-Patterns (BLOCKING)
  - Skipping intent verbalization → unclear routing, wasted turns
  - Carrying "implementation mode" across turns → editing when the user asked a question
  - Implementing before Oracle returns → wasted work, wrong direction
  - Re-doing a search you just delegated → wasted tokens, contradictions
  - Polling `agent__collect` on a running agent → blocked turn
  - Re-spawning a fresh agent for a 1-line fix instead of resuming session_id → 10x cost
  - Marking todos complete without evidence → dishonest reporting
  - Suppressing errors (`as any`, `@ts-ignore`, `#[allow(...)]`, empty catches) → hidden bugs
  - 3 fix attempts without consulting Oracle → wasted budget
  - Writing files via `execute_command` (heredocs, `cat >`, `echo >`, `printf >`) → file corruption from shell parsing
  ## Hard Blocks (NEVER violate)
  - Suppress type errors → never
  - Commit without explicit user request → never
  - Speculate about unread code → never
  - Leave code in broken state after failures → never
  - Deliver final user answer with Oracle still running → never
  - Write files via `execute_command` instead of `fs_write`/`fs_patch` → never
  ## Available Tools
  {{__tools__}}
@@ -1,24 +1,13 @@
 {
  "mcpServers": {
    "github": {
-      "type": "stdio",
+      "type": "http",
-      "command": "docker",
+      "url": "https://api.githubcopilot.com/mcp"
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    },
    "atlassian": {
      "type": "stdio",
      "command": "npx",
-      "args": ["-y", "mcp-remote@0.1.13", "https://mcp.atlassian.com/v1/mcp"]
+      "args": ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/mcp"]
    },
    "docker": {
      "type": "stdio",
@@ -0,0 +1,44 @@
 schemaVersion: "1"
 kind: mixin
 name: built-in-tools
 description: >
  Installs binaries and allows network domains required by Coyote's built-in
  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"
@@ -32,7 +32,7 @@ def main():
    agent_data = parse_raw_data(raw_data)
    root_dir = "{config_dir}"
-    setup_env(root_dir, agent_func)
+    setup_env(root_dir, agent_func, raw_data)
    agent_tools_path = os.path.join(root_dir, "agents/{agent_name}/tools.py")
    run(agent_tools_path, agent_func, agent_data)
@@ -65,13 +65,14 @@ def parse_argv():
    return agent_func, agent_data
-def setup_env(root_dir, agent_func):
+def setup_env(root_dir, agent_func, raw_data):
    load_env(os.path.join(root_dir, ".env"))
    os.environ["LLM_ROOT_DIR"] = root_dir
    os.environ["LLM_AGENT_NAME"] = "{agent_name}"
    os.environ["LLM_AGENT_FUNC"] = agent_func
    os.environ["LLM_AGENT_ROOT_DIR"] = os.path.join(root_dir, "agents", "{agent_name}")
    os.environ["LLM_AGENT_CACHE_DIR"] = os.path.join(root_dir, "cache", "{agent_name}")
    os.environ["LLM_AGENT_RAW_JSON"] = raw_data
 def load_env(file_path):
@@ -32,6 +32,7 @@ setup_env() {
    export LLM_AGENT_ROOT_DIR="$LLM_ROOT_DIR/agents/{agent_name}"
    export LLM_AGENT_CACHE_DIR="$LLM_ROOT_DIR/cache/{agent_name}"
    export LLM_PROMPT_UTILS_FILE="{prompt_utils_file}"
    export LLM_AGENT_RAW_JSON="$agent_data"
 }
 load_env() {
@@ -11,7 +11,7 @@ async function main(): Promise<void> {
  const agentData = parseRawData(rawData);
  const configDir = "{config_dir}";
-  setupEnv(configDir, agentFunc);
+  setupEnv(configDir, agentFunc, rawData);
  const agentToolsPath = join(configDir, "agents", "{agent_name}", "tools.ts");
  await run(agentToolsPath, agentFunc, agentData);
@@ -48,13 +48,14 @@ function parseArgv(): { agentFunc: string; rawData: string } {
  return { agentFunc, rawData: agentData };
 }
-function setupEnv(configDir: string, agentFunc: string): void {
+function setupEnv(configDir: string, agentFunc: string, rawData: string): void {
  loadEnv(join(configDir, ".env"));
  process.env["LLM_ROOT_DIR"] = configDir;
  process.env["LLM_AGENT_NAME"] = "{agent_name}";
  process.env["LLM_AGENT_FUNC"] = agentFunc;
  process.env["LLM_AGENT_ROOT_DIR"] = join(configDir, "agents", "{agent_name}");
  process.env["LLM_AGENT_CACHE_DIR"] = join(configDir, "cache", "{agent_name}");
  process.env["LLM_AGENT_RAW_JSON"] = rawData;
 }
 function loadEnv(filePath: string): void {
@@ -32,7 +32,7 @@ def main():
    tool_data = parse_raw_data(raw_data)
    root_dir = "{root_dir}"
-    setup_env(root_dir)
+    setup_env(root_dir, raw_data)
    tool_path = "{tool_path}.py"
    run(tool_path, "run", tool_data)
@@ -65,11 +65,12 @@ def parse_argv():
    return tool_data
-def setup_env(root_dir):
+def setup_env(root_dir, raw_data):
    load_env(os.path.join(root_dir, ".env"))
    os.environ["LLM_ROOT_DIR"] = root_dir
    os.environ["LLM_TOOL_NAME"] = "{function_name}"
    os.environ["LLM_TOOL_CACHE_DIR"] = os.path.join(root_dir, "cache", "{function_name}")
    os.environ["LLM_TOOL_RAW_JSON"] = raw_data
 def load_env(file_path):
@@ -29,6 +29,7 @@ setup_env() {
    export LLM_TOOL_NAME="{function_name}"
    export LLM_TOOL_CACHE_DIR="$LLM_ROOT_DIR/cache/{function_name}"
    export LLM_PROMPT_UTILS_FILE="{prompt_utils_file}"
    export LLM_TOOL_RAW_JSON="$tool_data"
 }
 load_env() {
@@ -11,7 +11,7 @@ async function main(): Promise<void> {
  const toolData = parseRawData(rawData);
  const rootDir = "{root_dir}";
-  setupEnv(rootDir);
+  setupEnv(rootDir, rawData);
  const toolPath = "{tool_path}.ts";
  await run(toolPath, "run", toolData);
@@ -45,11 +45,12 @@ function parseArgv(): string {
  return toolData;
 }
-function setupEnv(rootDir: string): void {
+function setupEnv(rootDir: string, rawData: string): void {
  loadEnv(join(rootDir, ".env"));
  process.env["LLM_ROOT_DIR"] = rootDir;
  process.env["LLM_TOOL_NAME"] = "{function_name}";
  process.env["LLM_TOOL_CACHE_DIR"] = join(rootDir, "cache", "{function_name}");
  process.env["LLM_TOOL_RAW_JSON"] = rawData;
 }
 function loadEnv(filePath: string): void {
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -e
-# @describe Execute the shell command.
+# @describe Execute the shell command. DO NOT use this to write files — use fs_write (new files) or fs_patch (edits) instead. Shell-based file writes (cat >, echo >, printf >, tee, heredocs, python -c "open(...)") break on multi-line content, special characters, quoted strings, and nested language blocks.
 # @option --command! The command to execute.
 # @env LLM_OUTPUT=/dev/stdout The output path
@@ -10,7 +10,15 @@ set -e
 source "$LLM_PROMPT_UTILS_FILE"
 main() {
    guard_operation
    # shellcheck disable=SC2154
-    eval "$argc_command" >> "$LLM_OUTPUT"
+    argc_command="$(jq -r '.command' <<< "$LLM_TOOL_RAW_JSON")"
    guard_operation
    local script
    script="$(mktemp)"
    # shellcheck disable=SC2064
    trap "rm -f '$script'" EXIT
    # shellcheck disable=SC2154
    printf '%s\n' "$argc_command" > "$script"
    bash -e -o pipefail "$script" >> "$LLM_OUTPUT"
 }
@@ -14,6 +14,8 @@ source "$LLM_PROMPT_UTILS_FILE"
 # shellcheck disable=SC2154
 main() {
    argc_code="$(jq -r '.code' <<< "$LLM_TOOL_RAW_JSON")"
    if ! grep -qi '^select' <<<"$argc_code"; then
        guard_operation ""
    fi
@@ -3,10 +3,11 @@ set -e
 # @describe Search file contents using regular expressions. Returns matching file paths and lines.
 # Use this to find relevant code before reading files. Much faster than reading files to search.
 # --path accepts either a directory (recursive search with exclude rules applied) or a single file.
 # @option --pattern! The regex pattern to search for in file contents
-# @option --path The directory to search in (defaults to current working directory)
+# @option --path The directory OR file to search in (defaults to current working directory)
-# @option --include File pattern to filter by (e.g. "*.rs", "*.{ts,tsx}", "*.py")
+# @option --include File pattern to filter by (e.g. "*.rs", "*.{ts,tsx}", "*.py"). Ignored when --path is a single file.
 # @env LLM_OUTPUT=/dev/stdout The output path
@@ -19,13 +20,17 @@ main() {
    local search_path="${argc_path:-.}"
    local include_filter="${argc_include:-}"
-    if [[ ! -d "$search_path" ]]; then
+    if [[ ! -e "$search_path" ]]; then
-        echo "Error: directory not found: $search_path" >> "$LLM_OUTPUT"
+        echo "Error: path not found: $search_path" >> "$LLM_OUTPUT"
        return 1
    fi
-    local grep_args=(-rn --color=never)
+    local grep_args=(-nH --color=never)
    if [[ -d "$search_path" ]]; then
        # Use -r (not -R) so symlinks to directories are NOT followed - this avoids
        # infinite loops on pathological symlink cycles (e.g. `ln -s . loop`).
        grep_args+=(-r)
        grep_args+=(
            --exclude-dir='.git'
            --exclude-dir='node_modules'
@@ -42,10 +47,12 @@ main() {
            --exclude='*.lock'
            --exclude='package-lock.json'
        )
        if [[ -n "$include_filter" ]]; then
            grep_args+=("--include=$include_filter")
        fi
    fi
    # If --path is a single file, --include and the exclude rules are ignored
    # (they only matter when recursing into a directory tree).
    local results
    results=$(grep "${grep_args[@]}" -E "$search_pattern" "$search_path" 2>/dev/null | head -n "$MAX_RESULTS") || true
@@ -1,8 +1,27 @@
 #!/usr/bin/env bash
 set -e
-# @describe Apply a patch to a file at the specified path.
+# @describe Apply a unified-diff patch to a file at the specified path. Use this for editing an existing file. It's the
-# This can be used to edit a file without having to rewrite the whole file.
+# PREFERRED way to modify a file. Prefer this over fs_write whenever the file already exists: it sends less data,
 # preserves unchanged content automatically, and is less prone to accidental data loss from full rewrites.
 # Use fs_write only when you are creating a new file or doing a complete rewrite where most of the content changes.
 #
 # CRITICAL — the patch is matched byte-for-byte. There is no fuzzy matching, no whitespace tolerance, and no context shift:
 # - Context lines (prefixed with a single space) and removed lines (prefixed with '-') must equal the file content exactly.
 #   If unsure, fs_cat the file first and copy the bytes verbatim into your patch.
 # - JSON-escape the contents string ONCE. Each literal backslash in the file becomes \\ in the JSON contents string. So a
 #   shell line containing s|\\"|"|g must appear in JSON as s|\\\\\"|\"|g — NOT s|\\\\\\\"|\\\"|g. Over-escaping backslashes
 #   is the most common cause of "unable to apply patch" failures, especially in files with sed/jq/regex pipelines or
 #   embedded Python with quoted strings.
 # - Hunks are applied in order; the first hunk that fails aborts the whole patch — later hunks are NOT attempted.
 # - If you've edited this file in earlier tool calls, fs_cat it again before composing the patch. A stale view of the file
 #   produces context lines that no longer match.
 # - On failure the error message names the failing hunk and shows the expected-vs-actual line. Fix that specific line and
 #   retry — do not blindly resend a near-identical patch.
 #
 # For files with heavy escaping (sed/jq/regex pipelines, shell with embedded heredocs, deeply quoted strings), prefer
 # fs_write over chained fs_patch hunks to replace the entire file with the full new contents (i.e. original content +
 # your changes).
 # @option --path! The path of the file to apply the patch to
 # @option --contents! The patch to apply to the file
@@ -14,6 +33,9 @@ source "$LLM_PROMPT_UTILS_FILE"
 # shellcheck disable=SC2154
 main() {
    argc_contents="$(jq -r '.contents' <<< "$LLM_TOOL_RAW_JSON")"
    argc_path="$(jq -r '.path' <<< "$LLM_TOOL_RAW_JSON")"
    if [[ ! -f "$argc_path" ]]; then
        error "Unable to find the specified file: $argc_path"
        exit 1
@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 set -e
-# @describe Read a file with line numbers, offset, and limit. For directories, lists entries.
+# @describe Read a TRUNCATED view of a file with line numbers, offset, and limit. For directories, lists entries.
-# Prefer this over fs_cat for controlled reading. Use offset/limit to read specific sections.
+# IMPORTANT: This tool truncates output — lines over 2000 chars are cut off, and output is capped at 2000 lines by default.
 # If you need the FULL, untruncated contents of a file, use fs_cat instead.
 # Use this tool when you want line numbers, want to read a specific section via --offset/--limit, or are scanning a large file.
 # Use the grep tool to find specific content before reading, then read with offset to target the relevant section.
 # @option --path! The absolute path to the file or directory to read
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -e
-# @describe Write the full file contents to a file at the specified path.
+# @describe Write the FULL file contents to a file at the specified path. Use this for NEW files or COMPLETE rewrites
 # only. For editing an existing file, prefer fs_patch. It's a surgical edit that preserves unchanged content, requires
 # sending less data, and is less prone to accidental data loss.
 # @option --path! The path of the file to write to
 # @option --contents! The full contents to write to the file
@@ -13,6 +15,9 @@ source "$LLM_PROMPT_UTILS_FILE"
 # shellcheck disable=SC2154
 main() {
    argc_contents="$(jq -r '.contents' <<< "$LLM_TOOL_RAW_JSON")"
    argc_path="$(jq -r '.path' <<< "$LLM_TOOL_RAW_JSON")"
    if [[ -f "$argc_path" ]]; then
        printf "%s" "$argc_contents" | git diff --no-index "$argc_path" - || true
        guard_operation "Apply changes?"
@@ -14,6 +14,10 @@ set -e
 # shellcheck disable=SC2154
 main() {
    argc_recipient="$(jq -r '.recipient' <<< "$LLM_TOOL_RAW_JSON")"
    argc_subject="$(jq -r '.subject' <<< "$LLM_TOOL_RAW_JSON")"
    argc_body="$(jq -r '.body' <<< "$LLM_TOOL_RAW_JSON")"
    sender_name="${EMAIL_SENDER_NAME:-$(echo "$EMAIL_SMTP_USER" | awk -F'@' '{print $1}')}"
    printf "%s\n" "From: $sender_name <$EMAIL_SMTP_USER>
 To: $argc_recipient 
@@ -507,7 +507,9 @@ open_link() {
 guard_operation() {
 	if [[ -z "$AUTO_CONFIRM" && -z "$LLM_AGENT_VAR_AUTO_CONFIRM" ]]; then
-		ans="$(confirm "${1:-Are you sure you want to continue?}")"
+		# 2>/dev/tty: keep the prompt off the host-captured stderr pipe so it
 		# can't leak into tool_call_error JSON when the wrapped command fails.
 		ans="$(confirm "${1:-Are you sure you want to continue?}" 2>/dev/tty)"
 		if [[ "$ans" == 0 ]]; then
 			error "Operation aborted!" 2>&1
@@ -598,6 +600,14 @@ patch_file() {
          for (i = 2; i <= hunkTotalOriginalLines[hunkIndex]; i++) {
            if (lines[nextLineIndex] != hunkOriginalLines[hunkIndex,i]) {
              if (i - 1 > bestPartialLen[hunkIndex]) {
                bestPartialLen[hunkIndex] = i - 1
                bestPartialAnchorLine[hunkIndex] = lineIndex
                bestPartialHunkPos[hunkIndex] = i
                bestPartialDivergeLine[hunkIndex] = nextLineIndex
                bestPartialExpected[hunkIndex] = hunkOriginalLines[hunkIndex,i]
                bestPartialActual[hunkIndex] = lines[nextLineIndex]
              }
              nextLineIndex = 0
              break
            }
@@ -619,7 +629,32 @@ patch_file() {
        }
        if (hunkIndex != totalHunks + 1) {
          failingHunk = hunkIndex
          print "error: unable to apply patch" > "/dev/stderr"
          print "" > "/dev/stderr"
          print "Hunk " failingHunk " of " totalHunks " did not match the file." > "/dev/stderr"
          if (bestPartialLen[failingHunk] == 0) {
            print "" > "/dev/stderr"
            print "The first context/removed line of hunk " failingHunk " was not found anywhere in the file:" > "/dev/stderr"
            print "  expected: " hunkOriginalLines[failingHunk, 1] > "/dev/stderr"
          } else {
            print "" > "/dev/stderr"
            print "Closest match: anchored at file line " bestPartialAnchorLine[failingHunk] ", matched " bestPartialLen[failingHunk] " of " hunkTotalOriginalLines[failingHunk] " original lines before diverging." > "/dev/stderr"
            print "" > "/dev/stderr"
            print "At file line " bestPartialDivergeLine[failingHunk] " (hunk original line " bestPartialHunkPos[failingHunk] "):" > "/dev/stderr"
            print "  expected: " bestPartialExpected[failingHunk] > "/dev/stderr"
            print "  actual:   " bestPartialActual[failingHunk] > "/dev/stderr"
          }
          print "" > "/dev/stderr"
          print "Lines must match byte-for-byte (no fuzzy matching). Check escaping, whitespace, and quoting." > "/dev/stderr"
          if (failingHunk < totalHunks) {
            print "" > "/dev/stderr"
            print (totalHunks - failingHunk) " subsequent hunk(s) were not attempted (patcher aborts on first failure)." > "/dev/stderr"
          }
          exit 1
        }
    }
@@ -657,7 +692,8 @@ guard_path() {
 	confirmation_prompt="$2"
 	if [[ ! "$path" == "$(pwd)"* && -z "$AUTO_CONFIRM" && -z "$LLM_AGENT_VAR_AUTO_CONFIRM" ]]; then
-		ans="$(confirm "$confirmation_prompt")"
+		# 2>/dev/tty: see guard_operation — prevents prompt text leaking via captured stderr.
 		ans="$(confirm "$confirmation_prompt" 2>/dev/tty)"
 		if [[ "$ans" == 0 ]]; then
 			error "Operation aborted!" >&2
@@ -1,3 +1,6 @@
 ---
 skills_enabled: false
 ---
 As a professional Prompt Engineer, your role is to create effective and innovative prompts for interacting with AI models.
 Your core skills include:
@@ -1,3 +1,6 @@
 ---
 skills_enabled: false
 ---
 Create a concise, 3-6 word title.
 **Notes**:
@@ -1,3 +1,6 @@
 ---
 skills_enabled: false
 ---
 Provide a terse, single sentence description of the given shell command.
 Describe each argument and option of the command.
 Provide short responses in about 80 words.
@@ -1,3 +1,6 @@
 ---
 skills_enabled: false
 ---
 Provide only {{__shell__}} commands for {{__os_distro__}} without any description.
 Ensure the output is a valid {{__shell__}} command.
 If there is a lack of details, provide most logical solution.
@@ -1,6 +1,5 @@
 ---
 enabled_mcp_servers: slack
 temperature: 0.2
 ---
 You are an expert Slack assistant designed to assist with Slack workspaces via the slack MCP server. 
 You can perform various tasks related to Slack, such as sending messages to channels, searching for messages, and 
@@ -0,0 +1,325 @@
 # Docker sbx agent kit for Coyote
 #
 # Setup (paths use $HOME so commands work in bash/zsh/PowerShell/Git Bash):
 #   sbx create --kit ./sbx-kit/ coyote --name testing .
 #   sbx cp $HOME/.config/coyote/ testing:/home/agent/.config/
 #   sbx cp $HOME/.coyote_password testing:/home/agent/
 #   sbx run testing --kit ./sbx-kit/
 schemaVersion: "1"
 kind: agent
 name: coyote
 displayName: Coyote
 description: >
  An all-in-one, batteries-included LLM CLI tool featuring Shell Assistant,
  CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros.
 agent:
  image: "docker/sandbox-templates:shell-docker"
  aiFilename: COYOTE.md
 #  persistence: persistent
  entrypoint:
    run: ["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"
    # Coyote install paths (cargo install + uv + rustup + Python tool deps at runtime)
    - "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"
    # 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"
    # 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"
 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
 environment:
  variables:
    IS_SANDBOX: "1"
    COYOTE_LOG_LEVEL: INFO
  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
 commands:
  install:
    - command: |
        sudo apt-get update &&
        sudo apt-get install -y \
          jq curl git \
          build-essential pkg-config \
          cmake \
          clang libclang-dev \
          musl-tools \
          libssl-dev \
          pandoc \
          bzip2
      user: "1000"
      description: Install system prerequisites (including pandoc for fetch_url_via_curl)
    - command: "curl -LsSf https://astral.sh/uv/install.sh | sh"
      user: "1000"
      description: Install uv (required for Python-based custom tools)
    - command: |
        set -euo pipefail
        USQL_VERSION="0.19.20"
        ARCH=$(uname -m)
        case "$ARCH" in
          x86_64) USQL_ARCH=amd64 ;;
          aarch64) USQL_ARCH=arm64 ;;
          *) echo "Unsupported arch for usql install: $ARCH" >&2; exit 1 ;;
        esac
        curl -sSL "https://github.com/xo/usql/releases/download/v${USQL_VERSION}/usql_static-${USQL_VERSION}-linux-${USQL_ARCH}.tar.bz2" -o /tmp/usql.tar.bz2
        sudo tar -xjf /tmp/usql.tar.bz2 -C /usr/local/bin
        sudo chmod +x /usr/local/bin/usql
        rm -f /tmp/usql.tar.bz2
      user: "1000"
      description: Install the usql universal SQL CLI (used by the built-in sql agent and execute_sql_code tool)
    - command: |
        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
          sh -s -- -y \
          --default-toolchain stable \
          --profile minimal \
          --target x86_64-unknown-linux-musl
        . "$HOME/.cargo/env"
        cargo install --locked coyote-ai
      user: "1000"
      description: Install Coyote AI CLI via Rust's Cargo
  startup:
    - command: ["sh", "-c", "test -f \"$HOME/.config/coyote/config.yaml\" || coyote --info >/dev/null 2>&1 || true"]
      user: "1000"
      background: false
      description: Bootstrap Coyote config directory on first sandbox start
 memory: |
  ## 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.
  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. The
  following provider env vars are recognized - export the ones you use on
  the host before running `sbx run coyote`:
    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 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. 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)
@@ -0,0 +1,33 @@
 schemaVersion: "1"
 kind: mixin
 name: vault-aws-secrets-manager
 description: >
  Installs the AWS CLI v2 so the Coyote vault can read secrets from AWS
  Secrets Manager inside the sandbox. The AWS Rust SDK does not strictly
  require the CLI, but most users authenticate via `aws sso login` or
  `aws configure`, which need the CLI to be installed. After install, run
  the appropriate auth command in the sandbox; cached credentials persist
  for the lifetime of the sandbox.
 network:
  allowedDomains:
    - "awscli.amazonaws.com:443"
    - "sts.amazonaws.com:443"
    - "*.sts.amazonaws.com:443"
    - "*.secretsmanager.amazonaws.com:443"
    - "*.amazonaws.com:443"
    - "*.awsapps.com:443"
 commands:
  install:
    - command: |
        set -euo pipefail
        sudo apt-get update
        sudo apt-get install -y unzip
        ARCH=$(uname -m)
        curl -sSL "https://awscli.amazonaws.com/awscli-exe-linux-${ARCH}.zip" -o /tmp/awscliv2.zip
        unzip -q /tmp/awscliv2.zip -d /tmp
        sudo /tmp/aws/install
        rm -rf /tmp/awscliv2.zip /tmp/aws
      user: "1000"
      description: Install AWS CLI v2 from the official installer
@@ -0,0 +1,24 @@
 schemaVersion: "1"
 kind: mixin
 name: vault-azure-key-vault
 description: >
  Installs the Azure CLI (`az`) so the Coyote vault can read secrets from
  Azure Key Vault inside the sandbox. After install, run `az login` in the
  sandbox to authenticate; the session token persists for the lifetime of
  the sandbox.
 network:
  allowedDomains:
    - "aka.ms:443"
    - "packages.microsoft.com:443"
    - "azurecliprod.blob.core.windows.net:443"
    - "login.microsoftonline.com:443"
    - "graph.microsoft.com:443"
    - "management.azure.com:443"
    - "*.vault.azure.net:443"
 commands:
  install:
    - command: "curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash"
      user: "1000"
      description: Install Azure CLI via Microsoft's official install script
@@ -0,0 +1,34 @@
 schemaVersion: "1"
 kind: mixin
 name: vault-gcp-secret-manager
 description: >
  Installs the Google Cloud CLI (`gcloud`) so the Coyote vault can read
  secrets from GCP Secret Manager inside the sandbox. The GCP Rust SDK does
  not strictly require the CLI, but most users authenticate via
  `gcloud auth application-default login`, which needs the CLI to be
  installed. After install, run that command in the sandbox; the ADC file
  persists for the lifetime of the sandbox.
 network:
  allowedDomains:
    - "packages.cloud.google.com:443"
    - "accounts.google.com:443"
    - "oauth2.googleapis.com:443"
    - "secretmanager.googleapis.com:443"
    - "cloudresourcemanager.googleapis.com:443"
    - "*.googleapis.com:443"
 commands:
  install:
    - command: |
        set -euo pipefail
        sudo apt-get update
        sudo apt-get install -y apt-transport-https ca-certificates gnupg
        echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
          | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list >/dev/null
        curl -sSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
          | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
        sudo apt-get update
        sudo apt-get install -y google-cloud-cli
      user: "1000"
      description: Install gcloud CLI from Google's official apt repository
@@ -0,0 +1,30 @@
 schemaVersion: "1"
 kind: mixin
 name: vault-gopass
 description: >
  Installs `gopass` and `gpg` so the Coyote vault can read secrets from a
  gopass store inside the sandbox. The store must be cloned manually
  (gopass walks a user-specific git remote, so v1 only allowlists github.com
  and gitlab.com; add other hosts via a user mixin if needed). After install,
  run `gopass setup` or `gopass clone <remote>` in the sandbox.
 network:
  allowedDomains:
    - "github.com:443"
    - "api.github.com:443"
    - "objects.githubusercontent.com:443"
    - "gitlab.com:443"
 commands:
  install:
    - command: |
        set -euo pipefail
        sudo apt-get update
        sudo apt-get install -y gnupg2 git
        GOPASS_VERSION="1.15.13"
        ARCH=$(dpkg --print-architecture)
        curl -sSL "https://github.com/gopasspw/gopass/releases/download/v${GOPASS_VERSION}/gopass_${GOPASS_VERSION}_linux_${ARCH}.deb" -o /tmp/gopass.deb
        sudo dpkg -i /tmp/gopass.deb
        rm -f /tmp/gopass.deb
      user: "1000"
      description: Install gnupg2, git, and gopass from the official .deb release
@@ -0,0 +1,31 @@
 schemaVersion: "1"
 kind: mixin
 name: vault-one-password
 description: >
  Installs the 1Password CLI (`op`) so the Coyote vault can decrypt secrets
  inside the sandbox. After install, run `op signin` in the sandbox to
  authenticate; credentials persist for the lifetime of the sandbox.
 network:
  allowedDomains:
    - "downloads.1password.com:443"
    - "cache.agilebits.com:443"
    - "my.1password.com:443"
    - "my.1password.eu:443"
    - "my.1password.ca:443"
    - "events.1password.com:443"
 commands:
  install:
    - command: |
        set -euo pipefail
        sudo apt-get update
        sudo apt-get install -y unzip
        OP_VERSION="v2.30.3"
        ARCH=$(dpkg --print-architecture)
        curl -sSL "https://cache.agilebits.com/dist/1P/op2/pkg/${OP_VERSION}/op_linux_${ARCH}_${OP_VERSION}.zip" -o /tmp/op.zip
        sudo unzip -od /usr/local/bin /tmp/op.zip op
        sudo chmod +x /usr/local/bin/op
        rm -f /tmp/op.zip
      user: "1000"
      description: Install 1Password CLI from the official archive
@@ -6,7 +6,7 @@ You are reviewing code. Use the filesystem tools (`fs_read`, `fs_grep`, `fs_glob
 ## Investigation workflow
-Before reviewing the diff, build a mental model of the surrounding code:
+Before reviewing, build a mental model of the surrounding code:
 - `fs_ls` the directories that contain the changed files.
 - `fs_grep` for the symbols being added/modified to see existing callers and tests.
@@ -15,6 +15,60 @@ Before reviewing the diff, build a mental model of the surrounding code:
 A review without context is just a syntax check.
 ## Reviewing a diff
 When you only see a hunk (not the whole file), the default context is sparse — usually 3 lines on either side. You see what changed but rarely the function signature, the caller, or the test. Read deliberately to recover what the diff omits.
 ### Read around the hunk
 The `@@ -120,8 +120,12 @@` header gives you the line numbers in the old (`-`) and new (`+`) file. Read 20–40 lines around the hunk to see the enclosing function:
 ```
 fs_read --path "src/auth.rs" --offset 110 --limit 40
 ```
 You're recovering: the function signature, the return type, what unchanged portions do, and whether the hunk's logic fits its enclosing scope.
 ### Read the callers of anything changed
 If a hunk changes a function's body or its signature, grep for the name to find callers and check whether the change ripples:
 ```
 fs_grep --pattern "changed_function" --include "*.rs"
 ```
 Skip the test files in this search; do the test sweep next.
 ### Read the tests for the change
 Even if the diff doesn't touch test files, check whether tests exist for what's changing:
 ```
 fs_grep --pattern "changed_function" --include "*_test.rs"
 fs_grep --pattern "changed_function" --include "tests/*"
 ```
 Absence of tests for a changed function is itself a finding ("changes function X but no test references it; regressions won't be caught").
 ### Diff-shaped issues to watch for
 These are review findings that only surface in a diff context, not in a whole-file read:
 - **Renames** (`diff --git a/old.rs b/new.rs`) — `fs_grep` for the old path to find imports that need updating but weren't.
 - **Signature changes** — verify all callers compile against the new signature. Compiler-checked languages catch some of this; dynamic languages don't.
 - **New code path without new tests** — usually a missing test. Flag it.
 - **Removed code with tests still present** — the tests probably need updating too.
 - **The "dog that didn't bark"** — what's obvious by its ABSENCE? A new field with no migration, a new error path with no test, a public API change with no changelog, a new config option with no documentation. Flag these as missing pieces, not as things to add later.
 ### Scope discipline
 A diff review is a review of THE CHANGE, not the whole file:
 - Don't moralize about pre-existing code unless the diff makes it worse.
 - Don't suggest refactors outside the scope of the change. ("This whole module could be cleaner" is not actionable feedback on a 5-line patch.)
 - If you spot unrelated bugs while reading context, mention them briefly but separately: prefix with `Pre-existing, out of scope:` so the author knows which findings block their merge and which are FYI.
 - The author's job is to ship THIS change. Your job is to catch what's wrong with THIS change.
 ## 1. Correctness
 - Does the change actually do what it claims? Does it solve the stated problem?
@@ -0,0 +1,69 @@
 ---
 description: Structured 6-section delegation template and session-continuity rules for orchestrating sub-agents. Load before spawning any agent.
 ---
 You are delegating work to a sub-agent. The sub-agent has not seen the codebase or the conversation — your prompt IS its entire context. Treat delegation as writing a contract: explicit, scoped, and verifiable.
 ## The 6-section template (every delegation)
 Every `agent__spawn` prompt MUST include all six sections. Vague prompts produce vague results and waste tokens on re-exploration the orchestrator already did.
 ```
 ## TASK
 [One atomic goal. One verb. One outcome. No "and also".]
 ## EXPECTED OUTCOME
 [Concrete deliverables and success criteria. "I will know this is done when ..."]
 ## REQUIRED TOOLS
 [Explicit allowlist: fs_read, fs_grep, etc. Prevents tool sprawl.]
 ## MUST DO
 [Exhaustive requirements. Leave nothing implicit. If you'd be annoyed by the agent not doing X, list X.]
 ## MUST NOT DO
 [Forbidden actions. Anticipate rogue behavior. "Do not modify files outside src/auth/."]
 ## CONTEXT
 [File paths, code snippets, existing patterns, constraints. Paste actual code lines from prior exploration — not just file paths.]
 ```
 ## Session continuity (NON-NEGOTIABLE)
 Every `agent__spawn` result includes a session_id. **Use it.**
 - Task failed/incomplete → resume with `session_id` + a tight "Fix: <error>" prompt.
 - Follow-up on a result → resume with `session_id` + "Also: <question>".
 - Multi-turn with the same agent → always resume. Never start fresh.
 Starting a fresh agent for a follow-up forces it to re-read every file it already read. That's 70%+ wasted tokens, plus the agent loses the reasoning it built up.
 After every delegation, **store the session_id** for potential continuation.
 ## Skill nudges to delegates
 Sub-agents have their own skills. Nudge them in the CONTEXT section:
 > "Load `code-review` before evaluating the diff."
 > "Load `frontend-ui-ux` before editing component files."
 > "Load `git-master` before touching history."
 A one-line nudge saves the delegate a `skill__list` turn.
 ## Verification after delegation
 A delegation is NOT complete when the sub-agent returns. It is complete when YOU have verified:
 1. Did it work as expected? (Did the file change? Did the test pass?)
 2. Did it follow existing codebase patterns?
 3. Did the EXPECTED OUTCOME actually materialize?
 4. Did it respect MUST DO and MUST NOT DO?
 If any answer is no → resume the session with a corrective prompt. Do not re-spawn from scratch.
 ## Anti-patterns
 - "Follow existing patterns" with no snippet → agent guesses, often wrong
 - Multi-goal prompts → agent does the easy one, skips the rest
 - Missing MUST NOT DO → agent over-reaches into unrelated files
 - Discarding session_id on failure → forced re-exploration, wasted tokens
 - Re-spawning instead of resuming for a 1-line fix → 10x cost
@@ -0,0 +1,81 @@
 ---
 description: Discipline for when and how to consult Oracle - blocking by design, never deliver an answer with Oracle pending, never bypass Oracle for design questions.
 ---
 Oracle is your read-only, high-IQ advisor. Using it correctly is the difference between shipping the right thing slowly and shipping the wrong thing fast.
 ## When you MUST consult Oracle
 Spawn `oracle` (do NOT answer yourself) any time the user asks:
 - "How should I..." / "What's the best way to..." — design/approach questions
 - "Why does X keep..." / "What's wrong with..." — complex debugging (not simple errors)
 - "Should I use X or Y?" — technology or pattern choices
 - "How should this be structured?" — architecture and organization
 - "Review this" / "What do you think of..." — code/design review
 - Tradeoff questions — performance vs readability, complexity vs flexibility
 - Multi-component questions — anything spanning 3+ files or modules
 - Vague/open-ended — "improve this", "make this better", "clean this up"
 - After 2+ failed fix attempts on the same problem — complex debugging
 Even if you think you know the answer, Oracle provides deeper, more thorough analysis. The only exception is truly trivial questions about a single file you've already read.
 ## Oracle is BLOCKING by design
 The orchestrator (you) has paused work and CANNOT proceed until Oracle returns. This is intentional. The cost of Oracle's latency is paid so YOU get a thorough, considered answer rather than rushing in a wrong direction.
 Therefore:
 - **Do NOT implement before Oracle returns** if your implementation depends on Oracle's recommendation.
 - **Do NOT deliver the final user-facing answer** while Oracle is still running.
 - **Do NOT "time out and continue anyway"** for Oracle-dependent tasks.
 - While waiting, do only NON-OVERLAPPING prep work (work that doesn't depend on Oracle's verdict).
 ## How to consult Oracle effectively
 Oracle has not seen the codebase or the conversation. Give it enough context to think:
 ```
 ## Question
 [The decision you need help with, stated as a question]
 ## Background
 [Why this question matters now. What constraint or trigger raised it.]
 ## Code context
 [Paste the actual snippets from prior exploration — file paths alone are not enough]
 - From `path/to/file.ext`:
  <relevant 5-20 lines>
 ## What you've considered
 [Options you've already weighed and their tradeoffs as you see them]
 ## What I'd love Oracle to evaluate
 [Specific aspects: correctness, performance, security, future flexibility, etc.]
 ```
 A well-scoped Oracle consult returns a tighter answer faster.
 ## After Oracle returns
 1. Read the recommendation, reasoning, and risks sections carefully.
 2. If the recommendation conflicts with your prior plan, update the plan — do not silently ignore Oracle.
 3. Pass Oracle's recommendation (and reasoning) to the implementer (e.g., coder) as CONTEXT in your delegation.
 4. If you disagree with Oracle's verdict, raise it with the user before implementing the alternative — don't act unilaterally against Oracle's advice.
 ## When NOT to consult Oracle
 - Simple file operations you can do with direct tools
 - First attempt at any fix (try yourself first; consult after 2 failures)
 - Questions answerable from code you've already read
 - Trivial decisions (variable names in small functions, formatting)
 - Things you can infer from existing code patterns
 Over-consultation wastes Oracle's budget and slows the work. Reserve Oracle for genuinely hard or load-bearing decisions.
 ## Anti-patterns (BLOCKING)
 - Answering an architecture question yourself "just this once"
 - Delivering a user-facing answer while Oracle is still running
 - Implementing the obvious approach without consulting Oracle on a tradeoff question
 - Ignoring Oracle's recommendation because it's inconvenient
 - Polling `agent__collect` on a running Oracle (end your response, wait for notification)
@@ -0,0 +1,70 @@
 ---
 description: Fan-out exploration protocol — fire multiple research agents in parallel, wait for completion notifications, and never duplicate delegated work.
 ---
 You are entering a research phase. Exploration is parallelizable; serial reads leave throughput on the table.
 ## Fan out, don't read serially
 For any non-trivial codebase question, fire 2-5 `explore` agents in parallel, each scoped to a different angle:
 - Auth implementation? → one for routes, one for middleware, one for token handling, one for error response shape.
 - Bug investigation? → one for the failing path, one for similar working paths, one for recent changes near the area.
 Each agent gets a NARROW slice. Narrow scope = fast, focused result. Broad scope = the agent over-reads and returns a wall of text.
 ## The wait protocol
 After spawning background agents:
 1. If you have **non-overlapping** work to do (work that doesn't depend on the delegated research), do it now.
 2. If you don't, **end your response.** Do not call `agent__collect` immediately — the agent is still running.
 3. The system notifies you when the agent completes (`pending_escalations` or completion event).
 4. On notification, call `agent__collect` to retrieve results.
 Polling `agent__collect` on a still-running agent blocks your turn for nothing.
 ## Anti-duplication rule (BLOCKING)
 Once you delegate a search to an `explore` agent, **do not perform that same search yourself.**
 Forbidden:
 - After firing `explore` for "auth middleware", running `fs_grep` for "auth middleware" yourself
 - "Just quickly checking" the same files the delegate is checking
 - Re-doing the research while waiting impatiently
 Allowed:
 - Non-overlapping work in a different module
 - Preparation work that doesn't depend on the delegated result
 - Ending your response and waiting
 Duplicate searches waste tokens, may contradict the delegate, and defeat the point of parallelism.
 ## Stop conditions
 Stop searching when:
 - The same information appears across multiple sources
 - Two search iterations yield no new useful data
 - A direct answer was found
 - You have enough context to proceed confidently
 Over-exploration is as bad as under-exploration. Time spent searching is time not spent shipping.
 ## Parallel + sequential composition
 It is fine to fire `explore` and then `oracle` when oracle needs the explore results — just sequence them:
 1. Fire explore(s) in parallel.
 2. End response, wait for completion.
 3. Synthesize findings, fire `oracle` with those findings as CONTEXT.
 4. End response, wait for oracle.
 5. Act on oracle's recommendation.
 Don't fire oracle blind to "save a turn" — it will give worse advice.
 ## Anti-patterns
 - One huge "explore everything about X" agent → slow, unfocused result
 - Serial explores ("wait for first, then fire next") → unnecessary latency
 - Firing 8+ parallel agents → diminishing returns, harder to synthesize
 - Calling `agent__collect` immediately after spawn → wastes a turn
@@ -0,0 +1,66 @@
 ---
 description: Evidence requirements before claiming completion — diagnostics, build exit code, tests. No completion without proof. Grants shell access for running build/test commands.
 enabled_tools: execute_command
 ---
 You are about to mark work complete. Before claiming "done," produce evidence. "I'm fairly confident it works" is not evidence.
 ## Hard gates
 A task is NOT complete until:
 | Change kind | Required evidence |
 |---|---|
 | File edit | Read the file to confirm the change landed; output is clean (or only pre-existing issues, explicitly noted) |
 | Build command exists | `execute_command` the build; exit code 0 |
 | Test command exists | `execute_command` the tests; pass (or explicit note of pre-existing failures unrelated to this change) |
 | Delegation | The delegate's result was received AND verified against your acceptance criteria |
 **No evidence = not complete.** Marking a todo done without evidence is dishonest reporting.
 ## The verification loop
 After every meaningful edit:
 1. Read the changed file region (confirm the change actually landed where intended).
 2. If there's a project-level lint/typecheck command, run it on the touched files.
 3. Run the project's build/check command if one exists.
 4. Run the project's test command if one exists.
 5. Only then mark the corresponding todo `completed`.
 If any step fails: do not mark complete. Fix the issue or surface it explicitly.
 ## Build/test detection (fallback)
 If no build/test command is configured, try standard ones for the project:
 - Rust: `cargo check`, `cargo test`
 - Node/TS: `npm run build`, `npm test`, or `pnpm` / `yarn` equivalents
 - Python: `pytest`, `python -m mypy <pkg>`, `ruff check`
 - Go: `go build ./...`, `go test ./...`
 Run from the project root. Capture exit codes.
 ## Distinguishing your failures from pre-existing failures
 If build or tests fail, identify the cause:
 - Caused by your change? → fix it before reporting complete.
 - Pre-existing (unrelated)? → note it explicitly: "Done. Build passes. Note: 3 lint errors pre-existing in unrelated files, not touched."
 Never silently leave broken state behind. Never delete a failing test to make CI green.
 ## Anti-patterns (BLOCKING)
 - "It should work" without running anything
 - Marking a todo complete based on intent, not verified outcome
 - Suppressing errors with `@ts-ignore`, `as any`, `#[allow(...)]` on unfamiliar lints, empty catch blocks
 - Deleting failing tests to "pass"
 - Reporting "all green" when you only ran a subset
 ## Reporting completion
 When the work is verifiably done, report in one sentence:
 > "Done. Build passes, 47 tests pass. Modified `auth.rs:42-58` to add JWT validation."
 Not a paragraph. Not a victory lap. Specific, terse, evidence-backed.
@@ -42,6 +42,18 @@ global_tools:                    # Optional list of additional global tools to e
  - web_search
  - fs
  - python
 skills_enabled: true             # Master switch for skills in this agent (default: inherit from global).
                                 # Skills also require `function_calling_support: true` in the global config.
 enabled_skills:                  # Optional list of skills available when this agent runs.
                                 # Must be a subset of global `visible_skills`. Omit to inherit the global default.
  - git-master
  - ai-slop-remover
 inject_skill_instructions: true  # Inject a short hint pointing the model at `skill__list` when skills are enabled
                                 # (default: true). Suppressed automatically when no skills are available.
 skill_instructions: null         # Custom text for the skill hint (optional; uses built-in default if null)
 memory: null                     # Per-agent memory override (default: inherit). Set to `false` to disable memory
                                 # for this agent regardless of workspace/global presence. See the Memory wiki page.
 dynamic_instructions: false      # Whether to use dynamic instructions for the agent; if false, static instructions are used
 instructions: |                  # Static instructions for the agent; ignored if dynamic instructions are used
  You are a AI agent designed to demonstrate agent capabilities.
@@ -34,15 +34,62 @@ right_prompt:
  '{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
 # ---- Vault ----
-# See the [Vault documentation](https://github.com/Dark-Alex-17/coyote/wiki/Vault) for more information on the Coyote vault
+# See the [Vault documentation](https://github.com/Dark-Alex-17/coyote/wiki/Vault) for more information on the Coyote vault.
 #
 # The secrets_provider tells Coyote where to read and write secrets referenced via {{SECRET_NAME}} syntax.
 #
 # Shorthand: set vault_password_file to enable the local provider with that password file.
 vault_password_file: null        # Path to a file containing the password for the Coyote vault (cannot be a secret template)
 #
 # Explicit: set secrets_provider to one of the supported types below. When secrets_provider is set,
 # vault_password_file is ignored. Note: secrets_provider itself cannot use {{SECRET}} template syntax.
 # The vault must be initialized before any secrets can be resolved.
 #
 # Local (same as the shorthand above):
 # secrets_provider:
 #   type: local
 #   password_file: ~/.coyote_password
 #
 # AWS Secrets Manager (requires an authenticated AWS CLI; see `aws sso login` or `aws configure`):
 # secrets_provider:
 #   type: aws_secrets_manager
 #   aws_profile: default
 #   aws_region: us-east-1
 #
 # GCP Secret Manager (requires `gcloud auth application-default login`):
 # secrets_provider:
 #   type: gcp_secret_manager
 #   gcp_project_id: my-project-id
 #
 # Azure Key Vault (requires `az login`):
 # secrets_provider:
 #   type: azure_key_vault
 #   vault_name: my-vault-name
 #
 # gopass (requires the `gopass` CLI to be installed and initialized):
 # secrets_provider:
 #   type: gopass
 #   store: my-store              # Optional; omit to use the default store
 #
 # 1Password (requires the `op` CLI to be installed and signed in via `op signin`):
 # secrets_provider:
 #   type: one_password
 #   vault: Production            # Optional; omit to use the default vault
 #   account: my.1password.com    # Optional; omit to use the default account
 # ---- Function Calling ----
 # See the [Tools documentation](https://github.com/Dark-Alex-17/coyote/wiki/Tools) for more details
 function_calling_support: true           # Enables or disables function calling (Globally).
 mapping_tools:                   # Alias for a tool or toolset
  fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write,fs_read,fs_glob,fs_grep'
-enabled_tools: null              # Which tools to enable by default. (e.g. 'fs,web_search_coyote')
+enabled_tools: null              # Which tools to enable by default.
                                 # Accepts either a YAML list or a comma-separated string. Use 'all' to enable everything.
                                 # Example (list form):
                                 #   enabled_tools:
                                 #     - fs
                                 #     - web_search_coyote
                                 # Example (comma-separated form):
                                 #   enabled_tools: fs,web_search_coyote
 visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools')
 #  - demo_py.py
 #  - demo_sh.sh
@@ -78,7 +125,37 @@ visible_tools:                   # Which tools are visible to be compiled (and a
 mcp_server_support: true         # Enables or disables MCP servers (globally).
 mapping_mcp_servers:             # Alias for an MCP server or set of servers
  git: github,gitmcp
-enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack,ddg-search')
+enabled_mcp_servers: null        # Which MCP servers to enable by default.
                                 # Accepts either a YAML list or a comma-separated string. Use 'all' to enable everything.
                                 # Example (list form):
                                 #   enabled_mcp_servers:
                                 #     - github
                                 #     - slack
                                 # Example (comma-separated form):
                                 #   enabled_mcp_servers: github,slack,ddg-search
 # ---- Skills ----
 # Skills are modular knowledge or capability packs the LLM can load and unload mid-conversation.
 # See the [Skills documentation](https://github.com/Dark-Alex-17/coyote/wiki/Skills) for more details.
 skills_enabled: true              # Master switch. Set to false to hide all skill management tools from the model.
                                  # Skills also require `function_calling_support: true` above to work at all.
 visible_skills:                   # The universe of skills allowed to be enabled in any context. Omit (null) for "all installed".
  - ai-slop-remover
  - code-review
  - frontend-ui-ux
  - git-master
 enabled_skills: null              # Which skills are available by default (no role/agent/session active). null = all visible.
                                  # Accepts either a YAML list or a comma-separated string.
                                  # Example (list form):
                                  #   enabled_skills:
                                  #     - git-master
                                  #     - ai-slop-remover
                                  # Example (comma-separated form):
                                  #   enabled_skills: git-master,ai-slop-remover
 inject_skill_instructions: true   # Inject a short hint pointing the model at `skill__list` when skills are enabled in
                                  # this context. Only injected if `function_calling_support`, `skills_enabled`, and the
                                  # effective enabled skill set is non-empty (default: true).
 skill_instructions: null          # Custom text used for the skill hint when injected. If null, uses built-in default.
 # ---- Auto-Continue (Todo System) ----
 # The auto-continue system provides built-in task tracking for improved reliability.
@@ -99,6 +176,19 @@ summarization_prompt: >          # The text prompt used for creating a concise s
 summary_context_prompt: >        # The text prompt used for including the summary of the entire session as context to the model
  'This is a summary of the chat history as a recap: '
 # ---- Memory ----
 # See the [Memory documentation](https://github.com/Dark-Alex-17/coyote/wiki/Memory) for more information.
 # Memory is opt-in by workspace presence (a `COYOTE.md` or `.coyote/memory/MEMORY.md`)
 # and global presence (`<config_dir>/memory/MEMORY.md`). Set `memory: false` to disable
 # even when memory files exist. The cascade is: agent > session > role > app.
 # Bootstrap with `coyote --init-memory [global|workspace]` to create the marker file
 # the LLM needs before it will write any memory.
 memory: null                     # null = enabled when memory exists on disk; true = force on; false = force off
 memory_cap_with_tools: null      # Char cap for injected memory when function calling is available (default: 6000).
                                 # Only MEMORY.md indexes are injected; the LLM uses memory__read to fetch drill files.
 memory_cap_without_tools: null   # Char cap when function calling is unavailable (default: 12000).
                                 # Indexes plus drill file bodies are injected up to this cap.
 # ---- RAG ----
 # See the [RAG Docs](https://github.com/Dark-Alex-17/coyote/wiki/RAG) for more details.
 rag_embedding_model: null        # Specifies the embedding model used for context retrieval
@@ -8,8 +8,23 @@ name: <role-name>                     # The name of the role
 model: openai:gpt-4o                  # The model to use for this role
 temperature: 0.2                      # The temperature to use for this role when querying the model
 top_p: 0                              # The top_p to use for this role when querying the model
-enabled_tools: fs_ls,fs_cat           # A comma-separated list of tools to enable for this role
+enabled_tools:                        # Tools to enable for this role. Accepts a YAML list (preferred)
-enabled_mcp_servers: github,gitmcp    # A comma-separated list of MCP servers to enable for this role
+  - fs_ls                             # or a comma-separated string (e.g. `enabled_tools: fs_ls,fs_cat`).
  - fs_cat                            # Use `all` to enable every visible tool.
 enabled_mcp_servers:                  # MCP servers to enable for this role. Accepts a YAML list (preferred)
  - github                            # or a comma-separated string (e.g. `enabled_mcp_servers: github,gitmcp`).
  - gitmcp                            # Use `all` to enable every configured MCP server.
 skills_enabled: true                  # Master switch for skills in this role (default: inherit from global).
                                      # Skills also require `function_calling_support: true` in the global config.
 enabled_skills:                       # Skills available when this role is active. Accepts a YAML list (preferred)
  - git-master                        # or a comma-separated string (e.g. `enabled_skills: git-master,ai-slop-remover`).
  - ai-slop-remover                   # Must be a subset of global `visible_skills`. Omit to inherit the global default.
 inject_skill_instructions: true       # Inject a short hint pointing the model at `skill__list` when skills are enabled 
                                      # (default: true). Suppressed automatically when no skills are available.
 skill_instructions: null              # Custom text for the skill hint (optional; uses built-in default if null)
 memory: null                          # Per-role memory override (default: inherit). Set to `false` to disable memory
                                      # when this role is active. See the Memory wiki page.
 prompt: null                          # A custom prompt to use for this role that will immediately query
                                      # the model for output instead of using the instructions below
 # Auto-Continue (Todo System)
@@ -41,6 +41,32 @@ global_tools:                      # Tool universe an `llm` node's `tools:` whit
 mcp_servers:                       # MCP servers an `llm` node may reference via `mcp:<server>`
  - ddg-search
 # ---------------------------------------------------------------------------
 # Skills policy (optional)
 # Skills only attach to `llm` nodes inside a graph. Both fields are optional.
 #
 #   skills_enabled:  master switch for skills across every `llm` node in the
 #                    graph. false here turns skills off entirely, regardless of
 #                    per-node settings. Omitting it inherits the agent / global
 #                    cascade (default true).
 #   enabled_skills:  the *universe* of skill names any `llm` node in this graph
 #                    may reference in its own `enabled_skills`. The validator
 #                    rejects per-node entries outside this list at load time.
 #                    Omit to inherit the agent / global cascade.
 #
 # Per-node usage is documented on the `triage` llm node below. There is no
 # auto-load: the model uses `skill__list` / `skill__load` / `skill__unload` to
 # bring skills in as it needs them, exactly like in normal-agent contexts.
 # ---------------------------------------------------------------------------
 skills_enabled: true
 enabled_skills:
  - code-review
  - git-master
  - ai-slop-remover
 inject_skill_instructions: true   # Inject a hint pointing the model at `skill__list`. Defaults to true; suppressed
                                  # automatically when no skills are available.
 skill_instructions: null          # Custom text for the skill hint (optional; uses the built-in default if omitted).
 conversation_starters:             # Suggested prompts surfaced in the UI
  - "Research the current state of WebAssembly outside the browser"
@@ -143,6 +169,19 @@ nodes:
      {{initial_prompt}}
    tools: []                  # Tool whitelist. Omitted or [] = no tools at all.
                               # A list narrows to exactly those entries.
    # --- Skills on llm nodes (optional) ------------------------------------
    # `enabled_skills` narrows what this node's model can see / load via the
    # built-in `skill__list` / `skill__load` / `skill__unload` meta-tools.
    # Must be a subset of the graph-level `enabled_skills` (the validator
    # catches violations at load time). `skills_enabled: false` would
    # disable skills entirely for this node (no meta-tools exposed).
    # Nothing is auto-loaded: the model decides when to load a skill.
    skills_enabled: true       # Whether skills are enabled on this llm node; defaults to 'true'
    enabled_skills:
      - ai-slop-remover
    inject_skill_instructions: true   # Override skill-hint injection for just this node. Falls back to
                                      # agent/graph/global default when omitted.
    skill_instructions: null          # Per-node skill-hint text override; uses the built-in default when omitted.
    output_schema:             # Optional JSON Schema. The output is parsed to JSON
      type: object             # and its top-level object keys auto-merge into state
      properties:              # (so `topic` / `needs_deep_dive` become {{topic}} etc).
@@ -3,6 +3,62 @@
 #  - https://platform.openai.com/docs/api-reference/chat
 - provider: openai
  models:
    - name: gpt-5.5
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 5
      output_price: 30
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.5-pro
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 30
      output_price: 180
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.4
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 2.5
      output_price: 15
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.4-pro
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 30
      output_price: 180
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.4-mini
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 0.75
      output_price: 4.5
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.4-nano
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 0.2
      output_price: 1.25
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.3-codex
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 1.75
      output_price: 14
      supports_vision: true
      supports_function_calling: true
    - name: chat-latest
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 5
      output_price: 30
      supports_vision: true
      supports_function_calling: true
    - name: gpt-5.2
      max_input_tokens: 400000
      max_output_tokens: 128000
@@ -273,9 +329,18 @@
 #  - https://docs.anthropic.com/en/api/messages
 - provider: claude
  models:
    - name: claude-fable-5
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 10
      output_price: 50
      supports_function_calling: true
      supports_vision: true
    - name: claude-opus-4-8
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -283,6 +348,7 @@
    - name: claude-opus-4-7
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -809,9 +875,18 @@
      max_input_tokens: 1048576
      supports_vision: true
      supports_function_calling: true
    - name: claude-fable-5
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 10
      output_price: 50
      supports_function_calling: true
      supports_vision: true
    - name: claude-opus-4-8
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -819,6 +894,7 @@
    - name: claude-opus-4-7
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -978,9 +1054,18 @@
 #  - https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-call.html
 - provider: bedrock
  models:
    - name: us.anthropic.claude-fable-5
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 10
      output_price: 50
      supports_function_calling: true
      supports_vision: true
    - name: us.anthropic.claude-opus-4-8
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -988,6 +1073,7 @@
    - name: us.anthropic.claude-opus-4-7
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -1534,6 +1620,55 @@
 #  - https://openrouter.ai/docs/api-reference/chat-completion
 - provider: openrouter
  models:
    - name: openai/gpt-5.5
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 5
      output_price: 30
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.5-pro
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 30
      output_price: 180
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.4
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 2.5
      output_price: 15
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.4-pro
      max_input_tokens: 1050000
      max_output_tokens: 128000
      input_price: 30
      output_price: 180
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.4-mini
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 0.75
      output_price: 4.5
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.4-nano
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 0.2
      output_price: 1.25
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.3-codex
      max_input_tokens: 400000
      max_output_tokens: 128000
      input_price: 1.75
      output_price: 14
      supports_vision: true
      supports_function_calling: true
    - name: openai/gpt-5.2
      max_input_tokens: 400000
      max_output_tokens: 128000
@@ -1618,9 +1753,18 @@
      max_input_tokens: 131072
      input_price: 0.1
      output_price: 0.2
    - name: anthropic/claude-fable-5
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 10
      output_price: 50
      supports_function_calling: true
      supports_vision: true
    - name: anthropic/claude-opus-4-8
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -1628,6 +1772,7 @@
    - name: anthropic/claude-opus-4-7
      max_input_tokens: 1000000
      max_output_tokens: 128000
      require_max_tokens: true
      input_price: 5
      output_price: 25
      supports_vision: true
@@ -137,7 +137,8 @@ pub(super) fn session_completer(current: &OsStr) -> Vec<CompletionCandidate> {
 pub(super) fn secrets_completer(current: &OsStr) -> Vec<CompletionCandidate> {
    let cur = current.to_string_lossy();
    match load_app_config_for_completion() {
-        Ok(app_config) => Vault::init(&app_config)
+        Ok(app_config) => match Vault::init(&app_config) {
            Ok(vault) => vault
                .list_secrets(false)
                .unwrap_or_default()
                .into_iter()
@@ -145,5 +146,7 @@ pub(super) fn secrets_completer(current: &OsStr) -> Vec<CompletionCandidate> {
                .map(CompletionCandidate::new)
                .collect(),
            Err(_) => vec![],
        },
        Err(_) => vec![],
    }
 }
@@ -4,12 +4,13 @@ use crate::cli::completer::{
    ShellCompletion, agent_completer, macro_completer, model_completer, rag_completer,
    role_completer, secrets_completer, session_completer,
 };
-use crate::config::{AssetCategory, InstallFilter};
+use crate::config::{AssetCategory, InstallFilter, MemoryScope};
 use anyhow::{Context, Result};
-use clap::ValueHint;
+use clap::{ArgGroup, ValueHint};
 use clap::{Parser, crate_authors, crate_description, crate_version};
 use clap_complete::ArgValueCompleter;
 use is_terminal::IsTerminal;
 use std::collections::HashSet;
 use std::io::{Read, stdin};
 #[derive(Parser, Debug)]
@@ -26,7 +27,20 @@ use std::io::{Read, stdin};
 {usage-heading} {usage}
 {all-args}{after-help}
-"
+",
 	group(
 		ArgGroup::new("sbx-mode")
 			.args(["sandbox", "fresh", "no_mixins"])
 			.multiple(true)
 			.conflicts_with_all([
 				"model", "prompt", "role", "session", "agent", "rag", "rebuild_rag",
 				"macro_name", "execute", "code", "file", "no_stream", "no_memory",
 				"init_memory", "dry_run", "info", "build_tools", "install",
 				"install_from", "sync_models", "list_models", "list_roles",
 				"list_sessions", "list_agents", "list_rags", "list_macros",
 				"list_skills", "skill", "tail_logs", "completions", "update",
 			])
 	),
 )]
 pub struct Cli {
    /// Select a LLM model
@@ -74,6 +88,12 @@ pub struct Cli {
    /// Turn off stream mode
    #[arg(short = 'S', long)]
    pub no_stream: bool,
    /// Disable memory for this invocation
    #[arg(long)]
    pub no_memory: bool,
    /// Bootstrap a memory marker so coyote begins loading memory next run
    #[arg(long, value_name = "SCOPE", value_enum)]
    pub init_memory: Option<MemoryScope>,
    /// Display the message without sending it
    #[arg(long)]
    pub dry_run: bool,
@@ -160,9 +180,30 @@ pub struct Cli {
    /// With --update, update even if Coyote was installed via a package manager
    #[arg(long, requires = "update")]
    pub force: bool,
    /// Launch Coyote inside a Docker sandbox (via `sbx`); name defaults to current directory basename
    #[arg(long, value_name = "NAME")]
    pub sandbox: Option<Option<String>>,
    /// Create the sandbox without bootstrapping the host config or vault password file
    #[arg(long, requires = "sandbox")]
    pub fresh: bool,
    /// Skip discovery and application of all sbx mixins (user and built-in)
    #[arg(long, requires = "sandbox")]
    pub no_mixins: bool,
 }
 impl Cli {
    pub fn skills(&self) -> Vec<String> {
        let mut seen = HashSet::new();
        let mut out = Vec::with_capacity(self.skill.len());
        for name in &self.skill {
            if seen.insert(name.clone()) {
                out.push(name.clone());
            }
        }
        out
    }
    pub fn text(&self) -> Result<Option<String>> {
        let mut stdin_text = String::new();
        if !stdin().is_terminal() {
@@ -323,6 +364,21 @@ mod tests {
        );
    }
    #[test]
    fn skills_method_dedupes_preserving_first_occurrence() {
        let cli = parse(&[
            "--skill", "alpha", "--skill", "beta", "--skill", "alpha", "--skill", "gamma",
            "--skill", "beta",
        ]);
        assert_eq!(cli.skills(), vec!["alpha", "beta", "gamma"]);
    }
    #[test]
    fn skills_method_returns_empty_when_no_flags() {
        assert!(parse(&[]).skills().is_empty());
    }
    #[test]
    fn parse_file_flag_single() {
        let cli = parse(&["-f", "file.txt", "question"]);
@@ -461,4 +517,59 @@ mod tests {
    fn parse_force_without_update_fails() {
        assert!(Cli::try_parse_from(["coyote", "--force"]).is_err());
    }
    #[test]
    fn parse_sandbox_flag_no_value() {
        let cli = parse(&["--sandbox"]);
        assert_eq!(cli.sandbox, Some(None));
    }
    #[test]
    fn parse_sandbox_flag_with_name() {
        let cli = parse(&["--sandbox", "my-box"]);
        assert_eq!(cli.sandbox, Some(Some("my-box".to_string())));
    }
    #[test]
    fn parse_sandbox_is_exclusive() {
        assert!(Cli::try_parse_from(["coyote", "--sandbox", "--agent", "foo"]).is_err());
    }
    #[test]
    fn parse_fresh_flag_requires_sandbox() {
        assert!(Cli::try_parse_from(["coyote", "--fresh"]).is_err());
    }
    #[test]
    fn parse_fresh_flag_with_sandbox() {
        let cli = parse(&["--sandbox", "--fresh"]);
        assert_eq!(cli.sandbox, Some(None));
        assert!(cli.fresh);
    }
    #[test]
    fn parse_fresh_flag_with_named_sandbox() {
        let cli = parse(&["--sandbox", "foo", "--fresh"]);
        assert_eq!(cli.sandbox, Some(Some("foo".to_string())));
        assert!(cli.fresh);
    }
    #[test]
    fn parse_no_mixins_requires_sandbox() {
        assert!(Cli::try_parse_from(["coyote", "--no-mixins"]).is_err());
    }
    #[test]
    fn parse_no_mixins_with_sandbox() {
        let cli = parse(&["--sandbox", "--no-mixins"]);
        assert!(cli.no_mixins);
    }
    #[test]
    fn parse_sandbox_with_fresh_and_no_mixins() {
        let cli = parse(&["--sandbox", "foo", "--fresh", "--no-mixins"]);
        assert_eq!(cli.sandbox, Some(Some("foo".to_string())));
        assert!(cli.fresh);
        assert!(cli.no_mixins);
    }
 }
@@ -354,7 +354,9 @@ pub async fn create_config(
        "type": client,
    });
    for (key, desc, help_message, is_secret) in prompts {
-        let env_name = format!("{client}_{key}").to_ascii_uppercase();
+        let env_name = format!("{client}-{key}")
            .to_ascii_uppercase()
            .replace("_", "-");
        let required = std::env::var(&env_name).is_err();
        let value = if !is_secret {
            prompt_input_string(desc, required, *help_message)?
@@ -119,7 +119,11 @@ fn prepare_chat_completions(
            format!("{base_url}/google/models/{model_name}:{func}")
        }
        ModelCategory::Claude => {
-            format!("{base_url}/anthropic/models/{model_name}:streamRawPredict")
+            let func = match data.stream {
                true => "streamRawPredict",
                false => "rawPredict",
            };
            format!("{base_url}/anthropic/models/{model_name}:{func}")
        }
        ModelCategory::Mistral => {
            let func = match data.stream {
@@ -2,6 +2,7 @@ use super::*;
 use crate::{
    client::Model,
    config::memory,
    function::{Functions, run_llm_function},
 };
@@ -19,7 +20,7 @@ use fancy_regex::Captures;
 use inquire::{Text, validator::Validation};
 use rust_embed::Embed;
 use serde::{Deserialize, Serialize};
-use std::{ffi::OsStr, path::Path};
+use std::{env, ffi::OsStr, path::Path};
 const DEFAULT_AGENT_NAME: &str = "rag";
@@ -207,6 +208,27 @@ impl Agent {
        functions.append_teammate_functions();
        functions.append_user_interaction_functions();
        if app.function_calling_support
            && app.skills_enabled
            && !matches!(agent_config.skills_enabled, Some(false))
        {
            functions.append_skill_functions();
        }
        if app.function_calling_support
            && !matches!(agent_config.memory, Some(false))
            && !matches!(app.memory, Some(false))
        {
            let memory_exists = paths::global_memory_index_path().exists()
                || env::current_dir()
                    .ok()
                    .and_then(|cwd| memory::discover_workspace_memory(&cwd))
                    .is_some();
            if memory_exists {
                functions.append_memory_functions();
            }
        }
        agent_config.replace_tools_placeholder(&functions);
        Ok(Self {
@@ -345,6 +367,18 @@ impl Agent {
        self.config.enabled_skills.as_deref()
    }
    pub fn memory(&self) -> Option<bool> {
        self.config.memory
    }
    pub fn set_skills_enabled(&mut self, value: Option<bool>) {
        self.config.skills_enabled = value;
    }
    pub fn set_enabled_skills(&mut self, value: Option<Vec<String>>) {
        self.config.enabled_skills = value;
    }
    pub fn conversation_starters(&self) -> Vec<String> {
        self.config
            .conversation_starters
@@ -449,6 +483,14 @@ impl Agent {
        self.config.continuation_prompt.clone()
    }
    pub fn inject_skill_instructions(&self) -> bool {
        self.config.inject_skill_instructions
    }
    pub fn skill_instructions_value(&self) -> Option<String> {
        self.config.skill_instructions.clone()
    }
    pub fn can_spawn_agents(&self) -> bool {
        self.config.can_spawn_agents
    }
@@ -533,12 +575,12 @@ impl RoleLike for Agent {
        self.config.top_p
    }
-    fn enabled_tools(&self) -> Option<String> {
+    fn enabled_tools(&self) -> Option<Vec<String>> {
        None
    }
-    fn enabled_mcp_servers(&self) -> Option<String> {
+    fn enabled_mcp_servers(&self) -> Option<Vec<String>> {
-        self.config.mcp_servers.clone().join(",").into()
+        Some(self.config.mcp_servers.clone())
    }
    fn set_model(&mut self, model: Model) {
@@ -554,15 +596,14 @@ impl RoleLike for Agent {
        self.config.top_p = value;
    }
-    fn set_enabled_tools(&mut self, value: Option<String>) {
+    fn set_enabled_tools(&mut self, value: Option<Vec<String>>) {
        match value {
            Some(tools) => {
-                let tools = tools
+                self.config.global_tools = tools
-                    .split(',')
+                    .into_iter()
                    .map(|v| v.trim().to_string())
                    .filter(|v| !v.is_empty())
                    .collect::<Vec<_>>();
                self.config.global_tools = tools;
            }
            None => {
                self.config.global_tools.clear();
@@ -570,15 +611,14 @@ impl RoleLike for Agent {
        }
    }
-    fn set_enabled_mcp_servers(&mut self, value: Option<String>) {
+    fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>) {
        match value {
            Some(servers) => {
-                let servers = servers
+                self.config.mcp_servers = servers
-                    .split(',')
+                    .into_iter()
                    .map(|v| v.trim().to_string())
                    .filter(|v| !v.is_empty())
                    .collect::<Vec<_>>();
                self.config.mcp_servers = servers;
            }
            None => {
                self.config.mcp_servers.clear();
@@ -612,6 +652,12 @@ pub struct AgentConfig {
    pub inject_todo_instructions: bool,
    #[serde(default = "default_true")]
    pub inject_spawn_instructions: bool,
    #[serde(default = "default_true")]
    pub inject_skill_instructions: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub skill_instructions: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub memory: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub compression_threshold: Option<usize>,
    #[serde(default)]
@@ -689,6 +735,10 @@ impl AgentConfig {
            description: graph.description.clone(),
            global_tools: graph.global_tools.clone(),
            mcp_servers: graph.mcp_servers.clone(),
            skills_enabled: graph.skills_enabled,
            enabled_skills: graph.enabled_skills.clone(),
            inject_skill_instructions: graph.inject_skill_instructions.unwrap_or(true),
            skill_instructions: graph.skill_instructions.clone(),
            conversation_starters: graph.conversation_starters.clone(),
            variables: graph.variables.clone(),
            can_spawn_agents: graph.has_agent_node(),
@@ -3,7 +3,8 @@ use crate::render::{MarkdownRender, RenderOptions};
 use crate::utils::{IS_STDOUT_TERMINAL, NO_COLOR, decode_bin, get_env_name};
 use super::paths;
-use anyhow::{Context, Result, anyhow};
+use anyhow::{Context, Result, anyhow, bail};
 use gman::providers::SupportedProvider;
 use indexmap::IndexMap;
 use serde::Deserialize;
 use std::collections::HashMap;
@@ -29,24 +30,30 @@ pub struct AppConfig {
    pub wrap: Option<String>,
    pub wrap_code: bool,
    pub(crate) vault_password_file: Option<PathBuf>,
    pub(crate) secrets_provider: Option<SupportedProvider>,
    pub function_calling_support: bool,
    pub mapping_tools: IndexMap<String, String>,
-    pub enabled_tools: Option<String>,
+    #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
    pub enabled_tools: Option<Vec<String>>,
    pub visible_tools: Option<Vec<String>>,
    pub skills_enabled: bool,
-    pub enabled_skills: Option<String>,
+    #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
    pub enabled_skills: Option<Vec<String>>,
    pub visible_skills: Option<Vec<String>>,
    pub mcp_server_support: bool,
    pub mapping_mcp_servers: IndexMap<String, String>,
-    pub enabled_mcp_servers: Option<String>,
+    #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
    pub enabled_mcp_servers: Option<Vec<String>>,
    pub auto_continue: bool,
    pub max_auto_continues: usize,
    pub inject_todo_instructions: bool,
    pub continuation_prompt: Option<String>,
    pub inject_skill_instructions: bool,
    pub skill_instructions: Option<String>,
    pub repl_prelude: Option<String>,
    pub cmd_prelude: Option<String>,
@@ -57,6 +64,10 @@ pub struct AppConfig {
    pub summarization_prompt: Option<String>,
    pub summary_context_prompt: Option<String>,
    pub memory: Option<bool>,
    pub memory_cap_with_tools: Option<usize>,
    pub memory_cap_without_tools: Option<usize>,
    pub rag_embedding_model: Option<String>,
    pub rag_reranker_model: Option<String>,
    pub rag_top_k: usize,
@@ -94,6 +105,7 @@ impl Default for AppConfig {
            wrap: None,
            wrap_code: false,
            vault_password_file: None,
            secrets_provider: None,
            function_calling_support: true,
            mapping_tools: Default::default(),
@@ -112,6 +124,8 @@ impl Default for AppConfig {
            max_auto_continues: 10,
            inject_todo_instructions: true,
            continuation_prompt: None,
            inject_skill_instructions: true,
            skill_instructions: None,
            repl_prelude: None,
            cmd_prelude: None,
@@ -122,6 +136,10 @@ impl Default for AppConfig {
            summarization_prompt: None,
            summary_context_prompt: None,
            memory: None,
            memory_cap_with_tools: None,
            memory_cap_without_tools: None,
            rag_embedding_model: None,
            rag_reranker_model: None,
            rag_top_k: 5,
@@ -160,6 +178,7 @@ impl AppConfig {
            wrap: config.wrap,
            wrap_code: config.wrap_code,
            vault_password_file: config.vault_password_file,
            secrets_provider: config.secrets_provider,
            function_calling_support: config.function_calling_support,
            mapping_tools: config.mapping_tools,
@@ -178,6 +197,8 @@ impl AppConfig {
            max_auto_continues: config.max_auto_continues,
            inject_todo_instructions: config.inject_todo_instructions,
            continuation_prompt: config.continuation_prompt,
            inject_skill_instructions: config.inject_skill_instructions,
            skill_instructions: config.skill_instructions,
            repl_prelude: config.repl_prelude,
            cmd_prelude: config.cmd_prelude,
@@ -188,6 +209,10 @@ impl AppConfig {
            summarization_prompt: config.summarization_prompt,
            summary_context_prompt: config.summary_context_prompt,
            memory: config.memory,
            memory_cap_with_tools: config.memory_cap_with_tools,
            memory_cap_without_tools: config.memory_cap_without_tools,
            rag_embedding_model: config.rag_embedding_model,
            rag_reranker_model: config.rag_reranker_model,
            rag_top_k: config.rag_top_k,
@@ -209,6 +234,7 @@ impl AppConfig {
            clients: config.clients,
        };
        app_config.load_envs();
        app_config.validate_visible_skills()?;
        if let Some(wrap) = app_config.wrap.clone() {
            app_config.set_wrap(&wrap)?;
        }
@@ -218,11 +244,28 @@ impl AppConfig {
        Ok(app_config)
    }
    fn validate_visible_skills(&self) -> Result<()> {
        let Some(skills) = self.visible_skills.as_ref() else {
            return Ok(());
        };
        for name in skills {
            paths::validate_skill_name(name)
                .map_err(|e| anyhow!("invalid entry in visible_skills: {e}"))?;
            if !paths::has_skill(name) {
                bail!("visible_skills references skill '{name}' which is not installed");
            }
        }
        Ok(())
    }
    pub fn resolve_model(&mut self) -> Result<()> {
        if self.model_id.is_empty() {
            let models = list_models(self, crate::client::ModelType::Chat);
            if models.is_empty() {
-                anyhow::bail!("No available model");
+                bail!("No available model");
            }
            self.model_id = models[0].id();
        }
@@ -231,10 +274,25 @@ impl AppConfig {
    pub fn vault_password_file(&self) -> PathBuf {
        match &self.vault_password_file {
-            Some(path) => match path.exists() {
+            Some(path) => {
-                true => path.clone(),
+                if path.exists() {
-                false => gman::config::Config::local_provider_password_file(),
+                    return path.clone();
-            },
+                }
                if let Some(translated) = paths::translate_sandboxed_home_path(path)
                    && translated.exists()
                {
                    info!(
                        "vault_password_file '{}' not found; resolved to sandboxed path '{}'",
                        path.display(),
                        translated.display()
                    );
                    return translated;
                }
                gman::config::Config::local_provider_password_file()
            }
            None => gman::config::Config::local_provider_password_file(),
        }
    }
@@ -388,7 +446,7 @@ impl AppConfig {
            self.mapping_tools = v;
        }
        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_tools")) {
-            self.enabled_tools = v;
+            self.enabled_tools = v.map(|raw| super::csv_to_vec(&raw));
        }
        if let Some(Some(v)) = super::read_env_bool(&get_env_name("skills_enabled")) {
@@ -396,7 +454,7 @@ impl AppConfig {
        }
        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_skills")) {
-            self.enabled_skills = v;
+            self.enabled_skills = v.map(|raw| super::csv_to_vec(&raw));
        }
        if let Some(Some(v)) = super::read_env_bool(&get_env_name("mcp_server_support")) {
@@ -408,7 +466,7 @@ impl AppConfig {
            self.mapping_mcp_servers = v;
        }
        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_mcp_servers")) {
-            self.enabled_mcp_servers = v;
+            self.enabled_mcp_servers = v.map(|raw| super::csv_to_vec(&raw));
        }
        if let Some(v) = super::read_env_value::<String>(&get_env_name("repl_prelude")) {
@@ -510,12 +568,12 @@ impl AppConfig {
    }
    #[allow(dead_code)]
-    pub fn set_enabled_tools_default(&mut self, value: Option<String>) {
+    pub fn set_enabled_tools_default(&mut self, value: Option<Vec<String>>) {
        self.enabled_tools = value;
    }
    #[allow(dead_code)]
-    pub fn set_enabled_mcp_servers_default(&mut self, value: Option<String>) {
+    pub fn set_enabled_mcp_servers_default(&mut self, value: Option<Vec<String>>) {
        self.enabled_mcp_servers = value;
    }
@@ -772,4 +830,42 @@ mod tests {
        app.resolve_model().unwrap();
        assert_eq!(app.model_id, "provider:explicit");
    }
    #[test]
    fn default_secrets_provider_is_none() {
        let app = AppConfig::default();
        assert!(app.secrets_provider.is_none());
    }
    #[test]
    fn secrets_provider_can_hold_non_local_variant() {
        let app = AppConfig {
            secrets_provider: Some(SupportedProvider::Gopass {
                provider_def: Default::default(),
            }),
            ..AppConfig::default()
        };
        assert!(matches!(
            app.secrets_provider,
            Some(SupportedProvider::Gopass { .. })
        ));
    }
    #[test]
    fn from_config_copies_secrets_provider() {
        let cfg = Config {
            model_id: "test-model".to_string(),
            clients: vec![ClientConfig::default()],
            secrets_provider: Some(SupportedProvider::Gopass {
                provider_def: Default::default(),
            }),
            ..Config::default()
        };
        let app = AppConfig::from_config(cfg).unwrap();
        assert!(matches!(
            app.secrets_provider,
            Some(SupportedProvider::Gopass { .. })
        ));
    }
 }
@@ -43,7 +43,7 @@ impl AppState {
        start_mcp_servers: bool,
        abort_signal: AbortSignal,
    ) -> Result<Self> {
-        let vault = Arc::new(Vault::init(&config));
+        let vault = Arc::new(Vault::init(&config)?);
        let mcp_registry = McpRegistry::init(
            log_path,
@@ -38,10 +38,10 @@ pub struct Input {
 }
 impl Input {
-    pub fn from_str(ctx: &RequestContext, text: &str, role: Option<Role>) -> Self {
+    pub fn from_str(ctx: &RequestContext, text: &str, role: Option<Role>) -> Result<Self> {
-        let (role, with_session, with_agent) = resolve_role(ctx, role);
+        let (role, with_session, with_agent) = resolve_role(ctx, role)?;
        let captured = capture_input_config(ctx, &role);
-        Self {
+        Ok(Self {
            app_config: Arc::clone(&ctx.app.config),
            stream_enabled: captured.stream_enabled,
            session: captured.session,
@@ -60,7 +60,7 @@ impl Input {
            rag_name: None,
            with_session,
            with_agent,
-        }
+        })
    }
    pub async fn from_files(
@@ -111,7 +111,7 @@ impl Input {
                ));
            }
        }
-        let (role, with_session, with_agent) = resolve_role(ctx, role);
+        let (role, with_session, with_agent) = resolve_role(ctx, role)?;
        let captured = capture_input_config(ctx, &role);
        Ok(Self {
            app_config: Arc::clone(&ctx.app.config),
@@ -398,14 +398,14 @@ impl Input {
    }
 }
-fn resolve_role(ctx: &RequestContext, role: Option<Role>) -> (Role, bool, bool) {
+fn resolve_role(ctx: &RequestContext, role: Option<Role>) -> Result<(Role, bool, bool)> {
    match role {
-        Some(v) => (v, false, false),
+        Some(v) => Ok((v, false, false)),
-        None => (
+        None => Ok((
-            ctx.extract_role(ctx.app.config.as_ref()),
+            ctx.extract_role(ctx.app.config.as_ref())?,
            ctx.session.is_some(),
            ctx.agent.is_some(),
-        ),
+        )),
    }
 }
@@ -600,7 +600,7 @@ mod tests {
    fn resolve_role_with_explicit_role() {
        let ctx = create_test_ctx();
        let role = Role::new("custom", "be helpful");
-        let (resolved, with_session, with_agent) = resolve_role(&ctx, Some(role));
+        let (resolved, with_session, with_agent) = resolve_role(&ctx, Some(role)).unwrap();
        assert_eq!(resolved.name(), "custom");
        assert!(!with_session);
        assert!(!with_agent);
@@ -609,7 +609,7 @@ mod tests {
    #[test]
    fn resolve_role_without_role_no_session_no_agent() {
        let ctx = create_test_ctx();
-        let (resolved, with_session, with_agent) = resolve_role(&ctx, None);
+        let (resolved, with_session, with_agent) = resolve_role(&ctx, None).unwrap();
        assert_eq!(resolved.name(), "");
        assert!(!with_session);
        assert!(!with_agent);
@@ -619,7 +619,7 @@ mod tests {
    fn resolve_role_without_role_with_session() {
        let mut ctx = create_test_ctx();
        ctx.session = Some(Session::default());
-        let (_resolved, with_session, with_agent) = resolve_role(&ctx, None);
+        let (_resolved, with_session, with_agent) = resolve_role(&ctx, None).unwrap();
        assert!(with_session);
        assert!(!with_agent);
    }
@@ -629,7 +629,7 @@ mod tests {
        let mut ctx = create_test_ctx();
        ctx.session = Some(Session::default());
        let role = Role::new("explicit", "prompt");
-        let (_resolved, with_session, _with_agent) = resolve_role(&ctx, Some(role));
+        let (_resolved, with_session, _with_agent) = resolve_role(&ctx, Some(role)).unwrap();
        assert!(!with_session);
    }
@@ -695,7 +695,7 @@ mod tests {
    #[test]
    fn input_from_str_captures_text() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "hello world", None);
+        let input = Input::from_str(&ctx, "hello world", None).unwrap();
        assert_eq!(input.text(), "hello world");
    }
@@ -703,7 +703,7 @@ mod tests {
    fn input_from_str_with_explicit_role() {
        let ctx = create_test_ctx();
        let role = Role::new("pirate", "you are a pirate");
-        let input = Input::from_str(&ctx, "ahoy", Some(role));
+        let input = Input::from_str(&ctx, "ahoy", Some(role)).unwrap();
        assert_eq!(input.role().name(), "pirate");
        assert!(!input.with_agent());
    }
@@ -715,28 +715,28 @@ mod tests {
        config.stream = false;
        state.config = Arc::new(config);
        let ctx = RequestContext::new(Arc::new(state), WorkingMode::Cmd);
-        let input = Input::from_str(&ctx, "test", None);
+        let input = Input::from_str(&ctx, "test", None).unwrap();
        assert!(!input.stream_enabled);
    }
    #[test]
    fn input_is_empty_with_no_text_and_no_medias() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "", None);
+        let input = Input::from_str(&ctx, "", None).unwrap();
        assert!(input.is_empty());
    }
    #[test]
    fn input_is_not_empty_with_text() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "hello", None);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
        assert!(!input.is_empty());
    }
    #[test]
    fn input_set_text_changes_text() {
        let ctx = create_test_ctx();
-        let mut input = Input::from_str(&ctx, "original", None);
+        let mut input = Input::from_str(&ctx, "original", None).unwrap();
        input.set_text("modified".to_string());
        assert_eq!(input.text(), "modified");
    }
@@ -744,7 +744,7 @@ mod tests {
    #[test]
    fn input_text_returns_patched_when_set() {
        let ctx = create_test_ctx();
-        let mut input = Input::from_str(&ctx, "original", None);
+        let mut input = Input::from_str(&ctx, "original", None).unwrap();
        input.patched_text = Some("patched".to_string());
        assert_eq!(input.text(), "patched");
    }
@@ -752,7 +752,7 @@ mod tests {
    #[test]
    fn input_clear_patch_restores_original() {
        let ctx = create_test_ctx();
-        let mut input = Input::from_str(&ctx, "original", None);
+        let mut input = Input::from_str(&ctx, "original", None).unwrap();
        input.patched_text = Some("patched".to_string());
        input.clear_patch();
        assert_eq!(input.text(), "original");
@@ -761,7 +761,7 @@ mod tests {
    #[test]
    fn input_set_continue_output_accumulates() {
        let ctx = create_test_ctx();
-        let mut input = Input::from_str(&ctx, "test", None);
+        let mut input = Input::from_str(&ctx, "test", None).unwrap();
        assert!(input.continue_output().is_none());
        input.set_continue_output("first ");
        assert_eq!(input.continue_output(), Some("first "));
@@ -772,7 +772,7 @@ mod tests {
    #[test]
    fn input_set_regenerate_sets_flag_and_clears_tool_calls() {
        let ctx = create_test_ctx();
-        let mut input = Input::from_str(&ctx, "test", None);
+        let mut input = Input::from_str(&ctx, "test", None).unwrap();
        let role = input.role().clone();
        assert!(!input.regenerate());
        input.set_regenerate(role);
@@ -784,7 +784,7 @@ mod tests {
    fn input_summary_truncates_long_text() {
        let ctx = create_test_ctx();
        let long_text = "a".repeat(200);
-        let input = Input::from_str(&ctx, &long_text, None);
+        let input = Input::from_str(&ctx, &long_text, None).unwrap();
        let summary = input.summary();
        assert!(summary.len() < 200);
        assert!(summary.ends_with("..."));
@@ -793,35 +793,35 @@ mod tests {
    #[test]
    fn input_summary_preserves_short_text() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "short", None);
+        let input = Input::from_str(&ctx, "short", None).unwrap();
        assert_eq!(input.summary(), "short");
    }
    #[test]
    fn input_raw_with_no_files() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "hello", None);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
        assert_eq!(input.raw(), "hello");
    }
    #[test]
    fn input_render_with_no_medias() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "hello", None);
+        let input = Input::from_str(&ctx, "hello", None).unwrap();
        assert_eq!(input.render(), "hello");
    }
    #[test]
    fn input_with_agent_false_when_no_agent() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "test", None);
+        let input = Input::from_str(&ctx, "test", None).unwrap();
        assert!(!input.with_agent());
    }
    #[test]
    fn input_session_returns_none_when_with_session_false() {
        let ctx = create_test_ctx();
-        let input = Input::from_str(&ctx, "test", Some(Role::new("r", "p")));
+        let input = Input::from_str(&ctx, "test", Some(Role::new("r", "p"))).unwrap();
        let session = Some(Session::default());
        assert!(input.session(&session).is_none());
    }
@@ -830,7 +830,7 @@ mod tests {
    fn input_session_returns_some_when_with_session_true() {
        let mut ctx = create_test_ctx();
        ctx.session = Some(Session::default());
-        let input = Input::from_str(&ctx, "test", None);
+        let input = Input::from_str(&ctx, "test", None).unwrap();
        let session = Some(Session::default());
        assert!(input.session(&session).is_some());
    }
@@ -1,10 +1,3 @@
 use anyhow::{Context, Result, bail};
 use indexmap::IndexMap;
 use inquire::{Confirm, Select};
 use std::ffi::{OsStr, OsString};
 use std::fs;
 use std::path::{Path, PathBuf};
 use crate::config::{InstallFilter, paths};
 #[cfg(not(windows))]
 use crate::function::Language;
@@ -12,6 +5,13 @@ use crate::mcp::{McpServer, McpServersConfig};
 use crate::utils;
 use crate::utils::IS_STDOUT_TERMINAL;
 use crate::vault::{Vault, create_vault_password_file, interpolate_secrets};
 use anyhow::{Context, Result, anyhow, bail};
 use indexmap::IndexMap;
 use indoc::formatdoc;
 use inquire::{Confirm, Select};
 use std::ffi::{OsStr, OsString};
 use std::fs;
 use std::path::{Path, PathBuf};
 pub fn install_remote(git_url: &str, filter: Option<InstallFilter>, force: bool) -> Result<()> {
    let (url, reference) = parse_url_with_ref(git_url)?;
@@ -375,7 +375,12 @@ fn plan_changes(layout: &RemoteLayout) -> Result<InstallPlan> {
    }
    if let Some(src_dir) = &layout.skills {
-        plan_dir_into(src_dir, &paths::skills_dir(), TopCategory::Skills, &mut files)?;
+        plan_dir_into(
            src_dir,
            &paths::skills_dir(),
            TopCategory::Skills,
            &mut files,
        )?;
    }
    if let Some(src_dir) = &layout.macros {
@@ -413,6 +418,26 @@ fn plan_dir_into(
        let rel = src
            .strip_prefix(src_dir)
            .expect("walk_files only returns paths under src_dir");
        if category == TopCategory::Skills {
            let skill_name = rel
                .components()
                .next()
                .and_then(|c| c.as_os_str().to_str())
                .ok_or_else(|| {
                    anyhow!(
                        "remote skill bundle has unparseable path component: {}",
                        rel.display()
                    )
                })?;
            paths::validate_skill_name(skill_name).with_context(|| {
                format!(
                    "remote skill '{skill_name}' has an invalid name \
                     (skill names must contain only ASCII alphanumerics, '-', or '_')"
                )
            })?;
        }
        let dst = dst_dir.join(rel);
        let kind = classify_file(&src, &dst)?;
        out.push(PlannedFile {
@@ -726,8 +751,21 @@ fn merge_mcp_json(
        serde_json::to_string_pretty(&merged).context("failed to serialize merged mcp.json")?;
    write_atomically(&final_path, &serialized)?;
-    let vault = Vault::init_bare();
+    let vault = Vault::init_bare()?;
-    let (_parsed, missing) = interpolate_secrets(&serialized, &vault);
+    let missing = match interpolate_secrets(&serialized, &vault) {
        Ok((_, missing)) => missing,
        Err(e) => {
            eprintln!(
                "{}",
                formatdoc! {"
                Skipping secret resolution for merged mcp.json: {e:#}
                Continuing without resolving missing secrets
                You may need to add any additional missing secrets to the vault manually.
            "}
            );
            Vec::new()
        }
    };
    let mut deduped: Vec<String> = Vec::new();
    for s in missing {
        if !deduped.contains(&s) {
@@ -855,7 +893,7 @@ fn handle_missing_secrets(missing: &[String]) -> Result<()> {
 }
 fn prompt_for_each_secret(missing: &[String]) -> Result<(Vec<String>, Vec<String>)> {
-    let mut vault = Vault::init_bare();
+    let mut vault = Vault::init_bare()?;
    let mut password_file_ensured = false;
    let mut added = Vec::new();
    let mut deferred = Vec::new();
@@ -909,6 +947,62 @@ fn print_secret_summary(added: &[String], deferred: &[String]) {
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::utils::get_env_name;
    use serial_test::serial;
    use std::env;
    use std::time::{SystemTime, UNIX_EPOCH};
    struct TestVaultConfigGuard {
        dir_key: String,
        file_key: String,
        previous_dir: Option<OsString>,
        previous_file: Option<OsString>,
        path: PathBuf,
    }
    impl TestVaultConfigGuard {
        fn new(label: &str) -> Self {
            let dir_key = get_env_name("config_dir");
            let file_key = get_env_name("config_file");
            let previous_dir = env::var_os(&dir_key);
            let previous_file = env::var_os(&file_key);
            let unique = SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .unwrap()
                .as_nanos();
            let path = env::temp_dir().join(format!("coyote-vault-test-{label}-{unique}"));
            fs::create_dir_all(&path).unwrap();
            let config_path = path.join("config.yaml");
            fs::write(&config_path, "{}").unwrap();
            unsafe {
                env::set_var(&dir_key, &path);
                env::set_var(&file_key, &config_path);
            }
            Self {
                dir_key,
                file_key,
                previous_dir,
                previous_file,
                path,
            }
        }
    }
    impl Drop for TestVaultConfigGuard {
        fn drop(&mut self) {
            unsafe {
                match &self.previous_dir {
                    Some(p) => env::set_var(&self.dir_key, p),
                    None => env::remove_var(&self.dir_key),
                }
                match &self.previous_file {
                    Some(p) => env::set_var(&self.file_key, p),
                    None => env::remove_var(&self.file_key),
                }
            }
            let _ = fs::remove_dir_all(&self.path);
        }
    }
    #[test]
    fn parse_url_no_ref() {
@@ -1248,7 +1342,9 @@ mod tests {
    }
    #[test]
    #[serial]
    fn merge_into_empty_local_adds_all_remote_servers() {
        let _guard = TestVaultConfigGuard::new("merge-empty");
        let dir = fresh_temp_dir("merge-empty-");
        let remote = dir.join("remote.json");
        let target = dir.join("target.json");
@@ -1265,7 +1361,9 @@ mod tests {
    }
    #[test]
    #[serial]
    fn merge_force_replaces_local_on_conflict() {
        let _guard = TestVaultConfigGuard::new("merge-force");
        let dir = fresh_temp_dir("merge-force-");
        let remote = dir.join("remote.json");
        let target = dir.join("target.json");
@@ -1289,6 +1387,12 @@ mod tests {
    #[test]
    fn merge_non_tty_conflict_aborts_without_force() {
        if *IS_STDOUT_TERMINAL {
            eprintln!(
                "Skipping merge_non_tty_conflict_aborts_without_force: requires non-TTY stdout"
            );
            return;
        }
        let dir = fresh_temp_dir("merge-non-tty-");
        let remote = dir.join("remote.json");
        let target = dir.join("target.json");
@@ -1325,7 +1429,9 @@ mod tests {
    }
    #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
    #[serial]
    async fn merge_detects_missing_secrets_in_output() {
        let _guard = TestVaultConfigGuard::new("merge-secret");
        let dir = fresh_temp_dir("merge-secret-");
        let remote = dir.join("remote.json");
        let target = dir.join("target.json");
@@ -1341,7 +1447,9 @@ mod tests {
    }
    #[test]
    #[serial]
    fn merge_is_idempotent_on_re_run() {
        let _guard = TestVaultConfigGuard::new("merge-idempotent");
        let dir = fresh_temp_dir("merge-idempotent-");
        let remote = dir.join("remote.json");
        let target = dir.join("target.json");
@@ -1365,6 +1473,12 @@ mod tests {
    #[test]
    fn handle_missing_secrets_defers_all_in_non_tty() {
        if *IS_STDOUT_TERMINAL {
            eprintln!(
                "Skipping handle_missing_secrets_defers_all_in_non_tty: requires non-TTY stdout"
            );
            return;
        }
        let missing = vec![
            "COYOTE_TEST_STEP4_A".to_string(),
            "COYOTE_TEST_STEP4_B".to_string(),
@@ -29,12 +29,12 @@ pub async fn macro_execute(
    let variables = macro_value
        .resolve_variables(&new_args)
        .map_err(|err| anyhow!("{err}. Usage: {}", macro_value.usage(name)))?;
-    let role = ctx.extract_role(ctx.app.config.as_ref());
+    let role = ctx.extract_role(ctx.app.config.as_ref())?;
    let mut app_config = (*ctx.app.config).clone();
    app_config.temperature = role.temperature();
    app_config.top_p = role.top_p();
-    app_config.enabled_tools = role.enabled_tools().clone();
+    app_config.enabled_tools = role.enabled_tools();
-    app_config.enabled_mcp_servers = role.enabled_mcp_servers().clone();
+    app_config.enabled_mcp_servers = role.enabled_mcp_servers();
    let mut app_state = (*ctx.app).clone();
    app_state.config = Arc::new(app_config);
@@ -0,0 +1,733 @@
 use std::fs;
 use std::path::{Path, PathBuf};
 use anyhow::{Context, Result};
 use log::warn;
 use serde::{Deserialize, Serialize};
 use crate::config::{
    GIT_DIR_NAME, GITIGNORE_FILE_NAME, MEMORY_DIR_NAME, MEMORY_INDEX_FILE_NAME,
    WORKSPACE_MEMORY_DIR_NAME, WORKSPACE_MEMORY_FILE_NAME, paths,
 };
 pub const DEFAULT_MEMORY_CAP_WITH_TOOLS: usize = 6_000;
 pub const DEFAULT_MEMORY_CAP_WITHOUT_TOOLS: usize = 12_000;
 #[derive(Debug, Clone)]
 pub enum WorkspaceMemory {
    Structured {
        workspace_root: PathBuf,
        dir: PathBuf,
    },
    Lite {
        workspace_root: PathBuf,
        file: PathBuf,
    },
 }
 pub fn discover_workspace_memory(start: &Path) -> Option<WorkspaceMemory> {
    for dir in start.ancestors() {
        let structured = dir.join(WORKSPACE_MEMORY_DIR_NAME).join(MEMORY_DIR_NAME);
        if structured.join(MEMORY_INDEX_FILE_NAME).exists() {
            return Some(WorkspaceMemory::Structured {
                workspace_root: dir.to_path_buf(),
                dir: structured,
            });
        }
        let lite = dir.join(WORKSPACE_MEMORY_FILE_NAME);
        if lite.exists() {
            return Some(WorkspaceMemory::Lite {
                workspace_root: dir.to_path_buf(),
                file: lite,
            });
        }
    }
    None
 }
 pub fn find_git_root(start: &Path) -> Option<PathBuf> {
    for dir in start.ancestors() {
        if dir.join(GIT_DIR_NAME).exists() {
            return Some(dir.to_path_buf());
        }
    }
    None
 }
 pub fn bootstrap_workspace_memory(git_root: &Path) -> Result<PathBuf> {
    let mem_dir = paths::workspace_memory_dir_for(git_root);
    fs::create_dir_all(&mem_dir)
        .with_context(|| format!("create memory dir {}", mem_dir.display()))?;
    let index_path = mem_dir.join(MEMORY_INDEX_FILE_NAME);
    if !index_path.exists() {
        fs::write(&index_path, "# Workspace Memory Index\n\n")
            .with_context(|| format!("write {}", index_path.display()))?;
    }
    let gitignore_appended = append_gitignore_entry(git_root)?;
    let suffix = if gitignore_appended {
        " (appended .coyote/memory/ to .gitignore)"
    } else {
        ""
    };
    warn!(
        "auto-bootstrapped workspace memory at {}{}",
        mem_dir.display(),
        suffix
    );
    Ok(mem_dir)
 }
 fn append_gitignore_entry(git_root: &Path) -> Result<bool> {
    let gitignore = git_root.join(GITIGNORE_FILE_NAME);
    let entry = format!("{WORKSPACE_MEMORY_DIR_NAME}/{MEMORY_DIR_NAME}/");
    let entry_no_slash = format!("{WORKSPACE_MEMORY_DIR_NAME}/{MEMORY_DIR_NAME}");
    let existing = fs::read_to_string(&gitignore).unwrap_or_default();
    let already_present = existing.lines().any(|line| {
        let trimmed = line.trim();
        trimmed == entry || trimmed == entry_no_slash
    });
    if already_present {
        return Ok(false);
    }
    let new_content = if existing.is_empty() {
        format!("{entry}\n")
    } else if existing.ends_with('\n') {
        format!("{existing}{entry}\n")
    } else {
        format!("{existing}\n{entry}\n")
    };
    fs::write(&gitignore, new_content).with_context(|| format!("write {}", gitignore.display()))?;
    Ok(true)
 }
 #[derive(Debug, Clone, Deserialize, Serialize, Default)]
 pub struct MemoryFrontmatter {
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default, rename = "type")]
    pub kind: Option<String>,
 }
 #[derive(Debug, Clone)]
 pub struct MemoryFile {
    pub path: PathBuf,
    pub frontmatter: MemoryFrontmatter,
    pub body: String,
 }
 impl MemoryFile {
    pub fn load(path: &Path) -> Result<Self> {
        let raw = fs::read_to_string(path)
            .with_context(|| format!("read memory file {}", path.display()))?;
        let (frontmatter, body) = parse_frontmatter(&raw)
            .with_context(|| format!("parse frontmatter in {}", path.display()))?;
        Ok(Self {
            path: path.to_path_buf(),
            frontmatter,
            body,
        })
    }
    pub fn save(&self) -> Result<()> {
        if let Some(parent) = self.path.parent() {
            fs::create_dir_all(parent)?;
        }
        let frontmatter_yaml = serde_yaml::to_string(&self.frontmatter)?;
        let content = format!("---\n{}---\n\n{}", frontmatter_yaml, self.body);
        fs::write(&self.path, content)?;
        Ok(())
    }
    pub fn char_len(&self) -> usize {
        self.body.chars().count()
    }
 }
 fn parse_frontmatter(raw: &str) -> Result<(MemoryFrontmatter, String)> {
    let trimmed = raw.trim_start();
    if !trimmed.starts_with("---") {
        return Ok((MemoryFrontmatter::default(), raw.to_string()));
    }
    let after = &trimmed[3..];
    let Some(end) = after.find("\n---") else {
        return Ok((MemoryFrontmatter::default(), raw.to_string()));
    };
    let yaml = &after[..end];
    let body = after[end + 4..].trim_start_matches('\n').to_string();
    let frontmatter: MemoryFrontmatter =
        serde_yaml::from_str(yaml.trim()).context("parse YAML frontmatter")?;
    Ok((frontmatter, body))
 }
 #[derive(Debug, Clone)]
 pub struct MemoryStore {
    pub global_dir: PathBuf,
    pub workspace: Option<WorkspaceMemory>,
 }
 impl MemoryStore {
    pub fn new(cwd: &Path) -> Self {
        Self {
            global_dir: paths::global_memory_dir(),
            workspace: discover_workspace_memory(cwd),
        }
    }
    pub fn load_global_index(&self) -> Result<Option<String>> {
        let path = self.global_dir.join(MEMORY_INDEX_FILE_NAME);
        if path.exists() {
            Ok(Some(fs::read_to_string(path)?))
        } else {
            Ok(None)
        }
    }
    pub fn load_workspace_index(&self) -> Result<Option<String>> {
        match &self.workspace {
            None => Ok(None),
            Some(WorkspaceMemory::Lite { file, .. }) => Ok(Some(fs::read_to_string(file)?)),
            Some(WorkspaceMemory::Structured { dir, .. }) => {
                let index = dir.join(MEMORY_INDEX_FILE_NAME);
                if index.exists() {
                    Ok(Some(fs::read_to_string(index)?))
                } else {
                    Ok(None)
                }
            }
        }
    }
    pub fn list_files(&self) -> Result<Vec<MemoryFile>> {
        let mut out = Vec::new();
        if self.global_dir.exists() {
            collect_md_files(&self.global_dir, &mut out)?;
        }
        if let Some(WorkspaceMemory::Structured { dir, .. }) = &self.workspace {
            collect_md_files(dir, &mut out)?;
        }
        Ok(out)
    }
 }
 pub fn build_memory_section(
    store: &MemoryStore,
    with_tools: bool,
    cap: usize,
 ) -> Result<Option<String>> {
    let global_index = store.load_global_index()?;
    let workspace_index = store.load_workspace_index()?;
    if global_index.is_none() && workspace_index.is_none() {
        return Ok(None);
    }
    let mut buf = String::from("<memory>\n");
    let mut consumed = 0usize;
    if let Some(s) = &global_index {
        buf.push_str("<global_index>\n");
        buf.push_str(s);
        buf.push_str("\n</global_index>\n");
        consumed += s.chars().count();
    }
    if let Some(s) = &workspace_index {
        buf.push_str("<workspace_index>\n");
        buf.push_str(s);
        buf.push_str("\n</workspace_index>\n");
        consumed += s.chars().count();
    }
    if consumed > cap {
        warn!(
            "memory indexes ({} chars) exceed cap ({} chars); injecting fully - \
             consider raising memory_cap_* in config or shrinking MEMORY.md",
            consumed, cap
        );
    }
    if !with_tools {
        let mut budget = cap.saturating_sub(consumed);
        let mut files = store.list_files()?;
        files.sort_by(|a, b| a.frontmatter.name.cmp(&b.frontmatter.name));
        let mut omitted = 0usize;
        for f in files {
            let needed = f.body.chars().count() + 50;
            if needed > budget {
                omitted += 1;
                continue;
            }
            buf.push_str(&format!("<file name=\"{}\">\n", f.frontmatter.name));
            buf.push_str(&f.body);
            buf.push_str("\n</file>\n");
            budget = budget.saturating_sub(needed);
        }
        if omitted > 0 {
            buf.push_str(&format!(
                "<!-- {} memory file(s) omitted; enable function calling for full access -->\n",
                omitted
            ));
        }
    }
    buf.push_str("</memory>");
    Ok(Some(buf))
 }
 fn collect_md_files(dir: &Path, out: &mut Vec<MemoryFile>) -> Result<()> {
    for entry in fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) != Some("md") {
            continue;
        }
        if path.file_name().and_then(|n| n.to_str()) == Some(MEMORY_INDEX_FILE_NAME) {
            continue;
        }
        match MemoryFile::load(&path) {
            Ok(f) => out.push(f),
            Err(e) => warn!("skip malformed memory file {}: {}", path.display(), e),
        }
    }
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::{env, time};
    use time::SystemTime;
    fn temp_root(label: &str) -> PathBuf {
        let unique = SystemTime::now()
            .duration_since(time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let root = env::temp_dir().join(format!("coyote-memory-{label}-{unique}"));
        fs::create_dir_all(&root).unwrap();
        root
    }
    #[test]
    fn loads_global_and_workspace_indexes_from_test_dirs() {
        let root = temp_root("phase1");
        let workspace = root.join("workspace");
        let workspace_memory_dir = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&workspace_memory_dir).unwrap();
        fs::write(
            workspace_memory_dir.join(MEMORY_INDEX_FILE_NAME),
            "workspace-content",
        )
        .unwrap();
        let global = root.join("global");
        fs::create_dir_all(&global).unwrap();
        fs::write(global.join(MEMORY_INDEX_FILE_NAME), "global-content").unwrap();
        let store = MemoryStore {
            global_dir: global,
            workspace: discover_workspace_memory(&workspace),
        };
        assert_eq!(
            store.load_global_index().unwrap().as_deref(),
            Some("global-content")
        );
        assert_eq!(
            store.load_workspace_index().unwrap().as_deref(),
            Some("workspace-content")
        );
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn workspace_discovery_prefers_structured_over_lite() {
        let root = temp_root("prefer");
        let workspace = root.join("ws");
        let structured = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join(MEMORY_INDEX_FILE_NAME), "s").unwrap();
        fs::write(workspace.join(WORKSPACE_MEMORY_FILE_NAME), "l").unwrap();
        let found = discover_workspace_memory(&workspace);
        assert!(matches!(found, Some(WorkspaceMemory::Structured { .. })));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn build_memory_section_returns_none_when_no_memory_exists() {
        let root = temp_root("none");
        let workspace = root.join("ws");
        fs::create_dir_all(&workspace).unwrap();
        let store = MemoryStore {
            global_dir: root.join("global"),
            workspace: discover_workspace_memory(&workspace),
        };
        assert!(build_memory_section(&store, true, 6_000).unwrap().is_none());
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn build_memory_section_injects_only_indexes_with_tools_on() {
        let root = temp_root("indexes_only");
        let workspace = root.join("ws");
        let structured = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&structured).unwrap();
        fs::write(
            structured.join(MEMORY_INDEX_FILE_NAME),
            "workspace-index-content",
        )
        .unwrap();
        fs::write(
            structured.join("foo.md"),
            "---\nname: foo\n---\nfoo body that should not appear\n",
        )
        .unwrap();
        let store = MemoryStore {
            global_dir: root.join("global"),
            workspace: discover_workspace_memory(&workspace),
        };
        let section = build_memory_section(&store, true, 6_000)
            .unwrap()
            .expect("memory section should exist");
        assert!(section.contains("workspace-index-content"));
        assert!(!section.contains("foo body that should not appear"));
        assert!(section.starts_with("<memory>"));
        assert!(section.ends_with("</memory>"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn build_memory_section_injects_drill_bodies_alphabetically_without_tools() {
        let root = temp_root("drill_bodies");
        let workspace = root.join("ws");
        let structured = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join(MEMORY_INDEX_FILE_NAME), "idx").unwrap();
        fs::write(
            structured.join("zebra.md"),
            "---\nname: zebra\n---\nzebra body\n",
        )
        .unwrap();
        fs::write(
            structured.join("alpha.md"),
            "---\nname: alpha\n---\nalpha body\n",
        )
        .unwrap();
        let store = MemoryStore {
            global_dir: root.join("global"),
            workspace: discover_workspace_memory(&workspace),
        };
        let section = build_memory_section(&store, false, 6_000)
            .unwrap()
            .expect("memory section should exist");
        let alpha_pos = section.find("alpha body").expect("alpha body missing");
        let zebra_pos = section.find("zebra body").expect("zebra body missing");
        assert!(alpha_pos < zebra_pos, "drill bodies must be alphabetical");
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn build_memory_section_omits_drill_bodies_when_cap_exceeded() {
        let root = temp_root("cap");
        let workspace = root.join("ws");
        let structured = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join(MEMORY_INDEX_FILE_NAME), "idx").unwrap();
        let big_body = "x".repeat(200);
        fs::write(
            structured.join("big.md"),
            format!("---\nname: big\n---\n{}\n", big_body),
        )
        .unwrap();
        let store = MemoryStore {
            global_dir: root.join("global"),
            workspace: discover_workspace_memory(&workspace),
        };
        let section = build_memory_section(&store, false, 100)
            .unwrap()
            .expect("memory section should exist");
        assert!(!section.contains(&big_body));
        assert!(section.contains("memory file(s) omitted"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn parse_frontmatter_extracts_yaml() {
        let raw = "---\nname: foo\ndescription: a thing\ntype: user\n---\nBody text\n";
        let (fm, body) = parse_frontmatter(raw).unwrap();
        assert_eq!(fm.name, "foo");
        assert_eq!(fm.description.as_deref(), Some("a thing"));
        assert_eq!(fm.kind.as_deref(), Some("user"));
        assert_eq!(body, "Body text\n");
    }
    #[test]
    fn parse_frontmatter_handles_missing_block() {
        let raw = "# Just markdown, no frontmatter\nbody";
        let (fm, body) = parse_frontmatter(raw).unwrap();
        assert_eq!(fm.name, "");
        assert!(fm.kind.is_none());
        assert_eq!(body, raw);
    }
    #[test]
    fn parse_frontmatter_handles_unterminated_block() {
        let raw = "---\nname: oops\nno closing delimiter\n# rest of doc";
        let (fm, body) = parse_frontmatter(raw).unwrap();
        assert_eq!(fm.name, "");
        assert_eq!(body, raw);
    }
    #[test]
    fn memory_file_save_and_load_roundtrip() {
        let root = temp_root("roundtrip");
        let path = root.join("test.md");
        let file = MemoryFile {
            path: path.clone(),
            frontmatter: MemoryFrontmatter {
                name: "test".into(),
                description: Some("a test".into()),
                kind: Some("user".into()),
            },
            body: "Hello world\nmore text".into(),
        };
        file.save().unwrap();
        let loaded = MemoryFile::load(&path).unwrap();
        assert_eq!(loaded.frontmatter.name, "test");
        assert_eq!(loaded.frontmatter.description.as_deref(), Some("a test"));
        assert_eq!(loaded.frontmatter.kind.as_deref(), Some("user"));
        assert_eq!(loaded.body, "Hello world\nmore text");
        let raw = fs::read_to_string(&path).unwrap();
        assert!(raw.contains("type: user"), "kind must serialize as 'type:'");
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn discover_walks_up_from_nested_dir() {
        let root = temp_root("walk_up");
        let workspace = root.join("ws");
        let mem_dir = workspace
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(MEMORY_DIR_NAME);
        fs::create_dir_all(&mem_dir).unwrap();
        fs::write(mem_dir.join(MEMORY_INDEX_FILE_NAME), "idx").unwrap();
        let nested = workspace.join("src").join("deep").join("path");
        fs::create_dir_all(&nested).unwrap();
        let found = discover_workspace_memory(&nested);
        assert!(matches!(found, Some(WorkspaceMemory::Structured { .. })));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn find_git_root_returns_dir_containing_git_dir() {
        let root = temp_root("git_root");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        assert_eq!(find_git_root(&repo), Some(repo.clone()));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn find_git_root_walks_up_from_nested_dir() {
        let root = temp_root("git_root_walk");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        let nested = repo.join("a").join("b").join("c");
        fs::create_dir_all(&nested).unwrap();
        assert_eq!(find_git_root(&nested), Some(repo));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn find_git_root_treats_git_file_as_repo_marker() {
        let root = temp_root("git_root_worktree");
        let worktree = root.join("worktree");
        fs::create_dir_all(&worktree).unwrap();
        fs::write(
            worktree.join(GIT_DIR_NAME),
            "gitdir: /elsewhere/.git/worktrees/wt\n",
        )
        .unwrap();
        assert_eq!(find_git_root(&worktree), Some(worktree));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn find_git_root_returns_none_when_no_git() {
        let root = temp_root("git_root_missing");
        let bare = root.join("bare");
        fs::create_dir_all(&bare).unwrap();
        assert_eq!(find_git_root(&bare), None);
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_creates_structured_layout_and_index() {
        let root = temp_root("bootstrap_layout");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        let mem_dir = bootstrap_workspace_memory(&repo).unwrap();
        assert_eq!(mem_dir, paths::workspace_memory_dir_for(&repo));
        assert!(mem_dir.is_dir());
        let index = mem_dir.join(MEMORY_INDEX_FILE_NAME);
        assert!(index.exists());
        let body = fs::read_to_string(&index).unwrap();
        assert!(body.starts_with("# Workspace Memory Index"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_creates_gitignore_when_absent() {
        let root = temp_root("bootstrap_gi_new");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        bootstrap_workspace_memory(&repo).unwrap();
        let gi = repo.join(GITIGNORE_FILE_NAME);
        assert!(gi.exists());
        let body = fs::read_to_string(&gi).unwrap();
        assert!(body.contains(".coyote/memory/"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_appends_to_existing_gitignore_without_trailing_newline() {
        let root = temp_root("bootstrap_gi_append");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        fs::write(repo.join(GITIGNORE_FILE_NAME), "target/").unwrap();
        bootstrap_workspace_memory(&repo).unwrap();
        let body = fs::read_to_string(repo.join(GITIGNORE_FILE_NAME)).unwrap();
        assert!(body.contains("target/"));
        assert!(body.contains(".coyote/memory/"));
        assert!(body.ends_with('\n'));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_is_idempotent_on_gitignore_entry() {
        let root = temp_root("bootstrap_gi_idempotent");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        let original = "target/\n.coyote/memory/\n";
        fs::write(repo.join(GITIGNORE_FILE_NAME), original).unwrap();
        bootstrap_workspace_memory(&repo).unwrap();
        let body = fs::read_to_string(repo.join(GITIGNORE_FILE_NAME)).unwrap();
        assert_eq!(body, original, "gitignore must be untouched");
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_treats_entry_without_trailing_slash_as_present() {
        let root = temp_root("bootstrap_gi_no_slash");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        let original = ".coyote/memory\n";
        fs::write(repo.join(GITIGNORE_FILE_NAME), original).unwrap();
        bootstrap_workspace_memory(&repo).unwrap();
        let body = fs::read_to_string(repo.join(GITIGNORE_FILE_NAME)).unwrap();
        assert_eq!(body, original);
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn bootstrap_does_not_clobber_existing_index() {
        let root = temp_root("bootstrap_existing_index");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(GIT_DIR_NAME)).unwrap();
        let mem_dir = paths::workspace_memory_dir_for(&repo);
        fs::create_dir_all(&mem_dir).unwrap();
        let preserved = "# Custom Index\n\n- [[foo]]: keep me\n";
        fs::write(mem_dir.join(MEMORY_INDEX_FILE_NAME), preserved).unwrap();
        bootstrap_workspace_memory(&repo).unwrap();
        let body = fs::read_to_string(mem_dir.join(MEMORY_INDEX_FILE_NAME)).unwrap();
        assert_eq!(body, preserved);
        let _ = fs::remove_dir_all(&root);
    }
 }
@@ -5,8 +5,9 @@ mod input;
 mod install_remote;
 mod macros;
 mod mcp_factory;
 pub(crate) mod memory;
 pub(crate) mod paths;
-mod prompts;
+pub(crate) mod prompts;
 mod rag_cache;
 mod request_context;
 mod role;
@@ -28,7 +29,7 @@ pub use self::app_state::AppState;
 pub use self::input::Input;
 pub use self::install_remote::{install_remote, install_remote_from_repl_args};
 #[allow(unused_imports)]
-pub use self::request_context::{RenderMode, RequestContext};
+pub use self::request_context::{RenderMode, RequestContext, should_inject_skill_instructions};
 pub use self::role::{
    CODE_ROLE, CREATE_TITLE_ROLE, EXPLAIN_SHELL_ROLE, Role, RoleLike, SHELL_ROLE,
 };
@@ -50,9 +51,12 @@ use crate::utils::*;
 pub use macros::macro_execute;
 use crate::config::macros::Macro;
-use crate::vault::{GlobalVault, Vault, create_vault_password_file, interpolate_secrets};
+use crate::vault::{
    GlobalVault, Vault, create_vault_password_file, interpolate_secrets, prompt_provider_choice,
 };
 use anyhow::{Context, Result, anyhow, bail};
 use fancy_regex::Regex;
 use gman::providers::SupportedProvider;
 use indexmap::IndexMap;
 use indoc::formatdoc;
 use inquire::{Confirm, Select};
@@ -76,6 +80,45 @@ pub const TEMP_SESSION_NAME: &str = "temp";
 static PASSWORD_FILE_SECRET_RE: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r#"vault_password_file:.*['|"]?\{\{(.+)}}['|"]?"#).unwrap());
 fn validate_no_template_in_secrets_provider(content: &str) -> Result<()> {
    let mut in_block = false;
    for (line_num, line) in content.lines().enumerate() {
        if line.starts_with("secrets_provider:") {
            if line.contains("{{") {
                bail!(
                    "secret injection cannot be done on the secrets_provider property (line {}): the secrets_provider config is loaded before the vault is initialized",
                    line_num + 1
                );
            }
            in_block = true;
            continue;
        }
        if in_block {
            let trimmed = line.trim_start();
            if trimmed.is_empty() || trimmed.starts_with('#') {
                continue;
            }
            if !line.starts_with(char::is_whitespace) {
                in_block = false;
                continue;
            }
            if line.contains("{{") {
                bail!(
                    "secret injection cannot be done within the secrets_provider block (line {}): the secrets_provider config is loaded before the vault is initialized",
                    line_num + 1
                );
            }
        }
    }
    Ok(())
 }
 /// Monokai Extended
 const DARK_THEME: &[u8] = include_bytes!("../../assets/monokai-extended.theme.bin");
 const LIGHT_THEME: &[u8] = include_bytes!("../../assets/monokai-extended-light.theme.bin");
@@ -96,6 +139,16 @@ const GLOBAL_TOOLS_DIR_NAME: &str = "tools";
 const GLOBAL_TOOLS_UTILS_DIR_NAME: &str = "utils";
 const BASH_PROMPT_UTILS_FILE_NAME: &str = "prompt-utils.sh";
 const MCP_FILE_NAME: &str = "mcp.json";
 const MEMORY_DIR_NAME: &str = "memory";
 const MEMORY_INDEX_FILE_NAME: &str = "MEMORY.md";
 const WORKSPACE_MEMORY_FILE_NAME: &str = "COYOTE.md";
 const WORKSPACE_MEMORY_DIR_NAME: &str = ".coyote";
 const SBX_KIT_DIR_NAME: &str = "sbx-kit";
 const SBX_KIT_HASH_FILE: &str = "kit.sha256";
 const SBX_MIXIN_FILE_NAME: &str = "sbx-mixin.yaml";
 const SBX_VAULT_MIXINS_DIR_NAME: &str = "sbx-vault-mixins";
 const GIT_DIR_NAME: &str = ".git";
 const GITIGNORE_FILE_NAME: &str = ".gitignore";
 const DEFAULT_VISIBLE_TOOLS: [&str; 18] = [
    "execute_command.sh",
    "execute_py_code.py",
@@ -149,23 +202,31 @@ pub struct Config {
    pub wrap_code: bool,
    pub(super) vault_password_file: Option<PathBuf>,
    #[serde(default)]
    pub(super) secrets_provider: Option<SupportedProvider>,
    pub function_calling_support: bool,
    pub mapping_tools: IndexMap<String, String>,
-    pub enabled_tools: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
    pub enabled_tools: Option<Vec<String>>,
    pub visible_tools: Option<Vec<String>>,
    pub skills_enabled: bool,
-    pub enabled_skills: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
    pub enabled_skills: Option<Vec<String>>,
    pub visible_skills: Option<Vec<String>>,
    pub mcp_server_support: bool,
    pub mapping_mcp_servers: IndexMap<String, String>,
-    pub enabled_mcp_servers: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
    pub enabled_mcp_servers: Option<Vec<String>>,
    pub auto_continue: bool,
    pub max_auto_continues: usize,
    pub inject_todo_instructions: bool,
    pub continuation_prompt: Option<String>,
    pub inject_skill_instructions: bool,
    pub skill_instructions: Option<String>,
    pub repl_prelude: Option<String>,
    pub cmd_prelude: Option<String>,
@@ -176,6 +237,10 @@ pub struct Config {
    pub summarization_prompt: Option<String>,
    pub summary_context_prompt: Option<String>,
    pub memory: Option<bool>,
    pub memory_cap_with_tools: Option<usize>,
    pub memory_cap_without_tools: Option<usize>,
    pub rag_embedding_model: Option<String>,
    pub rag_reranker_model: Option<String>,
    pub rag_top_k: usize,
@@ -213,6 +278,7 @@ impl Default for Config {
            wrap: None,
            wrap_code: false,
            vault_password_file: None,
            secrets_provider: None,
            function_calling_support: true,
            mapping_tools: Default::default(),
@@ -231,6 +297,8 @@ impl Default for Config {
            max_auto_continues: 10,
            inject_todo_instructions: true,
            continuation_prompt: None,
            inject_skill_instructions: true,
            skill_instructions: None,
            repl_prelude: None,
            cmd_prelude: None,
@@ -241,6 +309,10 @@ impl Default for Config {
            summarization_prompt: None,
            summary_context_prompt: None,
            memory: None,
            memory_cap_with_tools: None,
            memory_cap_without_tools: None,
            rag_embedding_model: None,
            rag_reranker_model: None,
            rag_top_k: 5,
@@ -297,6 +369,12 @@ impl AssetCategory {
    }
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
 pub enum MemoryScope {
    Global,
    Workspace,
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
 pub enum InstallFilter {
    Agents,
@@ -438,10 +516,11 @@ impl Config {
        let bootstrap_app = AppConfig {
            vault_password_file: config.vault_password_file.clone(),
            secrets_provider: config.secrets_provider.clone(),
            ..AppConfig::default()
        };
-        let vault = Vault::init(&bootstrap_app);
+        let vault = Vault::init(&bootstrap_app)?;
-        let (parsed_config, missing_secrets) = interpolate_secrets(&content, &vault);
+        let (parsed_config, missing_secrets) = interpolate_secrets(&content, &vault)?;
        if !missing_secrets.is_empty() && !info_flag {
            debug!(
                "Global config references secrets that are missing from the vault: {missing_secrets:?}"
@@ -480,6 +559,7 @@ impl Config {
        if PASSWORD_FILE_SECRET_RE.is_match(content)? {
            bail!("secret injection cannot be done on the vault_password_file property");
        }
        validate_no_template_in_secrets_provider(content)?;
        let config: Self = serde_yaml::from_str(content)
            .map_err(|err| {
@@ -591,6 +671,9 @@ bitflags::bitflags! {
        const SESSION = 1 << 2;
        const RAG = 1 << 3;
        const AGENT = 1 << 4;
        const FUNCTION_CALLING = 1 << 5;
        const AUTO_CONTINUE = 1 << 6;
        const SKILLS_ENABLED = 1 << 7;
    }
 }
@@ -632,15 +715,33 @@ pub async fn create_config_file(config_path: &Path) -> Result<()> {
        process::exit(0);
    }
-    let mut vault = Vault::init_bare();
+    let provider_choice = prompt_provider_choice()?;
    let mut vault = match &provider_choice {
        None => Vault::default_local(),
        Some(provider) => Vault {
            provider: provider.clone(),
        },
    };
    create_vault_password_file(&mut vault)?;
    if provider_choice.is_some() {
        vault.validate_round_trip()?;
    }
    let client = Select::new("API Provider (required):", list_client_types()).prompt()?;
    let mut config = json!({});
    let (model, clients_config) = create_client_config(client, &vault).await?;
    config["model"] = model.into();
-    config["vault_password_file"] = vault.password_file()?.display().to_string().into();
+    match &provider_choice {
        None => {
            config["vault_password_file"] =
                vault.local_password_file()?.display().to_string().into();
        }
        Some(provider) => {
            config["secrets_provider"] = serde_json::to_value(provider)
                .with_context(|| "failed to serialize secrets_provider config")?;
        }
    }
    config["stream"] = json!(true);
    config["save"] = json!(true);
    config["keybindings"] = json!("vi");
@@ -718,6 +819,72 @@ where
    Ok(value)
 }
 pub(super) fn csv_to_vec(raw: &str) -> Vec<String> {
    raw.split(',')
        .map(|t| t.trim().to_string())
        .filter(|t| !t.is_empty())
        .collect()
 }
 pub(super) fn deserialize_csv_or_vec<'de, D>(
    deserializer: D,
 ) -> std::result::Result<Option<Vec<String>>, D::Error>
 where
    D: serde::Deserializer<'de>,
 {
    use serde::de::{self, SeqAccess, Visitor};
    use std::fmt;
    struct CsvOrVec;
    impl<'de> Visitor<'de> for CsvOrVec {
        type Value = Option<Vec<String>>;
        fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
            formatter.write_str("a comma-separated string, a list of strings, or null")
        }
        fn visit_str<E: de::Error>(self, value: &str) -> std::result::Result<Self::Value, E> {
            Ok(Some(csv_to_vec(value)))
        }
        fn visit_string<E: de::Error>(self, value: String) -> std::result::Result<Self::Value, E> {
            Ok(Some(csv_to_vec(&value)))
        }
        fn visit_none<E: de::Error>(self) -> std::result::Result<Self::Value, E> {
            Ok(None)
        }
        fn visit_some<D2: serde::Deserializer<'de>>(
            self,
            deserializer: D2,
        ) -> std::result::Result<Self::Value, D2::Error> {
            deserializer.deserialize_any(self)
        }
        fn visit_unit<E: de::Error>(self) -> std::result::Result<Self::Value, E> {
            Ok(None)
        }
        fn visit_seq<A: SeqAccess<'de>>(
            self,
            mut seq: A,
        ) -> std::result::Result<Self::Value, A::Error> {
            let mut vec = Vec::new();
            while let Some(item) = seq.next_element::<String>()? {
                let trimmed = item.trim().to_string();
                if !trimmed.is_empty() {
                    vec.push(trimmed);
                }
            }
            Ok(Some(vec))
        }
    }
    deserializer.deserialize_option(CsvOrVec)
 }
 fn read_env_bool(key: &str) -> Option<Option<bool>> {
    let value = env::var(key).ok()?;
    Some(parse_bool(&value))
@@ -753,6 +920,62 @@ where
 mod tests {
    use super::*;
    #[test]
    fn validate_secrets_provider_rejects_template_in_field() {
        let yaml = "\
 secrets_provider:
  type: aws_secrets_manager
  aws_profile: '{{AWS_PROFILE}}'
  aws_region: us-east-1
 ";
        assert!(validate_no_template_in_secrets_provider(yaml).is_err());
    }
    #[test]
    fn validate_secrets_provider_rejects_template_in_local_password_file() {
        let yaml = "\
 secrets_provider:
  type: local
  password_file: '{{COYOTE_PASSWORD}}'
 ";
        assert!(validate_no_template_in_secrets_provider(yaml).is_err());
    }
    #[test]
    fn validate_secrets_provider_accepts_clean_yaml() {
        let yaml = "\
 secrets_provider:
  type: aws_secrets_manager
  aws_profile: default
  aws_region: us-east-1
 ";
        assert!(validate_no_template_in_secrets_provider(yaml).is_ok());
    }
    #[test]
    fn validate_secrets_provider_allows_templates_outside_block() {
        let yaml = "\
 secrets_provider:
  type: local
  password_file: ~/.coyote_password
 clients:
  - type: openai
    api_key: '{{OPENAI_KEY}}'
 ";
        assert!(validate_no_template_in_secrets_provider(yaml).is_ok());
    }
    #[test]
    fn validate_secrets_provider_handles_missing_block() {
        let yaml = "\
 model: openai:gpt-4
 clients:
  - type: openai
    api_key: '{{OPENAI_KEY}}'
 ";
        assert!(validate_no_template_in_secrets_provider(yaml).is_ok());
    }
    #[test]
    fn config_defaults_match_expected() {
        let cfg = Config::default();
@@ -2,8 +2,10 @@ use super::role::Role;
 use super::{
    AGENT_GRAPH_FILE_NAME, AGENTS_DIR_NAME, BASH_PROMPT_UTILS_FILE_NAME, CONFIG_FILE_NAME,
    ENV_FILE_NAME, FUNCTIONS_BIN_DIR_NAME, FUNCTIONS_DIR_NAME, GLOBAL_TOOLS_DIR_NAME,
-    GLOBAL_TOOLS_UTILS_DIR_NAME, MACROS_DIR_NAME, MCP_FILE_NAME, ModelsOverride, RAGS_DIR_NAME,
+    GLOBAL_TOOLS_UTILS_DIR_NAME, MACROS_DIR_NAME, MCP_FILE_NAME, MEMORY_DIR_NAME,
-    ROLES_DIR_NAME, SKILLS_DIR_NAME,
+    MEMORY_INDEX_FILE_NAME, ModelsOverride, RAGS_DIR_NAME, ROLES_DIR_NAME, SBX_KIT_DIR_NAME,
    SBX_KIT_HASH_FILE, SBX_MIXIN_FILE_NAME, SBX_VAULT_MIXINS_DIR_NAME, SKILLS_DIR_NAME,
    WORKSPACE_MEMORY_DIR_NAME,
 };
 use crate::client::ProviderModels;
 use crate::utils::{get_env_name, list_file_names, normalize_env_name};
@@ -13,7 +15,7 @@ use log::LevelFilter;
 use std::collections::HashSet;
 use std::env;
 use std::fs::{read_dir, read_to_string};
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 pub fn config_dir() -> PathBuf {
    if let Ok(v) = env::var(get_env_name("config_dir")) {
@@ -35,6 +37,89 @@ pub fn cache_path() -> PathBuf {
    base_dir.join(env!("CARGO_CRATE_NAME"))
 }
 pub fn sandbox_kit_override() -> Option<PathBuf> {
    env::var_os(get_env_name("sandbox_kit")).map(PathBuf::from)
 }
 pub fn translate_sandboxed_home_path(path: &Path) -> Option<PathBuf> {
    env::var_os("IS_SANDBOX")?;
    let s = path.to_str()?;
    if let Some(translated) = translate_unix_home_style(s, "/home/") {
        return Some(translated);
    }
    if let Some(translated) = translate_unix_home_style(s, "/Users/") {
        return Some(translated);
    }
    translate_windows_users_path(s)
 }
 fn translate_unix_home_style(s: &str, prefix: &str) -> Option<PathBuf> {
    let rest = s.strip_prefix(prefix)?;
    let (user, tail) = match rest.split_once('/') {
        Some((u, t)) => (u, t),
        None => (rest, ""),
    };
    if user.is_empty() || user == "agent" {
        return None;
    }
    Some(if tail.is_empty() {
        PathBuf::from("/home/agent")
    } else {
        PathBuf::from(format!("/home/agent/{tail}"))
    })
 }
 fn translate_windows_users_path(s: &str) -> Option<PathBuf> {
    let bytes = s.as_bytes();
    if bytes.len() < 4 || !bytes[0].is_ascii_alphabetic() || bytes[1] != b':' || bytes[2] != b'\\' {
        return None;
    }
    let after_drive = &s[3..];
    let rest = after_drive.strip_prefix("Users\\")?;
    let (user, tail) = match rest.split_once('\\') {
        Some((u, t)) => (u, t.replace('\\', "/")),
        None => (rest, String::new()),
    };
    if user.is_empty() || user == "agent" {
        return None;
    }
    Some(if tail.is_empty() {
        PathBuf::from("/home/agent")
    } else {
        PathBuf::from(format!("/home/agent/{tail}"))
    })
 }
 pub fn sbx_mixin_file() -> PathBuf {
    config_dir().join(SBX_MIXIN_FILE_NAME)
 }
 pub fn global_tools_sbx_mixin_file() -> PathBuf {
    functions_dir().join(SBX_MIXIN_FILE_NAME)
 }
 pub fn find_workspace_sbx_mixin(start: &Path) -> Option<PathBuf> {
    for dir in start.ancestors() {
        let candidate = dir
            .join(WORKSPACE_MEMORY_DIR_NAME)
            .join(SBX_MIXIN_FILE_NAME);
        if candidate.exists() {
            return Some(candidate);
        }
    }
    None
 }
 pub fn oauth_tokens_path() -> PathBuf {
    cache_path().join("oauth")
 }
@@ -47,6 +132,22 @@ pub fn log_path() -> PathBuf {
    cache_path().join(format!("{}.log", env!("CARGO_CRATE_NAME")))
 }
 pub fn sbx_kit_dir() -> PathBuf {
    cache_path().join(SBX_KIT_DIR_NAME)
 }
 pub fn sbx_kit_hash_file() -> PathBuf {
    sbx_kit_dir().join(SBX_KIT_HASH_FILE)
 }
 pub fn sbx_vault_mixins_dir() -> PathBuf {
    cache_path().join(SBX_VAULT_MIXINS_DIR_NAME)
 }
 pub fn sbx_vault_mixins_hash_file() -> PathBuf {
    sbx_vault_mixins_dir().join(SBX_KIT_HASH_FILE)
 }
 pub fn config_file() -> PathBuf {
    match env::var(get_env_name("config_file")) {
        Ok(value) => PathBuf::from(value),
@@ -80,6 +181,19 @@ pub fn skill_file(name: &str) -> PathBuf {
    skill_dir(name).join("SKILL.md")
 }
 pub fn validate_skill_name(name: &str) -> Result<()> {
    if name.is_empty() {
        bail!("Skill name cannot be empty");
    }
    if !name
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
    {
        bail!("Invalid skill name '{name}': only letters, digits, '-', and '_' are allowed");
    }
    Ok(())
 }
 pub fn macros_dir() -> PathBuf {
    match env::var(get_env_name("macros_dir")) {
        Ok(value) => PathBuf::from(value),
@@ -182,6 +296,20 @@ pub fn models_override_file() -> PathBuf {
    local_path("models-override.yaml")
 }
 pub fn global_memory_dir() -> PathBuf {
    config_dir().join(MEMORY_DIR_NAME)
 }
 pub fn global_memory_index_path() -> PathBuf {
    global_memory_dir().join(MEMORY_INDEX_FILE_NAME)
 }
 pub fn workspace_memory_dir_for(workspace_root: &Path) -> PathBuf {
    workspace_root
        .join(WORKSPACE_MEMORY_DIR_NAME)
        .join(MEMORY_DIR_NAME)
 }
 pub fn log_config() -> Result<(LevelFilter, Option<PathBuf>)> {
    let log_level = env::var(get_env_name("log_level"))
        .ok()
@@ -257,6 +385,7 @@ pub fn list_skills() -> Vec<String> {
                && file_type.is_dir()
                && let Some(name) = entry.file_name().to_str()
                && entry.path().join("SKILL.md").is_file()
                && validate_skill_name(name).is_ok()
            {
                names.push(name.to_string());
            }
@@ -286,3 +415,275 @@ pub fn local_models_override() -> Result<Vec<ProviderModels>> {
    }
    Ok(models_override.list)
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::{fs, time};
    #[test]
    fn validate_skill_name_accepts_alphanumerics_and_dashes() {
        assert!(validate_skill_name("git-master").is_ok());
        assert!(validate_skill_name("code_review").is_ok());
        assert!(validate_skill_name("Skill1").is_ok());
    }
    #[test]
    fn validate_skill_name_rejects_empty() {
        let err = validate_skill_name("").unwrap_err();
        assert!(err.to_string().contains("cannot be empty"));
    }
    #[test]
    fn validate_skill_name_rejects_path_traversal() {
        for bad in ["../escape", "..", "foo/bar", "foo\\bar", "./hidden"] {
            let err = validate_skill_name(bad).unwrap_err();
            assert!(
                err.to_string().contains("Invalid skill name"),
                "expected rejection for {bad:?}, got: {err}"
            );
        }
    }
    #[test]
    fn validate_skill_name_rejects_other_special_chars() {
        for bad in ["with space", "null\0byte", "weird?char", "dot.name"] {
            assert!(
                validate_skill_name(bad).is_err(),
                "expected rejection for {bad:?}"
            );
        }
    }
    #[test]
    fn has_skill_returns_false_for_missing_paths() {
        for absent in ["definitely-not-installed-skill-xyz", "another-missing"] {
            assert!(
                !has_skill(absent),
                "has_skill({absent:?}) should be false for a missing skill"
            );
        }
    }
    mod sandbox_home_translation {
        use super::*;
        use serial_test::serial;
        fn with_sandbox<F: FnOnce()>(f: F) {
            let prev = env::var_os("IS_SANDBOX");
            unsafe {
                env::set_var("IS_SANDBOX", "1");
            }
            f();
            unsafe {
                match prev {
                    Some(v) => env::set_var("IS_SANDBOX", v),
                    None => env::remove_var("IS_SANDBOX"),
                }
            }
        }
        fn without_sandbox<F: FnOnce()>(f: F) {
            let prev = env::var_os("IS_SANDBOX");
            unsafe {
                env::remove_var("IS_SANDBOX");
            }
            f();
            unsafe {
                if let Some(v) = prev {
                    env::set_var("IS_SANDBOX", v);
                }
            }
        }
        #[test]
        #[serial]
        fn returns_none_when_not_in_sandbox() {
            without_sandbox(|| {
                let p = Path::new("/home/atusa/.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn translates_host_home_to_agent_home() {
            with_sandbox(|| {
                let p = Path::new("/home/atusa/.coyote_password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.coyote_password"))
                );
            });
        }
        #[test]
        #[serial]
        fn translates_nested_host_home_path() {
            with_sandbox(|| {
                let p = Path::new("/home/atusa/.config/coyote/.password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.config/coyote/.password"))
                );
            });
        }
        #[test]
        #[serial]
        fn returns_none_when_path_already_targets_agent_home() {
            with_sandbox(|| {
                let p = Path::new("/home/agent/.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn returns_none_when_path_is_outside_home() {
            with_sandbox(|| {
                let p = Path::new("/etc/coyote/.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn returns_none_for_relative_path() {
            with_sandbox(|| {
                let p = Path::new(".coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn returns_none_for_first_segment_not_home() {
            with_sandbox(|| {
                let p = Path::new("/opt/atusa/.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn translates_macos_users_path() {
            with_sandbox(|| {
                let p = Path::new("/Users/atusa/.coyote_password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.coyote_password"))
                );
            });
        }
        #[test]
        #[serial]
        fn translates_macos_nested_path() {
            with_sandbox(|| {
                let p = Path::new("/Users/atusa/.config/coyote/.password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.config/coyote/.password"))
                );
            });
        }
        #[test]
        #[serial]
        fn returns_none_when_macos_path_already_targets_agent() {
            with_sandbox(|| {
                let p = Path::new("/Users/agent/.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
        #[test]
        #[serial]
        fn translates_windows_drive_letter_path() {
            with_sandbox(|| {
                let p = Path::new("C:\\Users\\atusa\\.coyote_password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.coyote_password"))
                );
            });
        }
        #[test]
        #[serial]
        fn translates_windows_nested_path() {
            with_sandbox(|| {
                let p = Path::new("D:\\Users\\atusa\\.config\\coyote\\.password");
                assert_eq!(
                    translate_sandboxed_home_path(p),
                    Some(PathBuf::from("/home/agent/.config/coyote/.password"))
                );
            });
        }
        #[test]
        #[serial]
        fn returns_none_when_windows_path_already_targets_agent() {
            with_sandbox(|| {
                let p = Path::new("C:\\Users\\agent\\.coyote_password");
                assert_eq!(translate_sandboxed_home_path(p), None);
            });
        }
    }
    #[test]
    fn sandbox_kit_override_reflects_env_var_state() {
        let env_name = get_env_name("sandbox_kit");
        let prev = env::var_os(&env_name);
        unsafe {
            env::remove_var(&env_name);
        }
        assert_eq!(sandbox_kit_override(), None);
        let probe = PathBuf::from("/tmp/coyote-sandbox-kit-probe");
        unsafe {
            env::set_var(&env_name, &probe);
        }
        assert_eq!(sandbox_kit_override(), Some(probe));
        unsafe {
            match prev {
                Some(v) => env::set_var(&env_name, v),
                None => env::remove_var(&env_name),
            }
        }
    }
    #[test]
    fn list_skills_skips_invalid_directory_names() {
        let unique = time::SystemTime::now()
            .duration_since(time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let root = env::temp_dir().join(format!("coyote-list-skills-test-{unique}"));
        fs::create_dir_all(&root).unwrap();
        let prev = env::var_os(get_env_name("skills_dir"));
        unsafe {
            env::set_var(get_env_name("skills_dir"), &root);
        }
        for name in ["valid-skill", "with space", ".hidden", "dot.name"] {
            let dir = root.join(name);
            fs::create_dir_all(&dir).unwrap();
            fs::write(dir.join("SKILL.md"), "body").unwrap();
        }
        let listed = list_skills();
        assert_eq!(listed, vec!["valid-skill".to_string()]);
        unsafe {
            match prev {
                Some(v) => env::set_var(get_env_name("skills_dir"), v),
                None => env::remove_var(get_env_name("skills_dir")),
            }
        }
        let _ = fs::remove_dir_all(&root);
    }
 }
@@ -1,5 +1,50 @@
 use indoc::indoc;
 pub(crate) const DEFAULT_SKILL_INSTRUCTIONS: &str = indoc! {"
    ## Skills
    Specialized skills may be available in this context. Call `skill__list` early in a task to
    discover any that match the work, then `skill__load` the relevant ones. Their instructions and
    granted tools will become active for subsequent turns. Call `skill__unload` when their work is
    complete to keep the context lean."
 };
 pub(crate) const DEFAULT_MEMORY_INSTRUCTIONS: &str = indoc! {"
    ## Memory
    A persistent memory file system survives across sessions. The MEMORY.md content shown above is
    your always-on context (universal facts, hard rules, binding feedback). Drill files hold deeper,
    on-demand context that you fetch with `memory__read`.
    Tools:
        - `memory__read(name)`: Read a specific drill file's full content.
        - `memory__write(name, content, scope)`: Create or replace a drill file (scope: 'global' | 'workspace').
          The MEMORY.md index is appended automatically; do not also update the index by hand.
        - `memory__edit_index(scope, content)`: Replace the entire MEMORY.md at the given scope.
          Use this to add always-on facts, reorganize, prune stale entries, or fix descriptions.
        - `memory__list()`: See all known drill files and their metadata.
        - `memory__lint()`: Health-check memory for orphans, broken links, oversized files.
    RULES:
        - Every interaction has two outputs: your answer AND any memory updates the conversation warrants.
          Don't let learnings evaporate into chat history.
        - All MEMORY.md edits MUST go through `memory__edit_index`. NEVER use `fs_write`, `fs_patch`,
          or any other generic file tool on MEMORY.md — Coyote manages its location and a stray
          MEMORY.md outside the managed path is invisible to memory.
        - All drill files MUST go through `memory__write`. The index updates itself.
        - Use [[wikilink]] notation in memory files to reference other memories by their `name:` slug.
        - NEVER write secrets, credentials, or API keys to memory — memory is plaintext on disk.
          Use coyote's Vault for secrets.
        - Keep individual drill files focused (under ~2K chars). Split large topics across linked files."
 };
 pub(crate) const DEFAULT_MEMORY_INSTRUCTIONS_READONLY: &str = indoc! {"
    ## Memory (read-only)
    The memory content shown above persists across sessions. In this session it is READ-ONLY — the user
    maintains memory files manually outside the conversation.
    Reference the memory content as authoritative context about the user and their workspace.
    Do not propose writing to memory or call any `memory__*` tools — they are unavailable."
 };
 pub(in crate::config) const DEFAULT_TODO_INSTRUCTIONS: &str = indoc! {"
    ## Task Tracking
    You have built-in task tracking tools. Use them to track your progress:
@@ -54,6 +99,36 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
    agent__collect --id agent_explore_e5f6g7h8
    ```
    ### CRITICAL: Never end your turn with pending agents
    Spawned agents do NOT report back on their own. They run in the background until you
    actively reclaim them with `agent__collect` (to get their output) or `agent__cancel`
    (to discard them). If you spawn agents and then emit a final message without reclaiming
    them, the system will detect the unreclaimed agents and reject the turn-end, injecting
    a reminder forcing you to handle them. After several such reminders, the system will
    auto-cancel them and warn you that work was lost.
    The correct flow when you have nothing else to do:
    ```
    # WRONG - do NOT do this:
    agent__spawn --agent explore --prompt \"...\"
    agent__spawn --agent explore --prompt \"...\"
    # ... emit text like \"I will synthesize once they report back.\" and stop
    # ^ The agents will be abandoned. Their output will be lost.
    # RIGHT - always do this:
    agent__spawn --agent explore --prompt \"...\"
    agent__spawn --agent explore --prompt \"...\"
    agent__collect --id <first_id>   # blocks until done
    agent__collect --id <second_id>  # blocks until done
    # ... NOW you can synthesize and end your turn
    ```
    `agent__collect` is a **blocking wait**: it pauses your execution until the agent
    completes, then returns the output as a tool result. Use it freely — it is the
    correct primitive for \"I'm done with my own work and just need the agents' results\".
    ### Parallel Spawning (DEFAULT for multi-agent work)
    When a task needs multiple agents, **spawn them all at once**, then collect:
@@ -28,13 +28,13 @@ pub trait RoleLike {
    fn model(&self) -> &Model;
    fn temperature(&self) -> Option<f64>;
    fn top_p(&self) -> Option<f64>;
-    fn enabled_tools(&self) -> Option<String>;
+    fn enabled_tools(&self) -> Option<Vec<String>>;
-    fn enabled_mcp_servers(&self) -> Option<String>;
+    fn enabled_mcp_servers(&self) -> Option<Vec<String>>;
    fn set_model(&mut self, model: Model);
    fn set_temperature(&mut self, value: Option<f64>);
    fn set_top_p(&mut self, value: Option<f64>);
-    fn set_enabled_tools(&mut self, value: Option<String>);
+    fn set_enabled_tools(&mut self, value: Option<Vec<String>>);
-    fn set_enabled_mcp_servers(&mut self, value: Option<String>);
+    fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>);
 }
 #[derive(Debug, Clone, Default, Deserialize, Serialize)]
@@ -51,14 +51,26 @@ pub struct Role {
    temperature: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    top_p: Option<f64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(
-    enabled_tools: Option<String>,
+        default,
-    #[serde(skip_serializing_if = "Option::is_none")]
+        skip_serializing_if = "Option::is_none",
-    enabled_mcp_servers: Option<String>,
+        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_tools: Option<Vec<String>>,
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_mcp_servers: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    skills_enabled: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(
-    enabled_skills: Option<String>,
+        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_skills: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    auto_continue: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
@@ -67,6 +79,12 @@ pub struct Role {
    inject_todo_instructions: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    continuation_prompt: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    inject_skill_instructions: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    skill_instructions: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    memory: Option<bool>,
    #[serde(skip)]
    model: Model,
@@ -98,14 +116,12 @@ impl Role {
                    "model" => role.model_id = value.as_str().map(|v| v.to_string()),
                    "temperature" => role.temperature = value.as_f64(),
                    "top_p" => role.top_p = value.as_f64(),
-                    "enabled_tools" => role.enabled_tools = value.as_str().map(|v| v.to_string()),
+                    "enabled_tools" => role.enabled_tools = parse_string_or_array(value),
                    "enabled_mcp_servers" => {
-                        role.enabled_mcp_servers = value.as_str().map(|v| v.to_string())
+                        role.enabled_mcp_servers = parse_string_or_array(value)
                    }
                    "skills_enabled" => role.skills_enabled = value.as_bool(),
-                    "enabled_skills" => {
+                    "enabled_skills" => role.enabled_skills = parse_string_or_array(value),
                        role.enabled_skills = value.as_str().map(|v| v.to_string())
                    }
                    "auto_continue" => role.auto_continue = value.as_bool(),
                    "max_auto_continues" => {
                        role.max_auto_continues = value.as_u64().map(|v| v as usize)
@@ -114,6 +130,11 @@ impl Role {
                    "continuation_prompt" => {
                        role.continuation_prompt = value.as_str().map(|v| v.to_string())
                    }
                    "inject_skill_instructions" => role.inject_skill_instructions = value.as_bool(),
                    "skill_instructions" => {
                        role.skill_instructions = value.as_str().map(|v| v.to_string())
                    }
                    "memory" => role.memory = value.as_bool(),
                    _ => (),
                }
            }
@@ -149,17 +170,21 @@ impl Role {
        if let Some(top_p) = self.top_p() {
            metadata.push(format!("top_p: {top_p}"));
        }
-        if let Some(enabled_tools) = self.enabled_tools() {
+        if let Some(enabled_tools) = &self.enabled_tools {
-            metadata.push(format!("enabled_tools: {enabled_tools}"));
+            let inline = serde_json::to_string(enabled_tools).unwrap_or_else(|_| "[]".to_string());
            metadata.push(format!("enabled_tools: {inline}"));
        }
-        if let Some(enabled_mcp_servers) = self.enabled_mcp_servers() {
+        if let Some(enabled_mcp_servers) = &self.enabled_mcp_servers {
-            metadata.push(format!("enabled_mcp_servers: {enabled_mcp_servers}"));
+            let inline =
                serde_json::to_string(enabled_mcp_servers).unwrap_or_else(|_| "[]".to_string());
            metadata.push(format!("enabled_mcp_servers: {inline}"));
        }
        if let Some(skills_enabled) = self.skills_enabled {
            metadata.push(format!("skills_enabled: {skills_enabled}"));
        }
        if let Some(enabled_skills) = &self.enabled_skills {
-            metadata.push(format!("enabled_skills: {enabled_skills}"));
+            let inline = serde_json::to_string(enabled_skills).unwrap_or_else(|_| "[]".to_string());
            metadata.push(format!("enabled_skills: {inline}"));
        }
        if let Some(auto_continue) = self.auto_continue {
            metadata.push(format!("auto_continue: {auto_continue}"));
@@ -175,6 +200,17 @@ impl Role {
        if let Some(continuation_prompt) = &self.continuation_prompt {
            metadata.push(format!("continuation_prompt: {continuation_prompt}"));
        }
        if let Some(inject_skill_instructions) = self.inject_skill_instructions {
            metadata.push(format!(
                "inject_skill_instructions: {inject_skill_instructions}"
            ));
        }
        if let Some(skill_instructions) = &self.skill_instructions {
            metadata.push(format!("skill_instructions: {skill_instructions}"));
        }
        if let Some(memory) = self.memory {
            metadata.push(format!("memory: {memory}"));
        }
        if metadata.is_empty() {
            format!("{}\n", self.prompt)
        } else if self.prompt.is_empty() {
@@ -227,8 +263,8 @@ impl Role {
        model: &Model,
        temperature: Option<f64>,
        top_p: Option<f64>,
-        enabled_tools: Option<String>,
+        enabled_tools: Option<Vec<String>>,
-        enabled_mcp_servers: Option<String>,
+        enabled_mcp_servers: Option<Vec<String>>,
    ) {
        self.set_model(model.clone());
        if temperature.is_some() {
@@ -285,11 +321,23 @@ impl Role {
        self.continuation_prompt.as_deref()
    }
    pub fn inject_skill_instructions(&self) -> Option<bool> {
        self.inject_skill_instructions
    }
    pub fn skill_instructions(&self) -> Option<&str> {
        self.skill_instructions.as_deref()
    }
    pub fn memory(&self) -> Option<bool> {
        self.memory
    }
    pub fn skills_enabled(&self) -> Option<bool> {
        self.skills_enabled
    }
-    pub fn enabled_skills(&self) -> Option<&str> {
+    pub fn enabled_skills(&self) -> Option<&[String]> {
        self.enabled_skills.as_deref()
    }
@@ -362,11 +410,11 @@ impl RoleLike for Role {
        self.top_p
    }
-    fn enabled_tools(&self) -> Option<String> {
+    fn enabled_tools(&self) -> Option<Vec<String>> {
        self.enabled_tools.clone()
    }
-    fn enabled_mcp_servers(&self) -> Option<String> {
+    fn enabled_mcp_servers(&self) -> Option<Vec<String>> {
        self.enabled_mcp_servers.clone()
    }
@@ -385,15 +433,37 @@ impl RoleLike for Role {
        self.top_p = value;
    }
-    fn set_enabled_tools(&mut self, value: Option<String>) {
+    fn set_enabled_tools(&mut self, value: Option<Vec<String>>) {
        self.enabled_tools = value;
    }
-    fn set_enabled_mcp_servers(&mut self, value: Option<String>) {
+    fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>) {
        self.enabled_mcp_servers = value;
    }
 }
 fn parse_string_or_array(value: &Value) -> Option<Vec<String>> {
    if value.is_null() {
        return None;
    }
    if let Some(s) = value.as_str() {
        return Some(csv_to_vec(s));
    }
    if let Some(arr) = value.as_array() {
        let items: Vec<String> = arr
            .iter()
            .filter_map(|v| v.as_str().map(|s| s.trim().to_string()))
            .filter(|s| !s.is_empty())
            .collect();
        return Some(items);
    }
    None
 }
 fn parse_structure_prompt(prompt: &str) -> (&str, Vec<(&str, &str)>) {
    let mut text = prompt;
    let mut search_input = true;
@@ -468,14 +538,20 @@ mod tests {
    fn role_new_parses_enabled_tools() {
        let content = "---\nenabled_tools: tool1,tool2\n---\nPrompt";
        let role = Role::new("test", content);
-        assert_eq!(role.enabled_tools(), Some("tool1,tool2".to_string()));
+        assert_eq!(
            role.enabled_tools(),
            Some(vec!["tool1".to_string(), "tool2".to_string()])
        );
    }
    #[test]
    fn role_new_parses_enabled_mcp_servers() {
        let content = "---\nenabled_mcp_servers: github,jira\n---\nPrompt";
        let role = Role::new("test", content);
-        assert_eq!(role.enabled_mcp_servers(), Some("github,jira".to_string()));
+        assert_eq!(
            role.enabled_mcp_servers(),
            Some(vec!["github".to_string(), "jira".to_string()])
        );
    }
    #[test]
@@ -24,14 +24,26 @@ pub struct Session {
    temperature: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    top_p: Option<f64>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(
-    enabled_tools: Option<String>,
+        default,
-    #[serde(skip_serializing_if = "Option::is_none")]
+        skip_serializing_if = "Option::is_none",
-    enabled_mcp_servers: Option<String>,
+        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_tools: Option<Vec<String>>,
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_mcp_servers: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    skills_enabled: Option<bool>,
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(
-    enabled_skills: Option<String>,
+        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "super::deserialize_csv_or_vec"
    )]
    enabled_skills: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    save_session: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
@@ -44,6 +56,12 @@ pub struct Session {
    inject_todo_instructions: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    continuation_prompt: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    inject_skill_instructions: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    skill_instructions: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    memory: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    role_name: Option<String>,
@@ -83,12 +101,19 @@ impl Session {
        self.skills_enabled
    }
-    pub fn enabled_skills(&self) -> Option<&str> {
+    pub fn enabled_skills(&self) -> Option<&[String]> {
        self.enabled_skills.as_deref()
    }
-    pub fn new_from_ctx(ctx: &RequestContext, app: &AppConfig, name: &str) -> Self {
+    pub fn set_skills_enabled(&mut self, value: Option<bool>) {
-        let role = ctx.extract_role(app);
+        if self.skills_enabled != value {
            self.skills_enabled = value;
            self.dirty = true;
        }
    }
    pub fn new_from_ctx(ctx: &RequestContext, app: &AppConfig, name: &str) -> Result<Self> {
        let role = ctx.extract_role(app)?;
        let mut session = Self {
            name: name.to_string(),
            save_session: app.save_session,
@@ -96,7 +121,7 @@ impl Session {
        };
        session.set_role(role);
        session.dirty = false;
-        session
+        Ok(session)
    }
    pub fn load_from_ctx(
@@ -182,10 +207,16 @@ impl Session {
            data["top_p"] = top_p.into();
        }
        if let Some(enabled_tools) = self.enabled_tools() {
-            data["enabled_tools"] = enabled_tools.into();
+            data["enabled_tools"] = json!(enabled_tools);
        }
        if let Some(enabled_mcp_servers) = self.enabled_mcp_servers() {
-            data["enabled_mcp_servers"] = enabled_mcp_servers.into();
+            data["enabled_mcp_servers"] = json!(enabled_mcp_servers);
        }
        if let Some(skills_enabled) = self.skills_enabled() {
            data["skills_enabled"] = skills_enabled.into();
        }
        if let Some(enabled_skills) = self.enabled_skills() {
            data["enabled_skills"] = json!(enabled_skills);
        }
        if let Some(save_session) = self.save_session() {
            data["save_session"] = save_session.into();
@@ -202,6 +233,15 @@ impl Session {
        if let Some(continuation_prompt) = self.continuation_prompt() {
            data["continuation_prompt"] = continuation_prompt.into();
        }
        if let Some(inject_skill_instructions) = self.inject_skill_instructions() {
            data["inject_skill_instructions"] = inject_skill_instructions.into();
        }
        if let Some(skill_instructions) = self.skill_instructions() {
            data["skill_instructions"] = skill_instructions.into();
        }
        if let Some(memory) = self.memory() {
            data["memory"] = memory.into();
        }
        let (tokens, percent) = self.tokens_usage();
        data["total_tokens"] = tokens.into();
        if let Some(max_input_tokens) = self.model().max_input_tokens() {
@@ -242,11 +282,19 @@ impl Session {
        }
        if let Some(enabled_tools) = self.enabled_tools() {
-            items.push(("enabled_tools", enabled_tools));
+            items.push(("enabled_tools", enabled_tools.join(",")));
        }
        if let Some(enabled_mcp_servers) = self.enabled_mcp_servers() {
-            items.push(("enabled_mcp_servers", enabled_mcp_servers));
+            items.push(("enabled_mcp_servers", enabled_mcp_servers.join(",")));
        }
        if let Some(skills_enabled) = self.skills_enabled() {
            items.push(("skills_enabled", skills_enabled.to_string()));
        }
        if let Some(enabled_skills) = self.enabled_skills() {
            items.push(("enabled_skills", enabled_skills.join(",")));
        }
        if let Some(save_session) = self.save_session() {
@@ -272,6 +320,18 @@ impl Session {
        if let Some(continuation_prompt) = self.continuation_prompt() {
            items.push(("continuation_prompt", continuation_prompt.to_string()));
        }
        if let Some(inject_skill_instructions) = self.inject_skill_instructions() {
            items.push((
                "inject_skill_instructions",
                inject_skill_instructions.to_string(),
            ));
        }
        if let Some(skill_instructions) = self.skill_instructions() {
            items.push(("skill_instructions", skill_instructions.to_string()));
        }
        if let Some(memory) = self.memory() {
            items.push(("memory", memory.to_string()));
        }
        if let Some(max_input_tokens) = self.model().max_input_tokens() {
            items.push(("max_input_tokens", max_input_tokens.to_string()));
@@ -413,6 +473,18 @@ impl Session {
        self.continuation_prompt.as_deref()
    }
    pub fn inject_skill_instructions(&self) -> Option<bool> {
        self.inject_skill_instructions
    }
    pub fn skill_instructions(&self) -> Option<&str> {
        self.skill_instructions.as_deref()
    }
    pub fn memory(&self) -> Option<bool> {
        self.memory
    }
    pub fn set_inject_todo_instructions(&mut self, value: Option<bool>) {
        if self.inject_todo_instructions != value {
            self.inject_todo_instructions = value;
@@ -427,6 +499,27 @@ impl Session {
        }
    }
    pub fn set_inject_skill_instructions(&mut self, value: Option<bool>) {
        if self.inject_skill_instructions != value {
            self.inject_skill_instructions = value;
            self.dirty = true;
        }
    }
    pub fn set_memory(&mut self, value: Option<bool>) {
        if self.memory != value {
            self.memory = value;
            self.dirty = true;
        }
    }
    pub fn set_skill_instructions(&mut self, value: Option<String>) {
        if self.skill_instructions != value {
            self.skill_instructions = value;
            self.dirty = true;
        }
    }
    pub fn needs_compression(&self, global_compression_threshold: usize) -> bool {
        if self.compressing {
            return false;
@@ -682,11 +775,11 @@ impl RoleLike for Session {
        self.top_p
    }
-    fn enabled_tools(&self) -> Option<String> {
+    fn enabled_tools(&self) -> Option<Vec<String>> {
        self.enabled_tools.clone()
    }
-    fn enabled_mcp_servers(&self) -> Option<String> {
+    fn enabled_mcp_servers(&self) -> Option<Vec<String>> {
        self.enabled_mcp_servers.clone()
    }
@@ -713,14 +806,14 @@ impl RoleLike for Session {
        }
    }
-    fn set_enabled_tools(&mut self, value: Option<String>) {
+    fn set_enabled_tools(&mut self, value: Option<Vec<String>>) {
        if self.enabled_tools != value {
            self.enabled_tools = value;
            self.dirty = true;
        }
    }
-    fn set_enabled_mcp_servers(&mut self, value: Option<String>) {
+    fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>) {
        if self.enabled_mcp_servers != value {
            self.enabled_mcp_servers = value;
            self.dirty = true;
@@ -784,7 +877,7 @@ mod tests {
            functions: Functions::default(),
        });
        let ctx = RequestContext::new(app_state, WorkingMode::Cmd);
-        let session = Session::new_from_ctx(&ctx, &app_config, "test-session");
+        let session = Session::new_from_ctx(&ctx, &app_config, "test-session").unwrap();
        assert_eq!(session.name(), "test-session");
        assert_eq!(session.save_session(), app_config.save_session);
@@ -2,11 +2,11 @@ use super::*;
 use anyhow::Result;
 use fancy_regex::Regex;
 use log::{debug, info};
 use rust_embed::Embed;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::sync::LazyLock;
 use log::{debug, info};
 #[derive(Embed)]
 #[folder = "assets/skills/"]
@@ -33,9 +33,9 @@ pub struct Skill {
    #[serde(default)]
    body: String,
    #[serde(skip_serializing_if = "Option::is_none")]
-    enabled_tools: Option<String>,
+    enabled_tools: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
-    enabled_mcp_servers: Option<String>,
+    enabled_mcp_servers: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    auto_unload: Option<bool>,
 }
@@ -69,10 +69,10 @@ impl Skill {
                        }
                    }
                    "enabled_tools" => {
-                        skill.enabled_tools = value.as_str().map(|v| v.to_string());
+                        skill.enabled_tools = parse_skill_string_or_array(value);
                    }
                    "enabled_mcp_servers" => {
-                        skill.enabled_mcp_servers = value.as_str().map(|v| v.to_string());
+                        skill.enabled_mcp_servers = parse_skill_string_or_array(value);
                    }
                    "auto_unload" => {
                        skill.auto_unload = value.as_bool();
@@ -93,9 +93,8 @@ impl Skill {
        for file in SkillsAsset::iter() {
            debug!("Processing skill file: {}", file.as_ref());
-            let embedded_file = SkillsAsset::get(&file).ok_or_else(|| {
+            let embedded_file = SkillsAsset::get(&file)
-                anyhow!("Failed to load embedded skill file: {}", file.as_ref())
+                .ok_or_else(|| anyhow!("Failed to load embedded skill file: {}", file.as_ref()))?;
            })?;
            let content = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
            let file_path = paths::skills_dir().join(file.as_ref());
@@ -117,10 +116,10 @@ impl Skill {
    }
    pub fn load(name: &str) -> Result<Self> {
        paths::validate_skill_name(name)?;
        let path = paths::skill_file(name);
-        let content = read_to_string(&path).with_context(|| {
+        let content = read_to_string(&path)
-            format!("Failed to read skill '{name}' at {}", path.display())
+            .with_context(|| format!("Failed to read skill '{name}' at {}", path.display()))?;
        })?;
        Ok(Skill::new(name, &content))
    }
@@ -136,11 +135,11 @@ impl Skill {
        &self.body
    }
-    pub fn enabled_tools(&self) -> Option<&str> {
+    pub fn enabled_tools(&self) -> Option<&[String]> {
        self.enabled_tools.as_deref()
    }
-    pub fn enabled_mcp_servers(&self) -> Option<&str> {
+    pub fn enabled_mcp_servers(&self) -> Option<&[String]> {
        self.enabled_mcp_servers.as_deref()
    }
@@ -148,11 +147,7 @@ impl Skill {
        self.auto_unload.unwrap_or(false)
    }
-    pub fn is_compatible(&self, function_calling_enabled: bool, mcp_enabled: bool) -> bool {
+    pub fn is_compatible(&self, mcp_enabled: bool) -> bool {
        if self.declares_tools() && !function_calling_enabled {
            return false;
        }
        if self.declares_mcp_servers() && !mcp_enabled {
            return false;
        }
@@ -160,21 +155,32 @@ impl Skill {
        true
    }
    fn declares_tools(&self) -> bool {
        self.enabled_tools
            .as_deref()
            .map(|s| !s.trim().is_empty())
            .unwrap_or(false)
    }
    fn declares_mcp_servers(&self) -> bool {
        self.enabled_mcp_servers
            .as_deref()
-            .map(|s| !s.trim().is_empty())
+            .map(|servers| !servers.is_empty())
            .unwrap_or(false)
    }
 }
 fn parse_skill_string_or_array(value: &Value) -> Option<Vec<String>> {
    if value.is_null() {
        return None;
    }
    if let Some(s) = value.as_str() {
        return Some(csv_to_vec(s));
    }
    if let Some(arr) = value.as_array() {
        let items: Vec<String> = arr
            .iter()
            .filter_map(|v| v.as_str().map(|s| s.trim().to_string()))
            .filter(|s| !s.is_empty())
            .collect();
        return Some(items);
    }
    None
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -202,8 +208,14 @@ mod tests {
        assert_eq!(skill.name(), "git-master");
        assert_eq!(skill.description(), "Atomic commits, rebase surgery");
-        assert_eq!(skill.enabled_tools(), Some("shell,fs"));
+        assert_eq!(
-        assert_eq!(skill.enabled_mcp_servers(), Some("github"));
+            skill.enabled_tools(),
            Some(["shell".to_string(), "fs".to_string()].as_slice())
        );
        assert_eq!(
            skill.enabled_mcp_servers(),
            Some(["github".to_string()].as_slice())
        );
        assert!(skill.auto_unload());
        assert_eq!(skill.body(), "You are a git expert");
    }
@@ -273,25 +285,21 @@ mod tests {
    }
    #[test]
-    fn is_compatible_knowledge_only_passes_all_combinations() {
+    fn is_compatible_knowledge_only_passes_both_mcp_states() {
        let skill = Skill::new("test", "Just knowledge");
-        assert!(skill.is_compatible(false, false));
+        assert!(skill.is_compatible(false));
-        assert!(skill.is_compatible(true, false));
+        assert!(skill.is_compatible(true));
        assert!(skill.is_compatible(false, true));
        assert!(skill.is_compatible(true, true));
    }
    #[test]
-    fn is_compatible_with_tools_requires_function_calling() {
+    fn is_compatible_with_tools_only_passes_both_mcp_states() {
        let content = "---\nenabled_tools: shell\n---\nbody";
        let skill = Skill::new("test", content);
-        assert!(!skill.is_compatible(false, true));
+        assert!(skill.is_compatible(false));
-        assert!(!skill.is_compatible(false, false));
+        assert!(skill.is_compatible(true));
        assert!(skill.is_compatible(true, true));
        assert!(skill.is_compatible(true, false));
    }
    #[test]
@@ -300,30 +308,26 @@ mod tests {
        let skill = Skill::new("test", content);
-        assert!(!skill.is_compatible(true, false));
+        assert!(!skill.is_compatible(false));
-        assert!(!skill.is_compatible(false, false));
+        assert!(skill.is_compatible(true));
        assert!(skill.is_compatible(true, true));
    }
    #[test]
-    fn is_compatible_requires_both_when_both_declared() {
+    fn is_compatible_with_both_requires_mcp_enabled() {
-        let content =
+        let content = "---\nenabled_tools: shell\nenabled_mcp_servers: github\n---\nbody";
            "---\nenabled_tools: shell\nenabled_mcp_servers: github\n---\nbody";
        let skill = Skill::new("test", content);
-        assert!(!skill.is_compatible(true, false));
+        assert!(!skill.is_compatible(false));
-        assert!(!skill.is_compatible(false, true));
+        assert!(skill.is_compatible(true));
        assert!(!skill.is_compatible(false, false));
        assert!(skill.is_compatible(true, true));
    }
    #[test]
-    fn is_compatible_empty_string_tools_is_knowledge_only() {
+    fn is_compatible_empty_string_mcps_is_knowledge_only() {
-        let content = "---\nenabled_tools: \"\"\n---\nbody";
+        let content = "---\nenabled_mcp_servers: \"\"\n---\nbody";
        let skill = Skill::new("test", content);
-        assert!(skill.is_compatible(false, false));
+        assert!(skill.is_compatible(false));
    }
 }
@@ -3,14 +3,16 @@ use super::app_config::AppConfig;
 use super::paths;
 use super::role::Role;
 use super::session::Session;
 use super::skill::Skill;
-use anyhow::{Result, bail};
+use anyhow::{Result, anyhow, bail};
-use std::collections::HashSet;
+use std::collections::{BTreeSet, HashSet};
 #[derive(Debug)]
 pub struct SkillPolicy {
    pub skills_enabled: bool,
    pub enabled: HashSet<String>,
    pub compatible_enabled: BTreeSet<String>,
 }
 impl SkillPolicy {
@@ -27,20 +29,27 @@ impl SkillPolicy {
            session,
            &paths::has_skill,
            &paths::list_skills,
            &|name, mcp_on| {
                Skill::load(name)
                    .map(|s| s.is_compatible(mcp_on))
                    .unwrap_or(false)
            },
        )
    }
-    fn effective_with<F, G>(
+    fn effective_with<F, G, H>(
        global: &AppConfig,
        role: Option<&Role>,
        agent: Option<&Agent>,
        session: Option<&Session>,
        skill_exists: &F,
        list_installed: &G,
        skill_is_compatible: &H,
    ) -> Result<Self>
    where
        F: Fn(&str) -> bool,
        G: Fn() -> Vec<String>,
        H: Fn(&str, bool) -> bool,
    {
        let mut skills_enabled = global.skills_enabled;
        if let Some(r) = role
@@ -67,27 +76,35 @@ impl SkillPolicy {
            .map(|v| v.iter().cloned().collect());
        let enabled_raw: Option<Vec<String>> = session
-            .and_then(|s| parse_csv_opt(s.enabled_skills()))
+            .and_then(|s| s.enabled_skills().map(|v| v.to_vec()))
            .or_else(|| agent.and_then(|a| a.enabled_skills().map(|v| v.to_vec())))
-            .or_else(|| role.and_then(|r| parse_csv_opt(r.enabled_skills())))
+            .or_else(|| role.and_then(|r| r.enabled_skills().map(|v| v.to_vec())))
-            .or_else(|| parse_csv_opt(global.enabled_skills.as_deref()));
+            .or_else(|| global.enabled_skills.clone());
        let enabled: HashSet<String> = match enabled_raw {
            Some(explicit) => {
                let set: HashSet<String> = explicit.into_iter().collect();
                for name in &set {
-                    if !skill_exists(name) {
+                    paths::validate_skill_name(name).map_err(|e| {
-                        bail!("enabled_skills references skill '{name}' which is not installed");
+                        anyhow!("enabled_skills contains invalid name '{name}': {e}")
-                    }
+                    })?;
-
+                    match &visible {
-                    if let Some(vs) = &visible
+                        Some(vs) => {
-                        && !vs.contains(name)
+                            if !vs.contains(name) {
                    {
                                bail!(
-                            "enabled_skills references skill '{name}' which is not in visible_skills"
+                                    "enabled_skills references skill '{name}' which is not in the global 'visible_skills' allow-list"
                                );
                            }
                        }
                        None => {
                            if !skill_exists(name) {
                                bail!(
                                    "enabled_skills references skill '{name}' which is not installed"
                                );
                            }
                        }
                    }
                }
                set
            }
            None => match &visible {
@@ -96,9 +113,21 @@ impl SkillPolicy {
            },
        };
        let compatible_enabled: BTreeSet<String> = if skills_enabled {
            let mcp_on = global.mcp_server_support;
            enabled
                .iter()
                .filter(|name| skill_is_compatible(name, mcp_on))
                .cloned()
                .collect()
        } else {
            BTreeSet::new()
        };
        Ok(Self {
            skills_enabled,
            enabled,
            compatible_enabled,
        })
    }
@@ -107,17 +136,9 @@ impl SkillPolicy {
    }
 }
 fn parse_csv_opt(s: Option<&str>) -> Option<Vec<String>> {
    s.map(|raw| {
        raw.split(',')
            .map(|t| t.trim().to_string())
            .filter(|t| !t.is_empty())
            .collect()
    })
 }
 #[cfg(test)]
 mod tests {
    use super::super::csv_to_vec;
    use super::*;
    fn always_true(_: &str) -> bool {
@@ -128,6 +149,10 @@ mod tests {
        Vec::new()
    }
    fn all_compatible(_: &str, _: bool) -> bool {
        true
    }
    fn make_app_config(
        skills_enabled: bool,
        enabled: Option<&str>,
@@ -135,7 +160,7 @@ mod tests {
    ) -> AppConfig {
        AppConfig {
            skills_enabled,
-            enabled_skills: enabled.map(|s| s.to_string()),
+            enabled_skills: enabled.map(csv_to_vec),
            visible_skills: visible.map(|v| v.iter().map(|s| s.to_string()).collect()),
            ..AppConfig::default()
        }
@@ -152,6 +177,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -164,8 +190,15 @@ mod tests {
        let global = AppConfig::default();
        let installed = || vec!["alpha".to_string(), "beta".to_string()];
-        let policy =
+        let policy = SkillPolicy::effective_with(
-            SkillPolicy::effective_with(&global, None, None, None, &always_true, &installed)
+            &global,
            None,
            None,
            None,
            &always_true,
            &installed,
            &all_compatible,
        )
        .unwrap();
        assert_eq!(policy.enabled.len(), 2);
@@ -184,6 +217,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -203,6 +237,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -214,10 +249,7 @@ mod tests {
    #[test]
    fn role_overrides_global_enabled_skills() {
        let global = make_app_config(true, Some("alpha"), Some(&["alpha", "beta"]));
-        let role = Role::new(
+        let role = Role::new("test", "---\nenabled_skills: beta\n---\nbody");
            "test",
            "---\nenabled_skills: beta\n---\nbody",
        );
        let policy = SkillPolicy::effective_with(
            &global,
@@ -226,6 +258,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -245,6 +278,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -265,6 +299,7 @@ mod tests {
            None,
            &always_true,
            &|| vec!["alpha".to_string()],
            &all_compatible,
        )
        .unwrap();
@@ -282,6 +317,7 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -300,6 +336,7 @@ mod tests {
            None,
            &|_| false,
            &empty_installed,
            &all_compatible,
        )
        .unwrap_err();
@@ -318,10 +355,14 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap_err();
-        assert!(err.to_string().contains("not in visible_skills"));
+        assert!(
            err.to_string()
                .contains("not in the global 'visible_skills'")
        );
        assert!(err.to_string().contains("beta"));
    }
@@ -336,6 +377,7 @@ mod tests {
            None,
            &|_| false,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
@@ -354,9 +396,142 @@ mod tests {
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
        assert!(policy.enabled.is_empty());
    }
    #[test]
    fn compatible_enabled_is_empty_when_skills_disabled() {
        let global = AppConfig {
            skills_enabled: false,
            enabled_skills: Some(vec!["alpha".into()]),
            visible_skills: Some(vec!["alpha".into()]),
            ..AppConfig::default()
        };
        let policy = SkillPolicy::effective_with(
            &global,
            None,
            None,
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
        assert!(!policy.skills_enabled);
        assert!(policy.compatible_enabled.is_empty());
    }
    #[test]
    fn compatible_enabled_short_circuits_callback_when_skills_disabled() {
        use std::cell::Cell;
        let global = AppConfig {
            skills_enabled: false,
            enabled_skills: Some(vec!["alpha".into()]),
            visible_skills: Some(vec!["alpha".into()]),
            ..AppConfig::default()
        };
        let invoked = Cell::new(0u32);
        let counting = |_: &str, _: bool| {
            invoked.set(invoked.get() + 1);
            true
        };
        SkillPolicy::effective_with(
            &global,
            None,
            None,
            None,
            &always_true,
            &empty_installed,
            &counting,
        )
        .unwrap();
        assert_eq!(
            invoked.get(),
            0,
            "skill_is_compatible callback must not run when skills are disabled"
        );
    }
    #[test]
    fn compatible_enabled_includes_all_when_callback_passes() {
        let global = make_app_config(true, Some("alpha,beta"), Some(&["alpha", "beta"]));
        let policy = SkillPolicy::effective_with(
            &global,
            None,
            None,
            None,
            &always_true,
            &empty_installed,
            &all_compatible,
        )
        .unwrap();
        assert_eq!(policy.compatible_enabled.len(), 2);
        assert!(policy.compatible_enabled.contains("alpha"));
        assert!(policy.compatible_enabled.contains("beta"));
    }
    #[test]
    fn compatible_enabled_excludes_incompatible_skills() {
        let global = make_app_config(true, Some("alpha,beta"), Some(&["alpha", "beta"]));
        let only_alpha_compat = |name: &str, _: bool| name == "alpha";
        let policy = SkillPolicy::effective_with(
            &global,
            None,
            None,
            None,
            &always_true,
            &empty_installed,
            &only_alpha_compat,
        )
        .unwrap();
        assert!(policy.compatible_enabled.contains("alpha"));
        assert!(!policy.compatible_enabled.contains("beta"));
        assert_eq!(policy.compatible_enabled.len(), 1);
    }
    #[test]
    fn compatible_enabled_passes_mcp_flag_to_callback() {
        use std::cell::Cell;
        let global = AppConfig {
            skills_enabled: true,
            mcp_server_support: false,
            enabled_skills: Some(vec!["alpha".into()]),
            visible_skills: Some(vec!["alpha".into()]),
            ..AppConfig::default()
        };
        let observed_mcp = Cell::new(None::<bool>);
        let capture = |_: &str, mcp_on: bool| {
            observed_mcp.set(Some(mcp_on));
            true
        };
        SkillPolicy::effective_with(
            &global,
            None,
            None,
            None,
            &always_true,
            &empty_installed,
            &capture,
        )
        .unwrap();
        assert_eq!(
            observed_mcp.get(),
            Some(false),
            "callback must receive mcp_server_support flag from AppConfig"
        );
    }
 }
@@ -1,7 +1,8 @@
 use super::role::{Role, RoleLike};
 use super::skill::Skill;
 use super::skill_policy::SkillPolicy;
-use anyhow::{Result, bail};
+use anyhow::{Result, anyhow, bail};
 use indexmap::IndexMap;
 use std::collections::BTreeSet;
@@ -10,24 +11,7 @@ pub struct SkillRegistry {
    loaded: IndexMap<String, Skill>,
 }
 #[allow(dead_code)]
 impl SkillRegistry {
    pub fn new() -> Self {
        Self {
            loaded: IndexMap::new(),
        }
    }
    pub fn load(&mut self, name: &str) -> Result<()> {
        if self.loaded.contains_key(name) {
            bail!("Skill '{name}' is already loaded");
        }
        let skill = Skill::load(name)?;
        self.loaded.insert(name.to_string(), skill);
        Ok(())
    }
    pub fn insert(&mut self, skill: Skill) -> Result<()> {
        let name = skill.name().to_string();
@@ -40,12 +24,10 @@ impl SkillRegistry {
        Ok(())
    }
-    pub fn unload(&mut self, name: &str) -> Result<()> {
+    pub fn unload(&mut self, name: &str) -> Result<Skill> {
-        if self.loaded.shift_remove(name).is_none() {
+        self.loaded
-            bail!("Skill '{name}' is not loaded");
+            .shift_remove(name)
-        }
+            .ok_or_else(|| anyhow!("Skill '{name}' is not loaded"))
        Ok(())
    }
    pub fn loaded_names(&self) -> Vec<String> {
@@ -55,8 +37,8 @@ impl SkillRegistry {
    pub fn loaded_mcp_servers(&self) -> BTreeSet<String> {
        let mut out = BTreeSet::new();
        for skill in self.loaded.values() {
-            if let Some(csv) = skill.enabled_mcp_servers() {
+            if let Some(servers) = skill.enabled_mcp_servers() {
-                for token in csv.split(',') {
+                for token in servers {
                    let t = token.trim();
                    if !t.is_empty() {
                        out.insert(t.to_string());
@@ -75,64 +57,69 @@ impl SkillRegistry {
        self.loaded.retain(|_, skill| !skill.auto_unload());
    }
-    pub fn effective_role(&self, base: &Role) -> Role {
+    pub fn effective_role(&self, base: &Role, policy: &SkillPolicy) -> Role {
-        if self.loaded.is_empty() {
+        if !policy.skills_enabled || self.loaded.is_empty() {
            return base.clone();
        }
        let mut effective = base.clone();
        let skip_body = effective.is_embedded_prompt();
-        let base_tools_set = effective.enabled_tools().is_some();
+        let base_tools = effective.enabled_tools();
-        let base_mcps_set = effective.enabled_mcp_servers().is_some();
+        let base_tools_set = base_tools.is_some();
        let base_mcps = effective.enabled_mcp_servers();
        let base_mcps_set = base_mcps.is_some();
-        let mut tools = parse_csv(effective.enabled_tools().as_deref());
+        let mut tools: BTreeSet<String> = base_tools.unwrap_or_default().into_iter().collect();
-        let mut mcps = parse_csv(effective.enabled_mcp_servers().as_deref());
+        let mut mcps: BTreeSet<String> = base_mcps.unwrap_or_default().into_iter().collect();
-        for (_, skill) in &self.loaded {
+        for (name, skill) in &self.loaded {
-            tools.extend(parse_csv(skill.enabled_tools()));
+            if !policy.allows(name) {
-            mcps.extend(parse_csv(skill.enabled_mcp_servers()));
+                continue;
            }
            if let Some(skill_tools) = skill.enabled_tools() {
                tools.extend(skill_tools.iter().cloned());
            }
            if let Some(servers) = skill.enabled_mcp_servers() {
                mcps.extend(servers.iter().cloned());
            }
            if !skip_body && !skill.body().is_empty() {
-                let separator = if effective.is_empty_prompt() { "" } else { "\n\n" };
+                let separator = if effective.is_empty_prompt() {
                    ""
                } else {
                    "\n\n"
                };
                effective.append_to_prompt(separator);
                effective.append_to_prompt(skill.body());
            }
        }
        if base_tools_set || !tools.is_empty() {
-            effective.set_enabled_tools(Some(join_csv(&tools)));
+            effective.set_enabled_tools(Some(tools.into_iter().collect()));
        }
        if base_mcps_set || !mcps.is_empty() {
-            effective.set_enabled_mcp_servers(Some(join_csv(&mcps)));
+            effective.set_enabled_mcp_servers(Some(mcps.into_iter().collect()));
        }
        effective
    }
 }
 fn parse_csv(s: Option<&str>) -> BTreeSet<String> {
    let mut set = BTreeSet::new();
    if let Some(raw) = s {
        for token in raw.split(',') {
            let trimmed = token.trim();
            if !trimmed.is_empty() {
                set.insert(trimmed.to_string());
            }
        }
    }
    set
 }
 fn join_csv(set: &BTreeSet<String>) -> String {
    set.iter().cloned().collect::<Vec<_>>().join(",")
 }
 #[cfg(test)]
 impl SkillRegistry {
    fn insert_for_test(&mut self, skill: Skill) {
        self.loaded.insert(skill.name().to_string(), skill);
    }
    fn effective_role_for_test(&self, base: &Role) -> Role {
        let policy = SkillPolicy {
            skills_enabled: true,
            enabled: self.loaded.keys().cloned().collect(),
            compatible_enabled: self.loaded.keys().cloned().collect(),
        };
        self.effective_role(base, &policy)
    }
 }
 #[cfg(test)]
@@ -151,51 +138,51 @@ mod tests {
    #[test]
    fn empty_registry_returns_base_clone() {
        let base = Role::new("test", "You are a helper");
-        let registry = SkillRegistry::new();
+        let registry = SkillRegistry::default();
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), base.prompt());
    }
    #[test]
    fn one_skill_appends_body_after_base_with_separator() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("git-master", "description: D", "Git knowledge"));
        let base = Role::new("test", "You are a helper");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), "You are a helper\n\nGit knowledge");
    }
    #[test]
    fn two_skills_compose_bodies_in_insertion_order() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("a", "", "Alpha body"));
        registry.insert_for_test(make_skill("b", "", "Beta body"));
        let base = Role::new("test", "Base");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), "Base\n\nAlpha body\n\nBeta body");
    }
    #[test]
    fn empty_base_prompt_omits_leading_separator() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("a", "", "Alpha"));
        registry.insert_for_test(make_skill("b", "", "Beta"));
        let base = Role::new("test", "");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), "Alpha\n\nBeta");
    }
    #[test]
    fn embedded_prompt_base_skips_body_composition() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill(
            "git-master",
            "enabled_tools: shell",
@@ -203,27 +190,27 @@ mod tests {
        ));
        let base = Role::new("test", "Process: __INPUT__");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), "Process: __INPUT__");
        let tools = effective.enabled_tools().expect("tools set by skill");
-        assert!(tools.contains("shell"));
+        assert!(tools.iter().any(|s| s == "shell"));
    }
    #[test]
    fn skills_with_empty_body_do_not_inject_separator() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("knowledge", "enabled_tools: fs", ""));
        let base = Role::new("test", "Base");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert_eq!(effective.prompt(), "Base");
    }
    #[test]
    fn tools_and_mcps_are_unioned_and_deduplicated() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill(
            "a",
            "enabled_tools: shell,fs\nenabled_mcp_servers: github",
@@ -236,29 +223,26 @@ mod tests {
        ));
        let mut base = Role::new("test", "body");
-        base.set_enabled_tools(Some("web_search".to_string()));
+        base.set_enabled_tools(Some(vec!["web_search".to_string()]));
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
-        let tools_str = effective.enabled_tools().unwrap();
+        let tools_vec = effective.enabled_tools().unwrap();
-        let tools: BTreeSet<&str> = tools_str.split(',').collect();
+        let tools: BTreeSet<&str> = tools_vec.iter().map(|s| s.as_str()).collect();
-        assert_eq!(
+        assert_eq!(tools, BTreeSet::from(["fs", "git", "shell", "web_search"]));
            tools,
            BTreeSet::from(["fs", "git", "shell", "web_search"])
        );
-        let mcps_str = effective.enabled_mcp_servers().unwrap();
+        let mcps_vec = effective.enabled_mcp_servers().unwrap();
-        let mcps: BTreeSet<&str> = mcps_str.split(',').collect();
+        let mcps: BTreeSet<&str> = mcps_vec.iter().map(|s| s.as_str()).collect();
        assert_eq!(mcps, BTreeSet::from(["github", "jira"]));
    }
    #[test]
    fn no_skill_tool_contributions_preserves_base_none() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("knowledge", "", "Pure knowledge"));
        let base = Role::new("test", "Base");
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
        assert!(effective.enabled_tools().is_none());
        assert!(effective.enabled_mcp_servers().is_none());
@@ -266,29 +250,19 @@ mod tests {
    #[test]
    fn base_some_empty_tools_is_preserved() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("knowledge", "", "Pure knowledge"));
        let mut base = Role::new("test", "Base");
-        base.set_enabled_tools(Some(String::new()));
+        base.set_enabled_tools(Some(Vec::new()));
-        let effective = registry.effective_role(&base);
+        let effective = registry.effective_role_for_test(&base);
-        assert_eq!(effective.enabled_tools().as_deref(), Some(""));
+        assert_eq!(effective.enabled_tools().as_deref(), Some([].as_slice()));
    }
    #[test]
    fn load_already_loaded_returns_error() {
        let mut registry = SkillRegistry::new();
        registry.insert_for_test(make_skill("git-master", "", "body"));
        let err = registry.load("git-master").unwrap_err();
        assert!(err.to_string().contains("already loaded"));
    }
    #[test]
    fn unload_not_loaded_returns_error() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        let err = registry.unload("missing").unwrap_err();
@@ -297,7 +271,7 @@ mod tests {
    #[test]
    fn unload_existing_succeeds_and_removes() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("git-master", "", "body"));
        assert!(registry.is_loaded("git-master"));
@@ -307,7 +281,7 @@ mod tests {
    #[test]
    fn loaded_names_returns_insertion_order() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("zulu", "", "body"));
        registry.insert_for_test(make_skill("alpha", "", "body"));
@@ -321,7 +295,7 @@ mod tests {
    #[test]
    fn sweep_removes_only_auto_unload_skills() {
-        let mut registry = SkillRegistry::new();
+        let mut registry = SkillRegistry::default();
        registry.insert_for_test(make_skill("ephemeral", "auto_unload: true", "body"));
        registry.insert_for_test(make_skill("persistent", "", "body"));
@@ -333,7 +307,7 @@ mod tests {
    #[test]
    fn is_loaded_returns_false_for_unknown() {
-        let registry = SkillRegistry::new();
+        let registry = SkillRegistry::default();
        assert!(!registry.is_loaded("nothing"));
    }
@@ -0,0 +1,679 @@
 use std::collections::HashSet;
 use std::path::{Path, PathBuf};
 use std::{env, fs};
 use anyhow::{Context, Result, anyhow, bail};
 use indexmap::IndexMap;
 use serde_json::{Value, json};
 use super::{FunctionDeclaration, JsonSchema};
 use crate::config::RequestContext;
 use crate::config::memory::{
    MemoryFile, MemoryFrontmatter, MemoryStore, WorkspaceMemory, bootstrap_workspace_memory,
    find_git_root,
 };
 use crate::config::paths;
 pub const MEMORY_FUNCTION_PREFIX: &str = "memory__";
 const PER_FILE_SOFT_CAP: usize = 2_000;
 pub fn memory_function_declarations() -> Vec<FunctionDeclaration> {
    vec![
        FunctionDeclaration {
            name: format!("{MEMORY_FUNCTION_PREFIX}read"),
            description: "Read the full content of a specific memory file by its name slug."
                .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([(
                    "name".to_string(),
                    JsonSchema {
                        type_value: Some("string".to_string()),
                        description: Some(
                            "The `name:` slug of the memory file to read (from MEMORY.md index)"
                                .into(),
                        ),
                        ..Default::default()
                    },
                )])),
                required: Some(vec!["name".to_string()]),
                ..Default::default()
            },
            agent: false,
        },
        FunctionDeclaration {
            name: format!("{MEMORY_FUNCTION_PREFIX}write"),
            description:
                "Create or replace a memory file. Caller must also update MEMORY.md index."
                    .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([
                    (
                        "name".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some(
                                "Short kebab-case slug for the file (no extension)".into(),
                            ),
                            ..Default::default()
                        },
                    ),
                    (
                        "description".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some("One-line description for the MEMORY.md index".into()),
                            ..Default::default()
                        },
                    ),
                    (
                        "type".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some(
                                "Memory type: user | feedback | project | reference".into(),
                            ),
                            ..Default::default()
                        },
                    ),
                    (
                        "content".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some("The full markdown body of the memory file".into()),
                            ..Default::default()
                        },
                    ),
                    (
                        "scope".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some(
                                "Where to write: 'global' (user-level) or 'workspace' (project-level)"
                                    .into(),
                            ),
                            ..Default::default()
                        },
                    ),
                ])),
                required: Some(vec![
                    "name".to_string(),
                    "description".to_string(),
                    "content".to_string(),
                    "scope".to_string(),
                ]),
                ..Default::default()
            },
            agent: false,
        },
        FunctionDeclaration {
            name: format!("{MEMORY_FUNCTION_PREFIX}list"),
            description: "List all known drill files with metadata (size, type, scope).".to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::new()),
                ..Default::default()
            },
            agent: false,
        },
        FunctionDeclaration {
            name: format!("{MEMORY_FUNCTION_PREFIX}lint"),
            description: "Health-check memory: orphan files, broken [[wikilinks]], oversized files."
                .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::new()),
                ..Default::default()
            },
            agent: false,
        },
        FunctionDeclaration {
            name: format!("{MEMORY_FUNCTION_PREFIX}edit_index"),
            description:
                "Replace the entire MEMORY.md index at the given scope. Use to add always-on facts, \
                 reorganize, prune stale entries, or fix descriptions. Coyote manages the path; \
                 NEVER use fs_write or any other generic file tool on MEMORY.md."
                    .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([
                    (
                        "scope".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some(
                                "Where to edit: 'global' (user-level) or 'workspace' (project-level)"
                                    .into(),
                            ),
                            ..Default::default()
                        },
                    ),
                    (
                        "content".to_string(),
                        JsonSchema {
                            type_value: Some("string".to_string()),
                            description: Some("Full new contents of MEMORY.md".into()),
                            ..Default::default()
                        },
                    ),
                ])),
                required: Some(vec!["scope".to_string(), "content".to_string()]),
                ..Default::default()
            },
            agent: false,
        },
    ]
 }
 pub fn handle_memory_tool(ctx: &mut RequestContext, cmd_name: &str, args: &Value) -> Result<Value> {
    if !ctx.should_register_memory_tools() {
        bail!("Memory tools are disabled (memory off or function calling unavailable).");
    }
    let action = cmd_name
        .strip_prefix(MEMORY_FUNCTION_PREFIX)
        .unwrap_or(cmd_name);
    let cwd = env::current_dir().context("get cwd")?;
    let store = MemoryStore::new(&cwd);
    match action {
        "read" => {
            let name = args
                .get("name")
                .and_then(Value::as_str)
                .ok_or_else(|| anyhow!("name is required"))?;
            let file = find_file(&store, name)?
                .ok_or_else(|| anyhow!("memory file '{}' not found", name))?;
            Ok(json!({
                "name": file.frontmatter.name,
                "type": file.frontmatter.kind,
                "content": file.body,
            }))
        }
        "list" => {
            let files = store.list_files()?;
            let entries: Vec<_> = files
                .iter()
                .map(|f| {
                    json!({
                        "name": f.frontmatter.name,
                        "description": f.frontmatter.description,
                        "type": f.frontmatter.kind,
                        "char_len": f.char_len(),
                        "path": f.path.display().to_string(),
                    })
                })
                .collect();
            Ok(json!({
                "files": entries,
                "global_index_exists": paths::global_memory_index_path().exists(),
                "workspace": store.workspace.as_ref().map(workspace_label),
            }))
        }
        "write" => {
            let name = arg_str(args, "name")?;
            let description = arg_str(args, "description")?;
            let content = arg_str(args, "content")?;
            let scope = arg_str(args, "scope")?;
            let kind = args.get("type").and_then(Value::as_str).map(String::from);
            let target_dir = match scope.as_str() {
                "global" => paths::global_memory_dir(),
                "workspace" => workspace_write_dir(&store, &cwd)?,
                other => bail!("unknown scope '{}': use 'global' or 'workspace'", other),
            };
            let file = MemoryFile {
                path: target_dir.join(format!("{name}.md")),
                frontmatter: MemoryFrontmatter {
                    name: name.clone(),
                    description: Some(description.clone()),
                    kind,
                },
                body: content,
            };
            file.save()?;
            let index_path = target_dir.join("MEMORY.md");
            let index_updated = ensure_index_entry(&index_path, &name, &description)?;
            Ok(json!({
                "status": "ok",
                "path": file.path.display().to_string(),
                "index_path": index_path.display().to_string(),
                "index_updated": index_updated,
            }))
        }
        "edit_index" => {
            let scope = arg_str(args, "scope")?;
            let content = arg_str(args, "content")?;
            let target_dir = match scope.as_str() {
                "global" => paths::global_memory_dir(),
                "workspace" => workspace_write_dir(&store, &cwd)?,
                other => bail!("unknown scope '{}': use 'global' or 'workspace'", other),
            };
            let index_path = write_memory_index(&target_dir, &content)?;
            Ok(json!({
                "status": "ok",
                "path": index_path.display().to_string(),
            }))
        }
        "lint" => lint_memory(&store),
        _ => bail!("unknown memory action: {action}"),
    }
 }
 fn write_memory_index(target_dir: &Path, content: &str) -> Result<PathBuf> {
    fs::create_dir_all(target_dir)?;
    let index_path = target_dir.join("MEMORY.md");
    fs::write(&index_path, content)?;
    Ok(index_path)
 }
 fn ensure_index_entry(index_path: &Path, name: &str, description: &str) -> Result<bool> {
    let existing = fs::read_to_string(index_path).unwrap_or_default();
    let already_referenced =
        existing.contains(&format!("[[{name}]]")) || existing.contains(&format!("{name}.md"));
    if already_referenced {
        return Ok(false);
    }
    let entry = format!("- [[{name}]]: {description}\n");
    let new_content = if existing.is_empty() {
        format!("# Memory Index\n\n{entry}")
    } else if existing.ends_with('\n') {
        format!("{existing}{entry}")
    } else {
        format!("{existing}\n{entry}")
    };
    if let Some(parent) = index_path.parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(index_path, new_content)?;
    Ok(true)
 }
 fn arg_str(args: &Value, key: &str) -> Result<String> {
    args.get(key)
        .and_then(Value::as_str)
        .map(String::from)
        .ok_or_else(|| anyhow!("{} is required", key))
 }
 fn find_file(store: &MemoryStore, name: &str) -> Result<Option<MemoryFile>> {
    Ok(store
        .list_files()?
        .into_iter()
        .find(|f| f.frontmatter.name == name))
 }
 fn workspace_write_dir(store: &MemoryStore, cwd: &Path) -> Result<PathBuf> {
    match &store.workspace {
        Some(WorkspaceMemory::Structured { dir, .. }) => Ok(dir.clone()),
        Some(WorkspaceMemory::Lite { workspace_root, .. }) => {
            Ok(paths::workspace_memory_dir_for(workspace_root))
        }
        None => match find_git_root(cwd) {
            Some(git_root) => bootstrap_workspace_memory(&git_root),
            None => bail!(
                "no workspace memory discoverable and not inside a git repository for auto-bootstrap. \
                 If you want workspace memory, run `coyote --init-memory workspace`."
            ),
        },
    }
 }
 fn workspace_label(w: &WorkspaceMemory) -> Value {
    match w {
        WorkspaceMemory::Structured { workspace_root, .. } => json!({
            "mode": "structured",
            "root": workspace_root.display().to_string(),
        }),
        WorkspaceMemory::Lite {
            workspace_root,
            file,
        } => json!({
            "mode": "lite",
            "root": workspace_root.display().to_string(),
            "file": file.display().to_string(),
        }),
    }
 }
 fn lint_memory(store: &MemoryStore) -> Result<Value> {
    let files = store.list_files()?;
    let names: HashSet<&str> = files.iter().map(|f| f.frontmatter.name.as_str()).collect();
    let mut oversized = Vec::new();
    let mut broken_links = Vec::new();
    for f in &files {
        if f.char_len() > PER_FILE_SOFT_CAP {
            oversized.push(json!({"name": &f.frontmatter.name, "chars": f.char_len()}));
        }
        for link in extract_wikilinks(&f.body) {
            if !names.contains(link.as_str()) {
                broken_links.push(json!({"from": &f.frontmatter.name, "to": link}));
            }
        }
    }
    let index_content = store
        .load_global_index()?
        .or_else(|| store.load_workspace_index().ok().flatten())
        .unwrap_or_default();
    let mut orphans = Vec::new();
    for f in &files {
        if !index_content.contains(&f.frontmatter.name) {
            orphans.push(f.frontmatter.name.clone());
        }
    }
    Ok(json!({
        "total_files": files.len(),
        "oversized": oversized,
        "broken_wikilinks": broken_links,
        "orphans": orphans,
    }))
 }
 fn extract_wikilinks(body: &str) -> Vec<String> {
    let mut out = Vec::new();
    let bytes = body.as_bytes();
    let mut i = 0;
    while i + 1 < bytes.len() {
        if bytes[i] == b'['
            && bytes[i + 1] == b'['
            && let Some(end_rel) = body[i + 2..].find("]]")
        {
            out.push(body[i + 2..i + 2 + end_rel].to_string());
            i = i + 2 + end_rel + 2;
            continue;
        }
        i += 1;
    }
    out
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::config::memory::discover_workspace_memory;
    use std::fs;
    use std::time;
    fn temp_root(label: &str) -> PathBuf {
        let unique = time::SystemTime::now()
            .duration_since(time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let root = env::temp_dir().join(format!("coyote-function-memory-{label}-{unique}"));
        fs::create_dir_all(&root).unwrap();
        root
    }
    #[test]
    fn extract_wikilinks_finds_all_pairs() {
        let body = "see [[alpha]] and [[bravo]] but not [single] or [[unclosed";
        assert_eq!(
            extract_wikilinks(body),
            vec!["alpha".to_string(), "bravo".to_string()]
        );
    }
    #[test]
    fn extract_wikilinks_handles_empty_and_no_links() {
        assert!(extract_wikilinks("").is_empty());
        assert!(extract_wikilinks("nothing here").is_empty());
    }
    #[test]
    fn ensure_index_entry_appends_when_missing() {
        let root = temp_root("index_append");
        let index = root.join("MEMORY.md");
        fs::write(&index, "# Memory Index\n\n- [[existing]]: already here\n").unwrap();
        let updated = ensure_index_entry(&index, "new_one", "newly added").unwrap();
        assert!(updated);
        let content = fs::read_to_string(&index).unwrap();
        assert!(content.contains("- [[existing]]: already here"));
        assert!(content.contains("- [[new_one]]: newly added"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn ensure_index_entry_skips_when_referenced() {
        let root = temp_root("index_skip");
        let index = root.join("MEMORY.md");
        let original = "# Memory Index\n\n- [[existing]]: already here\n";
        fs::write(&index, original).unwrap();
        let updated = ensure_index_entry(&index, "existing", "different description").unwrap();
        assert!(!updated);
        assert_eq!(fs::read_to_string(&index).unwrap(), original);
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn ensure_index_entry_creates_index_when_absent() {
        let root = temp_root("index_create");
        let index = root.join("memory").join("MEMORY.md");
        let updated = ensure_index_entry(&index, "first", "first ever").unwrap();
        assert!(updated);
        let content = fs::read_to_string(&index).unwrap();
        assert!(content.starts_with("# Memory Index"));
        assert!(content.contains("- [[first]]: first ever"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn workspace_write_dir_returns_structured_dir_directly() {
        let root = temp_root("ws_structured");
        let workspace = root.join("ws");
        let structured = workspace.join(".coyote").join("memory");
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join("MEMORY.md"), "idx").unwrap();
        let store = MemoryStore {
            global_dir: root.join("g"),
            workspace: discover_workspace_memory(&workspace),
        };
        let dir = workspace_write_dir(&store, &workspace).unwrap();
        assert_eq!(dir, structured);
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn workspace_write_dir_promotes_lite_to_structured_subdir() {
        let root = temp_root("ws_lite_promote");
        let workspace = root.join("ws");
        fs::create_dir_all(&workspace).unwrap();
        fs::write(workspace.join("COYOTE.md"), "lite").unwrap();
        let store = MemoryStore {
            global_dir: root.join("g"),
            workspace: discover_workspace_memory(&workspace),
        };
        let dir = workspace_write_dir(&store, &workspace).unwrap();
        assert_eq!(dir, workspace.join(".coyote").join("memory"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn workspace_write_dir_errors_when_no_workspace_and_no_git() {
        let root = temp_root("ws_none");
        let bare = root.join("nowhere");
        fs::create_dir_all(&bare).unwrap();
        let store = MemoryStore {
            global_dir: root.join("g"),
            workspace: discover_workspace_memory(&bare),
        };
        let err = workspace_write_dir(&store, &bare).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("no workspace memory discoverable"));
        assert!(msg.contains("coyote --init-memory workspace"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn workspace_write_dir_auto_bootstraps_inside_git_repo() {
        let root = temp_root("ws_bootstrap");
        let repo = root.join("repo");
        fs::create_dir_all(repo.join(".git")).unwrap();
        let nested = repo.join("src").join("deep");
        fs::create_dir_all(&nested).unwrap();
        let store = MemoryStore {
            global_dir: root.join("g"),
            workspace: discover_workspace_memory(&nested),
        };
        assert!(store.workspace.is_none());
        let dir = workspace_write_dir(&store, &nested).unwrap();
        assert_eq!(dir, repo.join(".coyote").join("memory"));
        assert!(dir.join("MEMORY.md").exists());
        let gi = fs::read_to_string(repo.join(".gitignore")).unwrap();
        assert!(gi.contains(".coyote/memory/"));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn find_file_returns_matching_file() {
        let root = temp_root("find_file");
        let workspace = root.join("ws");
        let structured = workspace.join(".coyote").join("memory");
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join("MEMORY.md"), "idx").unwrap();
        fs::write(
            structured.join("target.md"),
            "---\nname: target\n---\nfound me\n",
        )
        .unwrap();
        fs::write(
            structured.join("other.md"),
            "---\nname: other\n---\nignored\n",
        )
        .unwrap();
        let store = MemoryStore {
            global_dir: root.join("g"),
            workspace: discover_workspace_memory(&workspace),
        };
        let hit = find_file(&store, "target").unwrap();
        assert!(hit.is_some());
        assert_eq!(hit.unwrap().body.trim(), "found me");
        let miss = find_file(&store, "nope").unwrap();
        assert!(miss.is_none());
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn write_memory_index_creates_dir_and_writes_content() {
        let root = temp_root("write_index_create");
        let target = root.join("nested").join(".coyote").join("memory");
        let path =
            write_memory_index(&target, "# Workspace Memory Index\n\n- [[foo]]: hello\n").unwrap();
        assert_eq!(path, target.join("MEMORY.md"));
        assert!(path.exists());
        assert_eq!(
            fs::read_to_string(&path).unwrap(),
            "# Workspace Memory Index\n\n- [[foo]]: hello\n"
        );
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn write_memory_index_replaces_existing_content() {
        let root = temp_root("write_index_replace");
        fs::create_dir_all(&root).unwrap();
        let index = root.join("MEMORY.md");
        fs::write(&index, "# Old\n\n- [[stale]]: gone\n").unwrap();
        let path = write_memory_index(&root, "# New\n").unwrap();
        assert_eq!(path, index);
        assert_eq!(fs::read_to_string(&path).unwrap(), "# New\n");
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn lint_flags_orphans_broken_links_and_oversized() {
        let root = temp_root("lint");
        let workspace = root.join("ws");
        let structured = workspace.join(".coyote").join("memory");
        fs::create_dir_all(&structured).unwrap();
        fs::write(structured.join("MEMORY.md"), "- referenced\n").unwrap();
        fs::write(
            structured.join("referenced.md"),
            "---\nname: referenced\n---\nlinks to [[missing]] and [[also_missing]]\n",
        )
        .unwrap();
        fs::write(
            structured.join("orphan.md"),
            "---\nname: orphan\n---\nnot in the index\n",
        )
        .unwrap();
        let huge_body = "x".repeat(PER_FILE_SOFT_CAP + 100);
        fs::write(
            structured.join("huge.md"),
            format!("---\nname: huge\n---\n{huge_body}\n"),
        )
        .unwrap();
        let store = MemoryStore {
            global_dir: root.join("nonexistent_global"),
            workspace: discover_workspace_memory(&workspace),
        };
        let report = lint_memory(&store).unwrap();
        assert_eq!(report["total_files"], 3);
        let orphans = report["orphans"].as_array().unwrap();
        let orphan_names: Vec<&str> = orphans.iter().filter_map(|v| v.as_str()).collect();
        assert!(orphan_names.contains(&"orphan"));
        assert!(orphan_names.contains(&"huge"));
        assert!(!orphan_names.contains(&"referenced"));
        let broken = report["broken_wikilinks"].as_array().unwrap();
        let broken_targets: Vec<&str> = broken.iter().filter_map(|v| v["to"].as_str()).collect();
        assert!(broken_targets.contains(&"missing"));
        assert!(broken_targets.contains(&"also_missing"));
        let oversized = report["oversized"].as_array().unwrap();
        let oversized_names: Vec<&str> = oversized
            .iter()
            .filter_map(|v| v["name"].as_str())
            .collect();
        assert_eq!(oversized_names, vec!["huge"]);
        let _ = fs::remove_dir_all(&root);
    }
 }
@@ -1,3 +1,4 @@
 pub(crate) mod memory;
 pub(crate) mod skill;
 pub(crate) mod supervisor;
 pub(crate) mod todo;
@@ -19,9 +20,11 @@ use crate::parsers::{bash, python, typescript};
 use anyhow::{Context, Result, anyhow, bail};
 use indexmap::IndexMap;
 use indoc::formatdoc;
 use memory::MEMORY_FUNCTION_PREFIX;
 use rust_embed::Embed;
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use skill::SKILL_FUNCTION_PREFIX;
 use std::collections::VecDeque;
 use std::ffi::OsStr;
 use std::fs::File;
@@ -33,7 +36,6 @@ use std::{
    process::{Command, Stdio},
 };
 use strum_macros::AsRefStr;
 use skill::SKILL_FUNCTION_PREFIX;
 use supervisor::SUPERVISOR_FUNCTION_PREFIX;
 use todo::TODO_FUNCTION_PREFIX;
 use user_interaction::USER_FUNCTION_PREFIX;
@@ -355,6 +357,21 @@ impl Functions {
        self.declarations.extend(todo::todo_function_declarations());
    }
    pub fn remove_todo_functions(&mut self) {
        self.declarations
            .retain(|f| !f.name.starts_with(TODO_FUNCTION_PREFIX));
    }
    pub fn append_memory_functions(&mut self) {
        self.declarations
            .extend(memory::memory_function_declarations());
    }
    pub fn remove_memory_functions(&mut self) {
        self.declarations
            .retain(|f| !f.name.starts_with(MEMORY_FUNCTION_PREFIX));
    }
    pub fn append_skill_functions(&mut self) {
        self.declarations
            .extend(skill::skill_function_declarations());
@@ -1046,6 +1063,13 @@ impl ToolCall {
                    json!({"tool_call_error": error_msg})
                })
            }
            _ if cmd_name.starts_with(MEMORY_FUNCTION_PREFIX) => {
                memory::handle_memory_tool(ctx, &cmd_name, &json_data).unwrap_or_else(|e| {
                    let error_msg = format!("Memory tool failed: {e}");
                    eprintln!("{}", warning_text(&format!("⚠️ {error_msg} ⚠️")));
                    json!({"tool_call_error": error_msg})
                })
            }
            _ if cmd_name.starts_with(SKILL_FUNCTION_PREFIX) => {
                skill::handle_skill_tool(ctx, &cmd_name, &json_data)
                    .await
@@ -1268,11 +1292,13 @@ pub fn run_llm_function(
        let mut buffer = [0; 1024];
        let mut reader = stdout;
        let mut out = io::stdout();
        let mut buf = Vec::new();
        while let Ok(n) = reader.read(&mut buffer) {
            if n == 0 {
                break;
            }
            let chunk = &buffer[0..n];
            buf.extend_from_slice(chunk);
            let mut last_pos = 0;
            for (i, &byte) in chunk.iter().enumerate() {
                if byte == b'\n' {
@@ -1286,6 +1312,7 @@ pub fn run_llm_function(
            }
            let _ = out.flush();
        }
        buf
    });
    let stderr_thread = std::thread::spawn(move || {
@@ -1318,18 +1345,22 @@ pub fn run_llm_function(
    let status = child
        .wait()
        .map_err(|err| anyhow!("Unable to run {command_name}, {err}"))?;
-    let _ = stdout_thread.join();
+    let stdout_bytes = stdout_thread.join().unwrap_or_default();
    let stderr_bytes = stderr_thread.join().unwrap_or_default();
    let exit_code = status.code().unwrap_or_default();
    if exit_code != 0 {
        let stderr = String::from_utf8_lossy(&stderr_bytes).trim().to_string();
        let stdout = String::from_utf8_lossy(&stdout_bytes).trim().to_string();
        let tool_error_message = format!("Tool call '{command_name}' exited with code {exit_code}");
        eprintln!("{}", warning_text(&format!("⚠️ {tool_error_message} ⚠️")));
        let mut error_json = json!({"tool_call_error": tool_error_message});
        if !stderr.is_empty() {
            error_json["stderr"] = json!(stderr);
        }
        if !stdout.is_empty() {
            error_json["stdout"] = json!(stdout);
        }
        debug!("Tool call error: {error_json:?}");
        return Ok(Some(error_json.to_string()));
    }
@@ -14,9 +14,11 @@ pub fn skill_function_declarations() -> Vec<FunctionDeclaration> {
        FunctionDeclaration {
            name: format!("{SKILL_FUNCTION_PREFIX}list"),
            description:
-                "List skills available in this context. Returns each skill's name, description, \
+                "List skills available in this context. Call this early in any non-trivial task to \
-                 what tools and MCP servers it grants on load, and whether it is currently loaded. \
+                 discover specialized skills that may apply to the work before deciding on an \
-                 Call this to discover skills before using skill__load."
+                 approach. Returns each skill's name, description, what tools and MCP servers it \
                 grants on load, and whether it is currently loaded. Pair with `skill__load` to \
                 activate the skills you choose."
                    .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
@@ -28,9 +30,10 @@ pub fn skill_function_declarations() -> Vec<FunctionDeclaration> {
        FunctionDeclaration {
            name: format!("{SKILL_FUNCTION_PREFIX}load"),
            description:
-                "Load a skill module into the current context. The skill's instructions and any \
+                "Load a skill module into the current context after confirming via `skill__list` \
-                 tools or MCP servers it grants become active for subsequent turns. Call \
+                 that it applies to the task at hand. The skill's instructions and any tools or \
-                 skill__unload when the skill's work is complete to keep the context lean."
+                 MCP servers it grants become active for subsequent turns. Call `skill__unload` \
                 when the skill's work is complete to keep the context lean."
                    .to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
@@ -102,12 +105,14 @@ pub async fn handle_skill_tool(
 }
 fn handle_list(ctx: &RequestContext, policy: &SkillPolicy) -> Result<Value> {
-    let function_calling_on = ctx.app.config.function_calling_support;
+    let visible_names: Vec<String> = match ctx.app.config.visible_skills.as_deref() {
-    let mcp_on = ctx.app.config.mcp_server_support;
+        Some(list) => list.to_vec(),
        None => paths::list_skills(),
    };
    let mut entries = Vec::new();
-    for name in paths::list_skills() {
+    for name in visible_names {
-        if !policy.allows(&name) {
+        if !policy.compatible_enabled.contains(&name) {
            continue;
        }
@@ -118,18 +123,12 @@ fn handle_list(ctx: &RequestContext, policy: &SkillPolicy) -> Result<Value> {
                continue;
            }
        };
        if !skill.is_compatible(function_calling_on, mcp_on) {
            warn!(
                "Skill '{name}' filtered from list: declares tools or MCP servers but those features are disabled"
            );
            continue;
        }
        entries.push(json!({
            "name": skill.name(),
            "description": skill.description(),
-            "grants_tools": csv_to_vec(skill.enabled_tools()),
+            "grants_tools": skill.enabled_tools().unwrap_or_default(),
-            "grants_mcp_servers": csv_to_vec(skill.enabled_mcp_servers()),
+            "grants_mcp_servers": skill.enabled_mcp_servers().unwrap_or_default(),
            "loaded": ctx.skill_registry.is_loaded(skill.name()),
        }));
    }
@@ -167,11 +166,11 @@ async fn handle_load(
    let tools_declared = skill
        .enabled_tools()
-        .map(|s| !s.trim().is_empty())
+        .map(|v| !v.is_empty())
        .unwrap_or(false);
    let mcps_declared = skill
        .enabled_mcp_servers()
-        .map(|s| !s.trim().is_empty())
+        .map(|v| !v.is_empty())
        .unwrap_or(false);
    if tools_declared && !function_calling_on {
@@ -194,7 +193,10 @@ async fn handle_load(
    }
    if let Err(e) = ctx.refresh_tool_scope(create_abort_signal()).await {
-        let _ = ctx.skill_registry.unload(name);
+        if let Err(unload_err) = ctx.skill_registry.unload(name) {
            warn!("Failed to unload skill '{name}' during error recovery: {unload_err}");
        }
        return Ok(json!({
            "error": format!("Loaded skill '{name}' but failed to refresh tool scope: {e}")
        }));
@@ -213,12 +215,25 @@ async fn handle_unload(ctx: &mut RequestContext, args: &Value) -> Result<Value>
        _ => return Ok(json!({"error": "name is required"})),
    };
-    if let Err(e) = ctx.skill_registry.unload(name) {
+    if let Err(e) = paths::validate_skill_name(name) {
        return Ok(json!({"error": e.to_string()}));
    }
    let skill = match ctx.skill_registry.unload(name) {
        Ok(s) => s,
        Err(e) => return Ok(json!({"error": e.to_string()})),
    };
    if let Err(e) = ctx.refresh_tool_scope(create_abort_signal()).await {
-        warn!("Unloaded skill '{name}' but failed to refresh tool scope: {e}");
+        if let Err(insert_err) = ctx.skill_registry.insert(skill) {
            warn!("Failed to restore skill '{name}' after unload recovery: {insert_err}");
        }
        return Ok(json!({
            "error": format!(
                "Unloaded skill '{name}' but failed to refresh tool scope; restored: {e}"
            )
        }));
    }
    Ok(json!({
@@ -227,16 +242,6 @@ async fn handle_unload(ctx: &mut RequestContext, args: &Value) -> Result<Value>
    }))
 }
 fn csv_to_vec(csv: Option<&str>) -> Vec<String> {
    csv.map(|raw| {
        raw.split(',')
            .map(|t| t.trim().to_string())
            .filter(|t| !t.is_empty())
            .collect()
    })
    .unwrap_or_default()
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -294,18 +299,4 @@ mod tests {
        assert!(required, "skill__list should have no required parameters");
    }
    #[test]
    fn csv_to_vec_empty_input() {
        assert!(csv_to_vec(None).is_empty());
        assert!(csv_to_vec(Some("")).is_empty());
        assert!(csv_to_vec(Some("   ")).is_empty());
    }
    #[test]
    fn csv_to_vec_parses_and_trims() {
        let v = csv_to_vec(Some("a, b ,c,, d"));
        assert_eq!(v, vec!["a", "b", "c", "d"]);
    }
 }
@@ -3,7 +3,7 @@ use crate::client::{Model, ModelType, call_chat_completions};
 use crate::config::{Agent, AppState, Input, RequestContext, Role, RoleLike};
 use crate::supervisor::mailbox::{Envelope, EnvelopePayload, Inbox};
 use crate::supervisor::{AgentExitStatus, AgentHandle, AgentResult, Supervisor};
-use crate::utils::{AbortSignal, create_abort_signal};
+use crate::utils::{AbortSignal, create_abort_signal, wait_abort_signal};
 use crate::graph;
 use anyhow::{Context, Result, anyhow, bail};
@@ -16,10 +16,69 @@ use std::pin::Pin;
 use std::sync::Arc;
 use std::time::Duration;
 use tokio::time;
 use tokio::time::Instant;
 use uuid::Uuid;
 pub const SUPERVISOR_FUNCTION_PREFIX: &str = "agent__";
 pub const PENDING_AGENTS_GUARDRAIL_MAX: u32 = 3;
 pub enum GuardrailAction {
    NoAction,
    Inject(String),
    ForceTerminate(Vec<String>),
 }
 pub fn pending_agent_ids(ctx: &RequestContext) -> Vec<String> {
    let Some(sup) = ctx.supervisor.as_ref() else {
        return Vec::new();
    };
    let sup = sup.read();
    sup.list_agents()
        .into_iter()
        .filter_map(|(id, _)| match sup.is_finished(id) {
            Some(false) => Some(id.to_string()),
            _ => None,
        })
        .collect()
 }
 pub fn build_pending_agents_guardrail_prompt(ids: &[String]) -> String {
    let count = ids.len();
    let id_list = ids
        .iter()
        .map(|id| format!("- {id}"))
        .collect::<Vec<_>>()
        .join("\n");
    format!(
        "[SYSTEM GUARDRAIL] You attempted to end your turn while {count} spawned background agent(s) \
         are still running:\n{id_list}\n\nThese agents will be abandoned if your turn ends now. You MUST \
         reclaim each one before ending your turn. For each agent: call `agent__collect` (blocks until \
         done, returns output) or `agent__cancel` (discards). Do NOT emit a text-only response \
         expecting them to 'report back' — they will not."
    )
 }
 pub fn check_pending_agents_guardrail(ctx: &mut RequestContext) -> GuardrailAction {
    let pending = pending_agent_ids(ctx);
    if pending.is_empty() {
        ctx.pending_agents_guardrail_count = 0;
        return GuardrailAction::NoAction;
    }
    if ctx.pending_agents_guardrail_count >= PENDING_AGENTS_GUARDRAIL_MAX {
        if let Some(sup) = ctx.supervisor.as_ref().cloned() {
            sup.read().cancel_recursive();
        }
        ctx.pending_agents_guardrail_count = 0;
        return GuardrailAction::ForceTerminate(pending);
    }
    ctx.pending_agents_guardrail_count += 1;
    GuardrailAction::Inject(build_pending_agents_guardrail_prompt(&pending))
 }
 pub fn escalation_function_declarations() -> Vec<FunctionDeclaration> {
    vec![FunctionDeclaration {
        name: format!("{SUPERVISOR_FUNCTION_PREFIX}reply_escalation"),
@@ -55,7 +114,11 @@ pub fn supervisor_function_declarations() -> Vec<FunctionDeclaration> {
    vec![
        FunctionDeclaration {
            name: format!("{SUPERVISOR_FUNCTION_PREFIX}spawn"),
-            description: "Spawn a subagent to run in the background. Returns a task_id for tracking. The agent runs in parallel. You can continue working while it executes.".to_string(),
+            description: "Spawn a subagent to run in the background. Returns an `id` immediately so you can continue \
                          working in parallel. CRITICAL: every spawned agent MUST be reclaimed before you end your \
                          turn — call `agent__collect` to retrieve its output, or `agent__cancel` if you no longer \
                          need it. Ending your turn with pending agents will abandon their work and the system will \
                          reject the turn-end.".to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([
@@ -109,7 +172,11 @@ pub fn supervisor_function_declarations() -> Vec<FunctionDeclaration> {
        },
        FunctionDeclaration {
            name: format!("{SUPERVISOR_FUNCTION_PREFIX}collect"),
-            description: "Wait for a spawned agent to finish and return its result. Blocks until the agent completes.".to_string(),
+            description: "Block until the named spawned agent finishes and return its result. This is your primary \
                          wait primitive — it pauses your execution until the agent completes (or you are interrupted). \
                          Call this for every agent you spawned before ending your turn. Do NOT end your turn assuming \
                          agents will 'report back later' — they will not; they will be abandoned. If you no longer \
                          need an agent's result, call `agent__cancel` instead.".to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([(
@@ -137,7 +204,10 @@ pub fn supervisor_function_declarations() -> Vec<FunctionDeclaration> {
        },
        FunctionDeclaration {
            name: format!("{SUPERVISOR_FUNCTION_PREFIX}cancel"),
-            description: "Cancel a running subagent by its ID.".to_string(),
+            description: "Cancel a running subagent by its ID. Use this when an agent's output is no longer needed \
                          (e.g. you changed direction, or you're about to end your turn and don't want to wait). \
                          Cancellation cascades: all of the cancelled agent's own descendants are also cancelled. This \
                          call waits briefly for the agent to actually finish cleanup before returning.".to_string(),
            parameters: JsonSchema {
                type_value: Some("object".to_string()),
                properties: Some(IndexMap::from([(
@@ -315,7 +385,7 @@ pub async fn handle_supervisor_tool(
        "check" => handle_check(ctx, args).await,
        "collect" => handle_collect(ctx, args).await,
        "list" => handle_list(ctx),
-        "cancel" => handle_cancel(ctx, args),
+        "cancel" => handle_cancel(ctx, args).await,
        "send_message" => handle_send_message(ctx, args),
        "check_inbox" => handle_check_inbox(ctx),
        "task_create" => handle_task_create(ctx, args),
@@ -370,14 +440,28 @@ pub fn run_child_agent(
            }
            if tool_results.is_empty() {
                match check_pending_agents_guardrail(&mut child_ctx) {
                    GuardrailAction::NoAction => break,
                    GuardrailAction::ForceTerminate(ids) => {
                        log::warn!(
                            "Pending-agent guardrail force-cancelled {} agent(s) after max reminders: {:?}",
                            ids.len(),
                            ids
                        );
                        break;
                    }
                    GuardrailAction::Inject(prompt) => {
                        input = Input::from_str(&child_ctx, &prompt, None)?;
                        continue;
                    }
                }
            }
            input = input.merge_tool_results(output, tool_results);
        }
        if let Some(supervisor) = child_ctx.supervisor.clone() {
-            supervisor.read().cancel_all();
+            supervisor.read().cancel_recursive();
        }
        Ok(accumulated_output)
@@ -469,7 +553,7 @@ pub async fn run_agent_for_graph(
        child_ctx.init_agent_shared_variables()?;
    }
-    let input = Input::from_str(&child_ctx, prompt, None);
+    let input = Input::from_str(&child_ctx, prompt, None)?;
    debug!("Spawning agent '{agent_name}' for graph node as '{agent_id}'");
@@ -635,13 +719,14 @@ async fn handle_spawn(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
        child_ctx.init_agent_shared_variables()?;
    }
-    let input = Input::from_str(&child_ctx, &prompt, None);
+    let input = Input::from_str(&child_ctx, &prompt, None)?;
    debug!("Spawning child agent '{agent_name}' as '{agent_id}'");
    let spawn_agent_id = agent_id.clone();
    let spawn_agent_name = agent_name.clone();
    let spawn_abort = child_abort.clone();
    let child_supervisor = child_ctx.supervisor.clone();
    let join_handle = tokio::spawn(async move {
        let result = run_child_agent(child_ctx, input, spawn_abort).await;
@@ -669,6 +754,7 @@ async fn handle_spawn(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
        inbox: child_inbox,
        abort_signal: child_abort,
        join_handle,
        child_supervisor,
    };
    let supervisor = ctx
@@ -683,7 +769,11 @@ async fn handle_spawn(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
        "status": "ok",
        "id": agent_id,
        "agent": agent_name,
-        "message": format!("Agent '{agent_name}' spawned as '{agent_id}'. Use agent__check or agent__collect to get results."),
+        "message": format!("Agent '{agent_name}' spawned as '{agent_id}' and is running in the background. CRITICAL: \
                           you MUST reclaim this agent before ending your turn — call `agent__collect` (blocks until \
                           done, returns output) or `agent__cancel` (if you no longer need it). Ending your turn with \
                           unreclaimed agents will be rejected and forces you to handle them. Do NOT assume the agent \
                           will 'report back' on its own."),
    }))
 }
@@ -743,7 +833,7 @@ async fn handle_collect(ctx: &mut RequestContext, args: &Value) -> Result<Value>
        .cloned()
        .ok_or_else(|| anyhow!("No supervisor active"))?;
-    {
+    let target_abort = {
        let sup = supervisor.read();
        if sup.is_finished(id).is_none() {
            return Ok(json!({
@@ -751,7 +841,8 @@ async fn handle_collect(ctx: &mut RequestContext, args: &Value) -> Result<Value>
                "message": format!("Agent '{id}' not found. Use agent__check to verify it exists and is finished.")
            }));
        }
-    }
+        sup.abort_signal_for(id)
    };
    loop {
        let is_finished = {
@@ -775,8 +866,28 @@ async fn handle_collect(ctx: &mut RequestContext, args: &Value) -> Result<Value>
            }));
        }
        match target_abort.as_ref() {
            Some(abort) if abort.aborted() => {
                let deadline = Instant::now() + Duration::from_secs(2);
                while Instant::now() < deadline {
                    if supervisor.read().is_finished(id).unwrap_or(false) {
                        break;
                    }
                    time::sleep(Duration::from_millis(50)).await;
                }
                break;
            }
            Some(abort) => {
                tokio::select! {
                    _ = time::sleep(Duration::from_millis(200)) => {}
                    _ = wait_abort_signal(abort) => {}
                }
            }
            None => {
                time::sleep(Duration::from_millis(200)).await;
            }
        }
    }
    let handle = {
        let mut sup = supervisor.write();
@@ -792,6 +903,7 @@ async fn handle_collect(ctx: &mut RequestContext, args: &Value) -> Result<Value>
                .map_err(|e| anyhow!("Agent failed: {e}"))?;
            let output = summarize_output(ctx, &result.agent_name, &result.output).await?;
            ctx.pending_agents_guardrail_count = 0;
            Ok(json!({
                "status": "completed",
@@ -836,7 +948,7 @@ fn handle_list(ctx: &mut RequestContext) -> Result<Value> {
    }))
 }
-fn handle_cancel(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
+async fn handle_cancel(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
    let id = args
        .get("id")
        .and_then(Value::as_str)
@@ -847,14 +959,34 @@ fn handle_cancel(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
        .as_ref()
        .cloned()
        .ok_or_else(|| anyhow!("No supervisor active"))?;
    let mut sup = supervisor.write();
-    match sup.take(id) {
+    let handle = {
        let mut sup = supervisor.write();
        sup.take(id)
    };
    match handle {
        Some(handle) => {
            let agent_name = handle.agent_name.clone();
            if let Some(child_sup) = handle.child_supervisor.as_ref() {
                child_sup.read().cancel_recursive();
            }
            handle.abort_signal.set_ctrlc();
            let cleanup = tokio::time::timeout(Duration::from_secs(5), handle.join_handle).await;
            ctx.pending_agents_guardrail_count = 0;
            let message = match cleanup {
                Ok(_) => format!("Cancelled agent '{agent_name}' and waited for cleanup."),
                Err(_) => format!(
                    "Cancelled agent '{agent_name}'; cleanup did not complete within 5s. Its descendants have been signalled and will tear down asynchronously."
                ),
            };
            Ok(json!({
                "status": "ok",
-                "message": format!("Cancelled agent '{}'", handle.agent_name),
+                "message": message,
            }))
        }
        None => Ok(json!({
@@ -1228,7 +1360,7 @@ async fn summarize_output(ctx: &RequestContext, agent_name: &str, output: &str)
        "Summarize the following sub-agent output from '{}':\n\n{}",
        agent_name, output
    );
-    let input = Input::from_str(ctx, &user_message, Some(role));
+    let input = Input::from_str(ctx, &user_message, Some(role))?;
    let summary = input.fetch_chat_text().await?;
@@ -1283,6 +1415,7 @@ mod tests {
            inbox: Arc::new(Inbox::new()),
            abort_signal: create_abort_signal(),
            join_handle,
            child_supervisor: None,
        };
        ctx.supervisor
            .as_ref()
@@ -1362,6 +1495,7 @@ mod tests {
                inbox,
                abort_signal: abort,
                join_handle,
                child_supervisor: None,
            };
            ctx.supervisor
                .as_ref()
@@ -1381,7 +1515,7 @@ mod tests {
    fn handle_cancel_registered_agent() {
        let mut ctx = ctx_with_supervisor(4, 3);
        register_fake_agent(&mut ctx, "a1", "explore");
-        let result = handle_cancel(&mut ctx, &json!({"id": "a1"})).unwrap();
+        let result = run_async(handle_cancel(&mut ctx, &json!({"id": "a1"}))).unwrap();
        assert_eq!(result["status"], "ok");
        assert_eq!(ctx.supervisor.as_ref().unwrap().read().active_count(), 0);
    }
@@ -1389,14 +1523,14 @@ mod tests {
    #[test]
    fn handle_cancel_unknown_agent() {
        let mut ctx = ctx_with_supervisor(4, 3);
-        let result = handle_cancel(&mut ctx, &json!({"id": "missing"})).unwrap();
+        let result = run_async(handle_cancel(&mut ctx, &json!({"id": "missing"}))).unwrap();
        assert_eq!(result["status"], "error");
    }
    #[test]
    fn handle_cancel_no_supervisor_errors() {
        let mut ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
-        let result = handle_cancel(&mut ctx, &json!({"id": "x"}));
+        let result = run_async(handle_cancel(&mut ctx, &json!({"id": "x"})));
        assert!(result.is_err());
    }
@@ -2,9 +2,15 @@ use super::state::StateManager;
 use super::structured;
 use super::types::LlmNode;
 use crate::client::{Model, ModelType, call_chat_completions};
-use crate::config::{Input, RequestContext, Role, RoleLike};
+use crate::config::prompts::DEFAULT_SKILL_INSTRUCTIONS;
 use crate::config::{
    Input, RequestContext, Role, RoleLike, SkillPolicy, should_inject_skill_instructions,
 };
 use crate::function::skill::skill_function_declarations;
 use crate::function::supervisor::{GuardrailAction, check_pending_agents_guardrail};
 use crate::utils::create_abort_signal;
 use anyhow::{Context, Error, Result, anyhow, bail};
 use log::warn;
 use serde_json::Value;
 use std::collections::HashSet;
 use std::sync::Arc;
@@ -105,7 +111,7 @@ async fn run(
    let (regular_tools, mcp_servers) = categorize_tools(node.tools.as_deref());
    validate_tools_subset(&regular_tools, &mcp_servers, parent_ctx)?;
-    let role = build_inline_role(
+    let mut role = build_inline_role(
        node,
        instructions.as_deref(),
        &regular_tools,
@@ -113,8 +119,60 @@ async fn run(
        parent_ctx,
    )?;
    let saved_agent_skill_state = swap_in_node_skill_policy(node, parent_ctx);
    let policy = match SkillPolicy::effective(
        &parent_ctx.app.config,
        parent_ctx.role.as_ref(),
        parent_ctx.agent.as_ref(),
        parent_ctx.session.as_ref(),
    ) {
        Ok(p) => p,
        Err(e) => {
            restore_agent_skill_policy(parent_ctx, saved_agent_skill_state);
            return Err(e);
        }
    };
    if policy.skills_enabled {
        let mut tools = role.enabled_tools().map(|v| v.to_vec()).unwrap_or_default();
        for decl in skill_function_declarations() {
            if !tools.contains(&decl.name) {
                tools.push(decl.name);
            }
        }
        role.set_enabled_tools(Some(tools));
    }
    if should_inject_skill_instructions(&parent_ctx.app.config, &policy) {
        let app = &parent_ctx.app.config;
        let agent = parent_ctx.agent.as_ref();
        let inject = node
            .inject_skill_instructions
            .or_else(|| agent.map(|a| a.inject_skill_instructions()))
            .unwrap_or(app.inject_skill_instructions);
        if inject {
            let instructions = node
                .skill_instructions
                .clone()
                .or_else(|| agent.and_then(|a| a.skill_instructions_value()))
                .or_else(|| app.skill_instructions.clone());
            let separator = if role.is_empty_prompt() { "" } else { "\n\n" };
            role.append_to_prompt(separator);
            role.append_to_prompt(
                instructions
                    .as_deref()
                    .unwrap_or(DEFAULT_SKILL_INSTRUCTIONS),
            );
        }
    }
    let composed_role = parent_ctx.skill_registry.effective_role(&role, &policy);
    let saved_role = parent_ctx.role.clone();
-    parent_ctx.role = Some(role);
+    parent_ctx.role = Some(composed_role);
    let result = match node.timeout {
        Some(secs) => match timeout(
            Duration::from_secs(secs),
@@ -128,9 +186,46 @@ async fn run(
        None => run_with_retries(node, &prompt, parent_ctx).await,
    };
    parent_ctx.role = saved_role;
    restore_agent_skill_policy(parent_ctx, saved_agent_skill_state);
    result
 }
 struct SavedAgentSkillPolicy {
    skills_enabled: Option<bool>,
    enabled_skills: Option<Vec<String>>,
 }
 fn swap_in_node_skill_policy(
    node: &LlmNode,
    ctx: &mut RequestContext,
 ) -> Option<SavedAgentSkillPolicy> {
    let agent = ctx.agent.as_mut()?;
    let saved = SavedAgentSkillPolicy {
        skills_enabled: agent.skills_enabled(),
        enabled_skills: agent.enabled_skills().map(|s| s.to_vec()),
    };
    if let Some(b) = node.skills_enabled {
        agent.set_skills_enabled(Some(b));
    }
    if let Some(names) = &node.enabled_skills {
        agent.set_enabled_skills(Some(names.clone()));
    }
    Some(saved)
 }
 fn restore_agent_skill_policy(ctx: &mut RequestContext, saved: Option<SavedAgentSkillPolicy>) {
    let Some(saved) = saved else { return };
    let Some(agent) = ctx.agent.as_mut() else {
        return;
    };
    agent.set_skills_enabled(saved.skills_enabled);
    agent.set_enabled_skills(saved.enabled_skills);
 }
 async fn run_with_retries(
    node: &LlmNode,
    prompt: &str,
@@ -154,7 +249,7 @@ async fn run_chat_loop(node: &LlmNode, prompt: &str, ctx: &mut RequestContext) -
    let abort = create_abort_signal();
    let app_cfg = Arc::clone(&ctx.app.config);
    let role_for_input = ctx.role.clone();
-    let mut input = Input::from_str(ctx, prompt, role_for_input);
+    let mut input = Input::from_str(ctx, prompt, role_for_input)?;
    let mut accumulated = String::new();
    for turn in 0..node.max_iterations {
@@ -173,8 +268,29 @@ async fn run_chat_loop(node: &LlmNode, prompt: &str, ctx: &mut RequestContext) -
        }
        if tool_results.is_empty() {
            match check_pending_agents_guardrail(ctx) {
                GuardrailAction::NoAction => return Ok(accumulated),
                GuardrailAction::ForceTerminate(ids) => {
                    warn!(
                        "Pending-agent guardrail force-cancelled {} agent(s) after max reminders: {:?}",
                        ids.len(),
                        ids
                    );
                    return Ok(accumulated);
                }
                GuardrailAction::Inject(prompt) => {
                    if turn + 1 == node.max_iterations {
                        bail!(
                            "llm node hit max_iterations ({}) before LLM concluded",
                            node.max_iterations
                        );
                    }
                    let role = ctx.role.clone();
                    input = Input::from_str(ctx, &prompt, role)?;
                    continue;
                }
            }
        }
        if turn + 1 == node.max_iterations {
            bail!(
@@ -215,18 +331,18 @@ fn build_inline_role(
    }
    if node.tools.as_deref().unwrap_or_default().is_empty() {
-        role.set_enabled_tools(Some(String::new()));
+        role.set_enabled_tools(Some(Vec::new()));
-        role.set_enabled_mcp_servers(Some(String::new()));
+        role.set_enabled_mcp_servers(Some(Vec::new()));
    } else {
        if !regular_tools.is_empty() {
-            role.set_enabled_tools(Some(regular_tools.join(",")));
+            role.set_enabled_tools(Some(regular_tools.to_vec()));
        } else {
-            role.set_enabled_tools(Some(String::new()));
+            role.set_enabled_tools(Some(Vec::new()));
        }
        if !mcp_servers.is_empty() {
-            role.set_enabled_mcp_servers(Some(mcp_servers.join(",")));
+            role.set_enabled_mcp_servers(Some(mcp_servers.to_vec()));
        } else {
-            role.set_enabled_mcp_servers(Some(String::new()));
+            role.set_enabled_mcp_servers(Some(Vec::new()));
        }
    }
@@ -389,6 +505,10 @@ mod tests {
            state_updates: updates,
            output_schema: None,
            timeout: None,
            skills_enabled: None,
            enabled_skills: None,
            inject_skill_instructions: None,
            skill_instructions: None,
        }
    }
@@ -55,8 +55,8 @@ async fn extract_via_extractor(
 fn build_extractor_role() -> Result<Role> {
    let mut role = Role::new(EXTRACTOR_ROLE_NAME, EXTRACTOR_ROLE_PROMPT);
-    role.set_enabled_tools(Some(String::new()));
+    role.set_enabled_tools(Some(Vec::new()));
-    role.set_enabled_mcp_servers(Some(String::new()));
+    role.set_enabled_mcp_servers(Some(Vec::new()));
    Ok(role)
 }
@@ -76,7 +76,7 @@ async fn run_one_shot(prompt: &str, ctx: &mut RequestContext) -> Result<String>
    let abort = create_abort_signal();
    let app_cfg = Arc::clone(&ctx.app.config);
    let role_for_input = ctx.role.clone();
-    let input = Input::from_str(ctx, prompt, role_for_input);
+    let input = Input::from_str(ctx, prompt, role_for_input)?;
    let client = input.create_client()?;
    ctx.before_chat_completion(&input)?;
    let (output, tool_results) =
@@ -183,7 +183,7 @@ mod tests {
    fn build_extractor_role_disables_tools_and_mcp() {
        let role = build_extractor_role().expect("builtin role must exist");
-        assert_eq!(role.enabled_tools().as_deref(), Some(""));
+        assert_eq!(role.enabled_tools().as_deref(), Some([].as_slice()));
-        assert_eq!(role.enabled_mcp_servers().as_deref(), Some(""));
+        assert_eq!(role.enabled_mcp_servers().as_deref(), Some([].as_slice()));
    }
 }
@@ -31,6 +31,18 @@ pub struct Graph {
    #[serde(default)]
    pub mcp_servers: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub skills_enabled: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled_skills: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub inject_skill_instructions: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub skill_instructions: Option<String>,
    #[serde(default)]
    pub conversation_starters: Vec<String>,
@@ -293,6 +305,18 @@ pub struct LlmNode {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub skills_enabled: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled_skills: Option<Vec<String>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub inject_skill_instructions: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub skill_instructions: Option<String>,
 }
 fn default_llm_max_attempts() -> u32 {
@@ -93,6 +93,7 @@ impl AgentValidationContext {
 pub struct GraphValidator {
    base_dir: PathBuf,
    agent_ctx: Option<AgentValidationContext>,
    skill_exists: fn(&str) -> bool,
 }
 impl GraphValidator {
@@ -100,6 +101,7 @@ impl GraphValidator {
        Self {
            base_dir: base_dir.into(),
            agent_ctx: None,
            skill_exists: paths::has_skill,
        }
    }
@@ -108,6 +110,12 @@ impl GraphValidator {
        self
    }
    #[cfg(test)]
    pub fn with_skill_exists(mut self, f: fn(&str) -> bool) -> Self {
        self.skill_exists = f;
        self
    }
    pub fn validate(&self, graph: &Graph) -> ValidationResult {
        let mut result = ValidationResult::default();
        self.validate_node_references(graph, &mut result);
@@ -119,6 +127,7 @@ impl GraphValidator {
        self.validate_approval_routes(graph, &mut result);
        self.validate_rag_nodes(graph, &mut result);
        self.validate_llm_nodes(graph, &mut result);
        self.validate_llm_skills(graph, &mut result);
        self.validate_max_concurrency(graph, &mut result);
        self.validate_map_branches(graph, &mut result);
        self.validate_parallel_user_interaction(graph, &mut result);
@@ -189,6 +198,98 @@ impl GraphValidator {
        }
    }
    fn validate_llm_skills(&self, graph: &Graph, result: &mut ValidationResult) {
        let visible_skills = self
            .agent_ctx
            .as_ref()
            .and_then(|c| c.app_config.visible_skills.as_deref());
        let skill_exists = self.skill_exists;
        let has_agent_ctx = self.agent_ctx.is_some();
        let check_visibility = |name: &str| -> Option<String> {
            if !has_agent_ctx {
                return None;
            }
            match visible_skills {
                Some(list) if !list.iter().any(|s| s == name) => Some(format!(
                    "'{name}' is not in the global 'visible_skills' allow-list"
                )),
                None if !skill_exists(name) => Some(format!("'{name}' is not installed")),
                _ => None,
            }
        };
        if let Some(graph_skills) = &graph.enabled_skills {
            for name in graph_skills {
                if name.trim().is_empty() {
                    result.error(ValidationError::new(
                        "graph 'enabled_skills' contains an empty skill name",
                    ));
                    continue;
                }
                if let Err(e) = paths::validate_skill_name(name) {
                    result.error(ValidationError::new(format!(
                        "graph 'enabled_skills' contains an invalid skill name: '{name}': {e}"
                    )));
                    continue;
                }
                if let Some(reason) = check_visibility(name) {
                    result.error(ValidationError::new(format!(
                        "graph 'enabled_skills': {reason}"
                    )));
                }
            }
        }
        for (node_id, node) in &graph.nodes {
            let NodeType::Llm(llm) = &node.node_type else {
                continue;
            };
            let Some(node_skills) = &llm.enabled_skills else {
                continue;
            };
            for name in node_skills {
                if name.trim().is_empty() {
                    result.error(ValidationError::with_node(
                        node_id,
                        "llm node 'enabled_skills' contains an empty skill name",
                    ));
                    continue;
                }
                if let Err(e) = paths::validate_skill_name(name) {
                    result.error(ValidationError::with_node(
                        node_id,
                        format!(
                        "llm node 'enabled_skills' contains an invalid skill name: '{name}': {e}"
                    )));
                    continue;
                }
                if let Some(reason) = check_visibility(name) {
                    result.error(ValidationError::with_node(
                        node_id,
                        format!("llm node 'enabled_skills': {reason}"),
                    ));
                    continue;
                }
                if let Some(graph_skills) = &graph.enabled_skills
                    && !graph_skills.iter().any(|g| g == name)
                {
                    result.error(ValidationError::with_node(
                        node_id,
                        format!(
                            "llm node 'enabled_skills' references '{name}' which is not in \
                             graph-level 'enabled_skills' ({})",
                            graph_skills.join(", ")
                        ),
                    ));
                }
            }
        }
    }
    fn validate_node_references(&self, graph: &Graph, result: &mut ValidationResult) {
        for (node_id, node) in &graph.nodes {
            for (target, label) in declared_targets(node) {
@@ -847,6 +948,10 @@ mod tests {
            top_p: None,
            global_tools: Vec::new(),
            mcp_servers: Vec::new(),
            skills_enabled: None,
            enabled_skills: None,
            inject_skill_instructions: None,
            skill_instructions: None,
            conversation_starters: Vec::new(),
            variables: Vec::new(),
            settings: GraphSettings::default(),
@@ -946,6 +1051,10 @@ mod tests {
                state_updates: None,
                output_schema: None,
                timeout: None,
                skills_enabled: None,
                enabled_skills: None,
                inject_skill_instructions: None,
                skill_instructions: None,
            }),
            next: next.map(NextTargets::from),
        }
@@ -967,6 +1076,111 @@ mod tests {
        assert!(result.errors.iter().any(|e| e.message.contains("ghost")));
    }
    #[test]
    fn llm_node_skill_in_graph_set_passes() {
        let mut graph = graph_with(
            vec![
                ("l", llm_node("l", None, Some("end"))),
                ("end", end_node("end")),
            ],
            "l",
        );
        graph.enabled_skills = Some(vec!["code-review".into(), "git-master".into()]);
        if let NodeType::Llm(ref mut n) = graph.nodes.get_mut("l").unwrap().node_type {
            n.enabled_skills = Some(vec!["code-review".into()]);
        }
        let result = validator().validate(&graph);
        assert!(
            !result
                .errors
                .iter()
                .any(|e| e.message.contains("enabled_skills")),
            "unexpected enabled_skills error: {:?}",
            result.errors
        );
    }
    #[test]
    fn llm_node_skill_not_in_graph_set_errors() {
        let mut graph = graph_with(
            vec![
                ("l", llm_node("l", None, Some("end"))),
                ("end", end_node("end")),
            ],
            "l",
        );
        graph.enabled_skills = Some(vec!["code-review".into()]);
        if let NodeType::Llm(ref mut n) = graph.nodes.get_mut("l").unwrap().node_type {
            n.enabled_skills = Some(vec!["git-master".into()]);
        }
        let result = validator().validate(&graph);
        assert!(!result.is_valid());
        assert!(
            result
                .errors
                .iter()
                .any(|e| e.message.contains("'git-master'") && e.message.contains("graph-level")),
            "expected git-master subset error, got: {:?}",
            result.errors
        );
    }
    #[test]
    fn llm_node_empty_skill_name_errors() {
        let mut graph = graph_with(
            vec![
                ("l", llm_node("l", None, Some("end"))),
                ("end", end_node("end")),
            ],
            "l",
        );
        graph.enabled_skills = Some(vec!["code-review".into()]);
        if let NodeType::Llm(ref mut n) = graph.nodes.get_mut("l").unwrap().node_type {
            n.enabled_skills = Some(vec!["".into()]);
        }
        let result = validator().validate(&graph);
        assert!(!result.is_valid());
        assert!(
            result
                .errors
                .iter()
                .any(|e| e.message.contains("empty skill name")),
            "expected empty-skill-name error, got: {:?}",
            result.errors
        );
    }
    #[test]
    fn llm_node_skill_when_no_graph_set_is_permitted_by_validator() {
        let mut graph = graph_with(
            vec![
                ("l", llm_node("l", None, Some("end"))),
                ("end", end_node("end")),
            ],
            "l",
        );
        if let NodeType::Llm(ref mut n) = graph.nodes.get_mut("l").unwrap().node_type {
            n.enabled_skills = Some(vec!["anything".into()]);
        }
        let result = validator().validate(&graph);
        assert!(
            !result
                .errors
                .iter()
                .any(|e| e.message.contains("enabled_skills")),
            "validator should not block when graph.enabled_skills is None: {:?}",
            result.errors
        );
    }
    fn agent_ctx(tools: &[&str], mcp: &[&str]) -> AgentValidationContext {
        AgentValidationContext {
            tool_names: tools.iter().map(|s| s.to_string()).collect(),
@@ -1182,7 +1396,7 @@ mod tests {
    }
    fn validator() -> GraphValidator {
-        GraphValidator::new(env::current_dir().unwrap())
+        GraphValidator::new(env::current_dir().unwrap()).with_skill_exists(|_: &str| true)
    }
    #[test]
@@ -10,6 +10,7 @@ mod repl;
 mod utils;
 mod mcp;
 mod parsers;
 mod sandbox;
 mod supervisor;
 mod vault;
@@ -22,10 +23,11 @@ use crate::client::{
 };
 use crate::config::paths;
 use crate::config::{
-    Agent, AppConfig, AppState, CODE_ROLE, Config, EXPLAIN_SHELL_ROLE, Input, RequestContext,
+    Agent, AppConfig, AppState, CODE_ROLE, Config, EXPLAIN_SHELL_ROLE, Input, MemoryScope,
-    SHELL_ROLE, TEMP_SESSION_NAME, WorkingMode, ensure_parent_exists, install_builtins,
+    RequestContext, SHELL_ROLE, TEMP_SESSION_NAME, WorkingMode, ensure_parent_exists,
-    list_agents, load_env_file, macro_execute, sync_models,
+    install_builtins, list_agents, load_env_file, macro_execute, sync_models,
 };
 use crate::function::supervisor::{GuardrailAction, check_pending_agents_guardrail};
 use crate::render::{prompt_theme, render_error};
 use crate::repl::Repl;
 use crate::utils::*;
@@ -35,14 +37,14 @@ use clap::{CommandFactory, Parser};
 use clap_complete::CompleteEnv;
 use client::ClientConfig;
 use inquire::{Select, Text, set_global_render_config};
-use log::LevelFilter;
+use log::{LevelFilter, warn};
 use log4rs::append::console::ConsoleAppender;
 use log4rs::append::file::FileAppender;
 use log4rs::config::{Appender, Logger, Root};
 use log4rs::encode::pattern::PatternEncoder;
 use oauth::OAuthProvider;
 use std::path::PathBuf;
-use std::{env, process, sync::Arc};
+use std::{env, fs, process, sync::Arc};
 #[tokio::main]
 async fn main() -> Result<()> {
@@ -55,6 +57,7 @@ async fn main() -> Result<()> {
        shell.generate_completions(&mut cmd);
        return Ok(());
    }
    if cli.tail_logs {
        tail_logs(cli.disable_log_colors).await;
        return Ok(());
@@ -91,6 +94,10 @@ async fn main() -> Result<()> {
            .await?;
    }
    if let Some(name) = &cli.sandbox {
        return sandbox::launch(name.clone(), cli.fresh, cli.no_mixins);
    }
    install_builtins()?;
    if let Some(category) = cli.install {
@@ -113,7 +120,7 @@ async fn main() -> Result<()> {
    if vault_flags {
        let cfg = Config::load_with_interpolation(true).await?;
        let app_config = AppConfig::from_config(cfg)?;
-        let vault = Vault::init(&app_config);
+        let vault = Vault::init(&app_config)?;
        return Vault::handle_vault_flags(cli, &vault);
    }
@@ -197,14 +204,18 @@ async fn run(
        println!("{skills}");
        return Ok(());
    }
-    if cli.skill.len() == 1 && !paths::has_skill(&cli.skill[0]) {
+    let skills = cli.skills();
-        let name = &cli.skill[0];
+    if skills.len() == 1 {
        let name = &skills[0];
        paths::validate_skill_name(name)?;
        if !paths::has_skill(name) {
            let app = Arc::clone(&ctx.app.config);
            ctx.upsert_skill(app.as_ref(), name)?;
            return Ok(());
        }
-    if cli.skill.len() > 1 {
+    } else if skills.len() > 1 {
-        for name in &cli.skill {
+        for name in &skills {
            paths::validate_skill_name(name)?;
            if !paths::has_skill(name) {
                bail!("Skill '{name}' is not installed");
            }
@@ -288,12 +299,40 @@ async fn run(
    if cli.no_stream {
        update_app_config(&mut ctx, |app| app.stream = false);
    }
    if cli.no_memory {
        update_app_config(&mut ctx, |app| app.memory = Some(false));
    }
    if cli.empty_session {
        ctx.empty_session()?;
    }
    if cli.save_session {
        ctx.set_save_session_this_time()?;
    }
    if let Some(scope) = cli.init_memory {
        let (path, content) = match scope {
            MemoryScope::Global => (
                paths::global_memory_index_path(),
                "# Global Memory\n\n<!-- Universal facts about you go here. The LLM uses this as always-on context. -->\n<!-- Drill files (when created) are listed below. -->\n",
            ),
            MemoryScope::Workspace => (
                env::current_dir()?.join("COYOTE.md"),
                "# Workspace Memory\n\n<!-- Facts about this project go here. The LLM uses this as always-on context. -->\n",
            ),
        };
        if path.exists() {
            eprintln!("Memory marker already exists at '{}'.", path.display());
            return Ok(());
        }
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent)?;
        }
        fs::write(&path, content)?;
        println!("✓ Created memory marker at '{}'.", path.display());
        return Ok(());
    }
    if cli.info {
        let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
        let info = ctx.info(app.as_ref())?;
@@ -323,7 +362,7 @@ async fn run(
            .await?;
    }
-    for name in &cli.skill {
+    for name in &cli.skills() {
        ctx.load_skill_repl(name, abort_signal.clone()).await?;
    }
@@ -387,6 +426,21 @@ async fn start_directive(
            abort_signal,
        )
        .await?;
    } else {
        match check_pending_agents_guardrail(ctx) {
            GuardrailAction::Inject(prompt) => {
                let guardrail_input = Input::from_str(ctx, &prompt, None)?;
                return start_directive(ctx, guardrail_input, code_mode, abort_signal).await;
            }
            GuardrailAction::ForceTerminate(ids) => {
                warn!(
                    "Pending-agent guardrail force-cancelled {} agent(s) after max reminders: {:?}",
                    ids.len(),
                    ids
                );
            }
            GuardrailAction::NoAction => {}
        }
    }
    ctx.exit_session()?;
@@ -457,7 +511,7 @@ async fn shell_execute(
                }
                'd' => {
                    let role = ctx.retrieve_role(app.as_ref(), EXPLAIN_SHELL_ROLE)?;
-                    let input = Input::from_str(ctx, &eval_str, Some(role));
+                    let input = Input::from_str(ctx, &eval_str, Some(role))?;
                    if input.stream() {
                        call_chat_completions_streaming(
                            &input,
@@ -502,7 +556,7 @@ async fn create_input(
 ) -> Result<Input> {
    let text = text.unwrap_or_default();
    let input = if file.is_empty() {
-        Input::from_str(ctx, &text, None)
+        Input::from_str(ctx, &text, None)?
    } else {
        Input::from_files_with_spinner(ctx, &text, file.to_vec(), None, abort_signal).await?
    };
@@ -146,7 +146,7 @@ impl McpRegistry {
    pub async fn init(
        log_path: Option<PathBuf>,
        start_mcp_servers: bool,
-        enabled_mcp_servers: Option<String>,
+        enabled_mcp_servers: Option<Vec<String>>,
        abort_signal: AbortSignal,
        app_config: &AppConfig,
        vault: &Vault,
@@ -182,7 +182,7 @@ impl McpRegistry {
            return Ok(registry);
        }
-        let (parsed_content, missing_secrets) = interpolate_secrets(&content, vault);
+        let (parsed_content, missing_secrets) = interpolate_secrets(&content, vault)?;
        if !missing_secrets.is_empty() {
            return Err(anyhow!(formatdoc!(
@@ -216,7 +216,7 @@ impl McpRegistry {
    async fn start_select_mcp_servers(
        &mut self,
-        enabled_mcp_servers: Option<String>,
+        enabled_mcp_servers: Option<Vec<String>>,
    ) -> Result<()> {
        if self.config.is_none() {
            debug!(
@@ -292,15 +292,15 @@ impl McpRegistry {
        Ok((id.to_string(), service, catalog))
    }
-    fn resolve_server_ids(&self, enabled_mcp_servers: Option<String>) -> Vec<String> {
+    fn resolve_server_ids(&self, enabled_mcp_servers: Option<Vec<String>>) -> Vec<String> {
        if let Some(config) = &self.config
            && let Some(servers) = enabled_mcp_servers
        {
-            if servers == "all" {
+            if servers.iter().any(|s| s.trim() == "all") {
                config.mcp_servers.keys().cloned().collect()
            } else {
                let enabled_servers: HashSet<String> =
-                    servers.split(',').map(|s| s.trim().to_string()).collect();
+                    servers.into_iter().map(|s| s.trim().to_string()).collect();
                config
                    .mcp_servers
                    .keys()
@@ -754,7 +754,7 @@ mod tests {
    #[test]
    fn resolve_all_returns_all_configured_servers() {
        let registry = make_registry_with_config(&["github", "slack", "jira"]);
-        let mut ids = registry.resolve_server_ids(Some("all".to_string()));
+        let mut ids = registry.resolve_server_ids(Some(vec!["all".to_string()]));
        ids.sort();
        assert_eq!(ids, vec!["github", "jira", "slack"]);
    }
@@ -762,7 +762,8 @@ mod tests {
    #[test]
    fn resolve_comma_separated_returns_matching_servers() {
        let registry = make_registry_with_config(&["github", "slack", "jira"]);
-        let mut ids = registry.resolve_server_ids(Some("github, jira".to_string()));
+        let mut ids =
            registry.resolve_server_ids(Some(vec!["github".to_string(), "jira".to_string()]));
        ids.sort();
        assert_eq!(ids, vec!["github", "jira"]);
    }
@@ -770,7 +771,7 @@ mod tests {
    #[test]
    fn resolve_single_server_name() {
        let registry = make_registry_with_config(&["github", "slack"]);
-        let ids = registry.resolve_server_ids(Some("slack".to_string()));
+        let ids = registry.resolve_server_ids(Some(vec!["slack".to_string()]));
        assert_eq!(ids, vec!["slack"]);
    }
@@ -784,28 +785,32 @@ mod tests {
    #[test]
    fn resolve_no_config_returns_empty() {
        let registry = McpRegistry::default();
-        let ids = registry.resolve_server_ids(Some("all".to_string()));
+        let ids = registry.resolve_server_ids(Some(vec!["all".to_string()]));
        assert!(ids.is_empty());
    }
    #[test]
    fn resolve_nonexistent_server_filtered_out() {
        let registry = make_registry_with_config(&["github"]);
-        let ids = registry.resolve_server_ids(Some("github, nonexistent".to_string()));
+        let ids = registry
            .resolve_server_ids(Some(vec!["github".to_string(), "nonexistent".to_string()]));
        assert_eq!(ids, vec!["github"]);
    }
    #[test]
    fn resolve_all_nonexistent_returns_empty() {
        let registry = make_registry_with_config(&["github"]);
-        let ids = registry.resolve_server_ids(Some("foo, bar".to_string()));
+        let ids = registry.resolve_server_ids(Some(vec!["foo".to_string(), "bar".to_string()]));
        assert!(ids.is_empty());
    }
    #[test]
    fn resolve_trims_whitespace() {
        let registry = make_registry_with_config(&["github", "slack"]);
-        let mut ids = registry.resolve_server_ids(Some("  github  ,  slack  ".to_string()));
+        let mut ids = registry.resolve_server_ids(Some(vec![
            "  github  ".to_string(),
            "  slack  ".to_string(),
        ]));
        ids.sort();
        assert_eq!(ids, vec!["github", "slack"]);
    }
@@ -16,8 +16,8 @@ use parking_lot::RwLock;
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 use std::{
-    collections::HashMap, env, fmt, fmt::Debug, fs, hash::Hash, path::Path, sync::Arc,
+    cmp::Ordering, collections::HashMap, env, fmt, fmt::Debug, fs, hash::Hash, path::Path,
-    time::Duration,
+    sync::Arc, time::Duration,
 };
 use tokio::time::sleep;
@@ -1196,7 +1196,7 @@ fn reciprocal_rank_fusion(
        }
    }
    let mut sorted_items: Vec<(DocumentId, f32)> = map.into_iter().collect();
-    sorted_items.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
+    sorted_items.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(Ordering::Equal));
    sorted_items
        .into_iter()
@@ -12,11 +12,14 @@ use crate::config::{
    macro_execute,
 };
 use crate::config::{AssetCategory, paths};
 use crate::function::supervisor::{GuardrailAction, check_pending_agents_guardrail};
 use crate::render::render_error;
 use crate::utils::{
-    AbortSignal, abortable_run_with_spinner, create_abort_signal, dimmed_text, set_text, temp_file,
+    AbortSignal, SHELL, abortable_run_with_spinner, create_abort_signal, dimmed_text, run_command,
    set_text, temp_file,
 };
 use crate::sandbox::SANDBOX_ENV_FLAG;
 use crate::{config, graph, resolve_oauth_client};
 use anyhow::{Context, Result, bail};
 use crossterm::cursor::SetCursorStyle;
@@ -46,10 +49,15 @@ pub const DEFAULT_CONTINUATION_PROMPT: &str = indoc! {"
    4. Continue with the next pending item now. Call tools immediately."
 };
-static REPL_COMMANDS: LazyLock<[ReplCommand; 43]> = LazyLock::new(|| {
+static REPL_COMMANDS: LazyLock<[ReplCommand; 49]> = LazyLock::new(|| {
    [
        ReplCommand::new(".help", "Show this help guide", AssertState::pass()),
        ReplCommand::new(".info", "Show system info", AssertState::pass()),
        ReplCommand::new(
            ".info tools",
            "Show the list of enabled tools to be passed to the LLM",
            AssertState::True(StateFlags::FUNCTION_CALLING),
        ),
        ReplCommand::new(
            ".authenticate",
            "Authenticate the current model client via OAuth (if configured)",
@@ -160,6 +168,11 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 43]> = LazyLock::new(|| {
            "Clear the todo list and stop auto-continuation",
            AssertState::pass(),
        ),
        ReplCommand::new(
            ".info todo",
            "Show the current todo list driving auto-continuation",
            AssertState::True(StateFlags::AUTO_CONTINUE),
        ),
        ReplCommand::new(
            ".rag",
            "Initialize or access RAG",
@@ -193,8 +206,28 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 43]> = LazyLock::new(|| {
        ReplCommand::new(".macro", "Execute a macro", AssertState::pass()),
        ReplCommand::new(
            ".skill",
-            "List, load, unload, edit, or create skills",
+            "Create a new skill",
-            AssertState::pass(),
+            AssertState::True(StateFlags::SKILLS_ENABLED),
        ),
        ReplCommand::new(
            ".skill load",
            "Load a skill into the current context",
            AssertState::True(StateFlags::SKILLS_ENABLED),
        ),
        ReplCommand::new(
            ".skill loaded",
            "List currently-loaded skills",
            AssertState::True(StateFlags::SKILLS_ENABLED),
        ),
        ReplCommand::new(
            ".skill unload",
            "Unload a skill from the current context",
            AssertState::True(StateFlags::SKILLS_ENABLED),
        ),
        ReplCommand::new(
            ".edit skill",
            "Modify an existing skill by name",
            AssertState::True(StateFlags::SKILLS_ENABLED),
        ),
        ReplCommand::new(
            ".file",
@@ -272,7 +305,12 @@ Type ".help" for additional help.
 "#,
                env!("CARGO_CRATE_NAME"),
                env!("CARGO_PKG_VERSION"),
-            )
+            );
            if env::var_os(SANDBOX_ENV_FLAG).is_some() {
                eprintln!(
                    "Sandbox mode is enabled. All changes made to the Coyote config will not persist to the host machine."
                );
            }
        }
        loop {
@@ -301,6 +339,9 @@ Type ".help" for additional help.
                }
                Ok(Signal::CtrlC) => {
                    self.abort_signal.set_ctrlc();
                    if let Some(supervisor) = self.ctx.read().supervisor.clone() {
                        supervisor.read().cancel_recursive();
                    }
                    println!("(To exit, press Ctrl+D or enter \".exit\")\n");
                }
                Ok(Signal::CtrlD) => {
@@ -310,6 +351,11 @@ Type ".help" for additional help.
                _ => {}
            }
        }
        if let Some(supervisor) = self.ctx.read().supervisor.clone() {
            supervisor.read().cancel_recursive();
        }
        self.ctx.write().exit_session()?;
        Ok(())
    }
@@ -430,6 +476,7 @@ pub async fn run_repl_command(
    abort_signal: AbortSignal,
    mut line: &str,
 ) -> Result<bool> {
    ctx.pending_agents_guardrail_count = 0;
    if let Ok(Some(captures)) = MULTILINE_RE.captures(line)
        && let Some(text_match) = captures.get(1)
    {
@@ -458,6 +505,14 @@ pub async fn run_repl_command(
                    let info = ctx.agent_info()?;
                    print!("{info}");
                }
                Some("tools") => {
                    let info = ctx.tools_info()?;
                    print!("{info}");
                }
                Some("todo") => {
                    let info = ctx.todo_info()?;
                    print!("{info}");
                }
                Some(_) => unknown_command()?,
                None => {
                    let app = Arc::clone(&ctx.app.config);
@@ -498,7 +553,7 @@ pub async fn run_repl_command(
                    Some((name, text)) => {
                        let app = Arc::clone(&ctx.app.config);
                        let role = ctx.retrieve_role(app.as_ref(), name.trim())?;
-                        let input = Input::from_str(ctx, text, Some(role));
+                        let input = Input::from_str(ctx, text, Some(role))?;
                        ask(ctx, abort_signal.clone(), input, false).await?;
                    }
                    None => {
@@ -529,8 +584,8 @@ pub async fn run_repl_command(
    .skill loaded                   # List currently-loaded skills
    .skill load <name>              # Load a skill into the current context
    .skill unload <name>            # Unload a loaded skill
-    .skill edit <name>              # Open an existing skill in $EDITOR
+    .skill <name>                   # Open the skill in $EDITOR; create with a scaffold if missing
-    .skill <name>                   # Open the skill in $EDITOR; create with a scaffold if missing"#
+                                    # (Use `.edit skill <name>` to edit an existing skill without the create-if-missing behavior.)"#
                    ),
                    "loaded" => ctx.list_loaded_skills(),
                    "load" => {
@@ -547,19 +602,6 @@ pub async fn run_repl_command(
                            ctx.unload_skill_repl(rest, abort_signal.clone()).await?;
                        }
                    }
                    "edit" => {
                        if rest.is_empty() {
                            println!("Usage: .skill edit <name>");
                        } else if !paths::has_skill(rest) {
                            bail!(
                                "Skill '{rest}' is not installed (expected at {})",
                                paths::skill_file(rest).display()
                            );
                        } else {
                            let app = Arc::clone(&ctx.app.config);
                            ctx.upsert_skill(app.as_ref(), rest)?;
                        }
                    }
                    name => {
                        let app = Arc::clone(&ctx.app.config);
                        ctx.upsert_skill(app.as_ref(), name)?;
@@ -662,7 +704,7 @@ pub async fn run_repl_command(
                    match text {
                        Some(text) => {
                            println!("{}", dimmed_text(&format!(">> {text}")));
-                            let input = Input::from_str(ctx, &text, None);
+                            let input = Input::from_str(ctx, &text, None)?;
                            ask(ctx, abort_signal.clone(), input, true).await?;
                        }
                        None => {
@@ -712,9 +754,25 @@ pub async fn run_repl_command(
                    Some("mcp-config") => {
                        ctx.edit_mcp_config()?;
                    }
                    Some(s) if s == "skill" || s.starts_with("skill ") => {
                        let name = s.strip_prefix("skill").unwrap_or("").trim();
                        if name.is_empty() {
                            println!("Usage: .edit skill <name>");
                        } else if let Err(e) = paths::validate_skill_name(name) {
                            bail!(e);
                        } else if !paths::has_skill(name) {
                            bail!(
                                "Skill '{name}' is not installed (expected at {})",
                                paths::skill_file(name).display()
                            );
                        } else {
                            let app = Arc::clone(&ctx.app.config);
                            ctx.upsert_skill(app.as_ref(), name)?;
                        }
                    }
                    _ => {
                        println!(
-                            r#"Usage: .edit <config|mcp-config|role|session|rag-docs|agent-config>"#
+                            r#"Usage: .edit <config|mcp-config|role|session|rag-docs|agent-config|skill <name>>"#
                        )
                    }
                }
@@ -816,7 +874,7 @@ pub async fn run_repl_command(
                        None => bail!("Unable to regenerate the response"),
                    };
                let app = Arc::clone(&ctx.app.config);
-                input.set_regenerate(ctx.extract_role(&app));
+                input.set_regenerate(ctx.extract_role(&app)?);
                ask(ctx, abort_signal.clone(), input, true).await?;
            }
            ".set" => match args {
@@ -937,11 +995,15 @@ pub async fn run_repl_command(
            _ => unknown_command()?,
        },
        None => {
            if let Some(cmd) = try_extract_shell_command(line) {
                handle_shell_passthrough(cmd)?;
            } else {
                reset_continuation(ctx);
-            let input = Input::from_str(ctx, line, None);
+                let input = Input::from_str(ctx, line, None)?;
                ask(ctx, abort_signal.clone(), input, true).await?;
            }
        }
    }
    if !ctx.macro_flag {
        println!();
@@ -1003,6 +1065,20 @@ async fn ask(
        )
        .await
    } else {
        match check_pending_agents_guardrail(ctx) {
            GuardrailAction::Inject(prompt) => {
                let guardrail_input = Input::from_str(ctx, &prompt, None)?;
                return ask(ctx, abort_signal, guardrail_input, false).await;
            }
            GuardrailAction::ForceTerminate(ids) => {
                warn!(
                    "Pending-agent guardrail force-cancelled {} agent(s) after max reminders: {:?}",
                    ids.len(),
                    ids
                );
            }
            GuardrailAction::NoAction => {}
        }
        let do_continue = should_continue(ctx);
        if do_continue {
@@ -1034,7 +1110,7 @@ async fn ask(
                format!("{prompt}\n\n{todo_state}")
            };
-            let continuation_input = Input::from_str(ctx, &full_prompt, None);
+            let continuation_input = Input::from_str(ctx, &full_prompt, None)?;
            ask(ctx, abort_signal, continuation_input, false).await
        } else {
            reset_continuation(ctx);
@@ -1107,7 +1183,7 @@ async fn ask(
                        format!("{prompt}\n\n{todo_state}")
                    };
-                    let continuation_input = Input::from_str(ctx, &full_prompt, None);
+                    let continuation_input = Input::from_str(ctx, &full_prompt, None)?;
                    return ask(ctx, abort_signal, continuation_input, false).await;
                }
            }
@@ -1141,10 +1217,12 @@ fn dump_repl_help() {
        .join("\n");
    println!(
        r###"{head}
 {:<24} Run an arbitrary shell command (stdout/stderr stream to your terminal; Ctrl+C interrupts)
 Type ::: to start multi-line editing, type ::: to finish it.
 Press Ctrl+O to open an editor for editing the input buffer.
 Press Ctrl+C to cancel the response, Ctrl+D to exit the REPL."###,
        "!<command>",
    );
 }
@@ -1160,6 +1238,25 @@ fn parse_command(line: &str) -> Option<(&str, Option<&str>)> {
    }
 }
 fn try_extract_shell_command(line: &str) -> Option<&str> {
    let rest = line.strip_prefix('!')?;
    Some(rest.trim_start())
 }
 fn handle_shell_passthrough(cmd: &str) -> Result<()> {
    if cmd.is_empty() {
        eprintln!("Usage: !<command>");
        return Ok(());
    }
    let status = run_command(&SHELL.cmd, &[&SHELL.arg, cmd], None)?;
    if status != 0 {
        eprintln!("[exit {status}]");
    }
    Ok(())
 }
 fn split_first_arg(args: Option<&str>) -> Option<(&str, Option<&str>)> {
    args.map(|v| match v.split_once(' ') {
        Some((subcmd, args)) => (subcmd, Some(args.trim())),
@@ -1318,8 +1415,8 @@ mod tests {
    }
    #[test]
-    fn repl_commands_has_43_entries() {
+    fn repl_commands_has_49_entries() {
-        assert_eq!(REPL_COMMANDS.len(), 43);
+        assert_eq!(REPL_COMMANDS.len(), 49);
    }
    #[test]
@@ -1494,6 +1591,57 @@ mod tests {
        assert_eq!(parse_command("."), Some((".", None)));
    }
    #[test]
    fn try_extract_shell_command_strips_bang() {
        assert_eq!(try_extract_shell_command("!ls"), Some("ls"));
        assert_eq!(try_extract_shell_command("!ls -la"), Some("ls -la"));
    }
    #[test]
    fn try_extract_shell_command_trims_inner_whitespace() {
        assert_eq!(try_extract_shell_command("!   echo hi"), Some("echo hi"));
        assert_eq!(try_extract_shell_command("! ls"), Some("ls"));
    }
    #[test]
    fn try_extract_shell_command_only_bang_yields_empty() {
        assert_eq!(try_extract_shell_command("!"), Some(""));
        assert_eq!(try_extract_shell_command("!   "), Some(""));
    }
    #[test]
    fn try_extract_shell_command_rejects_leading_whitespace() {
        assert!(try_extract_shell_command(" !ls").is_none());
        assert!(try_extract_shell_command("\t!ls").is_none());
    }
    #[test]
    fn try_extract_shell_command_rejects_inline_bang() {
        assert!(try_extract_shell_command("echo !foo").is_none());
        assert!(try_extract_shell_command("hello world").is_none());
    }
    #[test]
    fn try_extract_shell_command_strips_one_leading_bang() {
        assert_eq!(try_extract_shell_command("!!ls"), Some("!ls"));
    }
    #[test]
    fn try_extract_shell_command_preserves_pipes_and_redirects() {
        assert_eq!(
            try_extract_shell_command("!ls -la | grep yaml"),
            Some("ls -la | grep yaml")
        );
        assert_eq!(
            try_extract_shell_command("!cat foo.txt > /tmp/out"),
            Some("cat foo.txt > /tmp/out")
        );
        assert_eq!(
            try_extract_shell_command(r#"!echo "$HOME""#),
            Some(r#"echo "$HOME""#)
        );
    }
    #[test]
    fn split_first_arg_none_input() {
        assert!(split_first_arg(None).is_none());
@@ -0,0 +1,237 @@
 use std::env;
 use std::fs::{read_dir, read_to_string};
 use std::path::{Path, PathBuf};
 use anyhow::{Context, Result};
 use serde_yaml::Value;
 use crate::config::paths;
 const SBX_MIXIN_FILE_NAME: &str = "sbx-mixin.yaml";
 #[derive(Debug, Clone)]
 pub struct DiscoveredMixin {
    pub path: PathBuf,
    pub label: String,
    pub install_count: usize,
    pub domain_count: usize,
 }
 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()) {
        out.push(read_mixin(path)?);
    }
    for path in collect_subdir_mixins(&paths::agents_data_dir()) {
        out.push(read_mixin(path)?);
    }
    if let Ok(cwd) = env::current_dir()
        && let Some(path) = paths::find_workspace_sbx_mixin(&cwd)
    {
        out.push(read_mixin(path)?);
    }
    Ok(out)
 }
 pub fn summarize(path: &Path) -> Result<(usize, usize)> {
    let content = read_to_string(path)
        .with_context(|| format!("Failed to read sbx mixin {}", path.display()))?;
    let value: Value = serde_yaml::from_str(&content)
        .with_context(|| format!("Failed to parse sbx mixin {}", path.display()))?;
    let installs = 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"))
        .and_then(|d| d.as_sequence())
        .map(|s| s.len())
        .unwrap_or(0);
    Ok((installs, domains))
 }
 pub fn log_discovery(mixins: &[DiscoveredMixin], disabled: bool) {
    if disabled {
        info!("Mixin discovery disabled via --no-mixins.");
        return;
    }
    if mixins.is_empty() {
        info!("No sbx mixins discovered.");
        return;
    }
    let header = format!("Applying {} sbx mixin(s):", mixins.len());
    info!("{header}");
    println!("{header}");
    for m in mixins {
        let line = format!(
            "  {}  (adds: {} install{}, {} domain{})",
            m.label,
            m.install_count,
            if m.install_count == 1 { "" } else { "s" },
            m.domain_count,
            if m.domain_count == 1 { "" } else { "s" },
        );
        info!("{line}");
        println!("{line}");
    }
 }
 fn push_if_exists(out: &mut Vec<DiscoveredMixin>, path: PathBuf) -> Result<()> {
    if path.exists() {
        out.push(read_mixin(path)?);
    }
    Ok(())
 }
 fn read_mixin(path: PathBuf) -> Result<DiscoveredMixin> {
    let label = path.display().to_string();
    let (install_count, domain_count) = summarize(&path)?;
    Ok(DiscoveredMixin {
        path,
        label,
        install_count,
        domain_count,
    })
 }
 fn collect_subdir_mixins(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_dir()).unwrap_or(false))
        .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
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::fs;
    use std::time;
    fn unique_root(prefix: &str) -> PathBuf {
        let nanos = time::SystemTime::now()
            .duration_since(time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let root = env::temp_dir().join(format!("coyote-{prefix}-{nanos}"));
        fs::create_dir_all(&root).unwrap();
        root
    }
    #[test]
    fn summarize_counts_installs_and_domains() {
        let root = unique_root("sbx-mixin-counts");
        let path = root.join("sbx-mixin.yaml");
        fs::write(
            &path,
            r#"
 schemaVersion: "1"
 kind: mixin
 commands:
  install:
    - command: "echo hi"
    - command: "echo bye"
 network:
  allowedDomains:
    - "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_treats_missing_blocks_as_zero() {
        let root = unique_root("sbx-mixin-empty");
        let path = root.join("sbx-mixin.yaml");
        fs::write(&path, "schemaVersion: \"1\"\nkind: mixin\n").unwrap();
        assert_eq!(summarize(&path).unwrap(), (0, 0));
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn summarize_returns_err_on_malformed_yaml() {
        let root = unique_root("sbx-mixin-bad");
        let path = root.join("sbx-mixin.yaml");
        fs::write(&path, "this: is: not: yaml: ::").unwrap();
        let err = summarize(&path).unwrap_err();
        let msg = format!("{err:#}");
        assert!(
            msg.contains(&path.display().to_string()),
            "expected error to mention path; got: {msg}"
        );
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn collect_subdir_mixins_sorts_and_skips_missing() {
        let root = unique_root("sbx-mixin-subdirs");
        for name in ["zebra", "apple", "no-mixin", "mango"] {
            let dir = root.join(name);
            fs::create_dir_all(&dir).unwrap();
            if name != "no-mixin" {
                fs::write(dir.join("sbx-mixin.yaml"), "kind: mixin\n").unwrap();
            }
        }
        let found = collect_subdir_mixins(&root);
        let names: Vec<String> = found
            .iter()
            .map(|p| {
                p.parent()
                    .unwrap()
                    .file_name()
                    .unwrap()
                    .to_string_lossy()
                    .to_string()
            })
            .collect();
        assert_eq!(names, vec!["apple", "mango", "zebra"]);
        let _ = fs::remove_dir_all(&root);
    }
    #[test]
    fn collect_subdir_mixins_returns_empty_for_missing_dir() {
        let absent = env::temp_dir().join("coyote-definitely-not-here-xyz");
        let found = collect_subdir_mixins(&absent);
        assert!(found.is_empty());
    }
 }
@@ -0,0 +1,874 @@
 use anyhow::{Context, Result, anyhow, bail};
 use rust_embed::RustEmbed;
 use sha2::{Digest, Sha256};
 use std::env;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 use which::which;
 mod mixins;
 use gman::providers::SupportedProvider;
 use crate::config::paths;
 use crate::sandbox::mixins::DiscoveredMixin;
 use crate::utils::run_command_with_output;
 use crate::vault::Vault;
 const SBX_BINARY: &str = "sbx";
 pub(crate) const SANDBOX_ENV_FLAG: &str = "IS_SANDBOX";
 const SANDBOX_AGENT: &str = "coyote";
 #[derive(RustEmbed)]
 #[folder = "assets/sbx-kit/"]
 struct EmbeddedKit;
 #[derive(RustEmbed)]
 #[folder = "assets/sbx-vault-mixins/"]
 struct EmbeddedVaultMixins;
 pub fn launch(name: Option<String>, fresh: bool, no_mixins: bool) -> Result<()> {
    ensure_sbx_installed()?;
    bail_if_nested()?;
    let name = resolve_name(name)?;
    let kit_path = resolve_kit_path()?;
    let discovered = if no_mixins {
        Vec::new()
    } else {
        let mut all = mixins::discover()?;
        if let Ok(vault) = Vault::init_bare()
            && let Some(vault_mixin) = extract_vault_mixin(&vault.provider)?
        {
            all.insert(0, vault_mixin);
        }
        all
    };
    if sandbox_exists(&name)? {
        info!("Re-attaching to existing sandbox '{name}'");
        if fresh {
            debug!("--fresh ignored: re-attaching to existing sandbox '{name}'");
        }
        if no_mixins {
            debug!("--no-mixins ignored: re-attaching to existing sandbox '{name}'");
        }
    } else {
        mixins::log_discovery(&discovered, no_mixins);
        if fresh {
            let msg = format!("Creating fresh sandbox '{name}' (no host config will be copied)");
            info!("{msg}");
            println!("{msg}");
            create_sandbox(&name, &kit_path, &discovered)?;
        } else {
            create_sandbox(&name, &kit_path, &discovered)?;
            copy_host_files(&name)?;
        }
    }
    exec_run(&name, &kit_path)
 }
 fn ensure_sbx_installed() -> Result<()> {
    which(SBX_BINARY).map_err(|_| {
        anyhow!(
            "`sbx` binary not found in PATH.\n\n\
             Install Docker Sandboxes:\n  https://docs.docker.com/ai/sandboxes/get-started/"
        )
    })?;
    Ok(())
 }
 fn bail_if_nested() -> Result<()> {
    if env::var_os(SANDBOX_ENV_FLAG).is_some() {
        bail!("Refusing to nest sandboxes: ${SANDBOX_ENV_FLAG} is set, already inside one");
    }
    Ok(())
 }
 fn resolve_name(name: Option<String>) -> Result<String> {
    if let Some(n) = name {
        let trimmed = n.trim();
        if !trimmed.is_empty() {
            let sanitized = sanitize_name(trimmed);
            if sanitized.is_empty() {
                bail!("Sandbox name '{trimmed}' sanitizes to an empty string");
            }
            return Ok(sanitized);
        }
    }
    let cwd = env::current_dir().context("Failed to determine current directory")?;
    let basename = cwd
        .file_name()
        .and_then(|s| s.to_str())
        .ok_or_else(|| anyhow!("Could not derive sandbox name from current directory"))?;
    let sanitized = sanitize_name(basename);
    if sanitized.is_empty() {
        bail!("Could not derive a valid sandbox name from '{basename}'; pass --sandbox <NAME>");
    }
    Ok(sanitized)
 }
 fn sanitize_name(input: &str) -> String {
    let mut out = String::with_capacity(input.len());
    let mut last_was_dash = false;
    for ch in input.chars() {
        let lower = ch.to_ascii_lowercase();
        if lower.is_ascii_alphanumeric() {
            out.push(lower);
            last_was_dash = false;
        } else if !last_was_dash {
            out.push('-');
            last_was_dash = true;
        }
    }
    out.trim_matches('-').to_string()
 }
 fn resolve_kit_path() -> Result<PathBuf> {
    if let Some(path) = paths::sandbox_kit_override() {
        if !path.exists() {
            bail!(
                "$COYOTE_SANDBOX_KIT is set but path does not exist: {}",
                path.display()
            );
        }
        debug!(
            "Using kit override from $COYOTE_SANDBOX_KIT: {}",
            path.display()
        );
        return Ok(path);
    }
    extract_embedded_kit()
 }
 fn extract_embedded_kit() -> Result<PathBuf> {
    let cache_root = paths::sbx_kit_dir();
    let new_hash = compute_kit_hash()?;
    let hash_file = paths::sbx_kit_hash_file();
    if let Ok(existing) = fs::read_to_string(&hash_file)
        && existing == new_hash
    {
        return Ok(cache_root);
    }
    if cache_root.exists() {
        fs::remove_dir_all(&cache_root)
            .with_context(|| format!("Failed to clear stale kit at {}", cache_root.display()))?;
    }
    fs::create_dir_all(&cache_root)
        .with_context(|| format!("Failed to create {}", cache_root.display()))?;
    for entry in EmbeddedKit::iter() {
        let file = EmbeddedKit::get(&entry)
            .ok_or_else(|| anyhow!("Embedded kit file missing during extraction: {entry}"))?;
        let dest = cache_root.join(entry.as_ref());
        if let Some(parent) = dest.parent() {
            fs::create_dir_all(parent)
                .with_context(|| format!("Failed to create {}", parent.display()))?;
        }
        fs::write(&dest, &file.data)
            .with_context(|| format!("Failed to write {}", dest.display()))?;
    }
    fs::write(&hash_file, &new_hash)
        .with_context(|| format!("Failed to write {}", hash_file.display()))?;
    debug!("Extracted embedded sbx-kit to {}", cache_root.display());
    Ok(cache_root)
 }
 fn compute_kit_hash() -> Result<String> {
    let mut hasher = Sha256::new();
    let mut entries: Vec<_> = EmbeddedKit::iter().collect();
    entries.sort();
    for entry in &entries {
        let file = EmbeddedKit::get(entry)
            .ok_or_else(|| anyhow!("Embedded kit file missing during hash: {entry}"))?;
        hasher.update(entry.as_bytes());
        hasher.update(b"\0");
        hasher.update(&file.data);
    }
    Ok(format!("{:x}", hasher.finalize()))
 }
 fn extract_vault_mixin(provider: &SupportedProvider) -> Result<Option<DiscoveredMixin>> {
    let provider_dir = match provider {
        SupportedProvider::Local { .. } => return Ok(None),
        SupportedProvider::AwsSecretsManager { .. } => "aws_secrets_manager",
        SupportedProvider::GcpSecretManager { .. } => "gcp_secret_manager",
        SupportedProvider::AzureKeyVault { .. } => "azure_key_vault",
        SupportedProvider::Gopass { .. } => "gopass",
        SupportedProvider::OnePassword { .. } => "one_password",
    };
    let cache_root = extract_vault_mixins_cache()?;
    let provider_root = cache_root.join(provider_dir);
    let spec_path = provider_root.join("spec.yaml");
    if !spec_path.exists() {
        bail!(
            "Embedded vault mixin for '{provider_dir}' is missing spec.yaml at {}",
            spec_path.display()
        );
    }
    let label = format!("<built-in: vault-{provider_dir}>");
    let (install_count, domain_count) = mixins::summarize(&spec_path)?;
    Ok(Some(DiscoveredMixin {
        path: provider_root,
        label,
        install_count,
        domain_count,
    }))
 }
 fn extract_vault_mixins_cache() -> Result<PathBuf> {
    let cache_root = paths::sbx_vault_mixins_dir();
    let new_hash = compute_vault_mixins_hash()?;
    let hash_file = paths::sbx_vault_mixins_hash_file();
    if let Ok(existing) = fs::read_to_string(&hash_file)
        && existing == new_hash
    {
        return Ok(cache_root);
    }
    if cache_root.exists() {
        fs::remove_dir_all(&cache_root).with_context(|| {
            format!(
                "Failed to clear stale vault mixins at {}",
                cache_root.display()
            )
        })?;
    }
    fs::create_dir_all(&cache_root)
        .with_context(|| format!("Failed to create {}", cache_root.display()))?;
    for entry in EmbeddedVaultMixins::iter() {
        let file = EmbeddedVaultMixins::get(&entry).ok_or_else(|| {
            anyhow!("Embedded vault mixin file missing during extraction: {entry}")
        })?;
        let dest = cache_root.join(entry.as_ref());
        if let Some(parent) = dest.parent() {
            fs::create_dir_all(parent)
                .with_context(|| format!("Failed to create {}", parent.display()))?;
        }
        fs::write(&dest, &file.data)
            .with_context(|| format!("Failed to write {}", dest.display()))?;
    }
    fs::write(&hash_file, &new_hash)
        .with_context(|| format!("Failed to write {}", hash_file.display()))?;
    debug!(
        "Extracted embedded sbx-vault-mixins to {}",
        cache_root.display()
    );
    Ok(cache_root)
 }
 fn compute_vault_mixins_hash() -> Result<String> {
    let mut hasher = Sha256::new();
    let mut entries: Vec<_> = EmbeddedVaultMixins::iter().collect();
    entries.sort();
    for entry in &entries {
        let file = EmbeddedVaultMixins::get(entry)
            .ok_or_else(|| anyhow!("Embedded vault mixin file missing during hash: {entry}"))?;
        hasher.update(entry.as_bytes());
        hasher.update(b"\0");
        hasher.update(&file.data);
    }
    Ok(format!("{:x}", hasher.finalize()))
 }
 fn sandbox_exists(name: &str) -> Result<bool> {
    let (success, stdout, stderr) =
        run_command_with_output(SBX_BINARY, &["ls"], None).context("Failed to run `sbx ls`")?;
    if !success {
        bail!("`sbx ls` failed: {stderr}");
    }
    Ok(stdout
        .lines()
        .skip(1)
        .any(|line| line.split_whitespace().next() == Some(name)))
 }
 fn create_sandbox(name: &str, kit_path: &Path, mixins: &[DiscoveredMixin]) -> Result<()> {
    info!("Creating sandbox '{name}'");
    let args = build_create_args(name, kit_path, mixins)?;
    let status = Command::new(SBX_BINARY)
        .args(&args)
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .status()
        .context("Failed to spawn `sbx create`")?;
    if !status.success() {
        bail!("`sbx create` exited with {status}");
    }
    Ok(())
 }
 fn build_create_args(
    name: &str,
    kit_path: &Path,
    mixins: &[DiscoveredMixin],
 ) -> Result<Vec<String>> {
    let kit_str = kit_path
        .to_str()
        .ok_or_else(|| anyhow!("Kit path is not valid UTF-8: {}", kit_path.display()))?;
    let mut args = vec![
        "create".to_string(),
        "--kit".to_string(),
        kit_str.to_string(),
    ];
    for mixin in mixins {
        let mixin_str = mixin
            .path
            .to_str()
            .ok_or_else(|| anyhow!("Mixin path is not valid UTF-8: {}", mixin.path.display()))?;
        args.push("--kit".to_string());
        args.push(mixin_str.to_string());
    }
    args.push(SANDBOX_AGENT.to_string());
    args.push("--name".to_string());
    args.push(name.to_string());
    args.push(".".to_string());
    Ok(args)
 }
 fn copy_host_files(name: &str) -> Result<()> {
    let config_dir = paths::config_dir();
    let home_dir = dirs::home_dir().context("Could not determine home directory")?;
    if config_dir.exists() {
        ensure_sandbox_dir(name, "/home/agent/.config")?;
        let src = format!("{}/", config_dir.display());
        let dest = format!("{name}:/home/agent/.config/");
        sbx_cp(&src, &dest)?;
    } else {
        debug!(
            "Skipping config copy: {} does not exist",
            config_dir.display()
        );
    }
    match resolve_vault_password_file() {
        Some(password_file) if password_file.exists() => {
            let dest_path = host_to_sandbox_path(&password_file, &home_dir, cfg!(windows))?;
            if let Some(parent) = sandbox_path_parent(&dest_path)
                && !parent.is_empty()
            {
                ensure_sandbox_dir(name, parent)?;
            }
            let dest = format!("{name}:{dest_path}");
            sbx_cp(&password_file.display().to_string(), &dest)?;
        }
        Some(password_file) => {
            debug!(
                "Skipping vault password copy: {} does not exist",
                password_file.display()
            );
        }
        None => {
            debug!("Skipping vault password copy: no local vault provider configured");
        }
    }
    Ok(())
 }
 fn host_to_sandbox_path(
    host_path: &Path,
    home_dir: &Path,
    is_windows_host: bool,
 ) -> Result<String> {
    let host_str = host_path.to_str().context("Host path is not valid UTF-8")?;
    let home_str = home_dir
        .to_str()
        .context("Home directory is not valid UTF-8")?;
    if let Some(rel) = strip_host_home(host_str, home_str) {
        let unixified = rel.replace('\\', "/");
        return Ok(format!("/home/agent/{unixified}"));
    }
    if is_windows_host {
        bail!(
            "Path '{host_str}' is outside your Windows user profile ({home_str}). \
             Sandbox mode cannot copy files from outside %USERPROFILE% into a Linux \
             sandbox. Move the file under your user profile and update your config \
             accordingly."
        );
    }
    Ok(host_str.to_string())
 }
 fn strip_host_home(path: &str, home: &str) -> Option<String> {
    let path_norm: String = path
        .chars()
        .map(|c| if c == '\\' { '/' } else { c })
        .collect();
    let home_norm: String = home
        .chars()
        .map(|c| if c == '\\' { '/' } else { c })
        .collect();
    let home_norm = home_norm.trim_end_matches('/');
    if home_norm.is_empty() || path_norm.len() <= home_norm.len() {
        return None;
    }
    let (head, tail) = path_norm.split_at(home_norm.len());
    if head != home_norm || !tail.starts_with('/') {
        return None;
    }
    Some(tail[1..].to_string())
 }
 fn sandbox_path_parent(linux_path: &str) -> Option<&str> {
    linux_path.rsplit_once('/').map(|(parent, _)| parent)
 }
 fn ensure_sandbox_dir(sandbox: &str, dir: &str) -> Result<()> {
    let dir_q = shell_words::quote(dir);
    let cmd = format!("sudo mkdir -p {dir_q} && sudo chown agent:agent {dir_q}");
    debug!("sbx exec {sandbox}: {cmd}");
    let status = Command::new(SBX_BINARY)
        .args(["exec", sandbox, "sh", "-c", &cmd])
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .status()
        .context("Failed to spawn `sbx exec` to prepare destination directory")?;
    if !status.success() {
        bail!("Preparing sandbox directory '{dir}' failed: sbx exec exited with {status}");
    }
    Ok(())
 }
 fn resolve_vault_password_file() -> Option<PathBuf> {
    Vault::init_bare().ok()?.local_password_file().ok()
 }
 fn sbx_cp(src: &str, dest: &str) -> Result<()> {
    debug!("sbx cp {src} {dest}");
    let status = Command::new(SBX_BINARY)
        .args(["cp", src, dest])
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .status()
        .context("Failed to spawn `sbx cp`")?;
    if !status.success() {
        bail!("`sbx cp {src} {dest}` exited with {status}");
    }
    Ok(())
 }
 fn exec_run(name: &str, kit_path: &Path) -> Result<()> {
    let kit_str = kit_path
        .to_str()
        .ok_or_else(|| anyhow!("Kit path is not valid UTF-8: {}", kit_path.display()))?;
    let status = Command::new(SBX_BINARY)
        .args(["run", name, "--kit", kit_str])
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .status()
        .context("Failed to spawn `sbx run`")?;
    if !status.success() {
        bail!("`sbx run` exited with {status}");
    }
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn sanitize_name_lowercases() {
        assert_eq!(sanitize_name("Foo"), "foo");
    }
    #[test]
    fn sanitize_name_replaces_non_alphanumeric() {
        assert_eq!(sanitize_name("hello world!"), "hello-world");
    }
    #[test]
    fn sanitize_name_collapses_dash_runs() {
        assert_eq!(sanitize_name("a___b"), "a-b");
    }
    #[test]
    fn sanitize_name_trims_dashes() {
        assert_eq!(sanitize_name("---hi---"), "hi");
    }
    #[test]
    fn sanitize_name_handles_mixed_input() {
        assert_eq!(sanitize_name("My Project (v2)"), "my-project-v2");
    }
    #[test]
    fn sanitize_name_all_invalid_yields_empty() {
        assert_eq!(sanitize_name("///"), "");
    }
    #[test]
    fn resolve_name_uses_explicit_arg() {
        let n = resolve_name(Some("explicit-name".to_string())).unwrap();
        assert_eq!(n, "explicit-name");
    }
    #[test]
    fn resolve_name_sanitizes_explicit_arg() {
        let n = resolve_name(Some("My Sandbox!".to_string())).unwrap();
        assert_eq!(n, "my-sandbox");
    }
    #[test]
    fn resolve_name_rejects_empty_after_sanitize() {
        let err = resolve_name(Some("///".to_string()));
        assert!(err.is_err());
    }
    #[test]
    fn resolve_name_falls_back_to_cwd_when_none() {
        let n = resolve_name(None).unwrap();
        assert!(!n.is_empty());
        assert!(n.chars().all(|c| c.is_ascii_alphanumeric() || c == '-'));
    }
    #[test]
    fn compute_kit_hash_is_deterministic() {
        let h1 = compute_kit_hash().unwrap();
        let h2 = compute_kit_hash().unwrap();
        assert_eq!(h1, h2);
        assert_eq!(h1.len(), 64);
    }
    #[test]
    fn build_create_args_emits_base_kit_before_mixins() {
        let kit = PathBuf::from("/cache/sbx-kit");
        let mixins = vec![
            DiscoveredMixin {
                path: PathBuf::from("/cfg/sbx-mixin.yaml"),
                label: "user".into(),
                install_count: 0,
                domain_count: 0,
            },
            DiscoveredMixin {
                path: PathBuf::from("/cfg/agents/sql/sbx-mixin.yaml"),
                label: "sql".into(),
                install_count: 0,
                domain_count: 0,
            },
        ];
        let args = build_create_args("my-box", &kit, &mixins).unwrap();
        assert_eq!(
            args,
            vec![
                "create".to_string(),
                "--kit".to_string(),
                "/cache/sbx-kit".to_string(),
                "--kit".to_string(),
                "/cfg/sbx-mixin.yaml".to_string(),
                "--kit".to_string(),
                "/cfg/agents/sql/sbx-mixin.yaml".to_string(),
                "coyote".to_string(),
                "--name".to_string(),
                "my-box".to_string(),
                ".".to_string(),
            ]
        );
    }
    #[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();
        assert_eq!(
            args,
            vec![
                "create".to_string(),
                "--kit".to_string(),
                "/cache/sbx-kit".to_string(),
                "coyote".to_string(),
                "--name".to_string(),
                "box".to_string(),
                ".".to_string(),
            ]
        );
    }
    mod vault_mixins {
        use super::*;
        use gman::providers::aws_secrets_manager::AwsSecretsManagerProvider;
        use gman::providers::azure_key_vault::AzureKeyVaultProvider;
        use gman::providers::gcp_secret_manager::GcpSecretManagerProvider;
        use gman::providers::gopass::GopassProvider;
        use gman::providers::local::LocalProvider;
        use gman::providers::one_password::OnePasswordProvider;
        use serial_test::serial;
        #[test]
        fn returns_none_for_local() {
            let p = SupportedProvider::Local {
                provider_def: LocalProvider::default(),
            };
            assert!(extract_vault_mixin(&p).unwrap().is_none());
        }
        #[test]
        #[serial]
        fn returns_some_for_aws() {
            let p = SupportedProvider::AwsSecretsManager {
                provider_def: AwsSecretsManagerProvider {
                    aws_profile: None,
                    aws_region: None,
                },
            };
            let m = extract_vault_mixin(&p)
                .unwrap()
                .expect("expected vault mixin");
            assert!(m.path.join("spec.yaml").exists());
            assert!(m.label.contains("aws_secrets_manager"));
        }
        #[test]
        #[serial]
        fn returns_some_for_gcp() {
            let p = SupportedProvider::GcpSecretManager {
                provider_def: GcpSecretManagerProvider {
                    gcp_project_id: None,
                },
            };
            let m = extract_vault_mixin(&p)
                .unwrap()
                .expect("expected vault mixin");
            assert!(m.path.join("spec.yaml").exists());
            assert!(m.label.contains("gcp_secret_manager"));
        }
        #[test]
        #[serial]
        fn returns_some_for_one_password() {
            let p = SupportedProvider::OnePassword {
                provider_def: OnePasswordProvider {
                    vault: None,
                    account: None,
                },
            };
            let m = extract_vault_mixin(&p)
                .unwrap()
                .expect("expected vault mixin");
            assert!(m.path.join("spec.yaml").exists());
            assert!(m.label.contains("one_password"));
        }
        #[test]
        #[serial]
        fn returns_some_for_azure() {
            let p = SupportedProvider::AzureKeyVault {
                provider_def: AzureKeyVaultProvider { vault_name: None },
            };
            let m = extract_vault_mixin(&p)
                .unwrap()
                .expect("expected vault mixin");
            assert!(m.path.join("spec.yaml").exists());
            assert!(m.label.contains("azure_key_vault"));
        }
        #[test]
        #[serial]
        fn returns_some_for_gopass() {
            let p = SupportedProvider::Gopass {
                provider_def: GopassProvider { store: None },
            };
            let m = extract_vault_mixin(&p)
                .unwrap()
                .expect("expected vault mixin");
            assert!(m.path.join("spec.yaml").exists());
            assert!(m.label.contains("gopass"));
        }
        #[test]
        fn hash_is_deterministic() {
            let h1 = compute_vault_mixins_hash().unwrap();
            let h2 = compute_vault_mixins_hash().unwrap();
            assert_eq!(h1, h2);
            assert_eq!(h1.len(), 64);
        }
    }
    mod host_to_sandbox_path_tests {
        use super::*;
        #[test]
        fn linux_under_home() {
            let dest = host_to_sandbox_path(
                Path::new("/home/atusa/.coyote_password"),
                Path::new("/home/atusa"),
                false,
            )
            .unwrap();
            assert_eq!(dest, "/home/agent/.coyote_password");
        }
        #[test]
        fn linux_nested_under_home() {
            let dest = host_to_sandbox_path(
                Path::new("/home/atusa/.config/coyote/.password"),
                Path::new("/home/atusa"),
                false,
            )
            .unwrap();
            assert_eq!(dest, "/home/agent/.config/coyote/.password");
        }
        #[test]
        fn linux_outside_home_returns_verbatim() {
            let dest = host_to_sandbox_path(
                Path::new("/etc/coyote/.password"),
                Path::new("/home/atusa"),
                false,
            )
            .unwrap();
            assert_eq!(dest, "/etc/coyote/.password");
        }
        #[test]
        fn macos_under_home_with_spaces() {
            let dest = host_to_sandbox_path(
                Path::new("/Users/atusa/Library/Application Support/coyote/.password"),
                Path::new("/Users/atusa"),
                false,
            )
            .unwrap();
            assert_eq!(
                dest,
                "/home/agent/Library/Application Support/coyote/.password"
            );
        }
        #[test]
        fn windows_under_home_converts_backslashes() {
            let dest = host_to_sandbox_path(
                Path::new(r"C:\Users\atusa\.coyote_password"),
                Path::new(r"C:\Users\atusa"),
                true,
            )
            .unwrap();
            assert_eq!(dest, "/home/agent/.coyote_password");
        }
        #[test]
        fn windows_nested_under_home() {
            let dest = host_to_sandbox_path(
                Path::new(r"C:\Users\atusa\Documents\my\vault.txt"),
                Path::new(r"C:\Users\atusa"),
                true,
            )
            .unwrap();
            assert_eq!(dest, "/home/agent/Documents/my/vault.txt");
        }
        #[test]
        fn windows_outside_home_bails_with_clear_error() {
            let err = host_to_sandbox_path(
                Path::new(r"C:\Program Files\Coyote\vault.txt"),
                Path::new(r"C:\Users\atusa"),
                true,
            )
            .unwrap_err();
            let msg = err.to_string();
            assert!(
                msg.contains("Program Files"),
                "error should name the offending path: {msg}"
            );
            assert!(
                msg.contains("user profile"),
                "error should explain the limitation: {msg}"
            );
        }
        #[test]
        fn windows_tolerates_trailing_slash_in_home() {
            let dest = host_to_sandbox_path(
                Path::new(r"C:\Users\atusa\foo"),
                Path::new(r"C:\Users\atusa\"),
                true,
            )
            .unwrap();
            assert_eq!(dest, "/home/agent/foo");
        }
        #[test]
        fn sandbox_path_parent_extracts_parent_for_nested() {
            assert_eq!(
                sandbox_path_parent("/home/agent/.coyote_password"),
                Some("/home/agent")
            );
            assert_eq!(
                sandbox_path_parent("/etc/coyote/.password"),
                Some("/etc/coyote")
            );
        }
        #[test]
        fn sandbox_path_parent_handles_edge_cases() {
            assert_eq!(sandbox_path_parent("/file"), Some(""));
            assert_eq!(sandbox_path_parent("noparent"), None);
        }
    }
 }
@@ -5,6 +5,7 @@ pub mod taskqueue;
 use crate::utils::AbortSignal;
 use fmt::{Debug, Formatter};
 use mailbox::Inbox;
 use parking_lot::RwLock;
 use taskqueue::TaskQueue;
 use anyhow::{Result, bail};
@@ -33,6 +34,7 @@ pub struct AgentHandle {
    pub inbox: Arc<Inbox>,
    pub abort_signal: AbortSignal,
    pub join_handle: JoinHandle<Result<AgentResult>>,
    pub child_supervisor: Option<Arc<RwLock<Supervisor>>>,
 }
 pub struct Supervisor {
@@ -103,6 +105,10 @@ impl Supervisor {
        self.handles.get(id).map(|h| &h.inbox)
    }
    pub fn abort_signal_for(&self, id: &str) -> Option<AbortSignal> {
        self.handles.get(id).map(|h| h.abort_signal.clone())
    }
    pub fn list_agents(&self) -> Vec<(&str, &str)> {
        self.handles
            .values()
@@ -115,6 +121,15 @@ impl Supervisor {
            handle.abort_signal.set_ctrlc();
        }
    }
    pub fn cancel_recursive(&self) {
        for handle in self.handles.values() {
            handle.abort_signal.set_ctrlc();
            if let Some(child_sup) = handle.child_supervisor.as_ref() {
                child_sup.read().cancel_recursive();
            }
        }
    }
 }
 impl Debug for Supervisor {
@@ -152,6 +167,7 @@ mod tests {
            inbox: Arc::new(Inbox::new()),
            abort_signal: create_abort_signal(),
            join_handle,
            child_supervisor: None,
        }
    }
@@ -1,60 +1,150 @@
 mod utils;
 use std::fs::read_to_string;
 use std::path::PathBuf;
 use crate::config::paths;
 pub use utils::create_vault_password_file;
 pub use utils::interpolate_secrets;
 pub use utils::prompt_provider_choice;
 use crate::cli::Cli;
 use crate::config::AppConfig;
 use crate::vault::utils::ensure_password_file_initialized;
-use anyhow::{Context, Result};
+use anyhow::{Context, Result, anyhow, bail};
 use fancy_regex::Regex;
 use gman::providers::SecretProvider;
 use gman::providers::SupportedProvider;
 use gman::providers::local::LocalProvider;
 use inquire::{Password, PasswordDisplayMode, required};
 use log::{info, warn};
 use serde_yaml::Value;
 use std::sync::{Arc, LazyLock};
 use tokio::runtime::Handle;
 use uuid::Uuid;
-pub static SECRET_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\{\{(.+)}}").unwrap());
+pub static SECRET_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\{\{([^{}]+)}}").unwrap());
 fn apply_sandboxed_home_translation(provider_def: &mut LocalProvider) {
    let Some(ref pf) = provider_def.password_file else {
        return;
    };
    if pf.exists() {
        return;
    }
    let Some(translated) = paths::translate_sandboxed_home_path(pf) else {
        return;
    };
    if !translated.exists() {
        return;
    }
    info!(
        "vault password file '{}' not found; resolved to sandboxed path '{}'",
        pf.display(),
        translated.display()
    );
    provider_def.password_file = Some(translated);
 }
 #[derive(Debug, Default, Clone)]
 pub struct Vault {
-    local_provider: LocalProvider,
+    pub(crate) provider: SupportedProvider,
 }
 pub type GlobalVault = Arc<Vault>;
 impl Vault {
-    pub fn init_bare() -> Self {
+    pub fn init_bare() -> Result<Self> {
-        let vault_password_file = AppConfig::default().vault_password_file();
+        let config_path = paths::config_file();
-        let local_provider = LocalProvider {
+        if !config_path.exists() {
-            password_file: Some(vault_password_file),
+            bail!(
                "Coyote config not found at {}. Run first-run setup before using the vault.",
                config_path.display()
            );
        }
        let content = read_to_string(&config_path)
            .with_context(|| format!("failed to read config at {}", config_path.display()))?;
        let value: Value = serde_yaml::from_str(&content)
            .with_context(|| format!("failed to parse config at {}", config_path.display()))?;
        let provider = match value.get("secrets_provider") {
            Some(v) if !v.is_null() => serde_yaml::from_value::<SupportedProvider>(v.clone())
                .with_context(|| "failed to parse 'secrets_provider' from config")?,
            _ => {
                let password_file = value
                    .get("vault_password_file")
                    .and_then(|v| v.as_str())
                    .map(PathBuf::from)
                    .unwrap_or_else(|| AppConfig::default().vault_password_file());
                SupportedProvider::Local {
                    provider_def: LocalProvider {
                        password_file: Some(password_file),
                        git_branch: None,
                        ..LocalProvider::default()
                    },
                }
            }
        };
-        Self { local_provider }
+        Ok(Self { provider })
    }
-    pub fn init(config: &AppConfig) -> Self {
+    pub fn default_local() -> Self {
-        let vault_password_file = config.vault_password_file();
+        Self {
-        let mut local_provider = LocalProvider {
+            provider: SupportedProvider::Local {
-            password_file: Some(vault_password_file),
+                provider_def: LocalProvider {
                    password_file: Some(AppConfig::default().vault_password_file()),
                    git_branch: None,
                    ..LocalProvider::default()
-        };
+                },
-
+            },
-        ensure_password_file_initialized(&mut local_provider)
+        }
            .expect("Failed to initialize password file");
        Self { local_provider }
    }
-    pub fn password_file(&self) -> Result<PathBuf> {
+    pub fn init(config: &AppConfig) -> Result<Self> {
-        self.local_provider
+        let mut provider = match &config.secrets_provider {
            Some(p) => p.clone(),
            None => SupportedProvider::Local {
                provider_def: LocalProvider {
                    password_file: Some(config.vault_password_file()),
                    ..LocalProvider::default()
                },
            },
        };
        if let SupportedProvider::Local { provider_def } = &mut provider {
            apply_sandboxed_home_translation(provider_def);
            ensure_password_file_initialized(provider_def)?;
        }
        Ok(Self { provider })
    }
    pub fn local_password_file(&self) -> Result<PathBuf> {
        match &self.provider {
            SupportedProvider::Local { provider_def } => provider_def
                .password_file
                .clone()
-            .with_context(|| "A password file is required for the local provider")
+                .with_context(|| "A password file is required for the local provider"),
            _ => Err(anyhow!(
                "password_file is only available for the local provider"
            )),
        }
    }
    fn provider_ref(&self) -> &dyn SecretProvider {
        match &self.provider {
            SupportedProvider::Local { provider_def } => provider_def,
            SupportedProvider::AwsSecretsManager { provider_def } => provider_def,
            SupportedProvider::GcpSecretManager { provider_def } => provider_def,
            SupportedProvider::AzureKeyVault { provider_def } => provider_def,
            SupportedProvider::Gopass { provider_def } => provider_def,
            SupportedProvider::OnePassword { provider_def } => provider_def,
        }
    }
    pub fn add_secret(&self, secret_name: &str) -> Result<()> {
@@ -66,7 +156,7 @@ impl Vault {
        let h = Handle::current();
        tokio::task::block_in_place(|| {
-            h.block_on(self.local_provider.set_secret(secret_name, &secret_value))
+            h.block_on(self.provider_ref().set_secret(secret_name, &secret_value))
        })?;
        println!("✓ Secret '{secret_name}' added to the vault.");
@@ -76,7 +166,7 @@ impl Vault {
    pub fn get_secret(&self, secret_name: &str, display_output: bool) -> Result<String> {
        let h = Handle::current();
        let secret = tokio::task::block_in_place(|| {
-            h.block_on(self.local_provider.get_secret(secret_name))
+            h.block_on(self.provider_ref().get_secret(secret_name))
        })?;
        if display_output {
@@ -95,7 +185,7 @@ impl Vault {
        let h = Handle::current();
        tokio::task::block_in_place(|| {
            h.block_on(
-                self.local_provider
+                self.provider_ref()
                    .update_secret(secret_name, &secret_value),
            )
        })?;
@@ -106,7 +196,7 @@ impl Vault {
    pub fn delete_secret(&self, secret_name: &str) -> Result<()> {
        let h = Handle::current();
-        tokio::task::block_in_place(|| h.block_on(self.local_provider.delete_secret(secret_name)))?;
+        tokio::task::block_in_place(|| h.block_on(self.provider_ref().delete_secret(secret_name)))?;
        println!("✓ Secret '{secret_name}' deleted from the vault.");
        Ok(())
@@ -115,7 +205,7 @@ impl Vault {
    pub fn list_secrets(&self, display_output: bool) -> Result<Vec<String>> {
        let h = Handle::current();
        let secrets =
-            tokio::task::block_in_place(|| h.block_on(self.local_provider.list_secrets()))?;
+            tokio::task::block_in_place(|| h.block_on(self.provider_ref().list_secrets()))?;
        if display_output {
            if secrets.is_empty() {
@@ -130,6 +220,67 @@ impl Vault {
        Ok(secrets)
    }
    pub fn auth_hint(&self) -> Option<&'static str> {
        match &self.provider {
            SupportedProvider::AwsSecretsManager { .. } => Some(
                "Try `aws sso login` (for SSO setups) or `aws configure` (for static keys), then retry.",
            ),
            SupportedProvider::GcpSecretManager { .. } => {
                Some("Try `gcloud auth application-default login`, then retry.")
            }
            SupportedProvider::AzureKeyVault { .. } => Some("Try `az login`, then retry."),
            SupportedProvider::Gopass { .. } => {
                Some("Make sure `gopass init` has been run and `gopass` is on your PATH.")
            }
            SupportedProvider::OnePassword { .. } => Some("Try `op signin`, then retry."),
            SupportedProvider::Local { .. } => None,
        }
    }
    pub fn validate_round_trip(&self) -> Result<()> {
        const PROBE_VALUE: &str = "ok";
        let probe_key = format!("coyote-setup-probe-{}", Uuid::new_v4().simple());
        let h = Handle::current();
        let result: Result<()> = tokio::task::block_in_place(|| {
            h.block_on(async {
                self.provider_ref()
                    .set_secret(&probe_key, PROBE_VALUE)
                    .await
                    .with_context(|| "vault write probe failed")?;
                let got = self
                    .provider_ref()
                    .get_secret(&probe_key)
                    .await
                    .with_context(|| "vault read probe failed")?;
                if got != PROBE_VALUE {
                    if let Err(cleanup_err) = self.provider_ref().delete_secret(&probe_key).await {
                        warn!("vault probe cleanup failed for key '{probe_key}': {cleanup_err}");
                    }
                    bail!("vault read probe returned an unexpected value");
                }
                self.provider_ref()
                    .delete_secret(&probe_key)
                    .await
                    .with_context(|| "vault delete probe failed")?;
                Ok(())
            })
        });
        result.with_context(|| {
            let base = "Vault validation failed. Check that your credentials have permission to create, read, and delete secrets in the configured backend.";
            match self.auth_hint() {
                Some(hint) => format!("{base}\n\nHint: {hint}"),
                None => base.to_string(),
            }
        })?;
        println!("✓ Vault validation succeeded.");
        Ok(())
    }
    pub fn handle_vault_flags(cli: Cli, vault: &Vault) -> Result<()> {
        if let Some(secret_name) = cli.add_secret {
            vault.add_secret(&secret_name)?;
@@ -193,6 +344,6 @@ mod tests {
    #[test]
    fn vault_default_creates_instance() {
        let vault = Vault::default();
-        assert!(vault.password_file().is_err());
+        assert!(vault.local_password_file().is_err());
    }
 }
@@ -2,11 +2,20 @@ use crate::config::ensure_parent_exists;
 use crate::vault::{SECRET_RE, Vault};
 use anyhow::Result;
 use anyhow::anyhow;
 use gman::SecretError;
 use gman::providers::SupportedProvider;
 use gman::providers::aws_secrets_manager::AwsSecretsManagerProvider;
 use gman::providers::azure_key_vault::AzureKeyVaultProvider;
 use gman::providers::gcp_secret_manager::GcpSecretManagerProvider;
 use gman::providers::gopass::GopassProvider;
 use gman::providers::local::LocalProvider;
 use gman::providers::one_password::OnePasswordProvider;
 use indoc::formatdoc;
 use inquire::validator::Validation;
-use inquire::{Confirm, Password, PasswordDisplayMode, Text, min_length, required};
+use inquire::{Confirm, Password, PasswordDisplayMode, Select, Text, min_length, required};
-use std::path::PathBuf;
+use log::debug;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 pub fn ensure_password_file_initialized(local_provider: &mut LocalProvider) -> Result<()> {
    let vault_password_file = local_provider
@@ -34,8 +43,14 @@ pub fn ensure_password_file_initialized(local_provider: &mut LocalProvider) -> R
 }
 pub fn create_vault_password_file(vault: &mut Vault) -> Result<()> {
-    let vault_password_file = vault
+    let SupportedProvider::Local {
-        .local_provider
+        provider_def: local_provider,
    } = &mut vault.provider
    else {
        return Ok(());
    };
    let vault_password_file = local_provider
        .password_file
        .clone()
        .ok_or_else(|| anyhow!("Password file is not configured"))?;
@@ -77,6 +92,7 @@ pub fn create_vault_password_file(vault: &mut Vault) -> Result<()> {
        match password {
            Ok(pw) => {
                std::fs::write(&vault_password_file, pw.as_bytes())?;
                set_password_file_permissions(&vault_password_file)?;
                println!(
                    "✓ Password file '{}' updated.",
                    vault_password_file.display()
@@ -148,7 +164,8 @@ pub fn create_vault_password_file(vault: &mut Vault) -> Result<()> {
        match password {
            Ok(pw) => {
                std::fs::write(&password_file, pw.as_bytes())?;
-                vault.local_provider.password_file = Some(password_file);
+                set_password_file_permissions(&password_file)?;
                local_provider.password_file = Some(password_file);
                println!(
                    "✓ Password file '{}' created.",
                    vault_password_file.display()
@@ -165,24 +182,233 @@ pub fn create_vault_password_file(vault: &mut Vault) -> Result<()> {
    Ok(())
 }
-pub fn interpolate_secrets(content: &str, vault: &Vault) -> (String, Vec<String>) {
+pub fn prompt_provider_choice() -> Result<Option<SupportedProvider>> {
    let choices = vec![
        "local - encrypted file on this machine",
        "aws_secrets_manager - AWS Secrets Manager",
        "gcp_secret_manager - Google Cloud Secret Manager",
        "azure_key_vault - Azure Key Vault",
        "gopass - gopass password manager (requires the `gopass` CLI)",
        "one_password - 1Password (requires the `op` CLI)",
    ];
    let choice = Select::new("Which secrets provider would you like to use?", choices)
        .with_starting_cursor(0)
        .prompt()?;
    if choice.starts_with("local") {
        return Ok(None);
    }
    let provider = if choice.starts_with("aws_secrets_manager") {
        prompt_aws_provider()?
    } else if choice.starts_with("gcp_secret_manager") {
        prompt_gcp_provider()?
    } else if choice.starts_with("azure_key_vault") {
        prompt_azure_provider()?
    } else if choice.starts_with("gopass") {
        prompt_gopass_provider()?
    } else if choice.starts_with("one_password") {
        prompt_one_password_provider()?
    } else {
        return Err(anyhow!("unexpected provider choice: {choice}"));
    };
    Ok(Some(provider))
 }
 fn prompt_aws_provider() -> Result<SupportedProvider> {
    let aws_profile = Text::new("AWS profile name:")
        .with_default("default")
        .with_validator(required!())
        .with_help_message("From your ~/.aws/config and ~/.aws/credentials")
        .prompt()?;
    let aws_region = Text::new("AWS region:")
        .with_default("us-east-1")
        .with_validator(required!())
        .with_help_message("Where your secrets live (e.g. us-east-1, eu-west-2)")
        .prompt()?;
    advisory_preflight(
        "AWS",
        "aws",
        &["sts", "get-caller-identity", "--profile", &aws_profile],
    );
    Ok(SupportedProvider::AwsSecretsManager {
        provider_def: AwsSecretsManagerProvider {
            aws_profile: Some(aws_profile),
            aws_region: Some(aws_region),
        },
    })
 }
 fn prompt_gcp_provider() -> Result<SupportedProvider> {
    let gcp_project_id = Text::new("GCP project ID:")
        .with_validator(required!())
        .with_help_message("The project that hosts your Secret Manager secrets")
        .prompt()?;
    advisory_preflight(
        "GCP",
        "gcloud",
        &["auth", "application-default", "print-access-token"],
    );
    Ok(SupportedProvider::GcpSecretManager {
        provider_def: GcpSecretManagerProvider {
            gcp_project_id: Some(gcp_project_id),
        },
    })
 }
 fn prompt_azure_provider() -> Result<SupportedProvider> {
    let vault_name = Text::new("Azure Key Vault name:")
        .with_validator(required!())
        .with_help_message("Just the vault name; the https endpoint is auto-derived")
        .prompt()?;
    advisory_preflight("Azure", "az", &["account", "show"]);
    Ok(SupportedProvider::AzureKeyVault {
        provider_def: AzureKeyVaultProvider {
            vault_name: Some(vault_name),
        },
    })
 }
 fn prompt_gopass_provider() -> Result<SupportedProvider> {
    let store_raw = Text::new("gopass store (leave blank for default):").prompt()?;
    let store = match store_raw.trim() {
        "" => None,
        s => Some(s.to_string()),
    };
    required_cli_preflight("gopass", "gopass", "https://www.gopass.pw/");
    Ok(SupportedProvider::Gopass {
        provider_def: GopassProvider { store },
    })
 }
 fn prompt_one_password_provider() -> Result<SupportedProvider> {
    let vault_raw = Text::new("1Password vault (leave blank for default):").prompt()?;
    let vault = match vault_raw.trim() {
        "" => None,
        s => Some(s.to_string()),
    };
    let account_raw = Text::new("1Password account (leave blank for default):").prompt()?;
    let account = match account_raw.trim() {
        "" => None,
        s => Some(s.to_string()),
    };
    required_cli_preflight(
        "1Password CLI",
        "op",
        "https://developer.1password.com/docs/cli/",
    );
    Ok(SupportedProvider::OnePassword {
        provider_def: OnePasswordProvider { vault, account },
    })
 }
 fn advisory_preflight(label: &str, cli: &str, args: &[&str]) {
    match Command::new(cli).args(args).output() {
        Ok(out) if out.status.success() => {
            println!("✓ {label} authentication check succeeded.");
        }
        Ok(out) => {
            let stderr = String::from_utf8_lossy(&out.stderr);
            eprintln!("⚠️  {label} preflight returned non-zero:");
            if !stderr.trim().is_empty() {
                eprintln!("    {}", stderr.trim());
            }
            eprintln!("    Setup will continue. Fix authentication before using --add-secret etc.");
        }
        Err(_) => {
            eprintln!(
                "⚠️  `{cli}` CLI not found on PATH. Coyote will still try the {label} SDK directly via standard credentials (env vars, instance metadata, service-account JSON, etc.)."
            );
        }
    }
 }
 fn required_cli_preflight(label: &str, cli: &str, install_url: &str) {
    match Command::new(cli).arg("--version").output() {
        Ok(out) if out.status.success() => {
            println!("✓ {label} is installed and reachable.");
        }
        Ok(_) => {
            eprintln!(
                "⚠️  `{cli} --version` returned non-zero. Your {label} install may be broken — verify before using the vault."
            );
        }
        Err(_) => {
            eprintln!("⚠️  `{cli}` not found on PATH.");
            eprintln!(
                "    The {label} secrets provider requires it. Install from {install_url} before running --add-secret etc."
            );
        }
    }
 }
 pub fn interpolate_secrets(content: &str, vault: &Vault) -> Result<(String, Vec<String>)> {
    interpolate_secrets_with(content, vault.auth_hint(), |name| {
        vault.get_secret(name, false)
    })
 }
 fn interpolate_secrets_with<F>(
    content: &str,
    auth_hint: Option<&'static str>,
    mut get_secret: F,
 ) -> Result<(String, Vec<String>)>
 where
    F: FnMut(&str) -> Result<String>,
 {
    let mut missing_secrets = vec![];
    let mut fatal_error: Option<anyhow::Error> = None;
    let parsed_content: String = content
        .lines()
        .map(|line| {
-            if line.trim_start().starts_with('#') {
+            if line.trim_start().starts_with('#') || fatal_error.is_some() {
                return line.to_string();
            }
            SECRET_RE
                .replace_all(line, |caps: &fancy_regex::Captures<'_>| {
-                    let secret = vault.get_secret(caps[1].trim(), false);
+                    if fatal_error.is_some() {
-                    match secret {
+                        return String::new();
                        Ok(s) => s,
                        Err(_) => {
                            missing_secrets.push(caps[1].to_string());
                            "".to_string()
                    }
                    let name = caps[1].trim();
                    match get_secret(name) {
                        Ok(s) => s,
                        Err(e) => match e.downcast_ref::<SecretError>() {
                            Some(SecretError::NotFound { .. }) => {
                                missing_secrets.push(name.to_string());
                                String::new()
                            }
                            Some(SecretError::AuthFailed { .. }) => {
                                let base =
                                    format!("Failed to fetch secret '{name}' from vault: {e}");
                                let msg = match auth_hint {
                                    Some(hint) => format!("{base}\n\nHint: {hint}"),
                                    None => base,
                                };
                                fatal_error = Some(anyhow!("{msg}"));
                                String::new()
                            }
                            _ => {
                                fatal_error = Some(anyhow!(
                                    "Failed to fetch secret '{name}' from vault: {e}"
                                ));
                                String::new()
                            }
                        },
                    }
                })
                .to_string()
@@ -190,5 +416,205 @@ pub fn interpolate_secrets(content: &str, vault: &Vault) -> (String, Vec<String>
        .collect::<Vec<_>>()
        .join("\n");
-    (parsed_content, missing_secrets)
+    if let Some(err) = fatal_error {
        return Err(err);
    }
    Ok((parsed_content, missing_secrets))
 }
 #[cfg(unix)]
 fn set_password_file_permissions(path: &Path) -> Result<()> {
    use std::os::unix::fs::PermissionsExt;
    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).map_err(|e| {
        anyhow!(
            "Failed to set 0600 permissions on '{}': {e}",
            path.display()
        )
    })
 }
 #[cfg(not(unix))]
 fn set_password_file_permissions(_path: &Path) -> Result<()> {
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use anyhow::Error;
    use std::cell::RefCell;
    fn not_found(name: &str) -> Error {
        Error::new(SecretError::NotFound {
            key: name.to_string(),
            provider: "test",
        })
    }
    fn auth_failed() -> Error {
        Error::new(SecretError::AuthFailed {
            provider: "test",
            source: anyhow!("auth failure"),
        })
    }
    struct Calls(RefCell<Vec<String>>);
    impl Calls {
        fn new() -> Self {
            Self(RefCell::new(Vec::new()))
        }
        fn record(&self, name: &str) {
            self.0.borrow_mut().push(name.to_string());
        }
        fn snapshot(&self) -> Vec<String> {
            self.0.borrow().clone()
        }
    }
    #[test]
    fn interpolates_single_secret_per_line() {
        let (out, missing) =
            interpolate_secrets_with("api_key={{API_KEY}}", None, |name| match name {
                "API_KEY" => Ok("sk-12345".to_string()),
                other => panic!("unexpected lookup: {other}"),
            })
            .unwrap();
        assert_eq!(out, "api_key=sk-12345");
        assert!(missing.is_empty());
    }
    #[test]
    fn regex_matches_each_secret_independently_when_one_per_line() {
        let calls = Calls::new();
        let (out, missing) = interpolate_secrets_with("{{ONE}}\nmiddle\n{{TWO}}", None, |name| {
            calls.record(name);
            Ok(name.to_lowercase())
        })
        .unwrap();
        assert_eq!(calls.snapshot(), vec!["ONE".to_string(), "TWO".to_string()]);
        assert_eq!(out, "one\nmiddle\ntwo");
        assert!(missing.is_empty());
    }
    #[test]
    fn skips_comment_lines() {
        let calls = Calls::new();
        let (out, missing) =
            interpolate_secrets_with("# api_key={{NEVER_FETCHED}}\nreal={{S}}", None, |name| {
                calls.record(name);
                Ok("v".to_string())
            })
            .unwrap();
        assert_eq!(out, "# api_key={{NEVER_FETCHED}}\nreal=v");
        assert!(missing.is_empty());
        assert_eq!(calls.snapshot(), vec!["S".to_string()]);
    }
    #[test]
    fn missing_secrets_become_empty_strings_and_are_reported() {
        let (out, missing) = interpolate_secrets_with(
            "a={{HAVE}}\nb={{MISSING_1}}\nc={{MISSING_2}}",
            None,
            |name| match name {
                "HAVE" => Ok("present".to_string()),
                missing => Err(not_found(missing)),
            },
        )
        .unwrap();
        assert_eq!(out, "a=present\nb=\nc=");
        assert_eq!(
            missing,
            vec!["MISSING_1".to_string(), "MISSING_2".to_string()]
        );
    }
    #[test]
    fn interpolates_multiple_secrets_on_same_line() {
        let calls = Calls::new();
        let (out, missing) = interpolate_secrets_with("url={{URL}} key={{KEY}}", None, |name| {
            calls.record(name);
            match name {
                "URL" => Ok("https://example.test".to_string()),
                "KEY" => Ok("sk-12345".to_string()),
                other => panic!("unexpected lookup: {other}"),
            }
        })
        .unwrap();
        assert_eq!(calls.snapshot(), vec!["URL".to_string(), "KEY".to_string()]);
        assert_eq!(out, "url=https://example.test key=sk-12345");
        assert!(missing.is_empty());
    }
    #[test]
    fn regex_rejects_braces_in_secret_names() {
        let calls = Calls::new();
        let (out, missing) =
            interpolate_secrets_with("literal {{ {NOT_A_NAME} }} text", None, |name| {
                calls.record(name);
                Ok(format!("got-{name}"))
            })
            .unwrap();
        assert!(
            calls.snapshot().is_empty(),
            "name with embedded braces must not match"
        );
        assert_eq!(out, "literal {{ {NOT_A_NAME} }} text");
        assert!(missing.is_empty());
    }
    #[test]
    fn fatal_failure_short_circuits_remaining_lines() {
        let calls = Calls::new();
        let result =
            interpolate_secrets_with("a={{S1}}\nb={{S2}}\nc={{S3}}\nd={{S4}}", None, |name| {
                calls.record(name);
                match name {
                    "S1" => Ok("first".to_string()),
                    "S2" => Err(auth_failed()),
                    other => Ok(format!("late-{other}")),
                }
            });
        let err = result.unwrap_err().to_string();
        assert!(
            err.contains("S2"),
            "error should name the offending secret, got: {err}"
        );
        assert_eq!(
            calls.snapshot(),
            vec!["S1".to_string(), "S2".to_string()],
            "lookups must stop at the failing secret - S3 and S4 should never be fetched"
        );
    }
    #[test]
    fn auth_failure_appends_hint_when_provided() {
        let result = interpolate_secrets_with(
            "k={{K}}",
            Some("run `coyote --authenticate` to reauth"),
            |_| Err(auth_failed()),
        );
        let err = result.unwrap_err().to_string();
        assert!(err.contains("Hint:"), "expected hint in error, got: {err}");
        assert!(
            err.contains("coyote --authenticate"),
            "expected hint contents, got: {err}"
        );
    }
 }