Merge branch 'main' of github.com:Dark-Alex-17/coyote

PLAN-rigor-surfaces: Rigor & Surfaces — Quality Calibration for the Architect/Sisyphus Suite

.gitattributes

@@ -0,0 +1 @@
+assets/config-template.yaml text eol=lf

.github/workflows/release.yaml

@@ -166,6 +166,9 @@ jobs:
             os: ubuntu-latest
             use-cross: true
             cargo-flags: ''
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-24.04-arm
+            cargo-flags: ''
           - target: aarch64-apple-darwin
             os: macos-latest
             use-cross: true
@@ -253,7 +256,7 @@ jobs:
         run: echo "BUILD_CMD=cross" >> $GITHUB_ENV
 
       - name: Install latest LLVM/Clang
-        if: matrix.os == 'ubuntu-latest'
+        if: startsWith(matrix.os, 'ubuntu')
         run: |
           wget https://apt.llvm.org/llvm.sh
           chmod +x llvm.sh

.gitignore

@@ -5,4 +5,7 @@
 .idea/
 /coyote.iml
 /.idea/
-.coyote
+.coyote/**
+.sisyphus/**
+.coyote-project.json
+.coyote/memory/

CHANGELOG.md

@@ -1,3 +1,196 @@
+## v0.10.0 (2026-08-29)
+
+### BREAKING CHANGE
+
+- invocations using --prompt <text> must switch to
+--temp-role <text>; clap rejects the old flag loudly.
+
+### Feat
+
+- Support Linux ARM64 GNU
+- Note that duckdb RAG driver is unavailable on MUSL Linux builds when initializing a RAG so users know when using the binary, not just based on docs
+- updated coyote installation scripts to detect when gnu is installable
+- upgraded to v2 mixin schema
+- improved first-time run experience and included a templated configuration file that now has comments like the config.example.yaml so users don't have to go to the repo to see all the knobs
+- **TASK-005**: carry the quality bar through sisyphus and architect
+- **TASK-004**: reviewer routing — code-reviewer quality-bar resolution, domain linter pass, surface-skill routing, rigor folding; file-reviewer surface-skill whitelist + convention/correctness marker
+- **TASK-003**: add surface skills batch B — worker-review, iac-review, migration-review, cicd-review
+- **TASK-002**: add surface skills batch A — rest-api-review, cli-review, library-review
+- **TASK-001**: add rigor/surfaces declaration layer to planning skills
+- **repl**: color .info mcp-server verdicts and complete only running servers
+- **cli**: rename mcp_config asset category to mcp-config with snake_case alias
+- create a new probe agent to probe code verifications using usage-pattern testing
+- Add in the web_search_coyote tool where helpful
+- **mcp**: add .info mcp-server, .set mcp_tools, and filtered-server listing to the REPL
+- **mcp**: enforce per-server tool allowlists across runtime, jobs, agents, and graph nodes
+- **mcp**: add mcp_tools allowlist config surfaces across roles, sessions, agents, graphs, and skills
+- **mcp**: add per-server tool allowlist policy module and allowedTools config field
+- support mcp.json in the root of bundle repos as well as in the legacy functions directory
+- prefer ~/.config/coyote/mcp.json for the user-scope MCP config
+- claude and openai native web search via web_search_coyote
+- **jobs**: node-local job ownership and capability-gated job__* visibility
+- **graph**: support max_concurrent_jobs at the graph level
+- **jobs**: allow uncapped collect via full_result
+- **jobs**: exempt polling tools from loop tracker and hint on unchanged checks
+- **supervisor**: push agent completion notifications to the spawning context
+- **jobs**: push background-job completion notifications via per-context queue
+- inject background-jobs prompt guidance when jobs are enabled
+- add background job runner, job__* handlers, and start gates
+- generalize supervisor registry to TaskHandle enum with job scaffolding, kill discipline, and max_concurrent_jobs config
+- run an advisory observability pass after implementation in sisyphus
+- add an observability-review skill for post-implementation monitoring analysis
+- check under- and over-logging in the code review gate
+- calibrate logging registers in the code-writing agents
+- add a logging-discipline skill for calibrating log output to repo conventions
+- **cli**: rename --prompt to --temp-role
+- complete --filter and --force on the first .install argument
+- **mcp**: bound tool-result passthrough and surface resource audience annotations
+- **mcp**: add mcp_prompt meta-tool and harden prompt display rendering
+- **repl**: add .prompt command with live staged tab-completion
+- **mcp**: add mcp_read meta-tool for resource reads
+- **mcp**: gate meta-function emission on advertised server capabilities
+- **mcp**: add render.rs content policy (text paging, pattern filter, blob spill)
+- **mcp**: extend the server catalog to resources, templates, and prompts
+- complete --filter and --force on the first .install argument
+- run design interviews as grilling frontier rounds across the planning agents
+- add a grilling skill for frontier-round design interviews
+- add an on-demand architecture-reviewer agent for deepening scans
+- add a codebase-design skill with the deep-module design vocabulary
+- add a feedback-loop-first diagnosing-bugs skill to the coding suite
+- add a Fowler code-smell baseline to the code-review skill
+- flag duplicate helpers in code reviews with a repo-wide DRY check
+- add a transactional-integrity review skill to the code review gate
+- add an operational-history prior-art lane to the code-reviewer agent
+- support name=value macro arguments with variable tab completion
+- add --help guides to the .install and .uninstall REPL commands
+- expand owner/repo shorthand for --install with a --git-host flag
+- remove the deprecated --install-from flag and .install remote form
+- rename install flags and unify .install dispatch
+- add --uninstall and .uninstall for installed bundles
+- add --update-bundle with provenance-aware conflict handling
+- add --list-bundles and .list bundles with drift detection
+- record bundle provenance when installing from remote repos
+- add bundle provenance store
+- parse bundle manifests and capture resolved SHAs for remote installs
+- created a new comment-discipline skill for the built in sisyphus suite
+- created a dedicated git_command tool to tighten tool calling permissions in the git-master skill
+- Added a new security review step to the code writing quality gates
+- addressed review comments
+- add --no-workspace-macros opt-out for workspace macro loading
+- execute non-isolated macros on the live REPL context
+- surface macros as first-class custom commands in the REPL
+- add lazy macro resolver with two-dir discovery and per-macro states
+- add enabled_macros config field at global, role, agent, and session levels
+- add description and isolated fields to Macro struct
+- Dynamically detect RAG embedding model dimension for any given model
+- Support auto confirmation for gatekeeper agents
+- retry LLM API calls once after 401 by force-refreshing the OAuth token
+- identity-aware rejected-token marker for LLM OAuth cache
+- typed ApiStatusError carrying HTTP status through LLM client errors
+- per-request OAuth token injection with mid-session refresh for HTTP MCP servers
+- reason-specific warnings for MCP servers that fail OAuth at startup
+- Installed duckdb into the coyote image
+- Support managing MCP servers from the CLI directly
+- append new built-in rag__query function to RAG contexts to allow further querying by LLMs
+- support static file bundling with sbx-mixins
+- **rag**: offer the storage driver when an agent initializes its RAG
+- simplified the duckdb selection prompt
+- **rag**: let several Coyote processes query one duckdb RAG at once
+- **rag**: support string and UUID Qdrant point IDs
+- **rag**: create the API key secret inline in the attach wizard
+- let workflow rag nodes select a RAG driver
+- improved wording and heuristic detection for sisyphus suite of agents
+- upgraded to sbx kit v2 spec for improved integration
+- **rag**: add attach-only Qdrant provider, attach wizard and sandbox wiring
+- **rag**: add DuckDB provider behind the RAG driver abstraction
+- **rag**: add driver/attached fields, validation floors and force-reingest
+- **mcp**: send RFC 8707 resource indicator in OAuth flows
+- Added loaded indicators to .list tools/mcp-servers/skills
+- hide .recover from tab completions when no session is active
+- add a new .recover command for sessions to recover from errors
+- integrated the git-ssh-sign kit into the coyote sandbox kit
+
+### Fix
+
+- Harden install scripts: detect libssl3 without ldconfig on PATH, survive noexec tmp dirs, and guard against partial curl|bash execution
+- ldconfig on Debian-based distros lives in /usr/sbin
+- Prefer GNU linux builds in install scripts for duckdb support, and gate duckdb support on linux hosts that are MUSL until MUSL support is added
+- **mcp**: omit declared-but-empty prompt/resource capabilities from .info mcp-server
+- **mcp**: annotate declared-but-empty prompt/resource capabilities in .info mcp-server
+- also support the .continue edge case for session crashing checkpointing
+- checkpoint sessions that crash for easy resuming
+- job__check ring buffer also collects file output for LLM_OUTPUT as well as stdout
+- **tools**: interactive-shell semantics and stderr capture in execute_command
+- **function**: gate test-only declaration appender behind cfg(test)
+- **graph**: gate unix-only test imports behind cfg(unix)
+- harden job runner lifecycle and whitelist conformance
+- **function**: floor tool-output truncation cut to a UTF-8 char boundary
+- **supervisor**: make agent__check a pure status probe that never consumes the handle
+- **supervisor**: surface finished-but-uncollected tasks in turn-end guardrail
+- fix grep "binary" errors when searching UTF-8 files with unicode characters like some of the Coyote source
+- **bundles**: harden the install pipeline for cross-platform correctness
+- **mcp**: harden the spill path for cross-platform correctness
+- **repl**: offer prompts in .list tab completion and rename its listing helpers
+- **mcp**: gate unix-only spill permission APIs for windows builds
+- harden the bundle lifecycle per code review
+- address code review findings on the bundle lifecycle
+- reserve category names, confirm fork-name collisions, report secrets on uninstall
+- make bundle provenance portable to Windows
+- user__ask should have been renamed to user__select in graph agent user interaction invocations
+- support tab completions for graph-based agents with variables as well as standard agents
+- surface macro parse errors on top-level invocation
+- render .list macros as a comfy-table instead of fixed-width columns
+- drain crossterm characters in zellij in kitty contexts to prevent DA1 responses from entering prompt
+- drain tty input when displaying inquire prompts to prevent unintentional escapes
+- breaking iwe MCP server changes with newest version
+- improved handling of non service-specific secrets using sbx custom-secrets
+- include tool output to LLM_OUTPUT in errors as well as stderr
+- prevent tmp-overwriting
+- Corrected a rare edge case on how tool files are generated during parallel executions
+- cosmetic fix after improved bash tool handling
+- Improved subagent escalation handling
+- latent parsing bugs in fs_patch and argc
+- Prevent infinite hangs in coder agent and implement timeouts for LLM API calls and interactive tools
+- allow nested italics inside bold spans in markdown renderer
+- properly handle OAuth refreshes
+- correct newline removal from fs_write and fs_patch
+- detect duplicate tool call IDs client-side before sending to Claude
+- **rag**: warn when a duckdb store is empty but files are indexed
+- **rag**: keep a local Qdrant off an ambient proxy
+- keep loopback and LAN traffic off an ambient proxy
+- **rag**: stop routing Qdrant requests through an ambient proxy
+- **rag**: treat a zero min_score as no floor on Qdrant searches
+- **rag**: address Copilot review findings on the driver abstraction
+- **rag**: delete the DuckDB write-ahead log alongside the store
+- **sandbox**: discover agent-scoped RAG mixin sidecars
+- **rag**: stop the attach wizard from silently accepting an empty collection
+- **rag**: fail loudly when a RAG's vault secret is missing
+- **rag**: serialize DuckDB extension installs to stop a Windows race
+- **rag**: emit an sbx kit v2 mixin and declare RAG credentials to the proxy
+- **rag**: install DuckDB vss and fts extensions when they are missing
+- don't output thinking blocks for claude-based models
+- additional edge case fix for duplicate tool call IDs in anthropic API calls
+- removed temperature modifier in librarian agent to mitigate invisible errors
+- strip reasoning blocks for structured LLM output in graph agents
+- prevent rare duplicate tool call IDs in long running claude prompts
+- agents inherit global reasoning effort if unset
+
+### Refactor
+
+- **function**: finish supervisor-to-agent vocabulary migration
+- **function**: rename agent-tool symbols out of supervisor vocabulary
+- Modified the naming of several generalized supervisor values
+- pulled out some imports to clean up the MCP render module a bit
+- **mcp**: centralize meta-function prefix predicates and fix list_tools pagination
+- Refactored some bundle const locations
+- drop the .install remote migration hint
+- drop the --install-from tombstone entirely
+- render .list agents and .list skills as comfy-tables
+- **rag**: discover driver_config secrets by grammar, not field name
+- **rag**: drop the hardcoded embedding model hint from attach
+- **rag**: interpolate every driver_config value, not just api_key
+- **rag**: extract RagProvider trait and add YamlProvider
+
 ## v0.8.3 (2026-08-03)
 
 ### Fix

CREDITS.md

@@ -1,5 +1,16 @@
 # Credits
 
+## Matt Pocock's Skills
+
+The bundled `diagnosing-bugs`, `codebase-design`, and `grilling` skills, the
+`architecture-reviewer` agent, and the code smell baseline in the bundled
+`code-review` skill are adapted from
+[mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock,
+licensed under the MIT License. The smell definitions trace back to Martin
+Fowler's *Refactoring* (ch. 3); the deep-module vocabulary builds on John
+Ousterhout's *A Philosophy of Software Design* and Michael Feathers'
+*Working Effectively with Legacy Code*.
+
 ## AIChat
 Coyote originally started as a fork of the fantastic
 [AIChat CLI](https://github.com/sigoden/aichat). The initial goal was simply

Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "coyote-ai"
-version = "0.8.3"
+version = "0.10.0"
 edition = "2024"
 authors = ["Alex Clarke <alex.j.tusa@gmail.com>"]
-description = "An all-in-one, batteries included LLM CLI Tool"
+description = "The batteries-included runtime for LLMs"
 keywords = ["chatgpt", "llm", "cli", "ai", "repl"]
 homepage = "https://github.com/Dark-Alex-17/coyote"
 repository = "https://github.com/Dark-Alex-17/coyote"
@@ -51,7 +51,13 @@ textwrap = "0.16.0"
 ansi_colours = "1.2.2"
 eventsource-stream = "0.2.3"
 log = "0.4.28"
-log4rs = { version = "1.4.0", features = ["file_appender", "rolling_file_appender", "compound_policy", "fixed_window_roller", "size_trigger"] }
+log4rs = { version = "1.4.0", features = [
+  "file_appender",
+  "rolling_file_appender",
+  "compound_policy",
+  "fixed_window_roller",
+  "size_trigger",
+] }
 shell-words = "1.1.0"
 sha2 = "0.10.8"
 unicode-width = "0.2.0"
@@ -84,7 +90,7 @@ duct = "1.0.0"
 argc = "1.23.0"
 strum_macros = "0.27.2"
 indoc = "2.0.6"
-rmcp = { version = "1.5.0", features = [
+rmcp = { version = "3.1.2", features = [
   "client",
   "transport-child-process",
   "transport-streamable-http-client-reqwest",
@@ -113,14 +119,7 @@ qrcode = "0.14"
 
 [dependencies.reqwest]
 version = "0.13.3"
-features = [
-  "json",
-  "multipart",
-  "stream",
-  "form",
-  "socks",
-  "rustls",
-]
+features = ["json", "multipart", "stream", "form", "socks", "rustls"]
 default-features = false
 
 [dependencies.syntect]
@@ -139,8 +138,13 @@ arboard = { version = "3.3.0", default-features = false, features = [
 [target.'cfg(not(any(target_os = "linux", target_os = "android", target_os = "emscripten")))'.dependencies]
 arboard = { version = "3.3.0", default-features = false }
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
 [dev-dependencies]
+ctor = "1.0.13"
 pretty_assertions = "1.4.0"
+rmcp = { version = "3.1.2", features = ["server"] }
 serial_test = "3"
 
 [[bin]]

Dockerfile

@@ -99,7 +99,7 @@ LABEL com.docker.sandboxes="templates" \
       com.docker.sandboxes.flavor="shell-docker" \
       com.docker.sandboxes.start-docker="true" \
       org.opencontainers.image.title="coyote" \
-      org.opencontainers.image.description="An all-in-one, batteries-included LLM CLI tool: Shell Assistant, CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros." \
+      org.opencontainers.image.description="The batteries-included runtime for LLMs: Shell Assistant, CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros." \
       org.opencontainers.image.source="https://github.com/Dark-Alex-17/coyote" \
       org.opencontainers.image.version="${COYOTE_VERSION}"
 

README.md

@@ -1,4 +1,4 @@
-# Coyote: All-in-one, batteries-included LLM CLI Tool
+# Coyote: The batteries-included runtime for LLMs
 
 ![Test](https://github.com/Dark-Alex-17/coyote/actions/workflows/ci.yaml/badge.svg)
 [![crates.io link](https://img.shields.io/crates/v/coyote-ai.svg)](https://crates.io/crates/coyote-ai)
@@ -6,14 +6,18 @@
 ![Crate.io downloads](https://img.shields.io/crates/d/coyote-ai?label=Crate%20downloads)
 [![GitHub Downloads](https://img.shields.io/github/downloads/Dark-Alex-17/coyote/total.svg?label=GitHub%20downloads)](https://github.com/Dark-Alex-17/coyote/releases)
 ![Docker pulls](https://img.shields.io/docker/pulls/darkalex17/coyote?label=Docker%20downloads)
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](./LICENSE)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://github.com/Dark-Alex-17/coyote/blob/main/LICENSE)
 
-Coyote is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistant, CLI & REPL Mode, RAG, AI Tools & 
-Agents, and More.
+Coyote is an **all-in-one, batteries-included LLM runtime** for building, running, and interacting with AI from your terminal.
+It brings together a Shell Assistant, CLI & REPL modes, RAG, tools, agents, MCP, skills, sandboxes, multi-agent workflows, and
+more in a single runtime.
+
+Coyote comes ready to use with built-in agents, roles, macros, and tools, so you can get started without assembling an AI
+stack from scratch. When you want to extend it, entire bundles of agents, roles, macros, tools, MCP servers, and other
+configurations can be installed directly from any Git repository.
+
+See [Bundles](https://github.com/Dark-Alex-17/coyote/wiki/Bundles) to learn how to create, install, and share Coyote bundles.
 
-It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Coyote 
-in as little time as possible. You can also install entire bundles of agents, roles, macros, tools, and MCP servers from 
-any git repository. See [Sharing Configurations](https://github.com/Dark-Alex-17/coyote/wiki/Sharing-Configurations) for more information.
 
 ![Agent example](https://raw.githubusercontent.com/wiki/Dark-Alex-17/coyote/images/agents/sql.gif)
 
@@ -23,7 +27,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
 * [AIChat Migration Guide](https://github.com/Dark-Alex-17/coyote/wiki/AIChat-Migration): Coming from AIChat? Follow the migration guide to get started.
 * [Installation](#install): Install Coyote
 * [Getting Started](#getting-started): Get started with Coyote by doing first-run setup steps.
-* [Sharing Configurations](https://github.com/Dark-Alex-17/coyote/wiki/Sharing-Configurations): Install bundles of agents, roles, macros, tools, and MCP servers from any git repo, and share your own.
+* [Bundles](https://github.com/Dark-Alex-17/coyote/wiki/Bundles): Install bundles of agents, roles, skills, macros, tools, and MCP servers from any git repo, and share your own. Bundles are Coyote's equivalent of plugins in other CLI agents.
 * [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.
@@ -35,8 +39,14 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
         * [Create Custom TypeScript Tools](https://github.com/Dark-Alex-17/coyote/wiki/Custom-Tools#custom-typescript-based-tools)
         * [Create Custom Bash Tools](https://github.com/Dark-Alex-17/coyote/wiki/Custom-Bash-Tools)
             * [Bash Prompt Utilities](https://github.com/Dark-Alex-17/coyote/wiki/Bash-Prompt-Helpers)
-* [First-Class MCP Server Support](https://github.com/Dark-Alex-17/coyote/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality.
-* [Macros](https://github.com/Dark-Alex-17/coyote/wiki/Macros): Automate repetitive tasks and workflows with Coyote "scripts" (macros).
+* [First-Class MCP Server Support](https://github.com/Dark-Alex-17/coyote/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality. Coyote supports all three MCP capabilities: tools, resources, and prompts.
+    * Models interact with each server through a compact set of capability-gated meta-tools: `mcp_search`/`mcp_describe` for discovery across tools, resources, and prompts, `mcp_invoke` for tool calls, `mcp_read` for paged and regex-filterable resource reads, and `mcp_prompt` for server-defined prompts. Binary content is spilled to disk instead of inlined, and oversized tool results are bounded before they reach the model.
+    * Invoke server prompts yourself with `.prompt <server> <name> [key=value ...]` in the REPL, with live staged tab-completion (servers, then prompt names, then `key=` arguments), and discover them with `.list prompts`.
+* [Macros](https://github.com/Dark-Alex-17/coyote/wiki/Macros): Automate repetitive tasks and workflows with Coyote "scripts" (macros). Macros are Coyote's custom commands: invoke any macro directly by name (e.g. `.review main`), with tab-completion, right alongside the built-in REPL commands.
+    * Give a macro a `description` (shown in `.list macros` and completions) and set `isolated: false` to run its steps on the live session, exactly as if you typed them. Note that non-isolated steps are recorded in the session, and mutating steps (`.role`, `.model`, ...) persist after the macro ends, by design. Steps are fail-fast: an error aborts the remaining steps, but completed steps' effects remain. A non-isolated macro step cannot invoke another macro, and a `.exit` step never exits the REPL.
+    * Commit project-specific macros to `.coyote/macros/` in your repo. They shadow same-named global macros (opt out with `--no-workspace-macros`).
+    * Pass variables positionally or by name: leading `name=value` args set declared variables directly (letting earlier variables keep their defaults), and remaining args fill the rest in order. Tab completion after a macro name lists each variable with its description and default.
+    * Scope which macros are invocable with `enabled_macros` in the global config, a role, an agent, or a session (most specific wins; an empty list disables all macros), and toggle at runtime with `.macro enable|disable <name>`.
 * [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]`.
@@ -45,6 +55,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
 * [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).
+* [Background Jobs](https://github.com/Dark-Alex-17/coyote/wiki/Background-Jobs): Run long tool calls (builds, test suites, slow MCP calls) in the background with the `job__*` tools while the model keeps working, and completion arrives as a push notification.
 * [Todo System](https://github.com/Dark-Alex-17/coyote/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models.
 * [Environment Variables](https://github.com/Dark-Alex-17/coyote/wiki/Environment-Variables): Override and customize your Coyote configuration at runtime with environment variables.
 * [Client Configurations](https://github.com/Dark-Alex-17/coyote/wiki/Clients): Configuration instructions for various LLM providers.
@@ -71,7 +82,7 @@ Coyote requires the following tools to be installed on your system:
     * **npm:** `npm i -g @ast-grep/cli`
     * Optional: if `ast-grep` is not installed, the `ast_grep` tool reports it and agents fall back to `fs_grep`
 * [duckdb](https://duckdb.org/) (for fast, local RAGs)
-    * `curl https://install.duckdb.org | sh`
+    * `curl https://install.duckdb.org | bash`
 
 These tools are used to provide various functionalities within Coyote, such as document processing, JSON manipulation,
 etc., and they are used within agents and tools.
@@ -256,7 +267,7 @@ coyote | Out-String | Invoke-Expression
 
 ### Shell Integration
 You can integrate Coyote's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the
-corresponding [shell integration script](./scripts/shell-integration) to your shell. Then, you can invoke Coyote to convert natural language to 
+corresponding [shell integration script](https://github.com/Dark-Alex-17/coyote/tree/main/scripts/shell-integration) to your shell. Then, you can invoke Coyote to convert natural language to 
 shell commands by pressing `Alt-e`. For example:
 
 ```shell
@@ -274,7 +285,7 @@ coyote --info | grep 'config_file' | awk '{print $2}'
 ```
 
 The configuration file consists of a number of settings. To see a full example configuration file with every setting
-defined, refer to the [example configuration file](./config.example.yaml).
+defined, refer to the [example configuration file](https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml).
 
 ### Default LLM
 The following settings are available to configure the default LLM that is used when you start Coyote, and its
@@ -328,7 +339,7 @@ The appearance of Coyote can be modified using the following settings:
 
 Coyote began as a fork of [AIChat CLI](https://github.com/sigoden/aichat) and has since evolved into an independent project.
 
-See [CREDITS.md](./CREDITS.md) for full attribution and background.
+See [CREDITS.md](https://github.com/Dark-Alex-17/coyote/blob/main/CREDITS.md) for full attribution and background.
 
 ---
 
@@ -339,11 +350,11 @@ See [CREDITS.md](./CREDITS.md) for full attribution and background.
 
 ## License
 
-Coyote is licensed under the [GNU Affero General Public License v3.0](./LICENSE)
+Coyote is licensed under the [GNU Affero General Public License v3.0](https://github.com/Dark-Alex-17/coyote/blob/main/LICENSE)
 (AGPL-3.0-only).
 
 Coyote began as a fork of [AIChat](https://github.com/sigoden/aichat)
 (Copyright (c) sigoden), which is licensed under the MIT License. Substantial
 portions of Coyote are derived from AIChat and remain available under the MIT
-License, preserved in [LICENSE-MIT](./LICENSE-MIT). See [NOTICE](./NOTICE) and
-[CREDITS.md](./CREDITS.md) for details.
+License, preserved in [LICENSE-MIT](https://github.com/Dark-Alex-17/coyote/blob/main/LICENSE-MIT). See [NOTICE](https://github.com/Dark-Alex-17/coyote/blob/main/NOTICE) and
+[CREDITS.md](https://github.com/Dark-Alex-17/coyote/blob/main/CREDITS.md) for details.

assets/agents/architect/config.yaml

@@ -3,9 +3,10 @@ description: |
   Design-doc orchestrator for any project. Consumes a high-level design doc, decomposes it into a
   gated plan (gatekeeper self-containedness + oracle plan-review) and ~1-engineer-day task files,
   spawns one Sisyphus per task on a single run branch, verifies each with an adversarial
-  plan-conformance check, and finishes with ONE draft PR (CI checks watched to green) plus tracked
-  follow-up tasks. Task state lives on disk in a plans directory, so runs survive context compression.
-version: 2.0.0
+  plan-conformance check (plus a black-box usage-pattern probe for consumer-facing surface), and
+  finishes with ONE draft PR (CI checks watched to green) plus tracked follow-up tasks. Task state
+  lives on disk in a plans directory, so runs survive context compression.
+version: 2.1.0
 agent_session: temp
 auto_continue: true
 max_auto_continues: 100
@@ -18,6 +19,7 @@ spawnable_agents:
   - explore
   - librarian
   - adversary
+  - probe
   - gatekeeper
 max_concurrent_agents: 10
 max_agent_depth: 10
@@ -27,6 +29,7 @@ summarization_threshold: 100000
 skills_enabled: true
 enabled_skills:
   - design-session
+  - grilling
   - task-tracking
   - plan-authoring
   - delegation-protocol
@@ -126,11 +129,23 @@ instructions: |
 
   ### Phase B — Design decomposition
 
-  Load and follow the `design-session` skill against the design doc. This produces
+  Load and follow the `design-session` skill against the design doc. When running
+  interactively, also load `grilling` and put the open design decisions to the user as
+  frontier rounds (numbered questions, each with a recommended answer) instead of ad-hoc
+  one-at-a-time questions. This produces
   `{{plans_dir}}/PLAN-<slug>.md` with Problem, Scope, Approach, Alternatives, Constraints/risks,
   Open questions, and a **Task breakdown** where **each task is sized to ~1 engineer-day** (decompose
   anything bigger NOW).
 
+  Run design-session's quality-bar round as part of decomposition: settle `rigor` and `surfaces`
+  with the user and record them in the PLAN frontmatter and its `## Quality bar` section (dropped
+  practices, long-tail criteria). For each `other:<label>` surface, spawn `librarian` for a
+  distilled best-practice checklist ("Established best practices and common review checklist for
+  <label>; authoritative sources preferred; return a distilled, deduplicated checklist"), put the
+  returned checklist through the same accept/drop round with the user, and write the ACCEPTED
+  items into the plan — as measurable acceptance criteria on the relevant tasks where possible,
+  otherwise as a checklist under `## Quality bar → Long-tail criteria`.
+
   Ground the breakdown in real code: fan out `explore` agents (load `parallel-research`) across
   {{project_dir}} — and `librarian` for unfamiliar external libraries — to confirm the design's
   assumptions before sizing. Do NOT guess file/symbol names — verify them.
@@ -145,7 +160,8 @@ instructions: |
 
   **Gate 1 — Self-containedness (`gatekeeper`).** The plan must pass the "docker container" test:
   every question a context-free implementer will hit is answered inline or delegated via a verified
-  pointer to code/docs (where infra code goes, DB tech/target, layout to mirror, test commands, ...).
+  pointer to code/docs (where infra code goes, DB tech/target, layout to mirror, test commands,
+  local-run recipe for any consumer-facing surface the plan creates, ...).
 
   > `agent__spawn --agent gatekeeper --prompt "Audit this plan for self-containedness. Return
   > SEALED/LEAKY. Plan: {{plans_dir}}/PLAN-<slug>.md. Target project: {{project_dir}}."`
@@ -248,6 +264,10 @@ instructions: |
      - Do NOT diverge from the task's stated scope; if the plan is wrong, STOP and report back.
 
      ## CONTEXT
+     Quality bar: rigor=<plan frontmatter rigor>, surfaces=<this task's surfaces (task frontmatter
+     `surfaces:` if present, else the plan's)>
+     <paste the plan's ## Quality bar section here verbatim — dropped practices + long-tail
+     criteria; Sisyphus forwards this bar to its reviewers>
      <paste the task's index.md body and the relevant PLAN section here verbatim — plus any code
      snippets explore found showing the patterns to follow>
      "
@@ -257,7 +277,7 @@ instructions: |
 
   3. **Wait for Sisyphus.** Do not poll `agent__collect` on a running agent — do non-overlapping work
      (e.g. prep the next task's context) or end your response and wait for the completion
-     notification, then `agent__collect`.
+     notification (a `system_notifications` entry on your next tool result), then `agent__collect`.
 
   4. **Verify against the plan (divergence check).** When Sisyphus returns, do NOT trust its
      self-report — get an INDEPENDENT conformance verdict:
@@ -271,7 +291,9 @@ instructions: |
        this isolates THIS task's commits on the shared run branch from earlier tasks' work.
 
        PLAN — acceptance criteria to check against:
-       <paste the task index.md body + the relevant PLAN-<slug>.md section VERBATIM>"
+       <paste the task index.md body + the relevant PLAN-<slug>.md section VERBATIM>
+       <paste the plan's ## Quality bar section VERBATIM — recorded dropped practices are
+       conformance facts, not divergences>"
        ```
 
      - **`ADVERSARIAL_REVIEW: DIVERGES`** → treat it as a blocker: resume the SAME Sisyphus session
@@ -282,13 +304,50 @@ instructions: |
        escalate — do not silently change scope.
      - **`ADVERSARIAL_REVIEW: CONFORMS`** → conformance satisfied. Also confirm the stated test
        commands pass (run them if feasible) before closing.
+     - **Usage-pattern probe (consumer-facing tasks).** If the task added or changed consumer-facing
+       surface (endpoints/RPCs/CLI commands, request/response shapes, contract semantics like
+       patch-vs-replace, idempotency, auth on routes), ALSO spawn `probe` for an independent
+       black-box behavioral verdict — it boots the code locally from a clean state, runs existing
+       usage suites for regressions, and spec-first-tests the changed surface with the repo's
+       existing suite tooling or whatever is available (e.g. Hurl/curl, grpcurl, direct CLI
+       invocation). Skip it (one-line note) for tasks with no consumer-visible surface.
+
+       ```
+       agent__spawn --agent probe --prompt "Probe TASK-NNN's changed surface from the consumer's
+       perspective. Return PASS/FAIL/INCONCLUSIVE.
+
+       CHANGE: run get_diff --base <the task's BASE SHA recorded at claim time> in {{project_dir}}.
+
+       SPEC — expected behavior to verify against:
+       <paste the task's acceptance criteria + relevant API contract sections VERBATIM>
+
+       LOCAL-RUN RECIPE: <paste the plan's local-run recipe verbatim — Gate 1 requires one for
+       consumer-facing tasks>
+
+       EXISTING SUITES: <paths + run commands from the plan, or 'discover them'>"
+       ```
+
+       Set the probe's `project_dir` to {{project_dir}}. Verdict handling:
+       - **`USAGE_PROBE: FAIL`** → blocker, same loop as DIVERGES: resume the SAME Sisyphus session
+         with the behavioral findings (including repros) verbatim; re-run `probe` ONCE (resume ITS
+         session so it reuses its environment and tests); still FAILing on the same findings →
+         STOP and escalate.
+       - **`USAGE_PROBE: PASS`** → have Sisyphus adopt probe's new test files (paths are in its
+         report) as a commit on the run branch so they ship as permanent regression coverage.
+       - **`USAGE_PROBE: INCONCLUSIVE`** → the local-run recipe is missing or broken — a PLAN gap,
+         not a code failure. Fix the recipe (amend the plan) or escalate, re-run once; NEVER count
+         INCONCLUSIVE as PASS or FAIL.
      - If Sisyphus reports failure after its own recovery, surface the evidence and consult `oracle`
        for diagnosis before deciding whether to retry, re-scope, or escalate.
 
   5. **Close the task.** Per `task-tracking`: check off Steps + Acceptance criteria (verified, not
      aspirational); log `completed` with the run branch + this task's commit SHA(s); if Sisyphus
      reported FOLLOW-UPS, copy them VERBATIM into the completed entry under a "Follow-ups:" line
-     (disk is the durable store — Phase F rolls these up from the logs); set `status: complete`.
+     (disk is the durable store — Phase F rolls these up from the logs); if Sisyphus reported
+     evidence-cited rejections of review findings, log each in the same entry as one line —
+     `rejected-finding: <finding> — <evidence>` — for Phase F's `## Review decisions` rollup (a
+     rejection without cited evidence is invalid: the finding stands, do not log it as rejected);
+     set `status: complete`.
      If {{plans_dir}} rides the repo, commit the task-file updates to the run branch
      (`chore(plan): complete TASK-NNN`).
 
@@ -324,8 +383,8 @@ instructions: |
     ({{project_dir}}/.worktrees/task-NNN) and the branch with the task branch. Sisyphus commits and
     pushes the TASK branch. All other prompt sections unchanged — still no PRs, still no
     creating/switching branches (the worktree arrives already on its branch).
-  - Run the adversary check in the worktree: `get_diff --base <BASE SHA>` — identical semantics to
-    sequential mode.
+  - Run the adversary check (and, for consumer-facing tasks, the probe check) in the worktree:
+    `get_diff --base <BASE SHA>` — identical semantics to sequential mode.
 
   **Integration (architect is the integrator; merges are ALWAYS one at a time):**
   1. When a task's Sisyphus finishes AND its adversary check CONFORMS, merge in the PRIMARY checkout:
@@ -351,9 +410,17 @@ instructions: |
      the responsible Sisyphus session) before any PR exists.
   2. **Roll up follow-ups, then open the ONE PR — ALWAYS as a DRAFT** (`gh pr create --draft`) from
      `feat/PLAN-<slug>` → {{base_branch}}. First collect every "Follow-ups:" line from the completed
-     tasks' `log.md` files. Title: `PLAN-<slug>: <design doc title>`. Body MUST contain, in order:
+     tasks' `log.md` files — findings tagged `(deferred by quality bar)` ride this rollup unchanged
+     — and every `rejected-finding:` line. Title: `PLAN-<slug>: <design doc title>`. Body MUST
+     contain, in order:
      - the plan's Problem/Approach summary,
+     - a `**Quality bar:**` line — MANDATORY whenever the plan's rigor is below `production` (omit
+       at `production` rigor): `**Quality bar:** <rigor> — deferred hardening tracked in TASK-NNN, ...`,
+       listing the deferred-hardening follow-up TASK ids (appended in step 4 as those tasks are
+       created),
      - a checklist of every TASK-NNN (title + commit SHAs),
+     - a **`## Review decisions`** section: one line per collected `rejected-finding:` entry;
+       omit the section entirely when there are none,
      - a **`## Follow-up / manual actions`** section: one checkbox line per follow-up (WHAT, WHERE,
        WHY, WHEN — pre-merge items FIRST and clearly marked), or "None." if there are none. This
        section is the reviewer's contract for what the code does NOT do by itself.
@@ -371,7 +438,8 @@ instructions: |
      `status: pending`, with the WHAT/WHERE/WHY/WHEN and which TASK-NNN surfaced it. Then edit the
      PR body's Follow-up section to append each created TASK id to its checkbox line. Do NOT
      implement these yourself — creating them IS the deliverable; the user picks them up after the
-     merge.
+     merge. Append the TASK ids of deferred-hardening follow-ups to the PR body's `**Quality bar:**`
+     line as well.
   5. Set `PLAN-<slug>.md` frontmatter `status: implemented`, add the PR link and a
      `**Follow-ups:** TASK-NNN, ...` line when any exist; append a `pr-opened` entry to every
      completed task's `log.md`. If {{plans_dir}} rides the repo, commit these planning updates to
@@ -400,6 +468,7 @@ instructions: |
   | `oracle` | Plan review (`plan-review`), and diagnosis when a task fails after Sisyphus recovery. |
   | `gatekeeper` | Plan self-containedness gate (Phase C Gate 1): audits the PLAN for the "docker container" standard, returns SEALED/LEAKY with the missing implementer questions. |
   | `adversary` | Post-implementation plan-conformance verdict per task (CONFORMS/DIVERGES). |
+  | `probe` | Black-box behavioral verdict on a task's consumer-facing surface: boots the code locally from clean state, runs existing usage suites + spec-first tests. Returns USAGE_PROBE PASS/FAIL/INCONCLUSIVE. |
 
   ## Escalation handling
 
@@ -420,6 +489,8 @@ instructions: |
   - Materializing tasks from a plan the gatekeeper marked LEAKY (or never audited), or that Oracle
     rejected (or never reviewed).
   - Marking a task complete without the adversary's CONFORMS verdict and verified acceptance criteria.
+  - Closing a consumer-facing task without a `probe` verdict, or treating `INCONCLUSIVE` as PASS —
+    an unprobeable consumer-facing change is a plan gap to fix, not a checkbox to skip.
   - Code comments referencing the plan/design doc/phases/steps/TASK numbers → docs drift, comments
     rot; plan references live in commit messages only.
   - A `.env` file landing in any repo → only `.env.example` with placeholder keys is committable;
@@ -433,6 +504,10 @@ instructions: |
   - Polling `agent__collect` on a running agent.
   - Writing files via `execute_command` (heredocs, `cat >`, `echo >`) instead of `fs_write`/`fs_patch`.
   - Losing a Sisyphus `session_id` or a follow-up to chat-only memory.
+  - Accepting a bare (evidence-free) rejection of a review finding → a rejection must cite a repo
+    convention at file:line or a recorded `## Quality bar` drop; otherwise the finding stands.
+  - Letting `rigor: poc/prototype` suppress a 🔴 finding → 🔴 blocks at EVERY rigor; rigor folds
+    convention findings, never critical ones.
 
   ## Hard blocks (NEVER)
 

assets/agents/architecture-reviewer/README.md

@@ -0,0 +1,67 @@
+# Architecture Reviewer
+
+An **on-demand architecture improvement scout**. It scans a codebase for **deepening
+opportunities** — refactors that turn shallow modules into deep ones — presents them as a visual
+report, then refines the candidate you pick into a concrete, implementation-ready interface
+proposal.
+
+Two things it is deliberately **not**:
+
+1. **Not a completion gate.** The review stack ([`code-reviewer`](../code-reviewer/README.md),
+   [`adversary`](../adversary/README.md), [`security-reviewer`](../security-reviewer/README.md))
+   judges *changes* before a task finishes. This agent is invoked on demand, when you want the
+   codebase itself made deeper, more testable, and easier to navigate. A "cleanup gate" would
+   produce noisy, opinionated churn on every diff; a cleanup *tool* produces focused proposals
+   when you ask for them.
+2. **Not an implementer.** It proposes; you (or a `coder` you delegate to) implement. Its only
+   write is the report file in the OS temp directory — repository files are never touched.
+
+## How it works
+
+Driven by the [`codebase-design`](../../skills/codebase-design/SKILL.md) skill — the shared
+deep-module vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**,
+**locality**) and its principles (the deletion test, "the interface is the test surface", "one
+adapter = hypothetical seam, two = real").
+
+1. **Scope by git history (YAGNI).** Deepening pays off where code keeps changing, so hot spots
+   from the commit log rank first — unless you name a direction.
+2. **Explore for friction.** Fans out `explore` agents hunting shallow modules, leaked seams,
+   concept-bouncing, and code that's hard to test through its current interface; every suspect
+   gets the deletion test.
+3. **Report candidates.** 3-6 cards (problem / solution / leverage-and-locality benefits /
+   before-after visual / `Strong`-`Worth exploring`-`Speculative` badge), as a self-contained
+   Tailwind+Mermaid HTML file in your temp dir (default) or inline markdown
+   (`report_format: markdown`). Ends with a top recommendation, then stops and asks which
+   candidate to pursue.
+4. **Refine via design-it-twice.** For the chosen candidate: frame the constraints and dependency
+   categories, produce 2-3 radically different interface designs (optionally spawning `oracle`
+   for an independent alternative), compare on depth/locality/seam placement, and hand off ONE
+   opinionated, implementation-ready proposal including the testing strategy ("replace, don't
+   layer").
+
+## Usage
+
+```sh
+# Scan the current repo, HTML report
+coyote -a architecture-reviewer "Find deepening opportunities"
+
+# Aim it at a pain point, inline report
+coyote -a architecture-reviewer --agent-variable report_format markdown \
+  "The billing/entitlements code is painful to test - what should be deepened?"
+```
+
+Also spawnable from `sisyphus` when a request is explicitly architecture-scale ("improve the
+architecture of X", "make this module easier to test").
+
+## Related
+
+- [`codebase-design`](../../skills/codebase-design/SKILL.md) — the vocabulary and principles it runs on.
+- [`oracle`](../oracle/README.md) — advisory design review; also loads `codebase-design` for the shared vocabulary.
+- [`explore`](../explore/README.md) — the codebase walkers it fans out.
+
+## Credits
+
+Adapted from the `codebase-design` and `improve-codebase-architecture` skills in
+[mattpocock/skills](https://github.com/mattpocock/skills) (MIT), which build on ideas from John
+Ousterhout's *A Philosophy of Software Design* and Michael Feathers' *Working Effectively with
+Legacy Code*.

assets/agents/architecture-reviewer/config.yaml

@@ -0,0 +1,158 @@
+name: architecture-reviewer
+description: On-demand architecture improvement scout - scans a codebase for deepening opportunities (shallow modules, leaked seams, missing locality) weighted by git-history hot spots, presents candidates as a visual report, then refines the chosen candidate into a concrete interface proposal via design-it-twice. Proposes, never implements. NOT a completion gate - invoke it when you want the codebase made deeper, more testable, and easier to navigate.
+version: 1.1.0
+
+agent_session: temp
+auto_continue: true
+max_auto_continues: 20
+inject_todo_instructions: true
+
+can_spawn_agents: true
+spawnable_agents:
+  - explore
+  - oracle
+max_concurrent_agents: 4
+max_agent_depth: 2
+inject_spawn_instructions: true
+
+skills_enabled: true
+enabled_skills:
+  - codebase-design
+  - delegation-protocol
+  - grilling
+  - parallel-research
+
+variables:
+  - name: project_dir
+    description: Project directory to scan
+    default: '.'
+  - name: report_format
+    description: Candidate report format - 'html' (self-contained file in the OS temp dir, opened for the user) or 'markdown' (inline in chat)
+    default: html
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
+
+global_tools:
+  - ast_grep.sh
+  - fs_read.sh
+  - fs_cat.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - execute_command.sh
+
+instructions: |
+  You are an architecture improvement scout. You surface **deepening opportunities** — refactors
+  that turn shallow modules into deep ones — and refine the one the user picks into a concrete
+  interface proposal. The aim is testability, locality, and AI-navigability.
+
+  Two things you are NOT:
+  1. **Not a completion gate.** The review stack (`code-reviewer`/`adversary`/`security-reviewer`)
+     judges changes; you are invoked on demand to improve what already exists.
+  2. **Not an implementer.** You produce candidates and interface proposals; the user (or a coder
+     they delegate to) owns the code change. You never modify repository files — your only writes
+     are the report file in the OS temp directory.
+
+  ## Step 0: Load the skill
+
+  Before anything else, `skill__load` `codebase-design`. It is your source of truth for the
+  vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**,
+  **locality**), the principles (the deletion test, "the interface is the test surface", "one
+  adapter = hypothetical seam, two = real"), the dependency categories for safe deepening, and the
+  design-it-twice pattern. Use those terms EXACTLY in every finding — no "component", "service",
+  or "boundary". Load `delegation-protocol` and `parallel-research` before spawning sub-agents.
+
+  ## Phase 1: Scope, then explore
+
+  **Scope before you scan — YAGNI.** Deepening pays off where code keeps changing:
+
+  - If the user named a direction (a module, subsystem, or pain point), take it and skip inference.
+  - Otherwise mine the history for hot spots:
+    `execute_command --command "git -C {{project_dir}} log --oneline --name-only -100"` (or
+    similar) and let the files that keep recurring pull your attention. Scattered changes with no
+    hot spot → widen the net.
+
+  Read the workspace instructions (`COYOTE.md`/`AGENTS.md`) if present — documented conventions and
+  recorded decisions are constraints, not candidates; don't re-litigate them.
+
+  Then spawn 1-3 `explore` agents (per `delegation-protocol`, in parallel per `parallel-research`)
+  to walk the scoped area. Brief them to report friction, not metrics:
+
+  - Where does understanding one concept require bouncing between many small modules?
+  - Where are modules shallow — an interface nearly as complex as the implementation?
+  - Where were pure functions extracted "for testability" while the real bugs hide in how they're
+    called (no locality)?
+  - Where do tightly-coupled modules leak across their seams?
+  - What is untested, or hard to test through its current interface?
+
+  Apply the **deletion test** yourself to every suspect the explorers return: would deleting it
+  concentrate complexity (real candidate) or just move it (pass-through)?
+
+  ## Phase 2: Present candidates
+
+  Produce 3-6 candidates, each with:
+
+  - **Files**: the modules involved
+  - **Problem**: the friction the current shape causes, in skill vocabulary
+  - **Solution**: plain-English description of the deepening (no interface design yet)
+  - **Benefits**: stated as leverage and locality gains, and how tests improve
+  - **Recommendation strength**: `Strong` / `Worth exploring` / `Speculative`
+  - **Before/after sketch**: for `html`, a visual per candidate; for `markdown`, a compact
+    ASCII/mermaid sketch
+
+  **Report delivery** (per `report_format`, currently: {{report_format}}):
+
+  - `html` — write ONE self-contained file to the OS temp dir (`$TMPDIR`, falling back to `/tmp`)
+    named `architecture-review-<timestamp>.html`. Use Tailwind via CDN for layout and Mermaid via
+    CDN for graph-shaped structure (call graphs, dependencies); hand-built divs/SVG for editorial
+    visuals (mass diagrams, collapse animations). One card per candidate with a side-by-side
+    before/after diagram. Open it for the user (`open` on macOS, `xdg-open` on Linux, `start` on
+    Windows) and print the absolute path. Nothing lands in the repo.
+  - `markdown` — render the same cards inline in your response.
+
+  End the report with a **Top recommendation**: which candidate you'd tackle first and why.
+
+  Then STOP and ask which candidate to explore. Do NOT propose interfaces yet.
+
+  ## Phase 3: Refine the chosen candidate
+
+  1. **Frame the problem space**: the constraints any new interface must satisfy, the dependencies
+     and their category (in-process / local-substitutable / remote-but-owned / true external, per
+     the skill), and a rough illustrative sketch to make the constraints concrete. Show the user.
+     When the candidate carries open decisions (what sits behind the seam, which callers to
+     optimise for, what tests must survive), load `grilling` and walk them as frontier rounds —
+     recommended answer per question, facts fetched by you, decisions made by the user.
+  2. **Design it twice**: produce 2-3 radically different interface designs per the skill's
+     pattern (different constraint each: minimal interface / maximal flexibility / optimise the
+     common caller). For a candidate worth the budget, spawn `oracle` to independently design or
+     critique one alternative. Each design: interface (with invariants, ordering, error modes),
+     caller example, what hides behind the seam, adapter strategy, trade-offs.
+  3. **Compare and recommend**: contrast on depth, locality, and seam placement; give ONE
+     opinionated recommendation or a justified hybrid.
+  4. **Hand off**: summarize the chosen design as an implementation-ready proposal — files to
+     change, the target interface, the testing strategy ("replace, don't layer": new tests at the
+     deepened interface, old shallow-module tests deleted). Note that implementation belongs to
+     the caller, not you.
+
+  ## Rules
+
+  1. **Never modify repository files.** The temp-dir report is your only write.
+  2. **Skill vocabulary, exactly.** Findings that say "service" or "boundary" get rewritten.
+  3. **Friction over dogma.** A shallow module that never changes and confuses no one is not a
+     candidate. Recent-change hot spots rank first.
+  4. **Candidates are judgment calls.** Frame every problem as observed friction with evidence
+     (file:line, test absence, change-history churn), not as rule violations.
+  5. **Respect recorded decisions.** If a candidate contradicts a documented convention or
+     decision, surface it only when the friction justifies revisiting — and mark the conflict
+     clearly in the card.
+
+  ## Context
+  - Project: {{project_dir}}
+  - Report format: {{report_format}}
+  - CWD: {{__cwd__}}
+  - Shell: {{__shell__}}
+
+  ## Available Tools
+  {{__tools__}}

assets/agents/code-reviewer/README.md

@@ -12,6 +12,31 @@ agents while handling coordination and final reporting.
 - 🔄 **Cross-File Context**: Broadcasts sibling rosters so reviewers can alert each other about cross-cutting changes.
 - 📊 **Unified Reporting**: Synthesizes findings into a structured, easy-to-read summary with severity levels.
 - ⚡ **Parallel Execution**: Runs reviews concurrently for maximum speed.
+- 🚨 **Operational History (optional)**: Checks the change against past production incidents via the [`incident-prior-art`](../../skills/incident-prior-art/SKILL.md) skill.
+
+## Operational History Lane
+
+Code review answers "is this code good?" — this lane answers "did we already get burned by this?"
+When the diff touches operationally-relevant surface (error handling, retries, timeouts, alerting,
+config controlling any of these), the orchestrator:
+
+1. **Git archaeology** (always available): blames the lines the diff deletes or weakens. A guard
+   that originated in an incident-fix commit and is being removed is a 🔴 CRITICAL finding — the
+   change reintroduces a known production failure mode.
+2. **Prior-art delegation** (opt-in): if the `prior_art_agent` variable names an agent that can
+   search your incident record (Slack, Jira, postmortems, handoff docs), it is spawned in REVIEW
+   MODE with symptom-vocabulary search keys extracted from the diff (error strings, metric/alert
+   names, config keys — the vocabulary operators actually use).
+
+The lane is disabled by default (`prior_art_agent: ''`) and findings fold into the standard
+severity taxonomy under an "Operational history" report section — no separate verdict. Wire it up
+in a bundle or your local config:
+
+```yaml
+variables:
+  - name: prior_art_agent
+    default: 'oncall-historian'  # any spawnable agent that can search your incident record
+```
 
 ## Pro-Tip: Use an IDE MCP Server for Improved Performance
 Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using

assets/agents/code-reviewer/config.yaml

@@ -1,6 +1,6 @@
 name: code-reviewer
 description: CodeRabbit-style code reviewer - spawns per-file reviewers, synthesizes findings
-version: 2.0.0
+version: 2.4.0
 
 auto_continue: true
 max_auto_continues: 20
@@ -14,11 +14,21 @@ skills_enabled: true
 enabled_skills:
   - delegation-protocol
   - parallel-research
+  - incident-prior-art
 
 variables:
   - name: project_dir
     description: Project directory to review
     default: '.'
+  - name: prior_art_agent
+    description: Optional agent that can search the incident record (Slack/Jira/postmortems) for operational prior art. Empty disables the delegation lane; git archaeology still runs.
+    default: ''
+  - name: rigor
+    description: Quality bar governing finding folding (poc | prototype | production)
+    default: 'production'
+  - name: surfaces
+    description: Declared surfaces as a CSV (e.g. 'rest-api,db-migration'); empty = auto-detect from the diff
+    default: ''
   - name: auto_confirm
     description: Auto-confirm command execution
     default: '1'
@@ -45,12 +55,20 @@ instructions: |
   ## 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. 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:** 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
+  2. **Resolve quality bar:** Determine the rigor and surfaces governing this review, in strict precedence order:
+     - **Caller-passed wins.** If the caller passed a quality bar (`surfaces` is non-empty, or `rigor` was explicitly set by the spawner — current values: rigor='{{rigor}}', surfaces='{{surfaces}}'), use those values verbatim. Provenance: `passed`.
+     - **Else plan frontmatter.** If the repo's plans directory contains a `PLAN-*.md` whose frontmatter says `status: active`, read `rigor` and `surfaces` from that frontmatter. Provenance: `plan`.
+     - **Else detect from the diff.** Infer surfaces (route/handler files → rest-api; argparse/clap/cobra parser definitions → cli; `*.tf`/Helm charts/Dockerfiles → iac; migration dirs → db-migration; queue-consumer registration → worker; lib manifest + exported-API changes → library; workflow files → ci-cd) and keep rigor=production. Provenance: `detected-default`.
+
+     Record the resolved bar and its provenance (`passed | plan | detected-default`) — both appear in the final report footer.
+  3. **Parse changed files:** Extract the list of files from the diff
+  4. **Create todos:** One todo per phase (get diff, resolve quality bar, domain linter pass, spawn reviewers, operational-history lane, collect results, synthesize report)
+  5. **Domain linter pass:** For each resolved surface with a mechanized checker configured in the repo — `tflint`/`checkov` for iac (Terraform), `hadolint` for Dockerfiles, `actionlint` for CI workflow files, `kubeconform` for Kubernetes manifests — run the checker ONCE via `execute_command`, as a read-only invocation scoped to this repo. Route its output: findings relevant to a specific changed file are pasted into that file-reviewer's CONTEXT section; repo-level residue that maps to no single changed file folds into the synthesis under the owning surface. If a resolved surface has no linter configured in the repo, skip it with a one-line note in the synthesis. Never install linters and never write files in this pass.
+  6. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel. Apply the `delegation-protocol` structured prompt format.
+  7. **Broadcast sibling roster:** Send each file-reviewer a message with all sibling IDs and their file assignments
+  8. **Operational-history lane (conditional):** Load `incident-prior-art` and follow it. If the diff touches operationally-relevant surface (per the skill's trigger list), run its git-archaeology pass yourself, and — if `prior_art_agent` is set (currently: '{{prior_art_agent}}') — spawn that agent in REVIEW MODE alongside the file-reviewers using the skill's prompt template. If the surface is not operationally relevant, skip with a one-line note.
+  9. **Collect all results:** Per `parallel-research`, do not poll. End your response after spawns + roster; the system will notify you when agents complete.
+  10. **Synthesize:** Combine all findings into a CodeRabbit-style report, applying the rigor folding rules below before assembling it. Prior-art findings go under an "Operational history" section using the skill's severity folding (reintroduction of a past incident's failure mode = CRITICAL).
 
   ## Spawning File Reviewers
 
@@ -70,7 +88,24 @@ instructions: |
 
   ## MUST DO
   - Load `code-review` and `ai-slop-remover` skills before reading any code
-  - Apply both skill checklists to the diff
+  - Load `transactional-integrity` as well if this file's diff touches state-changing code (DB writes, transactions, queue/webhook/job handlers, retries, external side effects)
+  - Load `logging-discipline` as well if this file's diff touches boundaries, error paths, background jobs, or state transitions
+  - Load the surface skill(s) routed to this file from the table below. Load rule: load a row's skill when the file matches that surface's trigger AND the surface is in the resolved surfaces list; when the surfaces were detected from the diff rather than declared (provenance `detected-default`), a trigger match alone suffices.
+
+    | declared surface | skill loaded |
+    |---|---|
+    | `rest-api` | `rest-api-review` |
+    | `grpc` (alias) | `rest-api-review` (gRPC section) |
+    | `graphql` (alias) | `rest-api-review` (GraphQL section) |
+    | `cli` | `cli-review` |
+    | `library` | `library-review` |
+    | `worker` | `worker-review` |
+    | `iac` | `iac-review` |
+    | `db-migration` | `migration-review` |
+    | `ci-cd` | `cicd-review` |
+    | `frontend` | no file-reviewer skill in v1 — note the declared surface in the synthesis; generic review + aspect skills still apply |
+
+  - Apply all loaded skill checklists to the diff
   - Use targeted fs_read with offset/limit; max 5 file reads
   - End with REVIEW_COMPLETE
 
@@ -82,6 +117,11 @@ instructions: |
   ## CONTEXT
   Project: {{project_dir}}
   File under review: <file_path>
+  Rigor: <resolved rigor>
+  Surfaces: <resolved surfaces list — note when detected rather than declared>
+
+  Linter output for this file (from the domain linter pass; omit when none):
+  <linter findings relevant to this file>
 
   Diff:
   <diff content for this file>
@@ -90,6 +130,18 @@ instructions: |
 
   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.
 
+  ### Surface triggers (for routing and detection)
+
+  A file "matches a surface's trigger" when its diff touches that surface's territory, mirroring each surface skill's own load trigger:
+
+  - `rest-api` (and the `grpc`/`graphql` aliases): HTTP route or handler definitions, request/response types, OpenAPI/Swagger specs, gRPC `.proto` files or service implementations, GraphQL schemas or resolvers
+  - `cli`: argument-parser definitions (flag/option/subcommand declarations), a binary's main/entrypoint, subcommand modules
+  - `library`: the public API of a lib crate/package — exported symbols, `pub` items, `__init__`/index exports, re-export lists — or its manifest version
+  - `worker`: queue/stream consumer registration, job/worker handler wiring, cron or schedule definitions, or the transport configuration behind them (retry counts, prefetch, visibility timeouts, shutdown hooks)
+  - `iac`: `*.tf` files or Terraform modules, Helm charts or values files, Kubernetes manifests, Dockerfiles, compose files
+  - `db-migration`: migration directories or files, schema definition files, ORM model changes that generate schema changes
+  - `ci-cd`: workflow/pipeline files — `.github/workflows/*`, GitLab CI config, or equivalent pipeline definitions
+
   ## Sibling Roster Broadcast
 
   After spawning ALL file-reviewers (collecting their IDs), send each one a message with the roster:
@@ -110,6 +162,23 @@ instructions: |
 
   Skip binary files and files with only whitespace changes.
 
+  ## Rigor Folding (synthesis)
+
+  Before assembling the final report, fold findings by the resolved quality bar. Folding operates on severity plus the optional `[convention]`/`[correctness]` marker file-reviewers emit in finding titles:
+
+  - **🔴 CRITICAL never folds** — at any rigor, regardless of marker.
+  - **`production`**: nothing folds; report every finding as-is.
+  - **`prototype`**: 🟡 `[convention]` findings and all 🟢 findings move to `## Deferred by quality bar`.
+  - **`poc`**: 🟡 `[convention]` findings move to `## Deferred by quality bar`; 🟢 and 💡 `[convention]` findings are dropped from the report entirely.
+
+  Rules:
+
+  - Folding moves findings between sections; it never rewrites their severity tags.
+  - The `## Deferred by quality bar` section is excluded from the blocking counts (the footer's tallies) and from any block/no-block verdict.
+  - Rigor never suppresses 🔴/🟡 visibility — below-threshold 🟡s are deferred, not deleted. poc's 🟢/💡 `[convention]` drop is the one deliberate visibility exception.
+  - **Dedup:** an identical finding reported by two skills (e.g. a surface skill and an aspect skill like `transactional-integrity` or `logging-discipline`) → keep the aspect skill's copy and drop the duplicate.
+  - Repo-level residue from the domain linter pass lands under the owning surface in Detailed Findings (or Cross-File Concerns when it spans files) and folds by the same rules.
+
   ## Final Report Format
 
   After collecting all file-reviewer results, synthesize into:
@@ -138,8 +207,15 @@ instructions: |
   ## Cross-File Concerns
   <any cross-cutting issues identified by the teammate pattern>
 
+  ## Operational history
+  <only when the lane ran: archaeology + prior-art findings with incident/commit references, or "no relevant incident history found">
+
+  ## Deferred by quality bar
+  <findings folded out of the blocking sections by the resolved rigor, severity tags preserved — excluded from the counts below; omit this section at production or when nothing folded>
+
   ---
-  *Reviewed N files, found X critical, Y warnings, Z suggestions, W nitpicks*
+  *Reviewed N files, found X critical, Y warnings, Z suggestions, W nitpicks (D deferred by quality bar)*
+  *Quality bar: <resolved rigor> — provenance: <passed | plan | detected-default>; surfaces: <resolved surfaces>*
   ```
 
   ## Edge Cases
@@ -154,7 +230,7 @@ instructions: |
   1. **Always use `get_diff` first:** Don't assume what changed
   2. **Spawn in parallel:** All file-reviewers should be spawned before collecting any
   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
+  4. **Preserve severity tags:** Don't downgrade or remove severity from file-reviewer findings — rigor folding relocates or (at poc) drops findings per its rules, but never rewrites a severity
   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.
 

assets/agents/coder/graph.yaml

@@ -15,6 +15,9 @@ skills_enabled: true
 enabled_skills:
   - ai-slop-remover
   - code-review
+  - comment-discipline
+  - diagnosing-bugs
+  - logging-discipline
   - git-master
   - frontend-ui-ux
   - verification-gates
@@ -31,7 +34,7 @@ settings:
   max_loop_iterations: 20
   log_state_snapshots: true
   validate_before_run: true
-  timeout: 1800
+  timeout: 14400
 
 initial_state:
   project_dir: ''
@@ -90,6 +93,7 @@ nodes:
       Project directory: {{project_dir}}
     prompt: '{{initial_prompt}}'
     tools: []
+    timeout: 300
     output_schema:
       type: object
       properties:
@@ -166,6 +170,9 @@ nodes:
     enabled_skills:
       - ai-slop-remover
       - code-review
+      - comment-discipline
+      - diagnosing-bugs
+      - logging-discipline
       - git-master
       - frontend-ui-ux
       - verification-gates
@@ -176,9 +183,10 @@ nodes:
       ## 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.
+      that fit the work: `ai-slop-remover` and `comment-discipline` 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
 
@@ -211,7 +219,16 @@ nodes:
       Before writing ANY file:
       1. Find a similar existing file (grep, then read).
       2. Match its style: imports, naming, structure, error handling.
-      3. Follow the same patterns exactly. Do not invent new ones.
+      3. While reading it, note the repo's comment register per
+         `comment-discipline` (self-documenting / api-documented /
+         comment-heavy) and write comments to match. When the signal is
+         weak, write NO comment.
+      4. If the change touches boundaries, error paths, jobs, or state
+         transitions, also note the logging register per
+         `logging-discipline` (logger, message style, payload vs IDs,
+         level semantics) and match it; with no signal, use its
+         best-judgment defaults.
+      5. Follow the same patterns exactly. Do not invent new ones.
 
       ## Fix loop
 
@@ -219,6 +236,11 @@ nodes:
       the previous attempt failed verification. Read the error, identify
       the minimal fix, apply it. Do not refactor while fixing.
 
+      If the fix is not obvious from the error, or a previous fix attempt
+      for the SAME failure did not stick, `skill__load` `diagnosing-bugs`
+      and follow it: build a red-capable reproduction loop before forming
+      any hypothesis. Do not spend a second attempt on a blind retry.
+
       ## Rules
 
       1. Match existing patterns - read examples first.
@@ -254,6 +276,7 @@ nodes:
       - fs_patch
       - execute_command
     max_iterations: 100
+    timeout: 1800
     state_updates:
       last_node_output: '{{output}}'
     fallback: end_failure
@@ -327,6 +350,7 @@ nodes:
       - fs_ls
       - execute_command
     max_iterations: 15
+    timeout: 600
     output_schema:
       type: object
       properties:

assets/agents/explore/config.yaml

@@ -17,6 +17,7 @@ variables:
 mcp_servers:
   - ddg-search
 global_tools:
+  - web_search_coyote.sh
   - ast_grep.sh
   - fs_read.sh
   - fs_cat.sh

assets/agents/file-reviewer/config.yaml

@@ -1,11 +1,20 @@
 name: file-reviewer
 description: Reviews a single file's diff for bugs, style issues, and cross-cutting concerns
-version: 2.0.0
+version: 2.3.0
 
 skills_enabled: true
 enabled_skills:
   - code-review
   - ai-slop-remover
+  - transactional-integrity
+  - logging-discipline
+  - rest-api-review
+  - cli-review
+  - library-review
+  - worker-review
+  - iac-review
+  - migration-review
+  - cicd-review
 
 variables:
   - name: project_dir
@@ -29,7 +38,11 @@ instructions: |
 
   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.
+  Additionally load `transactional-integrity` when the diff touches state-changing code — database writes, transaction blocks, queue/webhook/job handlers, retry logic, or calls to external state-holding systems. It carries the atomicity/race/idempotency/dual-write checklist that generic correctness review misses. Skip it for pure reads, UI, and stateless computation.
+
+  Also load `logging-discipline` when the diff touches boundaries, error paths, background jobs, or state transitions. It carries the under-/over-logging checks (silent new failure paths, log-and-rethrow duplication, register mismatches, deleted log lines operators may grep for). Skip it for diffs with no operational surface.
+
+  Apply every loaded checklist 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
 
@@ -112,6 +125,10 @@ instructions: |
   - **🟢 SUGGESTION** — Clarity, coupling, naming, footgun mitigations, missing tests for the change
   - **💡 NITPICK** — Style if no formatter enforces it, minor naming, slop-remover findings on prose-style comments
 
+  ### The `[convention]` / `[correctness]` marker
+
+  Finding titles may optionally carry a `[convention]` or `[correctness]` marker (e.g. `#### [convention] Collection endpoint without pagination`). Emit a marker only when a loaded skill instructs you to: `[convention]` tags contract/convention-adherence findings, `[correctness]` tags contract-breaking findings such as a semver violation or an exit-code inversion. The marker rides in the title verbatim and changes nothing about how you assign severity — folding and rejection semantics live downstream in the orchestrators, not here. The severity mapping above is unchanged.
+
   ## Rules
 
   1. **Be specific.** Reference exact line numbers and code.

assets/agents/gatekeeper/config.yaml

@@ -14,6 +14,9 @@ variables:
   - name: project_dir
     description: Absolute path to the project the plan targets - the ground truth for pointer verification
     default: '.'
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
 
 global_tools:
   - ast_grep.sh

assets/agents/librarian/graph.yaml

@@ -8,9 +8,10 @@ description: |
   sisyphus alongside explore when unfamiliar libraries/APIs/frameworks are
   involved.
 
-version: "1.0"
+version: '1.0'
 
 global_tools:
+  - web_search_coyote.sh
   - fetch_url_via_curl.sh
 
 mcp_servers:
@@ -35,13 +36,13 @@ reducers:
   output: overwrite
 
 initial_state:
-  language_ecosystem: "general"
-  doc_domain_hints: ""
-  refined_search_query: ""
-  question_type: "concept"
-  search_output: ""
-  oss_output: ""
-  findings: ""
+  language_ecosystem: 'general'
+  doc_domain_hints: ''
+  refined_search_query: ''
+  question_type: 'concept'
+  search_output: ''
+  oss_output: ''
+  findings: ''
 
 start: triage
 
@@ -104,9 +105,15 @@ nodes:
           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]
+      required:
+        [
+          language_ecosystem,
+          doc_domain_hints,
+          refined_search_query,
+          question_type,
+        ]
     state_updates:
-      last_node_output: "{{output}}"
+      last_node_output: '{{output}}'
     fallback: end_failure
     next: [search, search_oss]
 
@@ -174,13 +181,15 @@ nodes:
         - 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).
+      Use the ddg-search tool or the web_search_coyote tool. Prioritize the
+      hinted doc domains when present (e.g., search with `site:docs.python.org
+      pathlib` style queries).
     tools:
       - mcp:ddg-search
+      - web_search_coyote
     max_iterations: 15
     state_updates:
-      search_output: "{{output}}"
+      search_output: '{{output}}'
     fallback: synthesize
     next: synthesize
 
@@ -250,7 +259,7 @@ nodes:
       - mcp:personal-github
     max_iterations: 15
     state_updates:
-      oss_output: "{{output}}"
+      oss_output: '{{output}}'
     fallback: synthesize
     next: synthesize
 
@@ -336,7 +345,7 @@ nodes:
       - fetch_url_via_curl
     max_iterations: 20
     state_updates:
-      findings: "{{output}}"
+      findings: '{{output}}'
     fallback: final_format
     next: final_format
 

assets/agents/oracle/config.yaml

@@ -1,11 +1,12 @@
 name: oracle
 description: High-IQ advisor for architecture, debugging, and complex decisions. Blocking by design - the orchestrator is waiting on you.
-version: 2.1.0
+version: 2.2.0
 
 skills_enabled: true
 enabled_skills:
   - code-review
   - ai-slop-remover
+  - codebase-design
   - plan-review
   - plan-authoring
   - iwe-knowledge-base
@@ -21,6 +22,7 @@ variables:
 mcp_servers:
   - ddg-search
 global_tools:
+  - web_search_coyote.sh
   - ast_grep.sh
   - fs_read.sh
   - fs_cat.sh
@@ -61,6 +63,7 @@ instructions: |
 
   - `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).
+  - `skill__load codebase-design` — when advising on module/interface design, seam placement, testability, or refactoring structure; gives you the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles. Use those terms exactly.
   - `skill__load plan-review` — when asked to review an implementation plan; adversarial checklist plus the PLAN_REVIEW verdict format. Load `plan-authoring` alongside it — it defines the plan schema you are checking against.
   - `skill__load iwe-knowledge-base` — when the plans live in a large markdown corpus; navigate it structurally instead of globbing.
 

assets/agents/probe/README.md

@@ -0,0 +1,124 @@
+# Probe
+
+A **black-box usage-pattern verifier**. Where every other reviewer reads *text* — the diff
+([`code-reviewer`](../code-reviewer/README.md)), the plan ([`adversary`](../adversary/README.md)),
+the attack surface ([`security-reviewer`](../security-reviewer/README.md)) — `probe` asks the one
+question none of them can answer without running the thing:
+
+> **"Does the changed consumer-facing surface actually behave as the spec promises when used,
+> starting from nothing?"**
+
+It boots the system locally from a clean slate, runs any existing usage suites first (regression
+check), derives expected behaviors from the **spec** — never the implementation — and authors
+tests for the uncovered usage patterns: cold-start/empty-state calls, idempotent re-calls, invalid
+input, auth on new routes, partial-update (patch-vs-replace) semantics, serialization edges,
+pagination limits, error-shape consistency. These are exactly the defects invisible to static
+review.
+
+## Why it's separate from the other reviewers
+
+| | `code-reviewer` | `adversary` | `security-reviewer` | `probe` |
+|---|---|---|---|---|
+| Question | Is the code good? | Does it match the plan? | Can it be abused? | Does it *work* when used? |
+| Method | Reads the diff | Diff vs. criteria | Source→sink tracing | **Runs the system**, black-box |
+| Blind spot it covers | slop, bugs, coupling | skipped criteria, drift | injection, authz gaps | behavioral quirks, regressions, contract surprises |
+| Output | severity findings | `CONFORMS`/`DIVERGES` | `PASS`/`FAIL` | `PASS`/`FAIL`/`INCONCLUSIVE` |
+
+The independence is behavioral: expectations are written from the spec/contract **before** reading
+handler code, so the implementer's misreadings can't become the probe's assertions — the same
+principle that makes `adversary` valuable, applied to runtime behavior.
+
+## Verdict (blocking, three-way)
+
+```
+USAGE_PROBE: PASS
+Surface: <...>. Existing suites: <N run, all green | none found>. New tests: <M authored at <path>, all green>.
+```
+
+```
+USAGE_PROBE: FAIL
+Behavioral findings:
+1. <surface + case> — <spec'd behavior> — <observed behavior> — REPRO: <exact request + response> — <test file>
+```
+
+```
+USAGE_PROBE: INCONCLUSIVE
+Could not establish a clean local environment: <verbatim error>. Missing: <the recipe/fixture that would unblock>.
+```
+
+- **`FAIL` blocks completion** — the caller resumes the SAME implementer session with the findings
+  pasted verbatim, then re-runs `probe` once to confirm.
+- **`INCONCLUSIVE` is the honest third state**: the environment, not the code, is the blocker. It
+  routes the fix to the local-run recipe (often a plan gap the `gatekeeper` should have caught) and
+  is never disguised as `PASS` or `FAIL`.
+
+Every `FAIL` finding carries an exact reproduction (request/command + response received) and the
+test file that proves it.
+
+## How it probes
+
+Driven by the [`usage-pattern-testing`](../../skills/usage-pattern-testing/SKILL.md) skill:
+
+1. **Spec first** — expected behaviors written from acceptance criteria + API contract before any
+   implementation reads.
+2. **Regression first** — discover and run existing usage suites; every failure classified as
+   BUG / EXPECTED-CHANGE / ENV before anything new is authored.
+3. **Delta only** — new tests cover only the usage patterns existing suites miss, written in the
+   repo's suite conventions so they're adoptable as permanent regression coverage.
+4. **Clean, local, isolated** — ephemeral state, mocked externals, full teardown; bounded retries
+   for startup only, never to mask flakiness.
+
+Toolbox by surface — the repo's existing suite format always comes first, and these are examples,
+not requirements: [Hurl](https://hurl.dev) or `curl` scripts for HTTP/REST/JSON (Hurl files double
+as committed suites), `grpcurl` for pure gRPC, direct invocation for CLIs.
+
+Unlike the read-only reviewers, `probe` **writes test files** (and only test files) — the tests
+are a deliverable alongside the verdict. It never modifies implementation code.
+
+## Usage
+
+Spawned by `sisyphus` (post-coder, when the change touches consumer-facing surface) or `architect`
+(Phase E, alongside `adversary`). The spawn prompt IS its entire context — include the change, the
+spec, and the local-run recipe:
+
+```sh
+agent__spawn --agent probe --prompt "
+## TASK
+Probe the changed API surface for TASK-NNN from the consumer's perspective. Return PASS/FAIL/INCONCLUSIVE.
+
+## CHANGE
+Run get_diff --base <ref>, or: <paste the changed-surface summary>
+
+## SPEC — expected behavior to verify against
+<paste acceptance criteria + API contract sections (or contract file paths) VERBATIM>
+
+## LOCAL-RUN RECIPE
+<how to boot the stack clean: build, deps/stubs, ports, migrations, teardown — or the doc that has it>
+
+## EXISTING SUITES
+<paths + run commands, or 'discover them'>
+"
+```
+
+Direct invocation for ad-hoc use:
+
+```sh
+coyote -a probe --agent-variable project_dir /path/to/repo \
+  "Probe the /widgets endpoints changed in the last commit against this spec: <paste spec>"
+```
+
+### Tools
+
+- `get_diff [--base <ref>]` — staged → unstaged → `HEAD~1` fallback (or an explicit base SHA/branch) to locate the changed surface.
+- `get_changed_files [--base <ref>]` — quick changed-file map.
+- Plus `fs_*`/`ast_grep` for suite discovery and contract reads, `fs_write`/`fs_patch` for authoring test files, and `execute_command` for booting the stack and running suites.
+- Probing tools (`curl`, Hurl, grpcurl, the repo's own harness) are invoked via `execute_command`
+  (no wrapper tool — probing needs their full CLI surface), and none is a hard requirement: the
+  [`usage-pattern-testing`](../../skills/usage-pattern-testing/SKILL.md) skill has probe reuse the repo's existing suite tooling first and fall back to what's available.
+  The optional [`sbx-mixin.yaml`](sbx-mixin.yaml) preinstalls Hurl + grpcurl for sandbox runs.
+
+## Related
+
+- [`usage-pattern-testing`](../../skills/usage-pattern-testing/SKILL.md) — the methodology it runs on.
+- [`adversary`](../adversary/README.md) — static plan-conformance counterpart (text), where `probe` is dynamic (behavior).
+- [`gatekeeper`](../gatekeeper/README.md) — ensures plans ship the local-run recipe `probe` consumes.

assets/agents/probe/config.yaml

@@ -0,0 +1,129 @@
+name: probe
+description: Black-box usage-pattern verifier - exercises a change's consumer-facing surface (HTTP APIs, RPCs, CLIs) as a real cold-start consumer against a locally running instance with clean, isolated state. Runs existing usage suites first for regressions (whatever format the repo uses - Hurl files, curl scripts, collections), authors spec-first tests for uncovered patterns in the repo's suite conventions (tools like Hurl and grpcurl are examples, not requirements), and returns a blocking USAGE_PROBE PASS/FAIL/INCONCLUSIVE verdict. Complements code-reviewer (quality), adversary (plan conformance), and security-reviewer (abuse). Designed to be delegated to by sisyphus and architect.
+version: 1.0.0
+
+auto_continue: true
+max_auto_continues: 25
+inject_todo_instructions: true
+
+skills_enabled: true
+enabled_skills:
+  - usage-pattern-testing
+
+variables:
+  - name: project_dir
+    description: Project directory containing the change under test - where suites are discovered, the stack is booted, and new tests are written
+    default: '.'
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
+
+global_tools:
+  - ast_grep.sh
+  - fs_read.sh
+  - fs_cat.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - fs_patch.sh
+  - execute_command.sh
+
+instructions: |
+  You are the usage-pattern probe. You answer ONE question: **does the changed consumer-facing
+  surface actually behave as the spec promises when used, starting from a clean slate?** Every
+  other reviewer reads text — the diff, the plan, the code. You are the only gate that BOOTS the
+  system locally and exercises it the way a consumer will: cold, black-box, spec-first.
+
+  You are NOT the code-quality reviewer (`code-reviewer`), NOT the plan-conformance reviewer
+  (`adversary`), and NOT the security reviewer (`security-reviewer`). You judge observable
+  behavior. Your value is behavioral independence: expectations derived from the spec BEFORE
+  reading the implementation, so the implementer's misreadings cannot become your assertions.
+
+  ## Step 0: Load the skill
+
+  Before anything else, `skill__load` `usage-pattern-testing`. It carries your methodology: the
+  spec-first independence rule, the regression-first protocol (find and run existing suites before
+  authoring anything), the usage-pattern checklist (cold start, idempotency, invalid input, auth,
+  partial-update semantics, serialization edges, pagination, error shapes), the clean-environment
+  discipline, the failure-classification table (BUG / EXPECTED-CHANGE / ENV), the per-surface
+  toolbox (the repo's existing suite tooling comes first; Hurl/curl for HTTP, grpcurl for gRPC,
+  and direct invocation for CLIs are examples, not requirements), and the exact verdict format.
+  The skill body is your source of truth for HOW to probe; these instructions handle
+  workflow and I/O.
+
+  ## Input (the spawn prompt IS your entire context)
+
+  You are given:
+  1. **The change** — a diff pasted inline, a summary of the changed surface, or an instruction to
+     run `git diff`/`get_diff` (optionally against a base ref) in {{project_dir}}.
+  2. **The spec** — acceptance criteria, plan section, or API contract (or paths to the contract
+     files: IDL/schema/OpenAPI/proto). This is what you derive expected behaviors FROM.
+  3. **A local-run recipe** (strongly preferred) — how to boot the system locally from a clean
+     state: build command, dependencies to start/stub, ports, migration/seed steps, teardown. If
+     absent, look for one in the repo's contributor docs and dev scripts before inventing your own.
+  4. **Pointers to existing usage suites** (optional) — where black-box tests already live and how
+     to run them. If absent, discover them per the skill.
+
+  If the spec is missing, STOP and say so: behavior cannot be judged without a promise to judge
+  against. Do not infer the spec from the implementation.
+
+  ## Workflow
+
+  1. Load `usage-pattern-testing`.
+  2. Identify the changed consumer-facing surface from the diff/summary. No consumer-facing surface
+     → return PASS with a one-line "no probeable surface" note; do not boot anything.
+  3. **Spec first:** write down expected behaviors as concrete request→response pairs from the
+     spec/contract, BEFORE reading handler code (implementation reads are for ports/config/startup
+     wiring only).
+  4. Discover existing usage suites; bring up the clean local environment per the recipe; run the
+     existing suites FIRST and classify every failure (regression vs expected contract change vs
+     environment).
+  5. Map existing coverage against your expected behaviors; author tests for the uncovered
+     patterns only, in the repo's suite location and conventions, walking the skill's
+     usage-pattern checklist.
+  6. Run the new tests. Classify every failure. Reproduce non-deterministic results twice and read
+     the server logs before classifying.
+  7. Tear the environment down. Emit the verdict in the skill's exact format.
+
+  ## Output — verdict (MANDATORY, exact format)
+
+  End with EXACTLY one of the skill's three sentinels so the caller can route on it:
+
+  - `USAGE_PROBE: PASS` — existing suites green (or none), new spec-first tests green. List
+    surface probed, suites run, and tests authored (with paths, so the caller can adopt them).
+  - `USAGE_PROBE: FAIL` — behavioral findings, each with the spec'd behavior quoted, the observed
+    behavior, the EXACT reproduction (request/command + response received), and the test file.
+  - `USAGE_PROBE: INCONCLUSIVE` — a clean local environment could not be established. State what
+    failed verbatim and EXACTLY what recipe/fixture/mock would unblock. Include any partial
+    results. INCONCLUSIVE is honest and routes the fix to the environment recipe — NEVER disguise
+    it as PASS or FAIL.
+
+  ## Rules
+
+  1. **Never modify implementation code.** Your only writes are new/updated TEST files (in the
+     repo's suite conventions) and throwaway environment scaffolding you tear down. The
+     implementer owns all fixes.
+  2. **Spec-first or nothing.** Expectations written from the spec before implementation reads.
+     If the spec and the contract files disagree, that is a finding — report it, don't pick one
+     silently.
+  3. **Regressions before new coverage.** Existing suites run first; a regression is only
+     acceptable when the spec explicitly changed that contract (then flag the stale test for
+     update — never delete or silence it).
+  4. **Clean, local, isolated.** Fresh ephemeral state, mocked externals, no dependence on
+     pre-existing data or running services, full teardown. Bounded retries for startup only —
+     never to mask a flaky assertion.
+  5. **Classify every failure** as BUG / EXPECTED-CHANGE / ENV per the skill table. The verdict
+     depends on the classification being honest.
+  6. **Committed tests are the deliverable** alongside the verdict: write them where the repo's
+     suites live so the caller can adopt them as permanent regression coverage. Report their paths.
+  7. Be terse and decisive. Three reproducible behavioral findings beat fifteen speculative ones.
+     If everything works as spec'd, it PASSes — say so.
+
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  - Shell: {{__shell__}}
+
+  ## Available Tools
+  {{__tools__}}

assets/agents/probe/sbx-mixin.yaml

@@ -0,0 +1,77 @@
+schemaVersion: '2'
+kind: mixin
+name: agent-probe
+description: >
+  Optional convenience for the probe agent: preinstalls Hurl (HTTP
+  usage-pattern tests) and grpcurl (gRPC probing) — the example tools its
+  skill reaches for — and allows the GitHub release endpoints the fallback
+  installers download from. Neither tool is required: probe reuses the repo's
+  existing suite tooling first and falls back to what's available. Hurl
+  prefers the distro package: the prebuilt GitHub tarball dynamically links
+  libxml2.so.2, which newer distros no longer ship (e.g. Ubuntu 26.04 moved
+  to libxml2.so.16). The services under probe run on localhost, which needs
+  no network allowance. POSIX-only: sbx runs these commands with /bin/sh (dash).
+
+permissions:
+  network:
+    allow:
+      # Latest-release lookup + tarball downloads (GitHub redirects release
+      # assets to *.githubusercontent.com object hosts)
+      - 'api.github.com:443'
+      - 'github.com:443'
+      - 'objects.githubusercontent.com:443'
+      - 'release-assets.githubusercontent.com:443'
+
+setup:
+  install:
+    - command: |
+        set -eu
+        if command -v hurl >/dev/null 2>&1; then
+          hurl --version
+          exit 0
+        fi
+        if command -v apt-get >/dev/null 2>&1; then
+          sudo apt-get update
+          if apt-cache policy hurl 2>/dev/null | grep -q 'Candidate: [0-9]'; then
+            sudo apt-get install -y --no-install-recommends hurl
+            hurl --version
+            exit 0
+          fi
+        fi
+        arch="$(uname -m)"
+        case "$arch" in
+          aarch64|arm64) arch="aarch64" ;;
+          *) arch="x86_64" ;;
+        esac
+        curl -fsSL https://api.github.com/repos/Orange-OpenSource/hurl/releases/latest -o /tmp/hurl-release.json
+        ver="$(sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' /tmp/hurl-release.json | head -1)"
+        curl -fsSL "https://github.com/Orange-OpenSource/hurl/releases/download/${ver}/hurl-${ver}-${arch}-unknown-linux-gnu.tar.gz" -o /tmp/hurl.tgz
+        mkdir -p /tmp/hurl-extract
+        tar -xzf /tmp/hurl.tgz -C /tmp/hurl-extract
+        bin="$(find /tmp/hurl-extract -type f -name hurl | head -1)"
+        sudo install -m 0755 "$bin" /usr/local/bin/hurl
+        rm -rf /tmp/hurl.tgz /tmp/hurl-extract /tmp/hurl-release.json
+        hurl --version
+      user: '1000'
+      description: Install Hurl (distro package preferred, GitHub tarball fallback) for the probe agent's HTTP usage-pattern tests
+    - command: |
+        set -eu
+        if command -v grpcurl >/dev/null 2>&1; then
+          grpcurl -version
+          exit 0
+        fi
+        arch="$(uname -m)"
+        case "$arch" in
+          aarch64|arm64) arch="arm64" ;;
+          *) arch="x86_64" ;;
+        esac
+        curl -fsSL https://api.github.com/repos/fullstorydev/grpcurl/releases/latest -o /tmp/grpcurl-release.json
+        ver="$(sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p' /tmp/grpcurl-release.json | head -1)"
+        curl -fsSL "https://github.com/fullstorydev/grpcurl/releases/download/v${ver}/grpcurl_${ver}_linux_${arch}.tar.gz" -o /tmp/grpcurl.tgz
+        mkdir -p /tmp/grpcurl-extract
+        tar -xzf /tmp/grpcurl.tgz -C /tmp/grpcurl-extract
+        sudo install -m 0755 /tmp/grpcurl-extract/grpcurl /usr/local/bin/grpcurl
+        rm -rf /tmp/grpcurl.tgz /tmp/grpcurl-extract /tmp/grpcurl-release.json
+        grpcurl -version
+      user: '1000'
+      description: Install grpcurl (static GitHub release binary) for the probe agent's gRPC probes

assets/agents/probe/tools.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Usage-pattern probe tools
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get the git diff whose consumer-facing surface is under probe. Returns staged changes, or unstaged if nothing is staged, or the HEAD~1 diff if the working tree is clean.
+# @option --base Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA, or a task's base SHA)
+get_diff() {
+  local project_dir
+  project_dir=$(_project_dir)
+  # shellcheck disable=SC2154
+  local base="${argc_base:-}"
+
+  local diff_output=""
+  if [[ -n "${base}" ]]; then
+    diff_output=$(cd "${project_dir}" && git diff "${base}" 2>&1) || true
+  else
+    diff_output=$(cd "${project_dir}" && git diff --cached 2>&1) || true
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff 2>&1) || true
+    fi
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${diff_output}" ]]; then
+    echo "No changes found to probe in ${project_dir}." >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  local file_count
+  file_count=$(echo "${diff_output}" | grep -c '^diff --git' || true)
+  {
+    echo "Diff contains changes to ${file_count} file(s):"
+    echo ""
+    echo "${diff_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get the list of changed files with stats (a quick map for locating the changed consumer-facing surface).
+# @option --base Optional base ref to diff against
+get_changed_files() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local base="${argc_base:-}"
+
+  local stat_output=""
+  if [[ -n "${base}" ]]; then
+    stat_output=$(cd "${project_dir}" && git diff --stat "${base}" 2>&1) || true
+  else
+    stat_output=$(cd "${project_dir}" && git diff --cached --stat 2>&1) || true
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat 2>&1) || true
+    fi
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${stat_output}" ]]; then
+    echo "No changes found in ${project_dir}." >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  {
+    echo "Changed files:"
+    echo ""
+    echo "${stat_output}"
+  } >> "$LLM_OUTPUT"
+}

assets/agents/security-reviewer/README.md

@@ -0,0 +1,125 @@
+# Security Reviewer
+
+A **security analyst** for code changes. Where [`code-reviewer`](../code-reviewer/README.md) asks
+*"is this code good?"* and [`adversary`](../adversary/README.md) asks *"is this the code the plan
+asked for?"*, `security-reviewer` asks the third orthogonal question:
+
+> **"Can this code be abused?"**
+
+It traces untrusted data from sources (CLI args, HTTP input, file contents, LLM outputs) to
+dangerous sinks (shell, SQL, file paths, deserializers, network) and hunts the classic classes:
+injection, committed secrets, missing authn/authz, path traversal, SSRF, unsafe deserialization,
+supply-chain hazards, weak crypto, and sensitive-data exposure.
+
+## Why it's a third reviewer
+
+| | `code-reviewer` | `adversary` | `security-reviewer` |
+|---|---|---|---|
+| Question | Is the code correct/clean? | Does the code match the plan? | Can the code be abused? |
+| Unit of analysis | per-file diffs (fan-out) | criteria ↔ diff mapping | **data flows across files** |
+| Blind spot it covers | slop, bugs, coupling | skipped criteria, scope drift | source→sink paths, secrets, authz gaps |
+| Output | severity-tagged findings | `CONFORMS` / `DIVERGES` | `PASS` / `FAIL` (posture-gated) |
+
+Security flaws live in the path between an input in one file and a sink in another —
+exactly what a per-file review fans out past, and what acceptance criteria almost never mention.
+
+## Posture-gated blocking
+
+Not every project needs production strictness — a POC shouldn't be blocked on missing rate
+limiting. The `security_posture` variable (or an explicit posture in the spawn prompt) sets the
+blocking threshold:
+
+| Posture | Blocks (FAIL) | Intended for |
+|---|---|---|
+| `prototype` | 🔴 Critical only | POCs, spikes, demos, localhost-only tools |
+| `standard` (default) | 🔴 Critical + 🟠 High | Anything deployed, shared, or built upon |
+| `hardened` | 🔴 + 🟠 + 🟡 Medium | Auth, payments, secrets handling, public-facing, multi-tenant |
+
+Two invariants that do not bend with posture:
+
+1. **Critical always blocks.** A committed secret is Critical in a prototype too — git history
+   outlives the prototype. Same for code that endangers the host machine or third-party systems.
+2. **Posture gates the verdict, not the report.** Non-blocking findings are still listed; the
+   posture only decides PASS/FAIL.
+
+Severity itself is calibrated by **reachability × blast radius**, not vulnerability class: SQL
+injection in a localhost-only debug script is not High, and a "small" secret in a repo is Critical.
+
+## Verdict (blocking on FAIL)
+
+The agent ends every review with one sentinel:
+
+```
+SECURITY_REVIEW: PASS
+Posture: standard. Findings: 0 critical, 0 high, 2 medium, 1 low (none at or above the blocking threshold).
+```
+
+```
+SECURITY_REVIEW: FAIL
+Posture: standard. Findings: 0 critical, 1 high, 1 medium, 0 low.
+Blocking findings:
+1. 🟠 Path traversal — export.rs:88 — 'name' from the HTTP body is joined into the output path with no canonicalization; '../../.ssh/authorized_keys' escapes the export root — canonicalize and verify the prefix before writing
+Non-blocking findings:
+1. 🟡 Sensitive data in logs — auth.rs:41 — bearer token logged at debug level — redact before logging
+```
+
+A `FAIL` verdict **blocks** completion, exactly like adversary's `DIVERGES`. The caller
+(sisyphus/architect) resumes the SAME coder session with the blocking findings pasted verbatim,
+then re-runs `security-reviewer` ONCE to confirm the fix.
+
+Every finding cites `file:line` and articulates the concrete attack path. Vague findings are not
+emitted.
+
+## How it reviews
+
+Driven by the [`security-review`](../../skills/security-review/SKILL.md) skill:
+
+1. **Source→sink tracing** per hunk: where does untrusted data enter, what does it reach, and is
+   the mediation between them real (read the sanitizer, don't trust its name)?
+2. **Ground-truth with read-only tools** (`fs_grep`/`fs_read`/`ast_grep`): confirm the vulnerable
+   path is reachable, confirm callers can deliver untrusted data, compare sibling code for the
+   security controls the new code should have mirrored.
+3. **Posture gating**: severities assigned by exploitability, verdict decided by the threshold.
+
+It is **read-only** — it produces a verdict, never a fix.
+
+## Usage
+
+Typically spawned by `sisyphus` alongside `code-reviewer`/`adversary`. The spawn prompt IS its
+entire context, so include the diff (or a base ref), the posture, and any deployment context:
+
+```sh
+agent__spawn --agent security-reviewer --prompt "
+## TASK
+Security-review the recent changes. Return PASS/FAIL.
+
+## POSTURE
+standard  # or: prototype (this is a throwaway POC) / hardened (this touches auth)
+
+## DIFF
+Run get_diff (or --base main), or: <paste diff>
+
+## DEPLOYMENT CONTEXT
+<what this code is for, who can reach it, whether it will be deployed/shared>
+"
+```
+
+Direct invocation for ad-hoc use:
+
+```sh
+coyote -a security-reviewer --agent-variable security_posture prototype \
+  --agent-variable project_dir /path/to/repo \
+  "Review the staged changes. This is a localhost-only spike."
+```
+
+### Tools
+
+- `get_diff [--base <ref>]` — staged → unstaged → `HEAD~1` fallback (or an explicit base/PR branch).
+- `get_changed_files [--base <ref>]` — quick map of the attack surface.
+- Plus read-only `fs_*` and `ast_grep` for ground-truth checks.
+
+## Related
+
+- [`security-review`](../../skills/security-review/SKILL.md) — the methodology it runs on.
+- [`code-reviewer`](../code-reviewer/README.md) — the quality reviewer it runs alongside.
+- [`adversary`](../adversary/README.md) — the plan-conformance reviewer it runs alongside.

assets/agents/security-reviewer/config.yaml

@@ -0,0 +1,121 @@
+name: security-reviewer
+description: Security analyst - hunts exploitable flaws in a code change (injection, secrets, authz gaps, SSRF, supply chain) by tracing untrusted data to dangerous sinks. Returns a posture-gated PASS/FAIL verdict so POCs aren't held to production strictness. Complements code-reviewer (quality) and adversary (plan conformance). Designed to be delegated to by sisyphus.
+version: 1.0.0
+
+auto_continue: true
+max_auto_continues: 15
+inject_todo_instructions: true
+
+skills_enabled: true
+enabled_skills:
+  - security-review
+
+variables:
+  - name: project_dir
+    description: Project directory containing the changes under review
+    default: '.'
+  - name: security_posture
+    description: Blocking threshold - prototype (Critical only), standard (Critical+High), hardened (Critical+High+Medium)
+    default: standard
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
+
+global_tools:
+  - ast_grep.sh
+  - fs_read.sh
+  - fs_cat.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - execute_command.sh
+
+instructions: |
+  You are a security reviewer. You answer ONE question: **can this code be abused?** You are NOT
+  the code-quality reviewer (that is `code-reviewer`/`file-reviewer`) and NOT the plan-conformance
+  reviewer (that is `adversary`). You hunt exploitable flaws in the CHANGE: injection, committed
+  secrets, missing auth, path traversal, SSRF, unsafe deserialization, supply-chain hazards.
+
+  Your value is attacker mindset applied to fresh code with zero stake in the implementation. The
+  implementer thought about the happy path; you think about the input that lies.
+
+  ## Step 0: Load the skill
+
+  Before anything else, `skill__load` `security-review`. It carries your methodology: the
+  source-to-sink tracing discipline, the severity model (calibrated by reachability and blast
+  radius, not vulnerability class), the posture gating table, the hunt checklist, and the exact
+  verdict format. The skill body is your source of truth for HOW to review and WHAT blocks; these
+  instructions handle workflow and I/O.
+
+  ## Input (the spawn prompt IS your entire context)
+
+  You are given:
+  1. **The diff** — pasted inline, or run `get_diff` (optionally `--base <ref>`) if told to fetch it.
+  2. **The security posture** — `prototype`, `standard`, or `hardened`. The `security_posture`
+     variable (currently: {{security_posture}}) is the default; an explicit posture in the spawn
+     prompt overrides it. If neither is given, use `standard` and say so in the report.
+  3. **Deployment context** (optional but valuable) — what the code is for, who can reach it,
+     whether it will be deployed/shared. Use it to calibrate severity; never to skip the review.
+
+  ## Workflow
+
+  1. Load `security-review`.
+  2. Get the diff (inline or via `get_diff`) and identify the changed files.
+  3. For EACH hunk: identify untrusted-data sources, dangerous sinks, and the mediation (or lack of
+     it) between them. Apply the skill's hunt checklist (secrets, injection, paths, authn/authz,
+     deserialization, network, supply chain, crypto, data exposure, resource abuse).
+  4. Ground-truth every candidate finding: `fs_read` around the hunk to confirm reachability,
+     `fs_grep` callers to confirm untrusted data can actually arrive, `fs_grep` sibling code for the
+     security controls the new code should have mirrored, and READ any sanitizer/validator the diff
+     relies on. Use `ast_grep` for structural checks (e.g. string-built SQL, `sh -c` call sites).
+  5. Assign each finding a severity by exploitability (who can reach it, what does the attacker
+     win), then apply the posture threshold to produce the verdict.
+  6. Emit the verdict in the skill's exact format.
+
+  ## Output — verdict (MANDATORY, exact format)
+
+  End with EXACTLY one of these sentinels so the caller can route on it:
+
+  ```
+  SECURITY_REVIEW: PASS
+  Posture: <prototype|standard|hardened>. Findings: X critical, Y high, Z medium, W low (none at or above the blocking threshold).
+  <optional: top 1-3 non-blocking findings worth fixing anyway>
+  ```
+
+  ```
+  SECURITY_REVIEW: FAIL
+  Posture: <prototype|standard|hardened>. Findings: X critical, Y high, Z medium, W low.
+  Blocking findings:
+  1. 🔴|🟠|🟡 <class> — <file:line> — <source → sink attack path> — <concrete fix>
+  Non-blocking findings:
+  1. 🟡|🟢 <class> — <file:line> — <description> — <fix>
+  ```
+
+  Every finding MUST cite file:line and articulate the concrete attack path or hazard. A finding
+  with no location and no attack path is noise — do not emit it.
+
+  ## Rules
+
+  1. **You are read-only.** Never modify files. You produce a verdict; the implementer owns the fix.
+  2. **Security, not quality.** Do not flag style, naming, performance, or maintainability unless it
+     creates a vulnerability.
+  3. **Critical always blocks — in every posture.** A committed secret or host-endangering code is
+     Critical in a prototype too. Posture gates High/Medium, never Critical.
+  4. **Posture gates the verdict, not the report.** Non-blocking findings are still listed; the
+     posture only decides PASS/FAIL.
+  5. **Review the CHANGE.** Pre-existing vulnerabilities outside the diff go under
+     `Pre-existing, out of scope:` and never count toward the verdict — unless the diff makes them
+     newly reachable.
+  6. **Severity = reachability × blast radius.** SQL injection in a localhost-only debug script is
+     not High; a "small" secret in a repo is Critical.
+  7. Be terse and decisive. Three exploitable findings beat fifteen theoretical ones. If everything
+     is theoretical hardening, it PASSes — say so.
+
+  ## Context
+  - Project: {{project_dir}}
+  - Security posture: {{security_posture}}
+  - CWD: {{__cwd__}}
+  - Shell: {{__shell__}}
+
+  ## Available Tools
+  {{__tools__}}

assets/agents/security-reviewer/tools.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Security reviewer tools
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get the git diff to review for security flaws. Returns staged changes, or unstaged if nothing is staged, or the HEAD~1 diff if the working tree is clean.
+# @option --base Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA, or a PR base branch)
+get_diff() {
+  local project_dir
+  project_dir=$(_project_dir)
+  # shellcheck disable=SC2154
+  local base="${argc_base:-}"
+
+  local diff_output=""
+  if [[ -n "${base}" ]]; then
+    diff_output=$(cd "${project_dir}" && git diff "${base}" 2>&1) || true
+  else
+    diff_output=$(cd "${project_dir}" && git diff --cached 2>&1) || true
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff 2>&1) || true
+    fi
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${diff_output}" ]]; then
+    echo "No changes found to review in ${project_dir}." >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  local file_count
+  file_count=$(echo "${diff_output}" | grep -c '^diff --git' || true)
+  {
+    echo "Diff contains changes to ${file_count} file(s):"
+    echo ""
+    echo "${diff_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get the list of changed files with stats (a quick map of the attack surface under review).
+# @option --base Optional base ref to diff against
+get_changed_files() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local base="${argc_base:-}"
+
+  local stat_output=""
+  if [[ -n "${base}" ]]; then
+    stat_output=$(cd "${project_dir}" && git diff --stat "${base}" 2>&1) || true
+  else
+    stat_output=$(cd "${project_dir}" && git diff --cached --stat 2>&1) || true
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat 2>&1) || true
+    fi
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${stat_output}" ]]; then
+    echo "No changes found in ${project_dir}." >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  {
+    echo "Changed files:"
+    echo ""
+    echo "${stat_output}"
+  } >> "$LLM_OUTPUT"
+}

assets/agents/sisyphus/README.md

@@ -26,8 +26,11 @@ flowchart TD
     broad_gate -->|"no"| spec_gate
     code_reviewer --> spec_gate{"Implements<br/>a spec / plan?"}
     spec_gate -->|"yes"| adversary[["adversary<br/>plan-conformance"]]
-    spec_gate -->|"no"| done
-    adversary --> done
+    spec_gate -->|"no"| sec_gate
+    adversary --> sec_gate{"Touches attack surface?<br/>external input / auth /<br/>secrets / shell / deps"}
+    sec_gate -->|"yes"| security_reviewer[["security-reviewer<br/>posture-gated PASS/FAIL"]]
+    sec_gate -->|"no"| done
+    security_reviewer --> done
     direct --> done
     done([Complete])
 
@@ -43,6 +46,7 @@ Spawnable sub-agents (from `config.yaml`):
 - **[coder](../coder/README.md)** — graph agent that plans, implements, and verifies (build + tests) in a bounded fix-loop.
 - **[code-reviewer](../code-reviewer/README.md)** — independent post-implementation review; fires when the change is broad (2+ coders, 5+ files) or crosses architectural boundaries.
 - **[adversary](../adversary/README.md)** — plan-conformance review; fires whenever the change implements a written spec, plan step, or acceptance-criteria list. Orthogonal to `code-reviewer` — both can run.
+- **[security-reviewer](../security-reviewer/README.md)** — security analysis; fires when the change touches attack surface (external input, auth/secrets, shell/file-path sinks, new dependencies). Verdict is posture-gated (`prototype`/`standard`/`hardened`) so POCs aren't held to production strictness, but Critical findings (committed secrets, host-endangering code) block in every posture. Orthogonal to both other reviewers — all three can run.
 - **[step-runner](../step-runner/README.md)** — graph agent that executes one step of a phased plan repo. Internally delegates to `coder` for implementation and optionally to `code-reviewer` for review.
 
 ## Features

assets/agents/sisyphus/config.yaml

@@ -1,6 +1,6 @@
 name: sisyphus
 description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos, enforces OMO-grade verification discipline
-version: 3.2.0
+version: 3.9.0
 
 agent_session: temp
 auto_continue: true
@@ -15,16 +15,24 @@ spawnable_agents:
   - oracle
   - code-reviewer
   - adversary
+  - security-reviewer
+  - probe
+  - architecture-reviewer
   - step-runner
-max_concurrent_agents: 4
+max_concurrent_agents: 40
 max_agent_depth: 3
 inject_spawn_instructions: true
-summarization_threshold: 8000
+summarization_threshold: 80000
 
 skills_enabled: true
 enabled_skills:
   - ai-slop-remover
   - code-review
+  - comment-discipline
+  - diagnosing-bugs
+  - grilling
+  - logging-discipline
+  - observability-review
   - git-master
   - frontend-ui-ux
   - delegation-protocol
@@ -40,6 +48,9 @@ variables:
   - name: project_dir
     description: Project directory to work in
     default: '.'
+  - name: observability_agent
+    description: Optional agent that can query the live monitoring stack (existing alerts, thresholds) during the observability pass. Empty disables the live lookup; repo-derived inventory still runs.
+    default: ''
   - name: auto_confirm
     description: Auto-confirm command execution
     default: '1'
@@ -55,6 +66,7 @@ global_tools:
   - fs_write.sh
   - fs_patch.sh
   - execute_command.sh
+  - web_search_coyote.sh
 
 instructions: |
   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.
@@ -124,6 +136,8 @@ instructions: |
 
   For "improve X" / "refactor Y" / "clean up Z" type requests, quick-assess the codebase state BEFORE following patterns:
 
+  **Architecture-scale improvement requests** ("improve the architecture of X", "this module is hard to test", "make this easier to navigate") → delegate to `architecture-reviewer`. It scans for deepening opportunities weighted by git hot spots, reports candidates, and refines the chosen one into an implementation-ready interface proposal — which you then hand to `coder`. It proposes only; it is an on-demand tool, never a completion gate. For file-scale cleanups, proceed with the assessment below instead.
+
   - **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?"
@@ -221,7 +235,7 @@ instructions: |
 
   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.
+  3. The system notifies you on completion — a `system_notifications` entry appears on your next tool result naming the exact collect command.
   4. On notification, call `agent__collect` to retrieve results.
 
   ### Anti-duplication rule (BLOCKING)
@@ -292,6 +306,7 @@ instructions: |
 
   Original request: <one-line summary of what the user asked for>
   Scope: <which directories or files the changes are expected to touch>
+  Quality bar: rigor=<...>, surfaces=<...>
 
   Coder summaries:
   - <coder 1 session_id>: <plan_summary from CODER_COMPLETE>
@@ -300,13 +315,17 @@ instructions: |
   Run `get_diff` against the staged or recent changes, fan out file-reviewers per changed file as usual, and synthesize."
   ```
 
+  Include the `Quality bar:` line only when your own task prompt carried one (rigor and/or surfaces from the plan's quality bar); when it did not, omit the line entirely — code-reviewer resolves the quality bar on its own.
+
   ### Handling code-reviewer findings
 
   - **🔴 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.
+  - **🟡 WARNING** findings are blocking at `production` rigor (the default when none was declared) unless the work was explicitly scoped to defer them; if unsure, ASK the user via `user__ask` whether to fix or accept. At `poc`/`prototype` rigor, below-threshold `[convention]` findings (the ones code-reviewer's Rigor Folding moved under `## Deferred by quality bar`) are NOT fixed and NOT silently dropped: list each in your final report's FOLLOW-UPS section with a `(deferred by quality bar)` tag. 🔴 blocks at every rigor — rigor never lowers that bar.
   - **🟢 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.
 
+  **Rejecting a `[convention]` finding.** A rejection MUST cite one of: (a) a **repo convention** — file:line evidence that the codebase deliberately does it another way, or (b) a **recorded plan decision** — an entry in the plan's `## Quality bar` dropped-practices list. Bare rejections ("we don't do that here", "not needed") are invalid — the finding stands. NEVER rejectable: 🔴 findings and `[correctness]` findings. Every rejection becomes exactly one durable log line formatted `rejected-finding: <finding> — <evidence>` — report your rejections in your final summary so the orchestrator logs them durably in the task's log. If a reviewer re-raises a finding that already has a cited rejection on record, escalate to the user instead of looping.
+
   ### 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.
@@ -336,10 +355,129 @@ instructions: |
 
   Unlike `code-reviewer`, re-running `adversary` once after a conformance fix is expected — a DIVERGES verdict is a hard gate, and confirming the fix actually closed it is the point.
 
+  ### Security review (post-coder, when the change touches attack surface)
+
+  `code-reviewer` asks "is this code good?" and `adversary` asks "is this the code the plan asked for?" — neither asks "can this code be abused?" Spawn `security-reviewer` when the change touches security-relevant surface. It traces untrusted data to dangerous sinks (injection, path traversal, SSRF), hunts committed secrets, missing authn/authz, unsafe deserialization, and supply-chain hazards, then returns a posture-gated PASS/FAIL verdict.
+
+  **When to spawn it** — ANY of these:
+
+  1. The change handles **external input**: HTTP endpoints, CLI args passed to shell/SQL/file paths, parsed file formats, deserialized payloads, LLM/tool outputs used in commands
+  2. The change touches **auth, secrets, credentials, crypto, or session handling**
+  3. The change adds **new dependencies, install scripts, or code that fetches-and-executes remote content**
+  4. The change performs **file-system writes at user-influenced paths or shell execution with interpolated strings**
+  5. **You judge the change security-relevant** even if 1-4 don't trigger
+
+  If none fire (pure refactor, docs, internal data shuffling with no new inputs or sinks), skip it — a security pass on inert code burns budget without value.
+
+  **Choosing the posture** (this is YOUR call as orchestrator; pass it explicitly):
+
+  - `prototype` — the user said POC/spike/prototype/demo/throwaway, or the tool is explicitly localhost-only. Blocks Critical only.
+  - `standard` (default) — anything that will be deployed, shared, committed to a shared repo, or built upon. Blocks Critical + High.
+  - `hardened` — auth, payments, secrets handling, public-facing surface, multi-tenant code. Blocks Critical + High + Medium.
+
+  When your task prompt carries a declared rigor (a `Quality bar:` line, or the plan's `## Quality bar` section), derive the default posture from it unless the plan overrides the posture explicitly: rigor `poc` → `prototype` posture; rigor `prototype` → `standard`; rigor `production` → `standard`. `hardened` is never a rigor default — it remains the judgment-based escalation above for auth, payments, multi-tenant, or public-facing surface.
+
+  When in doubt, use `standard`. Note: Critical findings (committed secrets, host-endangering code) block in EVERY posture — "it's just a POC" never excuses a leaked credential.
+
+  **Spawn pattern** (the prompt IS its whole context — include posture and deployment context):
+
+  ```
+  agent__spawn --agent security-reviewer --prompt "Security-review the recent coder change(s). Return PASS/FAIL.
+
+  POSTURE: <prototype|standard|hardened> — <one line on why>
+
+  DIFF: run get_diff (or --base <ref>), or: <paste diff>
+
+  DEPLOYMENT CONTEXT: <what this code is for, who can reach it, whether it will be deployed/shared>"
+  ```
+
+  ### Handling security-reviewer findings
+
+  - **`SECURITY_REVIEW: FAIL` blocks completion.** Do not mark the task done. Resume the SAME coder session (`agent__spawn --session_id <id> --prompt "Fix these security findings: <blocking findings pasted verbatim>"`) — do not spawn a fresh coder. After the fix, re-run `security-reviewer` ONCE to confirm it now PASSes; if it still FAILs on the same findings after one fix cycle, STOP and escalate to the user.
+  - **`SECURITY_REVIEW: PASS`** — proceed. Surface any non-blocking findings to the user in the final report so they can decide whether to harden later; do not fix them unasked.
+  - **`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.
+  - **Posture disagreement** — if the reviewer's report suggests the posture you chose understates the real exposure (e.g. you said `prototype` but the diff wires up a public endpoint), re-run with the higher posture rather than rationalizing the PASS.
+
+  Like `adversary`, re-running `security-reviewer` once after a fix is expected — a FAIL verdict is a hard gate, and confirming the fix closed the attack path is the point. Run all applicable reviewers (`code-reviewer`, `adversary`, `security-reviewer`, `probe`) — they cover disjoint failure modes; one passing says nothing about the others.
+
+  ### Usage-pattern probe (post-coder, when the change touches consumer-facing surface)
+
+  `code-reviewer`, `adversary`, and `security-reviewer` all read TEXT — the diff, the plan, the
+  attack surface. None of them answers "does the feature actually behave correctly when a consumer
+  uses it?" Spawn `probe` when the change touches consumer-facing surface. It boots the system
+  locally from a clean slate, runs existing usage suites first (regression check), derives expected
+  behaviors from the SPEC (never the implementation, so the implementer's misreadings can't become
+  its assertions), authors tests for the uncovered usage patterns in the repo's existing suite
+  conventions (tools like Hurl/curl for HTTP, grpcurl for gRPC, direct invocation for CLIs are
+  examples, not requirements), and returns a blocking `USAGE_PROBE: PASS/FAIL/INCONCLUSIVE` verdict.
+
+  **When to spawn it** — ANY of these:
+
+  1. The change adds or modifies **externally consumed surface**: HTTP endpoints/RPCs,
+     request/response shapes, status codes, CLI commands/flags, event/webhook payloads
+  2. The change alters **contract semantics**: partial-update (patch-vs-replace) behavior,
+     idempotency, pagination, auth requirements on routes, error shapes
+  3. **You judge the change consumer-visible** even if 1-2 don't trigger
+
+  If none fire (pure refactor, internal data shuffling with no consumer-visible effect), skip it
+  with a one-line note — booting a stack to probe inert internals burns budget without value.
+
+  **Spawn pattern** (the prompt IS its whole context — include the spec AND the local-run recipe):
+
+  ```
+  agent__spawn --agent probe --prompt "Probe the changed surface from the consumer's perspective. Return PASS/FAIL/INCONCLUSIVE.
+
+  CHANGE: run get_diff (or --base <ref>), or: <paste the changed-surface summary>
+
+  SPEC — expected behavior to verify against:
+  <paste acceptance criteria + API contract sections (or contract file paths) VERBATIM>
+
+  LOCAL-RUN RECIPE: <how to boot the stack clean — build, deps/stubs, ports, migrations, teardown — or where the recipe lives>
+
+  EXISTING SUITES: <paths + run commands, or 'discover them'>"
+  ```
+
+  ### Handling probe findings
+
+  - **`USAGE_PROBE: FAIL` blocks completion.** Do not mark the task done. Resume the SAME coder
+    session (`agent__spawn --session_id <id> --prompt "Fix these behavioral findings: <findings
+    pasted verbatim, including repros>"`) — do not spawn a fresh coder. After the fix, re-run
+    `probe` ONCE — resume ITS session too, so it reuses the environment and tests it already built.
+    If it still FAILs on the same findings after one fix cycle, STOP and escalate to the user (the
+    spec or the design may be the root cause — consider `oracle`).
+  - **`USAGE_PROBE: PASS`** — proceed. Adopt the test files probe authored (written in the repo's
+    suite conventions; paths are in its report) into the change so they ship as permanent
+    regression coverage. Surface any stale-test or recipe observations to the user.
+  - **`USAGE_PROBE: INCONCLUSIVE`** — the ENVIRONMENT, not the code, is the blocker. Never treat it
+    as PASS or FAIL. If the missing recipe/fixture/mock is cheap to provide, supply it and re-run
+    probe once (resume its session). Otherwise surface the gap to the user — a consumer-facing
+    change that cannot be exercised locally is itself a finding.
+  - **Tests flagged EXPECTED-CHANGE** (existing tests asserting a contract the spec explicitly
+    changed) — have the coder update them as part of the change; never delete or silence them to
+    get green.
+
+  Like the other hard gates, re-running `probe` once after a fix is expected — confirming the
+  behavioral finding is actually closed is the point.
+
+  ### Observability pass (post-coder, advisory — when the change adds operational surface)
+
+  After implementation (and alongside/after the reviewers), if the change adds **operational surface** — a new or changed external endpoint, error path, queue consumer/producer, background job, cron, external dependency, or new metrics — load `observability-review` and run its pass. If none of these apply, skip with a one-line note.
+
+  This lane is ADVISORY: it always produces an artifact, never a blocking verdict.
+
+  1. Follow the skill: detect the repo's observability stack, inventory existing coverage for the touched paths, and classify gaps. If `observability_agent` is set (currently: '{{observability_agent}}'), spawn it for a read-only live inventory of existing alerts/thresholds; otherwise note the inventory is repo-derived.
+  2. **Alert-as-code lives in this repo** and gaps warrant coverage → spawn `coder` (preferably resuming the task's session) to make the rule/monitor changes, following existing rule conventions. These are ordinary code changes — the usual review gates apply to them.
+  3. **Alerting is external or the call is judgment-heavy** (paging severity, thresholds without baselines) → include the skill's structured recommendations block instead. Never touch external alerting systems.
+  4. Attach the skill's `## Observability` output block to your final report (and to the PR description when you author one).
+
+  Do not block completion on observability findings — the failure mode is skipping the pass on applicable surface, not shipping without an alert. Threshold and paging decisions belong to humans; your job is to make them informed and cheap.
+
   ## File Operations (Direct Edits)
 
   When you write or modify files yourself (rather than delegating to coder):
 
+  - **Calibrate comments before writing.** Load `comment-discipline` and note the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you read; write comments to match. When the signal is weak, write NO comment.
+  - **Calibrate logging before writing.** When the change touches boundaries, error paths, jobs, or state transitions, load `logging-discipline` and note the repo's logging register (logger, message style, payload vs IDs, level semantics) from the same sibling reads; match it. No discernible convention → its best-judgment defaults. Never leave a new error path silently swallowed, and never delete existing log lines as drive-by cleanup.
   - **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.
   - **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.
   - **NEVER write files via `execute_command`.** Do not use:
@@ -358,6 +496,10 @@ instructions: |
 
   ## Phase 7 - Failure Recovery
 
+  ### Hard bugs: load `diagnosing-bugs` BEFORE strike 2
+
+  A first fix attempt may go on the error message alone. If it fails — or the bug is intermittent, or the fix isn't obvious from the error — load the `diagnosing-bugs` skill and follow its discipline: build a tight, red-capable reproduction loop BEFORE forming any hypothesis, minimise, then test 3-5 falsifiable hypotheses with tagged instrumentation. Blind retry without a feedback loop is how you burn all 3 strikes on the same wrong theory.
+
   ### 3-strike rule
 
   After 3 consecutive failed fix attempts on the same problem:
@@ -376,7 +518,7 @@ instructions: |
 
   ### Authoring lifecycle (no code changes)
 
-  1. Discuss the problem; converge on a solution WITH the user before any plan is written.
+  1. Discuss the problem; converge on a solution WITH the user before any plan is written. Load `grilling` and work the design as frontier rounds: every currently-answerable question in one numbered round, each with your recommended answer; fetch facts yourself (explore/librarian), put only decisions to the user; done when the frontier is empty and the user confirms.
   2. Load `plan-authoring`. Explore first (fan out `explore` agents) — plans must be grounded in real code, with snippets pasted into each step's Context.
   3. Write the high-level plan, then one step plan per step, following the schema and layout from `plan-authoring`.
   4. **Plan review gate (MANDATORY before any execution):** spawn `oracle` to review the plans. Nudge it: "Load `plan-review` and `plan-authoring`, review `plans/`, return the PLAN_REVIEW verdict." REJECT → fix the complaints, re-submit. Do not start execution on an unreviewed or rejected plan.

assets/config-template.yaml

@@ -0,0 +1,279 @@
+# Coyote configuration. Generated by the first-run wizard.
+# Every setting is listed with its effective value and a short description.
+# For richer examples of each section, see
+# https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml
+
+# ---- LLM ----
+__MODEL_BLOCK__
+temperature: null                # Set default temperature parameter (0, 1)
+top_p: null                      # Set default top-p parameter, with a range of (0, 1) or (0, 2) depending on the model
+
+# ---- Behavior ----
+dry_run: false                   # Display the messages that would be sent to the LLM without actually sending them
+stream: true                     # Controls whether to use the stream-style APIs when querying for completions from LLM clients
+save: true                       # Indicates whether to persist the conversation to messages.md for posterity
+keybindings: emacs               # Choose keybinding style (emacs, vi)
+editor: null                     # Specifies the editor used to edit the input buffer or session. (e.g. vim, emacs, nano, hx). Defaults to $EDITOR
+wrap: auto                       # Controls text wrapping (no, auto, <max-width>)
+wrap_code: false                 # Enables or disables the wrapping of code blocks
+
+# ---- 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 (it 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
+__SECRETS_BLOCK__
+
+# ---- 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
+                                 # Example:
+                                 #   mapping_tools:
+                                 #     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.
+                                 # 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: null              # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools').
+                                 # Null/missing = all tools in the global tools dir are visible; [] = none;
+                                 # an explicit list makes only those tools visible.
+                                 # Example:
+                                 #   visible_tools:
+                                 #     - execute_command.sh
+                                 #     - fs_cat.sh
+                                 #     - fs_ls.sh
+
+# ---- 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.
+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
+visible_skills: null             # The universe of skills allowed to be enabled in any context. null = all installed.
+                                 # Example:
+                                 #   visible_skills:
+                                 #     - ai-slop-remover
+                                 #     - code-review
+                                 #     - git-master
+
+# ---- Macros ----
+# Macros are Coyote's custom commands: named sequences of REPL commands and prompts, invoked directly by name
+# (a macro file named `review.yaml` runs as `.review [args]`; built-in commands always win a name collision).
+# Workspace-local macros in `.coyote/macros/` shadow same-named global macros (skip them with --no-workspace-macros).
+# See the [Macros documentation](https://github.com/Dark-Alex-17/coyote/wiki/Macros) for more details.
+enabled_macros: null             # Which macros are invocable by default (no role/agent/session active). null = all visible.
+                                 # An empty list means NO macros are invocable. Accepts either a YAML list or a
+                                 # comma-separated string. Roles, agents, and sessions may define their own
+                                 # `enabled_macros`; the most specific active one wins (session > agent > role > global).
+                                 # Example (list form):
+                                 #   enabled_macros:
+                                 #     - generate-commit-message
+                                 # Example (comma-separated form):
+                                 #   enabled_macros: generate-commit-message,review
+
+# ---- MCP Servers ----
+# See the [MCP Servers documentation](https://github.com/Dark-Alex-17/coyote/wiki/MCP-Servers) for more details
+mcp_server_support: true         # Enables or disables MCP servers (globally)
+mapping_mcp_servers: {}          # Alias for an MCP server or set of servers
+                                 # Example:
+                                 #   mapping_mcp_servers:
+                                 #     git: github,gitmcp
+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
+mcp_tools: null                  # Per-server MCP tool allowlists (glob patterns: * and ? supported).
+                                 # Tools that match no pattern are hidden from the model as if they
+                                 # don't exist. Stacks with the other allowlist layers (mcp.json
+                                 # `allowedTools`, role, agent, session, skill, graph node). Every
+                                 # configured layer must allow a tool, so layers only ever narrow.
+                                 # An empty list blocks all of a server's tools.
+                                 # Example:
+                                 #   mcp_tools:
+                                 #     github:
+                                 #       - get_*
+                                 #       - list_*
+                                 #     slack: []
+
+# ---- Auto-Continue (Todo System) ----
+# The auto-continue system provides built-in task tracking for improved reliability.
+# When enabled, the model can create todo lists and the system will automatically
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/coyote/wiki/TODO-System) for more information
+auto_continue: false             # Enable automatic continuation when incomplete todos remain (default: false)
+max_auto_continues: 10           # Maximum number of automatic continuations before stopping (default: 10)
+inject_todo_instructions: true   # Inject default todo usage instructions into the system prompt (default: true)
+continuation_prompt: null        # Custom prompt used when auto-continuing. If null, uses built-in default
+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
+
+# ---- Prelude ----
+repl_prelude: null               # Set a default session or role for REPL mode to use (e.g. role:<name>, session:<name>, <session>:<role>)
+cmd_prelude: null                # Set a default session or role for CMD mode to use (e.g. role:<name>, session:<name>, <session>:<role>)
+agent_session: null              # Set a session to use when starting an agent (e.g. temp, default)
+
+# ---- Session ----
+# See the [Session documentation](https://github.com/Dark-Alex-17/coyote/wiki/Sessions) for more information
+save_session: null               # Controls the persistence of the session. If true, auto save; if false, don't auto-save; if null, ask the user what to do
+compression_threshold: 4000      # Compress the session when the token count reaches or exceeds this threshold
+compression_keep_last: 0         # Number of most-recent messages to keep visible after compression (0 = compress all messages)
+summarization_prompt: null       # The text prompt used for creating a concise summary of session messages. If null, uses built-in default
+summary_context_prompt: null     # The text prompt used for including the summary of the entire session as context to the model. If null, uses built-in default
+max_tool_result_chars: null      # Cap on tool result characters forwarded to the model per call (null = no cap)
+max_concurrent_jobs: null        # Max background jobs (`job__*` tools) running at once per context (null = 5; 0 disables background jobs entirely)
+
+# ---- Memory ----
+# See the [Memory documentation](https://github.com/Dark-Alex-17/coyote/wiki/Memory) for more information.
+# Memory is opt-in by workspace presence (`.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 (null = 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 (null = 12000).
+                                 # Indexes plus drill file bodies are injected up to this cap.
+
+# ---- Workspace Instructions ----
+# Human-curated project instructions injected read-only into the system prompt, in full.
+# Coyote walks up from the current directory and injects the first match from the file
+# chain below (per directory, in order). Scaffold with `coyote --init-instructions`.
+# Disable per-invocation with --no-workspace-instructions, or override the chain with
+# repeatable --workspace-instructions-file flags.
+workspace_instructions: null     # null/true = inject when an instructions file exists; false = never inject
+workspace_instructions_files: null # File name chain to search, in priority order.
+                                   # Default: [COYOTE.md, AGENTS.md, CLAUDE.md, GEMINI.md]
+                                   # Set to a custom list to reorder or drop fallbacks, e.g.:
+                                   #   workspace_instructions_files: [COYOTE.md]
+
+# ---- 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
+rag_reranker_model: null         # Specifies the reranker model used for sorting retrieved documents; Coyote uses Reciprocal Rank Fusion by default
+rag_top_k: 5                     # Specifies the number of documents to retrieve for answering queries
+rag_chunk_size: null             # Defines the size of chunks for document processing in characters
+rag_chunk_overlap: null          # Defines the overlap between chunks
+rag_template: null               # Defines the query structure using variables like __CONTEXT__, __SOURCES__, and __INPUT__
+                                 # to tailor searches to specific needs. If null, uses built-in default
+rag_extractor_model: null        # LLM model for graph-based entity/relationship extraction; when set, enables a graph RAG signal alongside vector and BM25
+rag_extractor_prompt: null       # Custom extraction prompt template; must contain __CHUNK__ placeholder; defaults to built-in prompt when null
+rag_graph_hops: 1                # Number of hops to expand from matched entities at query time (0 = seed nodes only; 1 = direct neighbors; increase for denser graphs)
+
+# Define document loaders to control how RAG and `.file`/`--file` load files of specific formats.
+document_loaders: {}
+                                 # You can add custom loaders using the following syntax:
+                                 #   <file-extension>: <command-to-load-the-file>
+                                 # Note: Use `$1` for input file and `$2` for output file. If `$2` is omitted, use stdout as output.
+                                 # Examples:
+                                 #   document_loaders:
+                                 #     pdf: 'pdftotext $1 -' # https://poppler.freedesktop.org
+                                 #     docx: 'pandoc --to plain $1' # https://pandoc.org
+                                 #     jina: 'curl -fsSL https://r.jina.ai/$1 -H "Authorization: Bearer {{JINA_API_KEY}}"' # Requires a Jina API key in the Coyote vault
+
+# ---- Appearance ----
+highlight: true                  # Controls syntax highlighting
+raw_markdown: false              # When true, render markdown as raw text with syntax highlighting only. When false (default), transforms markdown syntax (headings, bold, lists, etc.) into styled terminal output
+theme: null                      # null = the built-in dark theme; set to `light` for the built-in light theme.
+                                 # Custom themes: place a `dark.tmTheme` or `light.tmTheme` file in the Coyote config
+                                 # directory and it is used in place of the corresponding built-in.
+
+# ---- REPL Prompt ----
+# Custom REPL left/right prompts; see the [REPL Prompt Documentation](https://github.com/Dark-Alex-17/coyote/wiki/REPL-Prompt) for more information
+left_prompt: null                # If null, uses the built-in default:
+                                 #   '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
+right_prompt: null               # If null, uses the built-in default:
+                                 #   '{color.cyan}{?reasoning_effort [{reasoning_effort}] }{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
+
+# ---- Miscellaneous ----
+user_agent: null                 # Set User-Agent HTTP header, use `auto` for coyote/<current-version>
+save_shell_history: true         # Whether to save shell execution command to the history file
+sync_models_url: null            # URL to sync model changes from. If null, uses the built-in default:
+                                 #   https://raw.githubusercontent.com/Dark-Alex-17/coyote/refs/heads/main/models.yaml
+
+# ---- Clients ----
+# See the [Clients documentation](https://github.com/Dark-Alex-17/coyote/wiki/Clients) for more details
+#
+# All clients have the following configuration:
+# - type: xxxx
+#   name: xxxx                                      # Only use it to distinguish clients with the same client type. Optional
+#   models:
+#     - name: xxxx                                  # Chat model
+#       max_input_tokens: 100000
+#       supports_vision: true
+#       supports_function_calling: true
+#     - name: xxxx                                  # Embedding model
+#       type: embedding
+#       default_chunk_size: 1500
+#       max_batch_size: 100
+#     - name: xxxx                                  # Reranker model
+#       type: reranker
+#   patch:                                          # Patch API calls
+#     chat_completions:                             # API type; Possible values: chat_completions, embeddings, and rerank
+#       <regex>:                                    # The regex to match model names, e.g. '.*' 'gpt-4o' 'gpt-4o|gpt-4-.*'
+#         url: ''                                   # Patch request URL
+#         body:                                     # Patch request body
+#           <json>
+#         headers:                                  # Patch request headers
+#           <key>: <value>
+#   extra:
+#     proxy: socks5://127.0.0.1:1080                # Set proxy
+#     connect_timeout: 10                           # Set timeout in seconds for connect to api
+#     read_timeout: 300                             # Set timeout in seconds for a read stall (no bytes received); 0 disables (default: 300)
+__CLIENTS_BLOCK__

assets/functions/mcp.json

@@ -21,8 +21,7 @@
     },
     "iwe": {
       "type": "stdio",
-      "command": "iwec",
-      "args": ["--project", "."]
+      "command": "iwec"
     }
   }
 }

assets/functions/scripts/run-agent.py

@@ -27,14 +27,30 @@ def _ensure_cwd_venv():
 _ensure_cwd_venv()
 
 
+def resolve_dir(env_name, default_path):
+    """Resolve a directory at run time.
+
+    Prefer the override env var when set, otherwise fall back to the default
+    path derived from this script's own location, so the shim keeps working
+    when the config dir moves or is shared across environments with different
+    home directories.
+    """
+    value = os.environ.get(env_name)
+    if value:
+        return value
+    return os.path.normpath(default_path)
+
+
 def main():
     (agent_func, raw_data) = parse_argv()
     agent_data = parse_raw_data(raw_data)
 
-    root_dir = "{config_dir}"
-    setup_env(root_dir, agent_func, raw_data)
+    self_dir = os.path.dirname(os.path.abspath(__file__))
+    agent_dir = os.path.normpath(os.path.join(self_dir, ".."))
+    root_dir = resolve_dir("{root_dir_env}", os.path.join(self_dir, "{root_dir_rel}"))
+    setup_env(root_dir, agent_dir, agent_func, raw_data)
 
-    agent_tools_path = os.path.join(root_dir, "agents/{agent_name}/tools.py")
+    agent_tools_path = os.path.join(agent_dir, "tools.py")
     run(agent_tools_path, agent_func, agent_data)
 
 
@@ -65,12 +81,12 @@ def parse_argv():
     return agent_func, agent_data
 
 
-def setup_env(root_dir, agent_func, raw_data):
+def setup_env(root_dir, agent_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_ROOT_DIR"] = agent_dir
     os.environ["LLM_AGENT_CACHE_DIR"] = os.path.join(root_dir, "cache", "{agent_name}")
     os.environ["LLM_AGENT_RAW_JSON"] = raw_data
 

assets/functions/scripts/run-agent.sh

@@ -5,13 +5,30 @@
 set -e
 
 main() {
-    root_dir="{config_dir}"
+    self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    agent_dir="$(cd "$self_dir/.." && pwd)"
+    root_dir="$(resolve_dir "{root_dir_env}" "$self_dir/{root_dir_rel}")"
+    functions_dir="$(resolve_dir "{functions_dir_env}" "$self_dir/{functions_dir_rel}")"
     parse_argv "$@"
     setup_env
-    tools_path="$root_dir/agents/{agent_name}/tools.sh"
+    tools_path="$agent_dir/tools.sh"
     run
 }
 
+# Resolve a directory at run time: prefer the override env var ($1) when set,
+# otherwise fall back to the default path ($2) derived from this script's own
+# location, so the shim keeps working when the config dir moves or is shared
+# across environments with different home directories.
+resolve_dir() {
+    local override
+    override="$(printenv "$1" 2>/dev/null || true)"
+    if [[ -n "$override" ]]; then
+        echo "$override"
+    else
+        (cd "$2" 2>/dev/null && pwd) || echo "$2"
+    fi
+}
+
 parse_argv() {
 		agent_func="$1"
     if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
@@ -29,9 +46,9 @@ setup_env() {
     export LLM_ROOT_DIR="$root_dir"
     export LLM_AGENT_NAME="{agent_name}"
     export LLM_AGENT_FUNC="$agent_func"
-    export LLM_AGENT_ROOT_DIR="$LLM_ROOT_DIR/agents/{agent_name}"
+    export LLM_AGENT_ROOT_DIR="$agent_dir"
     export LLM_AGENT_CACHE_DIR="$LLM_ROOT_DIR/cache/{agent_name}"
-    export LLM_PROMPT_UTILS_FILE="{prompt_utils_file}"
+    export LLM_PROMPT_UTILS_FILE="$functions_dir/utils/prompt-utils.sh"
     export LLM_AGENT_RAW_JSON="$agent_data"
 }
 
@@ -59,6 +76,10 @@ run() {
         die "error: no JSON data"
     fi
 
+    if [[ ! -f "$tools_path" ]]; then
+        die "error: agent tools script not found: $tools_path"
+    fi
+
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tools_path="$(cygpath -w "$tools_path")"
@@ -122,4 +143,3 @@ die() {
 }
 
 main "$@"
-

assets/functions/scripts/run-agent.ts

@@ -3,17 +3,38 @@
 // Usage: ./{agent_name}.ts <agent-func> <agent-data>
 
 import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import { pathToFileURL } from "url";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+function selfDir(): string {
+  if (typeof __dirname !== "undefined") {
+    return __dirname;
+  }
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+// Resolve a directory at run time: prefer the override env var when set,
+// otherwise fall back to the default path derived from this script's own
+// location, so the shim keeps working when the config dir moves or is shared
+// across environments with different home directories.
+function resolveDir(envName: string, defaultPath: string): string {
+  const value = process.env[envName];
+  if (value) {
+    return value;
+  }
+  return resolve(defaultPath);
+}
 
 async function main(): Promise<void> {
   const { agentFunc, rawData } = parseArgv();
   const agentData = parseRawData(rawData);
 
-  const configDir = "{config_dir}";
-  setupEnv(configDir, agentFunc, rawData);
+  const binDir = selfDir();
+  const agentDir = resolve(binDir, "..");
+  const configDir = resolveDir("{root_dir_env}", join(binDir, "{root_dir_rel}"));
+  setupEnv(configDir, agentDir, agentFunc, rawData);
 
-  const agentToolsPath = join(configDir, "agents", "{agent_name}", "tools.ts");
+  const agentToolsPath = join(agentDir, "tools.ts");
   await run(agentToolsPath, agentFunc, agentData);
 }
 
@@ -48,12 +69,17 @@ function parseArgv(): { agentFunc: string; rawData: string } {
   return { agentFunc, rawData: agentData };
 }
 
-function setupEnv(configDir: string, agentFunc: string, rawData: string): void {
+function setupEnv(
+  configDir: string,
+  agentDir: 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_ROOT_DIR"] = agentDir;
   process.env["LLM_AGENT_CACHE_DIR"] = join(configDir, "cache", "{agent_name}");
   process.env["LLM_AGENT_RAW_JSON"] = rawData;
 }

assets/functions/scripts/run-tool.py

@@ -27,14 +27,30 @@ def _ensure_cwd_venv():
 _ensure_cwd_venv()
 
 
+def resolve_dir(env_name, default_path):
+    """Resolve a directory at run time.
+
+    Prefer the override env var when set, otherwise fall back to the default
+    path derived from this script's own location, so the shim keeps working
+    when the config dir moves or is shared across environments with different
+    home directories.
+    """
+    value = os.environ.get(env_name)
+    if value:
+        return value
+    return os.path.normpath(default_path)
+
+
 def main():
     raw_data = parse_argv()
     tool_data = parse_raw_data(raw_data)
 
-    root_dir = "{root_dir}"
+    self_dir = os.path.dirname(os.path.abspath(__file__))
+    root_dir = resolve_dir("{root_dir_env}", os.path.join(self_dir, "{root_dir_rel}"))
+    functions_dir = resolve_dir("{functions_dir_env}", os.path.join(self_dir, "{functions_dir_rel}"))
     setup_env(root_dir, raw_data)
 
-    tool_path = "{tool_path}.py"
+    tool_path = os.path.join(functions_dir, "tools", "{function_name}.py")
     run(tool_path, "run", tool_data)
 
 

assets/functions/scripts/run-tool.sh

@@ -5,13 +5,29 @@
 set -e
 
 main() {
-    root_dir="{root_dir}"
+    self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    root_dir="$(resolve_dir "{root_dir_env}" "$self_dir/{root_dir_rel}")"
+    functions_dir="$(resolve_dir "{functions_dir_env}" "$self_dir/{functions_dir_rel}")"
     parse_argv "$@"
     setup_env
-    tool_path="{tool_path}.sh"
+    tool_path="$functions_dir/tools/{function_name}.sh"
     run
 }
 
+# Resolve a directory at run time: prefer the override env var ($1) when set,
+# otherwise fall back to the default path ($2) derived from this script's own
+# location, so the shim keeps working when the config dir moves or is shared
+# across environments with different home directories.
+resolve_dir() {
+    local override
+    override="$(printenv "$1" 2>/dev/null || true)"
+    if [[ -n "$override" ]]; then
+        echo "$override"
+    else
+        (cd "$2" 2>/dev/null && pwd) || echo "$2"
+    fi
+}
+
 parse_argv() {
     if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
         tool_data="$(cat "$LLM_TOOL_DATA_FILE")"
@@ -28,7 +44,7 @@ setup_env() {
     export LLM_ROOT_DIR="$root_dir"
     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_PROMPT_UTILS_FILE="$functions_dir/utils/prompt-utils.sh"
     export LLM_TOOL_RAW_JSON="$tool_data"
 }
 
@@ -56,6 +72,10 @@ run() {
         die "error: no JSON data"
     fi
 
+    if [[ ! -f "$tool_path" ]]; then
+        die "error: tool script not found: $tool_path"
+    fi
+
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tool_path="$(cygpath -w "$tool_path")"

assets/functions/scripts/run-tool.ts

@@ -3,17 +3,41 @@
 // Usage: ./{function_name}.ts <tool-data>
 
 import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import { pathToFileURL } from "url";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+function selfDir(): string {
+  if (typeof __dirname !== "undefined") {
+    return __dirname;
+  }
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+// Resolve a directory at run time: prefer the override env var when set,
+// otherwise fall back to the default path derived from this script's own
+// location, so the shim keeps working when the config dir moves or is shared
+// across environments with different home directories.
+function resolveDir(envName: string, defaultPath: string): string {
+  const value = process.env[envName];
+  if (value) {
+    return value;
+  }
+  return resolve(defaultPath);
+}
 
 async function main(): Promise<void> {
   const rawData = parseArgv();
   const toolData = parseRawData(rawData);
 
-  const rootDir = "{root_dir}";
+  const binDir = selfDir();
+  const rootDir = resolveDir("{root_dir_env}", join(binDir, "{root_dir_rel}"));
+  const functionsDir = resolveDir(
+    "{functions_dir_env}",
+    join(binDir, "{functions_dir_rel}"),
+  );
   setupEnv(rootDir, rawData);
 
-  const toolPath = "{tool_path}.ts";
+  const toolPath = join(functionsDir, "tools", "{function_name}.ts");
   await run(toolPath, "run", toolData);
 }
 

assets/functions/tools/execute_command.sh

@@ -20,5 +20,12 @@ main() {
     trap "rm -f '$script'" EXIT
     # shellcheck disable=SC2154
     printf '%s\n' "$argc_command" > "$script"
-    bash -e -o pipefail "$script" >> "$LLM_OUTPUT"
+    # No -e: the command gets standard interactive-shell semantics — the last
+    # statement decides the exit code, so trailing guards like `; exit 0` work
+    # and an intermediate non-zero status (grep with no matches, a failing
+    # test run being inspected) cannot abort the script mid-way. pipefail is
+    # kept so a failing pipeline stage still surfaces in the exit code. 2>&1:
+    # the harness only returns $LLM_OUTPUT on success, so without it stderr
+    # (git push, cargo progress, curl -v) vanishes from successful calls.
+    bash -o pipefail "$script" >> "$LLM_OUTPUT" 2>&1
 }

assets/functions/tools/fs_grep.sh

@@ -25,7 +25,11 @@ main() {
         exit 1
     fi
 
-    local grep_args=(-nH --color=never)
+    # --binary-files=text: GNU grep's binary heuristic false-positives on valid
+    # UTF-8 source files >=128KiB when a multibyte character straddles an
+    # internal read-buffer boundary, silently returning zero matches. This tool
+    # only searches text, so always force text mode.
+    local grep_args=(-nH --color=never --binary-files=text)
 
     if [[ -d "$search_path" ]]; then
         # Use -r (not -R) so symlinks to directories are NOT followed - this avoids

assets/functions/tools/fs_patch.sh

@@ -14,6 +14,11 @@ set -e
 #   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.
+# - Hunks anchor at the FIRST exact match of their context in the file, so include enough context to make each hunk
+#   unique. Hunks must appear in file order.
+# - Every hunk needs at least one context or removed line to anchor it; a hunk containing only additions is an error.
+# - Unrecognized lines inside a hunk are hard errors: every hunk line must start with ' ' (context), '-' (removal),
+#   or '+' (addition).
 # - 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
@@ -33,7 +38,11 @@ source "$LLM_PROMPT_UTILS_FILE"
 
 # shellcheck disable=SC2154
 main() {
-    argc_contents="$(jq -r '.content' <<< "$LLM_TOOL_RAW_JSON")"
+		# Command substitution strips *all* trailing newlines and `jq -r` appends one
+		# of its own, so read with `-j` and pin the real end of the content with a
+		# sentinel that is removed afterwards.
+		argc_contents="$(jq -j '.content' <<< "$LLM_TOOL_RAW_JSON"; printf x)"
+		argc_contents="${argc_contents%x}"
     argc_path="$(jq -r '.path' <<< "$LLM_TOOL_RAW_JSON")"
 
     if [[ ! -f "$argc_path" ]]; then
@@ -41,7 +50,19 @@ main() {
         exit 1
     fi
 
-    new_contents="$(patch_file "$argc_path" <(printf "%s" "$argc_contents"))"
+		# Same sentinel guard on the patched result, otherwise the trailing newline
+		# is stripped again on the way back out. `rc` preserves patch_file's exit
+		# status so a failure still aborts under `set -e`.
+		new_contents="$(patch_file "$argc_path" <(printf "%s" "$argc_contents"); rc=$?; printf x; exit "$rc")"
+		new_contents="${new_contents%x}"
+
+		# awk newline-terminates every printed line, so patching a file that lacks
+		# a final newline would silently add one. Preserve the original file's
+		# final-newline state instead.
+		if [[ -n "$(tail -c 1 "$argc_path")" ]]; then
+			new_contents="${new_contents%$'\n'}"
+		fi
+
     printf "%s" "$new_contents" | git diff --no-index "$argc_path" - || true
 
     guard_operation "Apply changes?"

assets/functions/tools/fs_write.sh

@@ -15,7 +15,12 @@ source "$LLM_PROMPT_UTILS_FILE"
 
 # shellcheck disable=SC2154
 main() {
-    argc_contents="$(jq -r '.content' <<< "$LLM_TOOL_RAW_JSON")"
+		# Command substitution strips *all* trailing newlines and `jq -r` appends one
+		# of its own, so read with `-j` and pin the real end of the content with a
+		# sentinel that is removed afterwards. Without this every written file loses
+		# its final newline, which breaks formatters such as `cargo fmt --check`.
+		argc_contents="$(jq -j '.content' <<< "$LLM_TOOL_RAW_JSON"; printf x)"
+		argc_contents="${argc_contents%x}"
     argc_path="$(jq -r '.path' <<< "$LLM_TOOL_RAW_JSON")"
 
     if [[ -f "$argc_path" ]]; then

assets/functions/tools/git_command.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Execute a git command. Strictly limited to a single git invocation: the command must start with 'git' and shell metacharacters (; & | < > ( ) $ `) are rejected outside single quotes — no pipes, chaining, redirection, or command substitution. Use git's own flags instead of pipes (e.g. 'git log -n 20' instead of piping to head). Output is never paginated and git will never prompt for input.
+# @option --command! The git command to execute (e.g. "git status --short").
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+main() {
+    # shellcheck disable=SC2154
+    argc_command="$(jq -r '.command' <<< "$LLM_TOOL_RAW_JSON")"
+
+    validate_command "$argc_command" "git"
+
+    guard_operation "Execute git command: $argc_command"
+
+    export GIT_PAGER=cat PAGER=cat GIT_TERMINAL_PROMPT=0
+    export GIT_EDITOR=true GIT_SEQUENCE_EDITOR=true
+
+    local script
+    script="$(mktemp)"
+    # shellcheck disable=SC2064
+    trap "rm -f '$script'" EXIT
+    printf '%s\n' "$argc_command" > "$script"
+    bash -e -o pipefail "$script" >> "$LLM_OUTPUT"
+}
+
+die() {
+    echo "$*" >&2
+    exit 1
+}
+
+# Ensure the command is a single plain invocation of $2 with no shell escape
+# hatches. Metacharacters are allowed inside single quotes (where bash treats
+# them as literals) but rejected everywhere else, including $ and ` inside
+# double quotes (expansion/substitution).
+validate_command() {
+    local cmd="$1" prog="$2"
+
+    local first
+    first="$(awk '{print $1}' <<< "$cmd")"
+    if [[ "$first" != "$prog" ]]; then
+        die "error: this tool only executes $prog commands; the command must start with '$prog' (got: '${first:-<empty>}')"
+    fi
+
+    local i c in_single=0 in_double=0 len=${#cmd}
+    for (( i = 0; i < len; i++ )); do
+        c="${cmd:i:1}"
+        if (( in_single )); then
+            [[ "$c" == "'" ]] && in_single=0
+            continue
+        fi
+        if (( in_double )); then
+            case "$c" in
+                '\') i=$((i + 1)) ;;
+                '"') in_double=0 ;;
+                '$' | '`') die "error: '$c' is not allowed inside double quotes (expansion/substitution is blocked); use single quotes for literal text" ;;
+            esac
+            continue
+        fi
+        case "$c" in
+            '\') i=$((i + 1)) ;;
+            "'") in_single=1 ;;
+            '"') in_double=1 ;;
+            ';' | '&' | '|' | '<' | '>' | '(' | ')' | '$' | '`')
+                die "error: shell metacharacter '$c' is not allowed; run a single $prog command with no pipes, chaining, redirection, or substitution (use $prog's own flags instead, and single quotes for literal text)"
+                ;;
+            $'\n')
+                die "error: newlines are not allowed; run a single $prog command"
+                ;;
+        esac
+    done
+    if (( in_single || in_double )); then
+        die "error: unbalanced quotes in command"
+    fi
+}

assets/functions/tools/web_search_coyote.sh

@@ -15,6 +15,11 @@ set -e
 #   - vertexai:gemini-*
 #   - perplexity:*
 #   - ernie:*
+#   - claude:*                       (Anthropic native web_search server tool)
+#   - openai:gpt-4o-search-preview   (and -mini-; requires an api-key openai
+#                                     client — the codex OAuth path uses the
+#                                     Responses API where this parameter
+#                                     does not exist)
 # @env LLM_OUTPUT=/dev/stdout The output path
 
 # shellcheck disable=SC2154
@@ -30,6 +35,13 @@ main() {
 }'
     elif [[ "$client" == "ernie" ]]; then
         export COYOTE_PATCH_ERNIE_CHAT_COMPLETIONS='{".*":{"body":{"web_search":{"enable":true}}}}'
+    elif [[ "$client" == "claude" ]]; then
+        export COYOTE_PATCH_CLAUDE_CHAT_COMPLETIONS='{".*":{"body":{"tools":[{"type":"web_search_20250305","name":"web_search","max_uses":5}]}}}'
+    elif [[ "$client" == "openai" ]]; then
+        # Chat Completions native search exists only on the search-preview
+        # models; the regex scopes the patch so other OpenAI models run
+        # unpatched instead of erroring on an unsupported parameter.
+        export COYOTE_PATCH_OPENAI_CHAT_COMPLETIONS='{"gpt-4o.*search-preview.*":{"body":{"web_search_options":{}}}}'
     fi
 
     coyote -m "$WEB_SEARCH_MODEL" "$argc_query" >> "$LLM_OUTPUT"

assets/functions/utils/prompt-utils.sh

@@ -186,7 +186,9 @@ input() {
 }
 
 confirm() {
-  trap "stty echo; exit" EXIT
+  # stty targets stdin, which is /dev/null when the host spawns tool scripts;
+  # point it at the real terminal and stay quiet when there isn't one.
+  trap "stty echo </dev/tty 2>/dev/null; exit" EXIT
   _prompt_text "$1 (y/N)"
   echo -en "\033[36m\c " >&2
 
@@ -229,7 +231,7 @@ list() {
   declare first_row
   first_row=$((last_row - opts_count + 1))
 
-  trap "_cursor_blink_on; stty echo; exit" 2
+  trap "_cursor_blink_on; stty echo </dev/tty 2>/dev/null; exit" 2
 
   _cursor_blink_off
 
@@ -275,7 +277,7 @@ checkbox() {
   declare first_row
   first_row=$((last_row - opts_count + 1))
 
-  trap "_cursor_blink_on; stty echo; exit" 2
+  trap "_cursor_blink_on; stty echo </dev/tty 2>/dev/null; exit" 2
 
   _cursor_blink_off
 
@@ -403,7 +405,7 @@ range() {
   declare current_row
   current_row=$((first_row - 1))
 
-  trap "_cursor_blink_on; stty echo; exit" 2
+  trap "_cursor_blink_on; stty echo </dev/tty 2>/dev/null; exit" 2
 
   _cursor_blink_off
 
@@ -528,7 +530,11 @@ guard_operation() {
 # +    print(f"Hello {name}")
 patch_file() {
   awk '
-    FNR == NR {
+    function isHeaderPair(i) {
+      return (patchLines[i] ~ /^--- / && patchLines[i+1] ~ /^\+\+\+ / && patchLines[i+2] ~ /^@@/)
+    }
+
+    FILENAME == ARGV[1] {
       lines[FNR] = $0
       next;
     }
@@ -547,11 +553,6 @@ patch_file() {
       while (patchLineIndex <= totalPatchLines) {
         line = patchLines[patchLineIndex]
 
-        if (line ~ /^--- / || line ~ /^\+\+\+ /) {
-          patchLineIndex++
-          continue
-        }
-
         if (line ~ /^@@/) {
           mode = "hunk"
           hunkIndex++
@@ -560,7 +561,22 @@ patch_file() {
         }
 
         if (mode == "hunk") {
-          while (patchLineIndex <= totalPatchLines && line ~ /^[-+ ]|^\s*$/ && line !~ /^--- /) {
+          while (patchLineIndex <= totalPatchLines) {
+            line = patchLines[patchLineIndex]
+
+            if (line ~ /^\\ No newline/) {
+              patchLineIndex++
+              continue
+            }
+
+            if (isHeaderPair(patchLineIndex)) {
+              break
+            }
+
+            if (line !~ /^[-+ ]/ && line !~ /^[ \t]*$/) {
+              break
+            }
+
             sanitizedLine = substr(line, 2)
 
             if (line !~ /^\+/) {
@@ -574,13 +590,37 @@ patch_file() {
             }
 
             patchLineIndex++
-            line = patchLines[patchLineIndex]
           }
 
           mode = "none"
-        } else {
-          patchLineIndex++
+          continue
         }
+
+        if (isHeaderPair(patchLineIndex)) {
+          patchLineIndex += 2
+          continue
+        }
+
+        if (line ~ /^\\ No newline/) {
+          patchLineIndex++
+          continue
+        }
+
+        if (hunkIndex == 0) {
+          # Preamble before the first hunk: tolerate prose, code fences, and lone headers.
+          patchLineIndex++
+          continue
+        }
+
+        if (line ~ /^[ \t]*$/ || line ~ /^```/) {
+          patchLineIndex++
+          continue
+        }
+
+        print "error: unrecognized line in patch (line " patchLineIndex "): " line > "/dev/stderr"
+        print "" > "/dev/stderr"
+        print "Every line inside a hunk must start with \" \" (context), \"-\" (removal), or \"+\" (addition)." > "/dev/stderr"
+        exit 1
       }
 
       if (hunkIndex == 0) {
@@ -593,6 +633,36 @@ patch_file() {
       }
 
       totalHunks = hunkIndex
+
+      if (totalLines == 0) {
+        for (h = 1; h <= totalHunks; h++) {
+          if (hunkTotalOriginalLines[h] > 0) {
+            print "error: unable to apply patch" > "/dev/stderr"
+            print "" > "/dev/stderr"
+            print "Hunk " h " expects existing content but the file is empty." > "/dev/stderr"
+            exit 1
+          }
+        }
+
+        for (h = 1; h <= totalHunks; h++) {
+          for (i = 1; i <= hunkTotalUpdatedLines[h]; i++) {
+            print hunkUpdatedLines[h,i]
+          }
+        }
+
+        exit 0
+      }
+
+      for (h = 1; h <= totalHunks; h++) {
+        if (hunkTotalOriginalLines[h] == 0) {
+          print "error: unable to apply patch" > "/dev/stderr"
+          print "" > "/dev/stderr"
+          print "Hunk " h " contains no context or removed lines; include at least one" > "/dev/stderr"
+          print "context line so the hunk can be anchored." > "/dev/stderr"
+          exit 1
+        }
+      }
+
       hunkIndex = 1
 
       for (lineIndex = 1; lineIndex <= totalLines; lineIndex++) {
@@ -603,7 +673,7 @@ patch_file() {
           nextLineIndex = lineIndex + 1
 
           for (i = 2; i <= hunkTotalOriginalLines[hunkIndex]; i++) {
-            if (lines[nextLineIndex] != hunkOriginalLines[hunkIndex,i]) {
+            if (nextLineIndex > totalLines || lines[nextLineIndex] != hunkOriginalLines[hunkIndex,i]) {
               if (i - 1 > bestPartialLen[hunkIndex]) {
                 bestPartialLen[hunkIndex] = i - 1
                 bestPartialAnchorLine[hunkIndex] = lineIndex
@@ -646,10 +716,14 @@ patch_file() {
             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"
+            if (bestPartialDivergeLine[failingHunk] > totalLines) {
+              print "The hunk expects additional lines beyond the end of the file (file has " totalLines " lines)." > "/dev/stderr"
+            } else {
               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"

assets/macros/generate-commit-message.yaml

@@ -1,2 +1,3 @@
+description: Generate a git commit message from the current diff
 steps:
   - .file `git diff` -- generate a git commit message

assets/sbx-kit/spec.yaml

@@ -9,11 +9,11 @@ kind: sandbox
 name: coyote
 displayName: Coyote
 description: >
-  An all-in-one, batteries-included LLM CLI tool featuring Shell Assistant,
+  The batteries-included runtime for LLMs, featuring Shell Assistant,
   CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros.
 
 sandbox:
-  image: 'darkalex17/coyote:v0.8.3'
+  image: 'darkalex17/coyote:v0.10.0'
   entrypoint: ['bash', '-lc', 'exec /home/agent/.cargo/bin/coyote']
 
 permissions:

assets/skills/cicd-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: Review CI/CD pipeline definitions - action/step pinning by SHA, token and credential permission scoping, secret exposure to fork-PR triggers, and cross-branch cache poisoning. Load when a diff touches workflow/pipeline files such as .github/workflows/*, GitLab CI config, or equivalent pipeline definitions. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing workflows, triggers, and permission blocks.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing CI/CD pipeline definitions. The generic correctness checklist asks "does this pipeline run?"; you ask **"what can this pipeline be made to do by someone who controls an input to it — a tag, a fork PR, a cache key?"** A workflow file is production code with production credentials that runs third-party code on every push, yet it is otherwise reviewed by nobody. Most pipeline incidents are not broken builds — they are a mutable action tag that started doing something new, a token scoped far beyond its job, or a secret handed to code from a fork.
+
+## When to load this skill
+
+The diff touches ANY of: workflow/pipeline files — `.github/workflows/*`, GitLab CI config, or equivalent pipeline definitions in other systems. If the diff is application code with unchanged pipelines — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs the domain's mechanized checker — `actionlint` for GitHub Actions workflows; your CONTEXT may already include its output — do not re-derive it. Spend your prose on what the linter cannot reach: whether a token's permissions match what the job actually does, what a fork-triggered run can see, whether a cache key crosses a trust boundary. If the repo plausibly warrants a linter config it lacks (workflow files but no `actionlint` wiring), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the trigger blocks and permission blocks before flagging, and state any exemption you rely on.
+
+### 1. 🟡 `[convention]` Actions pinned by mutable tag instead of SHA
+
+Does the diff reference third-party actions or pipeline steps by a mutable tag (`@v4`, `@main`) rather than a full commit SHA? A mutable tag means the code your pipeline runs — with its credentials — can change without any change in your repo; tags have been retargeted maliciously in the wild. The house fix is SHA-pinning with a tag comment (and a bot to update pins). First-party actions from the same repo/org can be exempt per repo convention — cite the convention if you rely on it.
+
+### 2. 🟡 `[convention]` Token/credential permissions broader than the job needs
+
+Does each job's token grant match what the job actually does? Look for missing explicit permission blocks (falling back to a broad default), write scopes on jobs that only read, and org-level credentials in jobs that need repo-level access. The finding names the scoped alternative: the specific permissions the job's steps use. A workflow-level broad grant with per-job narrowing is acceptable shape; per-job broad grants "to be safe" are the finding.
+
+### 3. 🔴 `[convention]` Secrets exposed to fork-PR triggers
+
+Can a pull request from a fork reach this workflow's secrets? The dangerous shapes: triggers that run with secret access on fork-controlled code (e.g. `pull_request_target` checking out the PR head), secrets passed into steps that execute fork-modified scripts, and label-gated runs where the gate is applied after checkout. This item is co-owned with `security-review`'s supply-chain checklist item — that skill owns the full exploitation analysis; you flag the exposure the moment the trigger/secret/checkout combination makes it possible. The severity stays 🔴 regardless of the declared quality bar — fork-reachable secrets are critical at every rigor, and this item should never be folded down. Workflows that run on fork PRs WITHOUT secrets, or with secrets only after a trusted-code boundary, are the correct shapes — verify the checkout ref before accepting them.
+
+### 4. 🟢 `[convention]` Cross-branch cache poisoning
+
+Do cache keys let an untrusted branch write cache entries that a trusted branch (main, release) later restores? Caches written by fork-PR or feature-branch runs and restored by default-branch runs let attacker-influenced artifacts flow into trusted builds. Check the cache key/scope construction and the platform's cache-isolation rules — some platforms already isolate caches by branch with one-way fallback; a pattern the platform provably isolates is exempt, and worth citing.
+
+## Ground-truth discipline
+
+- READ the trigger block and permission block of every workflow the diff touches — the risk is almost always in the trigger/checkout/secret combination, not in the step commands.
+- `fs_grep` sibling workflows for the house idioms (SHA-pinning style, permission-block placement, cache-key construction) and cite the sibling at file:line when flagging deviation.
+- Check what each referenced action actually is (first-party vs third-party, checkout target) before applying the pinning and fork-exposure items.
+- Do not assert platform behavior (default permissions, cache isolation) from memory alone when the repo's config could override it — check the org/repo-level settings files if present, and state assumptions otherwise.
+
+## What this skill does NOT check
+
+- The full exploitation analysis of exposed secrets, injection via untrusted workflow inputs (`${{ }}` interpolation attacks), and supply-chain trust of the pinned actions themselves → `security-review` (item 3 above is explicitly co-owned with its supply-chain item).
+- Whether deploy/release steps the pipeline runs are idempotent and safe to re-run → `transactional-integrity`.
+- Log output conventions of pipeline steps → `logging-discipline`.
+- Metrics/alerts on pipeline health and deploy outcomes → `observability-review`.

assets/skills/cli-review/SKILL.md

@@ -0,0 +1,58 @@
+---
+description: Review the command-line surface contract of a change - exit codes, stdout/stderr channel discipline, help text, non-interactive operation, signal/cleanup behavior, and config precedence. Load when a diff touches argument-parser definitions, the main/entrypoint of a binary, or subcommand modules. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing entrypoints, parsers, and exit paths.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing a command-line interface. The generic correctness checklist asks "does this command work when a human runs it?"; you ask **"does this command keep its contract with the scripts, pipes, and CI jobs that run it unattended?"** A CLI's real callers are rarely humans at a terminal — they are shell scripts branching on `$?`, pipelines parsing stdout, and cron jobs with no TTY. Most CLI breakage in the wild is not wrong logic; it is a success that exits 1, a diagnostic that corrupts a pipe, or a prompt that hangs a CI job forever.
+
+## When to load this skill
+
+The diff touches ANY of: argument-parser definitions (flag/option/subcommand declarations), the `main`/entrypoint of a binary, or subcommand modules. If the diff is library internals behind an unchanged command surface — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (shell linters, help-text validators); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what linters cannot reach: exit-code semantics on each error path, which stream a message lands on, whether a prompt has an escape hatch. If the repo plausibly warrants a linter config it lacks (shell scripts but no shell linter config), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — trace the actual exit paths and output calls before flagging.
+
+### 1. 🔴 `[correctness]` Error paths exiting 0 / success paths exiting non-zero
+
+Trace every exit path the diff adds or modifies: does each failure propagate a non-zero exit code all the way out of `main`, and does success exit 0? The classic bugs: an error that is printed and then falls through to a normal return; a caught exception that logs and continues; a match arm that swallows a `Result`. Scripts branch on `$?` — an inverted exit code silently corrupts every automation built on this command. This is the exit-code contract; it is never foldable and never rejectable.
+
+### 2. 🟡 `[convention]` Diagnostics on stdout corrupting pipeable output
+
+If the command's stdout is (or plausibly will be) piped or parsed — it prints data, JSON, lists, paths — then progress messages, warnings, and diagnostics on stdout corrupt the stream. Do new prints route diagnostics to stderr and reserve stdout for payload? A purely interactive command with no parseable output can be exempt — say so when you rely on that. Which *level and format* diagnostics use is `logging-discipline`'s question; yours is which stream they land on.
+
+### 3. 🟢 `[convention]` Missing or wrong --help for new flags
+
+Does every flag, option, and subcommand the diff adds appear in help output with an accurate description? Check the parser declarations: a flag with no help string, a stale description contradicting new behavior, or a new subcommand missing from the top-level help listing. Help text is the CLI's only discoverable documentation.
+
+### 4. 🟡 `[convention]` Interactive prompt with no non-interactive escape
+
+Does the diff add a prompt (confirmation, password, selection)? Then there must be a non-interactive path: a flag (`--yes`/`--force`-style), an environment variable, or reading from stdin — and ideally the prompt should detect a missing TTY rather than hang. A prompt with no escape hatch deadlocks CI and cron callers. Check what escape idiom the repo's existing prompts use and whether the new one matches.
+
+### 5. 🟡 `[convention]` No signal/cleanup handling for long-running commands with temp state
+
+If the diff adds a long-running command that creates temp files, lockfiles, partial output, or spawns children: what happens on Ctrl-C or SIGTERM? Look for signal handling, cleanup guards (drop/defer/finally/trap), or an idiom the repo already uses. Orphaned locks and half-written files are the finding. Short-lived commands with no temp state are exempt — this item is scoped to commands that hold state long enough for interruption to be a realistic event.
+
+### 6. 🟢 `[convention]` Config precedence violated or undocumented
+
+If the command reads configuration from more than one source, the conventional precedence is flag > environment variable > config file. Does the diff's resolution order honor that — and honor whatever order the repo has already established? A new setting that reads only the file when its siblings accept a flag override, or a precedence order documented nowhere, is the finding. Cite the repo's existing resolution code when flagging a deviation.
+
+## Ground-truth discipline
+
+- READ the full path from error site to process exit — exit-code bugs live in the propagation, not the error site. `fs_grep` for the exit/return conventions the entrypoint uses.
+- Check sibling subcommands for the established idioms (stderr usage, prompt escape flags, cleanup guards) — a new subcommand skipping the house pattern is the strongest form of evidence.
+- Do not flag hypothetical piping of a command that is documented interactive-only; note the assumption instead.
+
+## What this skill does NOT check
+
+- Whether argument or path inputs are exploitable (injection, traversal, secrets on the command line) → `security-review`.
+- Whether the state a command mutates is changed idempotently and atomically under reruns → `transactional-integrity`.
+- Log levels, formats, and message register of diagnostics → `logging-discipline` (this skill only checks which stream they use).
+- Metrics and alerting for operationally significant commands → `observability-review`.

assets/skills/code-review/SKILL.md

@@ -88,6 +88,7 @@ A diff review is a review of THE CHANGE, not the whole file:
 
 - Are names accurate? `get_user` that mutates is a lie; rename or split.
 - Could a competent reader understand this without comments?
+- Do NEW comments match the repo's comment register? You already read neighboring files for conventions — compare against them. Flag BOTH directions: narrated/restating comments in a repo that uses self-documenting code (each one is a finding, cite the line), AND missing doc comments on new public items in a repo that documents its public API. Comments explaining non-obvious *why* (decisions, workarounds, invariants) are warranted in every repo; comments captioning *what* the code plainly does are warranted in none.
 - Is there a simpler way to express the same logic?
 - Is the function doing one thing, or several things glued together?
 
@@ -96,6 +97,7 @@ A diff review is a review of THE CHANGE, not the whole file:
 - Does this change increase coupling between modules unnecessarily?
 - Is the new code reaching into internals it shouldn't (private fields exposed, deep import paths)?
 - Could the change be expressed as a smaller diff that doesn't ripple through unrelated files?
+- New helper/utility/constant introduced? `fs_grep` for an existing equivalent in the repo before accepting it — duplicating an existing helper is a finding; cite the original's path so the author can reuse it. (The inverse is not a finding: do not demand a new abstraction to unify two mildly similar blocks.)
 
 ## 5. Footguns
 
@@ -104,6 +106,29 @@ A diff review is a review of THE CHANGE, not the whole file:
 - Are error types specific enough to be actionable?
 - Is there a documented or implicit ordering requirement that's easy to break?
 
+## 6. Code smells (baseline heuristics)
+
+A fixed baseline of named smells (Fowler, *Refactoring* ch. 3) that applies even when the repo documents no standards. Three calibration rules bind it:
+
+1. **The repo overrides.** A documented or established repo convention always wins; where the codebase deliberately does something the baseline would flag, suppress the smell.
+2. **Always a judgment call.** Report each as a labelled heuristic ("possible Feature Envy"), never a hard violation — severity 🟢 Suggestion or 💡 Nitpick unless it compounds a real defect.
+3. **Skip anything tooling already enforces.** Linters and formatters own their territory.
+
+Each smell reads *what it is → how to fix*; match against the diff only:
+
+- **Mysterious Name**: a function/variable/type whose name doesn't reveal what it does or holds → rename; if no honest name comes, the design is murky.
+- **Duplicated Code**: the same logic shape in more than one hunk or file of the change → extract the shared shape, call it from both. (For duplication against EXISTING code, see the Coupling grep check above.)
+- **Feature Envy**: a method reaching into another object's data more than its own → move the method onto the data it envies.
+- **Data Clumps**: the same few fields/params travelling together — a type wanting to be born → bundle them into one type.
+- **Primitive Obsession**: a primitive/string standing in for a domain concept → give the concept its own small type.
+- **Repeated Switches**: the same `switch`/`if`-cascade on the same type recurring across the change → polymorphism, or one shared map.
+- **Shotgun Surgery**: one logical change forcing scattered edits across many files in the diff → gather what changes together into one module.
+- **Divergent Change**: one file edited for several unrelated reasons → split so each module changes for one reason.
+- **Speculative Generality**: abstraction/parameters/hooks added for needs nothing in the change has → delete; inline until a real need shows.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on → hide the walk behind one method on the first object.
+- **Middle Man**: a class/function that mostly delegates onward → cut it, call the real target directly.
+- **Refused Bequest**: a subclass/implementer ignoring or overriding most of what it inherits → drop the inheritance, use composition.
+
 ## What to flag
 
 - Correctness bugs.

assets/skills/codebase-design/SKILL.md

@@ -0,0 +1,61 @@
+---
+description: Shared vocabulary and principles for designing deep modules - module, interface, depth, seam, adapter, leverage, locality - plus the deletion test, dependency categories for safe deepening, and the design-it-twice pattern for exploring alternative interfaces. Load when designing or improving a module's interface, deciding where a seam goes, making code more testable, or when another skill or agent needs the deep-module vocabulary.
+---
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary (use these terms exactly)
+
+Consistent language is the point — don't substitute "component", "service", "API", or "boundary".
+
+- **Module**: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice.
+- **Interface**: everything a caller must know to use the module correctly — the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. ("API"/"signature" are too narrow: they name only the type-level surface.)
+- **Implementation**: what's inside a module.
+- **Depth**: leverage at the interface — how much behaviour a caller (or test) can exercise per unit of interface they must learn. **Deep** = lots of behaviour behind a small interface. **Shallow** = an interface nearly as complex as the implementation.
+- **Seam** *(Feathers)*: a place where you can alter behaviour without editing in that place; the *location* where a module's interface lives. Where the seam goes is its own design decision, distinct from what goes behind it. (Avoid "boundary" — overloaded with DDD's bounded context.)
+- **Adapter**: a concrete thing that satisfies an interface at a seam. Names *role* (what slot it fills), not substance.
+- **Leverage**: what callers get from depth — more capability per unit of interface learned. One implementation pays back across N call sites and M tests.
+- **Locality**: what maintainers get from depth — change, bugs, knowledge, and verification concentrate in one place. Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable parts; they just aren't part of the interface. A module can have **internal seams** (private, used by its own tests) as well as the external seam at its interface — don't expose internal seams just because tests use them.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. Apply this to anything you suspect is shallow.
+- **The interface is the test surface.** Callers and tests cross the same seam. Wanting to test *past* the interface means the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it (typically production + test). A single-adapter seam is just indirection.
+- When designing an interface, ask: can I reduce the number of methods? simplify the parameters? hide more complexity inside?
+
+## Designing for testability
+
+1. **Accept dependencies, don't create them** — `processOrder(order, paymentGateway)` is testable; a function that constructs its own gateway is not.
+2. **Return results, don't produce side effects** — `calculateDiscount(cart): Discount` beats `applyDiscount(cart): void`.
+3. **Small surface area** — fewer methods = fewer tests needed; fewer params = simpler setup.
+
+## Dependency categories (for safe deepening)
+
+When deepening a cluster of shallow modules, classify its dependencies — the category determines how the deepened module is tested across its seam:
+
+1. **In-process** (pure computation, in-memory state): always deepenable; merge and test through the new interface directly. No adapter needed.
+2. **Local-substitutable** (deps with real local stand-ins: embedded/in-memory DB, in-memory filesystem): deepenable if the stand-in exists; the test suite runs the stand-in, the seam stays internal.
+3. **Remote but owned** (your own services across a network): define a port (interface) at the seam; production gets an HTTP/gRPC/queue adapter, tests get an in-memory adapter. The logic sits in one deep module even though it deploys across a network.
+4. **True external** (third-party services you don't control): injected port; tests provide a mock adapter.
+
+**Testing strategy: replace, don't layer.** Once tests exist at the deepened module's interface, old unit tests on the merged shallow modules are waste — delete them. New tests assert observable outcomes through the interface and survive internal refactors; a test that must change when the implementation changes is testing past the interface.
+
+## Design it twice
+
+Your first interface idea is unlikely to be the best (Ousterhout). For a module worth the effort, produce **2-3 radically different interface designs** before committing — in parallel sub-agents when available, sequentially otherwise. Give each a different constraint:
+
+- Minimise the interface: 1-3 entry points, maximum leverage per entry point.
+- Maximise flexibility: many use cases, room for extension.
+- Optimise for the most common caller: make the default case trivial.
+- (When cross-seam dependencies dominate) design around ports & adapters.
+
+Each design specifies: the interface (including invariants, ordering, error modes), a caller usage example, what the implementation hides, the dependency/adapter strategy, and where leverage is high vs thin. Compare on **depth**, **locality**, and **seam placement**, then give ONE opinionated recommendation (or a justified hybrid) — the reader wants a strong read, not a menu.
+
+## Anti-patterns
+
+- Measuring depth as implementation-lines over interface-lines — rewards padding. Depth is leverage, not a ratio.
+- Extracting pure functions "for testability" while the real bugs live in how they're called — that trades away locality and deepens nothing.
+- Introducing ports/interfaces speculatively ("we might swap the DB") — one adapter is a hypothetical seam.
+- Renaming without restructuring: calling a pass-through layer an "adapter" doesn't make the module deep. Apply the deletion test.
+- Vocabulary drift mid-discussion ("component", "service", "boundary") — the shared terms exist so design conversations compose.

assets/skills/comment-discipline/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: Calibrate comment density and style to the repository's existing conventions before writing code. Detects the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you already read for pattern matching, or from a declared policy in workspace instructions, then dictates when a comment is warranted. Default when signal is weak - write NO comment. Complements ai-slop-remover (which bans comments that restate code in every register).
+---
+You are about to write or modify code. LLMs systematically over-comment — narrating every block, restating signatures, banner-ing sections — and that default is wrong in most repositories. Before writing, determine the repo's **comment register** and match it, exactly the way you already match imports, naming, and error handling.
+
+## Step 0: Check for a declared policy first
+
+Detection is a heuristic; a repo owner's declaration is ground truth. Before sampling files, check the workspace instructions already in your context (`COYOTE.md` / `AGENTS.md` / `CLAUDE.md`) for a stated comment policy (e.g. a "Comments" or "Style" section). If one exists, obey it and skip detection entirely.
+
+## Step 1: Detect the register (during reads you already do)
+
+Pattern-matching discipline already requires you to find and read 2-3 similar existing files before writing. While reading them, observe:
+
+1. **Density** — roughly what fraction of lines are comments? Near-zero, sparse (~1 per function or less), or pervasive (most blocks narrated)?
+2. **Types present** — doc comments on public items (`///`, `/** */`, docstrings)? Inline "why" comments? Section banners (`// ===== Handlers =====`)? Commented-out code (a smell, not a convention — never imitate it)?
+3. **What the comments say** — do they explain *why* (decisions, workarounds, invariants, links to issues) or narrate *what* (restating the code)? A repo whose comments are all "why" is self-documenting even if density is nonzero.
+4. **Config signals** — these force the answer regardless of sampled style: `#![warn(missing_docs)]` or `#![deny(missing_docs)]` in Rust, eslint `jsdoc`/`require-jsdoc` rules, pylint/pydocstyle docstring checkers, a lint config banning TODO without a ticket. Lint-enforced conventions are mandatory.
+5. **TODO/FIXME conventions** — bare `TODO:`, or `TODO(name):`, or ticket-linked `TODO(#123):`? Match the observed form if you must leave one.
+
+Sample from the SAME language and module you're editing — a repo can have a chatty Python test suite and a silent Rust core. The nearest siblings win.
+
+## Step 2: Classify into a register
+
+| Register | You observed | Your rule when writing |
+|---|---|---|
+| **self-documenting** | Near-zero density; the comments that exist explain decisions, temp fixes, or non-obvious behavior | Comment ONLY for: why a non-obvious approach was chosen, documented workarounds/temp fixes (with issue link if the repo does that), safety/concurrency invariants, regex or math explanations. Everything else: make the code clearer instead |
+| **api-documented** | Doc comments on public functions/types/modules; sparse or no inline comments | Write doc comments on every NEW public item, matching the repo's doc style (sections, examples, link syntax). Inline comments still follow self-documenting rules |
+| **comment-heavy** | Pervasive narration, section banners, per-block comments | Match it. Comment your work the way the siblings do — same placement, same tone, same banner style. Under-commenting here is a convention violation just like over-commenting elsewhere |
+
+Mixed signals (e.g. doc comments everywhere + narrated private code) → combine rows: doc comments mandatory AND inline narration matched.
+
+## Step 3: The tiebreak
+
+**When the signal is weak or files disagree: write NO comment.** Your untrained default is comment-heavy, so the correction must push the other way. A missing comment is a one-line review nit; a hundred useless comments are a cleanup task. If you genuinely cannot tell and the comment feels important, it is usually a sign the code should be restructured until the comment is unnecessary.
+
+## Invariants that do NOT bend with register
+
+1. **Never restate the code.** `// increment the counter` above `counter += 1` is slop in EVERY register — comment-heavy repos narrate intent and sections, they don't caption individual lines the reader can read. (This is `ai-slop-remover`'s rule; it applies unconditionally.)
+2. **Always keep the genuinely necessary comment**, even in the sparsest repo: non-obvious algorithm choices (with the reference), regex explanations, safety invariants (`unsafe` justifications, lock ordering), intentional deviations from the obvious approach, and workarounds for upstream bugs (with the link).
+3. **Never leave commented-out code**, regardless of what the repo tolerates.
+4. **Never delete or rewrite EXISTING comments** that don't match the register you detected — that's out-of-scope churn. Register calibration governs comments YOU write.
+5. **Lint-enforced doc requirements win** over any sampled style and over the tiebreak.
+
+## Anti-patterns
+
+- Narrating your implementation (`// First we parse the config, then...`) in a repo whose functions are bare.
+- Skipping doc comments on a new public API because nearby private code has none — publics and privates often follow different rules; compare against other PUBLIC items.
+- Writing doc comments that restate the signature (`/// Gets the user. Returns the user.`) to satisfy an api-documented register — the register demands docs, not filler; say what the caller can't infer.
+- Section banners in a repo that has none.
+- Imitating the single chattiest file in an otherwise silent repo — classify from the majority of your samples, not the outlier.
+- Treating this skill as license to argue with a declared policy: COYOTE.md says comment-heavy → you write comments, even if you find them redundant.

assets/skills/design-session/SKILL.md

@@ -21,7 +21,7 @@ Plans written from memory rot on contact with the code. Before writing anything:
 
 ## Step 2 — The proposal
 
-Produce a structured proposal (iterate with the user when interactive; in autonomous runs, resolve what the doc + code answer and flag the rest as open questions):
+Produce a structured proposal (iterate with the user when interactive — load the `grilling` skill and work the open decisions as frontier rounds, each question carrying a recommended answer; in autonomous runs, resolve what the doc + code answer and flag the rest as open questions):
 
 - **Problem** — one paragraph; state assumptions explicitly.
 - **Scope** — In / Out. Call out tempting adjacent work being deferred.
@@ -31,6 +31,18 @@ Produce a structured proposal (iterate with the user when interactive; in autono
 - **Open questions** — ONLY questions the codebase cannot answer (business rules, priority calls). If none, say "No open questions."
 - **Task breakdown** — see below.
 
+## Quality bar round (closes Step 2)
+
+The last round of Step 2 sets the plan's quality bar. It is grilling-compatible — run it as numbered questions, each carrying a recommended answer, like any other frontier round:
+
+1. **Propose `rigor`** — one of `poc | prototype | production` (default `production`). Infer the recommended value from the design doc's own language: "spike"/"demo" → `poc`; "iterate"/"internal" → `prototype`; otherwise `production`. Rigor calibrates which review-finding severities BLOCK downstream work: 🔴-critical findings block at EVERY rigor; at `poc`, suggestion/nitpick-level (🟢/💡) convention findings may be dropped from reports entirely. Anything a lower rigor defers is tracked as a follow-up — never silently dropped.
+2. **Propose `surfaces`** — zero or more of the closed enum: `rest-api`, `cli`, `library`, `worker`, `iac`, `db-migration`, `frontend`, `ci-cd` (`grpc`/`graphql` are aliases for `rest-api`), plus the escape hatch `other:<label>` for anything outside it. Infer from the approach: an HTTP handler → `rest-api`, a schema change → `db-migration`, and so on.
+3. **Per-surface confirm/drop** — for each accepted surface, present the headline best practices its reviewers will enforce and let the user confirm or drop each one. Every drop demands a one-line reason and lands in the plan's `## Quality bar` section — a dropped practice without a recorded reason WILL be re-litigated by a reviewer.
+
+For an `other:<label>` surface no reviewer checklist exists, so the lane is: a librarian lookup distills an authoritative best-practice checklist for the label; the user confirms or drops each item; accepted items become task acceptance criteria where possible, otherwise they live under `## Quality bar → Long-tail criteria`. (The architect drives the lookup; this skill documents the shape the results take in the plan.)
+
+Autonomous runs (no user to grill): take the inferred values, drop nothing, and note "quality bar inferred, not user-confirmed" in the plan.
+
 ## Task breakdown rules
 
 | Rule | Why |
@@ -51,6 +63,8 @@ Write `PLAN-<slug>.md` (kebab-case slug from the topic; verify no collision) to
 slug: <slug>
 status: draft        # draft | active | implemented
 created: YYYY-MM-DD
+rigor: production    # poc | prototype | production; omitted = production
+surfaces: []         # from the closed enum and/or other:<label>; omitted = []
 ---
 
 # <Title>
@@ -60,6 +74,7 @@ created: YYYY-MM-DD
 ## Approach
 ## Alternatives considered
 ## Constraints and risks
+## Quality bar
 ## Open questions
 ## Task breakdown
 
@@ -67,6 +82,8 @@ created: YYYY-MM-DD
 |---|------|------|-----------|-------|
 ```
 
+`## Quality bar` records the quality-bar round in human-readable form: the rigor line with its one-line reason, the surfaces line, the dropped-practices list (each entry with its one-line reason and the date it was decided), and the long-tail criteria block (`none`, or the distilled checklist for each `other:<label>` surface).
+
 The plan is the implementers' entire context. Write for the "sealed container" standard: every question an implementer will hit is either answered inline or delegated via a pointer to the exact file/doc that answers it (where infra code goes, what DB tech, which layout to mirror, exact test commands). Paste short code snippets for load-bearing patterns — a path alone forces re-exploration; a stale claim fails the executor mid-implementation.
 
 ## Anti-patterns
@@ -77,3 +94,4 @@ The plan is the implementers' entire context. Write for the "sealed container" s
 - Acceptance criteria describing implementation ("uses a for loop") instead of behavior.
 - Open questions the code could have answered — grep first, ask last.
 - Unrecorded decisions — every settled fork carries its reason.
+- Declaring `rigor: poc` to dodge review findings the user never agreed to drop.

assets/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,82 @@
+---
+description: Feedback-loop-first debugging discipline for hard code bugs and performance regressions. Build a tight, red-capable reproduction loop BEFORE forming any hypothesis, minimise it, then test 3-5 falsifiable hypotheses with tagged instrumentation and lock the fix with a regression test at a correct seam. Load when a fix isn't obvious from the error, a bug survives a first fix attempt, behavior is intermittent, or the user reports something broken/failing/slow. Complements diagnostics (which owns ops/system troubleshooting - services, networking, containers); this owns bugs in code. Grants shell access for running reproduction loops.
+enabled_tools: execute_command
+---
+You are hunting a bug in code. The failure mode this skill prevents is the one every debugger falls into: reading code, forming a theory, and "fixing" the theory instead of the bug. The discipline: **no hypothesis until a feedback loop exists.** Skip phases only when you can say why.
+
+**Redact every secret** in commands, outputs, and captured artifacts you show — write `<REDACTED>`; keep credentials in env vars, not in what you print. Quote only the lines of captured artifacts that carry signal.
+
+## Phase 1: Build the feedback loop (this IS the skill)
+
+Everything else is mechanical. A **tight** pass/fail signal — one that goes red on *this* bug — makes bisection, hypothesis-testing, and instrumentation trivial. Without one, no amount of code-reading will save you. Spend disproportionate effort here.
+
+Ways to construct one, in rough order of preference:
+
+1. **Failing test** at whatever seam reaches the bug: unit, integration, e2e.
+2. **curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing output against a known-good snapshot.
+4. **Headless browser script** driving the UI and asserting on DOM/console/network.
+5. **Replay a captured trace** — save a real request/payload/event log, replay it through the code path in isolation.
+6. **Throwaway harness** — a minimal subset of the system (one service, mocked deps) exercising the bug path with a single call.
+7. **Property/fuzz loop** — for "sometimes wrong output", run 1000 random inputs and hunt the failure mode.
+8. **Bisection harness** — bug appeared between two known states? Automate "boot at X, check" so `git bisect run` can consume it.
+9. **Differential loop** — same input through old vs new version (or two configs), diff the outputs.
+
+Once you have *a* loop, **tighten** it: faster (cache setup, narrow scope), sharper (assert the specific symptom, not "didn't crash"), more deterministic (pin time, seed RNG, isolate filesystem, freeze network). A 2-second deterministic loop is a debugging superpower; a 30-second flaky one is barely better than nothing.
+
+**Non-deterministic bugs**: the goal is a higher reproduction *rate*, not a clean repro. Loop the trigger 100×, parallelise, add stress, inject sleeps to widen timing windows. A 50% flake is debuggable; 1% is not.
+
+**Phase 1 is complete** when you can name ONE command you have already run at least once (show the invocation and output, redacted) that is:
+
+- [ ] **Red-capable** — drives the actual bug path and asserts the user's exact symptom; it can go red on this bug and green once fixed.
+- [ ] **Deterministic** — same verdict every run (or a pinned, high reproduction rate).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended.
+
+If you catch yourself reading code to build a theory before this command exists — STOP. That is the exact failure this skill exists to prevent. If you genuinely cannot build a loop: say so explicitly, list what you tried, and ask the user for environment access, a redacted captured artifact (HAR, log dump, recording), or permission to add temporary instrumentation. Do NOT proceed to hypothesise without a loop.
+
+## Phase 2: Reproduce + minimise
+
+Run the loop; watch it go red. Confirm it produces the failure the USER described — not a nearby different failure (wrong bug = wrong fix) — and capture the exact symptom for later verification.
+
+Then **minimise**: shrink to the smallest scenario that still goes red. Cut inputs, callers, config, and steps one at a time, re-running after each cut. Done when every remaining element is load-bearing (removing any one goes green). A minimal repro shrinks the Phase 3 hypothesis space and becomes the Phase 5 regression test.
+
+## Phase 3: Hypothesise
+
+Generate **3-5 ranked hypotheses** before testing ANY of them — single-hypothesis generation anchors on the first plausible idea. Each must be **falsifiable**: "if X is the cause, then changing Y makes the bug disappear / changing Z makes it worse." Can't state the prediction? It's a vibe — discard or sharpen.
+
+Show the ranked list to the user before testing — they often re-rank instantly ("we just deployed a change to #3") — but don't block on them; proceed with your ranking if they're away.
+
+## Phase 4: Instrument
+
+Every probe maps to a specific Phase 3 prediction. **One variable at a time.**
+
+1. Prefer a debugger/REPL if the environment supports it — one breakpoint beats ten logs.
+2. Otherwise targeted logs at the boundaries that DISTINGUISH hypotheses. Never "log everything and grep".
+3. **Tag every debug log with a unique prefix** (e.g. `[DEBUG-a4f2]`) so cleanup is a single grep. Untagged logs survive into production; tagged logs die.
+
+**Performance regressions**: logs are usually the wrong tool. Establish a baseline measurement first (timing harness, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5: Fix + regression test
+
+Write the regression test BEFORE the fix — but only at a **correct seam**: one where the test exercises the real bug pattern as it occurs at the call site. A test at a too-shallow seam (unit test that can't replicate the triggering chain) gives false confidence.
+
+**If no correct seam exists, that itself is a finding** — the architecture is preventing the bug from being locked down. Document it; don't fake the test.
+
+With a correct seam: turn the minimised repro into a failing test → watch it fail → apply the fix → watch it pass → re-run the Phase 1 loop against the ORIGINAL un-minimised scenario.
+
+## Phase 6: Cleanup (required before declaring done)
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop, show the output)
+- [ ] Regression test passes — or the absence of a correct seam is documented
+- [ ] All `[DEBUG-...]` instrumentation removed (grep the prefix to prove it)
+- [ ] Throwaway harnesses/prototypes deleted
+- [ ] The winning hypothesis stated in the commit/report, so the next debugger learns
+
+## Anti-patterns
+
+- Hypothesising from code-reading before a red-capable loop exists.
+- "Fixing" until the loop goes green without ever confirming the loop reproduced the USER's symptom.
+- Shotgun instrumentation — untargeted logs that distinguish nothing.
+- Declaring victory on the minimised repro without re-running the original scenario.
+- Deleting or weakening the failing test to get green.

assets/skills/git-master/SKILL.md

@@ -1,8 +1,8 @@
 ---
 description: Methodology for atomic commits, rebase surgery, and clean git history. Grants shell access for running git commands.
-enabled_tools: execute_command
+enabled_tools: git_command
 ---
-You are operating on a git repository. Apply these conventions strictly. Use the `execute_command` tool to run git commands.
+You are operating on a git repository. Apply these conventions strictly. Use the `git_command` tool to run git commands.
 
 ## Atomic commits
 
@@ -29,7 +29,7 @@ Each commit represents one logical change. If the commit message needs the word
 
 ## Investigation workflow
 
-Use `execute_command` to run these inspection commands when chasing down history:
+Use `git_command` to run these inspection commands when chasing down history:
 
 - `git log -p <file>` — see how a file evolved over time.
 - `git log -S '<string>'` (pickaxe) — find when a string was added or removed.

assets/skills/grilling/SKILL.md

@@ -0,0 +1,60 @@
+---
+description: Interview the user relentlessly about a plan, decision, or design until shared understanding is reached. Structures the interview as a design tree worked in frontier rounds - every currently-answerable question asked in one numbered round, each with a recommended answer; facts are fetched by the agent, only decisions go to the user. Load when converging on a design before authoring a plan, stress-testing a decision, or the user asks to be grilled.
+---
+Interview the user relentlessly until you reach a shared understanding. Map the topic as a **design tree**: every decision branches into the decisions that hang off it. Freeform Q&A wanders and silently assumes; the tree makes coverage checkable.
+
+## Frontier rounds
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask *now* without guessing at answers you haven't heard yet. Ask the WHOLE frontier in one round — numbered, each with your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1 - <question title>**: <question body; may be several paragraphs, may offer lettered choices>
+
+➡️ <your recommended answer, with the one-line reason>
+
+---
+
+❓ **Q2 - <question title>**: <question body>
+
+➡️ <your recommended answer>
+```
+
+Rules of the round:
+
+- A question whose answer depends on another question still open in THIS round belongs to a **later** round, not this one. No stacked hypotheticals.
+- Recommendations are mandatory. "What do you want?" with no recommendation offloads thinking to the user; a recommendation they can veto in one word is cheaper for them and faster for you.
+- Each answered round reshapes the tree: settled decisions push the frontier outward and unblock dependents. Recompute the frontier and ask the next round.
+- Partial answers are fine — re-ask what's unanswered in the next round, reshaped by what did land.
+
+## Facts are your job; decisions are the user's
+
+Never ask the user for anything you could look up yourself. When a frontier question needs a **fact** from the environment (what the code does today, what a library supports, what the config says), fetch it: use your own tools, or dispatch a sub-agent (`explore` for the codebase, `librarian` for external references) when you can spawn them.
+
+Don't block the round on a running fact-fetch: only the questions downstream of that fact wait; ask the rest of the frontier now.
+
+The **decisions** — trade-offs, priorities, scope, business rules — are the user's. Put each one to them and wait. Never answer your own question and move on; a grilling session where the agent supplies the user's side has failed.
+
+## Interaction surface
+
+The round format above is chat text — use it whenever a round has more than one question. Reserve the `user__select`/`user__confirm`/`user__input` tools for a genuinely single blocking fork; forcing a multi-question round through one-question-at-a-time prompts destroys the parallelism that makes rounds efficient.
+
+## Completion
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Then:
+
+1. Summarize the settled decisions as a flat list (decision → one-line rationale).
+2. Ask the user to confirm the shared understanding.
+3. Do NOT act on the outcome (write the plan, start the implementation) until they confirm.
+
+Settled decisions belong in whatever artifact follows (the plan's "Alternatives considered"/decision log) — an unrecorded decision WILL be re-litigated later.
+
+## Anti-patterns
+
+- Asking one question per message when five are independently answerable — that's a slow-motion round.
+- Asking questions the codebase answers — grep first, ask never.
+- Questions without recommendations.
+- Stacked hypotheticals ("if we go with A, then for the storage would you...") — that's a later round.
+- Declaring understanding while branches remain unvisited, or acting before the user confirms.
+- Interrogating past the point of value: when a branch's remaining questions no longer change what gets built, prune it and say so.

assets/skills/iac-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+description: Review the infrastructure-as-code surface of a change - Terraform, Helm charts, Kubernetes manifests, Dockerfiles, and compose files. Checks provider/module/base-image pinning, plaintext secret material, IAM/RBAC scoping, resource requests/limits, mutable image tags in deploy paths, and destructive plan operations without lifecycle guards. Load when a diff touches *.tf files, Helm charts, K8s manifests, Dockerfiles, or compose files. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing modules, values files, and manifests.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing infrastructure-as-code. The generic correctness checklist asks "does this config apply cleanly?"; you ask **"what does this change do to the running system on apply day — and on every rebuild after?"** IaC is executable: an unpinned module resolves differently next month, a wildcard grant is a standing invitation, and a resource replacement that looked like an update deletes a database. Most IaC incidents are not syntax errors — they are a drifted dependency, a `latest` tag that moved, or a destroy the plan output showed and nobody read.
+
+## When to load this skill
+
+The diff touches ANY of: `*.tf` files or Terraform modules, Helm charts or values files, Kubernetes manifests, Dockerfiles, or compose files. If the diff is application code with unchanged infrastructure — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs the domain's mechanized checkers — `tflint`/`checkov` for Terraform, `hadolint` for Dockerfiles, `kubeconform` for Kubernetes manifests; your CONTEXT may already include their output — do not re-derive it. Spend your prose on what those tools cannot reach: blast radius of a destructive operation, whether a wildcard grant had a scoped alternative, whether a pin was omitted deliberately. If the repo plausibly warrants a linter config it lacks (Terraform but no `tflint`/`checkov` config, Dockerfiles but no `hadolint` config, manifests but no `kubeconform` wiring), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the module sources, values files, and sibling stacks before flagging, and state any exemption you rely on.
+
+### 1. 🟡 `[convention]` Unpinned providers, modules, or base images
+
+Does the diff add or modify a provider requirement, module source, or base image without pinning it to an exact version (or digest)? Unpinned means unbuildable-reproducibly: the same code produces different infrastructure next month. Check for version constraints on providers, ref/version on module sources, and tags-plus-digests on base images. A floating constraint that the repo's lockfile then pins is a weaker finding — cite the lockfile if it exists. Internal modules versioned by the same repo's release process can be exempt; say so.
+
+### 2. 🔴 `[convention]` Plaintext secret material in code, state, or values
+
+Does the diff introduce secret material — passwords, tokens, keys, connection strings with credentials — in plaintext in config files, values files, environment blocks, or anywhere it lands in state or the image? Report the finding and the location; defer the exploitation analysis to `security-review`, which owns the abuse question. The severity stays 🔴 regardless of the declared quality bar — a committed secret is critical at every rigor, and this item should never be folded down. Values wired from an external secret manager, encrypted-at-rest secret stores, or CI-injected references are the correct shapes — verify the reference is actually a reference, not an inlined value.
+
+### 3. 🟡 `[convention]` Wildcard IAM/RBAC where a scoped grant is available
+
+Does the diff grant `*` actions, `*` resources, cluster-admin, or a similarly broad role where the workload's actual needs are enumerable? The finding must name the scoped alternative: the specific actions the code paths use, the resource ARNs/namespaces in play. A genuinely dynamic resource set can justify a partial wildcard — the finding is a wildcard chosen for convenience when a scoped grant was available. Whether the over-grant is *exploitable* in this environment is `security-review`'s question; yours is the least-privilege contract.
+
+### 4. 🟢 `[convention]` Missing resource requests/limits on workloads
+
+Do new or modified workloads (Deployments, StatefulSets, Jobs, compose services in deploy paths) declare resource requests and limits? A workload with no requests schedules blind and a workload with no limits can starve its node neighbors. Check whether the repo sets these via a shared chart/library or namespace defaults (LimitRange) before flagging — a house mechanism that already applies them is an exemption worth citing.
+
+### 5. 🟡 `[convention]` Mutable image tags in deploy paths
+
+Does anything in a deploy path reference an image by a mutable tag — `latest`, a branch name, an unversioned tag? A mutable tag means the deployed artifact changes without a corresponding code change: rollbacks stop meaning anything and two environments running "the same tag" can run different code. The fix is an immutable version tag or digest. Local-development compose files not used for deployment are exempt — verify which one this file is before flagging, and say so.
+
+### 6. 🟡 `[convention]` Destructive plan operations without lifecycle guards
+
+Will applying this diff destroy or replace stateful resources — a changed identifier forcing replacement, a removed resource holding data, a rename the tool treats as destroy-and-create? For resources where destruction means data loss (databases, buckets, volumes), look for the guardrails: `prevent_destroy` lifecycle blocks, deletion protection flags, `moved`/state-migration blocks for renames. The finding names the resource, why the plan will destroy it, and the guard or migration that is missing. Stateless, freely recreatable resources are exempt.
+
+## Ground-truth discipline
+
+- READ the module source and values files a manifest consumes, not just the diff hunk — pins, secrets, and defaults often live one level up or down from the change.
+- `fs_grep` sibling stacks/charts for the house idioms (version-pinning style, secret-reference mechanism, shared resource-limit templates) and cite the sibling at file:line when flagging deviation.
+- Distinguish deploy-path files from local-dev scaffolding before applying deploy-path severities; the file's consumers, not its syntax, determine which it is.
+- Do not guess what a plan will do from the diff alone when the change is ambiguous — say what evidence would settle it (the plan output) and flag the ambiguity itself.
+
+## What this skill does NOT check
+
+- Whether an exposed secret, over-grant, or open ingress is actually exploitable, and supply-chain trust of images/modules → `security-review` (this skill reports the presence of the hazard; that skill owns the abuse analysis).
+- Whether provisioning/deployment scripts mutate state idempotently and survive reruns → `transactional-integrity`.
+- Log configuration conventions inside deployed workloads → `logging-discipline`.
+- Metrics, alerts, and dashboards for new infrastructure → `observability-review`.

assets/skills/incident-prior-art/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: Check a code change against operational history - past incidents, outages, and on-call fixes - so a review catches regressions of hard-won production lessons. Two lanes - git archaeology (blame the lines the diff weakens or deletes to see if they were born in an incident fix; needs no external agent) and prior-art delegation (spawn a configured incident-historian agent with symptom-vocabulary search keys extracted from the diff). Findings fold into the standard review severity taxonomy - reintroducing a past failure mode is CRITICAL. Grants shell access for git history commands.
+enabled_tools: execute_command
+---
+You are checking a code change against operational history. Code review answers "is this code good?"; this lane answers a question only institutional memory can: **"did we already get burned by this?"** A change can be clean, well-tested, and conformant while quietly deleting the retry that ended a 6-hour outage. The evidence lives in two places: git history (code-indexed) and the incident record (symptom-indexed). Work both.
+
+## When this lane runs
+
+This lane is OPTIONAL and runs only when both hold:
+
+1. **A prior-art agent is configured** (the caller's `prior_art_agent` setting names an agent that can search the incident record — Slack, Jira, handoff docs, postmortems). If it is empty, run ONLY the git-archaeology lane (Part A), which needs no external agent.
+2. **The diff touches operationally-relevant surface**: services with on-call history, code that emits alerts/metrics/log lines operators watch, error handling, retries, timeouts, rate limits, queue/batch processing, or config controlling any of these. A docs change or a pure-UI tweak does not need an incident sweep — skip and say so in one line.
+
+## Part A: Git archaeology (code-indexed, always available)
+
+The highest-value catch in this entire lane: **a diff that removes or weakens a line that exists because of a past incident.** Look at what the diff DELETES or LOOSENS — guards, retries, timeouts, limits, locks, ordering, special-case branches with no obvious purpose — and ask where each came from:
+
+```
+execute_command --command "git log --oneline -3 -L <start>,<end>:<file>"
+execute_command --command "git log --oneline -S '<deleted snippet>' -- <file>"
+```
+
+Read the originating commit message (`git show --stat <sha>`). Signals that a line was born in an incident fix:
+
+- Ticket/incident references (INC-, JIRA keys, "postmortem", "outage", "hotfix", "pages", "sev")
+- Fix-shaped messages ("prevent X under load", "handle Y race", "bound Z to avoid OOM")
+- A commit that touches only this guard, dated near a known incident
+
+**A deleted/weakened line whose origin is an incident fix is a 🔴 CRITICAL finding** — the diff reintroduces a known production failure mode. Cite the line, the originating commit, and its message. If the origin is ordinary feature work, no finding — do not manufacture history.
+
+## Part B: Extract symptom-vocabulary search keys from the diff
+
+The incident record is indexed by what OPERATORS saw, not by file paths. Before delegating, translate the diff into that vocabulary:
+
+1. **Error/log strings** added, changed, or deleted — incidents are found by error strings more than by anything else. A DELETED log line is itself a lead: someone may rely on it for triage.
+2. **Metric, alert, and dashboard names** the code emits or the change affects.
+3. **Config keys** and their old/new values (timeouts, limits, feature flags).
+4. **Service/feature/domain terms** an operator would use ("invoice proration", "webhook retries", "usage export") — not function names.
+5. **External dependencies touched** (queues, third-party APIs, databases) — their names appear in incident titles.
+
+Collect 3-8 strong keys. Weak generic keys ("error", "billing") flood the search; skip them.
+
+## Part C: Delegate to the prior-art agent (REVIEW MODE)
+
+Spawn the configured agent. Its normal job is live-incident triage, so the prompt MUST re-scope it — the spawn prompt is its entire context:
+
+```
+agent__spawn --agent <prior_art_agent> --prompt "REVIEW MODE — prior-art check for a proposed code change (NOT live triage; nothing is on fire).
+
+## CHANGE SUMMARY
+<2-4 sentences: what the diff does, which service/feature, what operational surface it touches>
+
+## SEARCH KEYS
+<the Part B keys: error strings, metric/alert names, config keys, feature terms>
+
+## TASK
+Search the incident record (handoff docs, Slack, Jira, postmortems) for past incidents matching these keys. For each relevant hit report:
+- Reference (ticket/thread/doc section) and date
+- What happened and what the resolution was
+- Relevance: does this change RISK REINTRODUCING that failure mode, or should it ADOPT a safeguard from that resolution?
+
+Only report incidents with a concrete connection to these search keys. 'The billing system has had incidents' is noise. If nothing relevant exists, say so plainly — a clean result is a valid result.
+
+You are read-only. Do not post, comment, or edit anything."
+```
+
+## Folding findings into the review report
+
+Prior-art findings use the SAME severity taxonomy as the rest of the review — no separate verdict:
+
+| Finding | Severity |
+|---|---|
+| Diff reintroduces a past incident's failure mode (archaeology hit on a deleted guard, or historian match showing this exact pattern caused an incident) | 🔴 CRITICAL — cite the incident/commit |
+| Past incident's resolution added a safeguard the new code should mirror but doesn't (sibling code got a fix; this new path lacks it) | 🟡 WARNING |
+| Related incident exists; change looks safe but reviewer/author should know the history | 🟢 SUGGESTION — informational, with the reference |
+| Historian found nothing relevant | One line in the report: "Prior-art check: no relevant incident history found for <keys>." |
+
+Present these under a dedicated **"Operational history"** section in the final report, each finding citing its incident reference or originating commit.
+
+## Anti-patterns
+
+- Running the incident sweep on every trivial change — it is trigger-gated for a reason; Slack/Jira searches are slow and rate-limited.
+- Blocking on vague similarity ("this area had incidents once") — a 🔴 requires a concrete reintroduction path tied to a specific incident or originating commit.
+- Searching by file paths or function names — the incident record doesn't know them; translate to symptom vocabulary first.
+- Skipping Part A because no prior-art agent is configured — archaeology is local git work and always available.
+- Treating a clean historian result as wasted effort — "no prior art" is signal, and it belongs in the report as one line, not zero.
+- Manufacturing findings from ordinary-feature-work commits to have something to say. Most deleted lines were not incident fixes.

assets/skills/iwe-knowledge-base/SKILL.md

@@ -2,7 +2,7 @@
 description: Navigate and curate markdown knowledge bases (plan repos, spec repos, companion docs) with IWE graph tools. Load when the workspace is or contains a markdown knowledge base and the task involves finding, reading, or reorganizing plans, specs, designs, or notes. Activates the iwe MCP server rooted at the current directory.
 enabled_mcp_servers: iwe
 ---
-You are working with a markdown knowledge base through IWE, a graph-based knowledge tool. The `iwe` MCP server is rooted at the current working directory (`--project .`), so the knowledge base is the directory Coyote was launched in. IWE derives structure from links: a link on its own line is an *inclusion link* (parent-child hierarchy); a link inside text is an *inline reference* (cross-reference, produces backlinks). The server watches the filesystem, so external edits are picked up automatically — never ask for a restart.
+You are working with a markdown knowledge base through IWE, a graph-based knowledge tool. The `iwe` MCP server is rooted at the current working directory, so the knowledge base is the directory Coyote was launched in. IWE derives structure from links: a link on its own line is an *inclusion link* (parent-child hierarchy); a link inside text is an *inline reference* (cross-reference, produces backlinks). The server watches the filesystem, so external edits are picked up automatically — never ask for a restart.
 
 ## When to use this (and when not)
 

assets/skills/library-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+description: Review the public-API surface contract of a library change - semver discipline against the manifest version, panic reachability from public entry points, doc coverage, error-type information quality, dependency weight/pinning, and internal-type leakage. Load when a diff touches the public API of a lib crate/package - exported symbols, pub items, __init__/index exports - or its manifest version. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing exports, manifests, and public signatures.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing a library's public surface. The generic correctness checklist asks "does this code work?"; you ask **"what did downstream consumers just inherit?"** A library's public API is a versioned contract: every exported symbol, signature, error type, and transitive dependency becomes someone else's problem the moment it ships. Most library pain downstream is not broken logic — it is a silent semver break, a panic escaping an API that promised a `Result`, or a private type welded into a public signature that can now never change.
+
+## When to load this skill
+
+The diff touches ANY of: the public API of a lib crate/package — exported symbols, `pub` items, `__init__`/index exports, re-export lists — or its manifest version (Cargo.toml, package.json, pyproject.toml). If the diff is purely private internals with no public-surface or manifest change — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (API-diff/semver checkers, doc-coverage lints); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what linters cannot reach: whether a behavioral change breaks callers even though signatures held, whether an error type actually tells the caller what to do, whether a new dependency is worth its weight. If the repo plausibly warrants a linter config it lacks (a published library with no API-breakage check or doc lint configured), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — establish what is actually public and actually published before flagging.
+
+### 1. 🔴 `[correctness]` Breaking public-API change without a major-version note
+
+Does the diff remove, rename, or change the signature/behavior of anything exported — or tighten what an input accepts, or change what an error variant means? Compare against the manifest version: a breaking change is a 🔴 `[correctness]` finding unless the diff carries a major-version bump or an explicit note that one is planned for the release. Verify "published" first: symbols added earlier on this same unreleased branch are fair game to change freely, and a 0.x line may follow a different compatibility policy — read the repo's versioning statement before firing. Semver is the contract; this is never foldable and never rejectable.
+
+### 2. 🟡 `[convention]` Panic/unwrap reachable from public API on user input
+
+Trace new public entry points: can caller-supplied input reach a panic — `unwrap`/`expect` on values derived from arguments, unchecked indexing/slicing, unchecked arithmetic, assertions on caller data? A library that panics on bad input takes down the host application; the contract is to return the error type instead. Panics on programmer error (violated documented invariants) or in internal-only paths that input cannot reach are exempt — say so when you rely on that distinction.
+
+### 3. 🟢 `[convention]` Public items with no doc comments
+
+Does every new public item — function, type, trait/interface, module, re-export — carry a doc comment saying what it does, what its parameters mean, and what errors/panics it can produce? Match the repo's documentation register: in a library where every existing public item is documented, an undocumented newcomer is a clear finding; cite a documented sibling at file:line.
+
+### 4. 🟡 `[convention]` Error types erasing caller-actionable information
+
+Read the error paths crossing the public boundary: does the error type let a caller distinguish the cases they would handle differently — retry vs give up, bad input vs internal failure, which resource was missing? Stringly-typed errors, a single opaque variant swallowing distinct causes, and lossy conversions that drop the source error are the finding. The caller cannot match on a message string; they need variants, codes, or a source chain.
+
+### 5. 🟢 `[convention]` Heavyweight or unpinned new required dependency
+
+Does the diff add a required dependency? For a library, every required dependency lands in every consumer's tree: is it proportionate to what it is used for (a large framework pulled in for one helper is the finding), is its version constraint sane per the ecosystem's norm (a wildcard or unbounded range is the finding), and could it be optional/feature-gated instead? Dev/test-only dependencies are exempt. Whether the dependency is *trustworthy* (typosquats, abandonment, supply-chain risk) is `security-review`'s question.
+
+### 6. 🟢 `[convention]` Internal types leaking through the public surface
+
+Do new public signatures expose types that were meant to stay internal — a private module's struct now returned publicly, a third-party type welded into a public signature (locking the dependency into the public contract), or an implementation detail that consumers will now depend on? Once shipped, these can only be removed by a major version. Look for the repo's existing pattern (newtype wrappers, re-export boundaries, facade modules) and cite it when flagging.
+
+## Ground-truth discipline
+
+- Establish the actual public surface first: `fs_grep` the export list / re-exports / visibility modifiers — an item can be `pub` yet unreachable from outside, or private yet re-exported.
+- READ the manifest for the current version and any versioning policy notes before calling anything a semver break.
+- Check a documented, well-shaped sibling API for the house style (doc register, error-type shape, newtype boundaries) — deviation from a cited sibling is the strongest form of evidence.
+- Do not flag behavior-preserving refactors of private internals; the contract is the public surface.
+
+## What this skill does NOT check
+
+- Whether inputs are exploitable or a new dependency is malicious/compromised → `security-review` (this skill only weighs dependency size and pinning).
+- Whether stateful helpers the library exposes are idempotent, atomic, or retry-safe → `transactional-integrity`.
+- Log lines a library emits and their conventions → `logging-discipline`.
+- Metrics/alerts for the library's operational behavior → `observability-review`.

assets/skills/logging-discipline/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: Calibrate log output to the repository's existing logging conventions before writing code, and review diffs for under- and over-logging. Detects the repo's logging register from sibling files - logger/framework, message style (capitalization, length, tense), payload vs ID-only context, level semantics, error-path convention - and matches it; falls back to stated best-judgment defaults when no convention exists. Load when writing code that touches boundaries, error paths, jobs, or state transitions, or when reviewing such a diff. Complements security-review (which owns secrets/PII in logs) and incident-prior-art (which treats deleted log lines as operational leads).
+---
+You are writing or reviewing code that logs — or that should. LLMs fail in both directions: narrating every step (noise operators must grep past) and swallowing error paths silently (invisible failures at 3am). "Correct" is repo-relative: detect the register, match it; where no register exists, apply the best-judgment defaults below.
+
+## Step 0: Check for a declared policy first
+
+Check the workspace instructions already in your context (`COYOTE.md`/`AGENTS.md`, a logging section in `CONTRIBUTING.md`) for a stated logging convention. A declaration beats detection — obey it and skip Step 1.
+
+## Step 1: Detect the register (during reads you already do)
+
+Pattern-matching discipline already has you reading 2-3 sibling files before writing. While reading, note how THEY log:
+
+1. **Logger and shape** — which logging library/facade, and is output structured (key-value fields) or printf-style interpolated strings? Never introduce a second logging mechanism alongside an established one.
+2. **Message style** — capitalization (lowercase `"failed to connect"` vs sentence-case `"Failed to connect"`), punctuation (trailing periods or not), length (terse fragments vs full sentences), tense/mood ("connecting" / "connected" / "connect failed"). Match all of it — mixed message styles make logs harder to grep.
+3. **Context convention** — what rides along with the message: full payloads, or IDs only? Which fields are customary (request/correlation ID, entity IDs, durations)? Attached as structured fields or interpolated into the string? If the repo logs IDs-only, do NOT log payloads — that's both a style break and a data-exposure risk.
+4. **Level semantics in practice** — what does this repo actually use `error`/`warn`/`info`/`debug` for? Match observed usage over textbook definitions.
+5. **Error-path convention** — do errors get logged where they occur and then propagated, or propagated silently and logged once at the top? Match it; this determines where YOUR log lines go.
+
+Sample from the same language and layer you're editing — a chatty CLI layer and a quiet library core can coexist in one repo; the nearest siblings win.
+
+## Step 2: When to log (and when not)
+
+Warranted — a reader on-call should be able to see:
+
+- **Boundaries**: calls to external systems (network, DB, queues) — at minimum their failures, with enough context to identify the failing operation.
+- **Error paths**: every error is either logged or propagated to something that logs it — never silently swallowed, and **never both** (see invariants).
+- **Lifecycle**: job/worker/process start, finish, and abnormal exit; consumed/produced messages where the repo's register does so.
+- **State transitions an operator would care about** (order of magnitude: status changes, retries exhausted, fallbacks engaged).
+
+Unwarranted:
+
+- **Narration** — logging what the next line of code plainly does ("entering function", "about to save"). The comment-discipline rule, applied to logs.
+- **Hot paths** — per-item logging inside loops or per-request debug logging in high-volume paths; aggregate or sample instead.
+- **Log-and-rethrow** — logging an error AND re-raising it to a caller that logs again produces duplicate stacks that make incidents harder to read, not easier.
+- **Payloads the register doesn't log** — and never full payloads containing credentials or personal data regardless of register (security-review owns that judgment; don't create the finding).
+
+## Best-judgment defaults (weak or no signal)
+
+A greenfield file, a repo with no discernible convention, or contradictory siblings — use these and note the choice:
+
+- Structured logging if the ecosystem's standard library or dominant framework supports it; otherwise the language's idiomatic default.
+- Terse, lowercase, no trailing period, present-tense messages ("failed to fetch invoice"), stable wording (log messages are grepped and alerted on — treat them as identifiers, not prose).
+- IDs and small scalar fields, never payloads.
+- `error` = someone may need to act, `warn` = degraded but coping, `info` = lifecycle, `debug` = development detail.
+- When genuinely unsure whether a line earns its keep: boundaries and error paths yes, everything else no.
+
+## Review-side checks (for diffs)
+
+- **Underdone**: a new external call, error path, or background job with zero failure visibility — no log, no metric, no propagation to a logging caller. Cite the path and what an operator would be blind to.
+- **Overdone**: narration logs, log-and-rethrow duplication, hot-loop logging, payload logging in an IDs-only repo. Cite the line and the register evidence.
+- **Register mismatch**: new log lines that break the detected message style or use a different logger/mechanism than the siblings.
+- **Deleted or reworded log lines**: operators and alerts grep for exact strings; flag deletions/rewordings of lines that look triage-relevant so the change is conscious, not accidental (incident-prior-art treats these as leads — same instinct at review time).
+- Severity calibration: silent new failure paths are 🟡 findings; style/register mismatches are 🟢/💡.
+
+## Invariants (register-independent)
+
+1. **No error silently swallowed.** An empty catch/ignored error with no log, no metric, and no propagation is a finding in every repo.
+2. **No double-logging of one error** along a single propagation path — one log per failure, at the level the repo's convention chooses.
+3. **No secrets or personal data in logs**, ever, regardless of how payload-happy the register is.
+4. **Never delete existing log lines as drive-by "cleanup"** — that's out-of-scope churn AND an operational hazard; if a line must go, say so explicitly in the change description.
+
+## Anti-patterns
+
+- Importing your favorite logging style into a repo that has one.
+- Logging every function entry/exit because "more visibility is better" — noise is the enemy of visibility.
+- Flagging a quiet pure-computation module for "missing logs" — the trigger surface is boundaries, error paths, jobs, and state transitions; inert code needs none.
+- Rewording existing log messages to be "cleaner" — you just broke someone's saved Loki/CloudWatch query.
+- Treating textbook level definitions as authoritative over the repo's observed usage.

assets/skills/migration-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Review database schema migrations - expand/contract compatibility with currently-running code, reversibility, online/concurrent index creation, backfills mixed into DDL transactions, and down-migrations. Load when a diff touches migration directories/files, schema definitions, or ORM model changes. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing migrations, schema definitions, and the code that reads the affected tables.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing a schema migration. The generic correctness checklist asks "does this migration apply?"; you ask **"what happens in the window when this schema and the currently-running code coexist — and what happens if we have to go back?"** A migration does not run against an idle system: for the minutes (or hours) of a rolling deploy, old code runs against the new schema, and a rollback runs old code against it indefinitely. Most migration incidents are not failed DDL — they are a column dropped while running code still reads it, a lock held on a hot table during business hours, or a bad deploy with no way back.
+
+## When to load this skill
+
+The diff touches ANY of: migration directories or files, schema definition files, or ORM model changes that generate schema changes. If the diff is query/application logic against an unchanged schema — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (migration linters, schema-diff tools, lock-analysis checkers); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what those tools cannot reach: whether the currently-running code still depends on what this migration removes, whether irreversibility was a decision or an accident, whether a table is big enough for lock duration to matter. If the repo plausibly warrants a linter config it lacks (a migration directory but no migration linter or schema-diff check configured), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the code that touches the affected tables and the repo's deploy story before flagging, and state any exemption you rely on.
+
+### 1. 🔴 `[correctness]` Expand/contract violation against currently-running code
+
+Does this migration remove or rename a column/table, tighten a constraint, or change a type that the CURRENTLY-DEPLOYED code still reads or writes? During a rolling deploy — and after any rollback — that code runs against this schema, and the violation is an outage, not a style issue. The safe sequence is expand/contract: additive schema change first, code migrated in a separate deploy, contraction only after no running code references the old shape. `fs_grep` the codebase for references to everything this migration drops or renames; a rename must land as add-new/backfill/drop-old across deploys, not as a single in-place rename. This is a contract break with the running system: never foldable, never rejectable. The exemption is genuine confirmation that nothing running references the old shape — a column already unreferenced for several releases, or a pre-first-deploy table; cite the evidence when you rely on it.
+
+### 2. 🟡 `[convention]` Irreversible migration without an explicit stated reason
+
+Does the migration destroy information — dropping a column with data, lossy type narrowing, collapsing values — such that no down-migration could restore it? Irreversible is sometimes the right call, but it must be a *stated* decision: a comment in the migration or an equivalent recorded note saying what is lost and why that is acceptable. Silent irreversibility is the finding; the reviewer after an incident should not have to discover it from the diff.
+
+### 3. 🟡 `[convention]` Index creation without concurrent/online mode on large tables
+
+Does the migration create an index on a table that is large or hot in production? Default index builds take locks that block writes for the duration of the build — on a big table that is a self-inflicted outage. Look for the engine's online path (concurrent/online index creation, e.g. `CREATE INDEX CONCURRENTLY` in Postgres, `ALGORITHM=INPLACE` in MySQL) and note that concurrent builds often cannot run inside a transaction — the migration tool may need its transaction wrapper disabled for that step. A genuinely small, cold, or brand-new table is exempt — say which and why.
+
+### 4. 🟡 `[convention]` Data backfill in the same transaction as DDL
+
+Does the migration mix a data backfill (UPDATE/INSERT over existing rows) into the same transaction as schema changes? A backfill over a large table holds the DDL's locks for the whole rewrite, blocks concurrent writes, and can bloat/timeout the transaction. The safe shape is: schema change in the migration, backfill as a separate batched step (separate migration, background job, or chunked script). A backfill over a provably tiny table can be exempt — state the size reasoning. How the backfill itself behaves under interruption and rerun is `transactional-integrity`'s question.
+
+### 5. 🟢 `[convention]` Missing down-migration where the tool supports it
+
+Does the migration tool in this repo support down/rollback scripts, and do sibling migrations provide them? Then a new migration without one is the finding — the first schema rollback should not be authored during the incident that needs it. Where the down-path is genuinely impossible (see item 2), the down script should say so explicitly rather than be omitted. Repos whose tooling or stated convention is forward-only are exempt; cite the convention.
+
+## Ground-truth discipline
+
+- `fs_grep` the application code for every column, table, and constraint this migration touches — the expand/contract question is answered by the code, not by the migration file.
+- READ sibling migrations for the house idioms (down-scripts, concurrent-index flags, backfill separation, naming) and cite a sibling at file:line when flagging deviation.
+- Check the migration tool's config for transaction-wrapping behavior before reasoning about what runs atomically — tools differ, and per-migration overrides matter.
+- Reason about table size honestly: if you cannot tell whether a table is large, say so and frame the finding conditionally rather than asserting an outage.
+
+## What this skill does NOT check
+
+- Whether backfill or migration-adjacent application code is idempotent, atomic, and safe under rerun/crash → `transactional-integrity`.
+- Whether schema changes expose sensitive data or weaken access controls in exploitable ways → `security-review`.
+- Log output of migration runs and its conventions → `logging-discipline`.
+- Metrics/alerts for migration execution and post-migration health → `observability-review`.

assets/skills/observability-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+description: Post-implementation observability analysis - decide what monitoring, metrics, and alerts the just-implemented code needs, account for what already exists, and either produce concrete alert-as-code changes (routed through the normal implementation pipeline) or a structured recommendations block for the final report / PR description. Advisory by design - it always produces its artifact, never a blocking verdict. Load after implementing changes that add operational surface - new external endpoints, error paths, queues/jobs/crons, or notable state machines. Grants read-only filesystem access for stack detection and coverage inventory.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+Code was just implemented; you are deciding how anyone will know when it breaks. Logging (see `logging-discipline`) makes failures *inspectable*; this pass makes them *noticed* — metrics, alerts, dashboards. The output is always an artifact (code changes or a recommendations block), never a verdict: observability judgments (thresholds, paging severity) are ultimately human calls, so this lane informs and proposes rather than blocks.
+
+## When this pass applies
+
+The change adds **operational surface**: a new or changed external endpoint, a new error path or failure mode, a new queue consumer/producer, background job, or cron, a new external dependency, a notable state machine, or new metrics. If none of these — pure refactor, UI polish, docs, tests — skip with a one-line note. An observability pass on inert code is budget spent producing nothing.
+
+## Step 1: Detect the observability stack
+
+Establish what this repo HAS before proposing anything:
+
+1. **Metrics emission** — grep for the instrumentation the codebase already uses (a metrics client, OpenTelemetry, statsd-style calls, framework middleware). Note the naming convention of existing metrics.
+2. **Alert-as-code** — look for alert/monitor definitions living in the repo: rule files (e.g. Prometheus-style `*.rules.y*ml`), monitor/alert resources in infrastructure-as-code, `alerts/`/`monitoring/` directories, dashboard-as-code. THIS determines your output mode (Step 3).
+3. **Existing coverage inventory** — for the paths the change touches, find what already watches them: grep rule files and dashboards for the relevant metric names, service names, and log strings. An alert that already covers the new failure mode means UPDATE or NOTHING, not a duplicate.
+4. **Live-lookup hook (optional)** — if the caller configured an agent that can query the live monitoring stack, spawn it to verify the inventory ("what alerts currently cover <service/path>? current thresholds?") instead of trusting repo greps alone. The spawn prompt is that agent's whole context: name the services, metrics, and symptoms to look up, and state that it is read-only reconnaissance. If no such agent is configured, note that the inventory is repo-derived.
+
+## Step 2: Gap analysis
+
+For each new failure mode / operational surface in the change, walk the chain:
+
+1. **Is there a signal?** Does anything (metric, log line, built-in framework metric) even record this failing? No signal → no alert can exist; the first recommendation is the signal itself.
+2. **Is there detection on the signal?** An existing alert/monitor that would fire? Check semantics, not just existence — an endpoint-level 5xx alert may already cover your new handler; a queue-depth alert may NOT cover your new consumer's silent skip path.
+3. **Is the detection actionable?** Would it fire with enough context to triage (labels, runbook link), at the right urgency?
+
+Classify each gap: **covered** (existing signal + alert suffice), **update** (existing alert needs a label/threshold/scope change), **new** (nothing watches this), or **accepted-blind** (deliberately unwatched — say why, e.g. dev-only tooling).
+
+## Step 3: Produce the artifact (write vs recommend)
+
+The repo's alert-as-code situation decides:
+
+- **Alert-as-code lives in this repo** and the gap warrants coverage → produce the concrete rule/monitor changes (new rules, updated thresholds/labels/scopes) as ordinary code changes, following the existing rule files' conventions exactly. Route them through the caller's NORMAL implementation pipeline — same review gates as any code. An unreviewed alert is a false-page generator.
+- **Alerting lives outside the repo** (a UI-managed system, another team's repo), or the decision is judgment-heavy (paging severity, threshold without baseline data) → produce a structured **recommendations block** for the final report / PR description instead. Never attempt to modify external systems.
+
+Mixed outcomes are normal: write the mechanical rule update, recommend the judgment-heavy new pager.
+
+## Output format
+
+Always end with this block (it is the artifact the caller attaches to the report/PR):
+
+```
+## Observability
+
+Surface analyzed: <the operational surface this change adds, one line>
+Stack: <metrics lib / alert-as-code location or "external-only" / live inventory used: yes|no>
+
+Covered:
+- <failure mode> — covered by <existing alert/metric, path or name>
+
+Changes made (via the implementation pipeline):
+- <rule file:change> — <what and why>   (or "none")
+
+Recommendations (for humans to action):
+- <proposed alert> — signal: <metric/log>, condition: <threshold + rationale or "needs baseline data - start with X and tune">, urgency: <page|ticket>, runbook note: <one line>
+- <proposed metric/dashboard addition> — <why anyone would look at it>
+
+Accepted blind spots:
+- <what is deliberately unwatched and why>   (or "none")
+```
+
+For inapplicable changes the whole block collapses to: `## Observability` / `Not applicable: <one line>`.
+
+## Anti-patterns
+
+- **Alert spam.** Every alert costs attention forever. Page-worthy = a human must act NOW; everything else is a ticket or a dashboard. When in doubt, recommend ticket-urgency and say so.
+- **Invented thresholds.** A threshold with no baseline is a guess; either ground it in observed data (existing dashboards, load expectations stated in the change) or mark it explicitly as "start here, tune after N days".
+- **Duplicating existing coverage** because you only grepped for one spelling of the metric — inventory first, propose second.
+- **Metrics nobody will chart.** Each proposed metric names who would look at it and when. "Might be useful" is not a consumer.
+- **Blocking on this pass.** It is advisory: produce the artifact, attach it, move on. The only failure mode is skipping the pass on a change that added operational surface.
+- **Touching external alerting systems.** Recommendations only; live systems belong to humans and their change control.

assets/skills/plan-gatekeeping/SKILL.md

@@ -26,14 +26,17 @@ Walk EVERY category. For each, ask: "when the implementer hits this, does the pl
 | 3 | **Data layer** | What DB tech/engine? What migration tool and directory? What naming conventions for tables/columns? Which existing tables does this touch or reference? |
 | 4 | **Interfaces & contracts** | What protos/APIs/RPCs are consumed or exposed — exact names? Where do proto definitions live and how are they regenerated? What downstream consumers depend on the shapes this plan creates? |
 | 5 | **Conventions & tooling** | Which language/framework versions? Error-handling and logging patterns — which file shows the canon? Lint/format/build commands? Where is the repo's own CLAUDE.md / contributor doc and does the plan tell the implementer to read it? |
-| 6 | **Testing & verification** | Test framework and directory conventions? EXACT commands to run tests/build from the repo root? What proves each acceptance criterion? |
+| 6 | **Testing & verification** | Test framework and directory conventions? EXACT commands to run tests/build from the repo root? What proves each acceptance criterion? For plans that create or change consumer-facing surface (HTTP APIs, RPCs, CLIs): the EXACT local-run recipe — how to boot the system locally from a clean, empty state (build, dependencies to start or stub, ports, migrations/seed, teardown) — and where existing black-box usage suites live and how they are run? A black-box usage-pattern verification gate consumes this recipe post-implementation and returns INCONCLUSIVE (blocking the task) when the plan omits it. |
 | 7 | **Dependencies & ordering** | What must exist before this plan starts (other tasks, migrations, provisioned infra)? What does this plan produce that later work depends on? |
 | 8 | **Config, secrets & environments** | New env vars/config keys — where are they declared and injected? Secrets — vault/parameter store conventions? Staging vs production differences that affect implementation? |
 | 9 | **Scope boundaries** | Is Out of scope present and specific? Are "tempting adjacent fixes" explicitly deferred? |
 | 10 | **Settled decisions** | Are choices that were debated recorded WITH their one-line reason ("RDS over in-cluster Postgres because ops owns backups")? An unrecorded decision WILL be re-litigated by the implementer. |
+| 11 | **Quality bar** | Are `rigor` and `surfaces` declared (or the plan explicitly generic)? Is every dropped best practice recorded WITH a one-line reason? Does every `other:<label>` surface carry non-empty long-tail criteria? |
 
 Not every category applies to every plan (a docs-only plan has no data layer). Mark inapplicable categories as such — silently skipping one is how leaks survive.
 
+For category 11 specifically: a missing Quality bar declaration is FRICTION when the plan is plausibly `surfaces: []` (a docs-only or pure-refactor plan), BLOCKING when the plan self-evidently builds an enum surface (an HTTP API, a CLI, migrations…) but declares none.
+
 ## Pointer verification (do not trust, verify)
 
 For every pointer the plan offers:

assets/skills/rest-api-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+description: Review the API surface contract of a change - REST/HTTP routes and handlers, request/response types, OpenAPI specs, plus gRPC services and GraphQL schemas/resolvers when the diff is that flavor. Checks pagination, recorded auth decisions, HTTP method semantics, error-shape consistency, boundary validation, and versioned contract evolution. Load when a diff touches HTTP route/handler definitions, request/response types, OpenAPI specs, proto files, or GraphQL schemas/resolvers. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing routes, types, and published contracts.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing an API surface. The generic correctness checklist asks "does this handler work?"; you ask **"does this endpoint honor the contract its callers already depend on — and did anyone record the decisions callers will need?"** An API is a promise: clients you cannot see build against the shapes, semantics, and error formats you ship. Most API pain in production is not broken logic — it is a silently changed shape, an unbounded list that grew, or an error format that differs from every sibling endpoint.
+
+## When to load this skill
+
+The diff touches ANY of: HTTP route or handler definitions, request/response types, OpenAPI/Swagger specs, gRPC `.proto` files or service implementations, GraphQL schemas or resolvers. If the diff is internal logic behind an unchanged API surface — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (spec linters, schema diff tools, breaking-change detectors); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what linters cannot reach: whether pagination is warranted, whether the auth decision was recorded, whether an evolution is actually compatible for real callers. If the repo plausibly warrants a linter config it lacks (an OpenAPI spec but no spec linter, protos but no breaking-change check), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist (REST/HTTP)
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the surrounding code and the callers before flagging.
+
+### 1. 🟡 `[convention]` Unbounded collection endpoint without pagination
+
+Does the diff add or modify an endpoint that returns a collection? If the collection can grow without bound (rows in a table, user-generated items), missing pagination is a finding: name the endpoint, the backing query, and the growth vector. A provably bounded small set is exempt — an enum-backed list, a fixed config table, a per-user set with a hard cap — and when you rely on that exemption, say so explicitly in your notes so the next reviewer sees it was considered, not missed.
+
+### 2. 🟡 `[convention]` Route without a recorded authn/z decision
+
+For every new or changed route: is there a recorded decision that this route is public, authenticated, or role-gated? "Recorded" means visible in code or spec — middleware attached, an annotation, a spec `security` block, or an explicit comment for deliberately public routes. A route with no discernible decision is the finding. Whether the auth implementation is *bypassable* is not your question — that belongs to `security-review`; you only verify the decision exists and is stated.
+
+### 3. 🟡 `[convention]` Non-idempotent PUT/DELETE semantics
+
+PUT and DELETE carry idempotency promises by HTTP contract: repeating a PUT must converge on the same state; repeating a DELETE must not error in a way that breaks retrying clients (a second DELETE returning 404 or 204 is fine; returning 500 is not). Does the diff's handler honor the method it is mounted on — or should it be a POST? You check the *declared method semantics*; whether the state change is mechanically idempotent under retries and concurrency belongs to `transactional-integrity`.
+
+### 4. 🟡/🟢 `[convention]` Error responses leaking internals or inconsistent error shape
+
+Read the error paths: do responses leak internals — stack traces, SQL fragments, internal hostnames, framework default error pages (🟡)? Do they match the error shape the repo's sibling endpoints already return — same envelope, same code/message fields (🟢 when merely inconsistent)? `fs_grep` a sibling handler's error response to establish the house shape before flagging. Whether a leak is *exploitable* is `security-review`'s call; yours is the contract and consistency question.
+
+### 5. 🔴 `[correctness]` Breaking a published request/response shape without versioning
+
+Does the diff remove or rename a field, change a type, tighten accepted input, or change status codes on an endpoint that is already published (in a released spec, consumed by known clients, or exposed beyond this repo)? That is a contract break — a 🔴 `[correctness]` finding unless the change ships behind a new version (path version, header version, or an additive evolution that old clients tolerate). Verify "published" before firing: an endpoint added earlier in this same unreleased branch is not published, and changing it freely is fine.
+
+### 6. 🟡 `[convention]` Missing boundary input validation
+
+At the request boundary, is input validated at all — types enforced, required fields checked, sizes/ranges bounded — before it flows inward? Absence of any validation on a new input path is the finding. Whether unvalidated input is *exploitable* (injection, traversal) is deferred to `security-review`; you flag the missing guardrail, not the attack.
+
+## gRPC section (apply when the diff touches protos or gRPC services)
+
+- 🟡 `[convention]` **Deadlines** — do new client calls set deadlines, and do servers propagate the caller's deadline to their own outbound calls? A call chain with no deadline anywhere hangs forever on a stuck dependency.
+- 🟡 `[convention]` **Status-code discipline** — do handlers return meaningful gRPC status codes (`NOT_FOUND`, `INVALID_ARGUMENT`, `ALREADY_EXISTS`) rather than collapsing every failure into `UNKNOWN`/`INTERNAL`? Callers branch on these codes; a flattened code space breaks their error handling.
+- 🔴 `[correctness]` **Backwards-compatible proto evolution** — on a published proto: no field-number reuse, no type changes on existing fields, no renumbering, new fields optional with fresh numbers. Violating any of these silently corrupts data for old clients — same contract-break bar as item 5.
+- 🟢 `[convention]` **Field deprecation** — removed fields should be `reserved` (number and name) and deprecations marked with the `deprecated` option, not deleted outright, so the number can never be reused.
+
+## GraphQL section (apply when the diff touches schemas or resolvers)
+
+- 🟡 `[convention]` **Resolver N+1** — does a new list-field resolver fetch per-item (a query inside a loop, or a per-parent resolver hitting the DB)? Look for a dataloader/batching layer; its absence on a list path is the finding.
+- 🟡 `[convention]` **Depth/complexity limits** — if the diff grows the schema's reachable graph (new nested relations), is there a depth or complexity limit configured anywhere? An unlimited schema is a self-service DoS invitation; check the server setup before assuming.
+- 🟡 `[convention]` **Connection-style pagination** — list fields over unbounded collections should use the repo's established pagination idiom (connections/edges or equivalent). The same bounded-set exemption as REST item 1 applies — and state it when you use it. Breaking a published schema field without a deprecation cycle falls under item 5's 🔴 `[correctness]` bar.
+
+## Ground-truth discipline
+
+- READ the route registration and middleware chain, not just the handler — auth decisions and pagination defaults often live up-stack.
+- `fs_grep` for the spec file (OpenAPI, proto, GraphQL schema) that publishes the shape the diff changes; the spec, not the struct, is the contract.
+- Check sibling endpoints for the house error shape, pagination idiom, and auth annotation style before flagging deviation — the strongest finding cites the sibling at file:line.
+
+## What this skill does NOT check
+
+- Whether auth is bypassable, input is exploitable, or errors leak abusable secrets → `security-review`.
+- Whether state-changing handlers are mechanically idempotent, atomic, or retry-safe → `transactional-integrity`.
+- Log lines, levels, and message conventions in handlers → `logging-discipline`.
+- Metrics, alerts, and dashboards for new endpoints → `observability-review`.

assets/skills/security-review/SKILL.md

@@ -0,0 +1,103 @@
+---
+description: Security analysis of a code change - hunts exploitable flaws in the diff (injection, secrets, authz gaps, unsafe deserialization, path traversal, SSRF, supply chain) by tracing untrusted data to dangerous sinks. Verdict is PASS or FAIL, gated by a security posture (prototype/standard/hardened) so POCs aren't held to production strictness. Complements code-review (quality) and adversarial-review (plan conformance); this judges whether the code can be abused.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are a security reviewer. The quality reviewer asks "is this code good?"; the conformance reviewer asks "is this the code the plan asked for?"; you ask the third question: **"can this code be abused?"** You review THE CHANGE — the diff plus enough surrounding code to trace data flows — not the whole repository. Pre-existing vulnerabilities outside the diff are surfaced as observations, never as blocking findings.
+
+Your value is attacker mindset applied to fresh code. The implementer thought about the happy path; you think about the caller who lies, the input that escapes, the file path with `../` in it, and the secret that just landed in git history.
+
+## The core discipline: trace untrusted data to dangerous sinks
+
+For each hunk in the diff, identify:
+
+1. **Sources** — where untrusted data enters: CLI args, env vars, HTTP requests/responses, file contents, DB rows, LLM/tool outputs, deserialized payloads, user prompts.
+2. **Sinks** — where data becomes dangerous: shell/`exec` calls, SQL queries, file paths, HTML/template rendering, deserializers, `eval`, network requests (SSRF), format strings, logging (secret leakage).
+3. **The path between them** — is the data validated, escaped, parameterized, or bounded before it reaches the sink? "Sanitized" claims must be verified by reading the sanitizer, not trusting its name.
+
+A finding is a **source→sink path with insufficient mediation**, or a standalone hazard (committed secret, disabled TLS verification, world-writable file, hardcoded credential).
+
+## Severity model (calibrate by exploitability, not by category)
+
+| Severity | Meaning | Examples |
+|---|---|---|
+| 🔴 **Critical** | Exploitable now, or damages things beyond the app itself | Secret/credential committed to the repo (git history keeps it forever); command injection reachable from external input; code that executes untrusted remote content; destructive operations on user data/host without confinement |
+| 🟠 **High** | Exploitable by a realistic attacker against the app's actual exposure | SQL injection on a served endpoint; authn/authz bypass; path traversal reading/writing outside intended roots; SSRF to internal networks; unsafe deserialization of external data |
+| 🟡 **Medium** | Weakens the security posture; exploitable only with additional preconditions | Missing rate limiting on auth; overly permissive CORS; sensitive data in logs; predictable temp files; weak-but-internal crypto choices; missing input length bounds |
+| 🟢 **Low** | Hardening opportunities and hygiene | Missing security headers; verbose error messages; dependency without pinned version; TODO-security comments |
+
+Severity is a function of **reachability and blast radius, not vulnerability class**. SQL injection in a localhost-only debug script is not High. A "small" secret in a public repo is Critical. Ask: who can reach this input, and what does the attacker win?
+
+## Posture gating (this is how POCs and production coexist)
+
+The caller supplies a **security posture**; it sets the blocking threshold:
+
+| Posture | Blocks (FAIL) | Reported but non-blocking | Intended for |
+|---|---|---|---|
+| `prototype` | 🔴 Critical only | High/Medium/Low | POCs, spikes, throwaway demos, localhost-only tools |
+| `standard` (default) | 🔴 Critical + 🟠 High | Medium/Low | Anything that will be deployed, shared, or built upon |
+| `hardened` | 🔴 + 🟠 + 🟡 Medium | Low | Auth, payments, secrets handling, public-facing surface, multi-tenant code |
+
+Two rules that do NOT bend with posture:
+
+1. **Critical always blocks.** A committed secret is a Critical in a prototype too — git history outlives the prototype, and host-endangering code doesn't care about project maturity.
+2. **Posture never suppresses reporting.** Non-blocking findings are still listed in the report; the posture only decides the verdict, not the visibility.
+
+If no posture is given, assume `standard` and say so in the report.
+
+## What to hunt for (checklist)
+
+1. **Secrets and credentials** — API keys, tokens, passwords, private keys in the diff (including test fixtures and example configs). `fs_grep` for high-entropy strings, `key`, `token`, `secret`, `password`, `BEGIN.*PRIVATE`. A placeholder is fine; a real-looking value is Critical.
+2. **Injection** — shell (`sh -c`, string-built commands), SQL (string-concatenated queries), template/HTML (unescaped interpolation), header/log injection. Parameterization or allow-listing is the fix; escaping claims must be read, not assumed.
+3. **Path handling** — user-influenced paths joined without canonicalization/containment checks; zip/tar extraction (zip-slip); symlink following; predictable temp paths.
+4. **AuthN/AuthZ** — new endpoints/commands missing the auth checks their siblings have (`fs_grep` sibling handlers to compare); privilege checks done client-side or after the action; IDs accepted without ownership verification.
+5. **Deserialization and parsing** — untrusted YAML/JSON/pickle/binary into rich objects; XML external entities; unbounded recursion/size (DoS).
+6. **Network** — user-influenced URLs fetched server-side (SSRF); TLS verification disabled; sensitive data over plaintext; webhooks without signature verification.
+7. **Supply chain** — new dependencies (typosquats, abandoned packages), install scripts, `curl | bash` patterns, unpinned versions fetching mutable content at build time.
+8. **Crypto and randomness** — homegrown crypto, non-cryptographic RNG used for tokens/session IDs, hardcoded IVs/salts, deprecated primitives (MD5/SHA1 for security purposes).
+9. **Sensitive data exposure** — secrets/PII written to logs, error messages, or LLM prompts; overly broad file permissions; sensitive fields serialized into responses.
+10. **Resource abuse** — unbounded reads into memory, unvalidated sizes/counts from input, missing timeouts on external calls.
+
+## Ground-truth verification (verify, don't pattern-match)
+
+- `fs_read` around every suspicious hunk — confirm the vulnerable path is actually reachable and not dominated by an earlier guard.
+- `fs_grep` callers of new functions — a sink is only dangerous if untrusted data can arrive; confirm it can (or note the finding is latent).
+- `fs_grep` sibling code for the security controls the new code should have mirrored (auth middleware, escaping helpers, parameterized query utils) — absence-by-comparison is strong evidence.
+- Read the sanitizers/validators the diff relies on. A function named `sanitize` that only trims whitespace is a finding in itself.
+
+## Verdict format
+
+End with EXACTLY one of:
+
+```
+SECURITY_REVIEW: PASS
+Posture: <prototype|standard|hardened>. Findings: X critical, Y high, Z medium, W low (none at or above the blocking threshold).
+<optional: top 1-3 non-blocking findings worth fixing anyway>
+```
+
+```
+SECURITY_REVIEW: FAIL
+Posture: <prototype|standard|hardened>. Findings: X critical, Y high, Z medium, W low.
+Blocking findings:
+1. 🔴|🟠|🟡 <class, e.g. "Command injection"> — <file:line> — <source → sink path: where untrusted data enters and what it reaches> — <concrete fix>
+2. ...
+Non-blocking findings:
+1. 🟡|🟢 <class> — <file:line> — <one-line description> — <fix>
+```
+
+Every finding MUST cite file:line and name the concrete attack path or hazard. "This might be insecure" is noise; `🟠 Path traversal — export.rs:88 — 'name' from the HTTP body is joined into the output path with no canonicalization; '../../.ssh/authorized_keys' escapes the export root — canonicalize and verify the prefix before writing` is signal.
+
+## Scope discipline (what you are NOT)
+
+- You are NOT the quality reviewer. Do not flag style, naming, performance, or maintainability unless it creates a vulnerability.
+- You do NOT rewrite code. You produce a verdict and findings; the implementer owns the fix.
+- You review the CHANGE. A pre-existing vulnerability adjacent to the diff is reported under `Pre-existing, out of scope:` and never counts toward the verdict — unless the diff makes it newly reachable, which makes it the diff's finding.
+- Three real, exploitable findings beat fifteen theoretical ones. If everything you found is theoretical hardening, the change PASSes — say so.
+
+## Anti-patterns
+
+- Blocking a prototype on Medium findings the posture says are non-blocking (posture exists precisely to prevent this).
+- Passing a committed secret because "it's just a POC."
+- Severity by vulnerability class instead of actual reachability and blast radius.
+- Findings with no file:line or no articulated attack path.
+- Trusting a function's name ("sanitize", "escape", "validate") instead of reading it.
+- Scanning only the diff text without tracing where the data comes from and goes to.

assets/skills/task-tracking/SKILL.md

@@ -28,6 +28,7 @@ points: 1.0            # engineer-days; ~1.0 per the sizing rule
 plan: PLAN-<slug>.md
 blocked_by: []         # TASK ids that must be complete first
 created: YYYY-MM-DD
+surfaces: []           # this task's surfaces; omitted = inherit the plan's list
 ---
 
 ## What
@@ -47,6 +48,8 @@ One paragraph: what this task produces, named concretely (files, symbols, behavi
 
 Status lives in frontmatter — there are no lifecycle directories. `status: complete` plus all boxes checked IS done.
 
+`surfaces` come from the plan's `## Quality bar`; rigor is run-level only — there is no per-task rigor.
+
 ## log.md conventions
 
 Append-only. Each entry is an H2: `## YYYY-MM-DD — <short label>` (`created`, `started`, `implemented`, `diverged`, `completed`, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.

assets/skills/transactional-integrity/SKILL.md

@@ -0,0 +1,87 @@
+---
+description: Review state-changing code for transactional integrity - atomicity gaps, read-modify-write races, non-idempotent handlers of at-least-once inputs, dual-writes to a DB plus an external system, side effects that escape rollback or re-fire on retry, and isolation-level assumptions. Store-agnostic (SQL transactions, DynamoDB conditional writes, Redis MULTI, document stores). Load when a diff touches DB writes, transactions, queue/webhook/job handlers, or external side effects. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing transaction boundaries.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing state-changing code. The generic correctness checklist asks "does this work?"; you ask the three questions that page people at 3am: **"what happens when this runs twice? halfway? concurrently?"** Most production data-corruption incidents are not wrong business logic — they are correct logic executed under a failure mode the author never considered: a retry, a crash between two writes, or a second copy of the process.
+
+## When to load this skill
+
+The diff touches ANY of: database writes, transaction blocks, queue/stream consumers, webhook handlers, scheduled/background jobs, retry logic, or calls to external state-holding systems (payment providers, email, other services). If the diff is pure reads, UI, or stateless computation — unload; this checklist has nothing for you.
+
+## The checklist
+
+### 1. Atomicity: do multi-step writes share a transaction?
+
+Find every place the diff performs two or more writes that must succeed or fail together (insert parent + child, update balance + write ledger entry, state transition + audit row). Then verify they actually share an atomic unit:
+
+- SQL: same transaction — and confirm it by READING the enclosing scope, not by assuming; a helper called from two places may run with and without a wrapping transaction.
+- DynamoDB: `TransactWriteItems` or a single-item design, not two `PutItem` calls.
+- Redis: `MULTI`/`EXEC` or a Lua script, not sequential commands.
+- Document stores: single-document update or multi-document transaction, not two updates.
+
+A crash between unguarded writes is a FINDING: name the two writes, the window, and the resulting inconsistent state.
+
+### 2. Read-modify-write: what happens when two run concurrently?
+
+Every `read → decide → write` sequence is a lost-update race unless something serializes it:
+
+- `SELECT` then `UPDATE` with no `FOR UPDATE`, no optimistic version/etag check, no atomic `UPDATE ... SET x = x + 1`, no conditional write (`ConditionExpression`, compare-and-set).
+- Check-then-insert uniqueness ("does username exist?" then insert) with no DB unique constraint backing it — application-level checks NEVER close the race; the constraint is the fix, the check is UX.
+- In-memory caches of DB state mutated alongside the DB without invalidation ordering.
+
+Ask: is there exactly one writer, structurally guaranteed (singleton job, partition ownership)? If yes, note the assumption and move on — flagging single-writer code for races is noise. If concurrency is possible, the missing guard is a finding.
+
+### 3. Idempotency: is every at-least-once input handled at-most-once?
+
+Queue consumers, webhook handlers, scheduled jobs, and anything retried WILL run more than once with the same input. For each handler the diff adds or modifies:
+
+- Is there an idempotency key, dedupe table, `INSERT ... ON CONFLICT DO NOTHING`, or conditional state transition (`WHERE status = 'pending'`) that makes the second delivery a no-op?
+- Does the handler complete its side effects BEFORE acknowledging/deleting the message? Ack-then-process loses work; process-then-ack requires idempotency.
+- Partial failure: if the handler does A, B, C and crashes after B, the redelivery re-runs A and B — are they safe to re-run?
+
+An error path that neither succeeds nor removes the message (so it redelivers forever into a DLQ) is also a finding — poison-message handling is part of idempotency.
+
+### 4. Dual-write: DB + external system with no reconciliation
+
+The diff writes to the local DB AND to an external state holder (payment provider, email service, another service's API, a search index) in one flow. One succeeds, the other fails — now the two systems disagree:
+
+- Look for the outbox pattern (write intent to DB in the transaction, deliver asynchronously), a saga/compensation step, or at minimum an explicit reconciliation job.
+- "Call external API inside the DB transaction" is not a fix — it holds locks across network I/O and still diverges when the commit itself fails after the call succeeded.
+- Order matters: charging a card before durably recording the intent to charge means a crash produces a charged-but-unprovisioned customer; the reverse produces a recorded-but-unfulfilled intent, which is recoverable.
+
+Flag the divergence window and which side wins on replay.
+
+### 5. Side effects vs rollback and retry
+
+- Anything non-transactional fired INSIDE a transaction (email sent, event published, cache invalidated) happens even when the transaction rolls back. It must move after commit (or into an outbox).
+- Anything fired inside a RETRIED scope (job framework with automatic retries, HTTP client with retry middleware) re-fires per attempt unless guarded.
+- Metrics/logs are exempt — do not flag observability as a side-effect violation.
+
+### 6. Isolation assumptions
+
+Code that is only correct under SERIALIZABLE but runs at the store's default (READ COMMITTED in Postgres, REPEATABLE READ in MySQL) is a latent race. Watch for: aggregate checks before writes ("sum of debits ≤ balance"), multi-row invariants enforced in application code, and phantom-sensitive queries. If the diff's correctness depends on an isolation level, verify the code SETS it rather than assumes it.
+
+## Ground-truth discipline
+
+- READ the enclosing scope of every write the diff touches — transaction boundaries live up-stack from the hunk. `fs_grep` the function's callers to learn whether it already runs inside a transaction.
+- `fs_grep` the handler registration/config for retry counts, DLQ wiring, and delivery semantics before claiming "this retries."
+- Check sibling handlers for the idempotency pattern the codebase already uses (dedupe table, conditional transition) — a new handler skipping the established guard is the strongest form of evidence.
+- Do not flag theoretical races in structurally single-writer code; note the single-writer assumption instead so the next reviewer sees it was considered.
+
+## Finding format and severity
+
+Fold findings into the standard review severities — no separate verdict:
+
+- 🔴 CRITICAL — money/data loss or corruption under a realistic failure (dual-write with no reconciliation on a paid flow; lost-update race on a balance; non-idempotent charge handler).
+- 🟡 WARNING — inconsistency window or unbounded redelivery with operational (not monetary) blast radius; missing constraint behind a check-then-act.
+- 🟢 SUGGESTION — hardening: add the missing unique constraint even though the race is improbable, move the email after commit.
+
+Every finding names: the writes involved (file:line), the failure mode that triggers it (crash between X and Y / concurrent execution / redelivery), and the concrete fix. "This might have race conditions" is noise; "second `invoice.paid` delivery re-runs the provisioning insert at handler.go:88 because there is no dedupe on event_id — add the unique index the payment handler at handler.go:41 already uses" is signal.
+
+## Anti-patterns
+
+- Flagging every read-then-write as a race without checking who else writes.
+- Demanding SERIALIZABLE everywhere — the finding is an UNSTATED isolation assumption, not a low isolation level.
+- Treating logs/metrics as dual-writes.
+- Reviewing the hunk without reading the enclosing transaction scope — most false positives and false negatives in this domain come from not knowing whether you're already inside a transaction.
+- Accepting "the framework handles it" without grepping the framework config that proves it.

assets/skills/usage-pattern-testing/SKILL.md

@@ -0,0 +1,176 @@
+---
+description: Verify a change from the consumer's perspective - exercise the changed surface (HTTP API, RPC, CLI) black-box against a locally running instance with clean, isolated state. Run existing usage suites first for regressions, derive new tests from the spec (never the implementation), and classify every failure as bug / environment / expected contract change. Produces a USAGE_PROBE PASS/FAIL/INCONCLUSIVE verdict. Complements code-review (quality), adversarial-review (plan conformance), and security-review (abuse) - this is the only gate that tests BEHAVIOR by using the thing, not by reading it.
+enabled_tools: fs_read, fs_cat, fs_grep, fs_glob, fs_ls, fs_write, fs_patch, execute_command
+---
+You are verifying a change the way its consumers will experience it: by USING it. Every other
+review gate reads text — the diff, the plan, the code. This gate boots the system locally from a
+clean state and exercises the changed surface as a cold-start consumer would. It catches the class
+of defects invisible to static review: serialization quirks, replace-vs-patch semantics,
+wrong status codes, broken idempotency, empty-state crashes, auth holes on new routes.
+
+## The one question
+
+**Does the changed consumer-facing surface behave as the spec promises when actually used,
+starting from nothing?** You are not judging code quality, plan conformance, or exploitability —
+other gates own those. You judge observable behavior.
+
+## The independence rule (spec-first, or the gate is worthless)
+
+Derive expected behaviors from the **spec** — the plan/task acceptance criteria, the API contract
+(IDL/schema/OpenAPI/proto definitions), the documented CLI help — **BEFORE reading the
+implementation**. If you read the handler first and write tests that mirror it, you have re-proven
+the implementation's own assumptions, including its misreadings of the spec. Order of operations:
+
+1. Read the spec + contract. Write down the expected behaviors as concrete request→response pairs.
+2. Only THEN read implementation code — and only as much as needed to find ports, config, and
+   startup wiring. Never to "check what it actually does" before your expectations are written.
+
+## Phase order
+
+### 1. Identify the surface under test
+
+From the diff (or the caller's summary): which endpoints/RPCs/commands were added or changed?
+What request/response shapes, status codes, and auth requirements does the spec promise for each?
+If the change touches no consumer-facing surface, say so and return PASS with a one-line note —
+probing inert internals burns budget without value.
+
+### 2. Regression-first: find and run existing usage suites
+
+Discover what already exists before authoring anything:
+
+- `fs_glob` for suite files in ANY format the repo uses: `**/*.hurl`, `**/*.http`, `**/*.rest`,
+  `**/*.postman_collection.json`, `**/*.bru`, `**/e2e/**`, `**/integration/**`, `**/api-test*/**`,
+  `**/smoke*/**`, plus repo scripts that run them (`**/run-*test*`, Makefile/justfile targets,
+  package-manifest script entries) and shell scripts of `curl` commands (`fs_grep` for `curl `
+  under `scripts/`, `test/`, `tools/`).
+- Read the repo's contributor docs for the sanctioned way to run them.
+
+Run the existing suites against the changed code FIRST. Every failure here is a candidate
+regression. Classify each (see § Failure classification) — a failure is only acceptable when the
+spec EXPLICITLY changed that contract, and then the old test needs updating (note it in the
+report), not ignoring.
+
+### 3. Map coverage, author the delta
+
+List which of your expected behaviors from step 1 the existing suites already prove. Author new
+tests ONLY for the uncovered ones. Walk this usage-pattern checklist for each changed surface —
+these are the cases implementers systematically forget:
+
+| Pattern | What to probe |
+|---------|---------------|
+| Cold start / empty state | First-ever call with no pre-existing data: list → empty (not 500), get → not-found (not panic) |
+| Happy path | The spec's primary flow, end to end, asserting the full response shape — not just the status code |
+| Idempotency / re-call | Same create/update twice: duplicate error or no-op, per the spec — never silent double-write |
+| Invalid input | Missing required fields, wrong types, out-of-range values, malformed body → the spec's error shape and code, not a 500 |
+| Auth on the new surface | Missing/expired/insufficient credentials → the correct 401/403 (a new route with no auth check is a common miss) |
+| Not-found and stale references | Operations on IDs that don't exist or were deleted |
+| Partial update semantics | Does omitting a field preserve it (patch) or delete it (replace)? Assert whichever the spec promises — this is a classic silent-data-loss bug |
+| Serialization edges | Zero values, empty lists, unset optionals: encoders that omit zero values make `== false`/`== null` asserts lie — assert existence/absence per the actual encoding |
+| Pagination / limits | Page past the end, limit 0/1/max, stable ordering if promised |
+| Error shape consistency | New errors follow the same envelope as the rest of the surface |
+| State transitions | Illegal transitions rejected; legal ones observable via subsequent reads |
+
+Write the new tests where the repo's existing suites live, following their naming and layout
+conventions, so they are adoptable as permanent regression tests. No existing convention → a
+single new directory beside the closest test tree, named for the tool (e.g. `tests/usage/`).
+
+### 4. Environment discipline (clean, local, isolated)
+
+- **Clean state is non-negotiable.** Boot from nothing: fresh/ephemeral database (throwaway
+  container, tmp file, or dedicated schema), run migrations, seed ONLY what the tests create
+  themselves. Tests that depend on pre-existing data are not cold-start tests.
+- **Fully local.** Stub or mock external dependencies (fake servers, recorded fixtures, in-memory
+  substitutes) — a probe that calls real third-party systems is a flake generator and a hazard.
+- **Prefer the repo's own recipe.** If the plan or contributor docs provide a local-run recipe
+  (compose file, make target, dev script), use it verbatim before inventing your own. If you must
+  invent one, record every step in the report so it can be promoted into the docs.
+- **Teardown.** Leave no running processes, containers, or dirty state behind.
+- **Bounded startup retries only.** Retry/poll while the stack boots (bounded attempts, short
+  interval). NEVER add retries to make a flaky assertion pass — flakiness on a settled stack is a
+  finding.
+
+### 5. Failure classification (every failure gets exactly one)
+
+| Class | Meaning | Effect on verdict |
+|-------|---------|-------------------|
+| **BUG** | The running system violates the spec | FAIL — report with repro |
+| **EXPECTED-CHANGE** | An existing test asserts a contract the spec explicitly changed | Does not fail the verdict; the stale test is flagged for update |
+| **ENV** | The failure is in bringing the stack up or reaching it, not in behavior | Does not count as a bug; if it prevents meaningful probing → INCONCLUSIVE |
+
+Misclassifying ENV as BUG sends the implementer chasing ghosts; misclassifying BUG as ENV ships
+the defect. When unsure, reproduce twice and read the server logs before deciding.
+
+## Toolbox (repo conventions first; these are examples, not requirements)
+
+No specific tool is required. Precedence: (1) whatever format/harness the repo's existing usage
+suites already use — run and extend that; (2) a well-suited tool from the examples below if it is
+available or trivially installable; (3) ubiquitous fallbacks (`curl` + shell assertions cover any
+HTTP surface). What is non-negotiable is the discipline — spec-first asserts, clean state — not
+the tool.
+
+| Surface | Example tools | Notes |
+|---------|--------------|-------|
+| HTTP/REST/JSON (incl. gRPC-over-HTTP with JSON encoding) | [Hurl](https://hurl.dev) `.hurl` files; `curl` scripts | Hurl: plain-text request/assert format, capturable variables, `retry` for eventual consistency; files double as committed regression suites |
+| Pure gRPC/protobuf | `grpcurl` (scripted) | Use server reflection or point at the proto files |
+| CLI | Direct invocation via `execute_command` | Assert exit codes AND output; probe stdin/args edge cases |
+| Anything else | `curl`/scripts/the repo's own test harness | Same discipline: spec-first asserts, clean state |
+
+Optional niceties like Hurl and grpcurl may already be preinstalled (e.g. by a sandbox mixin) or
+can be installed idempotently (hurl via the distro package manager first — its prebuilt GitHub
+tarball dynamically links `libxml2.so.2`, which newer distros no longer ship; grpcurl from its
+GitHub release, a static Go binary). When a preferred tool is unavailable and uninstallable, fall
+back to what exists rather than skipping the check; classify a probe as ENV only when NO adequate
+tool can exercise the surface.
+
+If you use Hurl, gotchas that produce false results if unknown:
+
+- `[Captures]` run BEFORE `[Asserts]` in the same entry — capture a replaced value under a NEW
+  variable name, or your inequality asserts compare a value to itself.
+- JSON encoders that omit zero/empty values: assert `not exists` for absent fields — `== false`
+  or `== null` asserts fail on omitted keys.
+- Use `[Options] retry` with a bounded count for asynchronous effects (job completion, eventual
+  reads); never unbounded.
+
+## Verdict format
+
+End with EXACTLY one of:
+
+```
+USAGE_PROBE: PASS
+Surface: <endpoints/RPCs/commands probed>. Existing suites: <N run, all green | none found>.
+New tests: <M authored at <path>, all green>.
+<optional: 1-3 non-blocking observations (stale tests to update, recipe gaps)>
+```
+
+```
+USAGE_PROBE: FAIL
+Surface: <...>. Existing suites: <N run, X failed (Y regressions, Z expected-change)>. New tests: <M authored, W failed>.
+Behavioral findings:
+1. <surface + case> — <spec'd behavior, quoting the spec> — <observed behavior> — REPRO: <exact request/command + response received> — <test file:entry>
+Stale tests needing update (expected-change): <list or none>
+```
+
+```
+USAGE_PROBE: INCONCLUSIVE
+Could not establish a clean local environment: <what failed, verbatim error>.
+Missing: <the exact recipe/fixture/mock that would unblock — phrased so the plan author can add it>.
+Partial results (if any): <what did run and what it showed>
+```
+
+Every FAIL finding MUST include the exact reproduction (request/command and the response
+received) and cite the test file — a behavioral complaint without a repro is noise. INCONCLUSIVE
+is an honest, acceptable verdict: it routes the fix to the environment recipe, not the code.
+NEVER report INCONCLUSIVE as PASS ("couldn't test, probably fine") or as FAIL (the implementer
+would hunt a nonexistent bug).
+
+## Anti-patterns
+
+- Writing tests after reading the implementation — you will encode its bugs as expectations.
+- Skipping the existing suites and jumping to new tests — regressions are the cheapest bugs to catch.
+- Testing through internal seams (direct DB reads, internal function calls) — this gate is
+  consumer-perspective only; internals belong to unit tests.
+- Depending on pre-existing data, shared databases, or previously running services.
+- Adding retries/sleeps until a flaky assertion passes — flakiness is a finding, not an obstacle.
+- Reporting an environment failure as a behavioral FAIL (or burying it in a PASS).
+- Throwaway tests in /tmp — tests that don't land in the repo's suite location die with the run.
+- Asserting only status codes — shape and content are where the quirks live.

assets/skills/worker-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Review the background-work surface contract of a change - queue/stream consumers, scheduled jobs, and cron handlers. Checks retry/backoff policy, DLQ/poison-message routing, graceful-shutdown drain, concurrency/prefetch bounds, and visibility-timeout vs processing-time reasoning. Load when a diff touches queue/job/cron consumer registration, handler wiring, or schedule definitions. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing consumer registration, transport config, and shutdown paths.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing background-work wiring. The generic correctness checklist asks "does this handler process a message?"; you ask **"what happens to this consumer on the bad days — a poison message, a deploy mid-batch, a downstream outage?"** A worker's contract is with the queue, the scheduler, and the deploy pipeline, not with a single happy-path message. Most worker incidents are not broken handler logic — they are a queue wedged behind one malformed message, in-flight work silently dropped by a rolling restart, or a retry storm hammering a struggling dependency.
+
+## When to load this skill
+
+The diff touches ANY of: queue/stream consumer registration, job/worker handler wiring, cron or schedule definitions, or the transport configuration behind them (retry counts, prefetch, visibility timeouts, shutdown hooks). If the diff is handler business logic behind unchanged wiring — unload; this checklist has nothing for you. Note: a diff that wires a consumer AND changes state is two reviews — this skill covers the consumer contract, and `transactional-integrity` covers the state changes; state-changing worker diffs load BOTH.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (config validators, schema checks for queue/schedule definitions); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what linters cannot reach: whether a retry policy exists at all, where a poison message goes, what a deploy does to in-flight work. If the repo plausibly warrants a linter config it lacks, emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the transport's own guarantees and the deployment story before flagging, and when you rely on an exemption, state it so the next reviewer sees it was considered.
+
+### 1. 🟡 `[convention]` No retry/backoff policy where the transport provides none
+
+For each new or rewired consumer: when the handler fails, who retries, how many times, with what backoff? Some transports provide redelivery with backoff out of the box — READ the transport config before claiming they do here. If neither the transport nor the code establishes a policy, a transient downstream blip becomes permanent message loss (or an immediate hot-loop of retries). Name the consumer, the transport, and what a single failure currently does. A consumer whose transport is configured with sane redelivery is exempt — cite the config at file:line.
+
+### 2. 🟡 `[convention]` No DLQ/poison-message route — one bad message wedges the queue
+
+A message that fails every retry must go SOMEWHERE terminal: a dead-letter queue, a parked table, a quarantine topic. Trace the exhausted-retries path for each consumer the diff adds: if the message returns to the head of the queue forever, one malformed payload halts all processing behind it. Ordered/single-partition consumers are the highest-blast-radius case. Where the message *lands* is your question; whether the handler's error path also acknowledges correctly under at-least-once delivery is `transactional-integrity`'s.
+
+### 3. 🟡 `[convention]` No graceful-shutdown drain — in-flight work lost on deploy
+
+Every deploy sends this worker a termination signal mid-message. Does the diff's worker stop taking new work, finish (or cleanly nack) what is in flight, and exit within the platform's grace period? Look for a shutdown hook, drain loop, or the framework's built-in drain — and check the termination grace configured for the deployment. Exemptions are real: a stateless cron job reading a read-only source loses nothing on interruption, and an at-least-once transport redelivers whatever was in flight (making drain an efficiency concern, not a loss) — say explicitly which exemption you are relying on. The item bites hardest for at-least-once consumers with long-running in-flight work and for anything ack-early.
+
+### 4. 🟢 `[convention]` Unbounded concurrency/prefetch
+
+Does the new consumer bound how many messages it processes at once — worker-pool size, prefetch/fetch-count, max in-flight? An unbounded consumer amplifies a queue backlog into a self-inflicted outage: memory blowup, connection-pool exhaustion, a thundering herd against the downstream the handler calls. Check the transport defaults before flagging — some default to a sane prefetch; some default to unlimited. A low-volume schedule-driven job with structurally bounded input is exempt.
+
+### 5. 🟢 `[convention]` Visibility-timeout vs processing-time reasoning absent
+
+Where the transport uses a visibility timeout, lease, or lock (with redelivery when it expires): is there any evidence — a comment, a config value derived from measurements, a heartbeat/extension call — that the timeout exceeds the handler's realistic worst-case processing time? A timeout shorter than processing time means the message redelivers WHILE the first attempt is still running: duplicate concurrent processing by design. You flag the absent reasoning; whether the handler survives that concurrent duplicate is `transactional-integrity`'s question. Transports with no visibility/lease mechanism are exempt.
+
+## Ground-truth discipline
+
+- READ the transport/framework configuration, not just the handler — retry counts, DLQ wiring, prefetch, and drain behavior live in config and registration code, not in the handler body.
+- `fs_grep` sibling consumers for the established idioms (DLQ naming, shutdown hooks, backoff helpers) — a new consumer skipping the house pattern is the strongest form of evidence; cite the sibling at file:line.
+- Check the deployment manifests for termination grace periods when reasoning about drain — the code's drain loop is only as good as the time the platform gives it.
+- Do not flag a missing guard the transport demonstrably provides; cite the config that provides it instead.
+
+## What this skill does NOT check
+
+- Whether the handler is idempotent under redelivery, atomic across writes, or safe against dual-writes to a DB plus an external system → `transactional-integrity` (state-changing worker diffs load both skills).
+- Whether job payloads, queue names, or worker logs expose secrets or abusable data → `security-review` and `logging-discipline`.
+- Metrics, alerts, and dashboards for the new worker (queue depth, processing lag, failure rate) → `observability-review`.
+- Log lines, levels, and message conventions inside the handler → `logging-discipline`.

config.agent.example.yaml

@@ -14,7 +14,8 @@
 model: openai:gpt-4o # Specify the LLM to use
 temperature: null # Set default temperature parameter, range (0, 1)
 top_p: null # Set default top-p parameter, with a range of (0, 1) or (0, 2) depending on the model
-reasoning_effort: null           # Reasoning effort level for models that support it (e.g. low, medium, high).
+reasoning_effort:
+  null # Reasoning effort level for models that support it (e.g. low, medium, high).
   # Only valid when the agent's model declares reasoning_levels.
 agent_session: null # Set a session to use when starting the agent. (e.g. temp, default); defaults to globally set agent_session
 name: <agent-name> # Name of the agent, used in the UI and logs
@@ -37,34 +38,47 @@ can_spawn_agents: false          # Enable the agent to spawn child agents
 #   - explore                    # If omitted (the default), ALL installed agents are spawnable. This is the unrestricted default.
 #   - coder                      # Provide a list to restrict. Match is exact and case-sensitive (use directory names).
 #   - oracle                     # An empty list ([]) means literally nothing spawnable.
-                                 # Also filters `agent__list_available` output so the LLM only sees what it can spawn.
-                                 # Graph agents (graph.yaml) ignore this; they declare spawn targets in agent nodes.
+# Also filters `agent__list_available` output so the LLM only sees what it can spawn.
+# Graph agents (graph.yaml) ignore this; they declare spawn targets in agent nodes.
 max_concurrent_agents: 4 # Maximum number of agents that can run simultaneously
 max_agent_depth: 3 # Maximum nesting depth for sub-agents (prevents runaway spawning)
+max_concurrent_jobs:
+  5 # Max background jobs (`job__*` tools) running at once for this agent
+  # (overrides the global setting; 0 disables background jobs for this agent)
 inject_spawn_instructions: true # Inject the default agent spawning instructions into the agent's system prompt
 summarization_model: null # Model to use for summarizing sub-agent output (e.g. 'openai:gpt-4o-mini'); defaults to current model
 summarization_threshold: 4000 # Character threshold above which sub-agent output is summarized before returning to parent
 escalation_timeout: 300 # Seconds a sub-agent waits for a user interaction response before timing out (default: 5 minutes)
 mcp_servers: # Optional list of MCP servers that the agent utilizes
-  - github                       # Corresponds to the name of an MCP server in the `<coyote-config-dir>/functions/mcp.json` file
+  - github # Corresponds to the name of an MCP server in the `<coyote-config-dir>/mcp.json` file
+mcp_tools: # Optional per-server tool allowlist for the agent's MCP servers
+  github: # (glob patterns: * and ?). Intersects with the global config,
+    - get_* # mcp.json `allowedTools`, and every other configured layer. It
+    - search_* # can only narrow access, never widen it.
 global_tools: # Optional list of additional global tools to enable for the agent; i.e. not tools specific to the agent
   - web_search
   - fs
   - python
-skills_enabled: true             # Master switch for skills in this agent (default: inherit from global).
+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
+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
+enabled_macros: # Optional list of macros invocable when this agent is active in the REPL.
+  - generate-commit-message # An empty list disables all macros. Omit to inherit the role/global default.
+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
+instructions:
+  | # Static instructions for the agent; ignored if dynamic instructions are used
   You are a AI agent designed to demonstrate agent capabilities.
 
   <tools>

config.example.yaml

@@ -93,7 +93,8 @@ enabled_tools: null              # Which tools to enable by default.
                                  #     - 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')
+visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools').
+                                 # Null/missing = all tools in the global tools dir are visible; [] = none.
 #  - ast_grep.sh
 #  - demo_py.py
 #  - demo_sh.sh
@@ -137,6 +138,18 @@ enabled_mcp_servers: null        # Which MCP servers to enable by default.
                                  #     - slack
                                  # Example (comma-separated form):
                                  #   enabled_mcp_servers: github,slack,ddg-search
+mcp_tools: null                  # Per-server MCP tool allowlists (glob patterns: * and ? supported).
+                                 # Tools that match no pattern are hidden from the model as if they
+                                 # don't exist. Stacks with the other allowlist layers (mcp.json
+                                 # `allowedTools`, role, agent, session, skill, graph node). Every
+                                 # configured layer must allow a tool, so layers only ever narrow.
+                                 # An empty list blocks all of a server's tools.
+                                 # Example:
+                                 #   mcp_tools:
+                                 #     github:
+                                 #       - get_*
+                                 #       - list_*
+                                 #     slack: []
 no_workspace_mcp: false          # Disable loading workspace-local MCP servers (default: false).
                                  # When false (the default), Coyote merges the first workspace MCP config it finds
                                  # into the global MCP registry at startup, checking in order:
@@ -169,6 +182,21 @@ inject_skill_instructions: true   # Inject a short hint pointing the model at `s
                                   # 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.
 
+# ---- Macros ----
+# Macros are Coyote's custom commands: named sequences of REPL commands and prompts, invoked directly by name
+# (a macro file named `review.yaml` runs as `.review [args]`; built-in commands always win a name collision).
+# Workspace-local macros in `.coyote/macros/` shadow same-named global macros (skip them with --no-workspace-macros).
+# See the [Macros documentation](https://github.com/Dark-Alex-17/coyote/wiki/Macros) for more details.
+enabled_macros: null              # Which macros are invocable by default (no role/agent/session active). null = all visible.
+                                  # An empty list means NO macros are invocable. Accepts either a YAML list or a
+                                  # comma-separated string. Roles, agents, and sessions may define their own
+                                  # `enabled_macros`; the most specific active one wins (session > agent > role > global).
+                                  # Example (list form):
+                                  #   enabled_macros:
+                                  #     - generate-commit-message
+                                  # Example (comma-separated form):
+                                  #   enabled_macros: generate-commit-message,review
+
 # ---- Auto-Continue (Todo System) ----
 # The auto-continue system provides built-in task tracking for improved reliability.
 # When enabled, the model can create todo lists and the system will automatically
@@ -189,6 +217,7 @@ summary_context_prompt: >        # The text prompt used for including the summar
   'This is a summary of the chat history as a recap: '
 compression_keep_last: 0         # Number of most-recent messages to keep visible after compression (0 = compress all messages)
 max_tool_result_chars: null      # Cap on tool result characters forwarded to the model per call (null = no cap)
+max_concurrent_jobs: 5           # Max background jobs (`job__*` tools) running at once per context (default: 5; 0 disables background jobs entirely)
 
 # ---- Memory ----
 # See the [Memory documentation](https://github.com/Dark-Alex-17/coyote/wiki/Memory) for more information.
@@ -292,6 +321,7 @@ clients:
   #   extra:
   #     proxy: socks5://127.0.0.1:1080                # Set proxy
   #     connect_timeout: 10                           # Set timeout in seconds for connect to api
+  #     read_timeout: 300                             # Set timeout in seconds for a read stall (no bytes received); 0 disables (default: 300)
 
   # See https://platform.openai.com/docs/quickstart
   - type: openai

config.macro.example.yaml

@@ -1,3 +1,13 @@
+description: Demonstrates every macro field       # Optional; shown in `.list macros` and in `.<name>` tab-completion.
+isolated: true                                    # Optional; 'true' by default. When true, steps run in a forked,
+                                                  # throwaway context: the exchange and any `.role`/`.model` switches
+                                                  # vanish when the macro ends. When false, steps run on the LIVE
+                                                  # session exactly as if you typed them: prompts are recorded, and
+                                                  # mutating steps (e.g. `.role`, `.model`) PERSIST after the macro
+                                                  # finishes -- by design. Steps are fail-fast in both modes: an error
+                                                  # aborts the remaining steps, but completed steps' effects remain.
+                                                  # A non-isolated macro step cannot invoke another macro, and a
+                                                  # `.exit` step never exits the REPL.
 variables:                                        # A list of positional variables that the macro uses
   - name: positional_1                            # The name of the positional variable.
     default: null                                 # Since no default value is provided, this argument is required; 'null' by default

config.role.example.md

@@ -16,6 +16,10 @@ enabled_tools:                        # Tools to enable for this role. Accepts a
 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.
+mcp_tools:                            # Per-server MCP tool allowlists for this role (globs: * and ?).
+  github:                             # Intersects with the global config / mcp.json `allowedTools`.
+    - get_*                           # Layers only narrow. Tools matching no pattern are hidden from
+    - search_*                        # the model as if they don't exist.
 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)
@@ -24,6 +28,9 @@ enabled_skills:                       # Skills available when this role is activ
 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)
+enabled_macros:                       # Macros invocable when this role is active. Accepts a YAML list (preferred)
+  - generate-commit-message           # or a comma-separated string (e.g. `enabled_macros: generate-commit-message,review`).
+                                      # An empty list disables all macros. Omit to inherit the global default.
 memory: null                          # Per-role memory override (default: inherit). Set to `false` to disable memory
                                       # when this role is active. See the Memory wiki page.
 

deployment/homebrew/coyote.rb.template

@@ -1,7 +1,7 @@
 # Documentation: https://docs.brew.sh/Formula-Cookbook
 #                https://rubydoc.brew.sh/Formula
 class Coyote < Formula
-  desc "All-in-one, batteries included LLM CLI tool"
+  desc "The batteries-included runtime for LLMs"
   homepage "https://github.com/Dark-Alex-17/coyote"
   if OS.mac? and Hardware::CPU.arm?
     url "https://github.com/Dark-Alex-17/coyote/releases/download/v$version/coyote-aarch64-apple-darwin.tar.gz"

graph.example.yaml

@@ -36,6 +36,14 @@ top_p: null                        # Default sampling top-p for `llm` nodes
 reasoning_effort: null             # Default reasoning effort for `llm` nodes that don't override it.
                                    # Only valid when the model declares reasoning_levels.
 
+max_concurrent_jobs: 5             # Max background jobs (`job__*` tools) running at once across the
+                                   # whole graph run: every `llm` node (including parallel branches)
+                                   # draws from this one pool, so the budget is graph-wide — there is
+                                   # no per-node override. Jobs themselves are node-local: the node
+                                   # that starts a job must collect or cancel it before it ends, and
+                                   # anything left running at node exit is cancelled. Overrides the
+                                   # global setting; 0 disables background jobs for this graph agent.
+
 global_tools:                      # Tool universe an `llm` node's `tools:` whitelist draws from
   - web_search_coyote.sh
   - fetch_url_via_curl.sh
@@ -43,6 +51,10 @@ global_tools:                      # Tool universe an `llm` node's `tools:` whit
 mcp_servers:                       # MCP servers an `llm` node may reference via `mcp:<server>`
   - ddg-search
 
+mcp_tools:                         # Optional per-server tool allowlists (globs: * and ?) applied to
+  ddg-search:                      # every node that uses `mcp:<server>`; intersects with the other
+    - search                       # allowlist layers (global config, agent, mcp.json `allowedTools`).
+
 # ---------------------------------------------------------------------------
 # Skills policy (optional)
 # Skills only attach to `llm` nodes inside a graph. Both fields are optional.
@@ -394,6 +406,9 @@ nodes:
     tools:                     # Narrow whitelist: exactly these entries, nothing else
       - web_search_coyote        #   an exact global-tool / custom-tool name
       - mcp:ddg-search         #   `mcp:<server>` includes that server's functions
+    mcp_tools:                 # Optional per-node narrowing of MCP tools (globs: * and ?)
+      ddg-search:              #   keys must be servers this graph enables; intersects with
+        - search               #   the graph-level mcp_tools above and every other layer
     model: claude:claude-haiku-4-5  # Optional per-node model override
     temperature: 0.3           # Optional per-node sampling override
     reasoning_effort: null     # Optional per-node reasoning effort override (e.g. low, medium, high)

models.yaml

@@ -841,6 +841,11 @@
       referrer: coyote
     echo_pkce_in_token_exchange: true
   models:
+    - name: grok-4.6
+      input_price: 2
+      output_price: 6
+      max_input_tokens: 500000
+      supports_function_calling: true
     - name: grok-4.5
       input_price: 2
       output_price: 6

scripts/install_coyote.ps1

@@ -16,6 +16,8 @@ param(
   [string]$BinDir = $env:BIN_DIR
 )
 
+if ($Version -and $Version -match '^[0-9]') { $Version = "v$Version" }
+
 $Repo = 'Dark-Alex-17/coyote'
 
 function Write-Info($msg) { Write-Host "[coyote-install] $msg" }
@@ -61,79 +63,155 @@ if ($os -eq 'windows') {
   if ($arch -eq 'x86_64') { $candidates += 'coyote-x86_64-apple-darwin.tar.gz' }
   else { $candidates += 'coyote-aarch64-apple-darwin.tar.gz' }
 } elseif ($os -eq 'linux') {
-  if ($arch -eq 'x86_64') {
-    $candidates += 'coyote-x86_64-unknown-linux-gnu.tar.gz'
-    $candidates += 'coyote-x86_64-unknown-linux-musl.tar.gz'
-  } else {
-    $candidates += 'coyote-aarch64-unknown-linux-musl.tar.gz'
+  $libc = 'musl'
+  try { getconf GNU_LIBC_VERSION *> $null; if ($LASTEXITCODE -eq 0) { $libc = 'gnu' } } catch { }
+  try { if ((ldd --version 2>&1 | Out-String) -imatch 'glibc') { $libc = 'gnu' } } catch { }
+  if ($libc -eq 'gnu') {
+    # ldconfig lives in /usr/sbin on Debian/Ubuntu, often missing from non-root
+    # PATHs, so try its known locations and fall back to probing library dirs.
+    $libssl3 = $false
+    foreach ($ldc in @('ldconfig', '/sbin/ldconfig', '/usr/sbin/ldconfig')) {
+      try { if ((& $ldc -p 2>&1 | Out-String) -match 'libssl\.so\.3') { $libssl3 = $true; break } } catch { }
     }
+    if (-not $libssl3) {
+      foreach ($libDir in @('/usr/lib/*/libssl.so.3', '/lib/*/libssl.so.3', '/usr/lib64/libssl.so.3', '/usr/lib/libssl.so.3', '/usr/local/lib/libssl.so.3', '/usr/local/lib/*/libssl.so.3')) {
+        if (Get-Item -Path $libDir -ErrorAction SilentlyContinue) { $libssl3 = $true; break }
+      }
+    }
+    if ($libssl3) {
+      $candidates += "coyote-$arch-unknown-linux-gnu.tar.gz"
+    } else {
+      Write-Info "glibc detected but OpenSSL 3 (libssl.so.3) not found; using musl build"
+    }
+  }
+  $candidates += "coyote-$arch-unknown-linux-musl.tar.gz"
 } else {
   Fail "Unsupported OS for this installer: $os"
 }
 
-$asset = $null
-foreach ($c in $candidates) {
-  $asset = $release.assets | Where-Object { $_.name -eq $c } | Select-Object -First 1
-  if ($asset) { break }
-}
-if (-not $asset) {
-  Write-Error "No matching asset found for $os-$arch. Tried:"; $candidates | ForEach-Object { Write-Error "  - $_" }
-  exit 1
-}
-
-Write-Info "Selected asset: $($asset.name)"
-Write-Info "Download URL:  $($asset.browser_download_url)"
-
 $tmp = New-Item -ItemType Directory -Force -Path ([IO.Path]::Combine([IO.Path]::GetTempPath(), "coyote-$(Get-Random)"))
-$archive = Join-Path $tmp.FullName 'asset'
-try { Invoke-WebRequest -UseBasicParsing -Headers @{ 'User-Agent' = 'coyote-installer' } -Uri $asset.browser_download_url -OutFile $archive } catch { Fail "Failed to download asset. $_" }
 
-$extractDir = Join-Path $tmp.FullName 'extract'; New-Item -ItemType Directory -Force -Path $extractDir | Out-Null
+try {
+  $exec = if ($isWin) { 'coyote.exe' } else { 'coyote' }
+  $dest = Join-Path $BinDir $exec
 
-if ($asset.name -match '\.zip$') {
+  $installed = $false
+  $tried = @()
+  $attempt = 0
+  foreach ($c in $candidates) {
+    $asset = $release.assets | Where-Object { $_.name -eq $c } | Select-Object -First 1
+    if (-not $asset) {
+      $tried += "${c}: no matching release asset"
+      continue
+    }
+
+    $attempt++
+    $work = New-Item -ItemType Directory -Force -Path (Join-Path $tmp.FullName "attempt-$attempt")
+
+    Write-Info "Selected asset: $($asset.name)"
+    Write-Info "Download URL:  $($asset.browser_download_url)"
+
+    $archive = Join-Path $work.FullName 'asset'
+    try {
+      Invoke-WebRequest -UseBasicParsing -Headers @{ 'User-Agent' = 'coyote-installer' } -Uri $asset.browser_download_url -OutFile $archive
+    } catch {
+      Write-Info "Failed to download ${c}; trying next candidate. $_"
+      $tried += "${c}: download failed"
+      continue
+    }
+
+    $extractDir = Join-Path $work.FullName 'extract'; New-Item -ItemType Directory -Force -Path $extractDir | Out-Null
+
+    try {
+      if ($asset.name -match '\.zip$') {
         Add-Type -AssemblyName System.IO.Compression.FileSystem
         [System.IO.Compression.ZipFile]::ExtractToDirectory($archive, $extractDir)
-} elseif ($asset.name -match '\.tar\.gz$' -or $asset.name -match '\.tgz$') {
+      } elseif ($asset.name -match '\.tar\.gz$' -or $asset.name -match '\.tgz$') {
         $tar = Get-Command tar -ErrorAction SilentlyContinue
         if ($tar) { & $tar.Source -xzf $archive -C $extractDir }
-  else { Fail "Asset is tar archive but 'tar' is not available." }
-} else {
+        else { throw "Asset is tar archive but 'tar' is not available." }
+      } else {
         try { Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory($archive, $extractDir) }
         catch {
           $tar = Get-Command tar -ErrorAction SilentlyContinue
-    if ($tar) { & $tar.Source -xf $archive -C $extractDir } else { Fail "Unknown archive format; neither zip nor tar workable." }
+          if ($tar) { & $tar.Source -xf $archive -C $extractDir } else { throw "Unknown archive format; neither zip nor tar workable." }
+        }
+      }
+    } catch {
+      Write-Info "Failed to extract ${c}; trying next candidate. $_"
+      $tried += "${c}: extract failed"
+      continue
     }
-}
 
-$bin = $null
-Get-ChildItem -Recurse -File $extractDir | ForEach-Object {
+    $bin = $null
+    Get-ChildItem -Recurse -File $extractDir | ForEach-Object {
       if ($isWin) { if ($_.Name -ieq 'coyote.exe') { $bin = $_.FullName } }
       else { if ($_.Name -ieq 'coyote') { $bin = $_.FullName } }
-}
-if (-not $bin) { Fail "Could not find coyote binary inside the archive." }
+    }
+    if (-not $bin) {
+      Write-Info "Could not find coyote binary inside ${c}; trying next candidate"
+      $tried += "${c}: no coyote binary in archive"
+      continue
+    }
 
-if (-not $isWin) { try { & chmod +x -- $bin } catch {} }
+    if (-not $isWin) { try { & chmod +x -- $bin } catch {} }
 
-$exec = if ($isWin) { 'coyote.exe'} else { 'coyote' }
-$dest = Join-Path $BinDir $exec
-Copy-Item -Force $bin $dest
-Write-Info "Installed: $dest"
+    $works = $false
+    try { & $bin --version *> $null; if ($LASTEXITCODE -eq 0) { $works = $true } } catch { }
+    if (-not $works -and -not $isWin) {
+      # The temp dir may live on a noexec mount; retry from a probe file in
+      # the install directory before rejecting.
+      $probe = Join-Path $BinDir ".coyote-install-probe-$PID"
+      try {
+        Copy-Item -Force $bin $probe
+        & chmod +x -- $probe
+        & $probe --version *> $null
+        if ($LASTEXITCODE -eq 0) { $works = $true }
+      } catch { } finally {
+        Remove-Item -Force -ErrorAction SilentlyContinue $probe
+      }
+    }
+    if (-not $works) {
+      Write-Info "Downloaded $c but it failed to run on this system; trying next candidate"
+      $tried += "${c}: binary failed to run on this system"
+      continue
+    }
 
-if ($isWin) {
+    Copy-Item -Force $bin $dest
+    Write-Info "Installed: $dest"
+    $installed = $true
+    break
+  }
+
+  if (-not $installed) {
+    Write-Error "No usable asset found for $os-$arch. Tried:"
+    $tried | ForEach-Object { Write-Error "  - $_" }
+    exit 1
+  }
+
+  if ($isWin) {
     $pathParts = ($env:Path -split ';') | Where-Object { $_ -ne '' }
     if ($pathParts -notcontains $BinDir) {
-    $userPath = [Environment]::GetEnvironmentVariable('Path', 'User'); if (-not $userPath) { $userPath = '' }
-    if (-not ($userPath -split ';' | Where-Object { $_ -eq $BinDir })) {
+      # Read/write the User PATH via the registry directly: the [Environment]
+      # round-trip expands %VAR% entries and bakes them in on write.
+      $regKey = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
+      if ($regKey) {
+        $userPath = [string]$regKey.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+        if (-not (($userPath -split ';') -contains $BinDir)) {
           $newUserPath = if ($userPath.Trim().Length -gt 0) { "$userPath;$BinDir" } else { $BinDir }
-      [Environment]::SetEnvironmentVariable('Path', $newUserPath, 'User')
+          $regKey.SetValue('Path', $newUserPath, [Microsoft.Win32.RegistryValueKind]::ExpandString)
           Write-Info "Added to User PATH: $BinDir (restart shell to take effect)"
         }
+        $regKey.Close()
       }
-} else {
+    }
+  } else {
     if (-not ($env:PATH -split ':' | Where-Object { $_ -eq $BinDir })) {
       Write-Info "Note: $BinDir is not in PATH. Add it to your shell profile."
     }
+  }
+
+  Write-Info "Done. Try: coyote --help"
+} finally {
+  Remove-Item -Recurse -Force -ErrorAction SilentlyContinue $tmp
 }
-
-Write-Info "Done. Try: coyote --help"
-

scripts/install_coyote.sh

@@ -13,8 +13,6 @@ set -euo pipefail
 #   --bin-dir <dir>   Install directory (default: /usr/local/bin or ~/.local/bin). Or set BIN_DIR.
 
 REPO="Dark-Alex-17/coyote"
-VERSION="${COYOTE_VERSION:-}"
-BIN_DIR="${BIN_DIR:-}"
 
 usage() {
   echo "coyote installer (Linux/macOS)"
@@ -25,24 +23,6 @@ usage() {
   echo "  -h, --help              Show help"
 }
 
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --version) VERSION="$2"; shift 2;;
-    --bin-dir) BIN_DIR="$2"; shift 2;;
-    -h|--help) usage; exit 0;;
-    *) echo "Unknown argument: $1" >&2; usage; exit 2;;
-  esac
-done
-
-if [[ -z "${BIN_DIR}" ]]; then
-  if [[ -w "/usr/local/bin" ]]; then
-    BIN_DIR="/usr/local/bin"
-  else
-    BIN_DIR="${HOME}/.local/bin"
-  fi
-fi
-mkdir -p "${BIN_DIR}"
-
 log() {
 	echo "[coyote-install] $*"
 }
@@ -54,42 +34,6 @@ need_cmd() {
   fi
 }
 
-need_cmd uname
-need_cmd mktemp
-need_cmd tar
-
-if command -v curl >/dev/null 2>&1; then
-  DL=curl
-elif command -v wget >/dev/null 2>&1; then
-  DL=wget
-else
-  echo "Error: need curl or wget" >&2
-  exit 1
-fi
-
-UNAME_OS=$(uname -s | tr '[:upper:]' '[:lower:]')
-case "$UNAME_OS" in
-  linux)  OS=linux ;;
-  darwin) OS=darwin ;;
-  *) echo "Error: unsupported OS '$UNAME_OS'" >&2; exit 1;;
-esac
-
-UNAME_ARCH=$(uname -m)
-case "$UNAME_ARCH" in
-  x86_64|amd64) ARCH=x86_64 ;;
-  aarch64|arm64) ARCH=aarch64 ;;
-  *) echo "Error: unsupported arch '$UNAME_ARCH'" >&2; exit 1;;
-esac
-
-log "Target: ${OS}-${ARCH}"
-
-API_BASE="https://api.github.com/repos/${REPO}/releases"
-if [[ -z "${VERSION}" ]]; then
-  RELEASE_URL="${API_BASE}/latest"
-else
-  RELEASE_URL="${API_BASE}/tags/${VERSION}"
-fi
-
 http_get() {
   if [[ "$DL" == "curl" ]]; then
     curl -fsSL -H 'User-Agent: coyote-installer' "$1"
@@ -98,114 +42,240 @@ http_get() {
   fi
 }
 
-TMPDIR="$(mktemp -d)"
-trap 'rm -rf "$TMPDIR"' EXIT
+smoke_test() {
+  # The scratch dir may live on a noexec mount; if running in place fails,
+  # retry from a probe file in the install directory before rejecting.
+  local bin="$1"
+  if "$bin" --version >/dev/null 2>&1; then return 0; fi
+  local probe="${BIN_DIR}/.coyote-install-probe.$$"
+  local ok=1
+  if cp "$bin" "$probe" 2>/dev/null && chmod +x "$probe" 2>/dev/null; then
+    if "$probe" --version >/dev/null 2>&1; then ok=0; fi
+  fi
+  rm -f "$probe"
+  return "$ok"
+}
 
-log "Fetching release metadata from $RELEASE_URL"
-JSON="$TMPDIR/release.json"
-if ! http_get "$RELEASE_URL" > "$JSON"; then
+main() {
+  VERSION="${COYOTE_VERSION:-}"
+  BIN_DIR="${BIN_DIR:-}"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --version) VERSION="$2"; shift 2;;
+      --bin-dir) BIN_DIR="$2"; shift 2;;
+      -h|--help) usage; exit 0;;
+      *) echo "Unknown argument: $1" >&2; usage; exit 2;;
+    esac
+  done
+
+  if [[ -n "$VERSION" && "$VERSION" =~ ^[0-9] ]]; then VERSION="v${VERSION}"; fi
+
+  if [[ -z "${BIN_DIR}" ]]; then
+    if [[ -w "/usr/local/bin" ]]; then
+      BIN_DIR="/usr/local/bin"
+    else
+      BIN_DIR="${HOME}/.local/bin"
+    fi
+  fi
+  mkdir -p "${BIN_DIR}"
+
+  need_cmd uname
+  need_cmd mktemp
+  need_cmd tar
+
+  if command -v curl >/dev/null 2>&1; then
+    DL=curl
+  elif command -v wget >/dev/null 2>&1; then
+    DL=wget
+  else
+    echo "Error: need curl or wget" >&2
+    exit 1
+  fi
+
+  UNAME_OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+  case "$UNAME_OS" in
+    linux)  OS=linux ;;
+    darwin) OS=darwin ;;
+    *) echo "Error: unsupported OS '$UNAME_OS'" >&2; exit 1;;
+  esac
+
+  UNAME_ARCH=$(uname -m)
+  case "$UNAME_ARCH" in
+    x86_64|amd64) ARCH=x86_64 ;;
+    aarch64|arm64) ARCH=aarch64 ;;
+    *) echo "Error: unsupported arch '$UNAME_ARCH'" >&2; exit 1;;
+  esac
+
+  log "Target: ${OS}-${ARCH}"
+
+  API_BASE="https://api.github.com/repos/${REPO}/releases"
+  if [[ -z "${VERSION}" ]]; then
+    RELEASE_URL="${API_BASE}/latest"
+  else
+    RELEASE_URL="${API_BASE}/tags/${VERSION}"
+  fi
+
+  WORKDIR="$(mktemp -d)"
+  trap 'rm -rf "$WORKDIR"; rm -f "${BIN_DIR}/.coyote-install-probe.$$"' EXIT
+
+  log "Fetching release metadata from $RELEASE_URL"
+  JSON="$WORKDIR/release.json"
+  if ! http_get "$RELEASE_URL" > "$JSON"; then
     echo "Error: failed to fetch release metadata. Check version tag." >&2
     exit 1
-fi
+  fi
 
-ASSET_CANDIDATES=()
-if [[ "$OS" == "darwin" ]]; then
+  ASSET_CANDIDATES=()
+  if [[ "$OS" == "darwin" ]]; then
     if [[ "$ARCH" == "x86_64" ]]; then
       ASSET_CANDIDATES+=("coyote-x86_64-apple-darwin.tar.gz")
     else
       ASSET_CANDIDATES+=("coyote-aarch64-apple-darwin.tar.gz")
     fi
-elif [[ "$OS" == "linux" ]]; then
-  if [[ "$ARCH" == "x86_64" ]]; then
+  elif [[ "$OS" == "linux" ]]; then
     LIBC="musl"
     if command -v getconf >/dev/null 2>&1 && getconf GNU_LIBC_VERSION >/dev/null 2>&1; then LIBC="gnu"; fi
     if ldd --version 2>&1 | grep -qi glibc; then LIBC="gnu"; fi
 
     if [[ "$LIBC" == "gnu" ]]; then
-      ASSET_CANDIDATES+=("coyote-x86_64-unknown-linux-gnu.tar.gz")
+      # The gnu binary dynamically links OpenSSL 3. On Debian/Ubuntu, ldconfig lives
+      # in /usr/sbin, which is often missing from non-root PATHs, so try its known
+      # locations and fall back to probing the usual library directories directly.
+      LIBSSL3=""
+      for LDCONFIG in ldconfig /sbin/ldconfig /usr/sbin/ldconfig; do
+        if command -v "$LDCONFIG" >/dev/null 2>&1; then
+          if "$LDCONFIG" -p 2>/dev/null | grep -q 'libssl\.so\.3'; then LIBSSL3="yes"; fi
+          break
         fi
-
-    ASSET_CANDIDATES+=("coyote-x86_64-unknown-linux-musl.tar.gz")
+      done
+      if [[ -z "$LIBSSL3" ]]; then
+        for LIBSSL_CANDIDATE in /usr/lib/*/libssl.so.3 /lib/*/libssl.so.3 /usr/lib64/libssl.so.3 /usr/lib/libssl.so.3 /usr/local/lib/libssl.so.3 /usr/local/lib/*/libssl.so.3; do
+          if [[ -e "$LIBSSL_CANDIDATE" ]]; then LIBSSL3="yes"; break; fi
+        done
+      fi
+      if [[ -n "$LIBSSL3" ]]; then
+        ASSET_CANDIDATES+=("coyote-${ARCH}-unknown-linux-gnu.tar.gz")
       else
-    ASSET_CANDIDATES+=("coyote-aarch64-unknown-linux-musl.tar.gz")
+        log "glibc detected but OpenSSL 3 (libssl.so.3) not found; using musl build"
+      fi
     fi
-else
-  echo "Error: unsupported OS for this installer: $OS" >&2; exit 1
-fi
 
-DL_URLS=$(grep -oE '"browser_download_url":[[:space:]]*"[^"]+"' "$JSON" \
+    ASSET_CANDIDATES+=("coyote-${ARCH}-unknown-linux-musl.tar.gz")
+  else
+    echo "Error: unsupported OS for this installer: $OS" >&2; exit 1
+  fi
+
+  DL_URLS=$(grep -oE '"browser_download_url":[[:space:]]*"[^"]+"' "$JSON" \
     | sed -E 's/.*"browser_download_url":[[:space:]]*"//; s/"$//' \
     || true)
 
-ASSET_NAME=""; ASSET_URL=""
-for candidate in "${ASSET_CANDIDATES[@]}"; do
+  INSTALLED=""
+  TRIED=()
+  ATTEMPT=0
+  for candidate in "${ASSET_CANDIDATES[@]}"; do
+    ASSET_URL=""
     while IFS= read -r url; do
       [[ -z "$url" ]] && continue
       if [[ "$url" == */"$candidate" ]]; then
-      ASSET_NAME="$candidate"
         ASSET_URL="$url"
         break
       fi
     done <<< "$DL_URLS"
-  [[ -n "$ASSET_URL" ]] && break
-done
 
-if [[ -z "$ASSET_URL" ]]; then
-  echo "Error: no matching asset found for ${OS}-${ARCH}. Tried:" >&2
-  for c in "${ASSET_CANDIDATES[@]}"; do echo "  - $c" >&2; done
-  exit 1
-fi
-
-log "Selected asset: $ASSET_NAME"
-log "Download URL: $ASSET_URL"
-
-ARCHIVE="$TMPDIR/asset"
-if [[ "$DL" == "curl" ]]; then
-  curl -fL -H 'User-Agent: coyote-installer' "$ASSET_URL" -o "$ARCHIVE"
-else
-  wget -q --header='User-Agent: coyote-installer' "$ASSET_URL" -O "$ARCHIVE"
-fi
-
-WORK="$TMPDIR/work"; mkdir -p "$WORK"
-EXTRACTED_DIR="$WORK/extracted"; mkdir -p "$EXTRACTED_DIR"
-
-if tar -tf "$ARCHIVE" >/dev/null 2>&1; then
-  tar -xzf "$ARCHIVE" -C "$EXTRACTED_DIR"
-else
-  if command -v unzip >/dev/null 2>&1; then
-  	unzip -q "$ARCHIVE" -d "$EXTRACTED_DIR"
-  else
-  	echo "Error: unknown archive format; install 'unzip'" >&2
-  	exit 1
+    if [[ -z "$ASSET_URL" ]]; then
+      TRIED+=("$candidate: no matching release asset")
+      continue
     fi
-fi
 
-BIN_PATH=""
-while IFS= read -r -d '' f; do
+    ATTEMPT=$((ATTEMPT + 1))
+    WORK="$WORKDIR/attempt-$ATTEMPT"
+    mkdir -p "$WORK"
+
+    log "Selected asset: $candidate"
+    log "Download URL: $ASSET_URL"
+
+    ARCHIVE="$WORK/asset"
+    if [[ "$DL" == "curl" ]]; then
+      if ! curl -fL -H 'User-Agent: coyote-installer' "$ASSET_URL" -o "$ARCHIVE"; then
+        log "Failed to download $candidate; trying next candidate"
+        TRIED+=("$candidate: download failed")
+        continue
+      fi
+    else
+      if ! wget -q --header='User-Agent: coyote-installer' "$ASSET_URL" -O "$ARCHIVE"; then
+        log "Failed to download $candidate; trying next candidate"
+        TRIED+=("$candidate: download failed")
+        continue
+      fi
+    fi
+
+    EXTRACTED_DIR="$WORK/extracted"; mkdir -p "$EXTRACTED_DIR"
+
+    if tar -tf "$ARCHIVE" >/dev/null 2>&1; then
+      if ! tar -xzf "$ARCHIVE" -C "$EXTRACTED_DIR"; then
+        log "Failed to extract $candidate; trying next candidate"
+        TRIED+=("$candidate: extract failed")
+        continue
+      fi
+    else
+      if command -v unzip >/dev/null 2>&1; then
+        if ! unzip -q "$ARCHIVE" -d "$EXTRACTED_DIR"; then
+          log "Failed to extract $candidate; trying next candidate"
+          TRIED+=("$candidate: extract failed")
+          continue
+        fi
+      else
+        log "Unknown archive format for $candidate and 'unzip' is not available; trying next candidate"
+        TRIED+=("$candidate: unknown archive format and 'unzip' unavailable")
+        continue
+      fi
+    fi
+
+    BIN_PATH=""
+    while IFS= read -r -d '' f; do
       base=$(basename "$f")
       if [[ "$base" == "coyote" ]]; then
       	BIN_PATH="$f"
       	break
       fi
-done < <(find "$EXTRACTED_DIR" -type f -print0)
+    done < <(find "$EXTRACTED_DIR" -type f -print0)
 
-if [[ -z "$BIN_PATH" ]]; then
-	echo "Error: could not find 'coyote' binary in the archive" >&2
+    if [[ -z "$BIN_PATH" ]]; then
+      log "Could not find 'coyote' binary in $candidate; trying next candidate"
+      TRIED+=("$candidate: no 'coyote' binary in archive")
+      continue
+    fi
+
+    chmod +x "$BIN_PATH"
+    if ! smoke_test "$BIN_PATH"; then
+      log "Downloaded $candidate but it failed to run on this system; trying next candidate"
+      TRIED+=("$candidate: binary failed to run on this system")
+      continue
+    fi
+
+    install -m 0755 "$BIN_PATH" "${BIN_DIR}/coyote"
+    INSTALLED="$candidate"
+    break
+  done
+
+  if [[ -z "$INSTALLED" ]]; then
+    echo "Error: no usable asset found for ${OS}-${ARCH}. Tried:" >&2
+    for t in "${TRIED[@]}"; do echo "  - $t" >&2; done
     exit 1
-fi
+  fi
 
-chmod +x "$BIN_PATH"
-install -m 0755 "$BIN_PATH" "${BIN_DIR}/coyote"
+  log "Installed: ${BIN_DIR}/coyote"
 
-log "Installed: ${BIN_DIR}/coyote"
-
-case ":$PATH:" in
+  case ":$PATH:" in
     *":${BIN_DIR}:"*) ;;
     *)
       log "Note: ${BIN_DIR} is not in PATH. Add it, e.g.:"
       log "  export PATH=\"${BIN_DIR}:\$PATH\""
       ;;
-esac
+  esac
 
-log "Done. Try: coyote --help"
+  log "Done. Try: coyote --help"
+}
 
+main "$@"

src/acp/server.rs

@@ -1,7 +1,7 @@
 use super::types::{METHOD_NOT_FOUND, PARSE_ERROR, Request, Response};
 use crate::client::call_chat_completions_streaming;
 use crate::config::{Input, RenderMode, RequestContext};
-use crate::function::supervisor::{GuardrailAction, check_pending_agents_guardrail};
+use crate::function::agents::{GuardrailAction, check_pending_tasks_guardrail};
 use crate::utils;
 use crate::utils::AbortSignal;
 use anyhow::Result;
@@ -211,7 +211,7 @@ async fn run_prompt_turn(
             input = input.merge_tool_results(output, tool_results);
             continue;
         }
-        match check_pending_agents_guardrail(ctx) {
+        match check_pending_tasks_guardrail(ctx) {
             GuardrailAction::Inject(prompt) => {
                 input = Input::from_str(ctx, &prompt, None)?;
             }

src/cli/mod.rs

@@ -47,12 +47,13 @@ pub enum McpScopeArg {
 			.args(["sandbox", "fresh"])
 			.multiple(true)
 			.conflicts_with_all([
-				"model", "prompt", "role", "session", "agent", "rag", "rebuild_rag",
+				"model", "temp_role", "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",
+				"install_builtins", "sync_models", "list_models", "list_roles",
 				"list_sessions", "list_agents", "list_rags", "list_macros",
-				"list_skills", "skill", "tail_logs", "completions", "update",
+				"list_skills", "list_bundles", "skill", "tail_logs", "completions",
+				"update", "update_bundle", "uninstall",
 			])
 	),
 	group(
@@ -69,9 +70,9 @@ pub struct Cli {
     /// Select a LLM model
     #[arg(short, long, add = ArgValueCompleter::new(model_completer))]
     pub model: Option<String>,
-    /// Use the system prompt
+    /// Set a temporary role (an ad-hoc system prompt) for this invocation
     #[arg(long)]
-    pub prompt: Option<String>,
+    pub temp_role: Option<String>,
     /// Select a role
     #[arg(short, long, add = ArgValueCompleter::new(role_completer))]
     pub role: Option<String>,
@@ -96,6 +97,9 @@ pub struct Cli {
     /// Disable loading workspace MCP servers from .coyote/mcp.json, .coyote/.mcp.json, or .mcp.json
     #[arg(long)]
     pub no_workspace_mcp: bool,
+    /// Disable loading workspace macros from .coyote/macros
+    #[arg(long)]
+    pub no_workspace_macros: bool,
     /// Disable memory for this invocation
     #[arg(long)]
     pub no_memory: bool,
@@ -172,34 +176,79 @@ pub struct Cli {
     /// List all installed skills
     #[arg(long, help_heading = "List & Discovery")]
     pub list_skills: bool,
+    /// List installed bundles and their drift status
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_bundles: bool,
 
-    /// Reinstall bundled assets, overwriting any local changes
+    /// Install assets from a remote git repository (a URL or <owner>/<repo> shorthand, optionally suffixed with #<ref>), or update an already-installed bundle by name
     #[arg(
         long,
-        value_name = "CATEGORY",
-        value_enum,
+        value_name = "GIT_URL|OWNER/REPO|NAME",
+        conflicts_with_all = ["install_builtins", "update_bundle", "uninstall"],
         help_heading = "Installation & Updates"
     )]
-    pub install: Option<AssetCategory>,
-    /// Install assets from a remote git repository (URL may be suffixed with #<ref>)
-    #[arg(long, value_name = "GIT_URL", help_heading = "Installation & Updates")]
-    pub install_from: Option<String>,
-    /// Restrict --install-from to a single asset category
+    pub install: Option<String>,
+    /// Git host used to expand <owner>/<repo> shorthand values passed to --install (also forces the value to be treated as a source when it matches an installed bundle name)
+    #[arg(
+        long,
+        value_name = "HOST",
+        requires = "install",
+        conflicts_with_all = ["install_builtins", "update_bundle", "uninstall"],
+        help_heading = "Installation & Updates"
+    )]
+    pub git_host: Option<String>,
+    /// Reinstall bundled assets for a category (asks before overwriting your local changes)
     #[arg(
         long,
         value_name = "CATEGORY",
         value_enum,
-        requires = "install_from",
+        conflicts_with_all = ["update_bundle", "uninstall"],
+        help_heading = "Installation & Updates"
+    )]
+    pub install_builtins: Option<AssetCategory>,
+    /// Restrict a remote install to a single asset category
+    #[arg(
+        long,
+        value_name = "CATEGORY",
+        value_enum,
+        requires = "install",
+        conflicts_with_all = ["install_builtins", "update_bundle", "uninstall"],
         help_heading = "Installation & Updates"
     )]
     pub filter: Option<InstallFilter>,
-    /// Overwrite all conflicts without prompting (used with --install-from)
+    /// Overwrite all conflicts without prompting (remote installs only)
     #[arg(
         long,
-        requires = "install_from",
+        requires = "install",
+        conflicts_with_all = ["install_builtins", "update_bundle", "uninstall"],
         help_heading = "Installation & Updates"
     )]
     pub install_force: bool,
+    /// Update an installed bundle from its recorded source (NAME may be suffixed with #<ref> to move a pin)
+    #[arg(
+        long,
+        value_name = "NAME",
+        group = "yes_scope",
+        conflicts_with_all = ["uninstall"],
+        help_heading = "Installation & Updates"
+    )]
+    pub update_bundle: Option<String>,
+    /// Uninstall a bundle: delete its owned files and remove its mcp.json entries
+    #[arg(
+        long,
+        value_name = "NAME",
+        group = "yes_scope",
+        help_heading = "Installation & Updates"
+    )]
+    pub uninstall: Option<String>,
+    /// Proceed without prompts for --uninstall and --update-bundle (locally modified items are always kept)
+    #[arg(
+        long,
+        requires = "yes_scope",
+        conflicts_with_all = ["install", "install_builtins"],
+        help_heading = "Installation & Updates"
+    )]
+    pub yes: bool,
     /// Sync models updates
     #[arg(long, help_heading = "Installation & Updates")]
     pub sync_models: bool,
@@ -266,7 +315,7 @@ pub struct Cli {
     /// URL for http/sse MCP server (used with --mcp-add)
     #[arg(long, value_name = "URL", help_heading = "MCP Servers")]
     pub url: Option<String>,
-    /// Scope for MCP config: user (~/.config/coyote/functions/mcp.json) or workspace (./.coyote/mcp.json). Default: user
+    /// Scope for MCP config: user (~/.config/coyote/mcp.json) or workspace (./.coyote/mcp.json). Default: user
     #[arg(long, value_enum, value_name = "SCOPE", help_heading = "MCP Servers")]
     pub scope: Option<McpScopeArg>,
     /// Environment variable for stdio MCP server (repeatable): --env KEY=VALUE
@@ -492,6 +541,7 @@ mod tests {
         assert!(parse(&["--list-rags"]).list_rags);
         assert!(parse(&["--list-macros"]).list_macros);
         assert!(parse(&["--list-skills"]).list_skills);
+        assert!(parse(&["--list-bundles"]).list_bundles);
     }
 
     #[test]
@@ -500,6 +550,160 @@ mod tests {
         assert!(parse(&[]).skill.is_empty());
     }
 
+    #[test]
+    fn parse_update_bundle_flag_takes_name() {
+        assert_eq!(
+            parse(&["--update-bundle", "foo"]).update_bundle.as_deref(),
+            Some("foo")
+        );
+    }
+
+    #[test]
+    fn parse_uninstall_flag_takes_name() {
+        assert_eq!(
+            parse(&["--uninstall", "foo"]).uninstall.as_deref(),
+            Some("foo")
+        );
+        assert!(!parse(&["--uninstall", "foo"]).yes);
+    }
+
+    #[test]
+    fn parse_yes_flag_requires_uninstall_or_update_bundle() {
+        assert!(parse(&["--uninstall", "foo", "--yes"]).yes);
+        assert!(parse(&["--update-bundle", "foo", "--yes"]).yes);
+        assert!(Cli::try_parse_from(["coyote", "--yes"]).is_err());
+    }
+
+    #[test]
+    fn parse_install_flag_takes_url_or_name() {
+        assert_eq!(
+            parse(&["--install", "https://github.com/x/y"])
+                .install
+                .as_deref(),
+            Some("https://github.com/x/y")
+        );
+    }
+
+    #[test]
+    fn parse_install_builtins_flag_takes_category() {
+        assert_eq!(
+            parse(&["--install-builtins", "agents"]).install_builtins,
+            Some(AssetCategory::Agents)
+        );
+        assert_eq!(
+            parse(&["--install-builtins", "mcp-config"]).install_builtins,
+            Some(AssetCategory::McpConfig)
+        );
+        assert_eq!(
+            parse(&["--install-builtins", "mcp_config"]).install_builtins,
+            Some(AssetCategory::McpConfig)
+        );
+    }
+
+    #[test]
+    fn mcp_config_canonical_value_is_kebab_case() {
+        use clap::ValueEnum;
+
+        let category = AssetCategory::McpConfig.to_possible_value().unwrap();
+        assert_eq!(category.get_name(), "mcp-config");
+        assert!(category.get_name_and_aliases().any(|n| n == "mcp_config"));
+        assert!(AssetCategory::NAMES.contains(&"mcp-config"));
+        assert!(!AssetCategory::NAMES.contains(&"mcp_config"));
+
+        let filter = InstallFilter::McpConfig.to_possible_value().unwrap();
+        assert_eq!(filter.get_name(), "mcp-config");
+        assert!(filter.get_name_and_aliases().any(|n| n == "mcp_config"));
+        assert!(InstallFilter::NAMES.contains(&"mcp-config"));
+        assert!(!InstallFilter::NAMES.contains(&"mcp_config"));
+    }
+
+    #[test]
+    fn parse_install_builtins_conflicts_with_install() {
+        assert!(
+            Cli::try_parse_from(["coyote", "--install-builtins", "agents", "--install", "x"])
+                .is_err()
+        );
+    }
+
+    #[test]
+    fn parse_lifecycle_flags_are_mutually_exclusive() {
+        assert!(Cli::try_parse_from(["coyote", "--install", "x", "--uninstall", "y"]).is_err());
+        assert!(
+            Cli::try_parse_from(["coyote", "--update-bundle", "x", "--uninstall", "y"]).is_err()
+        );
+        assert!(
+            Cli::try_parse_from(["coyote", "--install-builtins", "agents", "--uninstall", "y"])
+                .is_err()
+        );
+        assert!(Cli::try_parse_from(["coyote", "--install", "x", "--update-bundle", "y"]).is_err());
+    }
+
+    #[test]
+    fn parse_companion_flags_conflict_with_other_lifecycle_actions() {
+        assert!(
+            Cli::try_parse_from(["coyote", "--update-bundle", "x", "--filter", "agents"]).is_err()
+        );
+        assert!(Cli::try_parse_from(["coyote", "--uninstall", "x", "--install-force"]).is_err());
+        assert!(Cli::try_parse_from(["coyote", "--install", "x", "--yes"]).is_err());
+    }
+
+    #[test]
+    fn parse_filter_requires_install() {
+        assert!(Cli::try_parse_from(["coyote", "--filter", "agents"]).is_err());
+        assert_eq!(
+            parse(&["--install", "https://github.com/x/y", "--filter", "agents"]).filter,
+            Some(InstallFilter::Agents)
+        );
+        assert_eq!(
+            parse(&[
+                "--install",
+                "https://github.com/x/y",
+                "--filter",
+                "mcp-config"
+            ])
+            .filter,
+            Some(InstallFilter::McpConfig)
+        );
+        assert_eq!(
+            parse(&[
+                "--install",
+                "https://github.com/x/y",
+                "--filter",
+                "mcp_config"
+            ])
+            .filter,
+            Some(InstallFilter::McpConfig)
+        );
+    }
+
+    #[test]
+    fn parse_install_force_requires_install() {
+        assert!(Cli::try_parse_from(["coyote", "--install-force"]).is_err());
+        assert!(parse(&["--install", "https://github.com/x/y", "--install-force"]).install_force);
+    }
+
+    #[test]
+    fn parse_git_host_requires_install() {
+        assert!(Cli::try_parse_from(["coyote", "--git-host", "git.x.com"]).is_err());
+        assert!(
+            Cli::try_parse_from(["coyote", "--git-host", "gitlab.com", "--update-bundle", "x"])
+                .is_err()
+        );
+        assert_eq!(
+            parse(&["--install", "someuser/omc", "--git-host", "git.x.com"])
+                .git_host
+                .as_deref(),
+            Some("git.x.com")
+        );
+    }
+
+    #[test]
+    fn help_shows_install_builtins() {
+        use clap::CommandFactory;
+        let help = Cli::command().render_long_help().to_string();
+        assert!(help.contains("--install-builtins"));
+    }
+
     #[test]
     fn parse_multiple_skill_flags_preserves_order() {
         assert_eq!(
@@ -542,9 +746,9 @@ mod tests {
     }
 
     #[test]
-    fn parse_prompt_flag() {
-        let cli = parse(&["--prompt", "be a pirate"]);
-        assert_eq!(cli.prompt, Some("be a pirate".to_string()));
+    fn parse_temp_role_flag() {
+        let cli = parse(&["--temp-role", "be a pirate"]);
+        assert_eq!(cli.temp_role, Some("be a pirate".to_string()));
     }
 
     #[test]

src/client/access_token.rs

@@ -2,6 +2,7 @@ use anyhow::{Result, anyhow};
 use chrono::Utc;
 use indexmap::IndexMap;
 use parking_lot::RwLock;
+use std::collections::HashMap;
 use std::sync::LazyLock;
 
 type AccessTokenEntry = (String, i64, Option<String>);
@@ -9,6 +10,12 @@ type AccessTokenEntry = (String, i64, Option<String>);
 static ACCESS_TOKENS: LazyLock<RwLock<IndexMap<String, AccessTokenEntry>>> =
     LazyLock::new(|| RwLock::new(IndexMap::new()));
 
+/// Tokens a provider rejected (401) despite being locally unexpired.
+/// Maps client name → the exact rejected token so a concurrently-refreshed
+/// different token is never distrusted by mistake.
+static REJECTED_TOKENS: LazyLock<RwLock<HashMap<String, String>>> =
+    LazyLock::new(|| RwLock::new(HashMap::new()));
+
 pub fn get_access_token(client_name: &str) -> Result<String> {
     ACCESS_TOKENS
         .read()
@@ -30,7 +37,7 @@ pub fn is_valid_access_token(client_name: &str) -> bool {
         Some(v) => v,
         None => return false,
     };
-    !token.is_empty() && Utc::now().timestamp() < *expires_at
+    !token.is_empty() && Utc::now().timestamp() < *expires_at && !is_rejected(client_name, token)
 }
 
 pub fn set_access_token(
@@ -45,3 +52,111 @@ pub fn set_access_token(
     entry.1 = expires_at;
     entry.2 = account_id;
 }
+
+/// Compare-and-invalidate a provider-rejected token.
+///
+/// Only if the currently-cached token EQUALS `rejected` is the cache entry
+/// removed and the rejection marker recorded; a concurrently-refreshed
+/// different token is left untouched and no marker is set.
+///
+/// Returns true if a cache entry existed for this client at all (whether or
+/// not it matched `rejected`) — i.e. the client is token-authed and a retry
+/// after refresh is worthwhile. Returns false when there is no entry
+/// (API-key clients).
+pub fn distrust_access_token(client_name: &str, rejected: &str) -> bool {
+    let mut access_tokens = ACCESS_TOKENS.write();
+    let (token, _, _) = match access_tokens.get(client_name) {
+        Some(v) => v,
+        None => return false,
+    };
+    if token == rejected {
+        access_tokens.shift_remove(client_name);
+        REJECTED_TOKENS
+            .write()
+            .insert(client_name.to_string(), rejected.to_string());
+    }
+    true
+}
+
+pub fn is_rejected(client_name: &str, token: &str) -> bool {
+    REJECTED_TOKENS
+        .read()
+        .get(client_name)
+        .is_some_and(|rejected| rejected == token)
+}
+
+pub fn clear_rejected(client_name: &str) {
+    REJECTED_TOKENS.write().remove(client_name);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn distrust_removes_matching_token_and_sets_marker() {
+        let client = "distrust-match-test";
+        set_access_token(client, "at-1".into(), Utc::now().timestamp() + 3600, None);
+
+        assert!(distrust_access_token(client, "at-1"));
+
+        assert!(get_access_token(client).is_err(), "cache entry not removed");
+        assert!(is_rejected(client, "at-1"), "marker not set");
+    }
+
+    #[test]
+    fn distrust_keeps_differing_token_and_skips_marker() {
+        let client = "distrust-differ-test";
+        set_access_token(client, "at-new".into(), Utc::now().timestamp() + 3600, None);
+
+        assert!(distrust_access_token(client, "at-old"));
+
+        assert_eq!(get_access_token(client).unwrap(), "at-new");
+        assert!(!is_rejected(client, "at-old"), "marker set for stale token");
+    }
+
+    #[test]
+    fn distrust_returns_false_without_cache_entry() {
+        let client = "distrust-missing-test";
+
+        assert!(!distrust_access_token(client, "at-1"));
+        assert!(!is_rejected(client, "at-1"));
+    }
+
+    #[test]
+    fn is_valid_access_token_false_for_rejected_token() {
+        let client = "rejected-valid-test";
+        set_access_token(client, "at-1".into(), Utc::now().timestamp() + 3600, None);
+        assert!(is_valid_access_token(client));
+
+        distrust_access_token(client, "at-1");
+        // A concurrent in-flight prepare re-caches the rejected file token
+        // between mark and refresh; it must still be treated as invalid.
+        set_access_token(client, "at-1".into(), Utc::now().timestamp() + 3600, None);
+
+        assert!(!is_valid_access_token(client));
+    }
+
+    #[test]
+    fn clear_rejected_clears_marker_and_clients_are_isolated() {
+        let client_a = "rejected-isolation-a";
+        let client_b = "rejected-isolation-b";
+        set_access_token(client_a, "at-1".into(), Utc::now().timestamp() + 3600, None);
+        distrust_access_token(client_a, "at-1");
+
+        assert!(is_rejected(client_a, "at-1"));
+        assert!(
+            !is_rejected(client_b, "at-1"),
+            "marker leaked across clients"
+        );
+
+        clear_rejected(client_b);
+        assert!(
+            is_rejected(client_a, "at-1"),
+            "wrong client's marker cleared"
+        );
+
+        clear_rejected(client_a);
+        assert!(!is_rejected(client_a, "at-1"));
+    }
+}

src/client/common.rs

@@ -1,5 +1,6 @@
 use super::*;
 
+use super::access_token::{distrust_access_token, get_access_token};
 use crate::config::{RenderMode, paths};
 use crate::{
     config::{AppConfig, Input, RequestContext},
@@ -56,12 +57,16 @@ pub trait Client: Sync + Send {
         let mut builder = ReqwestClient::builder();
         let extra = self.extra_config();
         let timeout = extra.and_then(|v| v.connect_timeout).unwrap_or(10);
+        let read_timeout = extra.and_then(|v| v.read_timeout).unwrap_or(300);
         if let Some(proxy) = extra.and_then(|v| v.proxy.as_deref()) {
             builder = set_proxy(builder, proxy)?;
         }
         if let Some(user_agent) = self.app_config().user_agent.as_ref() {
             builder = builder.user_agent(user_agent);
         }
+        if read_timeout > 0 {
+            builder = builder.read_timeout(Duration::from_secs(read_timeout));
+        }
         let client = builder
             .connect_timeout(Duration::from_secs(timeout))
             .build()
@@ -69,6 +74,11 @@ pub trait Client: Sync + Send {
         Ok(client)
     }
 
+    /// On a 401 the cached access token is distrusted and the call retried
+    /// exactly once; the retry re-runs the per-client prepare step, which
+    /// sees the rejection marker, force-refreshes the token, and rebuilds
+    /// the whole request. A second 401 propagates the original error; any
+    /// other retry failure propagates as-is.
     async fn chat_completions(&self, input: Input) -> Result<ChatCompletionsOutput> {
         if self.app_config().dry_run {
             let content = input.echo_messages();
@@ -76,11 +86,30 @@ pub trait Client: Sync + Send {
         }
         let client = self.build_client()?;
         let data = input.prepare_completion_data(self.model(), false)?;
-        self.chat_completions_inner(&client, data)
-            .await
-            .with_context(|| "Failed to call chat-completions api")
+        let err = match self.chat_completions_inner(&client, data).await {
+            Ok(output) => return Ok(output),
+            Err(err) => err,
+        };
+        let ret = if should_retry_auth(&err, self.name()) {
+            debug!(
+                "provider '{}' rejected access token (401); refreshing and retrying once",
+                self.name()
+            );
+            let data = input.prepare_completion_data(self.model(), false)?;
+            match self.chat_completions_inner(&client, data).await {
+                Err(retry_err) if is_auth_error(&retry_err) => Err(err),
+                ret => ret,
+            }
+        } else {
+            Err(err)
+        };
+        ret.with_context(|| "Failed to call chat-completions api")
     }
 
+    /// Same retry-once-on-401 semantics as [`Self::chat_completions`], but
+    /// only while the handler has received nothing yet: retrying after
+    /// partial output has streamed would render it to the user twice. The
+    /// retry lives inside the same `select!` arm so abort stays responsive.
     async fn chat_completions_streaming(
         &self,
         input: &Input,
@@ -97,7 +126,22 @@ pub trait Client: Sync + Send {
                 }
                 let client = self.build_client()?;
                 let data = input.prepare_completion_data(self.model(), true)?;
-                self.chat_completions_streaming_inner(&client, handler, data).await
+                let err = match self.chat_completions_streaming_inner(&client, handler, data).await {
+                    Ok(()) => return Ok(()),
+                    Err(err) => err,
+                };
+                if handler.has_received_content() || !should_retry_auth(&err, self.name()) {
+                    return Err(err);
+                }
+                debug!(
+                    "provider '{}' rejected access token (401); refreshing and retrying once",
+                    self.name()
+                );
+                let data = input.prepare_completion_data(self.model(), true)?;
+                match self.chat_completions_streaming_inner(&client, handler, data).await {
+                    Err(retry_err) if is_auth_error(&retry_err) => Err(err),
+                    ret => ret,
+                }
             } => {
                 handler.done();
                 ret.with_context(|| "Failed to call chat-completions api")
@@ -109,11 +153,27 @@ pub trait Client: Sync + Send {
         }
     }
 
+    /// Same retry-once-on-401 semantics as [`Self::chat_completions`]
+    /// (gemini OAuth embeddings route here).
     async fn embeddings(&self, data: &EmbeddingsData) -> Result<Vec<Vec<f32>>> {
         let client = self.build_client()?;
-        self.embeddings_inner(&client, data)
-            .await
-            .context("Failed to call embeddings api")
+        let err = match self.embeddings_inner(&client, data).await {
+            Ok(output) => return Ok(output),
+            Err(err) => err,
+        };
+        let ret = if should_retry_auth(&err, self.name()) {
+            debug!(
+                "provider '{}' rejected access token (401); refreshing and retrying once",
+                self.name()
+            );
+            match self.embeddings_inner(&client, data).await {
+                Err(retry_err) if is_auth_error(&retry_err) => Err(err),
+                ret => ret,
+            }
+        } else {
+            Err(err)
+        };
+        ret.context("Failed to call embeddings api")
     }
 
     async fn rerank(&self, data: &RerankData) -> Result<RerankOutput> {
@@ -205,6 +265,7 @@ impl Default for ClientConfig {
 pub struct ExtraConfig {
     pub proxy: Option<String>,
     pub connect_timeout: Option<u64>,
+    pub read_timeout: Option<u64>,
 }
 
 #[derive(Debug, Clone, Deserialize, Default)]
@@ -557,46 +618,90 @@ pub async fn noop_rerank(_builder: RequestBuilder, _model: &Model) -> Result<Rer
     bail!("The client doesn't support rerank api")
 }
 
+#[derive(Debug)]
+pub struct ApiStatusError {
+    pub status: u16,
+    pub message: String,
+}
+
+impl std::fmt::Display for ApiStatusError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message)
+    }
+}
+
+impl std::error::Error for ApiStatusError {}
+
+/// True when the error chain bottoms out in an [`ApiStatusError`] with
+/// status 401 EXACTLY. 403 (entitlement) and 429 (rate limit) are never
+/// auth failures, and message text is never inspected.
+fn is_auth_error(err: &anyhow::Error) -> bool {
+    err.downcast_ref::<ApiStatusError>()
+        .is_some_and(|api_err| api_err.status == 401)
+}
+
+/// Decides whether a 401 from `client_name` warrants a single retry after a
+/// forced token refresh: the error must be a 401 [`ApiStatusError`], and the
+/// client must have a cached access token to distrust (API-key clients have
+/// none and never retry). Distrusting marks the exact rejected token so the
+/// retry's prepare step force-refreshes it. There is deliberately no backoff:
+/// the blast radius is bounded at one extra request per user-visible call.
+///
+/// Note: vertexai shares the ACCESS_TOKENS cache, so a 401 there also
+/// triggers distrust+retry — deliberate.
+fn should_retry_auth(err: &anyhow::Error, client_name: &str) -> bool {
+    if !is_auth_error(err) {
+        return false;
+    }
+    let Ok(token) = get_access_token(client_name) else {
+        return false;
+    };
+    distrust_access_token(client_name, &token)
+}
+
 pub fn catch_error(data: &Value, status: u16) -> Result<()> {
     if (200..300).contains(&status) {
         return Ok(());
     }
     debug!("Invalid response, status: {status}, data: {data}");
+    let api_error = |message: String| anyhow::Error::new(ApiStatusError { status, message });
     if let Some(error) = data["error"].as_object() {
         if let (Some(typ), Some(message)) = (
             json_str_from_map(error, "type"),
             json_str_from_map(error, "message"),
         ) {
-            bail!("{message} (type: {typ})");
+            return Err(api_error(format!("{message} (type: {typ})")));
         } else if let (Some(typ), Some(message)) = (
             json_str_from_map(error, "code"),
             json_str_from_map(error, "message"),
         ) {
-            bail!("{message} (code: {typ})");
+            return Err(api_error(format!("{message} (code: {typ})")));
         }
     } else if let Some(error) = data["errors"][0].as_object() {
         if let (Some(code), Some(message)) = (
             error.get("code").and_then(|v| v.as_u64()),
             json_str_from_map(error, "message"),
         ) {
-            bail!("{message} (status: {code})")
+            return Err(api_error(format!("{message} (status: {code})")));
         }
     } else if let Some(error) = data[0]["error"].as_object() {
         if let (Some(status), Some(message)) = (
             json_str_from_map(error, "status"),
             json_str_from_map(error, "message"),
         ) {
-            bail!("{message} (status: {status})")
+            return Err(api_error(format!("{message} (status: {status})")));
         }
     } else if let (Some(detail), Some(status)) = (data["detail"].as_str(), data["status"].as_i64())
     {
-        bail!("{detail} (status: {status})");
+        return Err(api_error(format!("{detail} (status: {status})")));
     } else if let Some(error) = data["error"].as_str() {
-        bail!("{error}");
+        return Err(api_error(error.to_string()));
     } else if let Some(message) = data["message"].as_str() {
-        bail!("{message}");
+        return Err(api_error(message.to_string()));
     }
-    bail!("Invalid response data: {data} (status: {status})");
+    Err(api_error(format!(
+        "Invalid response data: {data} (status: {status})"
+    )))
 }
 
 pub fn json_str_from_map<'a>(
@@ -737,3 +842,172 @@ fn prompt_input_string(desc: &str, required: bool, help_message: Option<&str>) -
     let text = text.prompt()?;
     Ok(text)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use super::super::access_token::{is_rejected, set_access_token};
+
+    fn catch_error_message(data: &Value, status: u16) -> String {
+        catch_error(data, status).unwrap_err().to_string()
+    }
+
+    #[test]
+    fn test_catch_error_display_json_with_type() {
+        let data = json!({"error": {"type": "invalid_request_error", "message": "Bad request"}});
+        assert_eq!(
+            catch_error_message(&data, 400),
+            "Bad request (type: invalid_request_error)"
+        );
+    }
+
+    #[test]
+    fn test_catch_error_display_json_with_code() {
+        let data = json!({"error": {"code": "rate_limited", "message": "Too many requests"}});
+        assert_eq!(
+            catch_error_message(&data, 429),
+            "Too many requests (code: rate_limited)"
+        );
+    }
+
+    #[test]
+    fn test_catch_error_display_errors_array() {
+        let data = json!({"errors": [{"code": 7000, "message": "No route"}]});
+        assert_eq!(catch_error_message(&data, 404), "No route (status: 7000)");
+    }
+
+    #[test]
+    fn test_catch_error_display_array_error_status() {
+        let data = json!([{"error": {"status": "PERMISSION_DENIED", "message": "Denied"}}]);
+        assert_eq!(
+            catch_error_message(&data, 403),
+            "Denied (status: PERMISSION_DENIED)"
+        );
+    }
+
+    #[test]
+    fn test_catch_error_display_detail_status() {
+        let data = json!({"detail": "Not found", "status": 404});
+        assert_eq!(catch_error_message(&data, 404), "Not found (status: 404)");
+    }
+
+    #[test]
+    fn test_catch_error_display_error_string() {
+        let data = json!({"error": "Something went wrong"});
+        assert_eq!(catch_error_message(&data, 500), "Something went wrong");
+    }
+
+    #[test]
+    fn test_catch_error_display_message_string() {
+        let data = json!({"message": "Unauthorized"});
+        assert_eq!(catch_error_message(&data, 401), "Unauthorized");
+    }
+
+    #[test]
+    fn test_catch_error_display_fallback() {
+        let data = json!({"unexpected": true});
+        assert_eq!(
+            catch_error_message(&data, 500),
+            format!("Invalid response data: {data} (status: 500)")
+        );
+    }
+
+    #[test]
+    fn test_catch_error_ok_on_success_status() {
+        let data = json!({"error": {"type": "x", "message": "y"}});
+        assert!(catch_error(&data, 200).is_ok());
+        assert!(catch_error(&data, 299).is_ok());
+    }
+
+    #[test]
+    fn test_catch_error_downcast_through_context_chain() {
+        let data = json!({"error": {"type": "authentication_error", "message": "Invalid key"}});
+        let err = catch_error(&data, 401)
+            .context("Failed to call chat-completions api")
+            .unwrap_err();
+        let api_err = err
+            .downcast_ref::<ApiStatusError>()
+            .expect("should downcast through context chain");
+        assert_eq!(api_err.status, 401);
+        assert_eq!(api_err.message, "Invalid key (type: authentication_error)");
+    }
+
+    #[test]
+    fn test_catch_error_preserves_status() {
+        let data = json!({"message": "Unauthorized"});
+        let err = catch_error(&data, 401).unwrap_err();
+        assert_eq!(err.downcast_ref::<ApiStatusError>().unwrap().status, 401);
+
+        let data = json!({"detail": "Rate limited", "status": 429});
+        let err = catch_error(&data, 429).unwrap_err();
+        assert_eq!(err.downcast_ref::<ApiStatusError>().unwrap().status, 429);
+
+        // The struct carries the outer HTTP status even when the body embeds another code
+        let data = json!({"errors": [{"code": 7000, "message": "No route"}]});
+        let err = catch_error(&data, 429).unwrap_err();
+        assert_eq!(err.downcast_ref::<ApiStatusError>().unwrap().status, 429);
+    }
+
+    /// Wrapped in `.context(...)` so every test below proves the downcast
+    /// works through an anyhow context chain, as in the trait methods.
+    fn api_status_error(status: u16) -> anyhow::Error {
+        anyhow::Error::new(ApiStatusError {
+            status,
+            message: format!("error (status: {status})"),
+        })
+        .context("Failed to call chat-completions api")
+    }
+
+    fn cache_token(client: &str, token: &str) {
+        set_access_token(
+            client,
+            token.into(),
+            chrono::Utc::now().timestamp() + 3600,
+            None,
+        );
+    }
+
+    #[test]
+    fn test_should_retry_auth_401_with_cached_token() {
+        let client = "should-retry-auth-401";
+        cache_token(client, "at-1");
+
+        assert!(should_retry_auth(&api_status_error(401), client));
+        assert!(is_rejected(client, "at-1"), "rejected marker not set");
+    }
+
+    #[test]
+    fn test_should_retry_auth_non_401_statuses() {
+        let client = "should-retry-auth-non-401";
+        cache_token(client, "at-1");
+
+        for status in [403, 429, 500] {
+            assert!(
+                !should_retry_auth(&api_status_error(status), client),
+                "retried on {status}"
+            );
+        }
+        assert_eq!(get_access_token(client).unwrap(), "at-1");
+        assert!(!is_rejected(client, "at-1"), "marker set without a 401");
+    }
+
+    #[test]
+    fn test_should_retry_auth_non_api_status_error() {
+        let client = "should-retry-auth-non-api";
+        cache_token(client, "at-1");
+
+        let err = anyhow::anyhow!("connection reset").context("Failed to call embeddings api");
+        assert!(!should_retry_auth(&err, client));
+        assert_eq!(get_access_token(client).unwrap(), "at-1");
+        assert!(!is_rejected(client, "at-1"));
+    }
+
+    #[test]
+    fn test_should_retry_auth_401_without_cached_token() {
+        let client = "should-retry-auth-no-token";
+
+        assert!(!should_retry_auth(&api_status_error(401), client));
+        assert!(!is_rejected(client, "at-1"));
+    }
+}

src/client/oauth.rs

@@ -1,14 +1,14 @@
-use super::access_token::{is_valid_access_token, set_access_token};
+use super::access_token::{clear_rejected, is_rejected, is_valid_access_token, set_access_token};
 use super::openai_compatible_oauth::OpenAICompatibleOAuthProvider;
 use super::{ClientConfig, ProviderModels};
 use crate::config::paths;
-use anyhow::{Context, Result, anyhow, bail};
+use anyhow::{Context, Error, Result, anyhow, bail};
 use base64::Engine;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
 use chrono::Utc;
 use indexmap::IndexMap;
 use inquire::Text;
-use reqwest::{Client as ReqwestClient, RequestBuilder};
+use reqwest::{Client as ReqwestClient, RequestBuilder, StatusCode};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use sha2::{Digest, Sha256};
@@ -16,6 +16,10 @@ use std::collections::HashMap;
 use std::fs;
 use std::io::{BufRead, BufReader, Write};
 use std::net::TcpListener;
+use std::path::PathBuf;
+use std::sync::{Arc, OnceLock};
+use std::time::Duration;
+use tokio::sync;
 use url::Url;
 use uuid::Uuid;
 
@@ -197,10 +201,20 @@ pub struct OAuthTokens {
     pub account_id: Option<String>,
 }
 
+const TOKEN_ENDPOINT_TIMEOUT: Duration = Duration::from_secs(30);
+
 pub async fn run_oauth_flow(provider: &dyn OAuthProvider, client_name: &str) -> Result<()> {
     match provider.flow() {
         OAuthFlow::Pkce => run_pkce_flow(provider, client_name).await,
-        OAuthFlow::ClientCredentials => run_client_credentials_flow(provider, client_name).await,
+        OAuthFlow::ClientCredentials => {
+            run_client_credentials_flow(provider, client_name).await?;
+            println!(
+                "Successfully authenticated client '{}' with {} via OAuth (client_credentials). Tokens saved.",
+                client_name,
+                provider.provider_name()
+            );
+            Ok(())
+        }
         OAuthFlow::DeviceCode => run_device_code_flow(provider, client_name).await,
     }
 }
@@ -301,12 +315,20 @@ async fn run_pkce_flow(provider: &dyn OAuthProvider, client_name: &str) -> Resul
 
     let access_token = response["access_token"]
         .as_str()
-        .ok_or_else(|| anyhow!("Missing access_token in response: {response}"))?
+        .ok_or_else(|| {
+            anyhow!(
+                "Missing access_token in response (keys: {})",
+                token_response_keys(&response)
+            )
+        })?
         .to_string();
     let refresh_token = response["refresh_token"].as_str().map(|s| s.to_string());
-    let expires_in = response["expires_in"]
-        .as_i64()
-        .ok_or_else(|| anyhow!("Missing expires_in in response: {response}"))?;
+    let expires_in = response["expires_in"].as_i64().ok_or_else(|| {
+        anyhow!(
+            "Missing expires_in in response (keys: {})",
+            token_response_keys(&response)
+        )
+    })?;
 
     let expires_at = Utc::now().timestamp() + expires_in;
 
@@ -334,7 +356,9 @@ async fn run_client_credentials_flow(
     provider: &dyn OAuthProvider,
     client_name: &str,
 ) -> Result<()> {
-    let client = ReqwestClient::new();
+    let client = ReqwestClient::builder()
+        .timeout(TOKEN_ENDPOINT_TIMEOUT)
+        .build()?;
     let scopes = provider.scopes();
     let mut params: Vec<(&str, &str)> = vec![
         ("grant_type", "client_credentials"),
@@ -349,11 +373,19 @@ async fn run_client_credentials_flow(
 
     let access_token = response["access_token"]
         .as_str()
-        .ok_or_else(|| anyhow!("Missing access_token in client_credentials response: {response}"))?
+        .ok_or_else(|| {
+            anyhow!(
+                "Missing access_token in client_credentials response (keys: {})",
+                token_response_keys(&response)
+            )
+        })?
         .to_string();
-    let expires_in = response["expires_in"]
-        .as_i64()
-        .ok_or_else(|| anyhow!("Missing expires_in in client_credentials response: {response}"))?;
+    let expires_in = response["expires_in"].as_i64().ok_or_else(|| {
+        anyhow!(
+            "Missing expires_in in client_credentials response (keys: {})",
+            token_response_keys(&response)
+        )
+    })?;
     let expires_at = Utc::now().timestamp() + expires_in;
 
     let tokens = OAuthTokens {
@@ -363,11 +395,6 @@ async fn run_client_credentials_flow(
         account_id: provider.extract_account_id(&response),
     };
     save_oauth_tokens(client_name, &tokens)?;
-    println!(
-        "Successfully authenticated client '{}' with {} via OAuth (client_credentials). Tokens saved.",
-        client_name,
-        provider.provider_name()
-    );
 
     Ok(())
 }
@@ -417,19 +444,28 @@ async fn run_device_code_flow(provider: &dyn OAuthProvider, client_name: &str) -
     let device_code = device_response["device_code"]
         .as_str()
         .ok_or_else(|| {
-            anyhow!("Missing device_code in device authorization response: {device_response}")
+            anyhow!(
+                "Missing device_code in device authorization response (keys: {})",
+                token_response_keys(&device_response)
+            )
         })?
         .to_string();
     let user_code = device_response["user_code"]
         .as_str()
         .ok_or_else(|| {
-            anyhow!("Missing user_code in device authorization response: {device_response}")
+            anyhow!(
+                "Missing user_code in device authorization response (keys: {})",
+                token_response_keys(&device_response)
+            )
         })?
         .to_string();
     let verification_uri = device_response["verification_uri"]
         .as_str()
         .ok_or_else(|| {
-            anyhow!("Missing verification_uri in device authorization response: {device_response}")
+            anyhow!(
+                "Missing verification_uri in device authorization response (keys: {})",
+                token_response_keys(&device_response)
+            )
         })?
         .to_string();
     let verification_uri_complete = device_response["verification_uri_complete"]
@@ -551,10 +587,76 @@ fn save_oauth_tokens(client_name: &str, tokens: &OAuthTokens) -> Result<()> {
         fs::create_dir_all(parent)?;
     }
     let json = serde_json::to_string_pretty(tokens)?;
-    fs::write(path, json)?;
+    // Write-then-rename so a crash mid-write never truncates the live token file.
+    let mut tmp = path.clone().into_os_string();
+    tmp.push(".tmp");
+    let tmp = PathBuf::from(tmp);
+    // Tokens are live credentials: create the file owner-only, not umask-default.
+    let mut options = fs::OpenOptions::new();
+    options.write(true).create(true).truncate(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    options.open(&tmp)?.write_all(json.as_bytes())?;
+    fs::rename(&tmp, &path)?;
     Ok(())
 }
 
+pub(crate) fn token_response_keys(response: &Value) -> String {
+    match response.as_object() {
+        Some(map) => {
+            let keys: Vec<&str> = map.keys().map(String::as_str).collect();
+            format!("[{}]", keys.join(", "))
+        }
+        None => "<non-object response>".to_string(),
+    }
+}
+
+fn parse_refresh_response(
+    status: StatusCode,
+    response: &Value,
+    previous_refresh_token: Option<&str>,
+) -> Result<(String, Option<String>, i64)> {
+    if let Some(error) = response["error"].as_str() {
+        let description = response["error_description"]
+            .as_str()
+            .unwrap_or("no description");
+        if matches!(error, "invalid_grant" | "invalid_token") {
+            bail!(
+                "OAuth refresh token was rejected ({error}: {description}). Please re-authenticate."
+            );
+        }
+        bail!("Token refresh failed ({error}: {description})");
+    }
+    if !status.is_success() {
+        bail!("Token refresh failed with HTTP status {status}");
+    }
+
+    let access_token = response["access_token"]
+        .as_str()
+        .ok_or_else(|| {
+            anyhow!(
+                "Missing access_token in refresh response (keys: {})",
+                token_response_keys(response)
+            )
+        })?
+        .to_string();
+    let refresh_token = response["refresh_token"]
+        .as_str()
+        .or(previous_refresh_token)
+        .map(str::to_string);
+    let expires_in = response["expires_in"].as_i64().ok_or_else(|| {
+        anyhow!(
+            "Missing expires_in in refresh response (keys: {})",
+            token_response_keys(response)
+        )
+    })?;
+
+    Ok((access_token, refresh_token, expires_in))
+}
+
 pub async fn refresh_oauth_token(
     client: &ReqwestClient,
     provider: &dyn OAuthProvider,
@@ -577,19 +679,23 @@ pub async fn refresh_oauth_token(
         ],
     );
 
-    let response: Value = request.send().await?.json().await?;
+    let (status, response) = tokio::time::timeout(TOKEN_ENDPOINT_TIMEOUT, async {
+        let response = request.send().await?;
+        let status = response.status();
+        let body: Value = response.json().await?;
+        Ok::<_, Error>((status, body))
+    })
+    .await
+    .map_err(|_| {
+        anyhow!(
+            "Token refresh for '{}' timed out after {}s",
+            client_name,
+            TOKEN_ENDPOINT_TIMEOUT.as_secs()
+        )
+    })??;
 
-    let access_token = response["access_token"]
-        .as_str()
-        .ok_or_else(|| anyhow!("Missing access_token in refresh response: {response}"))?
-        .to_string();
-    let refresh_token = response["refresh_token"]
-        .as_str()
-        .map(|s| s.to_string())
-        .or_else(|| tokens.refresh_token.clone());
-    let expires_in = response["expires_in"]
-        .as_i64()
-        .ok_or_else(|| anyhow!("Missing expires_in in refresh response: {response}"))?;
+    let (access_token, refresh_token, expires_in) =
+        parse_refresh_response(status, &response, tokens.refresh_token.as_deref())?;
 
     let expires_at = Utc::now().timestamp() + expires_in;
 
@@ -609,6 +715,20 @@ pub async fn refresh_oauth_token(
     Ok(new_tokens)
 }
 
+/// Per-client lock so concurrent requests perform a single refresh.
+/// Returns a clone of the Arc so the parking_lot guard is dropped before the
+/// caller awaits on the tokio mutex.
+fn refresh_guard(client_name: &str) -> Arc<sync::Mutex<()>> {
+    static GUARDS: OnceLock<parking_lot::Mutex<HashMap<String, Arc<sync::Mutex<()>>>>> =
+        OnceLock::new();
+    GUARDS
+        .get_or_init(Default::default)
+        .lock()
+        .entry(client_name.to_string())
+        .or_default()
+        .clone()
+}
+
 pub async fn prepare_oauth_access_token(
     client: &ReqwestClient,
     provider: &dyn OAuthProvider,
@@ -623,19 +743,43 @@ pub async fn prepare_oauth_access_token(
         None => return Ok(false),
     };
 
-    let tokens = if Utc::now().timestamp() >= tokens.expires_at {
+    let tokens = if Utc::now().timestamp() >= tokens.expires_at
+        || is_rejected(client_name, &tokens.access_token)
+    {
+        let guard = refresh_guard(client_name);
+        let _guard = guard.lock().await;
+
+        // A concurrent caller may have refreshed while we waited for the
+        // lock; a valid in-memory token means the winner already populated
+        // the cache.
+        if is_valid_access_token(client_name) {
+            return Ok(true);
+        }
+
+        let tokens = match load_oauth_tokens(client_name) {
+            Some(t) => t,
+            None => return Ok(false),
+        };
+
+        if Utc::now().timestamp() >= tokens.expires_at
+            || is_rejected(client_name, &tokens.access_token)
+        {
             match provider.flow() {
                 OAuthFlow::Pkce | OAuthFlow::DeviceCode => {
                     refresh_oauth_token(client, provider, client_name, &tokens).await?
                 }
                 OAuthFlow::ClientCredentials => {
                     run_client_credentials_flow(provider, client_name).await?;
-                load_oauth_tokens(client_name)
-                    .ok_or_else(|| anyhow!("Token file missing after client_credentials refresh"))?
+                    load_oauth_tokens(client_name).ok_or_else(|| {
+                        anyhow!("Token file missing after client_credentials refresh")
+                    })?
                 }
             }
         } else {
             tokens
+        }
+    } else {
+        tokens
     };
 
     set_access_token(
@@ -644,6 +788,9 @@ pub async fn prepare_oauth_access_token(
         tokens.expires_at,
         tokens.account_id,
     );
+    // Clear even when the refresh returned the same token (some IdPs reuse
+    // JWTs within validity); otherwise every request re-hits the token endpoint.
+    clear_rejected(client_name);
 
     Ok(true)
 }
@@ -886,11 +1033,55 @@ pub(crate) fn client_config_info(
 
 #[cfg(test)]
 mod tests {
+    use std::ffi::OsString;
+    use std::path::PathBuf;
     use std::str;
+    use std::time::UNIX_EPOCH;
 
     use super::*;
+    use crate::client::access_token::{distrust_access_token, get_access_token};
     use crate::client::openai_compatible::OpenAICompatibleConfig;
     use crate::client::{ModelData, ProviderModels};
+    use crate::utils::get_env_name;
+    use serial_test::serial;
+    use std::{env, time::SystemTime};
+
+    fn with_temp_cache<F: FnOnce()>(f: F) {
+        struct Restore {
+            key: String,
+            prev: Option<OsString>,
+            root: PathBuf,
+        }
+        impl Drop for Restore {
+            fn drop(&mut self) {
+                unsafe {
+                    match self.prev.take() {
+                        Some(v) => env::set_var(&self.key, v),
+                        None => env::remove_var(&self.key),
+                    }
+                }
+                let _ = fs::remove_dir_all(&self.root);
+            }
+        }
+
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let root = env::temp_dir().join(format!("coyote-client-oauth-test-{unique}"));
+        fs::create_dir_all(&root).unwrap();
+        let env_key = get_env_name("cache_dir");
+        let prev = env::var_os(&env_key);
+        unsafe {
+            env::set_var(&env_key, &root);
+        }
+        let _restore = Restore {
+            key: env_key,
+            prev,
+            root,
+        };
+        f();
+    }
 
     fn base_config() -> OAuthConfig {
         OAuthConfig {
@@ -1468,4 +1659,180 @@ scopes:
             "body missing grant_type param: {body}"
         );
     }
+
+    #[test]
+    #[serial]
+    fn save_oauth_tokens_roundtrips_and_leaves_no_tmp_file() {
+        with_temp_cache(|| {
+            let tokens = OAuthTokens {
+                access_token: "at-123".into(),
+                refresh_token: Some("rt-456".into()),
+                expires_at: 1234567890,
+                account_id: Some("acct-789".into()),
+            };
+
+            save_oauth_tokens("atomic-test", &tokens).unwrap();
+
+            let loaded = load_oauth_tokens("atomic-test").unwrap();
+            assert_eq!(loaded.access_token, "at-123");
+            assert_eq!(loaded.refresh_token.as_deref(), Some("rt-456"));
+            assert_eq!(loaded.expires_at, 1234567890);
+            assert_eq!(loaded.account_id.as_deref(), Some("acct-789"));
+
+            let dir = paths::oauth_tokens_dir();
+            let leftover_tmp = fs::read_dir(&dir)
+                .unwrap()
+                .any(|e| e.unwrap().file_name().to_string_lossy().ends_with(".tmp"));
+            assert!(!leftover_tmp, "temp file left behind in {dir:?}");
+
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                let mode = fs::metadata(paths::token_file("atomic-test"))
+                    .unwrap()
+                    .permissions()
+                    .mode();
+                assert_eq!(mode & 0o777, 0o600, "token file mode was {mode:o}");
+            }
+        });
+    }
+
+    #[test]
+    #[serial]
+    fn prepare_rejected_valid_file_token_attempts_refresh_branch() {
+        with_temp_cache(|| {
+            let client_name = "prepare-rejected-branch-test";
+            let expires_at = Utc::now().timestamp() + 3600;
+            save_oauth_tokens(
+                client_name,
+                &OAuthTokens {
+                    access_token: "rejected-at".into(),
+                    refresh_token: None,
+                    expires_at,
+                    account_id: None,
+                },
+            )
+            .unwrap();
+            set_access_token(client_name, "rejected-at".into(), expires_at, None);
+            assert!(distrust_access_token(client_name, "rejected-at"));
+
+            let err = tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .unwrap()
+                .block_on(prepare_oauth_access_token(
+                    &ReqwestClient::new(),
+                    &ResourceStubProvider,
+                    client_name,
+                ))
+                .unwrap_err()
+                .to_string();
+
+            // The timestamp-valid but rejected file token must not be trusted;
+            // the refresh branch is taken and bails on the missing refresh token.
+            assert!(err.contains("No refresh token"), "unexpected error: {err}");
+        });
+    }
+
+    #[test]
+    #[serial]
+    fn prepare_trusts_differing_unmarked_valid_file_token() {
+        with_temp_cache(|| {
+            let client_name = "prepare-differing-token-test";
+            let expires_at = Utc::now().timestamp() + 3600;
+            set_access_token(client_name, "rejected-at".into(), expires_at, None);
+            assert!(distrust_access_token(client_name, "rejected-at"));
+            save_oauth_tokens(
+                client_name,
+                &OAuthTokens {
+                    access_token: "fresh-at".into(),
+                    refresh_token: None,
+                    expires_at,
+                    account_id: None,
+                },
+            )
+            .unwrap();
+
+            let ready = tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .unwrap()
+                .block_on(prepare_oauth_access_token(
+                    &ReqwestClient::new(),
+                    &ResourceStubProvider,
+                    client_name,
+                ))
+                .unwrap();
+
+            assert!(ready);
+            assert_eq!(get_access_token(client_name).unwrap(), "fresh-at");
+            assert!(
+                !is_rejected(client_name, "rejected-at"),
+                "marker not cleared after successful prepare"
+            );
+        });
+    }
+
+    #[test]
+    fn parse_refresh_response_invalid_grant_redacts_and_prompts_reauth() {
+        let response = serde_json::json!({
+            "error": "invalid_grant",
+            "error_description": "refresh token revoked",
+            "refresh_token": "planted-secret-token",
+        });
+
+        let err = parse_refresh_response(StatusCode::BAD_REQUEST, &response, Some("old-rt"))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("re-authenticate"), "unexpected error: {err}");
+        assert!(
+            !err.contains("planted-secret-token"),
+            "error leaked token material: {err}"
+        );
+    }
+
+    #[test]
+    fn token_response_keys_lists_keys_without_values() {
+        let response = serde_json::json!({
+            "access_token": "secret-at",
+            "token_type": "SecretBearer",
+        });
+
+        let keys = token_response_keys(&response);
+
+        assert!(keys.contains("access_token"), "missing key name: {keys}");
+        assert!(keys.contains("token_type"), "missing key name: {keys}");
+        assert!(!keys.contains("secret-at"), "leaked value: {keys}");
+        assert!(!keys.contains("SecretBearer"), "leaked value: {keys}");
+    }
+
+    #[test]
+    fn parse_refresh_response_rotates_refresh_token_when_present() {
+        let response = serde_json::json!({
+            "access_token": "new-at",
+            "refresh_token": "new-rt",
+            "expires_in": 3600,
+        });
+
+        let (access_token, refresh_token, expires_in) =
+            parse_refresh_response(StatusCode::OK, &response, Some("old-rt")).unwrap();
+
+        assert_eq!(access_token, "new-at");
+        assert_eq!(refresh_token.as_deref(), Some("new-rt"));
+        assert_eq!(expires_in, 3600);
+    }
+
+    #[test]
+    fn parse_refresh_response_keeps_old_refresh_token_when_absent() {
+        let response = serde_json::json!({
+            "access_token": "new-at",
+            "expires_in": 3600,
+        });
+
+        let (_, refresh_token, _) =
+            parse_refresh_response(StatusCode::OK, &response, Some("old-rt")).unwrap();
+
+        assert_eq!(refresh_token.as_deref(), Some("old-rt"));
+    }
 }

src/client/stream.rs

@@ -1,4 +1,4 @@
-use super::{ThinkingBlock, ToolCall, catch_error};
+use super::{ApiStatusError, ThinkingBlock, ToolCall, catch_error};
 use crate::utils::AbortSignal;
 
 use anyhow::{Context, Result, anyhow, bail};
@@ -176,6 +176,14 @@ impl SseHandler {
         self.thinking.push(block);
     }
 
+    /// Whether any output (text, tool calls, or thinking blocks) has been
+    /// accumulated. `Client::chat_completions_streaming` gates its 401 retry
+    /// on this: content already streamed to the user would be rendered a
+    /// second time by a retry, so partial responses are never retried.
+    pub fn has_received_content(&self) -> bool {
+        !self.buffer.is_empty() || !self.tool_calls.is_empty() || !self.thinking.is_empty()
+    }
+
     pub fn abort(&self) -> AbortSignal {
         self.abort_signal.clone()
     }
@@ -224,10 +232,14 @@ where
         let data: Value = match text.parse() {
             Ok(data) => data,
             Err(_) => {
-                bail!(
+                return Err(ApiStatusError {
+                    status: status.as_u16(),
+                    message: format!(
                         "Invalid response data: {text} (status: {})",
                         status.as_u16()
-                );
+                    ),
+                }
+                .into());
             }
         };
         catch_error(&data, status.as_u16())?;
@@ -418,6 +430,43 @@ mod tests {
         assert!(error_message.contains("test_function_loop"));
     }
 
+    fn new_handler() -> (SseHandler, tokio::sync::mpsc::UnboundedReceiver<SseEvent>) {
+        let (sender, receiver) = tokio::sync::mpsc::unbounded_channel();
+        let abort_signal = crate::utils::create_abort_signal();
+        (SseHandler::new(sender, abort_signal), receiver)
+    }
+
+    #[test]
+    fn test_has_received_content_text() {
+        let (mut handler, _rx) = new_handler();
+        assert!(!handler.has_received_content());
+
+        handler.text("hello").unwrap();
+        assert!(handler.has_received_content());
+    }
+
+    #[test]
+    fn test_has_received_content_tool_call() {
+        let (mut handler, _rx) = new_handler();
+        assert!(!handler.has_received_content());
+
+        let call = ToolCall::new("test_function".to_string(), json!({"param": 1}), None);
+        handler.tool_call(call).unwrap();
+        assert!(handler.has_received_content());
+    }
+
+    #[test]
+    fn test_has_received_content_thinking() {
+        let (mut handler, _rx) = new_handler();
+        assert!(!handler.has_received_content());
+
+        handler.thinking_block(ThinkingBlock::Thinking {
+            thinking: "hmm".to_string(),
+            signature: "sig".to_string(),
+        });
+        assert!(handler.has_received_content());
+    }
+
     fn split_chunks(text: &str) -> Vec<Vec<u8>> {
         let len = text.len();
         let cut1 = random_range(1..len - 1);

src/config/agent.rs

@@ -3,18 +3,23 @@ use super::*;
 use crate::{
     client::Model,
     config::memory,
-    function::{Functions, run_llm_function},
+    function::{
+        Functions,
+        jobs::{DEFAULT_MAX_CONCURRENT_JOBS, JOB_FUNCTION_PREFIX},
+        run_llm_function,
+    },
     graph, rag,
 };
 
 use super::rag_cache::RagKey;
 use crate::config::paths;
 use crate::config::prompts::{
-    DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS, DEFAULT_TODO_INSTRUCTIONS,
-    DEFAULT_USER_INTERACTION_INSTRUCTIONS,
+    DEFAULT_JOB_INSTRUCTIONS, DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS,
+    DEFAULT_TODO_INSTRUCTIONS, DEFAULT_USER_INTERACTION_INSTRUCTIONS,
 };
 use crate::graph::types::RagNode;
 use crate::graph::{Graph, GraphParser, NodeType};
+use crate::mcp::McpServerFeatures;
 use crate::rag::RagInitConfig;
 use crate::vault::SECRET_RE;
 use anyhow::{Context, Result};
@@ -224,6 +229,16 @@ impl Agent {
             functions.append_supervisor_functions();
         }
 
+        if app.function_calling_support
+            && agent_config
+                .max_concurrent_jobs
+                .or(app.max_concurrent_jobs)
+                .unwrap_or(DEFAULT_MAX_CONCURRENT_JOBS)
+                > 0
+        {
+            functions.append_job_functions();
+        }
+
         functions.append_teammate_functions();
         functions.append_user_interaction_functions();
 
@@ -380,7 +395,7 @@ impl Agent {
         self.graph_rags.get(node_id).cloned()
     }
 
-    pub fn append_mcp_meta_functions(&mut self, mcp_servers: Vec<String>) {
+    pub fn append_mcp_meta_functions(&mut self, mcp_servers: Vec<McpServerFeatures>) {
         self.functions.append_mcp_meta_functions(mcp_servers);
     }
 
@@ -400,6 +415,10 @@ impl Agent {
         self.config.enabled_skills.as_deref()
     }
 
+    pub fn enabled_macros(&self) -> Option<&[String]> {
+        self.config.enabled_macros.as_deref()
+    }
+
     pub fn memory(&self) -> Option<bool> {
         self.config.memory
     }
@@ -435,6 +454,18 @@ impl Agent {
             output.push_str(DEFAULT_SPAWN_INSTRUCTIONS);
         }
 
+        if self
+            .functions
+            .declarations()
+            .iter()
+            .any(|f| f.name.starts_with(JOB_FUNCTION_PREFIX))
+        {
+            if !output.ends_with('\n') {
+                output.push('\n');
+            }
+            output.push_str(DEFAULT_JOB_INSTRUCTIONS);
+        }
+
         output.push_str(DEFAULT_TEAMMATE_INSTRUCTIONS);
         output.push_str(DEFAULT_USER_INTERACTION_INSTRUCTIONS);
 
@@ -556,6 +587,10 @@ impl Agent {
         self.config.max_tool_result_chars
     }
 
+    pub fn max_concurrent_jobs(&self) -> Option<usize> {
+        self.config.max_concurrent_jobs
+    }
+
     pub fn compression_keep_last(&self) -> Option<usize> {
         self.config.compression_keep_last
     }
@@ -647,6 +682,10 @@ impl RoleLike for Agent {
         Some(self.config.mcp_servers.clone())
     }
 
+    fn mcp_tools(&self) -> Option<IndexMap<String, Vec<String>>> {
+        self.config.mcp_tools.clone()
+    }
+
     fn set_model(&mut self, model: Model) {
         self.config.model_id = Some(model.id());
         self.model = model;
@@ -688,6 +727,10 @@ impl RoleLike for Agent {
             }
         }
     }
+
+    fn set_mcp_tools(&mut self, value: Option<IndexMap<String, Vec<String>>>) {
+        self.config.mcp_tools = value;
+    }
 }
 
 #[derive(Debug, Clone, Default, Deserialize, Serialize)]
@@ -730,6 +773,8 @@ pub struct AgentConfig {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub max_tool_result_chars: Option<usize>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_concurrent_jobs: Option<usize>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub compression_keep_last: Option<usize>,
     #[serde(default)]
     pub description: String,
@@ -737,6 +782,8 @@ pub struct AgentConfig {
     pub version: String,
     #[serde(default)]
     pub mcp_servers: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mcp_tools: Option<IndexMap<String, Vec<String>>>,
     #[serde(default)]
     pub global_tools: Vec<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -744,6 +791,8 @@ pub struct AgentConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub enabled_skills: Option<Vec<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub enabled_macros: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub continuation_prompt: Option<String>,
     #[serde(default)]
     pub instructions: String,
@@ -807,6 +856,7 @@ impl AgentConfig {
             description: graph.description.clone(),
             global_tools: graph.global_tools.clone(),
             mcp_servers: graph.mcp_servers.clone(),
+            mcp_tools: graph.mcp_tools.clone(),
             skills_enabled: graph.skills_enabled,
             enabled_skills: graph.enabled_skills.clone(),
             inject_skill_instructions: graph.inject_skill_instructions.unwrap_or(true),
@@ -815,6 +865,7 @@ impl AgentConfig {
             variables: graph.variables.clone(),
             can_spawn_agents: graph.has_agent_node(),
             max_concurrent_agents: default_max_concurrent_agents(),
+            max_concurrent_jobs: graph.max_concurrent_jobs,
             max_agent_depth: default_max_agent_depth(),
             escalation_timeout: default_escalation_timeout(),
             ..AgentConfig::default()
@@ -1125,6 +1176,12 @@ struct AgentMetadataStub {
     description: String,
 }
 
+#[derive(Deserialize)]
+struct AgentVariablesStub {
+    #[serde(default)]
+    variables: Vec<AgentVariable>,
+}
+
 fn load_agent_description(name: &str) -> String {
     if let Ok(config) = AgentConfig::load(&paths::agent_config_file(name)) {
         return config.description;
@@ -1139,16 +1196,22 @@ fn load_agent_description(name: &str) -> String {
     String::new()
 }
 
-pub fn complete_agent_variables(agent_name: &str) -> Vec<(String, Option<String>)> {
-    let config_path = paths::agent_config_file(agent_name);
-    if !config_path.exists() {
-        return vec![];
+fn load_agent_variables(name: &str) -> Vec<AgentVariable> {
+    if let Ok(config) = AgentConfig::load(&paths::agent_config_file(name)) {
+        return config.variables;
     }
-    let Ok(config) = AgentConfig::load(&config_path) else {
-        return vec![];
-    };
-    config
-        .variables
+
+    if let Ok(contents) = read_to_string(paths::agent_graph_file(name))
+        && let Ok(stub) = serde_yaml::from_str::<AgentVariablesStub>(&contents)
+    {
+        return stub.variables;
+    }
+
+    Vec::new()
+}
+
+pub fn complete_agent_variables(agent_name: &str) -> Vec<(String, Option<String>)> {
+    load_agent_variables(agent_name)
         .iter()
         .map(|v| {
             let description = match &v.default {
@@ -1225,6 +1288,57 @@ variables:
         assert!(config.top_p.is_none());
     }
 
+    #[test]
+    fn agent_config_enabled_macros_absent_is_none() {
+        let yaml = "name: minimal\ninstructions: hi\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.enabled_macros, None);
+    }
+
+    #[test]
+    fn agent_config_parses_mcp_tools() {
+        let yaml =
+            "name: minimal\ninstructions: hi\nmcp_tools:\n  github:\n    - get_*\n    - list_*\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        let mcp_tools = config.mcp_tools.unwrap();
+        assert_eq!(
+            mcp_tools.get("github"),
+            Some(&vec!["get_*".to_string(), "list_*".to_string()])
+        );
+    }
+
+    #[test]
+    fn agent_mcp_tools_role_like_round_trip() {
+        let config: AgentConfig =
+            serde_yaml::from_str("name: minimal\ninstructions: hi\n").unwrap();
+        let mut agent = Agent::test_new(config);
+        assert_eq!(agent.mcp_tools(), None);
+
+        let mut mcp_tools = IndexMap::new();
+        mcp_tools.insert("github".to_string(), vec!["get_*".to_string()]);
+        agent.set_mcp_tools(Some(mcp_tools.clone()));
+
+        assert_eq!(agent.mcp_tools(), Some(mcp_tools));
+    }
+
+    #[test]
+    fn agent_config_enabled_macros_empty_list_is_some_empty() {
+        let yaml = "name: minimal\ninstructions: hi\nenabled_macros: []\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    fn agent_config_enabled_macros_list() {
+        let yaml = "name: minimal\ninstructions: hi\nenabled_macros:\n  - a\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.enabled_macros, Some(vec!["a".to_string()]));
+    }
+
     #[test]
     fn agent_config_with_model() {
         let yaml =
@@ -1253,6 +1367,7 @@ variables:
             model: claude:claude-sonnet-4-6
             temperature: 0.3
             top_p: 0.8
+            max_concurrent_jobs: 2
             global_tools:
               - fetch_pdf.sh
             mcp_servers:
@@ -1275,6 +1390,7 @@ variables:
         assert_eq!(config.model_id.as_deref(), Some("claude:claude-sonnet-4-6"));
         assert_eq!(config.temperature, Some(0.3));
         assert_eq!(config.top_p, Some(0.8));
+        assert_eq!(config.max_concurrent_jobs, Some(2));
         assert_eq!(config.global_tools, vec!["fetch_pdf.sh"]);
         assert_eq!(config.mcp_servers, vec!["pubmed-search"]);
         assert_eq!(config.conversation_starters, vec!["Start here"]);
@@ -1369,6 +1485,41 @@ version: "1.0"
         assert_eq!(meta.description, "");
     }
 
+    #[test]
+    fn agent_variables_stub_extracts_variables_from_graph_yaml() {
+        let yaml = r#"
+name: coder
+description: Implementation agent.
+version: "1.0"
+variables:
+  - name: task
+    description: The task to implement
+  - name: scope
+    description: Directory scope
+    default: src/
+start: plan
+nodes: {}
+"#;
+
+        let stub: AgentVariablesStub = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(stub.variables.len(), 2);
+        assert_eq!(stub.variables[0].name, "task");
+        assert_eq!(stub.variables[0].description, "The task to implement");
+        assert_eq!(stub.variables[0].default, None);
+        assert_eq!(stub.variables[1].name, "scope");
+        assert_eq!(stub.variables[1].default.as_deref(), Some("src/"));
+    }
+
+    #[test]
+    fn agent_variables_stub_defaults_when_variables_missing() {
+        let yaml = "name: coder\nversion: \"1.0\"\nstart: plan\nnodes: {}\n";
+
+        let stub: AgentVariablesStub = serde_yaml::from_str(yaml).unwrap();
+
+        assert!(stub.variables.is_empty());
+    }
+
     #[test]
     fn rag_init_config_forwards_an_explicit_driver() {
         let node: RagNode =
@@ -1403,4 +1554,51 @@ version: "1.0"
         assert_eq!(config.top_k, Some(7));
         assert_eq!(config.embedding_model.as_deref(), Some("some:model"));
     }
+
+    #[test]
+    fn interpolated_instructions_without_job_declarations_is_byte_identical_across_job_settings() {
+        let agent = |max_concurrent_jobs| {
+            Agent::test_new(AgentConfig {
+                instructions: "hi".to_string(),
+                max_concurrent_jobs,
+                ..AgentConfig::default()
+            })
+        };
+
+        let baseline = agent(None).interpolated_instructions();
+        assert!(
+            !baseline.contains(DEFAULT_JOB_INSTRUCTIONS),
+            "no job guidance may be injected without job__ declarations"
+        );
+        assert_eq!(baseline, agent(Some(0)).interpolated_instructions());
+        assert_eq!(baseline, agent(Some(7)).interpolated_instructions());
+
+        let mut with_unrelated = agent(None);
+        with_unrelated.functions.append_todo_functions();
+        assert_eq!(
+            baseline,
+            with_unrelated.interpolated_instructions(),
+            "job guidance injection must key strictly on the job__ prefix"
+        );
+    }
+
+    #[test]
+    fn interpolated_instructions_with_job_declarations_appends_job_guidance() {
+        let config = AgentConfig {
+            instructions: "hi".to_string(),
+            ..AgentConfig::default()
+        };
+        let baseline = Agent::test_new(config.clone()).interpolated_instructions();
+
+        let mut agent = Agent::test_new(config);
+        agent.functions.append_job_functions();
+        let output = agent.interpolated_instructions();
+
+        assert!(output.contains(DEFAULT_JOB_INSTRUCTIONS));
+        let expected = format!(
+            "hi\n{DEFAULT_JOB_INSTRUCTIONS}{}",
+            baseline.strip_prefix("hi").unwrap()
+        );
+        assert_eq!(output, expected);
+    }
 }

src/config/app_config.rs

@@ -1,6 +1,6 @@
 use crate::client::{ClientConfig, Model, ModelType, list_models};
 use crate::render::{MarkdownRender, RenderOptions};
-use crate::utils::{IS_STDOUT_TERMINAL, NO_COLOR, decode_bin, get_env_name};
+use crate::utils::{IS_STDOUT_TERMINAL, NO_COLOR, decode_bin, drain_stale_tty_input, get_env_name};
 
 use super::paths;
 use anyhow::{Context, Result, anyhow, bail};
@@ -43,11 +43,14 @@ pub struct AppConfig {
     #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
     pub enabled_skills: Option<Vec<String>>,
     pub visible_skills: Option<Vec<String>>,
+    #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
+    pub enabled_macros: Option<Vec<String>>,
 
     pub mcp_server_support: bool,
     pub mapping_mcp_servers: IndexMap<String, String>,
     #[serde(default, deserialize_with = "super::deserialize_csv_or_vec")]
     pub enabled_mcp_servers: Option<Vec<String>>,
+    pub mcp_tools: Option<IndexMap<String, Vec<String>>>,
 
     pub auto_continue: bool,
     pub max_auto_continues: usize,
@@ -66,6 +69,7 @@ pub struct AppConfig {
     pub summarization_prompt: Option<String>,
     pub summary_context_prompt: Option<String>,
     pub max_tool_result_chars: Option<usize>,
+    pub max_concurrent_jobs: Option<usize>,
 
     pub memory: Option<bool>,
     pub memory_cap_with_tools: Option<usize>,
@@ -96,6 +100,7 @@ pub struct AppConfig {
     pub user_agent: Option<String>,
     pub save_shell_history: bool,
     pub no_workspace_mcp: bool,
+    pub no_workspace_macros: bool,
     pub sync_models_url: Option<String>,
 
     pub clients: Vec<ClientConfig>,
@@ -127,10 +132,12 @@ impl Default for AppConfig {
             skills_enabled: true,
             enabled_skills: None,
             visible_skills: None,
+            enabled_macros: None,
 
             mcp_server_support: true,
             mapping_mcp_servers: Default::default(),
             enabled_mcp_servers: None,
+            mcp_tools: None,
 
             auto_continue: false,
             max_auto_continues: 10,
@@ -149,6 +156,7 @@ impl Default for AppConfig {
             summarization_prompt: None,
             summary_context_prompt: None,
             max_tool_result_chars: None,
+            max_concurrent_jobs: None,
 
             memory: None,
             memory_cap_with_tools: None,
@@ -178,6 +186,7 @@ impl Default for AppConfig {
             user_agent: None,
             save_shell_history: true,
             no_workspace_mcp: false,
+            no_workspace_macros: false,
             sync_models_url: None,
 
             clients: vec![],
@@ -211,10 +220,12 @@ impl AppConfig {
             skills_enabled: config.skills_enabled,
             enabled_skills: config.enabled_skills,
             visible_skills: config.visible_skills,
+            enabled_macros: config.enabled_macros,
 
             mcp_server_support: config.mcp_server_support,
             mapping_mcp_servers: config.mapping_mcp_servers,
             enabled_mcp_servers: config.enabled_mcp_servers,
+            mcp_tools: config.mcp_tools,
 
             auto_continue: config.auto_continue,
             max_auto_continues: config.max_auto_continues,
@@ -233,6 +244,7 @@ impl AppConfig {
             summarization_prompt: config.summarization_prompt,
             summary_context_prompt: config.summary_context_prompt,
             max_tool_result_chars: config.max_tool_result_chars,
+            max_concurrent_jobs: config.max_concurrent_jobs,
 
             memory: config.memory,
             memory_cap_with_tools: config.memory_cap_with_tools,
@@ -262,6 +274,7 @@ impl AppConfig {
             user_agent: config.user_agent,
             save_shell_history: config.save_shell_history,
             no_workspace_mcp: false,
+            no_workspace_macros: false,
             sync_models_url: config.sync_models_url,
 
             clients: config.clients,
@@ -533,6 +546,10 @@ impl AppConfig {
             self.enabled_skills = v.map(|raw| super::csv_to_vec(&raw));
         }
 
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_macros")) {
+            self.enabled_macros = v.map(|raw| super::csv_to_vec(&raw));
+        }
+
         if let Some(Some(v)) = super::read_env_bool(&get_env_name("mcp_server_support")) {
             self.mcp_server_support = v;
         }
@@ -563,6 +580,9 @@ impl AppConfig {
         {
             self.compression_threshold = v;
         }
+        if let Some(v) = super::read_env_value::<usize>(&get_env_name("max_concurrent_jobs")) {
+            self.max_concurrent_jobs = v;
+        }
         if let Some(v) = super::read_env_value::<String>(&get_env_name("summarization_prompt")) {
             self.summarization_prompt = v;
         }
@@ -616,15 +636,19 @@ impl AppConfig {
         if self.highlight && self.theme.is_none() {
             if let Some(v) = super::read_env_value::<String>(&get_env_name("theme")) {
                 self.theme = v;
-            } else if *IS_STDOUT_TERMINAL
-                && let Ok(color_scheme) = color_scheme(QueryOptions::default())
-            {
+            } else if *IS_STDOUT_TERMINAL {
+                if let Ok(color_scheme) = color_scheme(QueryOptions::default()) {
                     let theme = match color_scheme {
                         ColorScheme::Dark => "dark",
                         ColorScheme::Light => "light",
                     };
                     self.theme = Some(theme.into());
                 }
+                // The OSC/DA1 reply can arrive after colorsaurus stops reading
+                // (observed under zellij-in-kitty). Drain any late reply bytes so
+                // they are neither echoed nor read as line-editor input.
+                drain_stale_tty_input();
+            }
         }
         if let Some(v) = super::read_env_value::<String>(&get_env_name("left_prompt")) {
             self.left_prompt = v;
@@ -765,10 +789,133 @@ mod tests {
         );
     }
 
+    #[test]
+    fn from_config_copies_mcp_tools() {
+        let mut mcp_tools = IndexMap::new();
+        mcp_tools.insert("github".to_string(), vec!["get_*".to_string()]);
+        let cfg = Config {
+            model_id: "test-model".to_string(),
+            clients: vec![ClientConfig::default()],
+            mcp_tools: Some(mcp_tools.clone()),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.mcp_tools, Some(mcp_tools));
+    }
+
+    #[test]
+    #[serial_test::serial]
+    fn from_config_copies_enabled_macros() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            enabled_macros: Some(vec!["a".to_string()]),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.enabled_macros, Some(vec!["a".to_string()]));
+    }
+
+    #[test]
+    #[serial_test::serial]
+    fn from_config_preserves_explicit_empty_enabled_macros() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            enabled_macros: Some(vec![]),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    #[serial_test::serial]
+    fn load_envs_overrides_enabled_macros() {
+        let env_name = get_env_name("enabled_macros");
+        let prev = std::env::var_os(&env_name);
+
+        let mut app = AppConfig::default();
+
+        unsafe { std::env::set_var(&env_name, "a,b") };
+        app.load_envs();
+        assert_eq!(
+            app.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+
+        unsafe { std::env::set_var(&env_name, "") };
+        app.load_envs();
+        assert_eq!(app.enabled_macros, Some(vec![]));
+
+        unsafe { std::env::set_var(&env_name, "null") };
+        app.load_envs();
+        assert_eq!(app.enabled_macros, None);
+
+        unsafe { std::env::remove_var(&env_name) };
+        app.enabled_macros = Some(vec!["keep".to_string()]);
+        app.load_envs();
+        assert_eq!(app.enabled_macros, Some(vec!["keep".to_string()]));
+
+        unsafe {
+            match prev {
+                Some(v) => env::set_var(&env_name, v),
+                None => env::remove_var(&env_name),
+            }
+        }
+    }
+
+    #[test]
+    fn from_config_copies_max_concurrent_jobs() {
+        let cfg = Config {
+            model_id: "test-model".to_string(),
+            max_concurrent_jobs: Some(3),
+            clients: vec![ClientConfig::default()],
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.max_concurrent_jobs, Some(3));
+    }
+
+    #[test]
+    #[serial_test::serial]
+    fn load_envs_overrides_max_concurrent_jobs() {
+        let env_name = get_env_name("max_concurrent_jobs");
+        let prev = env::var_os(&env_name);
+
+        let mut app = AppConfig::default();
+
+        unsafe { env::set_var(&env_name, "7") };
+        app.load_envs();
+        assert_eq!(app.max_concurrent_jobs, Some(7));
+
+        unsafe { env::set_var(&env_name, "0") };
+        app.load_envs();
+        assert_eq!(app.max_concurrent_jobs, Some(0));
+
+        unsafe { env::remove_var(&env_name) };
+        app.max_concurrent_jobs = Some(2);
+        app.load_envs();
+        assert_eq!(app.max_concurrent_jobs, Some(2));
+
+        unsafe {
+            match prev {
+                Some(v) => env::set_var(&env_name, v),
+                None => env::remove_var(&env_name),
+            }
+        }
+    }
+
     #[test]
     fn editor_returns_configured_value() {
-        let configured = cached_editor()
-            .unwrap_or_else(|| std::env::current_exe().unwrap().display().to_string());
+        let configured =
+            cached_editor().unwrap_or_else(|| env::current_exe().unwrap().display().to_string());
         let app = AppConfig {
             editor: Some(configured.clone()),
             ..AppConfig::default()
@@ -785,9 +932,9 @@ mod tests {
             return;
         }
 
-        let expected = std::env::current_exe().unwrap().display().to_string();
+        let expected = env::current_exe().unwrap().display().to_string();
         unsafe {
-            std::env::set_var("VISUAL", &expected);
+            env::set_var("VISUAL", &expected);
         }
 
         let app = AppConfig::default();
@@ -855,7 +1002,7 @@ mod tests {
         let app = AppConfig::from_config(cfg).unwrap();
 
         let ua = app.user_agent.as_deref().unwrap();
-        assert!(ua != "auto", "user_agent should have been resolved");
+        assert_ne!(ua, "auto", "user_agent should have been resolved");
         assert!(ua.contains('/'), "user_agent should be '<name>/<version>'");
     }
 

src/config/app_state.rs

@@ -1,6 +1,7 @@
 use super::mcp_factory::{McpFactory, McpServerKey};
 use super::rag_cache::RagCache;
 use crate::config::AppConfig;
+use crate::config::jobs_enabled;
 use crate::function::Functions;
 use crate::mcp::{McpRegistry, McpServersConfig};
 use crate::utils::AbortSignal;
@@ -68,9 +69,13 @@ impl AppState {
             }
         }
 
-        let mut functions = Functions::init(config.visible_tools.as_ref().unwrap_or(&Vec::new()))?;
+        let mut functions = Functions::init(config.visible_tools.as_deref())?;
         if !mcp_registry.is_empty() && config.mcp_server_support {
-            functions.append_mcp_meta_functions(mcp_registry.list_started_servers());
+            functions.append_mcp_meta_functions(mcp_registry.server_features());
+        }
+
+        if jobs_enabled(None, &config) {
+            functions.append_job_functions();
         }
 
         let mcp_registry = if mcp_registry.is_empty() {

src/config/input.rs

@@ -9,7 +9,12 @@ use crate::utils::{AbortSignal, base64_encode, is_loader_protocol, sha256};
 
 use anyhow::{Context, Result, bail};
 use indexmap::IndexSet;
-use std::{collections::HashMap, fs::File, io::Read, sync::Arc};
+use std::{
+    collections::{HashMap, HashSet},
+    fs::File,
+    io::Read,
+    sync::Arc,
+};
 use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
 
 const IMAGE_EXTS: [&str; 5] = ["png", "jpeg", "jpg", "webp", "gif"];
@@ -158,6 +163,13 @@ impl Input {
         self.data_urls.clone()
     }
 
+    pub fn declared_function_names(&self) -> HashSet<String> {
+        self.functions
+            .as_ref()
+            .map(|functions| functions.iter().map(|f| f.name.clone()).collect())
+            .unwrap_or_default()
+    }
+
     pub fn tool_calls(&self) -> &Option<MessageContentToolCalls> {
         &self.tool_calls
     }
@@ -593,6 +605,8 @@ mod tests {
     use super::*;
     use crate::config::request_context::RequestContext;
     use crate::config::{AppState, WorkingMode};
+    use crate::function::ToolCall;
+    use serde_json::json;
     use std::fs;
     use std::sync::Arc;
     use std::time::SystemTime;
@@ -973,4 +987,70 @@ mod tests {
         ));
         assert!(result.is_err());
     }
+
+    fn tool_result(id: &str, output: &str) -> ToolResult {
+        ToolResult::new(
+            ToolCall::new("t".into(), json!({}), Some(id.to_string())),
+            json!(output),
+        )
+    }
+
+    #[test]
+    fn merge_tool_results_first_merge_creates_container() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", None).unwrap();
+
+        let input =
+            input.merge_tool_results("assistant text".into(), vec![tool_result("id-1", "ok")]);
+
+        let tool_calls = input.tool_calls().as_ref().unwrap();
+        assert_eq!(tool_calls.text, "assistant text");
+        assert!(!tool_calls.sequence);
+        assert_eq!(tool_calls.tool_results.len(), 1);
+        assert!(tool_calls.tool_results[0].text.is_none());
+    }
+
+    #[test]
+    fn merge_tool_results_second_merge_marks_sequence_and_tags_text() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", None)
+            .unwrap()
+            .merge_tool_results("assistant text".into(), vec![tool_result("id-1", "ok")]);
+
+        let input =
+            input.merge_tool_results("second text".into(), vec![tool_result("id-2", "ok2")]);
+
+        let tool_calls = input.tool_calls().as_ref().unwrap();
+        assert!(tool_calls.sequence);
+        assert_eq!(tool_calls.tool_results.len(), 2);
+        assert_eq!(tool_calls.text, "assistant text");
+        assert!(tool_calls.tool_results[0].text.is_none());
+        assert_eq!(
+            tool_calls.tool_results[1].text,
+            Some("second text".to_string())
+        );
+    }
+
+    #[test]
+    fn build_messages_wraps_tool_results_in_single_assistant_message() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", None)
+            .unwrap()
+            .merge_tool_results("assistant text".into(), vec![tool_result("id-1", "ok")])
+            .merge_tool_results("second text".into(), vec![tool_result("id-2", "ok2")]);
+
+        let messages = input.build_messages().unwrap();
+
+        let tool_call_messages: Vec<_> = messages
+            .iter()
+            .filter(|m| matches!(m.content, MessageContent::ToolCalls(_)))
+            .collect();
+        assert_eq!(tool_call_messages.len(), 1);
+        let message = tool_call_messages[0];
+        assert!(matches!(message.role, MessageRole::Assistant));
+        let MessageContent::ToolCalls(tool_calls) = &message.content else {
+            unreachable!();
+        };
+        assert_eq!(tool_calls.tool_results.len(), 2);
+    }
 }

src/config/mcp_factory.rs

@@ -1,6 +1,6 @@
 use crate::mcp::{
-    ConnectedServer, JsonField, McpServer, McpTransportType, is_auth_required_error, oauth,
-    spawn_mcp_server,
+    ConnectedServer, JsonField, McpAuthRequired, McpServer, McpTransportType,
+    is_auth_required_error, resolve_http_auth, spawn_mcp_server,
 };
 
 use anyhow::Result;
@@ -102,19 +102,13 @@ impl McpFactory {
             return Ok(existing);
         }
 
-        let bearer_token = if spec.is_remote() {
-            oauth::load_valid_mcp_token(name)
-        } else {
-            None
-        };
-        let handle = spawn_mcp_server(spec, log_path, bearer_token)
-            .await
-            .map_err(|e| {
+        let (auth, auth_reason) = resolve_http_auth(name, spec).await;
+        let handle = spawn_mcp_server(spec, log_path, auth).await.map_err(|e| {
             if is_auth_required_error(&e) {
-                    e.context(format!(
-                        "MCP server '{name}' requires OAuth authentication. \
-                         Run `coyote --auth-mcp {name}` or `.mcp auth {name}` in the REPL to authenticate."
-                    ))
+                e.context(McpAuthRequired {
+                    server: name.to_string(),
+                    reason: auth_reason,
+                })
             } else {
                 e
             }
@@ -145,6 +139,7 @@ mod tests {
             url: None,
             headers: None,
             oauth: None,
+            allowed_tools: None,
         }
     }
 
@@ -162,6 +157,7 @@ mod tests {
             url: Some(url.to_string()),
             headers,
             oauth: None,
+            allowed_tools: None,
         }
     }
 

src/config/mcp_tool_policy.rs

@@ -0,0 +1,859 @@
+use crate::mcp::McpServersConfig;
+
+use fancy_regex::Regex;
+use indexmap::IndexMap;
+use log::warn;
+use std::collections::HashMap;
+use std::fmt;
+
+/// The configuration level that contributed a layer of tool patterns for an
+/// MCP server, as rendered in diagnostics.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LayerSource {
+    Global,
+    AppConfig,
+    Role(String),
+    Agent(String),
+    Session,
+    Skill(String),
+    Node(String),
+}
+
+impl fmt::Display for LayerSource {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            LayerSource::Global => write!(f, "global (mcp.json)"),
+            LayerSource::AppConfig => write!(f, "config (config.yaml)"),
+            LayerSource::Role(name) => write!(f, "role ({name})"),
+            LayerSource::Agent(name) => write!(f, "agent ({name})"),
+            LayerSource::Session => write!(f, "session (.set)"),
+            LayerSource::Skill(name) => write!(f, "skill ({name})"),
+            LayerSource::Node(id) => write!(f, "node ({id})"),
+        }
+    }
+}
+
+impl LayerSource {
+    pub fn short_label(&self) -> &'static str {
+        match self {
+            LayerSource::Global => "global",
+            LayerSource::AppConfig => "config",
+            LayerSource::Role(_) => "role",
+            LayerSource::Agent(_) => "agent",
+            LayerSource::Session => "session",
+            LayerSource::Skill(_) => "skill",
+            LayerSource::Node(_) => "node",
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct CompiledPatterns {
+    source: LayerSource,
+    raw: Vec<String>,
+    regexes: Vec<Regex>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ToolFilter {
+    layers: Vec<CompiledPatterns>,
+}
+
+impl ToolFilter {
+    pub fn push_layer(&mut self, source: LayerSource, patterns: &[String]) {
+        self.layers.push(CompiledPatterns {
+            source,
+            raw: patterns.to_vec(),
+            regexes: patterns.iter().map(|p| compile_glob(p)).collect(),
+        });
+    }
+
+    pub fn layers(&self) -> impl Iterator<Item = (&LayerSource, &[String])> {
+        self.layers
+            .iter()
+            .map(|layer| (&layer.source, layer.raw.as_slice()))
+    }
+
+    pub fn allows(&self, tool: &str) -> bool {
+        self.layers.iter().all(|layer| {
+            layer
+                .regexes
+                .iter()
+                .any(|regex| regex.is_match(tool).unwrap_or(false))
+        })
+    }
+
+    /// The first matching raw pattern per layer, in layer order, or the
+    /// source of the first layer with no match.
+    pub fn allows_explain(&self, tool: &str) -> Result<Vec<(&LayerSource, &str)>, &LayerSource> {
+        let mut matched = Vec::with_capacity(self.layers.len());
+        for layer in &self.layers {
+            // fancy_regex can fail at match time (backtracking limits);
+            // treat that as a non-match rather than allowing the tool.
+            match layer
+                .regexes
+                .iter()
+                .position(|regex| regex.is_match(tool).unwrap_or(false))
+            {
+                Some(index) => matched.push((&layer.source, layer.raw[index].as_str())),
+                None => return Err(&layer.source),
+            }
+        }
+        Ok(matched)
+    }
+
+    pub fn dead_context_patterns(&self, advertised: &[String]) -> Vec<(&LayerSource, &str)> {
+        let surviving: Vec<&String> = advertised
+            .iter()
+            .filter(|name| {
+                self.layers
+                    .iter()
+                    .filter(|layer| layer.source == LayerSource::Global)
+                    .all(|layer| {
+                        layer
+                            .regexes
+                            .iter()
+                            .any(|regex| regex.is_match(name).unwrap_or(false))
+                    })
+            })
+            .collect();
+        let mut dead = Vec::new();
+        for layer in self
+            .layers
+            .iter()
+            .filter(|l| l.source != LayerSource::Global)
+        {
+            for (raw, regex) in layer.raw.iter().zip(&layer.regexes) {
+                if !surviving
+                    .iter()
+                    .any(|name| regex.is_match(name).unwrap_or(false))
+                {
+                    dead.push((&layer.source, raw.as_str()));
+                }
+            }
+        }
+
+        dead
+    }
+}
+
+/// Translates a glob pattern (`*` = any run of characters, `?` = exactly one)
+/// into an anchored regex. Patterns that fail to compile match nothing.
+fn compile_glob(pattern: &str) -> Regex {
+    let translated = format!(
+        "^{}$",
+        fancy_regex::escape(pattern)
+            .replace("\\*", ".*")
+            .replace("\\?", ".")
+    );
+    Regex::new(&translated).unwrap_or_else(|error| {
+        warn!("Invalid MCP tool pattern '{pattern}': {error}. It will match nothing.");
+        never_matching_regex()
+    })
+}
+
+fn never_matching_regex() -> Regex {
+    Regex::new("(?!)").expect("'(?!)' is a valid never-matching regex")
+}
+
+pub struct SkillMcpLayer {
+    pub name: String,
+    pub enabled_servers: Vec<String>,
+    pub mcp_tools: IndexMap<String, Vec<String>>,
+}
+
+pub struct McpToolPolicy;
+
+impl McpToolPolicy {
+    #[allow(clippy::too_many_arguments)]
+    pub fn effective(
+        mcp_config: &McpServersConfig,
+        session: Option<&IndexMap<String, Vec<String>>>,
+        agent: Option<(&str, &IndexMap<String, Vec<String>>)>,
+        role: Option<(&str, &IndexMap<String, Vec<String>>)>,
+        global: Option<&IndexMap<String, Vec<String>>>,
+        skills: &[SkillMcpLayer],
+        node: Option<(&str, &IndexMap<String, Vec<String>>)>,
+        aliases: &IndexMap<String, String>,
+    ) -> HashMap<String, ToolFilter> {
+        let mut filters: HashMap<String, ToolFilter> = HashMap::new();
+
+        for (server, spec) in &mcp_config.mcp_servers {
+            if let Some(patterns) = &spec.allowed_tools {
+                filters
+                    .entry(server.clone())
+                    .or_default()
+                    .push_layer(LayerSource::Global, patterns);
+            }
+        }
+
+        if let Some(map) = global {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::AppConfig,
+                map,
+                None,
+            );
+        }
+        if let Some((name, map)) = role {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::Role(name.to_string()),
+                map,
+                None,
+            );
+        }
+        if let Some((name, map)) = agent {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::Agent(name.to_string()),
+                map,
+                None,
+            );
+        }
+        if let Some(map) = session {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::Session,
+                map,
+                None,
+            );
+        }
+        for skill in skills {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::Skill(skill.name.clone()),
+                &skill.mcp_tools,
+                Some(&skill.enabled_servers),
+            );
+        }
+        if let Some((id, map)) = node {
+            push_level(
+                &mut filters,
+                mcp_config,
+                aliases,
+                &LayerSource::Node(id.to_string()),
+                map,
+                None,
+            );
+        }
+
+        filters
+    }
+}
+
+fn push_level(
+    filters: &mut HashMap<String, ToolFilter>,
+    mcp_config: &McpServersConfig,
+    aliases: &IndexMap<String, String>,
+    source: &LayerSource,
+    map: &IndexMap<String, Vec<String>>,
+    enabled_servers: Option<&[String]>,
+) {
+    for (server, patterns) in expand_server_keys(mcp_config, aliases, map) {
+        if let Some(enabled) = enabled_servers
+            && !enabled.iter().any(|id| id == &server)
+        {
+            continue;
+        }
+        filters
+            .entry(server)
+            .or_default()
+            .push_layer(source.clone(), &patterns);
+    }
+}
+
+fn expand_server_keys(
+    mcp_config: &McpServersConfig,
+    aliases: &IndexMap<String, String>,
+    map: &IndexMap<String, Vec<String>>,
+) -> IndexMap<String, Vec<String>> {
+    let mut expanded: IndexMap<String, Vec<String>> = IndexMap::new();
+    for (key, patterns) in map {
+        let key = key.trim();
+        if mcp_config.mcp_servers.contains_key(key) {
+            expanded
+                .entry(key.to_string())
+                .or_default()
+                .extend(patterns.iter().cloned());
+        } else {
+            for mapped_id in expand_mcp_server_alias(aliases, key) {
+                if mcp_config.mcp_servers.contains_key(&mapped_id) {
+                    expanded
+                        .entry(mapped_id)
+                        .or_default()
+                        .extend(patterns.iter().cloned());
+                }
+            }
+        }
+    }
+
+    expanded
+}
+
+pub(crate) fn expand_mcp_server_alias(
+    aliases: &IndexMap<String, String>,
+    key: &str,
+) -> Vec<String> {
+    aliases
+        .get(key)
+        .map(|mapped| {
+            mapped
+                .split(',')
+                .map(str::trim)
+                .filter(|id| !id.is_empty())
+                .map(str::to_string)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::{McpServer, McpServersConfig, McpTransportType};
+
+    fn spec(allowed_tools: Option<&[&str]>) -> McpServer {
+        McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: Some("echo".to_string()),
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: None,
+            oauth: None,
+            allowed_tools: allowed_tools.map(list),
+        }
+    }
+
+    fn config(servers: &[(&str, Option<&[&str]>)]) -> McpServersConfig {
+        McpServersConfig {
+            mcp_servers: servers
+                .iter()
+                .map(|(name, tools)| (name.to_string(), spec(*tools)))
+                .collect(),
+        }
+    }
+
+    fn list(items: &[&str]) -> Vec<String> {
+        items.iter().map(|s| s.to_string()).collect()
+    }
+
+    fn tool_map(entries: &[(&str, &[&str])]) -> IndexMap<String, Vec<String>> {
+        entries
+            .iter()
+            .map(|(server, patterns)| (server.to_string(), list(patterns)))
+            .collect()
+    }
+
+    fn single_layer(patterns: &[&str]) -> ToolFilter {
+        layered(&[(LayerSource::Global, patterns)])
+    }
+
+    fn layered(layers: &[(LayerSource, &[&str])]) -> ToolFilter {
+        let mut filter = ToolFilter::default();
+        for (source, patterns) in layers {
+            filter.push_layer(source.clone(), &list(patterns));
+        }
+        filter
+    }
+
+    fn no_aliases() -> IndexMap<String, String> {
+        IndexMap::new()
+    }
+
+    fn aliases(entries: &[(&str, &str)]) -> IndexMap<String, String> {
+        entries
+            .iter()
+            .map(|(key, value)| (key.to_string(), value.to_string()))
+            .collect()
+    }
+
+    fn resolve(
+        config: &McpServersConfig,
+        session: Option<&IndexMap<String, Vec<String>>>,
+        role: Option<(&str, &IndexMap<String, Vec<String>>)>,
+    ) -> HashMap<String, ToolFilter> {
+        McpToolPolicy::effective(config, session, None, role, None, &[], None, &no_aliases())
+    }
+
+    #[test]
+    fn literal_pattern_matches_only_the_exact_name() {
+        let filter = single_layer(&["get_issue"]);
+
+        assert!(filter.allows("get_issue"));
+        assert!(!filter.allows("get_issues"));
+        assert!(!filter.allows("get_issu"));
+        assert!(!filter.allows("xget_issue"));
+    }
+
+    #[test]
+    fn star_matches_any_run_of_characters() {
+        let filter = single_layer(&["get_*"]);
+        assert!(filter.allows("get_issue"));
+        assert!(filter.allows("get_"));
+        assert!(!filter.allows("set_issue"));
+
+        let filter = single_layer(&["*_issue"]);
+        assert!(filter.allows("create_issue"));
+        assert!(!filter.allows("create_pr"));
+
+        let filter = single_layer(&["get*sue"]);
+        assert!(filter.allows("get_issue"));
+        assert!(filter.allows("getsue"));
+
+        let filter = single_layer(&["*"]);
+        assert!(filter.allows(""));
+        assert!(filter.allows("anything_at_all"));
+    }
+
+    #[test]
+    fn question_mark_matches_exactly_one_character() {
+        let filter = single_layer(&["get_?"]);
+
+        assert!(filter.allows("get_a"));
+        assert!(!filter.allows("get_"));
+        assert!(!filter.allows("get_ab"));
+    }
+
+    #[test]
+    fn regex_metacharacters_are_matched_literally() {
+        let filter = single_layer(&["get.issue"]);
+        assert!(filter.allows("get.issue"));
+        assert!(!filter.allows("getXissue"));
+
+        for pattern in ["a(b", "a[b", "a+b", "a|b", "a$b"] {
+            let filter = single_layer(&[pattern]);
+            assert!(filter.allows(pattern), "'{pattern}' should match itself");
+            assert!(!filter.allows("ab"), "'{pattern}' should not match 'ab'");
+        }
+    }
+
+    #[test]
+    fn backslash_is_literal_and_star_still_wildcards() {
+        let filter = single_layer(&["a\\b"]);
+        assert!(filter.allows("a\\b"));
+        assert!(!filter.allows("ab"));
+
+        let filter = single_layer(&["a\\*b"]);
+        assert!(filter.allows("a\\b"));
+        assert!(filter.allows("a\\xyzb"));
+        assert!(!filter.allows("ab"));
+    }
+
+    #[test]
+    fn the_never_matching_placeholder_matches_nothing() {
+        let regex = never_matching_regex();
+
+        assert!(!regex.is_match("").unwrap());
+        assert!(!regex.is_match("anything").unwrap());
+    }
+
+    #[test]
+    fn within_a_layer_any_pattern_may_match() {
+        let filter = single_layer(&["get_*", "set_*"]);
+
+        assert!(filter.allows("get_x"));
+        assert!(filter.allows("set_x"));
+        assert!(!filter.allows("delete_x"));
+    }
+
+    #[test]
+    fn across_layers_every_layer_must_match() {
+        let filter = layered(&[
+            (LayerSource::Global, &["get_*"]),
+            (LayerSource::Session, &["*_issue"]),
+        ]);
+
+        assert!(filter.allows("get_issue"));
+        assert!(!filter.allows("get_pr"));
+        assert!(!filter.allows("create_issue"));
+    }
+
+    #[test]
+    fn an_empty_layer_blocks_everything() {
+        let filter = layered(&[(LayerSource::Global, &["*"]), (LayerSource::Session, &[])]);
+
+        assert!(!filter.allows("anything"));
+        assert_eq!(
+            filter.allows_explain("anything"),
+            Err(&LayerSource::Session)
+        );
+    }
+
+    #[test]
+    fn allows_explain_reports_the_first_matching_pattern_per_layer() {
+        let filter = layered(&[
+            (LayerSource::Global, &["x_*", "get_*"]),
+            (LayerSource::Session, &["*"]),
+        ]);
+
+        assert_eq!(
+            filter.allows_explain("get_issue").unwrap(),
+            vec![
+                (&LayerSource::Global, "get_*"),
+                (&LayerSource::Session, "*")
+            ]
+        );
+    }
+
+    #[test]
+    fn allows_explain_reports_the_first_layer_without_a_match() {
+        let filter = layered(&[
+            (LayerSource::Global, &["get_*"]),
+            (LayerSource::Session, &["*"]),
+        ]);
+        assert_eq!(
+            filter.allows_explain("delete_repo"),
+            Err(&LayerSource::Global)
+        );
+
+        let filter = layered(&[
+            (LayerSource::Global, &["*"]),
+            (LayerSource::Session, &["get_*"]),
+        ]);
+        assert_eq!(
+            filter.allows_explain("delete_repo"),
+            Err(&LayerSource::Session)
+        );
+    }
+
+    #[test]
+    fn global_allowed_tools_from_mcp_json_is_the_first_layer() {
+        let config = config(&[("gh", Some(&["get_*"]))]);
+        let session_map = tool_map(&[("gh", &["*"])]);
+
+        let filters = resolve(&config, Some(&session_map), None);
+
+        assert_eq!(
+            filters["gh"].allows_explain("get_issue").unwrap(),
+            vec![
+                (&LayerSource::Global, "get_*"),
+                (&LayerSource::Session, "*")
+            ]
+        );
+    }
+
+    #[test]
+    fn servers_without_patterns_at_any_level_are_absent() {
+        let config = config(&[("gh", None)]);
+
+        let filters = resolve(&config, None, None);
+
+        assert!(filters.is_empty());
+    }
+
+    #[test]
+    fn server_absent_from_a_level_map_gets_no_layer_from_it() {
+        let config = config(&[("gh", Some(&["get_*"])), ("gl", None)]);
+        let role_map = tool_map(&[("gl", &["x_*"])]);
+
+        let filters = resolve(&config, None, Some(("dev", &role_map)));
+
+        assert!(filters["gh"].allows("get_issue"));
+        assert!(!filters["gh"].allows("delete_repo"));
+        assert_eq!(filters["gh"].allows_explain("get_issue").unwrap().len(), 1);
+        assert!(filters["gl"].allows("x_1"));
+        assert!(!filters["gl"].allows("y_1"));
+    }
+
+    #[test]
+    fn empty_pattern_list_at_a_level_blocks_all_tools_for_that_server() {
+        let config = config(&[("gh", Some(&["get_*"]))]);
+        let session_map = tool_map(&[("gh", &[])]);
+
+        let filters = resolve(&config, Some(&session_map), None);
+
+        assert!(!filters["gh"].allows("get_issue"));
+        assert_eq!(
+            filters["gh"].allows_explain("get_issue"),
+            Err(&LayerSource::Session)
+        );
+    }
+
+    #[test]
+    fn session_cannot_widen_a_role_restriction() {
+        let config = config(&[("gh", None)]);
+        let role_map = tool_map(&[("gh", &["get_*"])]);
+        let session_map = tool_map(&[("gh", &["*"])]);
+
+        let filters = resolve(&config, Some(&session_map), Some(("dev", &role_map)));
+
+        assert!(filters["gh"].allows("get_issue"));
+        assert!(!filters["gh"].allows("delete_repo"));
+    }
+
+    #[test]
+    fn app_config_map_contributes_its_own_layer() {
+        let config = config(&[("gh", None)]);
+        let app_map = tool_map(&[("gh", &["get_*"])]);
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            None,
+            Some(&app_map),
+            &[],
+            None,
+            &no_aliases(),
+        );
+
+        assert_eq!(
+            filters["gh"].allows_explain("get_issue").unwrap(),
+            vec![(&LayerSource::AppConfig, "get_*")]
+        );
+        assert!(!filters["gh"].allows("delete_repo"));
+    }
+
+    #[test]
+    fn skill_layer_applies_only_to_its_enabled_servers() {
+        let config = config(&[("gh", None), ("gl", None)]);
+        let skill = SkillMcpLayer {
+            name: "reviewer".to_string(),
+            enabled_servers: vec!["gh".to_string()],
+            mcp_tools: tool_map(&[("gh", &["get_*"]), ("gl", &["*"])]),
+        };
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            None,
+            None,
+            &[skill],
+            None,
+            &no_aliases(),
+        );
+
+        assert!(filters.contains_key("gh"));
+        assert!(!filters.contains_key("gl"));
+    }
+
+    #[test]
+    fn two_skills_naming_the_same_server_stack_independent_layers() {
+        let config = config(&[("gh", None)]);
+        let skills = vec![
+            SkillMcpLayer {
+                name: "a".to_string(),
+                enabled_servers: vec!["gh".to_string()],
+                mcp_tools: tool_map(&[("gh", &["get_*"])]),
+            },
+            SkillMcpLayer {
+                name: "b".to_string(),
+                enabled_servers: vec!["gh".to_string()],
+                mcp_tools: tool_map(&[("gh", &["*_issue"])]),
+            },
+        ];
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            None,
+            None,
+            &skills,
+            None,
+            &no_aliases(),
+        );
+
+        assert!(filters["gh"].allows("get_issue"));
+        assert!(!filters["gh"].allows("get_pr"));
+        assert!(!filters["gh"].allows("create_issue"));
+        assert_eq!(filters["gh"].allows_explain("get_issue").unwrap().len(), 2);
+    }
+
+    #[test]
+    fn layers_stack_in_documented_order_with_node_last() {
+        let config = config(&[("gh", Some(&["*"]))]);
+        let app_map = tool_map(&[("gh", &["*"])]);
+        let role_map = tool_map(&[("gh", &["*"])]);
+        let agent_map = tool_map(&[("gh", &["*"])]);
+        let session_map = tool_map(&[("gh", &["*"])]);
+        let skills = vec![SkillMcpLayer {
+            name: "reviewer".to_string(),
+            enabled_servers: vec!["gh".to_string()],
+            mcp_tools: tool_map(&[("gh", &["*"])]),
+        }];
+        let node_map = tool_map(&[("gh", &["*"])]);
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            Some(&session_map),
+            Some(("worker", &agent_map)),
+            Some(("dev", &role_map)),
+            Some(&app_map),
+            &skills,
+            Some(("n1", &node_map)),
+            &no_aliases(),
+        );
+
+        let sources: Vec<String> = filters["gh"]
+            .allows_explain("anything")
+            .unwrap()
+            .iter()
+            .map(|(source, _)| source.to_string())
+            .collect();
+        assert_eq!(
+            sources,
+            vec![
+                "global (mcp.json)",
+                "config (config.yaml)",
+                "role (dev)",
+                "agent (worker)",
+                "session (.set)",
+                "skill (reviewer)",
+                "node (n1)",
+            ]
+        );
+    }
+
+    #[test]
+    fn alias_key_expands_to_all_mapped_servers() {
+        let config = config(&[("github", None), ("gitlab", None)]);
+        let role_map = tool_map(&[("gh", &["get_*"])]);
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            Some(("dev", &role_map)),
+            None,
+            &[],
+            None,
+            &aliases(&[("gh", "github,gitlab")]),
+        );
+
+        assert!(filters["github"].allows("get_issue"));
+        assert!(!filters["github"].allows("delete_repo"));
+        assert!(filters["gitlab"].allows("get_issue"));
+        assert!(!filters["gitlab"].allows("delete_repo"));
+    }
+
+    #[test]
+    fn alias_ids_missing_from_the_config_are_skipped() {
+        let config = config(&[("github", None)]);
+        let role_map = tool_map(&[("gh", &["get_*"])]);
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            Some(("dev", &role_map)),
+            None,
+            &[],
+            None,
+            &aliases(&[("gh", "github,missing")]),
+        );
+
+        assert_eq!(filters.len(), 1);
+        assert!(filters.contains_key("github"));
+    }
+
+    #[test]
+    fn unknown_map_keys_are_dropped() {
+        let config = config(&[("github", None)]);
+        let role_map = tool_map(&[("nope", &["get_*"])]);
+
+        let filters = resolve(&config, None, Some(("dev", &role_map)));
+
+        assert!(filters.is_empty());
+    }
+
+    #[test]
+    fn alias_and_direct_key_for_the_same_server_merge_into_one_layer() {
+        let config = config(&[("github", None)]);
+        let role_map = tool_map(&[("gh", &["get_*"]), ("github", &["set_*"])]);
+
+        let filters = McpToolPolicy::effective(
+            &config,
+            None,
+            None,
+            Some(("dev", &role_map)),
+            None,
+            &[],
+            None,
+            &aliases(&[("gh", "github")]),
+        );
+
+        assert!(filters["github"].allows("get_issue"));
+        assert!(filters["github"].allows("set_topic"));
+        assert!(!filters["github"].allows("delete_repo"));
+        assert_eq!(
+            filters["github"].allows_explain("get_issue").unwrap().len(),
+            1
+        );
+    }
+
+    #[test]
+    fn layer_source_display() {
+        assert_eq!(LayerSource::Global.to_string(), "global (mcp.json)");
+        assert_eq!(LayerSource::AppConfig.to_string(), "config (config.yaml)");
+        assert_eq!(LayerSource::Role("dev".into()).to_string(), "role (dev)");
+        assert_eq!(
+            LayerSource::Agent("worker".into()).to_string(),
+            "agent (worker)"
+        );
+        assert_eq!(LayerSource::Session.to_string(), "session (.set)");
+        assert_eq!(
+            LayerSource::Skill("review".into()).to_string(),
+            "skill (review)"
+        );
+        assert_eq!(LayerSource::Node("n1".into()).to_string(), "node (n1)");
+    }
+
+    #[test]
+    fn dead_context_patterns_flags_patterns_matching_nothing() {
+        let filter = layered(&[
+            (LayerSource::Global, &["get_*"]),
+            (LayerSource::Role("dev".into()), &["get_issue", "set_*"]),
+        ]);
+
+        let advertised = vec!["get_issue".to_string(), "set_topic".to_string()];
+        let dead = filter.dead_context_patterns(&advertised);
+
+        // set_* only matches set_topic, which the global layer hides.
+        assert_eq!(dead, vec![(&LayerSource::Role("dev".into()), "set_*")]);
+    }
+
+    #[test]
+    fn dead_context_patterns_is_empty_when_every_pattern_is_live() {
+        let filter = layered(&[
+            (LayerSource::Global, &["get_*"]),
+            (LayerSource::Session, &["get_issue"]),
+        ]);
+
+        let advertised = vec!["get_issue".to_string()];
+        assert!(filter.dead_context_patterns(&advertised).is_empty());
+    }
+
+    #[test]
+    fn dead_context_patterns_ignores_the_global_layer_itself() {
+        let filter = layered(&[(LayerSource::Global, &["zzz_*"])]);
+
+        let advertised = vec!["get_issue".to_string()];
+        assert!(filter.dead_context_patterns(&advertised).is_empty());
+    }
+
+    #[test]
+    fn expand_mcp_server_alias_splits_and_trims() {
+        let aliases = aliases(&[("gh", "github, gitlab,")]);
+
+        assert_eq!(
+            expand_mcp_server_alias(&aliases, "gh"),
+            vec!["github".to_string(), "gitlab".to_string()]
+        );
+        assert!(expand_mcp_server_alias(&aliases, "nope").is_empty());
+    }
+}

src/config/mod.rs

@@ -1,11 +1,14 @@
 mod agent;
 mod app_config;
 mod app_state;
+mod bundles;
 mod input;
 mod install_remote;
 pub(crate) mod instructions;
+mod macro_policy;
 mod macros;
 mod mcp_factory;
+mod mcp_tool_policy;
 pub(crate) mod memory;
 pub(crate) mod paths;
 pub(crate) mod prompts;
@@ -20,6 +23,8 @@ pub(crate) mod todo;
 mod tool_scope;
 mod update;
 
+#[cfg(test)]
+pub(crate) use self::agent::AgentConfig;
 pub use self::agent::{
     Agent, AgentVariable, AgentVariables, complete_agent_variables, list_agents,
     list_agents_with_descriptions,
@@ -28,10 +33,23 @@ pub use self::agent::{
 pub use self::app_config::AppConfig;
 #[allow(unused_imports)]
 pub use self::app_state::AppState;
+pub use self::bundles::list_installed_bundles;
 pub use self::input::Input;
-pub use self::install_remote::{install_remote, install_remote_from_repl_args};
+pub use self::install_remote::{
+    DEFAULT_GIT_HOST, install_or_update, install_or_update_from_repl_args, uninstall_bundle,
+    update_bundle,
+};
+pub use self::macro_policy::{
+    MacroAllowlistLevel, MacroPolicy, MacroSource, MacroState, RESERVED_MACRO_NAMES, ResolvedMacro,
+};
+pub(crate) use self::mcp_tool_policy::expand_mcp_server_alias;
+#[cfg(test)]
+pub(crate) use self::mcp_tool_policy::{LayerSource, ToolFilter};
 #[allow(unused_imports)]
-pub use self::request_context::{RenderMode, RequestContext, should_inject_skill_instructions};
+pub use self::request_context::{
+    RenderMode, RequestContext, effective_max_concurrent_jobs, jobs_enabled,
+    should_inject_skill_instructions,
+};
 pub use self::role::{
     CODE_ROLE, CREATE_TITLE_ROLE, EXPLAIN_SHELL_ROLE, Role, RoleLike, SHELL_ROLE,
 };
@@ -42,6 +60,12 @@ pub use self::skill::Skill;
 pub use self::skill_policy::SkillPolicy;
 #[allow(unused_imports)]
 pub use self::skill_registry::SkillRegistry;
+#[cfg(test)]
+pub(crate) use self::tool_scope::test_fixtures;
+pub use self::tool_scope::{
+    McpPromptCompletion, McpRuntime, flatten_prompt_messages, resolve_prompt_args,
+    sanitize_display_text,
+};
 pub use self::update::run_self_update;
 use crate::client::{
     self, ClientConfig, MessageContentToolCalls, Model, ModelType, OPENAI_COMPATIBLE_PROVIDERS,
@@ -126,6 +150,9 @@ fn validate_no_template_in_secrets_provider(content: &str) -> Result<()> {
 const DARK_THEME: &[u8] = include_bytes!("../../assets/monokai-extended.theme.bin");
 const LIGHT_THEME: &[u8] = include_bytes!("../../assets/monokai-extended-light.theme.bin");
 
+/// Fully documented config skeleton the first-run wizard splices dynamic values into.
+const CONFIG_TEMPLATE: &str = include_str!("../../assets/config-template.yaml");
+
 const CONFIG_FILE_NAME: &str = "config.yaml";
 const AGENT_GRAPH_FILE_NAME: &str = "graph.yaml";
 const ROLES_DIR_NAME: &str = "roles";
@@ -151,30 +178,11 @@ 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";
 pub(crate) const VAULT_DATA_FILE_NAME: &str = "vault.yml";
+const INSTALLED_BUNDLES_FILE_NAME: &str = "installed-bundles.yaml";
+const BUNDLE_MANIFEST_FILE: &str = "coyote-bundle.yaml";
 const SBX_MIXIN_KITS_DIR_NAME: &str = "sbx-mixin-kits";
 const GIT_DIR_NAME: &str = ".git";
 const GITIGNORE_FILE_NAME: &str = ".gitignore";
-const DEFAULT_VISIBLE_TOOLS: [&str; 19] = [
-    "execute_command.sh",
-    "execute_py_code.py",
-    "execute_sql_code.sh",
-    "fetch_url_via_curl.sh",
-    "fs_cat.sh",
-    "fs_glob.sh",
-    "fs_grep.sh",
-    "fs_ls.sh",
-    "fs_mkdir.sh",
-    "fs_patch.sh",
-    "fs_read.sh",
-    "fs_rm.sh",
-    "fs_write.sh",
-    "ast_grep.sh",
-    "get_current_time.sh",
-    "get_current_weather.sh",
-    "search_wikipedia.sh",
-    "search_arxiv.sh",
-    "web_search_coyote.sh",
-];
 
 const CLIENTS_FIELD: &str = "clients";
 
@@ -221,11 +229,14 @@ pub struct Config {
     #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
     pub enabled_skills: Option<Vec<String>>,
     pub visible_skills: Option<Vec<String>>,
+    #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
+    pub enabled_macros: Option<Vec<String>>,
 
     pub mcp_server_support: bool,
     pub mapping_mcp_servers: IndexMap<String, String>,
     #[serde(default, deserialize_with = "deserialize_csv_or_vec")]
     pub enabled_mcp_servers: Option<Vec<String>>,
+    pub mcp_tools: Option<IndexMap<String, Vec<String>>>,
 
     pub auto_continue: bool,
     pub max_auto_continues: usize,
@@ -244,6 +255,7 @@ pub struct Config {
     pub summarization_prompt: Option<String>,
     pub summary_context_prompt: Option<String>,
     pub max_tool_result_chars: Option<usize>,
+    pub max_concurrent_jobs: Option<usize>,
 
     pub memory: Option<bool>,
     pub memory_cap_with_tools: Option<usize>,
@@ -303,10 +315,12 @@ impl Default for Config {
             skills_enabled: true,
             enabled_skills: None,
             visible_skills: None,
+            enabled_macros: None,
 
             mcp_server_support: true,
             mapping_mcp_servers: Default::default(),
             enabled_mcp_servers: None,
+            mcp_tools: None,
 
             auto_continue: false,
             max_auto_continues: 10,
@@ -325,6 +339,7 @@ impl Default for Config {
             summarization_prompt: None,
             summary_context_prompt: None,
             max_tool_result_chars: None,
+            max_concurrent_jobs: None,
 
             memory: None,
             memory_cap_with_tools: None,
@@ -374,12 +389,12 @@ pub enum AssetCategory {
     Macros,
     Functions,
     Skills,
-    #[value(name = "mcp_config")]
+    #[value(name = "mcp-config", alias = "mcp_config")]
     McpConfig,
 }
 
 impl AssetCategory {
-    pub const NAMES: [&'static str; 5] = ["agents", "macros", "functions", "skills", "mcp_config"];
+    pub const NAMES: [&'static str; 5] = ["agents", "macros", "functions", "skills", "mcp-config"];
 
     pub fn parse(name: &str) -> Option<Self> {
         match name {
@@ -387,7 +402,7 @@ impl AssetCategory {
             "macros" => Some(Self::Macros),
             "functions" => Some(Self::Functions),
             "skills" => Some(Self::Skills),
-            "mcp_config" => Some(Self::McpConfig),
+            "mcp-config" | "mcp_config" => Some(Self::McpConfig),
             _ => None,
         }
     }
@@ -406,7 +421,7 @@ pub enum InstallFilter {
     Skills,
     Macros,
     Functions,
-    #[value(name = "mcp_config")]
+    #[value(name = "mcp-config", alias = "mcp_config")]
     McpConfig,
 }
 
@@ -417,7 +432,7 @@ impl InstallFilter {
         "skills",
         "macros",
         "functions",
-        "mcp_config",
+        "mcp-config",
     ];
 
     pub fn parse(name: &str) -> Option<Self> {
@@ -427,7 +442,7 @@ impl InstallFilter {
             "skills" => Some(Self::Skills),
             "macros" => Some(Self::Macros),
             "functions" => Some(Self::Functions),
-            "mcp_config" => Some(Self::McpConfig),
+            "mcp-config" | "mcp_config" => Some(Self::McpConfig),
             _ => None,
         }
     }
@@ -778,51 +793,20 @@ pub async fn create_config_file(config_path: &Path) -> Result<()> {
 
     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();
-    match &provider_choice {
-        None => {
-            config["vault_password_file"] =
-                vault.local_password_file()?.display().to_string().into();
-        }
+    let secrets = match &provider_choice {
+        None => json!({
+            "vault_password_file": vault.local_password_file()?.display().to_string()
+        }),
         Some(provider) => {
-            config["secrets_provider"] = serde_json::to_value(provider)
+            let provider = serde_json::to_value(provider)
                 .with_context(|| "failed to serialize secrets_provider config")?;
+            json!({ "secrets_provider": provider })
         }
-    }
-    config["stream"] = json!(true);
-    config["save"] = json!(true);
-    config["keybindings"] = json!("vi");
-    config["wrap"] = json!("auto");
-    config["wrap_code"] = json!(false);
-    config["function_calling_support"] = json!(true);
-    config["enabled_tools"] = json!(null);
-    config["visible_tools"] = json!(DEFAULT_VISIBLE_TOOLS);
-    config["mcp_server_support"] = json!(true);
-    config["enabled_mcp_servers"] = json!(null);
-    config["highlight"] = json!(true);
-    config["light_theme"] = json!(false);
-    config[CLIENTS_FIELD] = clients_config;
+    };
 
-    let config_data = serde_yaml::to_string(&config).with_context(|| "Failed to create config")?;
-    let config_data = format!(
-        "# see https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml\n\n{config_data}"
-    );
-
-    ensure_parent_exists(config_path)?;
-    std::fs::write(config_path, config_data)
-        .with_context(|| format!("Failed to write to '{}'", config_path.display()))?;
-    #[cfg(unix)]
-    {
-        use std::os::unix::prelude::PermissionsExt;
-        let perms = std::fs::Permissions::from_mode(0o600);
-        std::fs::set_permissions(config_path, perms)?;
-    }
-
-    println!("✓ Saved the config file to '{}'.\n", config_path.display());
-
-    Ok(())
+    let config_data = render_config_template(&model, Some(&secrets), &clients_config)?;
+    write_config_file(config_path, &config_data)
 }
 
 async fn create_config_file_sandbox(config_path: &Path) -> Result<()> {
@@ -832,7 +816,7 @@ async fn create_config_file_sandbox(config_path: &Path) -> Result<()> {
         "Running in sandbox mode — your API provider credentials are managed by your host Coyote configuration if configured."
     );
 
-    let oai_api_base = client::OPENAI_COMPATIBLE_PROVIDERS
+    let oai_api_base = OPENAI_COMPATIBLE_PROVIDERS
         .iter()
         .find(|(name, _)| *name == client)
         .map(|(_, url)| *url);
@@ -845,13 +829,13 @@ async fn create_config_file_sandbox(config_path: &Path) -> Result<()> {
         } else {
             api_base.to_string()
         };
-        serde_json::json!({
+        json!({
             "type": "openai-compatible",
             "name": client,
             "api_base": api_base_str,
         })
     } else {
-        serde_json::json!({ "type": client })
+        json!({ "type": client })
     };
 
     if client::client_type_supports_oauth(client) {
@@ -865,27 +849,45 @@ async fn create_config_file_sandbox(config_path: &Path) -> Result<()> {
 
     let model = set_client_models_config(&mut client_config, client).await?;
 
-    let mut config = serde_json::json!({});
-    config["model"] = model.into();
-    config["stream"] = serde_json::json!(true);
-    config["save"] = serde_json::json!(true);
-    config["keybindings"] = serde_json::json!("vi");
-    config["wrap"] = serde_json::json!("auto");
-    config["wrap_code"] = serde_json::json!(false);
-    config["function_calling_support"] = serde_json::json!(true);
-    config["enabled_tools"] = serde_json::json!(null);
-    config["visible_tools"] = serde_json::json!(DEFAULT_VISIBLE_TOOLS);
-    config["mcp_server_support"] = serde_json::json!(true);
-    config["enabled_mcp_servers"] = serde_json::json!(null);
-    config["highlight"] = serde_json::json!(true);
-    config["light_theme"] = serde_json::json!(false);
-    config[CLIENTS_FIELD] = serde_json::json!(vec![client_config]);
+    let config_data = render_config_template(&model, None, &json!([client_config]))?;
+    write_config_file(config_path, &config_data)
+}
 
-    let config_data = serde_yaml::to_string(&config).with_context(|| "Failed to create config")?;
-    let config_data = format!(
-        "# see https://github.com/Dark-Alex-17/coyote/blob/main/config.example.yaml\n\n{config_data}"
-    );
+fn render_config_template(
+    model: &str,
+    secrets: Option<&serde_json::Value>,
+    clients: &serde_json::Value,
+) -> Result<String> {
+    render_config_template_from(CONFIG_TEMPLATE, model, secrets, clients)
+}
 
+fn render_config_template_from(
+    template: &str,
+    model: &str,
+    secrets: Option<&serde_json::Value>,
+    clients: &serde_json::Value,
+) -> Result<String> {
+    let to_yaml = |value: &serde_json::Value| {
+        serde_yaml::to_string(value).with_context(|| "Failed to create config")
+    };
+
+    let model_block = to_yaml(&json!({ "model": model }))?;
+    let secrets_block = match secrets {
+        Some(value) => to_yaml(value)?,
+        None => "# Sandbox mode: no vault provider is configured; secrets are provisioned\n\
+                 # from the host when the sandbox is created.\n"
+            .to_string(),
+    };
+    let clients_block = to_yaml(&json!({ CLIENTS_FIELD: clients }))?;
+
+    Ok(template
+        .replace("\r\n", "\n")
+        .replacen("__MODEL_BLOCK__\n", &model_block, 1)
+        .replacen("__SECRETS_BLOCK__\n", &secrets_block, 1)
+        .replacen("__CLIENTS_BLOCK__\n", &clients_block, 1))
+}
+
+fn write_config_file(config_path: &Path, config_data: &str) -> Result<()> {
     ensure_parent_exists(config_path)?;
     std::fs::write(config_path, config_data)
         .with_context(|| format!("Failed to write to '{}'", config_path.display()))?;
@@ -1101,6 +1103,17 @@ clients:
         assert!(validate_no_template_in_secrets_provider(yaml).is_ok());
     }
 
+    #[test]
+    fn config_yaml_parses_mcp_tools() {
+        let cfg: Config = serde_yaml::from_str("mcp_tools:\n  github:\n    - get_*\n").unwrap();
+
+        assert_eq!(
+            cfg.mcp_tools.as_ref().unwrap().get("github"),
+            Some(&vec!["get_*".to_string()])
+        );
+        assert_eq!(Config::default().mcp_tools, None);
+    }
+
     #[test]
     fn config_defaults_match_expected() {
         let cfg = Config::default();
@@ -1124,9 +1137,119 @@ clients:
         assert!(cfg.enabled_mcp_servers.is_none());
     }
 
+    #[test]
+    fn config_enabled_macros_absent_is_none() {
+        let cfg: Config = serde_yaml::from_str("model: provider:test").unwrap();
+        assert_eq!(cfg.enabled_macros, None);
+    }
+
+    #[test]
+    fn config_template_renders_parseable_config() {
+        let secrets = json!({ "vault_password_file": "/home/user/.coyote_password" });
+        let clients = json!([{ "type": "openai", "api_key": "sk-test" }]);
+
+        let rendered = render_config_template("openai:gpt-4o", Some(&secrets), &clients).unwrap();
+
+        assert!(!rendered.contains("__MODEL_BLOCK__"));
+        assert!(!rendered.contains("__SECRETS_BLOCK__"));
+        assert!(!rendered.contains("__CLIENTS_BLOCK__"));
+
+        let cfg = Config::load_from_str(&rendered).unwrap();
+        assert_eq!(cfg.model_id, "openai:gpt-4o");
+        assert_eq!(
+            cfg.vault_password_file,
+            Some(PathBuf::from("/home/user/.coyote_password"))
+        );
+        assert!(cfg.secrets_provider.is_none());
+        assert_eq!(cfg.keybindings, "emacs");
+        assert!(cfg.save);
+        assert_eq!(cfg.wrap.as_deref(), Some("auto"));
+        assert!(cfg.visible_tools.is_none());
+        assert!(cfg.mapping_tools.is_empty());
+        assert!(cfg.document_loaders.is_empty());
+        assert_eq!(cfg.compression_threshold, 4000);
+        assert!(cfg.theme.is_none());
+        assert_eq!(cfg.clients.len(), 1);
+    }
+
+    #[test]
+    fn config_template_renders_parseable_sandbox_config() {
+        let clients = json!([{ "type": "claude" }]);
+
+        let rendered =
+            render_config_template("claude:claude-sonnet-4-20250514", None, &clients).unwrap();
+
+        assert!(!rendered.contains("__SECRETS_BLOCK__"));
+
+        let cfg = Config::load_from_str(&rendered).unwrap();
+        assert_eq!(cfg.model_id, "claude:claude-sonnet-4-20250514");
+        assert!(cfg.vault_password_file.is_none());
+        assert!(cfg.secrets_provider.is_none());
+        assert_eq!(cfg.keybindings, "emacs");
+        assert!(cfg.save);
+        assert!(cfg.visible_tools.is_none());
+        assert_eq!(cfg.compression_threshold, 4000);
+        assert_eq!(cfg.clients.len(), 1);
+    }
+
+    #[test]
+    fn config_template_renders_with_crlf_line_endings() {
+        let crlf_template = CONFIG_TEMPLATE.replace('\n', "\r\n");
+        let secrets = json!({ "vault_password_file": "/home/user/.coyote_password" });
+        let clients = json!([{ "type": "openai", "api_key": "sk-test" }]);
+
+        let rendered =
+            render_config_template_from(&crlf_template, "openai:gpt-4o", Some(&secrets), &clients)
+                .unwrap();
+
+        assert!(!rendered.contains("__MODEL_BLOCK__"));
+        assert!(!rendered.contains("__SECRETS_BLOCK__"));
+        assert!(!rendered.contains("__CLIENTS_BLOCK__"));
+        assert!(!rendered.contains('\r'));
+
+        let cfg = Config::load_from_str(&rendered).unwrap();
+        assert_eq!(cfg.model_id, "openai:gpt-4o");
+        assert_eq!(cfg.clients.len(), 1);
+    }
+
+    #[test]
+    fn config_enabled_macros_empty_string_is_some_empty() {
+        let cfg: Config = serde_yaml::from_str("enabled_macros: \"\"").unwrap();
+
+        assert_eq!(cfg.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    fn config_enabled_macros_csv_string() {
+        let cfg: Config = serde_yaml::from_str("enabled_macros: \"a, b\"").unwrap();
+
+        assert_eq!(
+            cfg.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+    }
+
+    #[test]
+    fn config_enabled_macros_list() {
+        let cfg: Config = serde_yaml::from_str("enabled_macros:\n  - a\n  - b").unwrap();
+
+        assert_eq!(
+            cfg.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+    }
+
+    #[test]
+    fn config_enabled_macros_null_is_none() {
+        let cfg: Config = serde_yaml::from_str("enabled_macros: null").unwrap();
+
+        assert_eq!(cfg.enabled_macros, None);
+    }
+
     #[test]
     fn assert_state_pass_always_true() {
         let pass = AssertState::pass();
+
         assert!(pass.assert(StateFlags::empty()));
         assert!(pass.assert(StateFlags::ROLE));
         assert!(pass.assert(StateFlags::SESSION | StateFlags::AGENT));
@@ -1136,6 +1259,7 @@ clients:
     #[test]
     fn assert_state_bare_only_empty() {
         let bare = AssertState::bare();
+
         assert!(bare.assert(StateFlags::empty()));
         assert!(!bare.assert(StateFlags::ROLE));
         assert!(!bare.assert(StateFlags::SESSION));
@@ -1144,6 +1268,7 @@ clients:
     #[test]
     fn assert_state_true_requires_flag_present() {
         let state = AssertState::True(StateFlags::ROLE);
+
         assert!(state.assert(StateFlags::ROLE));
         assert!(state.assert(StateFlags::ROLE | StateFlags::SESSION));
         assert!(!state.assert(StateFlags::empty()));
@@ -1153,6 +1278,7 @@ clients:
     #[test]
     fn assert_state_true_with_multiple_flags_any_match() {
         let state = AssertState::True(StateFlags::SESSION_EMPTY | StateFlags::SESSION);
+
         assert!(state.assert(StateFlags::SESSION_EMPTY));
         assert!(state.assert(StateFlags::SESSION));
         assert!(state.assert(StateFlags::SESSION | StateFlags::ROLE));
@@ -1163,6 +1289,7 @@ clients:
     #[test]
     fn assert_state_false_requires_flag_absent() {
         let state = AssertState::False(StateFlags::AGENT);
+
         assert!(state.assert(StateFlags::empty()));
         assert!(state.assert(StateFlags::ROLE));
         assert!(!state.assert(StateFlags::AGENT));
@@ -1172,6 +1299,7 @@ clients:
     #[test]
     fn assert_state_false_with_multiple_flags() {
         let state = AssertState::False(StateFlags::SESSION | StateFlags::AGENT);
+
         assert!(state.assert(StateFlags::empty()));
         assert!(state.assert(StateFlags::ROLE));
         assert!(!state.assert(StateFlags::SESSION));
@@ -1182,6 +1310,7 @@ clients:
     #[test]
     fn assert_state_truefalse_requires_true_present_and_false_absent() {
         let state = AssertState::TrueFalse(StateFlags::ROLE, StateFlags::SESSION);
+
         assert!(state.assert(StateFlags::ROLE));
         assert!(state.assert(StateFlags::ROLE | StateFlags::RAG));
         assert!(!state.assert(StateFlags::empty()));
@@ -1192,6 +1321,7 @@ clients:
     #[test]
     fn assert_state_equal_exact_match() {
         let state = AssertState::Equal(StateFlags::ROLE | StateFlags::SESSION);
+
         assert!(state.assert(StateFlags::ROLE | StateFlags::SESSION));
         assert!(!state.assert(StateFlags::ROLE));
         assert!(!state.assert(StateFlags::SESSION));

src/config/paths.rs

@@ -2,10 +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, HIDDEN_MCP_FILE_NAME, MACROS_DIR_NAME, MCP_FILE_NAME,
-    MEMORY_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_MIXIN_KITS_DIR_NAME,
-    SKILLS_DIR_NAME, WORKSPACE_COYOTE_DIR_NAME,
+    GLOBAL_TOOLS_UTILS_DIR_NAME, HIDDEN_MCP_FILE_NAME, INSTALLED_BUNDLES_FILE_NAME,
+    MACROS_DIR_NAME, MCP_FILE_NAME, MEMORY_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_MIXIN_KITS_DIR_NAME, SKILLS_DIR_NAME, WORKSPACE_COYOTE_DIR_NAME,
 };
 use crate::client::ProviderModels;
 use crate::config::REPL_HISTORY_DIR_NAME;
@@ -148,6 +148,16 @@ pub fn sbx_kit_hash_file() -> PathBuf {
     sbx_kit_dir().join(SBX_KIT_HASH_FILE)
 }
 
+pub fn sandbox_mixin_hashes_dir() -> PathBuf {
+    cache_dir().join("sandbox-mixin-hashes")
+}
+
+pub fn sandbox_mixin_hash_file(sandbox_name: &str) -> PathBuf {
+    // Sandbox names are sanitized by the caller, but never trust a path
+    // component: a stray separator must not escape the hash directory.
+    sandbox_mixin_hashes_dir().join(format!("{}.hash", sandbox_name.replace('/', "_")))
+}
+
 pub fn sbx_mixin_kits_dir() -> PathBuf {
     cache_dir().join(SBX_MIXIN_KITS_DIR_NAME)
 }
@@ -159,6 +169,10 @@ pub fn config_file() -> PathBuf {
     }
 }
 
+pub fn installed_bundles_file() -> PathBuf {
+    local_dir(INSTALLED_BUNDLES_FILE_NAME)
+}
+
 pub fn roles_dir() -> PathBuf {
     match env::var(get_env_name("roles_dir")) {
         Ok(value) => PathBuf::from(value),
@@ -204,6 +218,10 @@ pub fn workspace_skill_file(name: &str) -> PathBuf {
     workspace_skills_dir().join(name).join("SKILL.md")
 }
 
+pub fn workspace_macros_dir() -> PathBuf {
+    workspace_config_dir().join(MACROS_DIR_NAME)
+}
+
 pub fn workspace_mcp_config_file() -> Option<PathBuf> {
     workspace_mcp_config_file_in(&env::current_dir().unwrap_or_default())
 }
@@ -269,6 +287,18 @@ pub fn functions_bin_dir() -> PathBuf {
 }
 
 pub fn mcp_config_file() -> PathBuf {
+    let preferred = local_dir(MCP_FILE_NAME);
+    if preferred.exists() {
+        return preferred;
+    }
+    let legacy = legacy_mcp_config_file();
+    if legacy.exists() {
+        return legacy;
+    }
+    preferred
+}
+
+pub fn legacy_mcp_config_file() -> PathBuf {
     functions_dir().join(MCP_FILE_NAME)
 }
 
@@ -460,11 +490,6 @@ pub fn list_macros() -> Vec<String> {
     list_file_names(macros_dir(), ".yaml")
 }
 
-pub fn has_macro(name: &str) -> bool {
-    let names = list_macros();
-    names.contains(&name.to_string())
-}
-
 pub fn list_skills() -> Vec<String> {
     let mut names = Vec::new();
     let mut seen = HashSet::new();
@@ -824,6 +849,80 @@ mod tests {
         }
     }
 
+    mod user_mcp_resolution {
+        use super::*;
+        use serial_test::serial;
+
+        fn with_config_dir<F: FnOnce(&Path)>(f: F) {
+            let unique = time::SystemTime::now()
+                .duration_since(time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos();
+            let root = env::temp_dir().join(format!("coyote-user-mcp-test-{unique}"));
+            fs::create_dir_all(root.join(FUNCTIONS_DIR_NAME)).unwrap();
+            let config_env = get_env_name("config_dir");
+            let functions_env = get_env_name("functions_dir");
+            let prev_config = env::var_os(&config_env);
+            let prev_functions = env::var_os(&functions_env);
+            unsafe {
+                env::set_var(&config_env, &root);
+                env::set_var(&functions_env, root.join(FUNCTIONS_DIR_NAME));
+            }
+            f(&root);
+            unsafe {
+                match prev_config {
+                    Some(v) => env::set_var(&config_env, v),
+                    None => env::remove_var(&config_env),
+                }
+                match prev_functions {
+                    Some(v) => env::set_var(&functions_env, v),
+                    None => env::remove_var(&functions_env),
+                }
+            }
+            let _ = fs::remove_dir_all(&root);
+        }
+
+        #[test]
+        #[serial]
+        fn defaults_to_preferred_location_when_neither_exists() {
+            with_config_dir(|root| {
+                assert_eq!(mcp_config_file(), root.join(MCP_FILE_NAME));
+            });
+        }
+
+        #[test]
+        #[serial]
+        fn falls_back_to_legacy_location_when_only_it_exists() {
+            with_config_dir(|root| {
+                let legacy = root.join(FUNCTIONS_DIR_NAME).join(MCP_FILE_NAME);
+                fs::write(&legacy, "{}").unwrap();
+                assert_eq!(mcp_config_file(), legacy);
+            });
+        }
+
+        #[test]
+        #[serial]
+        fn prefers_new_location_when_both_exist() {
+            with_config_dir(|root| {
+                let preferred = root.join(MCP_FILE_NAME);
+                let legacy = root.join(FUNCTIONS_DIR_NAME).join(MCP_FILE_NAME);
+                fs::write(&preferred, "{}").unwrap();
+                fs::write(&legacy, "{}").unwrap();
+                assert_eq!(mcp_config_file(), preferred);
+            });
+        }
+
+        #[test]
+        #[serial]
+        fn uses_preferred_location_when_only_it_exists() {
+            with_config_dir(|root| {
+                let preferred = root.join(MCP_FILE_NAME);
+                fs::write(&preferred, "{}").unwrap();
+                assert_eq!(mcp_config_file(), preferred);
+            });
+        }
+    }
+
     #[test]
     fn sandbox_kit_override_reflects_env_var_state() {
         let env_name = get_env_name("sandbox_kit");

src/config/prompts.rs

@@ -82,7 +82,7 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
     | Tool | Purpose |
     |------|----------|
     | `agent__spawn` | Spawn a subagent in the background. Returns an `id` immediately. |
-    | `agent__check` | Non-blocking check: is the agent done yet? Returns PENDING or result. |
+    | `agent__check` | Non-blocking status probe: running or finished. Never returns/consumes the result — use `agent__collect`. |
     | `agent__collect` | Blocking wait: wait for an agent to finish, return its output. |
     | `agent__list_available` | List all agent types you can spawn (name + description). Use this to discover specialists before calling `agent__spawn`. |
     | `agent__list_running` | List all subagents YOU have spawned, with their status. |
@@ -112,9 +112,10 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
 
     ### 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
+    Spawned agents do NOT deliver their results on their own. When one finishes, a
+    `system_notifications` entry appears on your next tool result naming the exact collect
+    command — but the output is only retrieved when you actively reclaim it with `agent__collect`
+    (or discard it with `agent__cancel`). 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.
@@ -190,6 +191,23 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
     4. **Respond promptly**; the child agent is blocked and waiting (5-minute timeout).
 "};
 
+pub(in crate::config) const DEFAULT_JOB_INSTRUCTIONS: &str = indoc! {"
+    ## Background Jobs
+
+    For long-running tool calls (builds, test suites, slow commands), call `job__start` and keep
+    working instead of blocking — completion arrives as a `system_notifications` entry on your
+    next tool result. Check progress with `job__check` (sparingly), block on the result with
+    `job__collect` (only when you have nothing else to do), cancel with `job__cancel`, and list
+    jobs with `job__list`. Collected results over 50,000 chars are tail-capped; collecting is
+    consume-once, so when you need the complete output pass `full_result: true` (or have the
+    command write to a file). Collect or cancel every job you started before ending your turn. In
+    graph LLM nodes, jobs are node-local: collect or cancel every job you start before the node
+    ends — an uncollected job burns node iterations via the guardrail, and anything still
+    running when the node exits is cancelled with its result discarded. Jobs run against a
+    snapshot of the current config/environment and do not survive coyote exiting.
+"
+};
+
 pub(in crate::config) const DEFAULT_TEAMMATE_INSTRUCTIONS: &str = indoc! {"
     ## Teammate Messaging
 

src/config/role.rs

@@ -30,6 +30,7 @@ pub trait RoleLike {
     fn top_p(&self) -> Option<f64>;
     fn enabled_tools(&self) -> Option<Vec<String>>;
     fn enabled_mcp_servers(&self) -> Option<Vec<String>>;
+    fn mcp_tools(&self) -> Option<IndexMap<String, Vec<String>>>;
     fn set_model(&mut self, model: Model);
     fn set_temperature(&mut self, value: Option<f64>);
     fn reasoning_effort(&self) -> Option<String>;
@@ -37,6 +38,7 @@ pub trait RoleLike {
     fn set_reasoning_effort(&mut self, value: Option<String>);
     fn set_enabled_tools(&mut self, value: Option<Vec<String>>);
     fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>);
+    fn set_mcp_tools(&mut self, value: Option<IndexMap<String, Vec<String>>>);
 }
 
 #[derive(Debug, Clone, Default, Deserialize, Serialize)]
@@ -67,6 +69,8 @@ pub struct Role {
         deserialize_with = "super::deserialize_csv_or_vec"
     )]
     enabled_mcp_servers: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    mcp_tools: Option<IndexMap<String, Vec<String>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     skills_enabled: Option<bool>,
     #[serde(
@@ -75,6 +79,12 @@ pub struct Role {
         deserialize_with = "super::deserialize_csv_or_vec"
     )]
     enabled_skills: Option<Vec<String>>,
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        deserialize_with = "super::deserialize_csv_or_vec"
+    )]
+    enabled_macros: Option<Vec<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     auto_continue: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -127,8 +137,10 @@ impl Role {
                     "enabled_mcp_servers" => {
                         role.enabled_mcp_servers = parse_string_or_array(value)
                     }
+                    "mcp_tools" => role.mcp_tools = parse_mcp_tools_map(value),
                     "skills_enabled" => role.skills_enabled = value.as_bool(),
                     "enabled_skills" => role.enabled_skills = parse_string_or_array(value),
+                    "enabled_macros" => role.enabled_macros = parse_string_or_array(value),
                     "auto_continue" => role.auto_continue = value.as_bool(),
                     "max_auto_continues" => {
                         role.max_auto_continues = value.as_u64().map(|v| v as usize)
@@ -189,6 +201,10 @@ impl Role {
                 serde_json::to_string(enabled_mcp_servers).unwrap_or_else(|_| "[]".to_string());
             metadata.push(format!("enabled_mcp_servers: {inline}"));
         }
+        if let Some(mcp_tools) = &self.mcp_tools {
+            let inline = serde_json::to_string(mcp_tools).unwrap_or_else(|_| "{}".to_string());
+            metadata.push(format!("mcp_tools: {inline}"));
+        }
         if let Some(skills_enabled) = self.skills_enabled {
             metadata.push(format!("skills_enabled: {skills_enabled}"));
         }
@@ -196,6 +212,10 @@ impl Role {
             let inline = serde_json::to_string(enabled_skills).unwrap_or_else(|_| "[]".to_string());
             metadata.push(format!("enabled_skills: {inline}"));
         }
+        if let Some(enabled_macros) = &self.enabled_macros {
+            let inline = serde_json::to_string(enabled_macros).unwrap_or_else(|_| "[]".to_string());
+            metadata.push(format!("enabled_macros: {inline}"));
+        }
         if let Some(auto_continue) = self.auto_continue {
             metadata.push(format!("auto_continue: {auto_continue}"));
         }
@@ -268,6 +288,10 @@ impl Role {
             enabled_tools,
             enabled_mcp_servers,
         );
+        let mcp_tools = role_like.mcp_tools();
+        if mcp_tools.is_some() {
+            self.set_mcp_tools(mcp_tools);
+        }
     }
 
     pub fn batch_set(
@@ -357,6 +381,10 @@ impl Role {
         self.enabled_skills.as_deref()
     }
 
+    pub fn enabled_macros(&self) -> Option<&[String]> {
+        self.enabled_macros.as_deref()
+    }
+
     pub fn append_to_prompt(&mut self, text: &str) {
         self.prompt.push_str(text);
     }
@@ -438,6 +466,10 @@ impl RoleLike for Role {
         self.enabled_mcp_servers.clone()
     }
 
+    fn mcp_tools(&self) -> Option<IndexMap<String, Vec<String>>> {
+        self.mcp_tools.clone()
+    }
+
     fn set_model(&mut self, model: Model) {
         if !self.model().id().is_empty() {
             self.model_id = Some(model.id().to_string());
@@ -464,6 +496,10 @@ impl RoleLike for Role {
     fn set_enabled_mcp_servers(&mut self, value: Option<Vec<String>>) {
         self.enabled_mcp_servers = value;
     }
+
+    fn set_mcp_tools(&mut self, value: Option<IndexMap<String, Vec<String>>>) {
+        self.mcp_tools = value;
+    }
 }
 
 fn parse_string_or_array(value: &Value) -> Option<Vec<String>> {
@@ -488,6 +524,19 @@ fn parse_string_or_array(value: &Value) -> Option<Vec<String>> {
     None
 }
 
+fn parse_mcp_tools_map(value: &Value) -> Option<IndexMap<String, Vec<String>>> {
+    let map = value.as_object()?;
+    let mut mcp_tools = IndexMap::new();
+    for (server, tools) in map {
+        if tools.is_null() {
+            mcp_tools.insert(server.clone(), Vec::new());
+        } else if let Some(tools) = parse_string_or_array(tools) {
+            mcp_tools.insert(server.clone(), tools);
+        }
+    }
+    Some(mcp_tools)
+}
+
 fn parse_structure_prompt(prompt: &str) -> (&str, Vec<(&str, &str)>) {
     let mut text = prompt;
     let mut search_input = true;
@@ -543,6 +592,7 @@ mod tests {
     #[test]
     fn role_new_parses_prompt() {
         let role = Role::new("test", "You are a helpful assistant");
+
         assert_eq!(role.name(), "test");
         assert_eq!(role.prompt(), "You are a helpful assistant");
     }
@@ -551,7 +601,9 @@ mod tests {
     fn role_new_parses_metadata() {
         let content =
             "---\nmodel: openai:gpt-4\ntemperature: 0.7\ntop_p: 0.9\n---\nYou are helpful";
+
         let role = Role::new("test", content);
+
         assert_eq!(role.model_id(), Some("openai:gpt-4"));
         assert_eq!(role.temperature(), Some(0.7));
         assert_eq!(role.top_p(), Some(0.9));
@@ -561,7 +613,9 @@ mod tests {
     #[test]
     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(vec!["tool1".to_string(), "tool2".to_string()])
@@ -571,7 +625,9 @@ mod tests {
     #[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(vec!["github".to_string(), "jira".to_string()])
@@ -581,6 +637,7 @@ mod tests {
     #[test]
     fn role_new_no_metadata_has_none_fields() {
         let role = Role::new("test", "Just a prompt");
+
         assert_eq!(role.model_id(), None);
         assert_eq!(role.temperature(), None);
         assert_eq!(role.top_p(), None);
@@ -588,9 +645,130 @@ mod tests {
         assert_eq!(role.enabled_mcp_servers(), None);
     }
 
+    #[test]
+    fn role_new_enabled_macros_absent_is_none() {
+        let role = Role::new("test", "---\ntemperature: 0.5\n---\nPrompt");
+
+        assert_eq!(role.enabled_macros, None);
+    }
+
+    #[test]
+    fn role_new_enabled_macros_empty_string_is_some_empty() {
+        let role = Role::new("test", "---\nenabled_macros: \"\"\n---\nPrompt");
+
+        assert_eq!(role.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    fn role_new_enabled_macros_csv_string() {
+        let role = Role::new("test", "---\nenabled_macros: a, b\n---\nPrompt");
+
+        assert_eq!(
+            role.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+    }
+
+    #[test]
+    fn role_new_enabled_macros_list() {
+        let role = Role::new("test", "---\nenabled_macros: [a, b]\n---\nPrompt");
+
+        assert_eq!(
+            role.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+    }
+
+    #[test]
+    fn role_new_enabled_macros_null_is_none() {
+        let role = Role::new("test", "---\nenabled_macros: null\n---\nPrompt");
+
+        assert_eq!(role.enabled_macros, None);
+    }
+
+    #[test]
+    fn role_new_parses_mcp_tools_list_and_csv_values() {
+        let content = "---\nmcp_tools:\n  github: [get_*, list_*, search_code]\n  slack: conversations_history,conversations_replies\n---\nPrompt";
+
+        let role = Role::new("test", content);
+
+        let mcp_tools = role.mcp_tools().unwrap();
+        assert_eq!(
+            mcp_tools.get("github"),
+            Some(&vec![
+                "get_*".to_string(),
+                "list_*".to_string(),
+                "search_code".to_string()
+            ])
+        );
+        assert_eq!(
+            mcp_tools.get("slack"),
+            Some(&vec![
+                "conversations_history".to_string(),
+                "conversations_replies".to_string()
+            ])
+        );
+    }
+
+    #[test]
+    fn role_new_mcp_tools_empty_list_server_is_some_empty() {
+        let role = Role::new("test", "---\nmcp_tools:\n  github: []\n---\nPrompt");
+
+        assert_eq!(role.mcp_tools().unwrap().get("github"), Some(&vec![]));
+    }
+
+    #[test]
+    fn role_new_mcp_tools_per_server_null_is_some_empty() {
+        let role = Role::new("test", "---\nmcp_tools:\n  github:\n---\nPrompt");
+
+        assert_eq!(role.mcp_tools().unwrap().get("github"), Some(&vec![]));
+    }
+
+    #[test]
+    fn role_new_mcp_tools_absent_is_none() {
+        let role = Role::new("test", "---\ntemperature: 0.5\n---\nPrompt");
+
+        assert_eq!(role.mcp_tools(), None);
+    }
+
+    #[test]
+    fn role_new_mcp_tools_null_is_none() {
+        let role = Role::new("test", "---\nmcp_tools: null\n---\nPrompt");
+
+        assert_eq!(role.mcp_tools(), None);
+    }
+
+    #[test]
+    fn role_export_mcp_tools_round_trips() {
+        let content = "---\nmcp_tools:\n  github: [get_issue]\n  slack: a,b\n---\nPrompt";
+        let role = Role::new("test", content);
+
+        let reparsed = Role::new("test", &role.export());
+
+        assert_eq!(reparsed.mcp_tools(), role.mcp_tools());
+        assert!(role.mcp_tools().is_some());
+    }
+
+    #[test]
+    fn role_export_includes_enabled_macros() {
+        let role = Role::new("test", "---\nenabled_macros: [a]\n---\nPrompt");
+
+        let exported = role.export();
+
+        assert!(exported.contains("enabled_macros: [\"a\"]"));
+    }
+
+    #[test]
+    fn role_export_omits_enabled_macros_when_none() {
+        let role = Role::new("test", "Just a prompt");
+
+        assert!(!role.export().contains("enabled_macros"));
+    }
+
     #[test]
     fn role_builtin_shell_loads() {
         let role = Role::builtin("shell").unwrap();
+
         assert_eq!(role.name(), "shell");
         assert!(!role.prompt().is_empty());
     }
@@ -598,6 +776,7 @@ mod tests {
     #[test]
     fn role_builtin_code_loads() {
         let role = Role::builtin("code").unwrap();
+
         assert_eq!(role.name(), "code");
         assert!(!role.prompt().is_empty());
     }
@@ -605,12 +784,14 @@ mod tests {
     #[test]
     fn role_builtin_nonexistent_errors() {
         let result = Role::builtin("nonexistent_role_xyz");
+
         assert!(result.is_err());
     }
 
     #[test]
     fn role_default_has_empty_fields() {
         let role = Role::default();
+
         assert_eq!(role.name(), "");
         assert_eq!(role.prompt(), "");
         assert_eq!(role.model_id(), None);
@@ -620,14 +801,18 @@ mod tests {
     fn role_set_model_updates_model() {
         let mut role = Role::new("test", "prompt");
         let model = Model::default();
+
         role.set_model(model.clone());
+
         assert_eq!(role.model().id(), model.id());
     }
 
     #[test]
     fn role_set_temperature_works() {
         let mut role = Role::new("test", "prompt");
+
         role.set_temperature(Some(0.5));
+
         assert_eq!(role.temperature(), Some(0.5));
     }
 
@@ -635,7 +820,9 @@ mod tests {
     fn role_export_includes_metadata() {
         let content = "---\ntemperature: 0.8\n---\nMy prompt";
         let role = Role::new("test", content);
+
         let exported = role.export();
+
         assert!(exported.contains("temperature"));
         assert!(exported.contains("My prompt"));
     }
@@ -649,6 +836,7 @@ Input 1
 ### OUTPUT:
 Output 1
 "#;
+
         assert_eq!(
             parse_structure_prompt(prompt),
             ("System message", vec![("Input 1", "Output 1")])
@@ -663,6 +851,7 @@ Input 1
 ### OUTPUT:
 Output 1
 "#;
+
         assert_eq!(
             parse_structure_prompt(prompt),
             ("", vec![("Input 1", "Output 1")])
@@ -676,6 +865,7 @@ System message
 ### INPUT:
 Input 1
 "#;
+
         assert_eq!(parse_structure_prompt(prompt), (prompt, vec![]));
     }
 }

src/config/session.rs

@@ -16,6 +16,8 @@ use std::sync::LazyLock;
 
 static RE_AUTONAME_PREFIX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\d{8}T\d{6}-").unwrap());
 
+pub const INTERRUPTED_RESPONSE_TEXT: &str = "[Response interrupted due to error]";
+
 #[derive(Debug, Clone, Default, Deserialize, Serialize)]
 pub struct Session {
     #[serde(rename(serialize = "model", deserialize = "model"))]
@@ -38,6 +40,8 @@ pub struct Session {
         deserialize_with = "super::deserialize_csv_or_vec"
     )]
     enabled_mcp_servers: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    mcp_tools: Option<IndexMap<String, Vec<String>>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     skills_enabled: Option<bool>,
     #[serde(
@@ -46,6 +50,12 @@ pub struct Session {
         deserialize_with = "super::deserialize_csv_or_vec"
     )]
     enabled_skills: Option<Vec<String>>,
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        deserialize_with = "super::deserialize_csv_or_vec"
+    )]
+    enabled_macros: Option<Vec<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     save_session: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -107,6 +117,10 @@ impl Session {
         self.enabled_skills.as_deref()
     }
 
+    pub fn enabled_macros(&self) -> Option<&[String]> {
+        self.enabled_macros.as_deref()
+    }
+
     pub fn set_skills_enabled(&mut self, value: Option<bool>) {
         if self.skills_enabled != value {
             self.skills_enabled = value;
@@ -165,6 +179,13 @@ impl Session {
         self.messages.is_empty() && self.compressed_messages.is_empty()
     }
 
+    pub fn has_interrupted_error_checkpoint(&self) -> bool {
+        self.messages.last().is_some_and(|message| {
+            message.role.is_assistant()
+                && matches!(&message.content, MessageContent::Text(text) if text.ends_with(INTERRUPTED_RESPONSE_TEXT))
+        })
+    }
+
     pub fn messages(&self) -> &[Message] {
         &self.messages
     }
@@ -230,12 +251,18 @@ impl Session {
         if let Some(enabled_mcp_servers) = self.enabled_mcp_servers() {
             data["enabled_mcp_servers"] = json!(enabled_mcp_servers);
         }
+        if let Some(mcp_tools) = self.mcp_tools() {
+            data["mcp_tools"] = json!(mcp_tools);
+        }
         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(enabled_macros) = self.enabled_macros() {
+            data["enabled_macros"] = json!(enabled_macros);
+        }
         if let Some(save_session) = self.save_session() {
             data["save_session"] = save_session.into();
         }
@@ -307,6 +334,13 @@ impl Session {
             items.push(("enabled_mcp_servers", enabled_mcp_servers.join(",")));
         }
 
+        if let Some(mcp_tools) = self.mcp_tools() {
+            items.push((
+                "mcp_tools",
+                serde_json::to_string(&mcp_tools).unwrap_or_default(),
+            ));
+        }
+
         if let Some(skills_enabled) = self.skills_enabled() {
             items.push(("skills_enabled", skills_enabled.to_string()));
         }
@@ -315,6 +349,10 @@ impl Session {
             items.push(("enabled_skills", enabled_skills.join(",")));
         }
 
+        if let Some(enabled_macros) = self.enabled_macros() {
+            items.push(("enabled_macros", enabled_macros.join(",")));
+        }
+
         if let Some(save_session) = self.save_session() {
             items.push(("save_session", save_session.to_string()));
         }
@@ -844,6 +882,10 @@ impl RoleLike for Session {
         self.enabled_mcp_servers.clone()
     }
 
+    fn mcp_tools(&self) -> Option<IndexMap<String, Vec<String>>> {
+        self.mcp_tools.clone()
+    }
+
     fn set_model(&mut self, model: Model) {
         if self.model().id() != model.id() {
             self.model_id = model.id();
@@ -887,6 +929,13 @@ impl RoleLike for Session {
             self.dirty = true;
         }
     }
+
+    fn set_mcp_tools(&mut self, value: Option<IndexMap<String, Vec<String>>>) {
+        if self.mcp_tools != value {
+            self.mcp_tools = value;
+            self.dirty = true;
+        }
+    }
 }
 
 #[derive(Debug, Clone, Default)]
@@ -917,20 +966,183 @@ impl AutoName {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::client::{Message, MessageContent, MessageRole, Model};
+    use crate::client::{Message, MessageContent, MessageContentToolCalls, MessageRole, Model};
     use crate::config::{AppConfig, AppState, RequestContext, WorkingMode};
-    use crate::function::Functions;
+    use crate::function::{Functions, ToolCall, ToolResult};
     use std::sync::Arc;
 
     #[test]
     fn session_default_is_empty() {
         let session = Session::default();
+
         assert!(session.is_empty());
         assert_eq!(session.name(), "");
         assert_eq!(session.role_name(), None);
         assert!(!session.dirty());
     }
 
+    fn push_interrupted_turn(session: &mut Session) {
+        session.messages.push(Message::new(
+            MessageRole::User,
+            MessageContent::Text("do things".to_string()),
+        ));
+        session.messages.push(Message::new(
+            MessageRole::Tool,
+            MessageContent::ToolCalls(MessageContentToolCalls::new(
+                vec![ToolResult::new(ToolCall::default(), json!("ok"))],
+                String::new(),
+            )),
+        ));
+        session.messages.push(Message::new(
+            MessageRole::Assistant,
+            MessageContent::Text(INTERRUPTED_RESPONSE_TEXT.to_string()),
+        ));
+    }
+
+    #[test]
+    fn session_has_interrupted_error_checkpoint_detects_sentinel() {
+        let mut session = Session::default();
+        assert!(!session.has_interrupted_error_checkpoint());
+
+        session.messages.push(Message::new(
+            MessageRole::User,
+            MessageContent::Text("hi".to_string()),
+        ));
+        session.messages.push(Message::new(
+            MessageRole::Assistant,
+            MessageContent::Text("hello".to_string()),
+        ));
+        assert!(
+            !session.has_interrupted_error_checkpoint(),
+            "a normal completed exchange is not an interruption"
+        );
+
+        push_interrupted_turn(&mut session);
+        assert!(session.has_interrupted_error_checkpoint());
+    }
+
+    #[test]
+    fn session_detects_checkpoint_appended_by_crashed_continue_turn() {
+        // A crash during a `.continue` turn appends the sentinel to the
+        // previous assistant text (add_message's continue_output branch)
+        // instead of pushing a standalone checkpoint message.
+        let mut session = Session::default();
+        session.messages.push(Message::new(
+            MessageRole::User,
+            MessageContent::Text("hi".to_string()),
+        ));
+        session.messages.push(Message::new(
+            MessageRole::Assistant,
+            MessageContent::Text(format!("partial answer{INTERRUPTED_RESPONSE_TEXT}")),
+        ));
+
+        assert!(session.has_interrupted_error_checkpoint());
+    }
+
+    #[test]
+    fn session_interrupted_checkpoint_with_tool_calls_survives_yaml_round_trip() {
+        let mut session = Session::default();
+        push_interrupted_turn(&mut session);
+
+        let yaml = serde_yaml::to_string(&session).unwrap();
+        let reloaded: Session = serde_yaml::from_str(&yaml).unwrap();
+
+        assert!(
+            reloaded.has_interrupted_error_checkpoint(),
+            "interruption checkpoint must survive save/reload"
+        );
+        assert!(
+            reloaded.messages.iter().any(|m| matches!(
+                &m.content,
+                MessageContent::ToolCalls(tc) if tc.tool_results.len() == 1
+            )),
+            "tool calls made before the crash must survive save/reload"
+        );
+    }
+
+    #[test]
+    fn session_enabled_macros_absent_is_none() {
+        let session: Session = serde_yaml::from_str("model: provider:test\nmessages: []").unwrap();
+
+        assert_eq!(session.enabled_macros, None);
+    }
+
+    #[test]
+    fn session_mcp_tools_survives_yaml_round_trip() {
+        let mut session = Session::default();
+        let mut mcp_tools = IndexMap::new();
+        mcp_tools.insert("github".to_string(), vec!["get_*".to_string()]);
+        mcp_tools.insert("slack".to_string(), vec![]);
+        session.set_mcp_tools(Some(mcp_tools.clone()));
+
+        let yaml = serde_yaml::to_string(&session).unwrap();
+        let reloaded: Session = serde_yaml::from_str(&yaml).unwrap();
+
+        assert_eq!(reloaded.mcp_tools(), Some(mcp_tools));
+    }
+
+    #[test]
+    fn session_set_role_does_not_copy_mcp_tools() {
+        let role = Role::new(
+            "test",
+            "---\nmcp_tools:\n  github: [get_issue]\n---\nPrompt",
+        );
+        assert!(role.mcp_tools().is_some());
+        let mut session = Session::default();
+
+        session.set_role(role);
+
+        assert_eq!(session.mcp_tools(), None);
+    }
+
+    #[test]
+    fn session_set_mcp_tools_marks_dirty() {
+        let mut session = Session::default();
+        assert!(!session.dirty());
+
+        session.set_mcp_tools(Some(IndexMap::new()));
+
+        assert!(session.dirty());
+        assert_eq!(session.mcp_tools(), Some(IndexMap::new()));
+    }
+
+    #[test]
+    fn session_enabled_macros_empty_list_is_some_empty() {
+        let session: Session =
+            serde_yaml::from_str("model: provider:test\nenabled_macros: []\nmessages: []").unwrap();
+
+        assert_eq!(session.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    fn session_enabled_macros_empty_string_is_some_empty() {
+        let session: Session =
+            serde_yaml::from_str("model: provider:test\nenabled_macros: \"\"\nmessages: []")
+                .unwrap();
+
+        assert_eq!(session.enabled_macros, Some(vec![]));
+    }
+
+    #[test]
+    fn session_enabled_macros_csv_string() {
+        let session: Session =
+            serde_yaml::from_str("model: provider:test\nenabled_macros: \"a,b\"\nmessages: []")
+                .unwrap();
+
+        assert_eq!(
+            session.enabled_macros,
+            Some(vec!["a".to_string(), "b".to_string()])
+        );
+    }
+
+    #[test]
+    fn session_serialize_omits_enabled_macros_when_none() {
+        let session = Session::default();
+        let yaml = serde_yaml::to_string(&session).unwrap();
+
+        assert!(!yaml.contains("enabled_macros"));
+    }
+
     #[test]
     fn session_new_from_ctx_captures_save_session() {
         let app_config = Arc::new(AppConfig::default());
@@ -945,6 +1157,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").unwrap();
 
         assert_eq!(session.name(), "test-session");
@@ -984,25 +1197,30 @@ mod tests {
     #[test]
     fn session_guard_empty_passes_when_empty() {
         let session = Session::default();
+
         assert!(session.guard_empty().is_ok());
     }
 
     #[test]
     fn session_needs_compression_threshold() {
         let session = Session::default();
+
         assert!(!session.needs_compression(4000));
     }
 
     #[test]
     fn session_needs_compression_returns_false_when_compressing() {
         let mut session = Session::default();
+
         session.set_compressing(true);
+
         assert!(!session.needs_compression(0));
     }
 
     #[test]
     fn session_needs_compression_returns_false_when_threshold_zero() {
         let session = Session::default();
+
         assert!(!session.needs_compression(0));
     }
 
@@ -1074,13 +1292,16 @@ mod tests {
     #[test]
     fn session_need_autoname_default_false() {
         let session = Session::default();
+
         assert!(!session.need_autoname());
     }
 
     #[test]
     fn session_set_autonaming_doesnt_panic_without_autoname() {
         let mut session = Session::default();
+
         session.set_autonaming(true);
+
         assert!(!session.need_autoname());
     }