+Claw Code is the public Rust implementation of the `claw` CLI agent harness.
+The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**.
> [!IMPORTANT]
-> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, then use [`rust/README.md`](./rust/README.md) for crate-level details.
+> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow.
-> Want the bigger idea behind this repo? Read [`PHILOSOPHY.md`](./PHILOSOPHY.md) and Sigrid Jin's public explanation: https://x.com/realsigridjin/status/2039472968624185713
+## Current repository shape
-> Shout-out to the UltraWorkers ecosystem powering this repo: [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), and the [UltraWorkers Discord](https://discord.gg/6ztZB9jvWq).
+- **`rust/`** — canonical Rust workspace and the `claw` CLI binary
+- **`USAGE.md`** — task-oriented usage guide for the current product surface
+- **`PARITY.md`** — Rust-port parity status and migration notes
+- **`ROADMAP.md`** — active roadmap and cleanup backlog
+- **`PHILOSOPHY.md`** — project intent and system-design framing
+- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface
----
-
-## Backstory
-
-This repo is maintained by **lobsters/claws**, not by a conventional human-only dev team.
-
-The people behind the system are [Bellman / Yeachan Heo](https://github.com/Yeachan-Heo) and friends like [Yeongyu](https://github.com/code-yeongyu), but the repo itself is being pushed forward by autonomous claw workflows: parallel coding sessions, event-driven orchestration, recovery loops, and machine-readable lane state.
-
-In practice, that means this project is not just *about* coding agents — it is being **actively built by them**. Features, tests, telemetry, docs, and workflow hardening are landed through claw-driven loops using [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), and [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex).
-
-This repository exists to prove that an open coding harness can be built **autonomously, in public, and at high velocity** — with humans setting direction and claws doing the grinding.
-
-See the public build story here:
-
-https://x.com/realsigridjin/status/2039472968624185713
-
-
-
----
-
-## Porting Status
-
-The main source tree is now Python-first.
-
-- `src/` contains the active Python porting workspace
-- `tests/` verifies the current Python workspace
-- the exposed snapshot is no longer part of the tracked repository state
-
-The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.
-
-## Why this rewrite exists
-
-I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.
-
-This repository now focuses on Python porting work instead.
-
-## Repository Layout
-
-```text
-.
-├── src/ # Python porting workspace
-│ ├── __init__.py
-│ ├── commands.py
-│ ├── main.py
-│ ├── models.py
-│ ├── port_manifest.py
-│ ├── query_engine.py
-│ ├── task.py
-│ └── tools.py
-├── tests/ # Python verification
-├── assets/omx/ # OmX workflow screenshots
-├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
-└── README.md
-```
-
-## Python Workspace Overview
-
-The new Python `src/` tree currently provides:
-
-- **`port_manifest.py`** — summarizes the current Python workspace structure
-- **`models.py`** — dataclasses for subsystems, modules, and backlog state
-- **`commands.py`** — Python-side command port metadata
-- **`tools.py`** — Python-side tool port metadata
-- **`query_engine.py`** — renders a Python porting summary from the active workspace
-- **`main.py`** — a CLI entrypoint for manifest and summary output
-
-## Quickstart
-
-Render the Python porting summary:
+## Quick start
```bash
-python3 -m src.main summary
+cd rust
+cargo build --workspace
+./target/debug/claw --help
+./target/debug/claw prompt "summarize this repository"
```
-Print the current Python workspace manifest:
+Authenticate with either an API key or the built-in OAuth flow:
```bash
-python3 -m src.main manifest
+export ANTHROPIC_API_KEY="sk-ant-..."
+# or
+cd rust
+./target/debug/claw login
```
-List the current Python modules:
+Run the workspace test suite:
```bash
-python3 -m src.main subsystems --limit 16
+cd rust
+cargo test --workspace
```
-Run verification:
+## Documentation map
-```bash
-python3 -m unittest discover -s tests -v
-```
+- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness
+- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout
+- [`PARITY.md`](./PARITY.md) — parity status for the Rust port
+- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details
+- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work
+- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated
-Run the parity audit against the local ignored archive (when present):
+## Ecosystem
-```bash
-python3 -m src.main parity-audit
-```
+Claw Code is built in the open alongside the broader UltraWorkers toolchain:
-Inspect mirrored command/tool inventories:
+- [clawhip](https://github.com/Yeachan-Heo/clawhip)
+- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)
+- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
+- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
+- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd)
-```bash
-python3 -m src.main commands --limit 10
-python3 -m src.main tools --limit 10
-```
-
-Run a local Ollama-backed chat prompt:
-
-```bash
-ollama run qwen2.5-coder:7b
-python3 -m src.main chat "write a hello world in python"
-```
-
-The local chat path uses Ollama at `http://localhost:11434` by default and sends a single non-streaming `/api/chat` request to `qwen2.5-coder:7b`.
-
-For the current local agent/tool integration, request features, and command examples, see [`OLLAMA_INTEGRATION.md`](./OLLAMA_INTEGRATION.md).
-
-## Current Parity Checkpoint
-
-The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.
-
-
-## Built with `oh-my-codex`
-
-The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.
-
-- **`$team` mode:** used for coordinated parallel review and architectural feedback
-- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
-- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace
-
-### OmX workflow screenshots
-
-
-
-*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*
-
-
-
-*Split-pane review and verification flow during the final README wording pass.*
-
-## Community
-
-
-
-
-
-Join the [**UltraWorkers Discord**](https://discord.gg/6ztZB9jvWq) — the community around clawhip, oh-my-openagent, oh-my-claudecode, oh-my-codex, and claw-code. Come chat about LLMs, harness engineering, agent workflows, and autonomous software development.
-
-[](https://discord.gg/6ztZB9jvWq)
-
-## Star History
-
-See the chart at the top of this README.
-
-## Ownership / Affiliation Disclaimer
+## Ownership / affiliation disclaimer
- This repository does **not** claim ownership of the original Claude Code source material.
- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**.
diff --git a/ROADMAP.md b/ROADMAP.md
index 38cd548f..5bf89472 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -271,15 +271,18 @@ Acceptance:
Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 = clawability hardening, P3 = swarm-efficiency improvements.
**P0 — Fix first (CI reliability)**
-1. Isolate `render_diff_report` tests into tmpdir — flaky under `cargo test --workspace`; reads real working-tree state; breaks CI during active worktree ops
-2. Expand GitHub CI from single-crate coverage to workspace-grade verification — current `rust-ci.yml` runs `cargo fmt` and `cargo test -p rusty-claude-cli`, but misses broader `cargo test --workspace` coverage that already passes locally
-3. Add release-grade binary workflow — repo has a Rust CLI and release intent, but no GitHub Actions path that builds tagged artifacts / checks release packaging before a publish step
-4. Add container-first test/run docs — runtime detects Docker/Podman/container state, but docs do not show a canonical container workflow for `cargo test --workspace`, binary execution, or bind-mounted repo usage
-5. Surface `doctor` / preflight diagnostics in onboarding docs and help — the CLI already has setup-diagnosis commands and branch preflight machinery, but they are not prominent enough in README/USAGE, so new users still ask manual setup questions instead of running a built-in health check first
-6. Add branding/source-of-truth residue checks for docs — after repo migration, old org names can survive in badges, star-history URLs, and copied snippets; docs need a consistency pass or CI lint to catch stale branding automatically
-7. Reconcile README product narrative with current repo reality — top-level docs now say the active workspace is Rust, but later sections still describe the repo as Python-first; users should not have to infer which implementation is canonical
-8. Eliminate warning spam from first-run help/build path — `cargo run -p rusty-claude-cli -- --help` currently prints a wall of compile warnings before the actual help text, which pollutes the first-touch UX and hides the product surface behind unrelated noise
-9. Promote `doctor` from slash-only to top-level CLI entrypoint — users naturally try `claw doctor`, but today it errors and tells them to enter a REPL or resume path first; healthcheck flows should be callable directly from the shell
+1. Isolate `render_diff_report` tests into tmpdir — **done**: `render_diff_report_for()` tests run in temp git repos instead of the live working tree, and targeted `cargo test -p rusty-claude-cli render_diff_report -- --nocapture` now stays green during branch/worktree activity
+2. Expand GitHub CI from single-crate coverage to workspace-grade verification — **done**: `.github/workflows/rust-ci.yml` now runs `cargo test --workspace` plus fmt/clippy at the workspace level
+3. Add release-grade binary workflow — **done**: `.github/workflows/release.yml` now builds tagged Rust release artifacts for the CLI
+4. Add container-first test/run docs — **done**: `Containerfile` + `docs/container.md` document the canonical Docker/Podman workflow for build, bind-mount, and `cargo test --workspace` usage
+5. Surface `doctor` / preflight diagnostics in onboarding docs and help — **done**: README + USAGE now put `claw doctor` / `/doctor` in the first-run path and point at the built-in preflight report
+6. Automate branding/source-of-truth residue checks in CI — **done**: `.github/scripts/check_doc_source_of_truth.py` and the `doc-source-of-truth` CI job now block stale repo/org/invite residue in tracked docs and metadata
+7. Eliminate warning spam from first-run help/build path — **done**: current `cargo run -q -p rusty-claude-cli -- --help` renders clean help output without a warning wall before the product surface
+8. Promote `doctor` from slash-only to top-level CLI entrypoint — **done**: `claw doctor` is now a local shell entrypoint with regression coverage for direct help and health-report output
+9. Make machine-readable status commands actually machine-readable — **done**: `claw --output-format json status` and `claw --output-format json sandbox` now emit structured JSON snapshots instead of prose tables
+10. Unify legacy config/skill namespaces in user-facing output — **done**: skills/help JSON/text output now present `.claw` as the canonical namespace and collapse legacy roots behind `.claw`-shaped source ids/labels
+11. Honor JSON output on inventory commands like `skills` and `mcp` — **done**: direct CLI inventory commands now honor `--output-format json` with structured payloads for both skills and MCP inventory
+12. Audit `--output-format` contract across the whole CLI surface — **done**: direct CLI commands now honor deterministic JSON/text handling across help/version/status/sandbox/agents/mcp/skills/bootstrap-plan/system-prompt/init/doctor, with regression coverage in `output_format_contract.rs` and resumed `/status` JSON coverage
**P1 — Next (integration wiring, unblocks verification)**
2. Add cross-module integration tests — **done**: 12 integration tests covering worker→recovery→policy, stale_branch→policy, green_contract→policy, reconciliation flows
@@ -297,11 +300,38 @@ Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 =
12. Lane board / machine-readable status API — **done**: Lane completion hardening + `LaneContext::completed` auto-detection + MCP degraded reporting surface machine-readable state
13. **Session completion failure classification** — **done**: `WorkerFailureKind::Provider` + `observe_completion()` + recovery recipe bridge landed
14. **Config merge validation gap** — **done**: `config.rs` hook validation before deep-merge (+56 lines), malformed entries fail with source-path context instead of merged parse errors
-15. **MCP manager discovery flaky test** — `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` has intermittent timing issues in CI; temporarily ignored, needs root cause fix
+15. **MCP manager discovery flaky test** — **done**: `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` now runs as a normal workspace test again after repeated stable passes, so degraded-startup coverage is no longer hidden behind `#[ignore]`
+
+16. **Commit provenance / worktree-aware push events** — **done**: `LaneCommitProvenance` now carries branch/worktree/canonical-commit/supersession metadata in lane events, and `dedupe_superseded_commit_events()` is applied before agent manifests are written so superseded commit events collapse to the latest canonical lineage
+17. **Orphaned module integration audit** — **done**: `runtime` now keeps `session_control` and `trust_resolver` behind `#[cfg(test)]` until they are wired into a real non-test execution path, so normal builds no longer advertise dead clawability surface area.
+18. **Context-window preflight gap** — **done**: provider request sizing now emits `context_window_blocked` before oversized requests leave the process, using a model-context registry instead of the old naive max-token heuristic.
+19. **Subcommand help falls through into runtime/API path** — **done**: `claw doctor --help`, `claw status --help`, `claw sandbox --help`, and nested `mcp`/`skills` help are now intercepted locally without runtime/provider startup, with regression tests covering the direct CLI paths.
+20. **Session state classification gap (working vs blocked vs finished vs truly stale)** — **done**: agent manifests now derive machine states such as `working`, `blocked_background_job`, `blocked_merge_conflict`, `degraded_mcp`, `interrupted_transport`, `finished_pending_report`, and `finished_cleanable`, and terminal-state persistence records commit provenance plus derived state so downstream monitoring can distinguish quiet progress from truly idle sessions.
+21. **Resumed `/status` JSON parity gap** — dogfooding shows fresh `claw status --output-format json` now emits structured JSON, but resumed slash-command status still leaks through a text-shaped path in at least one dispatch path. Local CI-equivalent repro fails `rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs::resumed_status_command_emits_structured_json_when_requested` with `expected value at line 1 column 1`, so resumed automation can receive text where JSON was explicitly requested. **Action:** unify fresh vs resumed `/status` rendering through one output-format contract and add regression coverage so resumed JSON output is guaranteed valid.
+22. **Opaque failure surface for session/runtime crashes** — repeated dogfood-facing failures can currently collapse to generic wrappers like `Something went wrong while processing your request. Please try again, or use /new to start a fresh session.` without exposing whether the fault was provider auth, session corruption, slash-command dispatch, render failure, or transport/runtime panic. This blocks fast self-recovery and turns actionable clawability bugs into blind retries. **Action:** preserve a short user-safe failure class (`provider_auth`, `session_load`, `command_dispatch`, `render`, `runtime_panic`, etc.), attach a local trace/session id, and ensure operators can jump from the chat-visible error to the exact failure log quickly.
+23. **`doctor --output-format json` check-level structure gap** — **done**: `claw doctor --output-format json` now keeps the human-readable `message`/`report` while also emitting structured per-check diagnostics (`name`, `status`, `summary`, `details`, plus typed fields like workspace paths and sandbox fallback data), with regression coverage in `output_format_contract.rs`.
+24. **Plugin lifecycle init/shutdown test flakes under workspace-parallel execution** — dogfooding surfaced that `build_runtime_runs_plugin_lifecycle_init_and_shutdown` can fail under `cargo test --workspace` while passing in isolation because sibling tests race on tempdir-backed shell init script paths. This is test brittleness rather than a code-path regression, but it still destabilizes CI confidence and wastes diagnosis cycles. **Action:** isolate temp resources per test robustly (unique dirs + no shared cwd assumptions), audit cleanup timing, and add a regression guard so the plugin lifecycle test remains stable under parallel workspace execution.
+26. **Resumed local-command JSON parity gap** — **done**: direct `claw --output-format json` already had structured renderers for `sandbox`, `mcp`, `skills`, `version`, and `init`, but resumed `claw --output-format json --resume /…` paths still fell back to prose because resumed slash dispatch only emitted JSON for `/status`. Resumed `/sandbox`, `/mcp`, `/skills`, `/version`, and `/init` now reuse the same JSON envelopes as their direct CLI counterparts, with regression coverage in `rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs` and `rust/crates/rusty-claude-cli/tests/output_format_contract.rs`.
+
+41. **Phantom completions root cause: global session store has no per-worktree isolation** —
+
+ **Root cause.** The session store under `~/.local/share/opencode` is global to the host. Every `opencode serve` instance — including the parallel lane workers spawned per worktree — reads and writes the same on-disk session directory. Sessions are keyed only by id and timestamp, not by the workspace they were created in, so there is no structural barrier between a session created in worktree `/tmp/b4-phantom-diag` and one created in `/tmp/b4-omc-flat`. Whichever serve instance picks up a given session id can drive it from whatever CWD that serve happens to be running in.
+
+ **Impact.** Parallel lanes silently cross wires. A lane reports a clean run — file edits, builds, tests — and the orchestrator marks the lane green, but the writes were applied against another worktree's CWD because a sibling `opencode serve` won the session race. The originating worktree shows no diff, the *other* worktree gains unexplained edits, and downstream consumers (clawhip lane events, PR pushes, merge gates) treat the empty originator as a successful no-op. These are the "phantom completions" we keep chasing: success messaging without any landed changes in the lane that claimed them, plus stray edits in unrelated lanes whose own runs never touched those files. Because the report path is happy, retries and recovery recipes never fire, so the lane silently wedges until a human notices the diff is empty.
+
+ **Proposed fix.** Bind every session to its workspace root + branch at creation time and refuse to drive it from any other CWD.
+
+ - At session creation, capture the canonical workspace root (resolved git worktree path) and the active branch and persist them on the session record.
+ - On every load (`opencode serve`, slash-command resume, lane recovery), validate that the current process CWD matches the persisted workspace root before any tool with side effects (file_ops, bash, git) is allowed to run. Mismatches surface as a typed `WorkspaceMismatch` failure class instead of silently writing to the wrong tree.
+ - Namespace the on-disk session path under the workspace fingerprint (e.g. `//`) so two parallel `opencode serve` instances physically cannot collide on the same session id.
+ - Forks inherit the parent's workspace root by default; an explicit re-bind is required to move a session to a new worktree, and that re-bind is itself recorded as a structured event so the orchestrator can audit cross-worktree handoffs.
+ - Surface a `branch.workspace_mismatch` lane event so clawhip stops counting wrong-CWD writes as lane completions.
+
+ **Status.** A `workspace_root` field has been added to `Session` in `rust/crates/runtime/src/session.rs` (with builder, accessor, JSON + JSONL round-trip, fork inheritance, and given/when/then test coverage in `persists_workspace_root_round_trip_and_forks_inherit_it`). The CWD validation, the namespaced on-disk path, and the `branch.workspace_mismatch` lane event are still outstanding and tracked under this item.
**P3 — Swarm efficiency**
-13. Swarm branch-lock protocol — detect same-module/same-branch collision before parallel workers drift into duplicate implementation
-14. Commit provenance / worktree-aware push events — emit branch, worktree, superseded-by, and canonical commit lineage so parallel sessions stop producing duplicate-looking push summaries
+13. Swarm branch-lock protocol — **done**: `branch_lock::detect_branch_lock_collisions()` now detects same-branch/same-scope and nested-module collisions before parallel lanes drift into duplicate implementation
+14. Commit provenance / worktree-aware push events — **done**: lane event provenance now includes branch/worktree/superseded/canonical lineage metadata, and manifest persistence de-dupes superseded commit events before downstream consumers render them
## Suggested Session Split
diff --git a/USAGE.md b/USAGE.md
index f8232d6b..f0220758 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -1,6 +1,20 @@
# Claw Code Usage
-This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
+This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. If you are brand new, make the doctor health check your first run: start `claw`, then run `/doctor`.
+
+## Quick-start health check
+
+Run this before prompts, sessions, or automation:
+
+```bash
+cd rust
+cargo build --workspace
+./target/debug/claw
+# first command inside the REPL
+/doctor
+```
+
+`/doctor` is the built-in setup and preflight diagnostic. Once you have a saved session, you can rerun it with `./target/debug/claw --resume latest /doctor`.
## Prerequisites
@@ -10,17 +24,25 @@ This guide covers the current Rust workspace under `rust/` and the `claw` CLI bi
- `claw login` for OAuth-based auth
- Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service
-## Build the workspace
+## Install / build the workspace
```bash
cd rust
cargo build --workspace
```
-The CLI binary is available at `rust/target/debug/claw` after a debug build.
+The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step.
## Quick start
+### First-run doctor check
+
+```bash
+cd rust
+./target/debug/claw
+/doctor
+```
+
### Interactive REPL
```bash
@@ -87,6 +109,157 @@ cd rust
./target/debug/claw logout
```
+## Local Models
+
+`claw` can talk to local servers and provider gateways through either Anthropic-compatible or OpenAI-compatible endpoints. Use `ANTHROPIC_BASE_URL` with `ANTHROPIC_AUTH_TOKEN` for Anthropic-compatible services, or `OPENAI_BASE_URL` with `OPENAI_API_KEY` for OpenAI-compatible services. OAuth is Anthropic-only, so when `OPENAI_BASE_URL` is set you should use API-key style auth instead of `claw login`.
+
+### Anthropic-compatible endpoint
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
+export ANTHROPIC_AUTH_TOKEN="local-dev-token"
+
+cd rust
+./target/debug/claw --model "claude-sonnet-4-6" prompt "reply with the word ready"
+```
+
+### OpenAI-compatible endpoint
+
+```bash
+export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
+export OPENAI_API_KEY="local-dev-token"
+
+cd rust
+./target/debug/claw --model "qwen2.5-coder" prompt "reply with the word ready"
+```
+
+### Ollama
+
+```bash
+export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
+unset OPENAI_API_KEY
+
+cd rust
+./target/debug/claw --model "llama3.2" prompt "summarize this repository in one sentence"
+```
+
+### OpenRouter
+
+```bash
+export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
+export OPENAI_API_KEY="sk-or-v1-..."
+
+cd rust
+./target/debug/claw --model "openai/gpt-4.1-mini" prompt "summarize this repository in one sentence"
+```
+
+## Supported Providers & Models
+
+`claw` has three built-in provider backends. The provider is selected automatically based on the model name, falling back to whichever credential is present in the environment.
+
+### Provider matrix
+
+| Provider | Protocol | Auth env var(s) | Base URL env var | Default base URL |
+|---|---|---|---|---|
+| **Anthropic** (direct) | Anthropic Messages API | `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` or OAuth (`claw login`) | `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` |
+| **xAI** | OpenAI-compatible | `XAI_API_KEY` | `XAI_BASE_URL` | `https://api.x.ai/v1` |
+| **OpenAI-compatible** | OpenAI Chat Completions | `OPENAI_API_KEY` | `OPENAI_BASE_URL` | `https://api.openai.com/v1` |
+
+The OpenAI-compatible backend also serves as the gateway for **OpenRouter**, **Ollama**, and any other service that speaks the OpenAI `/v1/chat/completions` wire format — just point `OPENAI_BASE_URL` at the service.
+
+### Tested models and aliases
+
+These are the models registered in the built-in alias table with known token limits:
+
+| Alias | Resolved model name | Provider | Max output tokens | Context window |
+|---|---|---|---|---|
+| `opus` | `claude-opus-4-6` | Anthropic | 32 000 | 200 000 |
+| `sonnet` | `claude-sonnet-4-6` | Anthropic | 64 000 | 200 000 |
+| `haiku` | `claude-haiku-4-5-20251213` | Anthropic | 64 000 | 200 000 |
+| `grok` / `grok-3` | `grok-3` | xAI | 64 000 | 131 072 |
+| `grok-mini` / `grok-3-mini` | `grok-3-mini` | xAI | 64 000 | 131 072 |
+| `grok-2` | `grok-2` | xAI | — | — |
+
+Any model name that does not match an alias is passed through verbatim. This is how you use OpenRouter model slugs (`openai/gpt-4.1-mini`), Ollama tags (`llama3.2`), or full Anthropic model IDs (`claude-sonnet-4-20250514`).
+
+### User-defined aliases
+
+You can add custom aliases in any settings file (`~/.claw/settings.json`, `.claw/settings.json`, or `.claw/settings.local.json`):
+
+```json
+{
+ "aliases": {
+ "fast": "claude-haiku-4-5-20251213",
+ "smart": "claude-opus-4-6",
+ "cheap": "grok-3-mini"
+ }
+}
+```
+
+Local project settings override user-level settings. Aliases resolve through the built-in table, so `"fast": "haiku"` also works.
+
+### How provider detection works
+
+1. If the resolved model name starts with `claude` → Anthropic.
+2. If it starts with `grok` → xAI.
+3. Otherwise, `claw` checks which credential is set: `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN` first, then `OPENAI_API_KEY`, then `XAI_API_KEY`.
+4. If nothing matches, it defaults to Anthropic.
+
+## FAQ
+
+### What about Codex?
+
+The name "codex" appears in the Claw Code ecosystem but it does **not** refer to OpenAI Codex (the code-generation model). Here is what it means in this project:
+
+- **`oh-my-codex` (OmX)** is the workflow and plugin layer that sits on top of `claw`. It provides planning modes, parallel multi-agent execution, notification routing, and other automation features. See [PHILOSOPHY.md](./PHILOSOPHY.md) and the [oh-my-codex repo](https://github.com/Yeachan-Heo/oh-my-codex).
+- **`.codex/` directories** (e.g. `.codex/skills`, `.codex/agents`, `.codex/commands`) are legacy lookup paths that `claw` still scans alongside the primary `.claw/` directories.
+- **`CODEX_HOME`** is an optional environment variable that points to a custom root for user-level skill and command lookups.
+
+`claw` does **not** support OpenAI Codex sessions, the Codex CLI, or Codex session import/export. If you need to use OpenAI models (like GPT-4.1), configure the OpenAI-compatible provider as shown above in the [OpenAI-compatible endpoint](#openai-compatible-endpoint) and [OpenRouter](#openrouter) sections.
+
+## HTTP proxy support
+
+`claw` honours the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (both upper- and lower-case spellings are accepted) when issuing outbound requests to Anthropic, OpenAI-, and xAI-compatible endpoints. Set them before launching the CLI and the underlying `reqwest` client will be configured automatically.
+
+### Environment variables
+
+```bash
+export HTTPS_PROXY="http://proxy.corp.example:3128"
+export HTTP_PROXY="http://proxy.corp.example:3128"
+export NO_PROXY="localhost,127.0.0.1,.corp.example"
+
+cd rust
+./target/debug/claw prompt "hello via the corporate proxy"
+```
+
+### Programmatic `proxy_url` config option
+
+As an alternative to per-scheme environment variables, the `ProxyConfig` type exposes a `proxy_url` field that acts as a single catch-all proxy for both HTTP and HTTPS traffic. When `proxy_url` is set it takes precedence over the separate `http_proxy` and `https_proxy` fields.
+
+```rust
+use api::{build_http_client_with, ProxyConfig};
+
+// From a single unified URL (config file, CLI flag, etc.)
+let config = ProxyConfig::from_proxy_url("http://proxy.corp.example:3128");
+let client = build_http_client_with(&config).expect("proxy client");
+
+// Or set the field directly alongside NO_PROXY
+let config = ProxyConfig {
+ proxy_url: Some("http://proxy.corp.example:3128".to_string()),
+ no_proxy: Some("localhost,127.0.0.1".to_string()),
+ ..ProxyConfig::default()
+};
+let client = build_http_client_with(&config).expect("proxy client");
+```
+
+### Notes
+
+- When both `HTTPS_PROXY` and `HTTP_PROXY` are set, the secure proxy applies to `https://` URLs and the plain proxy applies to `http://` URLs.
+- `proxy_url` is a unified alternative: when set, it applies to both `http://` and `https://` destinations, overriding the per-scheme fields.
+- `NO_PROXY` accepts a comma-separated list of host suffixes (for example `.corp.example`) and IP literals.
+- Empty values are treated as unset, so leaving `HTTPS_PROXY=""` in your shell will not enable a proxy.
+- If a proxy URL cannot be parsed, `claw` falls back to a direct (no-proxy) client so existing workflows keep working; double-check the URL if you expected the request to be tunnelled.
+
## Common operational commands
```bash
diff --git a/assets/clawd-hero.jpeg b/assets/claw-hero.jpeg
similarity index 100%
rename from assets/clawd-hero.jpeg
rename to assets/claw-hero.jpeg
diff --git a/assets/instructkr.png b/assets/instructkr.png
deleted file mode 100644
index 08d300fb..00000000
Binary files a/assets/instructkr.png and /dev/null differ
diff --git a/assets/sigrid-photo.png b/assets/sigrid-photo.png
new file mode 100644
index 00000000..a70aa842
Binary files /dev/null and b/assets/sigrid-photo.png differ
diff --git a/docs/container.md b/docs/container.md
new file mode 100644
index 00000000..aeaa45e3
--- /dev/null
+++ b/docs/container.md
@@ -0,0 +1,132 @@
+# Container-first claw-code workflows
+
+This repo already had **container detection** in the Rust runtime before this document was added:
+
+- `rust/crates/runtime/src/sandbox.rs` detects Docker/Podman/container markers such as `/.dockerenv`, `/run/.containerenv`, matching env vars, and `/proc/1/cgroup` hints.
+- `rust/crates/rusty-claude-cli/src/main.rs` exposes that state through the `claw sandbox` / `cargo run -p rusty-claude-cli -- sandbox` report.
+- `.github/workflows/rust-ci.yml` runs on `ubuntu-latest`, but it does **not** define a Docker or Podman container job.
+- Before this change, the repo did **not** have a checked-in `Dockerfile`, `Containerfile`, or `.devcontainer/` config.
+
+This document adds a small checked-in `Containerfile` so Docker and Podman users have one canonical container workflow.
+
+## What the checked-in container image is for
+
+The root [`../Containerfile`](../Containerfile) gives you a reusable Rust build/test shell with the extra packages this workspace commonly needs (`git`, `pkg-config`, `libssl-dev`, certificates).
+
+It does **not** copy the repository into the image. Instead, the recommended flow is to bind-mount your checkout into `/workspace` so edits stay on the host.
+
+## Build the image
+
+From the repository root:
+
+### Docker
+
+```bash
+docker build -t claw-code-dev -f Containerfile .
+```
+
+### Podman
+
+```bash
+podman build -t claw-code-dev -f Containerfile .
+```
+
+## Run `cargo test --workspace` in the container
+
+These commands mount the repo, keep Cargo build artifacts out of the working tree, and run from the Rust workspace at `rust/`.
+
+### Docker
+
+```bash
+docker run --rm -it \
+ -v "$PWD":/workspace \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev \
+ cargo test --workspace
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+ -v "$PWD":/workspace:Z \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev \
+ cargo test --workspace
+```
+
+If you want a fully clean rebuild, add `cargo clean &&` before `cargo test --workspace`.
+
+## Open a shell in the container
+
+### Docker
+
+```bash
+docker run --rm -it \
+ -v "$PWD":/workspace \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+ -v "$PWD":/workspace:Z \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev
+```
+
+Inside the shell:
+
+```bash
+cargo build --workspace
+cargo test --workspace
+cargo run -p rusty-claude-cli -- --help
+cargo run -p rusty-claude-cli -- sandbox
+```
+
+The `sandbox` command is a useful sanity check: inside Docker or Podman it should report `In container true` and list the markers the runtime detected.
+
+## Bind-mount this repo and another repo at the same time
+
+If you want to run `claw` against a second checkout while keeping `claw-code` itself mounted read-write:
+
+### Docker
+
+```bash
+docker run --rm -it \
+ -v "$PWD":/workspace \
+ -v "$HOME/src/other-repo":/repo \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+ -v "$PWD":/workspace:Z \
+ -v "$HOME/src/other-repo":/repo:Z \
+ -e CARGO_TARGET_DIR=/tmp/claw-target \
+ -w /workspace/rust \
+ claw-code-dev
+```
+
+Then, for example:
+
+```bash
+cargo run -p rusty-claude-cli -- prompt "summarize /repo"
+```
+
+## Notes
+
+- Docker and Podman use the same checked-in `Containerfile`.
+- The `:Z` suffix in the Podman examples is for SELinux relabeling; keep it on Fedora/RHEL-class hosts.
+- Running with `CARGO_TARGET_DIR=/tmp/claw-target` avoids leaving container-owned `target/` artifacts in your bind-mounted checkout.
+- For non-container local development, keep using [`../USAGE.md`](../USAGE.md) and [`../rust/README.md`](../rust/README.md).
diff --git a/install.sh b/install.sh
new file mode 100755
index 00000000..c95cddaf
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,394 @@
+#!/usr/bin/env bash
+# Claw Code installer
+#
+# Detects the host OS, verifies the Rust toolchain (rustc + cargo),
+# builds the `claw` binary from the `rust/` workspace, and runs a
+# post-install verification step. Supports Linux, macOS, and WSL.
+#
+# Usage:
+# ./install.sh # debug build (fast, default)
+# ./install.sh --release # optimized release build
+# ./install.sh --no-verify # skip post-install verification
+# ./install.sh --help # print usage
+#
+# Environment overrides:
+# CLAW_BUILD_PROFILE=debug|release same as --release toggle
+# CLAW_SKIP_VERIFY=1 same as --no-verify
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Pretty printing
+# ---------------------------------------------------------------------------
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+ COLOR_RESET="$(tput sgr0)"
+ COLOR_BOLD="$(tput bold)"
+ COLOR_DIM="$(tput dim)"
+ COLOR_RED="$(tput setaf 1)"
+ COLOR_GREEN="$(tput setaf 2)"
+ COLOR_YELLOW="$(tput setaf 3)"
+ COLOR_BLUE="$(tput setaf 4)"
+ COLOR_CYAN="$(tput setaf 6)"
+else
+ COLOR_RESET=""
+ COLOR_BOLD=""
+ COLOR_DIM=""
+ COLOR_RED=""
+ COLOR_GREEN=""
+ COLOR_YELLOW=""
+ COLOR_BLUE=""
+ COLOR_CYAN=""
+fi
+
+CURRENT_STEP=0
+TOTAL_STEPS=6
+
+step() {
+ CURRENT_STEP=$((CURRENT_STEP + 1))
+ printf '\n%s[%d/%d]%s %s%s%s\n' \
+ "${COLOR_BLUE}" "${CURRENT_STEP}" "${TOTAL_STEPS}" "${COLOR_RESET}" \
+ "${COLOR_BOLD}" "$1" "${COLOR_RESET}"
+}
+
+info() { printf '%s ->%s %s\n' "${COLOR_CYAN}" "${COLOR_RESET}" "$1"; }
+ok() { printf '%s ok%s %s\n' "${COLOR_GREEN}" "${COLOR_RESET}" "$1"; }
+warn() { printf '%s warn%s %s\n' "${COLOR_YELLOW}" "${COLOR_RESET}" "$1"; }
+error() { printf '%s error%s %s\n' "${COLOR_RED}" "${COLOR_RESET}" "$1" 1>&2; }
+
+print_banner() {
+ printf '%s' "${COLOR_BOLD}"
+ cat <<'EOF'
+ ____ _ ____ _
+ / ___|| | __ _ __ __ / ___|___ __| | ___
+ | | | | / _` |\ \ /\ / /| | / _ \ / _` |/ _ \
+ | |___ | || (_| | \ V V / | |__| (_) | (_| | __/
+ \____||_| \__,_| \_/\_/ \____\___/ \__,_|\___|
+EOF
+ printf '%s\n' "${COLOR_RESET}"
+ printf '%sClaw Code installer%s\n' "${COLOR_DIM}" "${COLOR_RESET}"
+}
+
+print_usage() {
+ cat <<'EOF'
+Usage: ./install.sh [options]
+
+Options:
+ --release Build the optimized release profile (slower, smaller binary).
+ --debug Build the debug profile (default, faster compile).
+ --no-verify Skip the post-install verification step.
+ -h, --help Show this help text and exit.
+
+Environment overrides:
+ CLAW_BUILD_PROFILE debug | release
+ CLAW_SKIP_VERIFY set to 1 to skip verification
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+BUILD_PROFILE="${CLAW_BUILD_PROFILE:-debug}"
+SKIP_VERIFY="${CLAW_SKIP_VERIFY:-0}"
+
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --release)
+ BUILD_PROFILE="release"
+ ;;
+ --debug)
+ BUILD_PROFILE="debug"
+ ;;
+ --no-verify)
+ SKIP_VERIFY="1"
+ ;;
+ -h|--help)
+ print_usage
+ exit 0
+ ;;
+ *)
+ error "unknown argument: $1"
+ print_usage
+ exit 2
+ ;;
+ esac
+ shift
+done
+
+case "${BUILD_PROFILE}" in
+ debug|release) ;;
+ *)
+ error "invalid build profile: ${BUILD_PROFILE} (expected debug or release)"
+ exit 2
+ ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Troubleshooting hints
+# ---------------------------------------------------------------------------
+
+print_troubleshooting() {
+ cat </dev/null 2>&1
+}
+
+# ---------------------------------------------------------------------------
+# Step 1: detect OS / arch / WSL
+# ---------------------------------------------------------------------------
+
+print_banner
+step "Detecting host environment"
+
+UNAME_S="$(uname -s 2>/dev/null || echo unknown)"
+UNAME_M="$(uname -m 2>/dev/null || echo unknown)"
+OS_FAMILY="unknown"
+IS_WSL="0"
+
+case "${UNAME_S}" in
+ Linux*)
+ OS_FAMILY="linux"
+ if grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null; then
+ IS_WSL="1"
+ fi
+ ;;
+ Darwin*)
+ OS_FAMILY="macos"
+ ;;
+ MINGW*|MSYS*|CYGWIN*)
+ OS_FAMILY="windows-shell"
+ ;;
+esac
+
+info "uname: ${UNAME_S} ${UNAME_M}"
+info "os family: ${OS_FAMILY}"
+if [ "${IS_WSL}" = "1" ]; then
+ info "wsl: yes"
+fi
+
+case "${OS_FAMILY}" in
+ linux|macos)
+ ok "supported platform detected"
+ ;;
+ windows-shell)
+ error "Detected a native Windows shell (MSYS/Cygwin/MinGW)."
+ error "Please re-run this script from inside a WSL distribution."
+ exit 1
+ ;;
+ *)
+ error "Unsupported or unknown OS: ${UNAME_S}"
+ error "Supported: Linux, macOS, and Windows via WSL."
+ exit 1
+ ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Step 2: locate the Rust workspace
+# ---------------------------------------------------------------------------
+
+step "Locating the Rust workspace"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RUST_DIR="${SCRIPT_DIR}/rust"
+
+if [ ! -d "${RUST_DIR}" ]; then
+ error "Could not find rust/ workspace next to install.sh"
+ error "Expected: ${RUST_DIR}"
+ exit 1
+fi
+
+if [ ! -f "${RUST_DIR}/Cargo.toml" ]; then
+ error "Missing ${RUST_DIR}/Cargo.toml — repository layout looks unexpected."
+ exit 1
+fi
+
+ok "workspace at ${RUST_DIR}"
+
+# ---------------------------------------------------------------------------
+# Step 3: prerequisite checks
+# ---------------------------------------------------------------------------
+
+step "Checking prerequisites"
+
+MISSING_PREREQS=0
+
+if require_cmd rustc; then
+ RUSTC_VERSION="$(rustc --version 2>/dev/null || echo 'unknown')"
+ ok "rustc found: ${RUSTC_VERSION}"
+else
+ error "rustc not found in PATH"
+ MISSING_PREREQS=1
+fi
+
+if require_cmd cargo; then
+ CARGO_VERSION="$(cargo --version 2>/dev/null || echo 'unknown')"
+ ok "cargo found: ${CARGO_VERSION}"
+else
+ error "cargo not found in PATH"
+ MISSING_PREREQS=1
+fi
+
+if require_cmd git; then
+ ok "git found: $(git --version 2>/dev/null || echo 'unknown')"
+else
+ warn "git not found — some workflows (login, session export) may degrade"
+fi
+
+if [ "${OS_FAMILY}" = "linux" ]; then
+ if require_cmd pkg-config; then
+ ok "pkg-config found"
+ else
+ warn "pkg-config not found — may be required for OpenSSL-linked crates"
+ fi
+fi
+
+if [ "${OS_FAMILY}" = "macos" ]; then
+ if ! require_cmd cc && ! xcode-select -p >/dev/null 2>&1; then
+ warn "Xcode command line tools not detected — run: xcode-select --install"
+ fi
+fi
+
+if [ "${MISSING_PREREQS}" -ne 0 ]; then
+ error "Missing required tools. See troubleshooting below."
+ exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: build the workspace
+# ---------------------------------------------------------------------------
+
+step "Building the claw workspace (${BUILD_PROFILE})"
+
+CARGO_FLAGS=("build" "--workspace")
+if [ "${BUILD_PROFILE}" = "release" ]; then
+ CARGO_FLAGS+=("--release")
+fi
+
+info "running: cargo ${CARGO_FLAGS[*]}"
+info "this may take a few minutes on the first build"
+
+(
+ cd "${RUST_DIR}"
+ CARGO_TERM_COLOR="${CARGO_TERM_COLOR:-always}" cargo "${CARGO_FLAGS[@]}"
+)
+
+CLAW_BIN="${RUST_DIR}/target/${BUILD_PROFILE}/claw"
+
+if [ ! -x "${CLAW_BIN}" ]; then
+ error "Expected binary not found at ${CLAW_BIN}"
+ error "The build reported success but the binary is missing — check cargo output above."
+ exit 1
+fi
+
+ok "built ${CLAW_BIN}"
+
+# ---------------------------------------------------------------------------
+# Step 5: post-install verification
+# ---------------------------------------------------------------------------
+
+step "Verifying the installed binary"
+
+if [ "${SKIP_VERIFY}" = "1" ]; then
+ warn "verification skipped (--no-verify or CLAW_SKIP_VERIFY=1)"
+else
+ info "running: claw --version"
+ if VERSION_OUT="$("${CLAW_BIN}" --version 2>&1)"; then
+ ok "claw --version -> ${VERSION_OUT}"
+ else
+ error "claw --version failed:"
+ printf '%s\n' "${VERSION_OUT}" 1>&2
+ exit 1
+ fi
+
+ info "running: claw --help (smoke test)"
+ if "${CLAW_BIN}" --help >/dev/null 2>&1; then
+ ok "claw --help responded"
+ else
+ error "claw --help failed"
+ exit 1
+ fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 6: next steps
+# ---------------------------------------------------------------------------
+
+step "Next steps"
+
+cat < One-shot prompt (non-interactive)
- login Authenticate via OAuth
- logout Clear stored credentials
- init Initialize project config
- status Show the current workspace status snapshot
- sandbox Show the current sandbox isolation snapshot
- agents Inspect agent definitions
- mcp Inspect configured MCP servers
- skills Inspect installed skills
- system-prompt Render the assembled system prompt
+Top-level commands:
+ prompt
+ help
+ version
+ status
+ sandbox
+ dump-manifests
+ bootstrap-plan
+ agents
+ mcp
+ skills
+ system-prompt
+ login
+ logout
+ init
```
-For the current canonical help text, run `cargo run -p rusty-claude-cli -- --help`.
+The command surface is moving quickly. For the canonical live help text, run:
+
+```bash
+cargo run -p rusty-claude-cli -- --help
+```
## Slash Commands (REPL)
Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.
-| Command | Description |
-|---------|-------------|
-| `/help` | Show help |
-| `/status` | Show session status (model, tokens, cost) |
-| `/cost` | Show cost breakdown |
-| `/compact` | Compact conversation history |
-| `/clear` | Clear conversation |
-| `/model [name]` | Show or switch model |
-| `/permissions` | Show or switch permission mode |
-| `/config [section]` | Show config (env, hooks, model) |
-| `/memory` | Show CLAUDE.md contents |
-| `/diff` | Show git diff |
-| `/export [path]` | Export conversation |
-| `/resume [id]` | Resume a saved conversation |
-| `/session [id]` | Resume a previous session |
-| `/version` | Show version |
+The REPL now exposes a much broader surface than the original minimal shell:
-See [`../USAGE.md`](../USAGE.md) for examples covering interactive use, JSON automation, sessions, permissions, and the mock parity harness.
+- session / visibility: `/help`, `/status`, `/sandbox`, `/cost`, `/resume`, `/session`, `/version`, `/usage`, `/stats`
+- workspace / git: `/compact`, `/clear`, `/config`, `/memory`, `/init`, `/diff`, `/commit`, `/pr`, `/issue`, `/export`, `/hooks`, `/files`, `/branch`, `/release-notes`, `/add-dir`
+- discovery / debugging: `/mcp`, `/agents`, `/skills`, `/doctor`, `/tasks`, `/context`, `/desktop`, `/ide`
+- automation / analysis: `/review`, `/advisor`, `/insights`, `/security-review`, `/subagent`, `/team`, `/telemetry`, `/providers`, `/cron`, and more
+- plugin management: `/plugin` (with aliases `/plugins`, `/marketplace`)
+
+Notable claw-first surfaces now available directly in slash form:
+- `/skills [list|install |help]`
+- `/agents [list|help]`
+- `/mcp [list|show |help]`
+- `/doctor`
+- `/plugin [list|install |enable |disable |uninstall |update ]`
+- `/subagent [list|steer |kill ]`
+
+See [`../USAGE.md`](../USAGE.md) for usage examples and run `cargo run -p rusty-claude-cli -- --help` for the live canonical command list.
## Workspace Layout
-```
+```text
rust/
├── Cargo.toml # Workspace root
├── Cargo.lock
└── crates/
- ├── api/ # Anthropic API client + SSE streaming
- ├── commands/ # Shared slash-command registry
+ ├── api/ # Provider clients + streaming + request preflight
+ ├── commands/ # Shared slash-command registry + help rendering
├── compat-harness/ # TS manifest extraction harness
├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
- ├── plugins/ # Plugin registry and hook wiring primitives
- ├── runtime/ # Session, config, permissions, MCP, prompts
+ ├── plugins/ # Plugin metadata, manager, install/enable/disable surfaces
+ ├── runtime/ # Session, config, permissions, MCP, prompts, auth/runtime loop
├── rusty-claude-cli/ # Main CLI binary (`claw`)
├── telemetry/ # Session tracing and usage telemetry types
- └── tools/ # Built-in tool implementations
+ └── tools/ # Built-in tools, skill resolution, tool search, agent runtime surfaces
```
### Crate Responsibilities
-- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer)
-- **commands** — Slash command definitions and help text generation
-- **compat-harness** — Extracts tool/prompt manifests from upstream TS source
-- **mock-anthropic-service** — Deterministic `/v1/messages` mock for CLI parity tests and local harness runs
-- **plugins** — Plugin metadata, registries, and hook integration surfaces
-- **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking
-- **rusty-claude-cli** — REPL, one-shot prompt, streaming display, tool call rendering, CLI argument parsing
-- **telemetry** — Session trace events and supporting telemetry payloads
-- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
+- **api** — provider clients, SSE streaming, request/response types, auth (API key + OAuth bearer), request-size/context-window preflight
+- **commands** — slash command definitions, parsing, help text generation, JSON/text command rendering
+- **compat-harness** — extracts tool/prompt manifests from upstream TS source
+- **mock-anthropic-service** — deterministic `/v1/messages` mock for CLI parity tests and local harness runs
+- **plugins** — plugin metadata, install/enable/disable/update flows, plugin tool definitions, hook integration surfaces
+- **runtime** — `ConversationRuntime`, config loading, session persistence, permission policy, MCP client lifecycle, system prompt assembly, usage tracking
+- **rusty-claude-cli** — REPL, one-shot prompt, direct CLI subcommands, streaming display, tool call rendering, CLI argument parsing
+- **telemetry** — session trace events and supporting telemetry payloads
+- **tools** — tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, and runtime-facing tool discovery
## Stats
diff --git a/rust/TUI-ENHANCEMENT-PLAN.md b/rust/TUI-ENHANCEMENT-PLAN.md
index d2a06574..a9de6c35 100644
--- a/rust/TUI-ENHANCEMENT-PLAN.md
+++ b/rust/TUI-ENHANCEMENT-PLAN.md
@@ -20,12 +20,14 @@ This plan covers a comprehensive analysis of the current terminal user interface
### Current TUI Components
+> Note: The legacy prototype files `app.rs` and `args.rs` were removed on 2026-04-05.
+> References below describe future extraction targets, not current tracked source files.
+
| Component | File | What It Does Today | Quality |
|---|---|---|---|
| **Input** | `input.rs` (269 lines) | `rustyline`-based line editor with slash-command tab completion, Shift+Enter newline, history | ✅ Solid |
| **Rendering** | `render.rs` (641 lines) | Markdown→terminal rendering (headings, lists, tables, code blocks with syntect highlighting, blockquotes), spinner widget | ✅ Good |
| **App/REPL loop** | `main.rs` (3,159 lines) | The monolithic `LiveCli` struct: REPL loop, all slash command handlers, streaming output, tool call display, permission prompting, session management | ⚠️ Monolithic |
-| **Alt App** | `app.rs` (398 lines) | An earlier `CliApp` prototype with `ConversationClient`, stream event handling, `TerminalRenderer`, output format support | ⚠️ Appears unused/legacy |
### Key Dependencies
@@ -56,7 +58,7 @@ This plan covers a comprehensive analysis of the current terminal user interface
8. **Streaming is char-by-char with artificial delay** — `stream_markdown` sleeps 8ms per whitespace-delimited chunk
9. **No color theme customization** — hardcoded `ColorTheme::default()`
10. **No resize handling** — no terminal size awareness for wrapping, truncation, or layout
-11. **Dual app structs** — `app.rs` has a separate `CliApp` that duplicates `LiveCli` from `main.rs`
+11. **Historical dual app split** — the repo previously carried a separate `CliApp` prototype alongside `LiveCli`; the prototype is gone, but the monolithic `main.rs` still needs extraction
12. **No pager for long outputs** — `/status`, `/config`, `/memory` can overflow the viewport
13. **Tool results not collapsible** — large bash outputs flood the screen
14. **No thinking/reasoning indicator** — when the model is in "thinking" mode, no visual distinction
@@ -73,8 +75,8 @@ This plan covers a comprehensive analysis of the current terminal user interface
| Task | Description | Effort |
|---|---|---|
| 0.1 | **Extract `LiveCli` into `app.rs`** — Move the entire `LiveCli` struct, its impl, and helpers (`format_*`, `render_*`, session management) out of `main.rs` into focused modules: `app.rs` (core), `format.rs` (report formatting), `session_manager.rs` (session CRUD) | M |
-| 0.2 | **Remove or merge the legacy `CliApp`** — The existing `app.rs` has an unused `CliApp` with its own `ConversationClient`-based rendering. Either delete it or merge its unique features (stream event handler pattern) into the active `LiveCli` | S |
-| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is a hand-rolled parser that duplicates the clap-based `args.rs`. Consolidate on the hand-rolled parser (it's more feature-complete) and move it to `args.rs`, or adopt clap fully | S |
+| 0.2 | **Keep the legacy `CliApp` removed** — The old `CliApp` prototype has already been deleted; if any unique ideas remain valuable (for example stream event handler patterns), reintroduce them intentionally inside the active `LiveCli` extraction rather than restoring the old file wholesale | S |
+| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is still a hand-rolled parser in `main.rs`. If parsing is extracted later, do it into a newly-introduced module intentionally rather than reviving the removed prototype `args.rs` by accident | S |
| 0.4 | **Create a `tui/` module** — Introduce `crates/rusty-claude-cli/src/tui/mod.rs` as the namespace for all new TUI components: `status_bar.rs`, `layout.rs`, `tool_panel.rs`, etc. | S |
### Phase 1: Status Bar & Live HUD
@@ -214,7 +216,7 @@ crates/rusty-claude-cli/src/
| Terminal compatibility issues (tmux, SSH, Windows) | Rely on crossterm's abstraction; test in degraded environments |
| Performance regression with rich rendering | Profile before/after; keep the fast path (raw streaming) always available |
| Scope creep into Phase 6 | Ship Phases 0–3 as a coherent release before starting Phase 6 |
-| `app.rs` vs `main.rs` confusion | Phase 0.2 explicitly resolves this by removing the legacy `CliApp` |
+| Historical `app.rs` vs `main.rs` confusion | Keep the legacy prototype removed and avoid reintroducing a second app surface accidentally during extraction |
---
diff --git a/rust/crates/api/src/error.rs b/rust/crates/api/src/error.rs
index 76498891..2aa84d94 100644
--- a/rust/crates/api/src/error.rs
+++ b/rust/crates/api/src/error.rs
@@ -2,22 +2,50 @@ use std::env::VarError;
use std::fmt::{Display, Formatter};
use std::time::Duration;
+const GENERIC_FATAL_WRAPPER_MARKERS: &[&str] = &[
+ "something went wrong while processing your request",
+ "please try again, or use /new to start a fresh session",
+];
+
+const CONTEXT_WINDOW_ERROR_MARKERS: &[&str] = &[
+ "maximum context length",
+ "context window",
+ "context length",
+ "too many tokens",
+ "prompt is too long",
+ "input is too long",
+ "request is too large",
+];
+
#[derive(Debug)]
pub enum ApiError {
MissingCredentials {
provider: &'static str,
env_vars: &'static [&'static str],
},
+ ContextWindowExceeded {
+ model: String,
+ estimated_input_tokens: u32,
+ requested_output_tokens: u32,
+ estimated_total_tokens: u32,
+ context_window_tokens: u32,
+ },
ExpiredOAuthToken,
Auth(String),
InvalidApiKeyEnv(VarError),
Http(reqwest::Error),
Io(std::io::Error),
- Json(serde_json::Error),
+ Json {
+ provider: String,
+ model: String,
+ body_snippet: String,
+ source: serde_json::Error,
+ },
Api {
status: reqwest::StatusCode,
error_type: Option,
message: Option,
+ request_id: Option,
body: String,
retryable: bool,
},
@@ -41,6 +69,25 @@ impl ApiError {
Self::MissingCredentials { provider, env_vars }
}
+ /// Build a `Self::Json` enriched with the provider name, the model that
+ /// was requested, and the first 200 characters of the raw response body so
+ /// that callers can diagnose deserialization failures without re-running
+ /// the request.
+ #[must_use]
+ pub fn json_deserialize(
+ provider: impl Into,
+ model: impl Into,
+ body: &str,
+ source: serde_json::Error,
+ ) -> Self {
+ Self::Json {
+ provider: provider.into(),
+ model: model.into(),
+ body_snippet: truncate_body_snippet(body, 200),
+ source,
+ }
+ }
+
#[must_use]
pub fn is_retryable(&self) -> bool {
match self {
@@ -48,11 +95,106 @@ impl ApiError {
Self::Api { retryable, .. } => *retryable,
Self::RetriesExhausted { last_error, .. } => last_error.is_retryable(),
Self::MissingCredentials { .. }
+ | Self::ContextWindowExceeded { .. }
| Self::ExpiredOAuthToken
| Self::Auth(_)
| Self::InvalidApiKeyEnv(_)
| Self::Io(_)
- | Self::Json(_)
+ | Self::Json { .. }
+ | Self::InvalidSseFrame(_)
+ | Self::BackoffOverflow { .. } => false,
+ }
+ }
+
+ #[must_use]
+ pub fn request_id(&self) -> Option<&str> {
+ match self {
+ Self::Api { request_id, .. } => request_id.as_deref(),
+ Self::RetriesExhausted { last_error, .. } => last_error.request_id(),
+ Self::MissingCredentials { .. }
+ | Self::ContextWindowExceeded { .. }
+ | Self::ExpiredOAuthToken
+ | Self::Auth(_)
+ | Self::InvalidApiKeyEnv(_)
+ | Self::Http(_)
+ | Self::Io(_)
+ | Self::Json { .. }
+ | Self::InvalidSseFrame(_)
+ | Self::BackoffOverflow { .. } => None,
+ }
+ }
+
+ #[must_use]
+ pub fn safe_failure_class(&self) -> &'static str {
+ match self {
+ Self::RetriesExhausted { .. } if self.is_context_window_failure() => "context_window",
+ Self::RetriesExhausted { .. } if self.is_generic_fatal_wrapper() => {
+ "provider_retry_exhausted"
+ }
+ Self::RetriesExhausted { last_error, .. } => last_error.safe_failure_class(),
+ Self::MissingCredentials { .. } | Self::ExpiredOAuthToken | Self::Auth(_) => {
+ "provider_auth"
+ }
+ Self::Api { status, .. } if matches!(status.as_u16(), 401 | 403) => "provider_auth",
+ Self::ContextWindowExceeded { .. } => "context_window",
+ Self::Api { .. } if self.is_context_window_failure() => "context_window",
+ Self::Api { status, .. } if status.as_u16() == 429 => "provider_rate_limit",
+ Self::Api { .. } if self.is_generic_fatal_wrapper() => "provider_internal",
+ Self::Api { .. } => "provider_error",
+ Self::Http(_) | Self::InvalidSseFrame(_) | Self::BackoffOverflow { .. } => {
+ "provider_transport"
+ }
+ Self::InvalidApiKeyEnv(_) | Self::Io(_) | Self::Json { .. } => "runtime_io",
+ }
+ }
+
+ #[must_use]
+ pub fn is_generic_fatal_wrapper(&self) -> bool {
+ match self {
+ Self::Api { message, body, .. } => {
+ message
+ .as_deref()
+ .is_some_and(looks_like_generic_fatal_wrapper)
+ || looks_like_generic_fatal_wrapper(body)
+ }
+ Self::RetriesExhausted { last_error, .. } => last_error.is_generic_fatal_wrapper(),
+ Self::MissingCredentials { .. }
+ | Self::ContextWindowExceeded { .. }
+ | Self::ExpiredOAuthToken
+ | Self::Auth(_)
+ | Self::InvalidApiKeyEnv(_)
+ | Self::Http(_)
+ | Self::Io(_)
+ | Self::Json { .. }
+ | Self::InvalidSseFrame(_)
+ | Self::BackoffOverflow { .. } => false,
+ }
+ }
+
+ #[must_use]
+ pub fn is_context_window_failure(&self) -> bool {
+ match self {
+ Self::ContextWindowExceeded { .. } => true,
+ Self::Api {
+ status,
+ message,
+ body,
+ ..
+ } => {
+ matches!(status.as_u16(), 400 | 413 | 422)
+ && (message
+ .as_deref()
+ .is_some_and(looks_like_context_window_error)
+ || looks_like_context_window_error(body))
+ }
+ Self::RetriesExhausted { last_error, .. } => last_error.is_context_window_failure(),
+ Self::MissingCredentials { .. }
+ | Self::ExpiredOAuthToken
+ | Self::Auth(_)
+ | Self::InvalidApiKeyEnv(_)
+ | Self::Http(_)
+ | Self::Io(_)
+ | Self::Json { .. }
| Self::InvalidSseFrame(_)
| Self::BackoffOverflow { .. } => false,
}
@@ -62,10 +204,36 @@ impl ApiError {
impl Display for ApiError {
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
match self {
- Self::MissingCredentials { provider, env_vars } => write!(
+ Self::MissingCredentials { provider, env_vars } => {
+ write!(
+ f,
+ "missing {provider} credentials; export {} before calling the {provider} API",
+ env_vars.join(" or ")
+ )?;
+ if cfg!(target_os = "windows") {
+ if let Some(primary) = env_vars.first() {
+ write!(
+ f,
+ " (on Windows, environment variables set in PowerShell only persist for the current session; use `setx {primary} ` to make it permanent, then open a new terminal, or place a `.env` file containing `{primary}=` in the current working directory)"
+ )?;
+ } else {
+ write!(
+ f,
+ " (on Windows, environment variables set in PowerShell only persist for the current session; use `setx` to make them permanent, then open a new terminal, or place a `.env` file in the current working directory)"
+ )?;
+ }
+ }
+ Ok(())
+ }
+ Self::ContextWindowExceeded {
+ model,
+ estimated_input_tokens,
+ requested_output_tokens,
+ estimated_total_tokens,
+ context_window_tokens,
+ } => write!(
f,
- "missing {provider} credentials; export {} before calling the {provider} API",
- env_vars.join(" or ")
+ "context_window_blocked for {model}: estimated input {estimated_input_tokens} + requested output {requested_output_tokens} = {estimated_total_tokens} tokens exceeds the {context_window_tokens}-token context window; compact the session or reduce request size before retrying"
),
Self::ExpiredOAuthToken => {
write!(
@@ -79,19 +247,37 @@ impl Display for ApiError {
}
Self::Http(error) => write!(f, "http error: {error}"),
Self::Io(error) => write!(f, "io error: {error}"),
- Self::Json(error) => write!(f, "json error: {error}"),
+ Self::Json {
+ provider,
+ model,
+ body_snippet,
+ source,
+ } => write!(
+ f,
+ "failed to parse {provider} response for model {model}: {source}; first 200 chars of body: {body_snippet}"
+ ),
Self::Api {
status,
error_type,
message,
+ request_id,
body,
..
- } => match (error_type, message) {
- (Some(error_type), Some(message)) => {
- write!(f, "api returned {status} ({error_type}): {message}")
+ } => {
+ if let (Some(error_type), Some(message)) = (error_type, message) {
+ write!(f, "api returned {status} ({error_type})")?;
+ if let Some(request_id) = request_id {
+ write!(f, " [trace {request_id}]")?;
+ }
+ write!(f, ": {message}")
+ } else {
+ write!(f, "api returned {status}")?;
+ if let Some(request_id) = request_id {
+ write!(f, " [trace {request_id}]")?;
+ }
+ write!(f, ": {body}")
}
- _ => write!(f, "api returned {status}: {body}"),
- },
+ }
Self::RetriesExhausted {
attempts,
last_error,
@@ -124,7 +310,12 @@ impl From for ApiError {
impl From for ApiError {
fn from(value: serde_json::Error) -> Self {
- Self::Json(value)
+ Self::Json {
+ provider: "unknown".to_string(),
+ model: "unknown".to_string(),
+ body_snippet: String::new(),
+ source: value,
+ }
}
}
@@ -133,3 +324,163 @@ impl From for ApiError {
Self::InvalidApiKeyEnv(value)
}
}
+
+fn looks_like_generic_fatal_wrapper(text: &str) -> bool {
+ let lowered = text.to_ascii_lowercase();
+ GENERIC_FATAL_WRAPPER_MARKERS
+ .iter()
+ .any(|marker| lowered.contains(marker))
+}
+
+fn looks_like_context_window_error(text: &str) -> bool {
+ let lowered = text.to_ascii_lowercase();
+ CONTEXT_WINDOW_ERROR_MARKERS
+ .iter()
+ .any(|marker| lowered.contains(marker))
+}
+
+/// Truncate `body` so the resulting snippet contains at most `max_chars`
+/// characters (counted by Unicode scalar values, not bytes), preserving the
+/// leading slice of the body that the caller most often needs to inspect.
+fn truncate_body_snippet(body: &str, max_chars: usize) -> String {
+ let mut taken_chars = 0;
+ let mut byte_end = 0;
+ for (offset, character) in body.char_indices() {
+ if taken_chars >= max_chars {
+ break;
+ }
+ taken_chars += 1;
+ byte_end = offset + character.len_utf8();
+ }
+ if taken_chars >= max_chars && byte_end < body.len() {
+ format!("{}…", &body[..byte_end])
+ } else {
+ body[..byte_end].to_string()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{truncate_body_snippet, ApiError};
+
+ #[test]
+ fn json_deserialize_error_includes_provider_model_and_truncated_body_snippet() {
+ let raw_body = format!("{}{}", "x".repeat(190), "_TAIL_PAST_200_CHARS_MARKER_");
+ let source = serde_json::from_str::("{not json")
+ .expect_err("invalid json should fail to parse");
+
+ let error = ApiError::json_deserialize("Anthropic", "claude-opus-4-6", &raw_body, source);
+ let rendered = error.to_string();
+
+ assert!(
+ rendered.starts_with("failed to parse Anthropic response for model claude-opus-4-6: "),
+ "rendered error should lead with provider and model: {rendered}"
+ );
+ assert!(
+ rendered.contains("first 200 chars of body: "),
+ "rendered error should label the body snippet: {rendered}"
+ );
+ let snippet = rendered
+ .split("first 200 chars of body: ")
+ .nth(1)
+ .expect("snippet section should be present");
+ assert!(
+ snippet.starts_with(&"x".repeat(190)),
+ "snippet should preserve the leading characters of the body: {snippet}"
+ );
+ assert!(
+ snippet.ends_with('…'),
+ "snippet should signal truncation with an ellipsis: {snippet}"
+ );
+ assert!(
+ !snippet.contains("_TAIL_PAST_200_CHARS_MARKER_"),
+ "snippet should drop characters past the 200-char cap: {snippet}"
+ );
+ assert_eq!(error.safe_failure_class(), "runtime_io");
+ assert_eq!(error.request_id(), None);
+ assert!(!error.is_retryable());
+ }
+
+ #[test]
+ fn truncate_body_snippet_keeps_short_bodies_intact() {
+ assert_eq!(truncate_body_snippet("hello", 200), "hello");
+ assert_eq!(truncate_body_snippet("", 200), "");
+ }
+
+ #[test]
+ fn truncate_body_snippet_caps_long_bodies_at_max_chars() {
+ let body = "a".repeat(250);
+ let snippet = truncate_body_snippet(&body, 200);
+ assert_eq!(snippet.chars().count(), 201, "200 chars + ellipsis");
+ assert!(snippet.ends_with('…'));
+ assert!(snippet.starts_with(&"a".repeat(200)));
+ }
+
+ #[test]
+ fn truncate_body_snippet_does_not_split_multibyte_characters() {
+ let body = "한글한글한글한글한글한글";
+ let snippet = truncate_body_snippet(body, 4);
+ assert_eq!(snippet, "한글한글…");
+ }
+
+ #[test]
+ fn detects_generic_fatal_wrapper_and_classifies_it_as_provider_internal() {
+ let error = ApiError::Api {
+ status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
+ error_type: Some("api_error".to_string()),
+ message: Some(
+ "Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
+ .to_string(),
+ ),
+ request_id: Some("req_jobdori_123".to_string()),
+ body: String::new(),
+ retryable: true,
+ };
+
+ assert!(error.is_generic_fatal_wrapper());
+ assert_eq!(error.safe_failure_class(), "provider_internal");
+ assert_eq!(error.request_id(), Some("req_jobdori_123"));
+ assert!(error.to_string().contains("[trace req_jobdori_123]"));
+ }
+
+ #[test]
+ fn retries_exhausted_preserves_nested_request_id_and_failure_class() {
+ let error = ApiError::RetriesExhausted {
+ attempts: 3,
+ last_error: Box::new(ApiError::Api {
+ status: reqwest::StatusCode::BAD_GATEWAY,
+ error_type: Some("api_error".to_string()),
+ message: Some(
+ "Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
+ .to_string(),
+ ),
+ request_id: Some("req_nested_456".to_string()),
+ body: String::new(),
+ retryable: true,
+ }),
+ };
+
+ assert!(error.is_generic_fatal_wrapper());
+ assert_eq!(error.safe_failure_class(), "provider_retry_exhausted");
+ assert_eq!(error.request_id(), Some("req_nested_456"));
+ }
+
+ #[test]
+ fn classifies_provider_context_window_errors() {
+ let error = ApiError::Api {
+ status: reqwest::StatusCode::BAD_REQUEST,
+ error_type: Some("invalid_request_error".to_string()),
+ message: Some(
+ "This model's maximum context length is 200000 tokens, but your request used 230000 tokens."
+ .to_string(),
+ ),
+ request_id: Some("req_ctx_123".to_string()),
+ body: String::new(),
+ retryable: false,
+ };
+
+ assert!(error.is_context_window_failure());
+ assert_eq!(error.safe_failure_class(), "context_window");
+ assert_eq!(error.request_id(), Some("req_ctx_123"));
+ }
+}
diff --git a/rust/crates/api/src/http_client.rs b/rust/crates/api/src/http_client.rs
new file mode 100644
index 00000000..508a5775
--- /dev/null
+++ b/rust/crates/api/src/http_client.rs
@@ -0,0 +1,344 @@
+use crate::error::ApiError;
+
+const HTTP_PROXY_KEYS: [&str; 2] = ["HTTP_PROXY", "http_proxy"];
+const HTTPS_PROXY_KEYS: [&str; 2] = ["HTTPS_PROXY", "https_proxy"];
+const NO_PROXY_KEYS: [&str; 2] = ["NO_PROXY", "no_proxy"];
+
+/// Snapshot of the proxy-related environment variables that influence the
+/// outbound HTTP client. Captured up front so callers can inspect, log, and
+/// test the resolved configuration without re-reading the process environment.
+///
+/// When `proxy_url` is set it acts as a single catch-all proxy for both
+/// HTTP and HTTPS traffic, taking precedence over the per-scheme fields.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ProxyConfig {
+ pub http_proxy: Option,
+ pub https_proxy: Option,
+ pub no_proxy: Option,
+ /// Optional unified proxy URL that applies to both HTTP and HTTPS.
+ /// When set, this takes precedence over `http_proxy` and `https_proxy`.
+ pub proxy_url: Option,
+}
+
+impl ProxyConfig {
+ /// Read proxy settings from the live process environment, honouring both
+ /// the upper- and lower-case spellings used by curl, git, and friends.
+ #[must_use]
+ pub fn from_env() -> Self {
+ Self::from_lookup(|key| std::env::var(key).ok())
+ }
+
+ /// Create a proxy configuration from a single URL that applies to both
+ /// HTTP and HTTPS traffic. This is the config-file alternative to setting
+ /// `HTTP_PROXY` and `HTTPS_PROXY` environment variables separately.
+ #[must_use]
+ pub fn from_proxy_url(url: impl Into) -> Self {
+ Self {
+ proxy_url: Some(url.into()),
+ ..Self::default()
+ }
+ }
+
+ fn from_lookup(mut lookup: F) -> Self
+ where
+ F: FnMut(&str) -> Option,
+ {
+ Self {
+ http_proxy: first_non_empty(&HTTP_PROXY_KEYS, &mut lookup),
+ https_proxy: first_non_empty(&HTTPS_PROXY_KEYS, &mut lookup),
+ no_proxy: first_non_empty(&NO_PROXY_KEYS, &mut lookup),
+ proxy_url: None,
+ }
+ }
+
+ #[must_use]
+ pub fn is_empty(&self) -> bool {
+ self.proxy_url.is_none() && self.http_proxy.is_none() && self.https_proxy.is_none()
+ }
+}
+
+/// Build a `reqwest::Client` that honours the standard `HTTP_PROXY`,
+/// `HTTPS_PROXY`, and `NO_PROXY` environment variables. When no proxy is
+/// configured the client behaves identically to `reqwest::Client::new()`.
+pub fn build_http_client() -> Result {
+ build_http_client_with(&ProxyConfig::from_env())
+}
+
+/// Infallible counterpart to [`build_http_client`] for constructors that
+/// historically returned `Self` rather than `Result`. When the proxy
+/// configuration is malformed we fall back to a default client so that
+/// callers retain the previous behaviour and the failure surfaces on the
+/// first outbound request instead of at construction time.
+#[must_use]
+pub fn build_http_client_or_default() -> reqwest::Client {
+ build_http_client().unwrap_or_else(|_| reqwest::Client::new())
+}
+
+/// Build a `reqwest::Client` from an explicit [`ProxyConfig`]. Used by tests
+/// and by callers that want to override process-level environment lookups.
+///
+/// When `config.proxy_url` is set it overrides the per-scheme `http_proxy`
+/// and `https_proxy` fields and is registered as both an HTTP and HTTPS
+/// proxy so a single value can route every outbound request.
+pub fn build_http_client_with(config: &ProxyConfig) -> Result {
+ let mut builder = reqwest::Client::builder().no_proxy();
+
+ let no_proxy = config
+ .no_proxy
+ .as_deref()
+ .and_then(reqwest::NoProxy::from_string);
+
+ let (http_proxy_url, https_proxy_url) = match config.proxy_url.as_deref() {
+ Some(unified) => (Some(unified), Some(unified)),
+ None => (config.http_proxy.as_deref(), config.https_proxy.as_deref()),
+ };
+
+ if let Some(url) = https_proxy_url {
+ let mut proxy = reqwest::Proxy::https(url)?;
+ if let Some(filter) = no_proxy.clone() {
+ proxy = proxy.no_proxy(Some(filter));
+ }
+ builder = builder.proxy(proxy);
+ }
+
+ if let Some(url) = http_proxy_url {
+ let mut proxy = reqwest::Proxy::http(url)?;
+ if let Some(filter) = no_proxy.clone() {
+ proxy = proxy.no_proxy(Some(filter));
+ }
+ builder = builder.proxy(proxy);
+ }
+
+ Ok(builder.build()?)
+}
+
+fn first_non_empty(keys: &[&str], lookup: &mut F) -> Option
+where
+ F: FnMut(&str) -> Option,
+{
+ keys.iter()
+ .find_map(|key| lookup(key).filter(|value| !value.is_empty()))
+}
+
+#[cfg(test)]
+mod tests {
+ use std::collections::HashMap;
+
+ use super::{build_http_client_with, ProxyConfig};
+
+ fn config_from_map(pairs: &[(&str, &str)]) -> ProxyConfig {
+ let map: HashMap = pairs
+ .iter()
+ .map(|(key, value)| ((*key).to_string(), (*value).to_string()))
+ .collect();
+ ProxyConfig::from_lookup(|key| map.get(key).cloned())
+ }
+
+ #[test]
+ fn proxy_config_is_empty_when_no_env_vars_are_set() {
+ // given
+ let config = config_from_map(&[]);
+
+ // when
+ let empty = config.is_empty();
+
+ // then
+ assert!(empty);
+ assert_eq!(config, ProxyConfig::default());
+ }
+
+ #[test]
+ fn proxy_config_reads_uppercase_http_https_and_no_proxy() {
+ // given
+ let pairs = [
+ ("HTTP_PROXY", "http://proxy.internal:3128"),
+ ("HTTPS_PROXY", "http://secure.internal:3129"),
+ ("NO_PROXY", "localhost,127.0.0.1,.corp"),
+ ];
+
+ // when
+ let config = config_from_map(&pairs);
+
+ // then
+ assert_eq!(
+ config.http_proxy.as_deref(),
+ Some("http://proxy.internal:3128")
+ );
+ assert_eq!(
+ config.https_proxy.as_deref(),
+ Some("http://secure.internal:3129")
+ );
+ assert_eq!(
+ config.no_proxy.as_deref(),
+ Some("localhost,127.0.0.1,.corp")
+ );
+ assert!(!config.is_empty());
+ }
+
+ #[test]
+ fn proxy_config_falls_back_to_lowercase_keys() {
+ // given
+ let pairs = [
+ ("http_proxy", "http://lower.internal:3128"),
+ ("https_proxy", "http://lower-secure.internal:3129"),
+ ("no_proxy", ".lower"),
+ ];
+
+ // when
+ let config = config_from_map(&pairs);
+
+ // then
+ assert_eq!(
+ config.http_proxy.as_deref(),
+ Some("http://lower.internal:3128")
+ );
+ assert_eq!(
+ config.https_proxy.as_deref(),
+ Some("http://lower-secure.internal:3129")
+ );
+ assert_eq!(config.no_proxy.as_deref(), Some(".lower"));
+ }
+
+ #[test]
+ fn proxy_config_prefers_uppercase_over_lowercase_when_both_set() {
+ // given
+ let pairs = [
+ ("HTTP_PROXY", "http://upper.internal:3128"),
+ ("http_proxy", "http://lower.internal:3128"),
+ ];
+
+ // when
+ let config = config_from_map(&pairs);
+
+ // then
+ assert_eq!(
+ config.http_proxy.as_deref(),
+ Some("http://upper.internal:3128")
+ );
+ }
+
+ #[test]
+ fn proxy_config_treats_empty_strings_as_unset() {
+ // given
+ let pairs = [("HTTP_PROXY", ""), ("http_proxy", "")];
+
+ // when
+ let config = config_from_map(&pairs);
+
+ // then
+ assert!(config.http_proxy.is_none());
+ }
+
+ #[test]
+ fn build_http_client_succeeds_when_no_proxy_is_configured() {
+ // given
+ let config = ProxyConfig::default();
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+ }
+
+ #[test]
+ fn build_http_client_succeeds_with_valid_http_and_https_proxies() {
+ // given
+ let config = ProxyConfig {
+ http_proxy: Some("http://proxy.internal:3128".to_string()),
+ https_proxy: Some("http://secure.internal:3129".to_string()),
+ no_proxy: Some("localhost,127.0.0.1".to_string()),
+ proxy_url: None,
+ };
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+ }
+
+ #[test]
+ fn build_http_client_returns_http_error_for_invalid_proxy_url() {
+ // given
+ let config = ProxyConfig {
+ http_proxy: None,
+ https_proxy: Some("not a url".to_string()),
+ no_proxy: None,
+ proxy_url: None,
+ };
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ let error = result.expect_err("invalid proxy URL must be reported as a build failure");
+ assert!(
+ matches!(error, crate::error::ApiError::Http(_)),
+ "expected ApiError::Http for invalid proxy URL, got: {error:?}"
+ );
+ }
+
+ #[test]
+ fn from_proxy_url_sets_unified_field_and_leaves_per_scheme_empty() {
+ // given / when
+ let config = ProxyConfig::from_proxy_url("http://unified.internal:3128");
+
+ // then
+ assert_eq!(
+ config.proxy_url.as_deref(),
+ Some("http://unified.internal:3128")
+ );
+ assert!(config.http_proxy.is_none());
+ assert!(config.https_proxy.is_none());
+ assert!(!config.is_empty());
+ }
+
+ #[test]
+ fn build_http_client_succeeds_with_unified_proxy_url() {
+ // given
+ let config = ProxyConfig {
+ proxy_url: Some("http://unified.internal:3128".to_string()),
+ no_proxy: Some("localhost".to_string()),
+ ..ProxyConfig::default()
+ };
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+ }
+
+ #[test]
+ fn proxy_url_takes_precedence_over_per_scheme_fields() {
+ // given – both per-scheme and unified are set
+ let config = ProxyConfig {
+ http_proxy: Some("http://per-scheme.internal:1111".to_string()),
+ https_proxy: Some("http://per-scheme.internal:2222".to_string()),
+ no_proxy: None,
+ proxy_url: Some("http://unified.internal:3128".to_string()),
+ };
+
+ // when – building succeeds (the unified URL is valid)
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+ }
+
+ #[test]
+ fn build_http_client_returns_error_for_invalid_unified_proxy_url() {
+ // given
+ let config = ProxyConfig::from_proxy_url("not a url");
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(
+ matches!(result, Err(crate::error::ApiError::Http(_))),
+ "invalid unified proxy URL should fail: {result:?}"
+ );
+ }
+}
diff --git a/rust/crates/api/src/lib.rs b/rust/crates/api/src/lib.rs
index cac2f539..bcf3e1b2 100644
--- a/rust/crates/api/src/lib.rs
+++ b/rust/crates/api/src/lib.rs
@@ -1,5 +1,6 @@
mod client;
mod error;
+mod http_client;
mod prompt_cache;
mod providers;
mod sse;
@@ -10,6 +11,9 @@ pub use client::{
resolve_startup_auth_source, MessageStream, OAuthTokenSet, ProviderClient,
};
pub use error::ApiError;
+pub use http_client::{
+ build_http_client, build_http_client_or_default, build_http_client_with, ProxyConfig,
+};
pub use prompt_cache::{
CacheBreakEvent, PromptCache, PromptCacheConfig, PromptCachePaths, PromptCacheRecord,
PromptCacheStats,
@@ -17,7 +21,8 @@ pub use prompt_cache::{
pub use providers::anthropic::{AnthropicClient, AnthropicClient as ApiClient, AuthSource};
pub use providers::openai_compat::{OpenAiCompatClient, OpenAiCompatConfig};
pub use providers::{
- detect_provider_kind, max_tokens_for_model, resolve_model_alias, ProviderKind,
+ detect_provider_kind, max_tokens_for_model, max_tokens_for_model_with_override,
+ resolve_model_alias, ProviderKind,
};
pub use sse::{parse_frame, SseParser};
pub use types::{
diff --git a/rust/crates/api/src/providers/anthropic.rs b/rust/crates/api/src/providers/anthropic.rs
index f8b41ac0..31801690 100644
--- a/rust/crates/api/src/providers/anthropic.rs
+++ b/rust/crates/api/src/providers/anthropic.rs
@@ -1,4 +1,5 @@
use std::collections::VecDeque;
+use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
@@ -12,18 +13,19 @@ use serde_json::{Map, Value};
use telemetry::{AnalyticsEvent, AnthropicRequestProfile, ClientIdentity, SessionTracer};
use crate::error::ApiError;
+use crate::http_client::build_http_client_or_default;
use crate::prompt_cache::{PromptCache, PromptCacheRecord, PromptCacheStats};
-use super::{Provider, ProviderFuture};
+use super::{model_token_limit, resolve_model_alias, Provider, ProviderFuture};
use crate::sse::SseParser;
use crate::types::{MessageDeltaEvent, MessageRequest, MessageResponse, StreamEvent, Usage};
pub const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
const REQUEST_ID_HEADER: &str = "request-id";
const ALT_REQUEST_ID_HEADER: &str = "x-request-id";
-const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_millis(200);
-const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(2);
-const DEFAULT_MAX_RETRIES: u32 = 2;
+const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
+const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(128);
+const DEFAULT_MAX_RETRIES: u32 = 8;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthSource {
@@ -127,7 +129,7 @@ impl AnthropicClient {
#[must_use]
pub fn new(api_key: impl Into) -> Self {
Self {
- http: reqwest::Client::new(),
+ http: build_http_client_or_default(),
auth: AuthSource::ApiKey(api_key.into()),
base_url: DEFAULT_BASE_URL.to_string(),
max_retries: DEFAULT_MAX_RETRIES,
@@ -143,7 +145,7 @@ impl AnthropicClient {
#[must_use]
pub fn from_auth(auth: AuthSource) -> Self {
Self {
- http: reqwest::Client::new(),
+ http: build_http_client_or_default(),
auth,
base_url: DEFAULT_BASE_URL.to_string(),
max_retries: DEFAULT_MAX_RETRIES,
@@ -294,12 +296,14 @@ impl AnthropicClient {
}
}
- let response = self.send_with_retry(&request).await?;
- let request_id = request_id_from_headers(response.headers());
- let mut response = response
- .json::()
- .await
- .map_err(ApiError::from)?;
+ self.preflight_message_request(&request).await?;
+
+ let http_response = self.send_with_retry(&request).await?;
+ let request_id = request_id_from_headers(http_response.headers());
+ let body = http_response.text().await.map_err(ApiError::from)?;
+ let mut response = serde_json::from_str::(&body).map_err(|error| {
+ ApiError::json_deserialize("Anthropic", &request.model, &body, error)
+ })?;
if response.request_id.is_none() {
response.request_id = request_id;
}
@@ -337,13 +341,14 @@ impl AnthropicClient {
&self,
request: &MessageRequest,
) -> Result {
+ self.preflight_message_request(request).await?;
let response = self
.send_with_retry(&request.clone().with_streaming())
.await?;
Ok(MessageStream {
request_id: request_id_from_headers(response.headers()),
response,
- parser: SseParser::new(),
+ parser: SseParser::new().with_context("Anthropic", request.model.clone()),
pending: VecDeque::new(),
done: false,
request: request.clone(),
@@ -368,10 +373,10 @@ impl AnthropicClient {
.await
.map_err(ApiError::from)?;
let response = expect_success(response).await?;
- response
- .json::()
- .await
- .map_err(ApiError::from)
+ let body = response.text().await.map_err(ApiError::from)?;
+ serde_json::from_str::(&body).map_err(|error| {
+ ApiError::json_deserialize("Anthropic OAuth (exchange)", "n/a", &body, error)
+ })
}
pub async fn refresh_oauth_token(
@@ -388,10 +393,10 @@ impl AnthropicClient {
.await
.map_err(ApiError::from)?;
let response = expect_success(response).await?;
- response
- .json::()
- .await
- .map_err(ApiError::from)
+ let body = response.text().await.map_err(ApiError::from)?;
+ serde_json::from_str::(&body).map_err(|error| {
+ ApiError::json_deserialize("Anthropic OAuth (refresh)", "n/a", &body, error)
+ })
}
async fn send_with_retry(
@@ -449,7 +454,7 @@ impl AnthropicClient {
break;
}
- tokio::time::sleep(self.backoff_for_attempt(attempts)?).await;
+ tokio::time::sleep(self.jittered_backoff_for_attempt(attempts)?).await;
}
Err(ApiError::RetriesExhausted {
@@ -463,18 +468,74 @@ impl AnthropicClient {
request: &MessageRequest,
) -> Result {
let request_url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
+ let mut request_body = self.request_profile.render_json_body(request)?;
+ strip_unsupported_beta_body_fields(&mut request_body);
+ let request_builder = self.build_request(&request_url).json(&request_body);
+ request_builder.send().await.map_err(ApiError::from)
+ }
+
+ fn build_request(&self, request_url: &str) -> reqwest::RequestBuilder {
let request_builder = self
.http
- .post(&request_url)
+ .post(request_url)
.header("content-type", "application/json");
let mut request_builder = self.auth.apply(request_builder);
for (header_name, header_value) in self.request_profile.header_pairs() {
request_builder = request_builder.header(header_name, header_value);
}
+ request_builder
+ }
- let request_body = self.request_profile.render_json_body(request)?;
- request_builder = request_builder.json(&request_body);
- request_builder.send().await.map_err(ApiError::from)
+ async fn preflight_message_request(&self, request: &MessageRequest) -> Result<(), ApiError> {
+ let Some(limit) = model_token_limit(&request.model) else {
+ return Ok(());
+ };
+
+ let counted_input_tokens = match self.count_tokens(request).await {
+ Ok(count) => count,
+ Err(_) => return Ok(()),
+ };
+ let estimated_total_tokens = counted_input_tokens.saturating_add(request.max_tokens);
+ if estimated_total_tokens > limit.context_window_tokens {
+ return Err(ApiError::ContextWindowExceeded {
+ model: resolve_model_alias(&request.model),
+ estimated_input_tokens: counted_input_tokens,
+ requested_output_tokens: request.max_tokens,
+ estimated_total_tokens,
+ context_window_tokens: limit.context_window_tokens,
+ });
+ }
+
+ Ok(())
+ }
+
+ async fn count_tokens(&self, request: &MessageRequest) -> Result {
+ #[derive(serde::Deserialize)]
+ struct CountTokensResponse {
+ input_tokens: u32,
+ }
+
+ let request_url = format!("{}/v1/messages/count_tokens", self.base_url.trim_end_matches('/'));
+ let mut request_body = self.request_profile.render_json_body(request)?;
+ strip_unsupported_beta_body_fields(&mut request_body);
+ let response = self
+ .build_request(&request_url)
+ .json(&request_body)
+ .send()
+ .await
+ .map_err(ApiError::from)?;
+
+ let response = expect_success(response).await?;
+ let body = response.text().await.map_err(ApiError::from)?;
+ let parsed = serde_json::from_str::(&body).map_err(|error| {
+ ApiError::json_deserialize(
+ "Anthropic count_tokens",
+ &request.model,
+ &body,
+ error,
+ )
+ })?;
+ Ok(parsed.input_tokens)
}
fn record_request_failure(&self, attempt: u32, error: &ApiError) {
@@ -509,6 +570,40 @@ impl AnthropicClient {
.checked_mul(multiplier)
.map_or(self.max_backoff, |delay| delay.min(self.max_backoff)))
}
+
+ fn jittered_backoff_for_attempt(&self, attempt: u32) -> Result {
+ let base = self.backoff_for_attempt(attempt)?;
+ Ok(base + jitter_for_base(base))
+ }
+}
+
+/// Process-wide counter that guarantees distinct jitter samples even when
+/// the system clock resolution is coarser than consecutive retry sleeps.
+static JITTER_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// Returns a random additive jitter in `[0, base]` to decorrelate retries
+/// from multiple concurrent clients. Entropy is drawn from the nanosecond
+/// wall clock mixed with a monotonic counter and run through a splitmix64
+/// finalizer; adequate for retry jitter (no cryptographic requirement).
+fn jitter_for_base(base: Duration) -> Duration {
+ let base_nanos = u64::try_from(base.as_nanos()).unwrap_or(u64::MAX);
+ if base_nanos == 0 {
+ return Duration::ZERO;
+ }
+ let raw_nanos = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map(|elapsed| u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX))
+ .unwrap_or(0);
+ let tick = JITTER_COUNTER.fetch_add(1, Ordering::Relaxed);
+ // splitmix64 finalizer — mixes the low bits so large bases still see
+ // jitter across their full range instead of being clamped to subsec nanos.
+ let mut mixed = raw_nanos.wrapping_add(tick).wrapping_add(0x9E37_79B9_7F4A_7C15);
+ mixed = (mixed ^ (mixed >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ mixed = (mixed ^ (mixed >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ mixed ^= mixed >> 31;
+ // Inclusive upper bound: jitter may equal `base`, matching "up to base".
+ let jitter_nanos = mixed % base_nanos.saturating_add(1);
+ Duration::from_nanos(jitter_nanos)
}
impl AuthSource {
@@ -673,7 +768,7 @@ fn now_unix_timestamp() -> u64 {
fn read_env_non_empty(key: &str) -> Result, ApiError> {
match std::env::var(key) {
Ok(value) if !value.is_empty() => Ok(Some(value)),
- Ok(_) | Err(std::env::VarError::NotPresent) => Ok(None),
+ Ok(_) | Err(std::env::VarError::NotPresent) => Ok(super::dotenv_value(key)),
Err(error) => Err(ApiError::from(error)),
}
}
@@ -805,6 +900,7 @@ async fn expect_success(response: reqwest::Response) -> Result(&body).ok();
let retryable = is_retryable_status(status);
@@ -817,6 +913,7 @@ async fn expect_success(response: reqwest::Response) -> Result bool {
matches!(status.as_u16(), 408 | 409 | 429 | 500 | 502 | 503 | 504)
}
+/// Remove beta-only body fields that the standard `/v1/messages` and
+/// `/v1/messages/count_tokens` endpoints reject as `Extra inputs are not
+/// permitted`. The `betas` opt-in is communicated via the `anthropic-beta`
+/// HTTP header on these endpoints, never as a JSON body field.
+fn strip_unsupported_beta_body_fields(body: &mut Value) {
+ if let Some(object) = body.as_object_mut() {
+ object.remove("betas");
+ }
+}
+
#[derive(Debug, Deserialize)]
struct AnthropicErrorEnvelope {
error: AnthropicErrorBody,
@@ -1178,6 +1285,58 @@ mod tests {
);
}
+ #[test]
+ fn jittered_backoff_stays_within_additive_bounds_and_varies() {
+ let client = AnthropicClient::new("test-key").with_retry_policy(
+ 8,
+ Duration::from_secs(1),
+ Duration::from_secs(128),
+ );
+ let mut samples = Vec::with_capacity(64);
+ for _ in 0..64 {
+ let base = client.backoff_for_attempt(3).expect("base attempt 3");
+ let jittered = client
+ .jittered_backoff_for_attempt(3)
+ .expect("jittered attempt 3");
+ assert!(
+ jittered >= base,
+ "jittered delay {jittered:?} must be at least the base {base:?}"
+ );
+ assert!(
+ jittered <= base * 2,
+ "jittered delay {jittered:?} must not exceed base*2 {:?}",
+ base * 2
+ );
+ samples.push(jittered);
+ }
+ let distinct: std::collections::HashSet<_> = samples.iter().collect();
+ assert!(
+ distinct.len() > 1,
+ "jitter should produce varied delays across samples, got {samples:?}"
+ );
+ }
+
+ #[test]
+ fn default_retry_policy_matches_exponential_schedule() {
+ let client = AnthropicClient::new("test-key");
+ assert_eq!(
+ client.backoff_for_attempt(1).expect("attempt 1"),
+ Duration::from_secs(1)
+ );
+ assert_eq!(
+ client.backoff_for_attempt(2).expect("attempt 2"),
+ Duration::from_secs(2)
+ );
+ assert_eq!(
+ client.backoff_for_attempt(3).expect("attempt 3"),
+ Duration::from_secs(4)
+ );
+ assert_eq!(
+ client.backoff_for_attempt(8).expect("attempt 8"),
+ Duration::from_secs(128)
+ );
+ }
+
#[test]
fn retryable_statuses_are_detected() {
assert!(super::is_retryable_status(
@@ -1242,4 +1401,73 @@ mod tests {
Some("Bearer proxy-token")
);
}
+
+ #[test]
+ fn strip_unsupported_beta_body_fields_removes_betas_array() {
+ let mut body = serde_json::json!({
+ "model": "claude-sonnet-4-6",
+ "max_tokens": 1024,
+ "betas": ["claude-code-20250219", "prompt-caching-scope-2026-01-05"],
+ "metadata": {"source": "test"},
+ });
+
+ super::strip_unsupported_beta_body_fields(&mut body);
+
+ assert!(
+ body.get("betas").is_none(),
+ "betas body field must be stripped before sending to /v1/messages"
+ );
+ assert_eq!(
+ body.get("model").and_then(serde_json::Value::as_str),
+ Some("claude-sonnet-4-6")
+ );
+ assert_eq!(body["max_tokens"], serde_json::json!(1024));
+ assert_eq!(body["metadata"]["source"], serde_json::json!("test"));
+ }
+
+ #[test]
+ fn strip_unsupported_beta_body_fields_is_a_noop_when_betas_absent() {
+ let mut body = serde_json::json!({
+ "model": "claude-sonnet-4-6",
+ "max_tokens": 1024,
+ });
+ let original = body.clone();
+
+ super::strip_unsupported_beta_body_fields(&mut body);
+
+ assert_eq!(body, original);
+ }
+
+ #[test]
+ fn rendered_request_body_strips_betas_for_standard_messages_endpoint() {
+ let client = AnthropicClient::new("test-key").with_beta("tools-2026-04-01");
+ let request = MessageRequest {
+ model: "claude-sonnet-4-6".to_string(),
+ max_tokens: 64,
+ messages: vec![],
+ system: None,
+ tools: None,
+ tool_choice: None,
+ stream: false,
+ };
+
+ let mut rendered = client
+ .request_profile()
+ .render_json_body(&request)
+ .expect("body should render");
+ assert!(
+ rendered.get("betas").is_some(),
+ "render_json_body still emits betas; the strip helper guards the wire format",
+ );
+ super::strip_unsupported_beta_body_fields(&mut rendered);
+
+ assert!(
+ rendered.get("betas").is_none(),
+ "betas must not appear in /v1/messages request bodies"
+ );
+ assert_eq!(
+ rendered.get("model").and_then(serde_json::Value::as_str),
+ Some("claude-sonnet-4-6")
+ );
+ }
}
diff --git a/rust/crates/api/src/providers/mod.rs b/rust/crates/api/src/providers/mod.rs
index d28febd3..36c01fd5 100644
--- a/rust/crates/api/src/providers/mod.rs
+++ b/rust/crates/api/src/providers/mod.rs
@@ -1,14 +1,19 @@
+#![allow(clippy::cast_possible_truncation)]
use std::future::Future;
use std::pin::Pin;
+use serde::Serialize;
+
use crate::error::ApiError;
use crate::types::{MessageRequest, MessageResponse};
pub mod anthropic;
pub mod openai_compat;
+#[allow(dead_code)]
pub type ProviderFuture<'a, T> = Pin> + Send + 'a>>;
+#[allow(dead_code)]
pub trait Provider {
type Stream;
@@ -38,6 +43,12 @@ pub struct ProviderMetadata {
pub default_base_url: &'static str,
}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModelTokenLimit {
+ pub max_output_tokens: u32,
+ pub context_window_tokens: u32,
+}
+
const MODEL_REGISTRY: &[(&str, ProviderMetadata)] = &[
(
"opus",
@@ -180,17 +191,150 @@ pub fn detect_provider_kind(model: &str) -> ProviderKind {
#[must_use]
pub fn max_tokens_for_model(model: &str) -> u32 {
+ model_token_limit(model).map_or_else(
+ || {
+ let canonical = resolve_model_alias(model);
+ if canonical.contains("opus") {
+ 32_000
+ } else {
+ 64_000
+ }
+ },
+ |limit| limit.max_output_tokens,
+ )
+}
+
+/// Returns the effective max output tokens for a model, preferring a plugin
+/// override when present. Falls back to [`max_tokens_for_model`] when the
+/// override is `None`.
+#[must_use]
+pub fn max_tokens_for_model_with_override(model: &str, plugin_override: Option) -> u32 {
+ plugin_override.unwrap_or_else(|| max_tokens_for_model(model))
+}
+
+#[must_use]
+pub fn model_token_limit(model: &str) -> Option {
let canonical = resolve_model_alias(model);
- if canonical.contains("opus") {
- 32_000
- } else {
- 64_000
+ match canonical.as_str() {
+ "claude-opus-4-6" => Some(ModelTokenLimit {
+ max_output_tokens: 32_000,
+ context_window_tokens: 200_000,
+ }),
+ "claude-sonnet-4-6" | "claude-haiku-4-5-20251213" => Some(ModelTokenLimit {
+ max_output_tokens: 64_000,
+ context_window_tokens: 200_000,
+ }),
+ "grok-3" | "grok-3-mini" => Some(ModelTokenLimit {
+ max_output_tokens: 64_000,
+ context_window_tokens: 131_072,
+ }),
+ _ => None,
}
}
+pub fn preflight_message_request(request: &MessageRequest) -> Result<(), ApiError> {
+ let Some(limit) = model_token_limit(&request.model) else {
+ return Ok(());
+ };
+
+ let estimated_input_tokens = estimate_message_request_input_tokens(request);
+ let estimated_total_tokens = estimated_input_tokens.saturating_add(request.max_tokens);
+ if estimated_total_tokens > limit.context_window_tokens {
+ return Err(ApiError::ContextWindowExceeded {
+ model: resolve_model_alias(&request.model),
+ estimated_input_tokens,
+ requested_output_tokens: request.max_tokens,
+ estimated_total_tokens,
+ context_window_tokens: limit.context_window_tokens,
+ });
+ }
+
+ Ok(())
+}
+
+fn estimate_message_request_input_tokens(request: &MessageRequest) -> u32 {
+ let mut estimate = estimate_serialized_tokens(&request.messages);
+ estimate = estimate.saturating_add(estimate_serialized_tokens(&request.system));
+ estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tools));
+ estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tool_choice));
+ estimate
+}
+
+fn estimate_serialized_tokens(value: &T) -> u32 {
+ serde_json::to_vec(value)
+ .ok()
+ .map_or(0, |bytes| (bytes.len() / 4 + 1) as u32)
+}
+
+/// Parse a `.env` file body into key/value pairs using a minimal `KEY=VALUE`
+/// grammar. Lines that are blank, start with `#`, or do not contain `=` are
+/// ignored. Surrounding double or single quotes are stripped from the value.
+/// An optional leading `export ` prefix on the key is also stripped so files
+/// shared with shell `source` workflows still parse cleanly.
+pub(crate) fn parse_dotenv(content: &str) -> std::collections::HashMap {
+ let mut values = std::collections::HashMap::new();
+ for raw_line in content.lines() {
+ let line = raw_line.trim();
+ if line.is_empty() || line.starts_with('#') {
+ continue;
+ }
+ let Some((raw_key, raw_value)) = line.split_once('=') else {
+ continue;
+ };
+ let trimmed_key = raw_key.trim();
+ let key = trimmed_key
+ .strip_prefix("export ")
+ .map_or(trimmed_key, str::trim)
+ .to_string();
+ if key.is_empty() {
+ continue;
+ }
+ let trimmed_value = raw_value.trim();
+ let unquoted = if (trimmed_value.starts_with('"') && trimmed_value.ends_with('"')
+ || trimmed_value.starts_with('\'') && trimmed_value.ends_with('\''))
+ && trimmed_value.len() >= 2
+ {
+ &trimmed_value[1..trimmed_value.len() - 1]
+ } else {
+ trimmed_value
+ };
+ values.insert(key, unquoted.to_string());
+ }
+ values
+}
+
+/// Load and parse a `.env` file from the given path. Missing files yield
+/// `None` instead of an error so callers can use this as a soft fallback.
+pub(crate) fn load_dotenv_file(
+ path: &std::path::Path,
+) -> Option> {
+ let content = std::fs::read_to_string(path).ok()?;
+ Some(parse_dotenv(&content))
+}
+
+/// Look up `key` in a `.env` file located in the current working directory.
+/// Returns `None` when the file is missing, the key is absent, or the value
+/// is empty.
+pub(crate) fn dotenv_value(key: &str) -> Option {
+ let cwd = std::env::current_dir().ok()?;
+ let values = load_dotenv_file(&cwd.join(".env"))?;
+ values.get(key).filter(|value| !value.is_empty()).cloned()
+}
+
#[cfg(test)]
mod tests {
- use super::{detect_provider_kind, max_tokens_for_model, resolve_model_alias, ProviderKind};
+ use serde_json::json;
+
+ use crate::error::ApiError;
+ use crate::types::{
+ InputContentBlock, InputMessage, MessageRequest, ToolChoice, ToolDefinition,
+ };
+
+ use super::{
+ detect_provider_kind, load_dotenv_file, max_tokens_for_model,
+ max_tokens_for_model_with_override, model_token_limit, parse_dotenv,
+ preflight_message_request, resolve_model_alias, ProviderKind,
+ };
#[test]
fn resolves_grok_aliases() {
@@ -213,4 +357,217 @@ mod tests {
assert_eq!(max_tokens_for_model("opus"), 32_000);
assert_eq!(max_tokens_for_model("grok-3"), 64_000);
}
+
+ #[test]
+ fn plugin_config_max_output_tokens_overrides_model_default() {
+ // given
+ let nanos = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .expect("time should be after epoch")
+ .as_nanos();
+ let root = std::env::temp_dir().join(format!("api-plugin-max-tokens-{nanos}"));
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ std::fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
+ std::fs::create_dir_all(&home).expect("home config dir");
+ std::fs::write(
+ home.join("settings.json"),
+ r#"{
+ "plugins": {
+ "maxOutputTokens": 12345
+ }
+ }"#,
+ )
+ .expect("write plugin settings");
+
+ // when
+ let loaded = runtime::ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect("config should load");
+ let plugin_override = loaded.plugins().max_output_tokens();
+ let effective = max_tokens_for_model_with_override("claude-opus-4-6", plugin_override);
+
+ // then
+ assert_eq!(plugin_override, Some(12345));
+ assert_eq!(effective, 12345);
+ assert_ne!(effective, max_tokens_for_model("claude-opus-4-6"));
+
+ std::fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
+ #[test]
+ fn max_tokens_for_model_with_override_falls_back_when_plugin_unset() {
+ // given
+ let plugin_override: Option = None;
+
+ // when
+ let effective = max_tokens_for_model_with_override("claude-opus-4-6", plugin_override);
+
+ // then
+ assert_eq!(effective, max_tokens_for_model("claude-opus-4-6"));
+ assert_eq!(effective, 32_000);
+ }
+
+ #[test]
+ fn returns_context_window_metadata_for_supported_models() {
+ assert_eq!(
+ model_token_limit("claude-sonnet-4-6")
+ .expect("claude-sonnet-4-6 should be registered")
+ .context_window_tokens,
+ 200_000
+ );
+ assert_eq!(
+ model_token_limit("grok-mini")
+ .expect("grok-mini should resolve to a registered model")
+ .context_window_tokens,
+ 131_072
+ );
+ }
+
+ #[test]
+ fn preflight_blocks_requests_that_exceed_the_model_context_window() {
+ let request = MessageRequest {
+ model: "claude-sonnet-4-6".to_string(),
+ max_tokens: 64_000,
+ messages: vec![InputMessage {
+ role: "user".to_string(),
+ content: vec![InputContentBlock::Text {
+ text: "x".repeat(600_000),
+ }],
+ }],
+ system: Some("Keep the answer short.".to_string()),
+ tools: Some(vec![ToolDefinition {
+ name: "weather".to_string(),
+ description: Some("Fetches weather".to_string()),
+ input_schema: json!({
+ "type": "object",
+ "properties": { "city": { "type": "string" } },
+ }),
+ }]),
+ tool_choice: Some(ToolChoice::Auto),
+ stream: true,
+ };
+
+ let error = preflight_message_request(&request)
+ .expect_err("oversized request should be rejected before the provider call");
+
+ match error {
+ ApiError::ContextWindowExceeded {
+ model,
+ estimated_input_tokens,
+ requested_output_tokens,
+ estimated_total_tokens,
+ context_window_tokens,
+ } => {
+ assert_eq!(model, "claude-sonnet-4-6");
+ assert!(estimated_input_tokens > 136_000);
+ assert_eq!(requested_output_tokens, 64_000);
+ assert!(estimated_total_tokens > context_window_tokens);
+ assert_eq!(context_window_tokens, 200_000);
+ }
+ other => panic!("expected context-window preflight failure, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn preflight_skips_unknown_models() {
+ let request = MessageRequest {
+ model: "unknown-model".to_string(),
+ max_tokens: 64_000,
+ messages: vec![InputMessage {
+ role: "user".to_string(),
+ content: vec![InputContentBlock::Text {
+ text: "x".repeat(600_000),
+ }],
+ }],
+ system: None,
+ tools: None,
+ tool_choice: None,
+ stream: false,
+ };
+
+ preflight_message_request(&request)
+ .expect("models without context metadata should skip the guarded preflight");
+ }
+
+ #[test]
+ fn parse_dotenv_extracts_keys_handles_comments_quotes_and_export_prefix() {
+ // given
+ let body = "\
+# this is a comment
+
+ANTHROPIC_API_KEY=plain-value
+XAI_API_KEY=\"quoted-value\"
+OPENAI_API_KEY='single-quoted'
+export GROK_API_KEY=exported-value
+ PADDED_KEY = padded-value
+EMPTY_VALUE=
+NO_EQUALS_LINE
+";
+
+ // when
+ let values = parse_dotenv(body);
+
+ // then
+ assert_eq!(
+ values.get("ANTHROPIC_API_KEY").map(String::as_str),
+ Some("plain-value")
+ );
+ assert_eq!(
+ values.get("XAI_API_KEY").map(String::as_str),
+ Some("quoted-value")
+ );
+ assert_eq!(
+ values.get("OPENAI_API_KEY").map(String::as_str),
+ Some("single-quoted")
+ );
+ assert_eq!(
+ values.get("GROK_API_KEY").map(String::as_str),
+ Some("exported-value")
+ );
+ assert_eq!(
+ values.get("PADDED_KEY").map(String::as_str),
+ Some("padded-value")
+ );
+ assert_eq!(values.get("EMPTY_VALUE").map(String::as_str), Some(""));
+ assert!(!values.contains_key("NO_EQUALS_LINE"));
+ assert!(!values.contains_key("# this is a comment"));
+ }
+
+ #[test]
+ fn load_dotenv_file_reads_keys_from_disk_and_returns_none_when_missing() {
+ // given
+ let temp_root = std::env::temp_dir().join(format!(
+ "api-dotenv-test-{}-{}",
+ std::process::id(),
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_or(0, |duration| duration.as_nanos())
+ ));
+ std::fs::create_dir_all(&temp_root).expect("create temp dir");
+ let env_path = temp_root.join(".env");
+ std::fs::write(
+ &env_path,
+ "ANTHROPIC_API_KEY=secret-from-file\n# comment\nXAI_API_KEY=\"xai-secret\"\n",
+ )
+ .expect("write .env");
+ let missing_path = temp_root.join("does-not-exist.env");
+
+ // when
+ let loaded = load_dotenv_file(&env_path).expect("file should load");
+ let missing = load_dotenv_file(&missing_path);
+
+ // then
+ assert_eq!(
+ loaded.get("ANTHROPIC_API_KEY").map(String::as_str),
+ Some("secret-from-file")
+ );
+ assert_eq!(
+ loaded.get("XAI_API_KEY").map(String::as_str),
+ Some("xai-secret")
+ );
+ assert!(missing.is_none());
+
+ let _ = std::fs::remove_dir_all(&temp_root);
+ }
}
diff --git a/rust/crates/api/src/providers/openai_compat.rs b/rust/crates/api/src/providers/openai_compat.rs
index 48eec301..57d9ef22 100644
--- a/rust/crates/api/src/providers/openai_compat.rs
+++ b/rust/crates/api/src/providers/openai_compat.rs
@@ -1,10 +1,12 @@
use std::collections::{BTreeMap, VecDeque};
-use std::time::Duration;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
use serde::Deserialize;
use serde_json::{json, Value};
use crate::error::ApiError;
+use crate::http_client::build_http_client_or_default;
use crate::types::{
ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
InputContentBlock, InputMessage, MessageDelta, MessageDeltaEvent, MessageRequest,
@@ -12,15 +14,15 @@ use crate::types::{
ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
};
-use super::{Provider, ProviderFuture};
+use super::{preflight_message_request, Provider, ProviderFuture};
pub const DEFAULT_XAI_BASE_URL: &str = "https://api.x.ai/v1";
pub const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
const REQUEST_ID_HEADER: &str = "request-id";
const ALT_REQUEST_ID_HEADER: &str = "x-request-id";
-const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_millis(200);
-const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(2);
-const DEFAULT_MAX_RETRIES: u32 = 2;
+const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
+const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(128);
+const DEFAULT_MAX_RETRIES: u32 = 8;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpenAiCompatConfig {
@@ -81,7 +83,7 @@ impl OpenAiCompatClient {
#[must_use]
pub fn new(api_key: impl Into, config: OpenAiCompatConfig) -> Self {
Self {
- http: reqwest::Client::new(),
+ http: build_http_client_or_default(),
api_key: api_key.into(),
config,
base_url: read_base_url(config),
@@ -128,9 +130,18 @@ impl OpenAiCompatClient {
stream: false,
..request.clone()
};
+ preflight_message_request(&request)?;
let response = self.send_with_retry(&request).await?;
let request_id = request_id_from_headers(response.headers());
- let payload = response.json::().await?;
+ let body = response.text().await.map_err(ApiError::from)?;
+ let payload = serde_json::from_str::(&body).map_err(|error| {
+ ApiError::json_deserialize(
+ self.config.provider_name,
+ &request.model,
+ &body,
+ error,
+ )
+ })?;
let mut normalized = normalize_response(&request.model, payload)?;
if normalized.request_id.is_none() {
normalized.request_id = request_id;
@@ -142,13 +153,17 @@ impl OpenAiCompatClient {
&self,
request: &MessageRequest,
) -> Result {
+ preflight_message_request(request)?;
let response = self
.send_with_retry(&request.clone().with_streaming())
.await?;
Ok(MessageStream {
request_id: request_id_from_headers(response.headers()),
response,
- parser: OpenAiSseParser::new(),
+ parser: OpenAiSseParser::with_context(
+ self.config.provider_name,
+ request.model.clone(),
+ ),
pending: VecDeque::new(),
done: false,
state: StreamState::new(request.model.clone()),
@@ -177,7 +192,7 @@ impl OpenAiCompatClient {
break retryable_error;
}
- tokio::time::sleep(self.backoff_for_attempt(attempts)?).await;
+ tokio::time::sleep(self.jittered_backoff_for_attempt(attempts)?).await;
};
Err(ApiError::RetriesExhausted {
@@ -213,6 +228,37 @@ impl OpenAiCompatClient {
.checked_mul(multiplier)
.map_or(self.max_backoff, |delay| delay.min(self.max_backoff)))
}
+
+ fn jittered_backoff_for_attempt(&self, attempt: u32) -> Result {
+ let base = self.backoff_for_attempt(attempt)?;
+ Ok(base + jitter_for_base(base))
+ }
+}
+
+/// Process-wide counter that guarantees distinct jitter samples even when
+/// the system clock resolution is coarser than consecutive retry sleeps.
+static JITTER_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// Returns a random additive jitter in `[0, base]` to decorrelate retries
+/// from multiple concurrent clients. Entropy is drawn from the nanosecond
+/// wall clock mixed with a monotonic counter and run through a splitmix64
+/// finalizer; adequate for retry jitter (no cryptographic requirement).
+fn jitter_for_base(base: Duration) -> Duration {
+ let base_nanos = u64::try_from(base.as_nanos()).unwrap_or(u64::MAX);
+ if base_nanos == 0 {
+ return Duration::ZERO;
+ }
+ let raw_nanos = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .map(|elapsed| u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX))
+ .unwrap_or(0);
+ let tick = JITTER_COUNTER.fetch_add(1, Ordering::Relaxed);
+ let mut mixed = raw_nanos.wrapping_add(tick).wrapping_add(0x9E37_79B9_7F4A_7C15);
+ mixed = (mixed ^ (mixed >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ mixed = (mixed ^ (mixed >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ mixed ^= mixed >> 31;
+ let jitter_nanos = mixed % base_nanos.saturating_add(1);
+ Duration::from_nanos(jitter_nanos)
}
impl Provider for OpenAiCompatClient {
@@ -280,11 +326,17 @@ impl MessageStream {
#[derive(Debug, Default)]
struct OpenAiSseParser {
buffer: Vec,
+ provider: String,
+ model: String,
}
impl OpenAiSseParser {
- fn new() -> Self {
- Self::default()
+ fn with_context(provider: impl Into, model: impl Into) -> Self {
+ Self {
+ buffer: Vec::new(),
+ provider: provider.into(),
+ model: model.into(),
+ }
}
fn push(&mut self, chunk: &[u8]) -> Result, ApiError> {
@@ -292,7 +344,7 @@ impl OpenAiSseParser {
let mut events = Vec::new();
while let Some(frame) = next_sse_frame(&mut self.buffer) {
- if let Some(event) = parse_sse_frame(&frame)? {
+ if let Some(event) = parse_sse_frame(&frame, &self.provider, &self.model)? {
events.push(event);
}
}
@@ -833,7 +885,11 @@ fn next_sse_frame(buffer: &mut Vec) -> Option {
Some(String::from_utf8_lossy(&frame[..frame_len]).into_owned())
}
-fn parse_sse_frame(frame: &str) -> Result, ApiError> {
+fn parse_sse_frame(
+ frame: &str,
+ provider: &str,
+ model: &str,
+) -> Result, ApiError> {
let trimmed = frame.trim();
if trimmed.is_empty() {
return Ok(None);
@@ -855,15 +911,15 @@ fn parse_sse_frame(frame: &str) -> Result, ApiError>
if payload == "[DONE]" {
return Ok(None);
}
- serde_json::from_str(&payload)
+ serde_json::from_str::(&payload)
.map(Some)
- .map_err(ApiError::from)
+ .map_err(|error| ApiError::json_deserialize(provider, model, &payload, error))
}
fn read_env_non_empty(key: &str) -> Result, ApiError> {
match std::env::var(key) {
Ok(value) if !value.is_empty() => Ok(Some(value)),
- Ok(_) | Err(std::env::VarError::NotPresent) => Ok(None),
+ Ok(_) | Err(std::env::VarError::NotPresent) => Ok(super::dotenv_value(key)),
Err(error) => Err(ApiError::from(error)),
}
}
@@ -904,6 +960,7 @@ async fn expect_success(response: reqwest::Response) -> Result(&body).ok();
let retryable = is_retryable_status(status);
@@ -916,6 +973,7 @@ async fn expect_success(response: reqwest::Response) -> Result,
+ provider: Option,
+ model: Option,
}
impl SseParser {
@@ -12,12 +14,23 @@ impl SseParser {
Self::default()
}
+ /// Attach the provider name and model to this parser so that JSON
+ /// deserialization failures within streamed frames carry enough context
+ /// for callers to understand which upstream produced the unparseable
+ /// payload.
+ #[must_use]
+ pub fn with_context(mut self, provider: impl Into, model: impl Into) -> Self {
+ self.provider = Some(provider.into());
+ self.model = Some(model.into());
+ self
+ }
+
pub fn push(&mut self, chunk: &[u8]) -> Result, ApiError> {
self.buffer.extend_from_slice(chunk);
let mut events = Vec::new();
while let Some(frame) = self.next_frame() {
- if let Some(event) = parse_frame(&frame)? {
+ if let Some(event) = self.parse_frame_with_context(&frame)? {
events.push(event);
}
}
@@ -31,12 +44,18 @@ impl SseParser {
}
let trailing = std::mem::take(&mut self.buffer);
- match parse_frame(&String::from_utf8_lossy(&trailing))? {
+ match self.parse_frame_with_context(&String::from_utf8_lossy(&trailing))? {
Some(event) => Ok(vec![event]),
None => Ok(Vec::new()),
}
}
+ fn parse_frame_with_context(&self, frame: &str) -> Result, ApiError> {
+ let provider = self.provider.as_deref().unwrap_or("unknown");
+ let model = self.model.as_deref().unwrap_or("unknown");
+ parse_frame_with_provider(frame, provider, model)
+ }
+
fn next_frame(&mut self) -> Option {
let separator = self
.buffer
@@ -61,6 +80,14 @@ impl SseParser {
}
pub fn parse_frame(frame: &str) -> Result, ApiError> {
+ parse_frame_with_provider(frame, "unknown", "unknown")
+}
+
+pub(crate) fn parse_frame_with_provider(
+ frame: &str,
+ provider: &str,
+ model: &str,
+) -> Result, ApiError> {
let trimmed = frame.trim();
if trimmed.is_empty() {
return Ok(None);
@@ -97,7 +124,7 @@ pub fn parse_frame(frame: &str) -> Result, ApiError> {
serde_json::from_str::(&payload)
.map(Some)
- .map_err(ApiError::from)
+ .map_err(|error| ApiError::json_deserialize(provider, model, &payload, error))
}
#[cfg(test)]
@@ -276,4 +303,28 @@ mod tests {
))
);
}
+
+ #[test]
+ fn given_message_delta_frame_with_empty_usage_when_parsed_then_usage_defaults_to_zero() {
+ // given
+ let frame = concat!(
+ "event: message_delta\n",
+ "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null},\"usage\":{}}\n\n"
+ );
+
+ // when
+ let event = parse_frame(frame).expect("frame should parse");
+
+ // then
+ assert_eq!(
+ event,
+ Some(StreamEvent::MessageDelta(crate::types::MessageDeltaEvent {
+ delta: MessageDelta {
+ stop_reason: Some("end_turn".to_string()),
+ stop_sequence: None,
+ },
+ usage: Usage::default(),
+ }))
+ );
+ }
}
diff --git a/rust/crates/api/src/types.rs b/rust/crates/api/src/types.rs
index ec70d404..f2e33f61 100644
--- a/rust/crates/api/src/types.rs
+++ b/rust/crates/api/src/types.rs
@@ -113,6 +113,7 @@ pub struct MessageResponse {
pub stop_reason: Option,
#[serde(default)]
pub stop_sequence: Option,
+ #[serde(default)]
pub usage: Usage,
#[serde(default)]
pub request_id: Option,
@@ -147,13 +148,15 @@ pub enum OutputContentBlock {
},
}
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Usage {
+ #[serde(default)]
pub input_tokens: u32,
#[serde(default)]
pub cache_creation_input_tokens: u32,
#[serde(default)]
pub cache_read_input_tokens: u32,
+ #[serde(default)]
pub output_tokens: u32,
}
@@ -194,6 +197,7 @@ pub struct MessageStartEvent {
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MessageDeltaEvent {
pub delta: MessageDelta,
+ #[serde(default)]
pub usage: Usage,
}
diff --git a/rust/crates/api/tests/client_integration.rs b/rust/crates/api/tests/client_integration.rs
index 01addefe..9d45cc78 100644
--- a/rust/crates/api/tests/client_integration.rs
+++ b/rust/crates/api/tests/client_integration.rs
@@ -97,9 +97,44 @@ async fn send_message_posts_json_and_parses_response() {
assert!(body.get("stream").is_none());
assert_eq!(body["tools"][0]["name"], json!("get_weather"));
assert_eq!(body["tool_choice"]["type"], json!("auto"));
- assert_eq!(
- body["betas"],
- json!(["claude-code-20250219", "prompt-caching-scope-2026-01-05"])
+ assert!(
+ body.get("betas").is_none(),
+ "betas must travel via the anthropic-beta header, not the request body"
+ );
+}
+
+#[tokio::test]
+async fn send_message_blocks_oversized_requests_before_the_http_call() {
+ let state = Arc::new(Mutex::new(Vec::::new()));
+ let server = spawn_server(
+ state.clone(),
+ vec![http_response("200 OK", "application/json", "{}")],
+ )
+ .await;
+
+ let client = AnthropicClient::new("test-key").with_base_url(server.base_url());
+ let error = client
+ .send_message(&MessageRequest {
+ model: "claude-sonnet-4-6".to_string(),
+ max_tokens: 64_000,
+ messages: vec![InputMessage {
+ role: "user".to_string(),
+ content: vec![InputContentBlock::Text {
+ text: "x".repeat(600_000),
+ }],
+ }],
+ system: Some("Keep the answer short.".to_string()),
+ tools: None,
+ tool_choice: None,
+ stream: false,
+ })
+ .await
+ .expect_err("oversized request should fail local context-window preflight");
+
+ assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
+ assert!(
+ state.lock().await.is_empty(),
+ "preflight failure should avoid any upstream HTTP request"
);
}
@@ -156,13 +191,9 @@ async fn send_message_applies_request_profile_and_records_telemetry() {
let body: serde_json::Value =
serde_json::from_str(&request.body).expect("request body should be json");
assert_eq!(body["metadata"]["source"], json!("clawd-code"));
- assert_eq!(
- body["betas"],
- json!([
- "claude-code-20250219",
- "prompt-caching-scope-2026-01-05",
- "tools-2026-04-01"
- ])
+ assert!(
+ body.get("betas").is_none(),
+ "betas must travel via the anthropic-beta header, not the request body"
);
let events = sink.events();
@@ -241,6 +272,44 @@ async fn send_message_parses_prompt_cache_token_usage_from_response() {
assert_eq!(response.usage.output_tokens, 4);
}
+#[tokio::test]
+async fn given_empty_usage_object_when_send_message_parses_response_then_usage_defaults_to_zero() {
+ // given
+ let state = Arc::new(Mutex::new(Vec::::new()));
+ let body = concat!(
+ "{",
+ "\"id\":\"msg_empty_usage\",",
+ "\"type\":\"message\",",
+ "\"role\":\"assistant\",",
+ "\"content\":[{\"type\":\"text\",\"text\":\"Hello from Claude\"}],",
+ "\"model\":\"claude-3-7-sonnet-latest\",",
+ "\"stop_reason\":\"end_turn\",",
+ "\"stop_sequence\":null,",
+ "\"usage\":{}",
+ "}"
+ );
+ let server = spawn_server(
+ state,
+ vec![http_response("200 OK", "application/json", body)],
+ )
+ .await;
+ let client = AnthropicClient::new("test-key").with_base_url(server.base_url());
+
+ // when
+ let response = client
+ .send_message(&sample_request(false))
+ .await
+ .expect("response with empty usage object should still parse");
+
+ // then
+ assert_eq!(response.id, "msg_empty_usage");
+ assert_eq!(response.total_tokens(), 0);
+ assert_eq!(response.usage.input_tokens, 0);
+ assert_eq!(response.usage.cache_creation_input_tokens, 0);
+ assert_eq!(response.usage.cache_read_input_tokens, 0);
+ assert_eq!(response.usage.output_tokens, 0);
+}
+
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn stream_message_parses_sse_events_with_tool_use() {
@@ -476,6 +545,71 @@ async fn surfaces_retry_exhaustion_for_persistent_retryable_errors() {
}
}
+#[tokio::test]
+async fn retries_multiple_retryable_failures_with_exponential_backoff_and_jitter() {
+ let state = Arc::new(Mutex::new(Vec::::new()));
+ let server = spawn_server(
+ state.clone(),
+ vec![
+ http_response(
+ "429 Too Many Requests",
+ "application/json",
+ "{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"slow down\"}}",
+ ),
+ http_response(
+ "500 Internal Server Error",
+ "application/json",
+ "{\"type\":\"error\",\"error\":{\"type\":\"api_error\",\"message\":\"boom\"}}",
+ ),
+ http_response(
+ "503 Service Unavailable",
+ "application/json",
+ "{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"busy\"}}",
+ ),
+ http_response(
+ "429 Too Many Requests",
+ "application/json",
+ "{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"slow down again\"}}",
+ ),
+ http_response(
+ "503 Service Unavailable",
+ "application/json",
+ "{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"still busy\"}}",
+ ),
+ http_response(
+ "200 OK",
+ "application/json",
+ "{\"id\":\"msg_exp_retry\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Recovered after 5\"}],\"model\":\"claude-3-7-sonnet-latest\",\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":3,\"output_tokens\":2}}",
+ ),
+ ],
+ )
+ .await;
+
+ let client = ApiClient::new("test-key")
+ .with_base_url(server.base_url())
+ .with_retry_policy(8, Duration::from_millis(1), Duration::from_millis(4));
+ let started_at = std::time::Instant::now();
+
+ let response = client
+ .send_message(&sample_request(false))
+ .await
+ .expect("8-retry policy should absorb 5 retryable failures");
+
+ let elapsed = started_at.elapsed();
+ assert_eq!(response.total_tokens(), 5);
+ assert_eq!(
+ state.lock().await.len(),
+ 6,
+ "client should issue 1 original + 5 retry requests before the 200"
+ );
+ // Jittered sleeps are bounded by 2 * max_backoff per retry (base + jitter),
+ // so 5 sleeps fit comfortably below this upper bound with generous slack.
+ assert!(
+ elapsed < Duration::from_secs(5),
+ "retries should complete promptly, took {elapsed:?}"
+ );
+}
+
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn send_message_reuses_recent_completion_cache_entries() {
diff --git a/rust/crates/api/tests/openai_compat_integration.rs b/rust/crates/api/tests/openai_compat_integration.rs
index e12e6733..2dd90a2c 100644
--- a/rust/crates/api/tests/openai_compat_integration.rs
+++ b/rust/crates/api/tests/openai_compat_integration.rs
@@ -4,10 +4,10 @@ use std::sync::Arc;
use std::sync::{Mutex as StdMutex, OnceLock};
use api::{
- ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
- InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest, OpenAiCompatClient,
- OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent, ToolChoice,
- ToolDefinition,
+ ApiError, ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent,
+ ContentBlockStopEvent, InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest,
+ OpenAiCompatClient, OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent,
+ ToolChoice, ToolDefinition,
};
use serde_json::json;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -63,6 +63,42 @@ async fn send_message_uses_openai_compatible_endpoint_and_auth() {
assert_eq!(body["tools"][0]["type"], json!("function"));
}
+#[tokio::test]
+async fn send_message_blocks_oversized_xai_requests_before_the_http_call() {
+ let state = Arc::new(Mutex::new(Vec::::new()));
+ let server = spawn_server(
+ state.clone(),
+ vec![http_response("200 OK", "application/json", "{}")],
+ )
+ .await;
+
+ let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
+ .with_base_url(server.base_url());
+ let error = client
+ .send_message(&MessageRequest {
+ model: "grok-3".to_string(),
+ max_tokens: 64_000,
+ messages: vec![InputMessage {
+ role: "user".to_string(),
+ content: vec![InputContentBlock::Text {
+ text: "x".repeat(300_000),
+ }],
+ }],
+ system: Some("Keep the answer short.".to_string()),
+ tools: None,
+ tool_choice: None,
+ stream: false,
+ })
+ .await
+ .expect_err("oversized request should fail local context-window preflight");
+
+ assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
+ assert!(
+ state.lock().await.is_empty(),
+ "preflight failure should avoid any upstream HTTP request"
+ );
+}
+
#[tokio::test]
async fn send_message_accepts_full_chat_completions_endpoint_override() {
let state = Arc::new(Mutex::new(Vec::::new()));
diff --git a/rust/crates/api/tests/proxy_integration.rs b/rust/crates/api/tests/proxy_integration.rs
new file mode 100644
index 00000000..7e390698
--- /dev/null
+++ b/rust/crates/api/tests/proxy_integration.rs
@@ -0,0 +1,173 @@
+use std::ffi::OsString;
+use std::sync::{Mutex, OnceLock};
+
+use api::{build_http_client_with, ProxyConfig};
+
+fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+ static LOCK: OnceLock> = OnceLock::new();
+ LOCK.get_or_init(|| Mutex::new(()))
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+struct EnvVarGuard {
+ key: &'static str,
+ original: Option,
+}
+
+impl EnvVarGuard {
+ fn set(key: &'static str, value: Option<&str>) -> Self {
+ let original = std::env::var_os(key);
+ match value {
+ Some(value) => std::env::set_var(key, value),
+ None => std::env::remove_var(key),
+ }
+ Self { key, original }
+ }
+}
+
+impl Drop for EnvVarGuard {
+ fn drop(&mut self) {
+ match &self.original {
+ Some(value) => std::env::set_var(self.key, value),
+ None => std::env::remove_var(self.key),
+ }
+ }
+}
+
+#[test]
+fn proxy_config_from_env_reads_uppercase_proxy_vars() {
+ // given
+ let _lock = env_lock();
+ let _http = EnvVarGuard::set("HTTP_PROXY", Some("http://proxy.corp:3128"));
+ let _https = EnvVarGuard::set("HTTPS_PROXY", Some("http://secure.corp:3129"));
+ let _no = EnvVarGuard::set("NO_PROXY", Some("localhost,127.0.0.1"));
+ let _http_lower = EnvVarGuard::set("http_proxy", None);
+ let _https_lower = EnvVarGuard::set("https_proxy", None);
+ let _no_lower = EnvVarGuard::set("no_proxy", None);
+
+ // when
+ let config = ProxyConfig::from_env();
+
+ // then
+ assert_eq!(config.http_proxy.as_deref(), Some("http://proxy.corp:3128"));
+ assert_eq!(
+ config.https_proxy.as_deref(),
+ Some("http://secure.corp:3129")
+ );
+ assert_eq!(config.no_proxy.as_deref(), Some("localhost,127.0.0.1"));
+ assert!(config.proxy_url.is_none());
+ assert!(!config.is_empty());
+}
+
+#[test]
+fn proxy_config_from_env_reads_lowercase_proxy_vars() {
+ // given
+ let _lock = env_lock();
+ let _http = EnvVarGuard::set("HTTP_PROXY", None);
+ let _https = EnvVarGuard::set("HTTPS_PROXY", None);
+ let _no = EnvVarGuard::set("NO_PROXY", None);
+ let _http_lower = EnvVarGuard::set("http_proxy", Some("http://lower.corp:3128"));
+ let _https_lower = EnvVarGuard::set("https_proxy", Some("http://lower-secure.corp:3129"));
+ let _no_lower = EnvVarGuard::set("no_proxy", Some(".internal"));
+
+ // when
+ let config = ProxyConfig::from_env();
+
+ // then
+ assert_eq!(config.http_proxy.as_deref(), Some("http://lower.corp:3128"));
+ assert_eq!(
+ config.https_proxy.as_deref(),
+ Some("http://lower-secure.corp:3129")
+ );
+ assert_eq!(config.no_proxy.as_deref(), Some(".internal"));
+ assert!(!config.is_empty());
+}
+
+#[test]
+fn proxy_config_from_env_is_empty_when_no_vars_set() {
+ // given
+ let _lock = env_lock();
+ let _http = EnvVarGuard::set("HTTP_PROXY", None);
+ let _https = EnvVarGuard::set("HTTPS_PROXY", None);
+ let _no = EnvVarGuard::set("NO_PROXY", None);
+ let _http_lower = EnvVarGuard::set("http_proxy", None);
+ let _https_lower = EnvVarGuard::set("https_proxy", None);
+ let _no_lower = EnvVarGuard::set("no_proxy", None);
+
+ // when
+ let config = ProxyConfig::from_env();
+
+ // then
+ assert!(config.is_empty());
+ assert!(config.http_proxy.is_none());
+ assert!(config.https_proxy.is_none());
+ assert!(config.no_proxy.is_none());
+}
+
+#[test]
+fn proxy_config_from_env_treats_empty_values_as_unset() {
+ // given
+ let _lock = env_lock();
+ let _http = EnvVarGuard::set("HTTP_PROXY", Some(""));
+ let _https = EnvVarGuard::set("HTTPS_PROXY", Some(""));
+ let _http_lower = EnvVarGuard::set("http_proxy", Some(""));
+ let _https_lower = EnvVarGuard::set("https_proxy", Some(""));
+ let _no = EnvVarGuard::set("NO_PROXY", Some(""));
+ let _no_lower = EnvVarGuard::set("no_proxy", Some(""));
+
+ // when
+ let config = ProxyConfig::from_env();
+
+ // then
+ assert!(config.is_empty());
+}
+
+#[test]
+fn build_client_with_env_proxy_config_succeeds() {
+ // given
+ let _lock = env_lock();
+ let _http = EnvVarGuard::set("HTTP_PROXY", Some("http://proxy.corp:3128"));
+ let _https = EnvVarGuard::set("HTTPS_PROXY", Some("http://secure.corp:3129"));
+ let _no = EnvVarGuard::set("NO_PROXY", Some("localhost"));
+ let _http_lower = EnvVarGuard::set("http_proxy", None);
+ let _https_lower = EnvVarGuard::set("https_proxy", None);
+ let _no_lower = EnvVarGuard::set("no_proxy", None);
+ let config = ProxyConfig::from_env();
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+}
+
+#[test]
+fn build_client_with_proxy_url_config_succeeds() {
+ // given
+ let config = ProxyConfig::from_proxy_url("http://unified.corp:3128");
+
+ // when
+ let result = build_http_client_with(&config);
+
+ // then
+ assert!(result.is_ok());
+}
+
+#[test]
+fn proxy_config_from_env_prefers_uppercase_over_lowercase() {
+ // given
+ let _lock = env_lock();
+ let _http_upper = EnvVarGuard::set("HTTP_PROXY", Some("http://upper.corp:3128"));
+ let _http_lower = EnvVarGuard::set("http_proxy", Some("http://lower.corp:3128"));
+ let _https = EnvVarGuard::set("HTTPS_PROXY", None);
+ let _https_lower = EnvVarGuard::set("https_proxy", None);
+ let _no = EnvVarGuard::set("NO_PROXY", None);
+ let _no_lower = EnvVarGuard::set("no_proxy", None);
+
+ // when
+ let config = ProxyConfig::from_env();
+
+ // then
+ assert_eq!(config.http_proxy.as_deref(), Some("http://upper.corp:3128"));
+}
diff --git a/rust/crates/commands/src/lib.rs b/rust/crates/commands/src/lib.rs
index 7e6191d9..dc329d10 100644
--- a/rust/crates/commands/src/lib.rs
+++ b/rust/crates/commands/src/lib.rs
@@ -9,6 +9,7 @@ use runtime::{
compact_session, CompactionConfig, ConfigLoader, ConfigSource, McpOAuthConfig, McpServerConfig,
ScopedMcpServerConfig, Session,
};
+use serde_json::{json, Value};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommandManifestEntry {
@@ -49,6 +50,12 @@ pub struct SlashCommandSpec {
pub resume_supported: bool,
}
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SkillSlashDispatch {
+ Local,
+ Invoke(String),
+}
+
const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
SlashCommandSpec {
name: "help",
@@ -214,8 +221,10 @@ const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
SlashCommandSpec {
name: "session",
aliases: &[],
- summary: "List, switch, or fork managed local sessions",
- argument_hint: Some("[list|switch |fork [branch-name]]"),
+ summary: "List, switch, fork, or delete managed local sessions",
+ argument_hint: Some(
+ "[list|switch |fork [branch-name]|delete [--force]]",
+ ),
resume_supported: false,
},
SlashCommandSpec {
@@ -236,9 +245,9 @@ const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
},
SlashCommandSpec {
name: "skills",
- aliases: &[],
- summary: "List or install available skills",
- argument_hint: Some("[list|install |help]"),
+ aliases: &["skill"],
+ summary: "List, install, or invoke available skills",
+ argument_hint: Some("[list|install |help| [args]]"),
resume_supported: true,
},
SlashCommandSpec {
@@ -1181,6 +1190,9 @@ pub enum SlashCommand {
AddDir {
path: Option,
},
+ History {
+ count: Option,
+ },
Unknown(String),
}
@@ -1305,7 +1317,7 @@ pub fn validate_slash_command_input(
"agents" => SlashCommand::Agents {
args: parse_list_or_help_args(command, remainder)?,
},
- "skills" => SlashCommand::Skills {
+ "skills" | "skill" => SlashCommand::Skills {
args: parse_skills_args(remainder.as_deref())?,
},
"doctor" => {
@@ -1414,6 +1426,9 @@ pub fn validate_slash_command_input(
"tag" => SlashCommand::Tag { label: remainder },
"output-style" => SlashCommand::OutputStyle { style: remainder },
"add-dir" => SlashCommand::AddDir { path: remainder },
+ "history" => SlashCommand::History {
+ count: optional_single_arg(command, &args, "[count]")?,
+ },
other => SlashCommand::Unknown(other.to_string()),
}))
}
@@ -1513,7 +1528,7 @@ fn parse_session_command(args: &[&str]) -> Result Err(usage_error("session", "[list|switch |fork [branch-name]]")),
+ ["list", ..] => Err(usage_error("session", "[list|switch |fork [branch-name]|delete [--force]]")),
["switch"] => Err(usage_error("session switch", "")),
["switch", target] => Ok(SlashCommand::Session {
action: Some("switch".to_string()),
@@ -1537,12 +1552,33 @@ fn parse_session_command(args: &[&str]) -> Result Err(command_error(
+ ["delete"] => Err(usage_error("session delete", " [--force]")),
+ ["delete", target] => Ok(SlashCommand::Session {
+ action: Some("delete".to_string()),
+ target: Some((*target).to_string()),
+ }),
+ ["delete", target, "--force"] => Ok(SlashCommand::Session {
+ action: Some("delete-force".to_string()),
+ target: Some((*target).to_string()),
+ }),
+ ["delete", _target, unexpected] => Err(command_error(
&format!(
- "Unknown /session action '{action}'. Use list, switch , or fork [branch-name]."
+ "Unsupported /session delete flag '{unexpected}'. Use --force to skip confirmation."
),
"session",
- "/session [list|switch |fork [branch-name]]",
+ "/session delete [--force]",
+ )),
+ ["delete", ..] => Err(command_error(
+ "Unexpected arguments for /session delete.",
+ "session",
+ "/session delete [--force]",
+ )),
+ [action, ..] => Err(command_error(
+ &format!(
+ "Unknown /session action '{action}'. Use list, switch , fork [branch-name], or delete [--force]."
+ ),
+ "session",
+ "/session [list|switch |fork [branch-name]|delete [--force]]",
)),
}
}
@@ -1685,13 +1721,7 @@ fn parse_skills_args(args: Option<&str>) -> Result, SlashCommandP
}
}
- Err(command_error(
- &format!(
- "Unexpected arguments for /skills: {args}. Use /skills, /skills list, /skills install , or /skills help."
- ),
- "skills",
- "/skills [list|install |help]",
- ))
+ Ok(Some(args.to_string()))
}
fn usage_error(command: &str, argument_hint: &str) -> SlashCommandParseError {
@@ -1785,24 +1815,29 @@ pub fn resume_supported_slash_commands() -> Vec<&'static SlashCommandSpec> {
fn slash_command_category(name: &str) -> &'static str {
match name {
- "help" | "status" | "sandbox" | "model" | "permissions" | "cost" | "resume" | "session"
- | "version" | "login" | "logout" | "usage" | "stats" | "rename" | "privacy-settings" => {
- "Session & visibility"
- }
- "compact" | "clear" | "config" | "memory" | "init" | "diff" | "commit" | "pr" | "issue"
- | "export" | "plugin" | "branch" | "add-dir" | "files" | "hooks" | "release-notes" => {
- "Workspace & git"
- }
- "agents" | "skills" | "teleport" | "debug-tool-call" | "mcp" | "context" | "tasks"
- | "doctor" | "ide" | "desktop" => "Discovery & debugging",
- "bughunter" | "ultraplan" | "review" | "security-review" | "advisor" | "insights" => {
- "Analysis & automation"
- }
- "theme" | "vim" | "voice" | "color" | "effort" | "fast" | "brief" | "output-style"
- | "keybindings" | "stickers" => "Appearance & input",
- "copy" | "share" | "feedback" | "summary" | "tag" | "thinkback" | "plan" | "exit"
- | "upgrade" | "rewind" => "Communication & control",
- _ => "Other",
+ "help" | "status" | "cost" | "resume" | "session" | "version" | "login" | "logout"
+ | "usage" | "stats" | "rename" | "clear" | "compact" | "history" | "tokens" | "cache"
+ | "exit" | "summary" | "tag" | "thinkback" | "copy" | "share" | "feedback" | "rewind"
+ | "pin" | "unpin" | "bookmarks" | "context" | "files" | "focus" | "unfocus" | "retry"
+ | "stop" | "undo" => "Session",
+ "diff" | "commit" | "pr" | "issue" | "branch" | "blame" | "log" | "git" | "stash"
+ | "init" | "export" | "plan" | "review" | "security-review" | "bughunter" | "ultraplan"
+ | "teleport" | "refactor" | "fix" | "autofix" | "explain" | "docs" | "perf" | "search"
+ | "references" | "definition" | "hover" | "symbols" | "map" | "web" | "image"
+ | "screenshot" | "paste" | "listen" | "speak" | "test" | "lint" | "build" | "run"
+ | "format" | "parallel" | "multi" | "macro" | "alias" | "templates" | "migrate"
+ | "benchmark" | "cron" | "agent" | "subagent" | "agents" | "skills" | "team" | "plugin"
+ | "mcp" | "hooks" | "tasks" | "advisor" | "insights" | "release-notes" | "chat"
+ | "approve" | "deny" | "allowed-tools" | "add-dir" => "Tools",
+ "model" | "permissions" | "config" | "memory" | "theme" | "vim" | "voice" | "color"
+ | "effort" | "fast" | "brief" | "output-style" | "keybindings" | "privacy-settings"
+ | "stickers" | "language" | "profile" | "max-tokens" | "temperature" | "system-prompt"
+ | "api-key" | "terminal-setup" | "notifications" | "telemetry" | "providers" | "env"
+ | "project" | "reasoning" | "budget" | "rate-limit" | "workspace" | "reset" | "ide"
+ | "desktop" | "upgrade" => "Config",
+ "debug-tool-call" | "doctor" | "sandbox" | "diagnostics" | "tool-details" | "changelog"
+ | "metrics" => "Debug",
+ _ => "Tools",
}
}
@@ -1911,12 +1946,7 @@ pub fn render_slash_command_help() -> String {
String::new(),
];
- let categories = [
- "Session & visibility",
- "Workspace & git",
- "Discovery & debugging",
- "Analysis & automation",
- ];
+ let categories = ["Session", "Tools", "Config", "Debug"];
for category in categories {
lines.push(category.to_string());
@@ -1929,6 +1959,12 @@ pub fn render_slash_command_help() -> String {
lines.push(String::new());
}
+ lines.push("Keyboard shortcuts".to_string());
+ lines.push(" Up/Down Navigate prompt history".to_string());
+ lines.push(" Tab Complete commands, modes, and recent sessions".to_string());
+ lines.push(" Ctrl-C Clear input (or exit on empty prompt)".to_string());
+ lines.push(" Shift+Enter/Ctrl+J Insert a newline".to_string());
+
lines
.into_iter()
.rev()
@@ -1954,25 +1990,49 @@ pub struct PluginsCommandResult {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum DefinitionSource {
+ ProjectClaw,
ProjectCodex,
ProjectClaude,
+ UserClawConfigHome,
UserCodexHome,
+ UserClaw,
UserCodex,
UserClaude,
}
-impl DefinitionSource {
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum DefinitionScope {
+ Project,
+ UserConfigHome,
+ UserHome,
+}
+
+impl DefinitionScope {
fn label(self) -> &'static str {
match self {
- Self::ProjectCodex => "Project (.codex)",
- Self::ProjectClaude => "Project (.claude)",
- Self::UserCodexHome => "User ($CODEX_HOME)",
- Self::UserCodex => "User (~/.codex)",
- Self::UserClaude => "User (~/.claude)",
+ Self::Project => "Project roots",
+ Self::UserConfigHome => "User config roots",
+ Self::UserHome => "User home roots",
}
}
}
+impl DefinitionSource {
+ fn report_scope(self) -> DefinitionScope {
+ match self {
+ Self::ProjectClaw | Self::ProjectCodex | Self::ProjectClaude => {
+ DefinitionScope::Project
+ }
+ Self::UserClawConfigHome | Self::UserCodexHome => DefinitionScope::UserConfigHome,
+ Self::UserClaw | Self::UserCodex | Self::UserClaude => DefinitionScope::UserHome,
+ }
+ }
+
+ fn label(self) -> &'static str {
+ self.report_scope().label()
+ }
+}
+
#[derive(Debug, Clone, PartialEq, Eq)]
struct AgentSummary {
name: String,
@@ -2142,17 +2202,47 @@ pub fn handle_plugins_slash_command(
}
pub fn handle_agents_slash_command(args: Option<&str>, cwd: &Path) -> std::io::Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_agents_usage(None),
+ _ => render_agents_usage(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
match normalize_optional_args(args) {
None | Some("list") => {
let roots = discover_definition_roots(cwd, "agents");
let agents = load_agents_from_roots(&roots)?;
Ok(render_agents_report(&agents))
}
- Some("-h" | "--help" | "help") => Ok(render_agents_usage(None)),
+ Some(args) if is_help_arg(args) => Ok(render_agents_usage(None)),
Some(args) => Ok(render_agents_usage(Some(args))),
}
}
+pub fn handle_agents_slash_command_json(args: Option<&str>, cwd: &Path) -> std::io::Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_agents_usage_json(None),
+ _ => render_agents_usage_json(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
+ match normalize_optional_args(args) {
+ None | Some("list") => {
+ let roots = discover_definition_roots(cwd, "agents");
+ let agents = load_agents_from_roots(&roots)?;
+ Ok(render_agents_report_json(cwd, &agents))
+ }
+ Some(args) if is_help_arg(args) => Ok(render_agents_usage_json(None)),
+ Some(args) => Ok(render_agents_usage_json(Some(args))),
+ }
+}
+
pub fn handle_mcp_slash_command(
args: Option<&str>,
cwd: &Path,
@@ -2161,7 +2251,25 @@ pub fn handle_mcp_slash_command(
render_mcp_report_for(&loader, cwd, args)
}
+pub fn handle_mcp_slash_command_json(
+ args: Option<&str>,
+ cwd: &Path,
+) -> Result {
+ let loader = ConfigLoader::default_for(cwd);
+ render_mcp_report_json_for(&loader, cwd, args)
+}
+
pub fn handle_skills_slash_command(args: Option<&str>, cwd: &Path) -> std::io::Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_skills_usage(None),
+ ["install", ..] => render_skills_usage(Some("install")),
+ _ => render_skills_usage(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
match normalize_optional_args(args) {
None | Some("list") => {
let roots = discover_skill_roots(cwd);
@@ -2177,16 +2285,177 @@ pub fn handle_skills_slash_command(args: Option<&str>, cwd: &Path) -> std::io::R
let install = install_skill(target, cwd)?;
Ok(render_skill_install_report(&install))
}
- Some("-h" | "--help" | "help") => Ok(render_skills_usage(None)),
+ Some(args) if is_help_arg(args) => Ok(render_skills_usage(None)),
Some(args) => Ok(render_skills_usage(Some(args))),
}
}
+pub fn handle_skills_slash_command_json(args: Option<&str>, cwd: &Path) -> std::io::Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_skills_usage_json(None),
+ ["install", ..] => render_skills_usage_json(Some("install")),
+ _ => render_skills_usage_json(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
+ match normalize_optional_args(args) {
+ None | Some("list") => {
+ let roots = discover_skill_roots(cwd);
+ let skills = load_skills_from_roots(&roots)?;
+ Ok(render_skills_report_json(&skills))
+ }
+ Some("install") => Ok(render_skills_usage_json(Some("install"))),
+ Some(args) if args.starts_with("install ") => {
+ let target = args["install ".len()..].trim();
+ if target.is_empty() {
+ return Ok(render_skills_usage_json(Some("install")));
+ }
+ let install = install_skill(target, cwd)?;
+ Ok(render_skill_install_report_json(&install))
+ }
+ Some(args) if is_help_arg(args) => Ok(render_skills_usage_json(None)),
+ Some(args) => Ok(render_skills_usage_json(Some(args))),
+ }
+}
+
+#[must_use]
+pub fn classify_skills_slash_command(args: Option<&str>) -> SkillSlashDispatch {
+ match normalize_optional_args(args) {
+ None | Some("list" | "help" | "-h" | "--help") => SkillSlashDispatch::Local,
+ Some(args) if args == "install" || args.starts_with("install ") => {
+ SkillSlashDispatch::Local
+ }
+ Some(args) => SkillSlashDispatch::Invoke(format!("${}", args.trim_start_matches('/'))),
+ }
+}
+
+/// Resolve a skill invocation by validating the skill exists on disk before
+/// returning the dispatch. When the skill is not found, returns `Err` with a
+/// human-readable message that lists nearby skill names.
+pub fn resolve_skill_invocation(
+ cwd: &Path,
+ args: Option<&str>,
+) -> Result {
+ let dispatch = classify_skills_slash_command(args);
+ if let SkillSlashDispatch::Invoke(ref prompt) = dispatch {
+ // Extract the skill name from the "$skill [args]" prompt.
+ let skill_token = prompt
+ .trim_start_matches('$')
+ .split_whitespace()
+ .next()
+ .unwrap_or_default();
+ if !skill_token.is_empty() {
+ if let Err(error) = resolve_skill_path(cwd, skill_token) {
+ let mut message = format!("Unknown skill: {skill_token} ({error})");
+ let roots = discover_skill_roots(cwd);
+ if let Ok(available) = load_skills_from_roots(&roots) {
+ let names: Vec = available
+ .iter()
+ .filter(|s| s.shadowed_by.is_none())
+ .map(|s| s.name.clone())
+ .collect();
+ if !names.is_empty() {
+ message.push_str(&format!("\n Available skills: {}", names.join(", ")));
+ }
+ }
+ message.push_str("\n Usage: /skills [list|install |help| [args]]");
+ return Err(message);
+ }
+ }
+ }
+ Ok(dispatch)
+}
+
+pub fn resolve_skill_path(cwd: &Path, skill: &str) -> std::io::Result {
+ let requested = skill.trim().trim_start_matches('/').trim_start_matches('$');
+ if requested.is_empty() {
+ return Err(std::io::Error::new(
+ std::io::ErrorKind::InvalidInput,
+ "skill must not be empty",
+ ));
+ }
+
+ let roots = discover_skill_roots(cwd);
+ for root in &roots {
+ let mut entries = Vec::new();
+ for entry in fs::read_dir(&root.path)? {
+ let entry = entry?;
+ match root.origin {
+ SkillOrigin::SkillsDir => {
+ if !entry.path().is_dir() {
+ continue;
+ }
+ let skill_path = entry.path().join("SKILL.md");
+ if !skill_path.is_file() {
+ continue;
+ }
+ let contents = fs::read_to_string(&skill_path)?;
+ let (name, _) = parse_skill_frontmatter(&contents);
+ entries.push((
+ name.unwrap_or_else(|| entry.file_name().to_string_lossy().to_string()),
+ skill_path,
+ ));
+ }
+ SkillOrigin::LegacyCommandsDir => {
+ let path = entry.path();
+ let markdown_path = if path.is_dir() {
+ let skill_path = path.join("SKILL.md");
+ if !skill_path.is_file() {
+ continue;
+ }
+ skill_path
+ } else if path
+ .extension()
+ .is_some_and(|ext| ext.to_string_lossy().eq_ignore_ascii_case("md"))
+ {
+ path
+ } else {
+ continue;
+ };
+
+ let contents = fs::read_to_string(&markdown_path)?;
+ let fallback_name = markdown_path.file_stem().map_or_else(
+ || entry.file_name().to_string_lossy().to_string(),
+ |stem| stem.to_string_lossy().to_string(),
+ );
+ let (name, _) = parse_skill_frontmatter(&contents);
+ entries.push((name.unwrap_or(fallback_name), markdown_path));
+ }
+ }
+ }
+ entries.sort_by(|left, right| left.0.cmp(&right.0));
+ if let Some((_, path)) = entries
+ .into_iter()
+ .find(|(name, _)| name.eq_ignore_ascii_case(requested))
+ {
+ return Ok(path);
+ }
+ }
+
+ Err(std::io::Error::new(
+ std::io::ErrorKind::NotFound,
+ format!("unknown skill: {requested}"),
+ ))
+}
+
fn render_mcp_report_for(
loader: &ConfigLoader,
cwd: &Path,
args: Option<&str>,
) -> Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_mcp_usage(None),
+ ["show", ..] => render_mcp_usage(Some("show")),
+ _ => render_mcp_usage(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
match normalize_optional_args(args) {
None | Some("list") => {
let runtime_config = loader.load()?;
@@ -2195,7 +2464,7 @@ fn render_mcp_report_for(
runtime_config.mcp().servers(),
))
}
- Some("-h" | "--help" | "help") => Ok(render_mcp_usage(None)),
+ Some(args) if is_help_arg(args) => Ok(render_mcp_usage(None)),
Some("show") => Ok(render_mcp_usage(Some("show"))),
Some(args) if args.split_whitespace().next() == Some("show") => {
let mut parts = args.split_whitespace();
@@ -2217,6 +2486,51 @@ fn render_mcp_report_for(
}
}
+fn render_mcp_report_json_for(
+ loader: &ConfigLoader,
+ cwd: &Path,
+ args: Option<&str>,
+) -> Result {
+ if let Some(args) = normalize_optional_args(args) {
+ if let Some(help_path) = help_path_from_args(args) {
+ return Ok(match help_path.as_slice() {
+ [] => render_mcp_usage_json(None),
+ ["show", ..] => render_mcp_usage_json(Some("show")),
+ _ => render_mcp_usage_json(Some(&help_path.join(" "))),
+ });
+ }
+ }
+
+ match normalize_optional_args(args) {
+ None | Some("list") => {
+ let runtime_config = loader.load()?;
+ Ok(render_mcp_summary_report_json(
+ cwd,
+ runtime_config.mcp().servers(),
+ ))
+ }
+ Some(args) if is_help_arg(args) => Ok(render_mcp_usage_json(None)),
+ Some("show") => Ok(render_mcp_usage_json(Some("show"))),
+ Some(args) if args.split_whitespace().next() == Some("show") => {
+ let mut parts = args.split_whitespace();
+ let _ = parts.next();
+ let Some(server_name) = parts.next() else {
+ return Ok(render_mcp_usage_json(Some("show")));
+ };
+ if parts.next().is_some() {
+ return Ok(render_mcp_usage_json(Some(args)));
+ }
+ let runtime_config = loader.load()?;
+ Ok(render_mcp_server_report_json(
+ cwd,
+ server_name,
+ runtime_config.mcp().get(server_name),
+ ))
+ }
+ Some(args) => Ok(render_mcp_usage_json(Some(args))),
+ }
+}
+
#[must_use]
pub fn render_plugins_report(plugins: &[PluginSummary]) -> String {
let mut lines = vec!["Plugins".to_string()];
@@ -2273,6 +2587,11 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
let mut roots = Vec::new();
for ancestor in cwd.ancestors() {
+ push_unique_root(
+ &mut roots,
+ DefinitionSource::ProjectClaw,
+ ancestor.join(".claw").join(leaf),
+ );
push_unique_root(
&mut roots,
DefinitionSource::ProjectCodex,
@@ -2285,6 +2604,14 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
);
}
+ if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+ push_unique_root(
+ &mut roots,
+ DefinitionSource::UserClawConfigHome,
+ PathBuf::from(claw_config_home).join(leaf),
+ );
+ }
+
if let Ok(codex_home) = env::var("CODEX_HOME") {
push_unique_root(
&mut roots,
@@ -2293,8 +2620,21 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
);
}
+ if let Ok(claude_config_dir) = env::var("CLAUDE_CONFIG_DIR") {
+ push_unique_root(
+ &mut roots,
+ DefinitionSource::UserClaude,
+ PathBuf::from(claude_config_dir).join(leaf),
+ );
+ }
+
if let Some(home) = env::var_os("HOME") {
let home = PathBuf::from(home);
+ push_unique_root(
+ &mut roots,
+ DefinitionSource::UserClaw,
+ home.join(".claw").join(leaf),
+ );
push_unique_root(
&mut roots,
DefinitionSource::UserCodex,
@@ -2310,10 +2650,29 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
roots
}
+#[allow(clippy::too_many_lines)]
fn discover_skill_roots(cwd: &Path) -> Vec {
let mut roots = Vec::new();
for ancestor in cwd.ancestors() {
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::ProjectClaw,
+ ancestor.join(".claw").join("skills"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::ProjectClaw,
+ ancestor.join(".omc").join("skills"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::ProjectClaw,
+ ancestor.join(".agents").join("skills"),
+ SkillOrigin::SkillsDir,
+ );
push_unique_skill_root(
&mut roots,
DefinitionSource::ProjectCodex,
@@ -2326,6 +2685,12 @@ fn discover_skill_roots(cwd: &Path) -> Vec {
ancestor.join(".claude").join("skills"),
SkillOrigin::SkillsDir,
);
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::ProjectClaw,
+ ancestor.join(".claw").join("commands"),
+ SkillOrigin::LegacyCommandsDir,
+ );
push_unique_skill_root(
&mut roots,
DefinitionSource::ProjectCodex,
@@ -2340,6 +2705,22 @@ fn discover_skill_roots(cwd: &Path) -> Vec {
);
}
+ if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+ let claw_config_home = PathBuf::from(claw_config_home);
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClawConfigHome,
+ claw_config_home.join("skills"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClawConfigHome,
+ claw_config_home.join("commands"),
+ SkillOrigin::LegacyCommandsDir,
+ );
+ }
+
if let Ok(codex_home) = env::var("CODEX_HOME") {
let codex_home = PathBuf::from(codex_home);
push_unique_skill_root(
@@ -2358,6 +2739,24 @@ fn discover_skill_roots(cwd: &Path) -> Vec {
if let Some(home) = env::var_os("HOME") {
let home = PathBuf::from(home);
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaw,
+ home.join(".claw").join("skills"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaw,
+ home.join(".omc").join("skills"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaw,
+ home.join(".claw").join("commands"),
+ SkillOrigin::LegacyCommandsDir,
+ );
push_unique_skill_root(
&mut roots,
DefinitionSource::UserCodex,
@@ -2376,6 +2775,12 @@ fn discover_skill_roots(cwd: &Path) -> Vec {
home.join(".claude").join("skills"),
SkillOrigin::SkillsDir,
);
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaude,
+ home.join(".claude").join("skills").join("omc-learned"),
+ SkillOrigin::SkillsDir,
+ );
push_unique_skill_root(
&mut roots,
DefinitionSource::UserClaude,
@@ -2384,6 +2789,29 @@ fn discover_skill_roots(cwd: &Path) -> Vec {
);
}
+ if let Ok(claude_config_dir) = env::var("CLAUDE_CONFIG_DIR") {
+ let claude_config_dir = PathBuf::from(claude_config_dir);
+ let skills_dir = claude_config_dir.join("skills");
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaude,
+ skills_dir.clone(),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaude,
+ skills_dir.join("omc-learned"),
+ SkillOrigin::SkillsDir,
+ );
+ push_unique_skill_root(
+ &mut roots,
+ DefinitionSource::UserClaude,
+ claude_config_dir.join("commands"),
+ SkillOrigin::LegacyCommandsDir,
+ );
+ }
+
roots
}
@@ -2438,15 +2866,18 @@ fn install_skill_into(
}
fn default_skill_install_root() -> std::io::Result {
+ if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+ return Ok(PathBuf::from(claw_config_home).join("skills"));
+ }
if let Ok(codex_home) = env::var("CODEX_HOME") {
return Ok(PathBuf::from(codex_home).join("skills"));
}
if let Some(home) = env::var_os("HOME") {
- return Ok(PathBuf::from(home).join(".codex").join("skills"));
+ return Ok(PathBuf::from(home).join(".claw").join("skills"));
}
Err(std::io::Error::new(
std::io::ErrorKind::NotFound,
- "unable to resolve a skills install root; set CODEX_HOME or HOME",
+ "unable to resolve a skills install root; set CLAW_CONFIG_HOME or HOME",
))
}
@@ -2812,22 +3243,20 @@ fn render_agents_report(agents: &[AgentSummary]) -> String {
String::new(),
];
- for source in [
- DefinitionSource::ProjectCodex,
- DefinitionSource::ProjectClaude,
- DefinitionSource::UserCodexHome,
- DefinitionSource::UserCodex,
- DefinitionSource::UserClaude,
+ for scope in [
+ DefinitionScope::Project,
+ DefinitionScope::UserConfigHome,
+ DefinitionScope::UserHome,
] {
let group = agents
.iter()
- .filter(|agent| agent.source == source)
+ .filter(|agent| agent.source.report_scope() == scope)
.collect::>();
if group.is_empty() {
continue;
}
- lines.push(format!("{}:", source.label()));
+ lines.push(format!("{}:", scope.label()));
for agent in group {
let detail = agent_detail(agent);
match agent.shadowed_by {
@@ -2841,6 +3270,25 @@ fn render_agents_report(agents: &[AgentSummary]) -> String {
lines.join("\n").trim_end().to_string()
}
+fn render_agents_report_json(cwd: &Path, agents: &[AgentSummary]) -> Value {
+ let active = agents
+ .iter()
+ .filter(|agent| agent.shadowed_by.is_none())
+ .count();
+ json!({
+ "kind": "agents",
+ "action": "list",
+ "working_directory": cwd.display().to_string(),
+ "count": agents.len(),
+ "summary": {
+ "total": agents.len(),
+ "active": active,
+ "shadowed": agents.len().saturating_sub(active),
+ },
+ "agents": agents.iter().map(agent_summary_json).collect::>(),
+ })
+}
+
fn agent_detail(agent: &AgentSummary) -> String {
let mut parts = vec![agent.name.clone()];
if let Some(description) = &agent.description {
@@ -2870,22 +3318,20 @@ fn render_skills_report(skills: &[SkillSummary]) -> String {
String::new(),
];
- for source in [
- DefinitionSource::ProjectCodex,
- DefinitionSource::ProjectClaude,
- DefinitionSource::UserCodexHome,
- DefinitionSource::UserCodex,
- DefinitionSource::UserClaude,
+ for scope in [
+ DefinitionScope::Project,
+ DefinitionScope::UserConfigHome,
+ DefinitionScope::UserHome,
] {
let group = skills
.iter()
- .filter(|skill| skill.source == source)
+ .filter(|skill| skill.source.report_scope() == scope)
.collect::>();
if group.is_empty() {
continue;
}
- lines.push(format!("{}:", source.label()));
+ lines.push(format!("{}:", scope.label()));
for skill in group {
let mut parts = vec![skill.name.clone()];
if let Some(description) = &skill.description {
@@ -2906,6 +3352,23 @@ fn render_skills_report(skills: &[SkillSummary]) -> String {
lines.join("\n").trim_end().to_string()
}
+fn render_skills_report_json(skills: &[SkillSummary]) -> Value {
+ let active = skills
+ .iter()
+ .filter(|skill| skill.shadowed_by.is_none())
+ .count();
+ json!({
+ "kind": "skills",
+ "action": "list",
+ "summary": {
+ "total": skills.len(),
+ "active": active,
+ "shadowed": skills.len().saturating_sub(active),
+ },
+ "skills": skills.iter().map(skill_summary_json).collect::>(),
+ })
+}
+
fn render_skill_install_report(skill: &InstalledSkill) -> String {
let mut lines = vec![
"Skills".to_string(),
@@ -2927,6 +3390,20 @@ fn render_skill_install_report(skill: &InstalledSkill) -> String {
lines.join("\n")
}
+fn render_skill_install_report_json(skill: &InstalledSkill) -> Value {
+ json!({
+ "kind": "skills",
+ "action": "install",
+ "result": "installed",
+ "invocation_name": &skill.invocation_name,
+ "invoke_as": format!("${}", skill.invocation_name),
+ "display_name": &skill.display_name,
+ "source": skill.source.display().to_string(),
+ "registry_root": skill.registry_root.display().to_string(),
+ "installed_path": skill.installed_path.display().to_string(),
+ })
+}
+
fn render_mcp_summary_report(
cwd: &Path,
servers: &BTreeMap,
@@ -2954,6 +3431,22 @@ fn render_mcp_summary_report(
lines.join("\n")
}
+fn render_mcp_summary_report_json(
+ cwd: &Path,
+ servers: &BTreeMap,
+) -> Value {
+ json!({
+ "kind": "mcp",
+ "action": "list",
+ "working_directory": cwd.display().to_string(),
+ "configured_servers": servers.len(),
+ "servers": servers
+ .iter()
+ .map(|(name, server)| mcp_server_json(name, server))
+ .collect::>(),
+ })
+}
+
fn render_mcp_server_report(
cwd: &Path,
server_name: &str,
@@ -3032,16 +3525,51 @@ fn render_mcp_server_report(
lines.join("\n")
}
+
+fn render_mcp_server_report_json(
+ cwd: &Path,
+ server_name: &str,
+ server: Option<&ScopedMcpServerConfig>,
+) -> Value {
+ match server {
+ Some(server) => json!({
+ "kind": "mcp",
+ "action": "show",
+ "working_directory": cwd.display().to_string(),
+ "found": true,
+ "server": mcp_server_json(server_name, server),
+ }),
+ None => json!({
+ "kind": "mcp",
+ "action": "show",
+ "working_directory": cwd.display().to_string(),
+ "found": false,
+ "server_name": server_name,
+ "message": format!("server `{server_name}` is not configured"),
+ }),
+ }
+}
+
fn normalize_optional_args(args: Option<&str>) -> Option<&str> {
args.map(str::trim).filter(|value| !value.is_empty())
}
+fn is_help_arg(arg: &str) -> bool {
+ matches!(arg, "help" | "-h" | "--help")
+}
+
+fn help_path_from_args(args: &str) -> Option> {
+ let parts = args.split_whitespace().collect::>();
+ let help_index = parts.iter().position(|part| is_help_arg(part))?;
+ Some(parts[..help_index].to_vec())
+}
+
fn render_agents_usage(unexpected: Option<&str>) -> String {
let mut lines = vec![
"Agents".to_string(),
" Usage /agents [list|help]".to_string(),
" Direct CLI claw agents".to_string(),
- " Sources .codex/agents, .claude/agents, $CODEX_HOME/agents".to_string(),
+ " Sources .claw/agents, ~/.claw/agents, $CLAW_CONFIG_HOME/agents".to_string(),
];
if let Some(args) = unexpected {
lines.push(format!(" Unexpected {args}"));
@@ -3049,13 +3577,28 @@ fn render_agents_usage(unexpected: Option<&str>) -> String {
lines.join("\n")
}
+fn render_agents_usage_json(unexpected: Option<&str>) -> Value {
+ json!({
+ "kind": "agents",
+ "action": "help",
+ "usage": {
+ "slash_command": "/agents [list|help]",
+ "direct_cli": "claw agents [list|help]",
+ "sources": [".claw/agents", "~/.claw/agents", "$CLAW_CONFIG_HOME/agents"],
+ },
+ "unexpected": unexpected,
+ })
+}
+
fn render_skills_usage(unexpected: Option<&str>) -> String {
let mut lines = vec![
"Skills".to_string(),
- " Usage /skills [list|install |help]".to_string(),
- " Direct CLI claw skills [list|install |help]".to_string(),
- " Install root $CODEX_HOME/skills or ~/.codex/skills".to_string(),
- " Sources .codex/skills, .claude/skills, legacy /commands".to_string(),
+ " Usage /skills [list|install |help| [args]]".to_string(),
+ " Alias /skill".to_string(),
+ " Direct CLI claw skills [list|install |help| [args]]".to_string(),
+ " Invoke /skills help overview -> $help overview".to_string(),
+ " Install root $CLAW_CONFIG_HOME/skills or ~/.claw/skills".to_string(),
+ " Sources .claw/skills, .omc/skills, .agents/skills, .codex/skills, .claude/skills, ~/.claw/skills, ~/.omc/skills, ~/.claude/skills/omc-learned, ~/.codex/skills, ~/.claude/skills, legacy /commands".to_string(),
];
if let Some(args) = unexpected {
lines.push(format!(" Unexpected {args}"));
@@ -3063,6 +3606,35 @@ fn render_skills_usage(unexpected: Option<&str>) -> String {
lines.join("\n")
}
+fn render_skills_usage_json(unexpected: Option<&str>) -> Value {
+ json!({
+ "kind": "skills",
+ "action": "help",
+ "usage": {
+ "slash_command": "/skills [list|install |help| [args]]",
+ "aliases": ["/skill"],
+ "direct_cli": "claw skills [list|install |help| [args]]",
+ "invoke": "/skills help overview -> $help overview",
+ "install_root": "$CLAW_CONFIG_HOME/skills or ~/.claw/skills",
+ "sources": [
+ ".claw/skills",
+ ".omc/skills",
+ ".agents/skills",
+ ".codex/skills",
+ ".claude/skills",
+ "~/.claw/skills",
+ "~/.omc/skills",
+ "~/.claude/skills/omc-learned",
+ "~/.codex/skills",
+ "~/.claude/skills",
+ "legacy /commands",
+ "legacy fallback dirs still load automatically"
+ ],
+ },
+ "unexpected": unexpected,
+ })
+}
+
fn render_mcp_usage(unexpected: Option<&str>) -> String {
let mut lines = vec![
"MCP".to_string(),
@@ -3076,6 +3648,19 @@ fn render_mcp_usage(unexpected: Option<&str>) -> String {
lines.join("\n")
}
+fn render_mcp_usage_json(unexpected: Option<&str>) -> Value {
+ json!({
+ "kind": "mcp",
+ "action": "help",
+ "usage": {
+ "slash_command": "/mcp [list|show |help]",
+ "direct_cli": "claw mcp [list|show |help]",
+ "sources": [".claw/settings.json", ".claw/settings.local.json"],
+ },
+ "unexpected": unexpected,
+ })
+}
+
fn config_source_label(source: ConfigSource) -> &'static str {
match source {
ConfigSource::User => "user",
@@ -3152,6 +3737,138 @@ fn format_mcp_oauth(oauth: Option<&McpOAuthConfig>) -> String {
}
}
+fn definition_source_id(source: DefinitionSource) -> &'static str {
+ match source {
+ DefinitionSource::ProjectClaw
+ | DefinitionSource::ProjectCodex
+ | DefinitionSource::ProjectClaude => "project_claw",
+ DefinitionSource::UserClawConfigHome | DefinitionSource::UserCodexHome => {
+ "user_claw_config_home"
+ }
+ DefinitionSource::UserClaw | DefinitionSource::UserCodex | DefinitionSource::UserClaude => {
+ "user_claw"
+ }
+ }
+}
+
+fn definition_source_json(source: DefinitionSource) -> Value {
+ json!({
+ "id": definition_source_id(source),
+ "label": source.label(),
+ })
+}
+
+fn agent_summary_json(agent: &AgentSummary) -> Value {
+ json!({
+ "name": &agent.name,
+ "description": &agent.description,
+ "model": &agent.model,
+ "reasoning_effort": &agent.reasoning_effort,
+ "source": definition_source_json(agent.source),
+ "active": agent.shadowed_by.is_none(),
+ "shadowed_by": agent.shadowed_by.map(definition_source_json),
+ })
+}
+
+fn skill_origin_id(origin: SkillOrigin) -> &'static str {
+ match origin {
+ SkillOrigin::SkillsDir => "skills_dir",
+ SkillOrigin::LegacyCommandsDir => "legacy_commands_dir",
+ }
+}
+
+fn skill_origin_json(origin: SkillOrigin) -> Value {
+ json!({
+ "id": skill_origin_id(origin),
+ "detail_label": origin.detail_label(),
+ })
+}
+
+fn skill_summary_json(skill: &SkillSummary) -> Value {
+ json!({
+ "name": &skill.name,
+ "description": &skill.description,
+ "source": definition_source_json(skill.source),
+ "origin": skill_origin_json(skill.origin),
+ "active": skill.shadowed_by.is_none(),
+ "shadowed_by": skill.shadowed_by.map(definition_source_json),
+ })
+}
+
+fn config_source_id(source: ConfigSource) -> &'static str {
+ match source {
+ ConfigSource::User => "user",
+ ConfigSource::Project => "project",
+ ConfigSource::Local => "local",
+ }
+}
+
+fn config_source_json(source: ConfigSource) -> Value {
+ json!({
+ "id": config_source_id(source),
+ "label": config_source_label(source),
+ })
+}
+
+fn mcp_transport_json(config: &McpServerConfig) -> Value {
+ let label = mcp_transport_label(config);
+ json!({
+ "id": label,
+ "label": label,
+ })
+}
+
+fn mcp_oauth_json(oauth: Option<&McpOAuthConfig>) -> Value {
+ let Some(oauth) = oauth else {
+ return Value::Null;
+ };
+ json!({
+ "client_id": &oauth.client_id,
+ "callback_port": oauth.callback_port,
+ "auth_server_metadata_url": &oauth.auth_server_metadata_url,
+ "xaa": oauth.xaa,
+ })
+}
+
+fn mcp_server_details_json(config: &McpServerConfig) -> Value {
+ match config {
+ McpServerConfig::Stdio(config) => json!({
+ "command": &config.command,
+ "args": &config.args,
+ "env_keys": config.env.keys().cloned().collect::>(),
+ "tool_call_timeout_ms": config.tool_call_timeout_ms,
+ }),
+ McpServerConfig::Sse(config) | McpServerConfig::Http(config) => json!({
+ "url": &config.url,
+ "header_keys": config.headers.keys().cloned().collect::>(),
+ "headers_helper": &config.headers_helper,
+ "oauth": mcp_oauth_json(config.oauth.as_ref()),
+ }),
+ McpServerConfig::Ws(config) => json!({
+ "url": &config.url,
+ "header_keys": config.headers.keys().cloned().collect::>(),
+ "headers_helper": &config.headers_helper,
+ }),
+ McpServerConfig::Sdk(config) => json!({
+ "name": &config.name,
+ }),
+ McpServerConfig::ManagedProxy(config) => json!({
+ "url": &config.url,
+ "id": &config.id,
+ }),
+ }
+}
+
+fn mcp_server_json(name: &str, server: &ScopedMcpServerConfig) -> Value {
+ json!({
+ "name": name,
+ "scope": config_source_json(server.scope),
+ "transport": mcp_transport_json(&server.config),
+ "summary": mcp_server_summary(&server.config),
+ "details": mcp_server_details_json(&server.config),
+ })
+}
+
#[must_use]
pub fn handle_slash_command(
input: &str,
@@ -3254,6 +3971,7 @@ pub fn handle_slash_command(
| SlashCommand::Tag { .. }
| SlashCommand::OutputStyle { .. }
| SlashCommand::AddDir { .. }
+ | SlashCommand::History { .. }
| SlashCommand::Unknown(_) => None,
}
}
@@ -3261,18 +3979,23 @@ pub fn handle_slash_command(
#[cfg(test)]
mod tests {
use super::{
- handle_plugins_slash_command, handle_slash_command, load_agents_from_roots,
- load_skills_from_roots, render_agents_report, render_plugins_report, render_skills_report,
- render_slash_command_help, render_slash_command_help_detail,
- resume_supported_slash_commands, slash_command_specs, suggest_slash_commands,
- validate_slash_command_input, DefinitionSource, SkillOrigin, SkillRoot, SlashCommand,
+ classify_skills_slash_command, handle_agents_slash_command_json,
+ handle_plugins_slash_command, handle_skills_slash_command_json, handle_slash_command,
+ load_agents_from_roots, load_skills_from_roots, render_agents_report,
+ render_agents_report_json, render_mcp_report_json_for, render_plugins_report,
+ render_skills_report, render_slash_command_help, render_slash_command_help_detail,
+ resolve_skill_path, resume_supported_slash_commands, slash_command_specs,
+ suggest_slash_commands, validate_slash_command_input, DefinitionSource, SkillOrigin,
+ SkillRoot, SkillSlashDispatch, SlashCommand,
};
use plugins::{PluginKind, PluginManager, PluginManagerConfig, PluginMetadata, PluginSummary};
use runtime::{
CompactionConfig, ConfigLoader, ContentBlock, ConversationMessage, MessageRole, Session,
};
+ use std::ffi::OsString;
use std::fs;
use std::path::{Path, PathBuf};
+ use std::sync::{Mutex, OnceLock};
use std::time::{SystemTime, UNIX_EPOCH};
fn temp_dir(label: &str) -> PathBuf {
@@ -3283,6 +4006,18 @@ mod tests {
std::env::temp_dir().join(format!("commands-plugin-{label}-{nanos}"))
}
+ fn env_lock() -> &'static Mutex<()> {
+ static LOCK: OnceLock> = OnceLock::new();
+ LOCK.get_or_init(|| Mutex::new(()))
+ }
+
+ fn restore_env_var(key: &str, original: Option) {
+ match original {
+ Some(value) => std::env::set_var(key, value),
+ None => std::env::remove_var(key),
+ }
+ }
+
fn write_external_plugin(root: &Path, name: &str, version: &str) {
fs::create_dir_all(root.join(".claude-plugin")).expect("manifest dir");
fs::write(
@@ -3551,6 +4286,47 @@ mod tests {
);
}
+ #[test]
+ fn parses_history_command_without_count() {
+ // given
+ let input = "/history";
+
+ // when
+ let parsed = SlashCommand::parse(input);
+
+ // then
+ assert_eq!(parsed, Ok(Some(SlashCommand::History { count: None })));
+ }
+
+ #[test]
+ fn parses_history_command_with_numeric_count() {
+ // given
+ let input = "/history 25";
+
+ // when
+ let parsed = SlashCommand::parse(input);
+
+ // then
+ assert_eq!(
+ parsed,
+ Ok(Some(SlashCommand::History {
+ count: Some("25".to_string())
+ }))
+ );
+ }
+
+ #[test]
+ fn rejects_history_with_extra_arguments() {
+ // given
+ let input = "/history 25 extra";
+
+ // when
+ let error = parse_error_message(input);
+
+ // then
+ assert!(error.contains("Usage: /history [count]"));
+ }
+
#[test]
fn rejects_unexpected_arguments_for_no_arg_commands() {
// given
@@ -3592,7 +4368,7 @@ mod tests {
// then
assert!(error.contains("Usage: /teleport "));
- assert!(error.contains(" Category Discovery & debugging"));
+ assert!(error.contains(" Category Tools"));
}
#[test]
@@ -3613,24 +4389,40 @@ mod tests {
}
#[test]
- fn rejects_invalid_agents_and_skills_arguments() {
+ fn rejects_invalid_agents_arguments() {
// given
let agents_input = "/agents show planner";
- let skills_input = "/skills show help";
// when
let agents_error = parse_error_message(agents_input);
- let skills_error = parse_error_message(skills_input);
// then
assert!(agents_error.contains(
"Unexpected arguments for /agents: show planner. Use /agents, /agents list, or /agents help."
));
assert!(agents_error.contains(" Usage /agents [list|help]"));
- assert!(skills_error.contains(
- "Unexpected arguments for /skills: show help. Use /skills, /skills list, /skills install , or /skills help."
- ));
- assert!(skills_error.contains(" Usage /skills [list|install |help]"));
+ }
+
+ #[test]
+ fn accepts_skills_invocation_arguments_for_prompt_dispatch() {
+ assert_eq!(
+ SlashCommand::parse("/skills help overview"),
+ Ok(Some(SlashCommand::Skills {
+ args: Some("help overview".to_string()),
+ }))
+ );
+ assert_eq!(
+ classify_skills_slash_command(Some("help overview")),
+ SkillSlashDispatch::Invoke("$help overview".to_string())
+ );
+ assert_eq!(
+ classify_skills_slash_command(Some("/test")),
+ SkillSlashDispatch::Invoke("$test".to_string())
+ );
+ assert_eq!(
+ classify_skills_slash_command(Some("install ./skill-pack")),
+ SkillSlashDispatch::Local
+ );
}
#[test]
@@ -3650,10 +4442,10 @@ mod tests {
let help = render_slash_command_help();
assert!(help.contains("Start here /status, /diff, /agents, /skills, /commit"));
assert!(help.contains("[resume] also works with --resume SESSION.jsonl"));
- assert!(help.contains("Session & visibility"));
- assert!(help.contains("Workspace & git"));
- assert!(help.contains("Discovery & debugging"));
- assert!(help.contains("Analysis & automation"));
+ assert!(help.contains("Session"));
+ assert!(help.contains("Tools"));
+ assert!(help.contains("Config"));
+ assert!(help.contains("Debug"));
assert!(help.contains("/help"));
assert!(help.contains("/status"));
assert!(help.contains("/sandbox"));
@@ -3684,11 +4476,59 @@ mod tests {
));
assert!(help.contains("aliases: /plugins, /marketplace"));
assert!(help.contains("/agents [list|help]"));
- assert!(help.contains("/skills [list|install |help]"));
+ assert!(help.contains("/skills [list|install |help| [args]]"));
+ assert!(help.contains("aliases: /skill"));
assert_eq!(slash_command_specs().len(), 141);
assert!(resume_supported_slash_commands().len() >= 39);
}
+ #[test]
+ fn renders_help_with_grouped_categories_and_keyboard_shortcuts() {
+ // given
+ let categories = ["Session", "Tools", "Config", "Debug"];
+
+ // when
+ let help = render_slash_command_help();
+
+ // then
+ for category in categories {
+ assert!(
+ help.contains(category),
+ "expected help to contain category {category}"
+ );
+ }
+ let session_index = help.find("Session").expect("Session header should exist");
+ let tools_index = help.find("Tools").expect("Tools header should exist");
+ let config_index = help.find("Config").expect("Config header should exist");
+ let debug_index = help.find("Debug").expect("Debug header should exist");
+ assert!(session_index < tools_index);
+ assert!(tools_index < config_index);
+ assert!(config_index < debug_index);
+
+ assert!(help.contains("Keyboard shortcuts"));
+ assert!(help.contains("Up/Down Navigate prompt history"));
+ assert!(help.contains("Tab Complete commands, modes, and recent sessions"));
+ assert!(help.contains("Ctrl-C Clear input (or exit on empty prompt)"));
+ assert!(help.contains("Shift+Enter/Ctrl+J Insert a newline"));
+
+ // every command should still render with a summary line
+ for spec in slash_command_specs() {
+ let usage = match spec.argument_hint {
+ Some(hint) => format!("/{} {hint}", spec.name),
+ None => format!("/{}", spec.name),
+ };
+ assert!(
+ help.contains(&usage),
+ "expected help to contain command {usage}"
+ );
+ assert!(
+ help.contains(spec.summary),
+ "expected help to contain summary for /{}",
+ spec.name
+ );
+ }
+ }
+
#[test]
fn renders_per_command_help_detail() {
// given
@@ -3701,7 +4541,7 @@ mod tests {
assert!(help.contains("/plugin"));
assert!(help.contains("Summary Manage Claw Code plugins"));
assert!(help.contains("Aliases /plugins, /marketplace"));
- assert!(help.contains("Category Workspace & git"));
+ assert!(help.contains("Category Tools"));
}
#[test]
@@ -3709,7 +4549,7 @@ mod tests {
let help = render_slash_command_help_detail("mcp").expect("detail help should exist");
assert!(help.contains("/mcp"));
assert!(help.contains("Summary Inspect configured MCP servers"));
- assert!(help.contains("Category Discovery & debugging"));
+ assert!(help.contains("Category Tools"));
assert!(help.contains("Resume Supported with --resume SESSION.jsonl"));
}
@@ -3894,7 +4734,7 @@ mod tests {
let workspace = temp_dir("agents-workspace");
let project_agents = workspace.join(".codex").join("agents");
let user_home = temp_dir("agents-home");
- let user_agents = user_home.join(".codex").join("agents");
+ let user_agents = user_home.join(".claude").join("agents");
write_agent(
&project_agents,
@@ -3927,16 +4767,82 @@ mod tests {
assert!(report.contains("Agents"));
assert!(report.contains("2 active agents"));
- assert!(report.contains("Project (.codex):"));
+ assert!(report.contains("Project roots:"));
assert!(report.contains("planner · Project planner · gpt-5.4 · medium"));
- assert!(report.contains("User (~/.codex):"));
- assert!(report.contains("(shadowed by Project (.codex)) planner · User planner"));
+ assert!(report.contains("User home roots:"));
+ assert!(report.contains("(shadowed by Project roots) planner · User planner"));
assert!(report.contains("verifier · Verification agent · gpt-5.4-mini · high"));
let _ = fs::remove_dir_all(workspace);
let _ = fs::remove_dir_all(user_home);
}
+ #[test]
+ fn renders_agents_reports_as_json() {
+ let workspace = temp_dir("agents-json-workspace");
+ let project_agents = workspace.join(".codex").join("agents");
+ let user_home = temp_dir("agents-json-home");
+ let user_agents = user_home.join(".codex").join("agents");
+
+ write_agent(
+ &project_agents,
+ "planner",
+ "Project planner",
+ "gpt-5.4",
+ "medium",
+ );
+ write_agent(
+ &project_agents,
+ "verifier",
+ "Verification agent",
+ "gpt-5.4-mini",
+ "high",
+ );
+ write_agent(
+ &user_agents,
+ "planner",
+ "User planner",
+ "gpt-5.4-mini",
+ "high",
+ );
+
+ let roots = vec![
+ (DefinitionSource::ProjectCodex, project_agents),
+ (DefinitionSource::UserCodex, user_agents),
+ ];
+ let report = render_agents_report_json(
+ &workspace,
+ &load_agents_from_roots(&roots).expect("agent roots should load"),
+ );
+
+ assert_eq!(report["kind"], "agents");
+ assert_eq!(report["action"], "list");
+ assert_eq!(report["working_directory"], workspace.display().to_string());
+ assert_eq!(report["count"], 3);
+ assert_eq!(report["summary"]["active"], 2);
+ assert_eq!(report["summary"]["shadowed"], 1);
+ assert_eq!(report["agents"][0]["name"], "planner");
+ assert_eq!(report["agents"][0]["model"], "gpt-5.4");
+ assert_eq!(report["agents"][0]["active"], true);
+ assert_eq!(report["agents"][1]["name"], "verifier");
+ assert_eq!(report["agents"][2]["name"], "planner");
+ assert_eq!(report["agents"][2]["active"], false);
+ assert_eq!(report["agents"][2]["shadowed_by"]["id"], "project_claw");
+
+ let help = handle_agents_slash_command_json(Some("help"), &workspace).expect("agents help");
+ assert_eq!(help["kind"], "agents");
+ assert_eq!(help["action"], "help");
+ assert_eq!(help["usage"]["direct_cli"], "claw agents [list|help]");
+
+ let unexpected = handle_agents_slash_command_json(Some("show planner"), &workspace)
+ .expect("agents usage");
+ assert_eq!(unexpected["action"], "help");
+ assert_eq!(unexpected["unexpected"], "show planner");
+
+ let _ = fs::remove_dir_all(workspace);
+ let _ = fs::remove_dir_all(user_home);
+ }
+
#[test]
fn lists_skills_from_project_and_user_roots() {
let workspace = temp_dir("skills-workspace");
@@ -3972,18 +4878,92 @@ mod tests {
assert!(report.contains("Skills"));
assert!(report.contains("3 available skills"));
- assert!(report.contains("Project (.codex):"));
+ assert!(report.contains("Project roots:"));
assert!(report.contains("plan · Project planning guidance"));
- assert!(report.contains("Project (.claude):"));
assert!(report.contains("deploy · Legacy deployment guidance · legacy /commands"));
- assert!(report.contains("User (~/.codex):"));
- assert!(report.contains("(shadowed by Project (.codex)) plan · User planning guidance"));
+ assert!(report.contains("User home roots:"));
+ assert!(report.contains("(shadowed by Project roots) plan · User planning guidance"));
assert!(report.contains("help · Help guidance"));
let _ = fs::remove_dir_all(workspace);
let _ = fs::remove_dir_all(user_home);
}
+ #[test]
+ fn resolves_project_skills_and_legacy_commands_from_shared_registry() {
+ let workspace = temp_dir("resolve-project-skills");
+ let project_skills = workspace.join(".claw").join("skills");
+ let legacy_commands = workspace.join(".claw").join("commands");
+
+ write_skill(&project_skills, "plan", "Project planning guidance");
+ write_legacy_command(&legacy_commands, "handoff", "Legacy handoff guidance");
+
+ assert_eq!(
+ resolve_skill_path(&workspace, "$plan").expect("project skill should resolve"),
+ project_skills.join("plan").join("SKILL.md")
+ );
+ assert_eq!(
+ resolve_skill_path(&workspace, "/handoff").expect("legacy command should resolve"),
+ legacy_commands.join("handoff.md")
+ );
+ }
+
+ #[test]
+ fn renders_skills_reports_as_json() {
+ let workspace = temp_dir("skills-json-workspace");
+ let project_skills = workspace.join(".codex").join("skills");
+ let project_commands = workspace.join(".claude").join("commands");
+ let user_home = temp_dir("skills-json-home");
+ let user_skills = user_home.join(".codex").join("skills");
+
+ write_skill(&project_skills, "plan", "Project planning guidance");
+ write_legacy_command(&project_commands, "deploy", "Legacy deployment guidance");
+ write_skill(&user_skills, "plan", "User planning guidance");
+ write_skill(&user_skills, "help", "Help guidance");
+
+ let roots = vec![
+ SkillRoot {
+ source: DefinitionSource::ProjectCodex,
+ path: project_skills,
+ origin: SkillOrigin::SkillsDir,
+ },
+ SkillRoot {
+ source: DefinitionSource::ProjectClaude,
+ path: project_commands,
+ origin: SkillOrigin::LegacyCommandsDir,
+ },
+ SkillRoot {
+ source: DefinitionSource::UserCodex,
+ path: user_skills,
+ origin: SkillOrigin::SkillsDir,
+ },
+ ];
+ let report = super::render_skills_report_json(
+ &load_skills_from_roots(&roots).expect("skills should load"),
+ );
+ assert_eq!(report["kind"], "skills");
+ assert_eq!(report["action"], "list");
+ assert_eq!(report["summary"]["active"], 3);
+ assert_eq!(report["summary"]["shadowed"], 1);
+ assert_eq!(report["skills"][0]["name"], "plan");
+ assert_eq!(report["skills"][0]["source"]["id"], "project_claw");
+ assert_eq!(report["skills"][1]["name"], "deploy");
+ assert_eq!(report["skills"][1]["origin"]["id"], "legacy_commands_dir");
+ assert_eq!(report["skills"][3]["shadowed_by"]["id"], "project_claw");
+
+ let help = handle_skills_slash_command_json(Some("help"), &workspace).expect("skills help");
+ assert_eq!(help["kind"], "skills");
+ assert_eq!(help["action"], "help");
+ assert_eq!(help["usage"]["aliases"][0], "/skill");
+ assert_eq!(
+ help["usage"]["direct_cli"],
+ "claw skills [list|install |help| [args]]"
+ );
+
+ let _ = fs::remove_dir_all(workspace);
+ let _ = fs::remove_dir_all(user_home);
+ }
+
#[test]
fn agents_and_skills_usage_support_help_and_unexpected_args() {
let cwd = temp_dir("slash-usage");
@@ -3992,6 +4972,8 @@ mod tests {
super::handle_agents_slash_command(Some("help"), &cwd).expect("agents help");
assert!(agents_help.contains("Usage /agents [list|help]"));
assert!(agents_help.contains("Direct CLI claw agents"));
+ assert!(agents_help
+ .contains("Sources .claw/agents, ~/.claw/agents, $CLAW_CONFIG_HOME/agents"));
let agents_unexpected =
super::handle_agents_slash_command(Some("show planner"), &cwd).expect("agents usage");
@@ -3999,17 +4981,114 @@ mod tests {
let skills_help =
super::handle_skills_slash_command(Some("--help"), &cwd).expect("skills help");
- assert!(skills_help.contains("Usage /skills [list|install |help]"));
- assert!(skills_help.contains("Install root $CODEX_HOME/skills or ~/.codex/skills"));
+ assert!(skills_help
+ .contains("Usage /skills [list|install |help| [args]]"));
+ assert!(skills_help.contains("Alias /skill"));
+ assert!(skills_help.contains("Invoke /skills help overview -> $help overview"));
+ assert!(skills_help.contains("Install root $CLAW_CONFIG_HOME/skills or ~/.claw/skills"));
+ assert!(skills_help.contains(".omc/skills"));
+ assert!(skills_help.contains(".agents/skills"));
+ assert!(skills_help.contains("~/.claude/skills/omc-learned"));
assert!(skills_help.contains("legacy /commands"));
let skills_unexpected =
super::handle_skills_slash_command(Some("show help"), &cwd).expect("skills usage");
- assert!(skills_unexpected.contains("Unexpected show help"));
+ assert!(skills_unexpected.contains("Unexpected show"));
+
+ let skills_install_help = super::handle_skills_slash_command(Some("install --help"), &cwd)
+ .expect("nested skills help");
+ assert!(skills_install_help
+ .contains("Usage /skills [list|install |help| [args]]"));
+ assert!(skills_install_help.contains("Alias /skill"));
+ assert!(skills_install_help.contains("Unexpected install"));
+
+ let skills_unknown_help =
+ super::handle_skills_slash_command(Some("show --help"), &cwd).expect("skills help");
+ assert!(skills_unknown_help
+ .contains("Usage /skills [list|install |help| [args]]"));
+ assert!(skills_unknown_help.contains("Unexpected show"));
+
+ let skills_help_json =
+ super::handle_skills_slash_command_json(Some("help"), &cwd).expect("skills help json");
+ let sources = skills_help_json["usage"]["sources"]
+ .as_array()
+ .expect("skills help sources");
+ assert_eq!(skills_help_json["usage"]["aliases"][0], "/skill");
+ assert!(sources.iter().any(|value| value == ".omc/skills"));
+ assert!(sources.iter().any(|value| value == ".agents/skills"));
+ assert!(sources.iter().any(|value| value == "~/.omc/skills"));
+ assert!(sources
+ .iter()
+ .any(|value| value == "~/.claude/skills/omc-learned"));
let _ = fs::remove_dir_all(cwd);
}
+ #[test]
+ fn discovers_omc_skills_from_project_and_user_compatibility_roots() {
+ let _guard = env_lock().lock().expect("env lock");
+ let workspace = temp_dir("skills-omc-workspace");
+ let user_home = temp_dir("skills-omc-home");
+ let claude_config_dir = temp_dir("skills-omc-claude-config");
+ let project_omc_skills = workspace.join(".omc").join("skills");
+ let project_agents_skills = workspace.join(".agents").join("skills");
+ let user_omc_skills = user_home.join(".omc").join("skills");
+ let claude_config_skills = claude_config_dir.join("skills");
+ let claude_config_commands = claude_config_dir.join("commands");
+ let learned_skills = claude_config_dir.join("skills").join("omc-learned");
+ let original_home = std::env::var_os("HOME");
+ let original_claude_config_dir = std::env::var_os("CLAUDE_CONFIG_DIR");
+
+ write_skill(&project_omc_skills, "hud", "OMC HUD guidance");
+ write_skill(
+ &project_agents_skills,
+ "trace",
+ "Compatibility skill guidance",
+ );
+ write_skill(&user_omc_skills, "cancel", "OMC cancel guidance");
+ write_skill(
+ &claude_config_skills,
+ "statusline",
+ "Claude config skill guidance",
+ );
+ write_legacy_command(
+ &claude_config_commands,
+ "doctor-check",
+ "Claude config command guidance",
+ );
+ write_skill(&learned_skills, "learned", "Learned skill guidance");
+ std::env::set_var("HOME", &user_home);
+ std::env::set_var("CLAUDE_CONFIG_DIR", &claude_config_dir);
+
+ let report = super::handle_skills_slash_command(None, &workspace).expect("skills list");
+ assert!(report.contains("available skills"));
+ assert!(report.contains("hud · OMC HUD guidance"));
+ assert!(report.contains("trace · Compatibility skill guidance"));
+ assert!(report.contains("cancel · OMC cancel guidance"));
+ assert!(report.contains("statusline · Claude config skill guidance"));
+ assert!(report.contains("doctor-check · Claude config command guidance · legacy /commands"));
+ assert!(report.contains("learned · Learned skill guidance"));
+
+ let help =
+ super::handle_skills_slash_command_json(Some("help"), &workspace).expect("skills help");
+ let sources = help["usage"]["sources"]
+ .as_array()
+ .expect("skills help sources");
+ assert_eq!(help["usage"]["aliases"][0], "/skill");
+ assert!(sources.iter().any(|value| value == ".omc/skills"));
+ assert!(sources.iter().any(|value| value == ".agents/skills"));
+ assert!(sources.iter().any(|value| value == "~/.omc/skills"));
+ assert!(sources
+ .iter()
+ .any(|value| value == "~/.claude/skills/omc-learned"));
+
+ restore_env_var("HOME", original_home);
+ restore_env_var("CLAUDE_CONFIG_DIR", original_claude_config_dir);
+ let _ = fs::remove_dir_all(workspace);
+ let _ = fs::remove_dir_all(user_home);
+ let _ = fs::remove_dir_all(claude_config_dir);
+ }
+
#[test]
fn mcp_usage_supports_help_and_unexpected_args() {
let cwd = temp_dir("mcp-usage");
@@ -4022,6 +5101,16 @@ mod tests {
super::handle_mcp_slash_command(Some("show alpha beta"), &cwd).expect("mcp usage");
assert!(unexpected.contains("Unexpected show alpha beta"));
+ let nested_help =
+ super::handle_mcp_slash_command(Some("show --help"), &cwd).expect("mcp help");
+ assert!(nested_help.contains("Usage /mcp [list|show |help]"));
+ assert!(nested_help.contains("Unexpected show"));
+
+ let unknown_help =
+ super::handle_mcp_slash_command(Some("inspect --help"), &cwd).expect("mcp usage");
+ assert!(unknown_help.contains("Usage /mcp [list|show |help]"));
+ assert!(unknown_help.contains("Unexpected inspect"));
+
let _ = fs::remove_dir_all(cwd);
}
@@ -4102,6 +5191,88 @@ mod tests {
let _ = fs::remove_dir_all(config_home);
}
+ #[test]
+ fn renders_mcp_reports_as_json() {
+ let workspace = temp_dir("mcp-json-workspace");
+ let config_home = temp_dir("mcp-json-home");
+ fs::create_dir_all(workspace.join(".claw")).expect("workspace config dir");
+ fs::create_dir_all(&config_home).expect("config home");
+ fs::write(
+ workspace.join(".claw").join("settings.json"),
+ r#"{
+ "mcpServers": {
+ "alpha": {
+ "command": "uvx",
+ "args": ["alpha-server"],
+ "env": {"ALPHA_TOKEN": "secret"},
+ "toolCallTimeoutMs": 1200
+ },
+ "remote": {
+ "type": "http",
+ "url": "https://remote.example/mcp",
+ "headers": {"Authorization": "Bearer secret"},
+ "headersHelper": "./bin/headers",
+ "oauth": {
+ "clientId": "remote-client",
+ "callbackPort": 7878
+ }
+ }
+ }
+ }"#,
+ )
+ .expect("write settings");
+ fs::write(
+ workspace.join(".claw").join("settings.local.json"),
+ r#"{
+ "mcpServers": {
+ "remote": {
+ "type": "ws",
+ "url": "wss://remote.example/mcp"
+ }
+ }
+ }"#,
+ )
+ .expect("write local settings");
+
+ let loader = ConfigLoader::new(&workspace, &config_home);
+ let list =
+ render_mcp_report_json_for(&loader, &workspace, None).expect("mcp list json render");
+ assert_eq!(list["kind"], "mcp");
+ assert_eq!(list["action"], "list");
+ assert_eq!(list["configured_servers"], 2);
+ assert_eq!(list["servers"][0]["name"], "alpha");
+ assert_eq!(list["servers"][0]["transport"]["id"], "stdio");
+ assert_eq!(list["servers"][0]["details"]["command"], "uvx");
+ assert_eq!(list["servers"][1]["name"], "remote");
+ assert_eq!(list["servers"][1]["scope"]["id"], "local");
+ assert_eq!(list["servers"][1]["transport"]["id"], "ws");
+ assert_eq!(
+ list["servers"][1]["details"]["url"],
+ "wss://remote.example/mcp"
+ );
+
+ let show = render_mcp_report_json_for(&loader, &workspace, Some("show alpha"))
+ .expect("mcp show json render");
+ assert_eq!(show["action"], "show");
+ assert_eq!(show["found"], true);
+ assert_eq!(show["server"]["name"], "alpha");
+ assert_eq!(show["server"]["details"]["env_keys"][0], "ALPHA_TOKEN");
+ assert_eq!(show["server"]["details"]["tool_call_timeout_ms"], 1200);
+
+ let missing = render_mcp_report_json_for(&loader, &workspace, Some("show missing"))
+ .expect("mcp missing json render");
+ assert_eq!(missing["found"], false);
+ assert_eq!(missing["server_name"], "missing");
+
+ let help =
+ render_mcp_report_json_for(&loader, &workspace, Some("help")).expect("mcp help json");
+ assert_eq!(help["action"], "help");
+ assert_eq!(help["usage"]["sources"][0], ".claw/settings.json");
+
+ let _ = fs::remove_dir_all(workspace);
+ let _ = fs::remove_dir_all(config_home);
+ }
+
#[test]
fn parses_quoted_skill_frontmatter_values() {
let contents = "---\nname: \"hud\"\ndescription: 'Quoted description'\n---\n";
@@ -4154,7 +5325,7 @@ mod tests {
let listed = render_skills_report(
&load_skills_from_roots(&roots).expect("installed skills should load"),
);
- assert!(listed.contains("User ($CODEX_HOME):"));
+ assert!(listed.contains("User config roots:"));
assert!(listed.contains("help · Helpful skill"));
let _ = fs::remove_dir_all(workspace);
diff --git a/rust/crates/plugins/src/lib.rs b/rust/crates/plugins/src/lib.rs
index 3070d177..052d1bab 100644
--- a/rust/crates/plugins/src/lib.rs
+++ b/rust/crates/plugins/src/lib.rs
@@ -920,6 +920,9 @@ pub enum PluginManifestValidationError {
tool_name: String,
permission: String,
},
+ UnsupportedManifestContract {
+ detail: String,
+ },
}
impl Display for PluginManifestValidationError {
@@ -965,6 +968,7 @@ impl Display for PluginManifestValidationError {
f,
"plugin tool `{tool_name}` requiredPermission `{permission}` must be read-only, workspace-write, or danger-full-access"
),
+ Self::UnsupportedManifestContract { detail } => f.write_str(detail),
}
}
}
@@ -1594,10 +1598,73 @@ fn load_manifest_from_path(
manifest_path.display()
))
})?;
- let raw_manifest: RawPluginManifest = serde_json::from_str(&contents)?;
+ let raw_json: Value = serde_json::from_str(&contents)?;
+ let compatibility_errors = detect_claude_code_manifest_contract_gaps(&raw_json);
+ if !compatibility_errors.is_empty() {
+ return Err(PluginError::ManifestValidation(compatibility_errors));
+ }
+ let raw_manifest: RawPluginManifest = serde_json::from_value(raw_json)?;
build_plugin_manifest(root, raw_manifest)
}
+fn detect_claude_code_manifest_contract_gaps(
+ raw_manifest: &Value,
+) -> Vec {
+ let Some(root) = raw_manifest.as_object() else {
+ return Vec::new();
+ };
+
+ let mut errors = Vec::new();
+
+ for (field, detail) in [
+ (
+ "skills",
+ "plugin manifest field `skills` uses the Claude Code plugin contract; `claw` does not load plugin-managed skills and instead discovers skills from local roots such as `.claw/skills`, `.omc/skills`, `.agents/skills`, `~/.omc/skills`, and `~/.claude/skills/omc-learned`.",
+ ),
+ (
+ "mcpServers",
+ "plugin manifest field `mcpServers` uses the Claude Code plugin contract; `claw` does not import MCP servers from plugin manifests.",
+ ),
+ (
+ "agents",
+ "plugin manifest field `agents` uses the Claude Code plugin contract; `claw` does not load plugin-managed agent markdown catalogs from plugin manifests.",
+ ),
+ ] {
+ if root.contains_key(field) {
+ errors.push(PluginManifestValidationError::UnsupportedManifestContract {
+ detail: detail.to_string(),
+ });
+ }
+ }
+
+ if root
+ .get("commands")
+ .and_then(Value::as_array)
+ .is_some_and(|commands| commands.iter().any(Value::is_string))
+ {
+ errors.push(PluginManifestValidationError::UnsupportedManifestContract {
+ detail: "plugin manifest field `commands` uses Claude Code-style directory globs; `claw` slash dispatch is still built-in and does not load plugin slash command markdown files.".to_string(),
+ });
+ }
+
+ if let Some(hooks) = root.get("hooks").and_then(Value::as_object) {
+ for hook_name in hooks.keys() {
+ if !matches!(
+ hook_name.as_str(),
+ "PreToolUse" | "PostToolUse" | "PostToolUseFailure"
+ ) {
+ errors.push(PluginManifestValidationError::UnsupportedManifestContract {
+ detail: format!(
+ "plugin hook `{hook_name}` uses the Claude Code lifecycle contract; `claw` plugins currently support only PreToolUse, PostToolUse, and PostToolUseFailure."
+ ),
+ });
+ }
+ }
+ }
+
+ errors
+}
+
fn plugin_manifest_path(root: &Path) -> Result {
let direct_path = root.join(MANIFEST_FILE_NAME);
if direct_path.exists() {
@@ -2517,6 +2584,37 @@ mod tests {
let _ = fs::remove_dir_all(root);
}
+ #[test]
+ fn load_plugin_from_directory_rejects_claude_code_manifest_contracts_with_guidance() {
+ let root = temp_dir("manifest-claude-code-contract");
+ write_file(
+ root.join(MANIFEST_FILE_NAME).as_path(),
+ r#"{
+ "name": "oh-my-claudecode",
+ "version": "4.10.2",
+ "description": "Claude Code plugin manifest",
+ "hooks": {
+ "SessionStart": ["scripts/session-start.mjs"]
+ },
+ "agents": ["agents/*.md"],
+ "commands": ["commands/**/*.md"],
+ "skills": "./skills/",
+ "mcpServers": "./.mcp.json"
+}"#,
+ );
+
+ let error = load_plugin_from_directory(&root)
+ .expect_err("Claude Code plugin manifest should fail with guidance");
+ let rendered = error.to_string();
+ assert!(rendered.contains("field `skills` uses the Claude Code plugin contract"));
+ assert!(rendered.contains("field `mcpServers` uses the Claude Code plugin contract"));
+ assert!(rendered.contains("field `agents` uses the Claude Code plugin contract"));
+ assert!(rendered.contains("field `commands` uses Claude Code-style directory globs"));
+ assert!(rendered.contains("hook `SessionStart` uses the Claude Code lifecycle contract"));
+
+ let _ = fs::remove_dir_all(root);
+ }
+
#[test]
fn load_plugin_from_directory_rejects_missing_tool_or_command_paths() {
let root = temp_dir("manifest-paths");
diff --git a/rust/crates/runtime/Cargo.toml b/rust/crates/runtime/Cargo.toml
index 8b692176..b1bd04f3 100644
--- a/rust/crates/runtime/Cargo.toml
+++ b/rust/crates/runtime/Cargo.toml
@@ -13,7 +13,7 @@ regex = "1"
serde = { version = "1", features = ["derive"] }
serde_json.workspace = true
telemetry = { path = "../telemetry" }
-tokio = { version = "1", features = ["io-util", "macros", "process", "rt", "rt-multi-thread", "time"] }
+tokio = { version = "1", features = ["io-std", "io-util", "macros", "process", "rt", "rt-multi-thread", "time"] }
walkdir = "2"
[lints]
diff --git a/rust/crates/runtime/src/branch_lock.rs b/rust/crates/runtime/src/branch_lock.rs
new file mode 100644
index 00000000..6fbf0d09
--- /dev/null
+++ b/rust/crates/runtime/src/branch_lock.rs
@@ -0,0 +1,144 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchLockIntent {
+ #[serde(rename = "laneId")]
+ pub lane_id: String,
+ pub branch: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub worktree: Option,
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub modules: Vec,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchLockCollision {
+ pub branch: String,
+ pub module: String,
+ #[serde(rename = "laneIds")]
+ pub lane_ids: Vec,
+}
+
+#[must_use]
+pub fn detect_branch_lock_collisions(intents: &[BranchLockIntent]) -> Vec {
+ let mut collisions = Vec::new();
+
+ for (index, left) in intents.iter().enumerate() {
+ for right in &intents[index + 1..] {
+ if left.branch != right.branch {
+ continue;
+ }
+ for module in overlapping_modules(&left.modules, &right.modules) {
+ collisions.push(BranchLockCollision {
+ branch: left.branch.clone(),
+ module,
+ lane_ids: vec![left.lane_id.clone(), right.lane_id.clone()],
+ });
+ }
+ }
+ }
+
+ collisions.sort_by(|a, b| {
+ a.branch
+ .cmp(&b.branch)
+ .then(a.module.cmp(&b.module))
+ .then(a.lane_ids.cmp(&b.lane_ids))
+ });
+ collisions.dedup();
+ collisions
+}
+
+fn overlapping_modules(left: &[String], right: &[String]) -> Vec {
+ let mut overlaps = Vec::new();
+ for left_module in left {
+ for right_module in right {
+ if modules_overlap(left_module, right_module) {
+ overlaps.push(shared_scope(left_module, right_module));
+ }
+ }
+ }
+ overlaps.sort();
+ overlaps.dedup();
+ overlaps
+}
+
+fn modules_overlap(left: &str, right: &str) -> bool {
+ left == right
+ || left.starts_with(&format!("{right}/"))
+ || right.starts_with(&format!("{left}/"))
+}
+
+fn shared_scope(left: &str, right: &str) -> String {
+ if left.starts_with(&format!("{right}/")) || left == right {
+ right.to_string()
+ } else {
+ left.to_string()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{detect_branch_lock_collisions, BranchLockIntent};
+
+ #[test]
+ fn detects_same_branch_same_module_collisions() {
+ let collisions = detect_branch_lock_collisions(&[
+ BranchLockIntent {
+ lane_id: "lane-a".to_string(),
+ branch: "feature/lock".to_string(),
+ worktree: Some("wt-a".to_string()),
+ modules: vec!["runtime/mcp".to_string()],
+ },
+ BranchLockIntent {
+ lane_id: "lane-b".to_string(),
+ branch: "feature/lock".to_string(),
+ worktree: Some("wt-b".to_string()),
+ modules: vec!["runtime/mcp".to_string()],
+ },
+ ]);
+
+ assert_eq!(collisions.len(), 1);
+ assert_eq!(collisions[0].branch, "feature/lock");
+ assert_eq!(collisions[0].module, "runtime/mcp");
+ }
+
+ #[test]
+ fn detects_nested_module_scope_collisions() {
+ let collisions = detect_branch_lock_collisions(&[
+ BranchLockIntent {
+ lane_id: "lane-a".to_string(),
+ branch: "feature/lock".to_string(),
+ worktree: None,
+ modules: vec!["runtime".to_string()],
+ },
+ BranchLockIntent {
+ lane_id: "lane-b".to_string(),
+ branch: "feature/lock".to_string(),
+ worktree: None,
+ modules: vec!["runtime/mcp".to_string()],
+ },
+ ]);
+
+ assert_eq!(collisions[0].module, "runtime");
+ }
+
+ #[test]
+ fn ignores_different_branches() {
+ let collisions = detect_branch_lock_collisions(&[
+ BranchLockIntent {
+ lane_id: "lane-a".to_string(),
+ branch: "feature/a".to_string(),
+ worktree: None,
+ modules: vec!["runtime/mcp".to_string()],
+ },
+ BranchLockIntent {
+ lane_id: "lane-b".to_string(),
+ branch: "feature/b".to_string(),
+ worktree: None,
+ modules: vec!["runtime/mcp".to_string()],
+ },
+ ]);
+
+ assert!(collisions.is_empty());
+ }
+}
diff --git a/rust/crates/runtime/src/config.rs b/rust/crates/runtime/src/config.rs
index 3120ac55..70d69b31 100644
--- a/rust/crates/runtime/src/config.rs
+++ b/rust/crates/runtime/src/config.rs
@@ -9,6 +9,27 @@ use crate::sandbox::{FilesystemIsolationMode, SandboxConfig};
/// Schema name advertised by generated settings files.
pub const CLAW_SETTINGS_SCHEMA_NAME: &str = "SettingsSchema";
+/// Top-level settings keys recognized by the runtime configuration loader.
+const KNOWN_TOP_LEVEL_KEYS: &[&str] = &[
+ "$schema",
+ "enabledPlugins",
+ "env",
+ "hooks",
+ "mcpServers",
+ "model",
+ "oauth",
+ "permissionMode",
+ "permissions",
+ "plugins",
+ "sandbox",
+];
+
+/// Deprecated top-level keys mapped to their replacement guidance.
+const DEPRECATED_TOP_LEVEL_KEYS: &[(&str, &str)] = &[
+ ("allowedTools", "permissions.allow"),
+ ("ignorePatterns", "permissions.deny"),
+];
+
/// Origin of a loaded settings file in the configuration precedence chain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ConfigSource {
@@ -48,6 +69,7 @@ pub struct RuntimePluginConfig {
install_root: Option,
registry_path: Option,
bundled_root: Option,
+ max_output_tokens: Option,
}
/// Structured feature configuration consumed by runtime subsystems.
@@ -58,9 +80,20 @@ pub struct RuntimeFeatureConfig {
mcp: McpConfigCollection,
oauth: Option,
model: Option,
+ aliases: BTreeMap,
permission_mode: Option,
permission_rules: RuntimePermissionRuleConfig,
sandbox: SandboxConfig,
+ provider_fallbacks: ProviderFallbackConfig,
+}
+
+/// Ordered chain of fallback model identifiers used when the primary
+/// provider returns a retryable failure (429/500/503/etc.). The chain is
+/// strict: each entry is tried in order until one succeeds.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct ProviderFallbackConfig {
+ primary: Option,
+ fallbacks: Vec,
}
/// Hook command lists grouped by lifecycle stage.
@@ -259,17 +292,33 @@ impl ConfigLoader {
let mut merged = BTreeMap::new();
let mut loaded_entries = Vec::new();
let mut mcp_servers = BTreeMap::new();
+ let mut all_warnings = Vec::new();
for entry in self.discover() {
- let Some(value) = read_optional_json_object(&entry.path)? else {
+ crate::config_validate::check_unsupported_format(&entry.path)?;
+ let Some(parsed) = read_optional_json_object(&entry.path)? else {
continue;
};
- validate_optional_hooks_config(&value, &entry.path)?;
- merge_mcp_servers(&mut mcp_servers, entry.source, &value, &entry.path)?;
- deep_merge_objects(&mut merged, &value);
+ let validation = crate::config_validate::validate_config_file(
+ &parsed.object,
+ &parsed.source,
+ &entry.path,
+ );
+ if !validation.is_ok() {
+ let first_error = &validation.errors[0];
+ return Err(ConfigError::Parse(first_error.to_string()));
+ }
+ all_warnings.extend(validation.warnings);
+ validate_optional_hooks_config(&parsed.object, &entry.path)?;
+ merge_mcp_servers(&mut mcp_servers, entry.source, &parsed.object, &entry.path)?;
+ deep_merge_objects(&mut merged, &parsed.object);
loaded_entries.push(entry);
}
+ for warning in &all_warnings {
+ eprintln!("warning: {warning}");
+ }
+
let merged_value = JsonValue::Object(merged.clone());
let feature_config = RuntimeFeatureConfig {
@@ -280,9 +329,11 @@ impl ConfigLoader {
},
oauth: parse_optional_oauth_config(&merged_value, "merged settings.oauth")?,
model: parse_optional_model(&merged_value),
+ aliases: parse_optional_aliases(&merged_value)?,
permission_mode: parse_optional_permission_mode(&merged_value)?,
permission_rules: parse_optional_permission_rules(&merged_value)?,
sandbox: parse_optional_sandbox_config(&merged_value)?,
+ provider_fallbacks: parse_optional_provider_fallbacks(&merged_value)?,
};
Ok(RuntimeConfig {
@@ -353,6 +404,11 @@ impl RuntimeConfig {
self.feature_config.model.as_deref()
}
+ #[must_use]
+ pub fn aliases(&self) -> &BTreeMap {
+ &self.feature_config.aliases
+ }
+
#[must_use]
pub fn permission_mode(&self) -> Option {
self.feature_config.permission_mode
@@ -367,6 +423,11 @@ impl RuntimeConfig {
pub fn sandbox(&self) -> &SandboxConfig {
&self.feature_config.sandbox
}
+
+ #[must_use]
+ pub fn provider_fallbacks(&self) -> &ProviderFallbackConfig {
+ &self.feature_config.provider_fallbacks
+ }
}
impl RuntimeFeatureConfig {
@@ -407,6 +468,11 @@ impl RuntimeFeatureConfig {
self.model.as_deref()
}
+ #[must_use]
+ pub fn aliases(&self) -> &BTreeMap {
+ &self.aliases
+ }
+
#[must_use]
pub fn permission_mode(&self) -> Option {
self.permission_mode
@@ -421,6 +487,33 @@ impl RuntimeFeatureConfig {
pub fn sandbox(&self) -> &SandboxConfig {
&self.sandbox
}
+
+ #[must_use]
+ pub fn provider_fallbacks(&self) -> &ProviderFallbackConfig {
+ &self.provider_fallbacks
+ }
+}
+
+impl ProviderFallbackConfig {
+ #[must_use]
+ pub fn new(primary: Option, fallbacks: Vec) -> Self {
+ Self { primary, fallbacks }
+ }
+
+ #[must_use]
+ pub fn primary(&self) -> Option<&str> {
+ self.primary.as_deref()
+ }
+
+ #[must_use]
+ pub fn fallbacks(&self) -> &[String] {
+ &self.fallbacks
+ }
+
+ #[must_use]
+ pub fn is_empty(&self) -> bool {
+ self.fallbacks.is_empty()
+ }
}
impl RuntimePluginConfig {
@@ -449,6 +542,15 @@ impl RuntimePluginConfig {
self.bundled_root.as_deref()
}
+ #[must_use]
+ pub fn max_output_tokens(&self) -> Option {
+ self.max_output_tokens
+ }
+
+ pub fn set_max_output_tokens(&mut self, max_output_tokens: Option) {
+ self.max_output_tokens = max_output_tokens;
+ }
+
pub fn set_plugin_state(&mut self, plugin_id: String, enabled: bool) {
self.enabled_plugins.insert(plugin_id, enabled);
}
@@ -572,9 +674,13 @@ impl McpServerConfig {
}
}
-fn read_optional_json_object(
- path: &Path,
-) -> Result>, ConfigError> {
+/// Parsed JSON object paired with its raw source text for validation.
+struct ParsedConfigFile {
+ object: BTreeMap,
+ source: String,
+}
+
+fn read_optional_json_object(path: &Path) -> Result, ConfigError> {
let is_legacy_config = path.file_name().and_then(|name| name.to_str()) == Some(".claw.json");
let contents = match fs::read_to_string(path) {
Ok(contents) => contents,
@@ -583,7 +689,10 @@ fn read_optional_json_object(
};
if contents.trim().is_empty() {
- return Ok(Some(BTreeMap::new()));
+ return Ok(Some(ParsedConfigFile {
+ object: BTreeMap::new(),
+ source: contents,
+ }));
}
let parsed = match JsonValue::parse(&contents) {
@@ -600,7 +709,10 @@ fn read_optional_json_object(
path.display()
)));
};
- Ok(Some(object.clone()))
+ Ok(Some(ParsedConfigFile {
+ object: object.clone(),
+ source: contents,
+ }))
}
fn merge_mcp_servers(
@@ -637,6 +749,13 @@ fn parse_optional_model(root: &JsonValue) -> Option {
.map(ToOwned::to_owned)
}
+fn parse_optional_aliases(root: &JsonValue) -> Result, ConfigError> {
+ let Some(object) = root.as_object() else {
+ return Ok(BTreeMap::new());
+ };
+ Ok(optional_string_map(object, "aliases", "merged settings")?.unwrap_or_default())
+}
+
fn parse_optional_hooks_config(root: &JsonValue) -> Result {
let Some(object) = root.as_object() else {
return Ok(RuntimeHookConfig::default());
@@ -714,6 +833,7 @@ fn parse_optional_plugin_config(root: &JsonValue) -> Result Result Result {
+ let Some(object) = root.as_object() else {
+ return Ok(ProviderFallbackConfig::default());
+ };
+ let Some(value) = object.get("providerFallbacks") else {
+ return Ok(ProviderFallbackConfig::default());
+ };
+ let entry = expect_object(value, "merged settings.providerFallbacks")?;
+ let primary =
+ optional_string(entry, "primary", "merged settings.providerFallbacks")?.map(str::to_string);
+ let fallbacks = optional_string_array(entry, "fallbacks", "merged settings.providerFallbacks")?
+ .unwrap_or_default();
+ Ok(ProviderFallbackConfig { primary, fallbacks })
+}
+
fn parse_filesystem_mode_label(value: &str) -> Result {
match value {
"off" => Ok(FilesystemIsolationMode::Off),
@@ -957,6 +1094,27 @@ fn optional_u16(
}
}
+fn optional_u32(
+ object: &BTreeMap,
+ key: &str,
+ context: &str,
+) -> Result, ConfigError> {
+ match object.get(key) {
+ Some(value) => {
+ let Some(number) = value.as_i64() else {
+ return Err(ConfigError::Parse(format!(
+ "{context}: field {key} must be a non-negative integer"
+ )));
+ };
+ let number = u32::try_from(number).map_err(|_| {
+ ConfigError::Parse(format!("{context}: field {key} is out of range"))
+ })?;
+ Ok(Some(number))
+ }
+ None => Ok(None),
+ }
+}
+
fn optional_u64(
object: &BTreeMap,
key: &str,
@@ -1247,6 +1405,66 @@ mod tests {
fs::remove_dir_all(root).expect("cleanup temp dir");
}
+ #[test]
+ fn parses_provider_fallbacks_chain_with_primary_and_ordered_fallbacks() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::write(
+ home.join("settings.json"),
+ r#"{
+ "providerFallbacks": {
+ "primary": "claude-opus-4-6",
+ "fallbacks": ["grok-3", "grok-3-mini"]
+ }
+ }"#,
+ )
+ .expect("write provider fallback settings");
+
+ // when
+ let loaded = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect("config should load");
+
+ // then
+ let chain = loaded.provider_fallbacks();
+ assert_eq!(chain.primary(), Some("claude-opus-4-6"));
+ assert_eq!(
+ chain.fallbacks(),
+ &["grok-3".to_string(), "grok-3-mini".to_string()]
+ );
+ assert!(!chain.is_empty());
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
+ #[test]
+ fn provider_fallbacks_default_is_empty_when_unset() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::create_dir_all(&cwd).expect("project dir");
+ fs::write(home.join("settings.json"), "{}").expect("write empty settings");
+
+ // when
+ let loaded = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect("config should load");
+
+ // then
+ let chain = loaded.provider_fallbacks();
+ assert_eq!(chain.primary(), None);
+ assert!(chain.fallbacks().is_empty());
+ assert!(chain.is_empty());
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
#[test]
fn parses_typed_mcp_and_oauth_config() {
let root = temp_dir();
@@ -1493,6 +1711,49 @@ mod tests {
fs::remove_dir_all(root).expect("cleanup temp dir");
}
+ #[test]
+ fn parses_user_defined_model_aliases_from_settings() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
+ fs::create_dir_all(&home).expect("home config dir");
+
+ fs::write(
+ home.join("settings.json"),
+ r#"{"aliases":{"fast":"claude-haiku-4-5-20251213","smart":"claude-opus-4-6"}}"#,
+ )
+ .expect("write user settings");
+ fs::write(
+ cwd.join(".claw").join("settings.local.json"),
+ r#"{"aliases":{"smart":"claude-sonnet-4-6","cheap":"grok-3-mini"}}"#,
+ )
+ .expect("write local settings");
+
+ // when
+ let loaded = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect("config should load");
+
+ // then
+ let aliases = loaded.aliases();
+ assert_eq!(
+ aliases.get("fast").map(String::as_str),
+ Some("claude-haiku-4-5-20251213")
+ );
+ assert_eq!(
+ aliases.get("smart").map(String::as_str),
+ Some("claude-sonnet-4-6")
+ );
+ assert_eq!(
+ aliases.get("cheap").map(String::as_str),
+ Some("grok-3-mini")
+ );
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
#[test]
fn empty_settings_file_loads_defaults() {
// given
@@ -1574,12 +1835,13 @@ mod tests {
.load()
.expect_err("config should fail");
- // then
+ // then — config validation now catches the mixed array before the hooks parser
let rendered = error.to_string();
- assert!(rendered.contains(&format!(
- "{}: hooks: field PreToolUse must contain only strings",
- project_settings.display()
- )));
+ assert!(
+ rendered.contains("hooks.PreToolUse")
+ && rendered.contains("must be an array of strings"),
+ "expected validation error for hooks.PreToolUse, got: {rendered}"
+ );
assert!(!rendered.contains("merged settings.hooks"));
fs::remove_dir_all(root).expect("cleanup temp dir");
@@ -1645,4 +1907,140 @@ mod tests {
assert!(config.state_for("missing", true));
assert!(!config.state_for("missing", false));
}
+
+ #[test]
+ fn validates_unknown_top_level_keys_with_line_and_field_name() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ let user_settings = home.join("settings.json");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::create_dir_all(&cwd).expect("project dir");
+ fs::write(
+ &user_settings,
+ "{\n \"model\": \"opus\",\n \"telemetry\": true\n}\n",
+ )
+ .expect("write user settings");
+
+ // when
+ let error = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect_err("config should fail");
+
+ // then
+ let rendered = error.to_string();
+ assert!(
+ rendered.contains(&format!("{}:3:", user_settings.display())),
+ "error should include file path and line number, got: {rendered}"
+ );
+ assert!(
+ rendered.contains("unknown field telemetry"),
+ "error should name the offending field, got: {rendered}"
+ );
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
+ #[test]
+ fn validates_deprecated_top_level_keys_with_replacement_guidance() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ let user_settings = home.join("settings.json");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::create_dir_all(&cwd).expect("project dir");
+ fs::write(
+ &user_settings,
+ "{\n \"model\": \"opus\",\n \"allowedTools\": [\"Read\"]\n}\n",
+ )
+ .expect("write user settings");
+
+ // when
+ let error = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect_err("config should fail");
+
+ // then
+ let rendered = error.to_string();
+ assert!(
+ rendered.contains(&format!("{}:3:", user_settings.display())),
+ "error should include file path and line number, got: {rendered}"
+ );
+ assert!(
+ rendered.contains("deprecated field allowedTools"),
+ "error should call out the deprecated field, got: {rendered}"
+ );
+ assert!(
+ rendered.contains("permissions.allow"),
+ "error should mention the replacement field, got: {rendered}"
+ );
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
+ #[test]
+ fn validates_wrong_type_for_known_field_with_field_path() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ let user_settings = home.join("settings.json");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::create_dir_all(&cwd).expect("project dir");
+ fs::write(
+ &user_settings,
+ "{\n \"hooks\": {\n \"PreToolUse\": \"not-an-array\"\n }\n}\n",
+ )
+ .expect("write user settings");
+
+ // when
+ let error = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect_err("config should fail");
+
+ // then
+ let rendered = error.to_string();
+ assert!(
+ rendered.contains(&format!("{}: hooks", user_settings.display())),
+ "error should include file path and field path, got: {rendered}"
+ );
+ assert!(
+ rendered.contains("PreToolUse must be an array"),
+ "error should describe the type mismatch, got: {rendered}"
+ );
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
+
+ #[test]
+ fn unknown_top_level_key_suggests_closest_match() {
+ // given
+ let root = temp_dir();
+ let cwd = root.join("project");
+ let home = root.join("home").join(".claw");
+ let user_settings = home.join("settings.json");
+ fs::create_dir_all(&home).expect("home config dir");
+ fs::create_dir_all(&cwd).expect("project dir");
+ fs::write(&user_settings, "{\n \"modle\": \"opus\"\n}\n").expect("write user settings");
+
+ // when
+ let error = ConfigLoader::new(&cwd, &home)
+ .load()
+ .expect_err("config should fail");
+
+ // then
+ let rendered = error.to_string();
+ assert!(
+ rendered.contains("unknown field modle"),
+ "error should name the offending field, got: {rendered}"
+ );
+ assert!(
+ rendered.contains("did you mean model?"),
+ "error should suggest the closest known key, got: {rendered}"
+ );
+
+ fs::remove_dir_all(root).expect("cleanup temp dir");
+ }
}
diff --git a/rust/crates/runtime/src/config_validate.rs b/rust/crates/runtime/src/config_validate.rs
new file mode 100644
index 00000000..31ccde1c
--- /dev/null
+++ b/rust/crates/runtime/src/config_validate.rs
@@ -0,0 +1,887 @@
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use crate::config::ConfigError;
+use crate::json::JsonValue;
+
+/// Diagnostic emitted when a config file contains a suspect field.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConfigDiagnostic {
+ pub path: String,
+ pub field: String,
+ pub line: Option,
+ pub kind: DiagnosticKind,
+}
+
+/// Classification of the diagnostic.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DiagnosticKind {
+ UnknownKey {
+ suggestion: Option,
+ },
+ WrongType {
+ expected: &'static str,
+ got: &'static str,
+ },
+ Deprecated {
+ replacement: &'static str,
+ },
+}
+
+impl std::fmt::Display for ConfigDiagnostic {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ let location = self
+ .line
+ .map_or_else(String::new, |line| format!(" (line {line})"));
+ match &self.kind {
+ DiagnosticKind::UnknownKey { suggestion: None } => {
+ write!(f, "{}: unknown key \"{}\"{location}", self.path, self.field)
+ }
+ DiagnosticKind::UnknownKey {
+ suggestion: Some(hint),
+ } => {
+ write!(
+ f,
+ "{}: unknown key \"{}\"{location}. Did you mean \"{}\"?",
+ self.path, self.field, hint
+ )
+ }
+ DiagnosticKind::WrongType { expected, got } => {
+ write!(
+ f,
+ "{}: field \"{}\" must be {expected}, got {got}{location}",
+ self.path, self.field
+ )
+ }
+ DiagnosticKind::Deprecated { replacement } => {
+ write!(
+ f,
+ "{}: field \"{}\" is deprecated{location}. Use \"{replacement}\" instead",
+ self.path, self.field
+ )
+ }
+ }
+ }
+}
+
+/// Result of validating a single config file.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ValidationResult {
+ pub errors: Vec,
+ pub warnings: Vec,
+}
+
+impl ValidationResult {
+ #[must_use]
+ pub fn is_ok(&self) -> bool {
+ self.errors.is_empty()
+ }
+
+ fn merge(&mut self, other: Self) {
+ self.errors.extend(other.errors);
+ self.warnings.extend(other.warnings);
+ }
+}
+
+// ---- known-key schema ----
+
+/// Expected type for a config field.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum FieldType {
+ String,
+ Bool,
+ Object,
+ StringArray,
+ Number,
+}
+
+impl FieldType {
+ fn label(self) -> &'static str {
+ match self {
+ Self::String => "a string",
+ Self::Bool => "a boolean",
+ Self::Object => "an object",
+ Self::StringArray => "an array of strings",
+ Self::Number => "a number",
+ }
+ }
+
+ fn matches(self, value: &JsonValue) -> bool {
+ match self {
+ Self::String => value.as_str().is_some(),
+ Self::Bool => value.as_bool().is_some(),
+ Self::Object => value.as_object().is_some(),
+ Self::StringArray => value
+ .as_array()
+ .is_some_and(|arr| arr.iter().all(|v| v.as_str().is_some())),
+ Self::Number => value.as_i64().is_some(),
+ }
+ }
+}
+
+fn json_type_label(value: &JsonValue) -> &'static str {
+ match value {
+ JsonValue::Null => "null",
+ JsonValue::Bool(_) => "a boolean",
+ JsonValue::Number(_) => "a number",
+ JsonValue::String(_) => "a string",
+ JsonValue::Array(_) => "an array",
+ JsonValue::Object(_) => "an object",
+ }
+}
+
+struct FieldSpec {
+ name: &'static str,
+ expected: FieldType,
+}
+
+struct DeprecatedField {
+ name: &'static str,
+ replacement: &'static str,
+}
+
+const TOP_LEVEL_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "$schema",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "model",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "hooks",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "permissions",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "permissionMode",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "mcpServers",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "oauth",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "enabledPlugins",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "plugins",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "sandbox",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "env",
+ expected: FieldType::Object,
+ },
+];
+
+const HOOKS_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "PreToolUse",
+ expected: FieldType::StringArray,
+ },
+ FieldSpec {
+ name: "PostToolUse",
+ expected: FieldType::StringArray,
+ },
+ FieldSpec {
+ name: "PostToolUseFailure",
+ expected: FieldType::StringArray,
+ },
+];
+
+const PERMISSIONS_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "defaultMode",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "allow",
+ expected: FieldType::StringArray,
+ },
+ FieldSpec {
+ name: "deny",
+ expected: FieldType::StringArray,
+ },
+ FieldSpec {
+ name: "ask",
+ expected: FieldType::StringArray,
+ },
+];
+
+const PLUGINS_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "enabled",
+ expected: FieldType::Object,
+ },
+ FieldSpec {
+ name: "externalDirectories",
+ expected: FieldType::StringArray,
+ },
+ FieldSpec {
+ name: "installRoot",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "registryPath",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "bundledRoot",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "maxOutputTokens",
+ expected: FieldType::Number,
+ },
+];
+
+const SANDBOX_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "enabled",
+ expected: FieldType::Bool,
+ },
+ FieldSpec {
+ name: "namespaceRestrictions",
+ expected: FieldType::Bool,
+ },
+ FieldSpec {
+ name: "networkIsolation",
+ expected: FieldType::Bool,
+ },
+ FieldSpec {
+ name: "filesystemMode",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "allowedMounts",
+ expected: FieldType::StringArray,
+ },
+];
+
+const OAUTH_FIELDS: &[FieldSpec] = &[
+ FieldSpec {
+ name: "clientId",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "authorizeUrl",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "tokenUrl",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "callbackPort",
+ expected: FieldType::Number,
+ },
+ FieldSpec {
+ name: "manualRedirectUrl",
+ expected: FieldType::String,
+ },
+ FieldSpec {
+ name: "scopes",
+ expected: FieldType::StringArray,
+ },
+];
+
+const DEPRECATED_FIELDS: &[DeprecatedField] = &[
+ DeprecatedField {
+ name: "permissionMode",
+ replacement: "permissions.defaultMode",
+ },
+ DeprecatedField {
+ name: "enabledPlugins",
+ replacement: "plugins.enabled",
+ },
+];
+
+// ---- line-number resolution ----
+
+/// Find the 1-based line number where a JSON key first appears in the raw source.
+fn find_key_line(source: &str, key: &str) -> Option {
+ // Search for `"key"` followed by optional whitespace and a colon.
+ let needle = format!("\"{key}\"");
+ let mut search_start = 0;
+ while let Some(offset) = source[search_start..].find(&needle) {
+ let absolute = search_start + offset;
+ let after = absolute + needle.len();
+ // Verify the next non-whitespace char is `:` to confirm this is a key, not a value.
+ if source[after..].chars().find(|ch| !ch.is_ascii_whitespace()) == Some(':') {
+ return Some(source[..absolute].chars().filter(|&ch| ch == '\n').count() + 1);
+ }
+ search_start = after;
+ }
+ None
+}
+
+// ---- core validation ----
+
+fn validate_object_keys(
+ object: &BTreeMap,
+ known_fields: &[FieldSpec],
+ prefix: &str,
+ source: &str,
+ path_display: &str,
+) -> ValidationResult {
+ let mut result = ValidationResult {
+ errors: Vec::new(),
+ warnings: Vec::new(),
+ };
+
+ let known_names: Vec<&str> = known_fields.iter().map(|f| f.name).collect();
+
+ for (key, value) in object {
+ let field_path = if prefix.is_empty() {
+ key.clone()
+ } else {
+ format!("{prefix}.{key}")
+ };
+
+ if let Some(spec) = known_fields.iter().find(|f| f.name == key) {
+ // Type check.
+ if !spec.expected.matches(value) {
+ result.errors.push(ConfigDiagnostic {
+ path: path_display.to_string(),
+ field: field_path,
+ line: find_key_line(source, key),
+ kind: DiagnosticKind::WrongType {
+ expected: spec.expected.label(),
+ got: json_type_label(value),
+ },
+ });
+ }
+ } else {
+ // Unknown key.
+ let suggestion = suggest_field(key, &known_names);
+ result.errors.push(ConfigDiagnostic {
+ path: path_display.to_string(),
+ field: field_path,
+ line: find_key_line(source, key),
+ kind: DiagnosticKind::UnknownKey { suggestion },
+ });
+ }
+ }
+
+ result
+}
+
+fn suggest_field(input: &str, candidates: &[&str]) -> Option {
+ let input_lower = input.to_ascii_lowercase();
+ candidates
+ .iter()
+ .filter_map(|candidate| {
+ let distance = simple_edit_distance(&input_lower, &candidate.to_ascii_lowercase());
+ (distance <= 3).then_some((distance, *candidate))
+ })
+ .min_by_key(|(distance, _)| *distance)
+ .map(|(_, name)| name.to_string())
+}
+
+fn simple_edit_distance(left: &str, right: &str) -> usize {
+ if left.is_empty() {
+ return right.len();
+ }
+ if right.is_empty() {
+ return left.len();
+ }
+ let right_chars: Vec = right.chars().collect();
+ let mut previous: Vec = (0..=right_chars.len()).collect();
+ let mut current = vec![0; right_chars.len() + 1];
+
+ for (left_index, left_char) in left.chars().enumerate() {
+ current[0] = left_index + 1;
+ for (right_index, right_char) in right_chars.iter().enumerate() {
+ let cost = usize::from(left_char != *right_char);
+ current[right_index + 1] = (previous[right_index + 1] + 1)
+ .min(current[right_index] + 1)
+ .min(previous[right_index] + cost);
+ }
+ previous.clone_from(¤t);
+ }
+
+ previous[right_chars.len()]
+}
+
+/// Validate a parsed config file's keys and types against the known schema.
+///
+/// Returns diagnostics (errors and deprecation warnings) without blocking the load.
+pub fn validate_config_file(
+ object: &BTreeMap,
+ source: &str,
+ file_path: &Path,
+) -> ValidationResult {
+ let path_display = file_path.display().to_string();
+ let mut result = validate_object_keys(object, TOP_LEVEL_FIELDS, "", source, &path_display);
+
+ // Check deprecated fields.
+ for deprecated in DEPRECATED_FIELDS {
+ if object.contains_key(deprecated.name) {
+ result.warnings.push(ConfigDiagnostic {
+ path: path_display.clone(),
+ field: deprecated.name.to_string(),
+ line: find_key_line(source, deprecated.name),
+ kind: DiagnosticKind::Deprecated {
+ replacement: deprecated.replacement,
+ },
+ });
+ }
+ }
+
+ // Validate known nested objects.
+ if let Some(hooks) = object.get("hooks").and_then(JsonValue::as_object) {
+ result.merge(validate_object_keys(
+ hooks,
+ HOOKS_FIELDS,
+ "hooks",
+ source,
+ &path_display,
+ ));
+ }
+ if let Some(permissions) = object.get("permissions").and_then(JsonValue::as_object) {
+ result.merge(validate_object_keys(
+ permissions,
+ PERMISSIONS_FIELDS,
+ "permissions",
+ source,
+ &path_display,
+ ));
+ }
+ if let Some(plugins) = object.get("plugins").and_then(JsonValue::as_object) {
+ result.merge(validate_object_keys(
+ plugins,
+ PLUGINS_FIELDS,
+ "plugins",
+ source,
+ &path_display,
+ ));
+ }
+ if let Some(sandbox) = object.get("sandbox").and_then(JsonValue::as_object) {
+ result.merge(validate_object_keys(
+ sandbox,
+ SANDBOX_FIELDS,
+ "sandbox",
+ source,
+ &path_display,
+ ));
+ }
+ if let Some(oauth) = object.get("oauth").and_then(JsonValue::as_object) {
+ result.merge(validate_object_keys(
+ oauth,
+ OAUTH_FIELDS,
+ "oauth",
+ source,
+ &path_display,
+ ));
+ }
+
+ result
+}
+
+/// Check whether a file path uses an unsupported config format (e.g. TOML).
+pub fn check_unsupported_format(file_path: &Path) -> Result<(), ConfigError> {
+ if let Some(ext) = file_path.extension().and_then(|e| e.to_str()) {
+ if ext.eq_ignore_ascii_case("toml") {
+ return Err(ConfigError::Parse(format!(
+ "{}: TOML config files are not supported. Use JSON (settings.json) instead",
+ file_path.display()
+ )));
+ }
+ }
+ Ok(())
+}
+
+/// Format all diagnostics into a human-readable report.
+#[must_use]
+pub fn format_diagnostics(result: &ValidationResult) -> String {
+ let mut lines = Vec::new();
+ for warning in &result.warnings {
+ lines.push(format!("warning: {warning}"));
+ }
+ for error in &result.errors {
+ lines.push(format!("error: {error}"));
+ }
+ lines.join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::path::PathBuf;
+
+ fn test_path() -> PathBuf {
+ PathBuf::from("/test/settings.json")
+ }
+
+ #[test]
+ fn detects_unknown_top_level_key() {
+ // given
+ let source = r#"{"model": "opus", "unknownField": true}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "unknownField");
+ assert!(matches!(
+ result.errors[0].kind,
+ DiagnosticKind::UnknownKey { .. }
+ ));
+ }
+
+ #[test]
+ fn detects_wrong_type_for_model() {
+ // given
+ let source = r#"{"model": 123}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "model");
+ assert!(matches!(
+ result.errors[0].kind,
+ DiagnosticKind::WrongType {
+ expected: "a string",
+ got: "a number"
+ }
+ ));
+ }
+
+ #[test]
+ fn detects_deprecated_permission_mode() {
+ // given
+ let source = r#"{"permissionMode": "plan"}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.warnings.len(), 1);
+ assert_eq!(result.warnings[0].field, "permissionMode");
+ assert!(matches!(
+ result.warnings[0].kind,
+ DiagnosticKind::Deprecated {
+ replacement: "permissions.defaultMode"
+ }
+ ));
+ }
+
+ #[test]
+ fn detects_deprecated_enabled_plugins() {
+ // given
+ let source = r#"{"enabledPlugins": {"tool-guard@builtin": true}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.warnings.len(), 1);
+ assert_eq!(result.warnings[0].field, "enabledPlugins");
+ assert!(matches!(
+ result.warnings[0].kind,
+ DiagnosticKind::Deprecated {
+ replacement: "plugins.enabled"
+ }
+ ));
+ }
+
+ #[test]
+ fn reports_line_number_for_unknown_key() {
+ // given
+ let source = "{\n \"model\": \"opus\",\n \"badKey\": true\n}";
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].line, Some(3));
+ assert_eq!(result.errors[0].field, "badKey");
+ }
+
+ #[test]
+ fn reports_line_number_for_wrong_type() {
+ // given
+ let source = "{\n \"model\": 42\n}";
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].line, Some(2));
+ }
+
+ #[test]
+ fn validates_nested_hooks_keys() {
+ // given
+ let source = r#"{"hooks": {"PreToolUse": ["cmd"], "BadHook": ["x"]}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "hooks.BadHook");
+ }
+
+ #[test]
+ fn validates_nested_permissions_keys() {
+ // given
+ let source = r#"{"permissions": {"allow": ["Read"], "denyAll": true}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "permissions.denyAll");
+ }
+
+ #[test]
+ fn validates_nested_sandbox_keys() {
+ // given
+ let source = r#"{"sandbox": {"enabled": true, "containerMode": "strict"}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "sandbox.containerMode");
+ }
+
+ #[test]
+ fn validates_nested_plugins_keys() {
+ // given
+ let source = r#"{"plugins": {"installRoot": "/tmp", "autoUpdate": true}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "plugins.autoUpdate");
+ }
+
+ #[test]
+ fn validates_nested_oauth_keys() {
+ // given
+ let source = r#"{"oauth": {"clientId": "abc", "secret": "hidden"}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "oauth.secret");
+ }
+
+ #[test]
+ fn valid_config_produces_no_diagnostics() {
+ // given
+ let source = r#"{
+ "model": "opus",
+ "hooks": {"PreToolUse": ["guard"]},
+ "permissions": {"defaultMode": "plan", "allow": ["Read"]},
+ "mcpServers": {},
+ "sandbox": {"enabled": false}
+}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert!(result.is_ok());
+ assert!(result.warnings.is_empty());
+ }
+
+ #[test]
+ fn suggests_close_field_name() {
+ // given
+ let source = r#"{"modle": "opus"}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ match &result.errors[0].kind {
+ DiagnosticKind::UnknownKey {
+ suggestion: Some(s),
+ } => assert_eq!(s, "model"),
+ other => panic!("expected suggestion, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn format_diagnostics_includes_all_entries() {
+ // given
+ let source = r#"{"permissionMode": "plan", "badKey": 1}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+ let result = validate_config_file(object, source, &test_path());
+
+ // when
+ let output = format_diagnostics(&result);
+
+ // then
+ assert!(output.contains("warning:"));
+ assert!(output.contains("error:"));
+ assert!(output.contains("badKey"));
+ assert!(output.contains("permissionMode"));
+ }
+
+ #[test]
+ fn check_unsupported_format_rejects_toml() {
+ // given
+ let path = PathBuf::from("/home/.claw/settings.toml");
+
+ // when
+ let result = check_unsupported_format(&path);
+
+ // then
+ assert!(result.is_err());
+ let message = result.unwrap_err().to_string();
+ assert!(message.contains("TOML"));
+ assert!(message.contains("settings.toml"));
+ }
+
+ #[test]
+ fn check_unsupported_format_allows_json() {
+ // given
+ let path = PathBuf::from("/home/.claw/settings.json");
+
+ // when / then
+ assert!(check_unsupported_format(&path).is_ok());
+ }
+
+ #[test]
+ fn wrong_type_in_nested_sandbox_field() {
+ // given
+ let source = r#"{"sandbox": {"enabled": "yes"}}"#;
+ let parsed = JsonValue::parse(source).expect("valid json");
+ let object = parsed.as_object().expect("object");
+
+ // when
+ let result = validate_config_file(object, source, &test_path());
+
+ // then
+ assert_eq!(result.errors.len(), 1);
+ assert_eq!(result.errors[0].field, "sandbox.enabled");
+ assert!(matches!(
+ result.errors[0].kind,
+ DiagnosticKind::WrongType {
+ expected: "a boolean",
+ got: "a string"
+ }
+ ));
+ }
+
+ #[test]
+ fn display_format_unknown_key_with_line() {
+ // given
+ let diag = ConfigDiagnostic {
+ path: "/test/settings.json".to_string(),
+ field: "badKey".to_string(),
+ line: Some(5),
+ kind: DiagnosticKind::UnknownKey { suggestion: None },
+ };
+
+ // when
+ let output = diag.to_string();
+
+ // then
+ assert_eq!(
+ output,
+ r#"/test/settings.json: unknown key "badKey" (line 5)"#
+ );
+ }
+
+ #[test]
+ fn display_format_wrong_type_with_line() {
+ // given
+ let diag = ConfigDiagnostic {
+ path: "/test/settings.json".to_string(),
+ field: "model".to_string(),
+ line: Some(2),
+ kind: DiagnosticKind::WrongType {
+ expected: "a string",
+ got: "a number",
+ },
+ };
+
+ // when
+ let output = diag.to_string();
+
+ // then
+ assert_eq!(
+ output,
+ r#"/test/settings.json: field "model" must be a string, got a number (line 2)"#
+ );
+ }
+
+ #[test]
+ fn display_format_deprecated_with_line() {
+ // given
+ let diag = ConfigDiagnostic {
+ path: "/test/settings.json".to_string(),
+ field: "permissionMode".to_string(),
+ line: Some(3),
+ kind: DiagnosticKind::Deprecated {
+ replacement: "permissions.defaultMode",
+ },
+ };
+
+ // when
+ let output = diag.to_string();
+
+ // then
+ assert_eq!(
+ output,
+ r#"/test/settings.json: field "permissionMode" is deprecated (line 3). Use "permissions.defaultMode" instead"#
+ );
+ }
+}
diff --git a/rust/crates/runtime/src/conversation.rs b/rust/crates/runtime/src/conversation.rs
index 1010bd3d..99cce827 100644
--- a/rust/crates/runtime/src/conversation.rs
+++ b/rust/crates/runtime/src/conversation.rs
@@ -504,6 +504,10 @@ where
&self.session
}
+ pub fn session_mut(&mut self) -> &mut Session {
+ &mut self.session
+ }
+
#[must_use]
pub fn fork_session(&self, branch_name: Option) -> Session {
self.session.fork(branch_name)
@@ -890,6 +894,7 @@ mod tests {
current_date: "2026-03-31".to_string(),
git_status: None,
git_diff: None,
+ git_context: None,
instruction_files: Vec::new(),
})
.with_os("linux", "6.8")
diff --git a/rust/crates/runtime/src/file_ops.rs b/rust/crates/runtime/src/file_ops.rs
index fde889b7..546897b3 100644
--- a/rust/crates/runtime/src/file_ops.rs
+++ b/rust/crates/runtime/src/file_ops.rs
@@ -28,6 +28,7 @@ fn is_binary_file(path: &Path) -> io::Result {
/// Validate that a resolved path stays within the given workspace root.
/// Returns the canonical path on success, or an error if the path escapes
/// the workspace boundary (e.g. via `../` traversal or symlink).
+#[allow(dead_code)]
fn validate_workspace_boundary(resolved: &Path, workspace_root: &Path) -> io::Result<()> {
if !resolved.starts_with(workspace_root) {
return Err(io::Error::new(
@@ -557,6 +558,7 @@ fn normalize_path_allow_missing(path: &str) -> io::Result {
}
/// Read a file with workspace boundary enforcement.
+#[allow(dead_code)]
pub fn read_file_in_workspace(
path: &str,
offset: Option,
@@ -572,6 +574,7 @@ pub fn read_file_in_workspace(
}
/// Write a file with workspace boundary enforcement.
+#[allow(dead_code)]
pub fn write_file_in_workspace(
path: &str,
content: &str,
@@ -586,6 +589,7 @@ pub fn write_file_in_workspace(
}
/// Edit a file with workspace boundary enforcement.
+#[allow(dead_code)]
pub fn edit_file_in_workspace(
path: &str,
old_string: &str,
@@ -602,6 +606,7 @@ pub fn edit_file_in_workspace(
}
/// Check whether a path is a symlink that resolves outside the workspace.
+#[allow(dead_code)]
pub fn is_symlink_escape(path: &Path, workspace_root: &Path) -> io::Result {
let metadata = fs::symlink_metadata(path)?;
if !metadata.is_symlink() {
diff --git a/rust/crates/runtime/src/git_context.rs b/rust/crates/runtime/src/git_context.rs
new file mode 100644
index 00000000..5703ebe8
--- /dev/null
+++ b/rust/crates/runtime/src/git_context.rs
@@ -0,0 +1,324 @@
+use std::path::Path;
+use std::process::Command;
+
+/// A single git commit entry from the log.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GitCommitEntry {
+ pub hash: String,
+ pub subject: String,
+}
+
+/// Git-aware context gathered at startup for injection into the system prompt.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GitContext {
+ pub branch: Option,
+ pub recent_commits: Vec,
+ pub staged_files: Vec,
+}
+
+const MAX_RECENT_COMMITS: usize = 5;
+
+impl GitContext {
+ /// Detect the git context from the given working directory.
+ ///
+ /// Returns `None` when the directory is not inside a git repository.
+ #[must_use]
+ pub fn detect(cwd: &Path) -> Option {
+ // Quick gate: is this a git repo at all?
+ let rev_parse = Command::new("git")
+ .args(["rev-parse", "--is-inside-work-tree"])
+ .current_dir(cwd)
+ .output()
+ .ok()?;
+ if !rev_parse.status.success() {
+ return None;
+ }
+
+ Some(Self {
+ branch: read_branch(cwd),
+ recent_commits: read_recent_commits(cwd),
+ staged_files: read_staged_files(cwd),
+ })
+ }
+
+ /// Render a human-readable summary suitable for system-prompt injection.
+ #[must_use]
+ pub fn render(&self) -> String {
+ let mut lines = Vec::new();
+
+ if let Some(branch) = &self.branch {
+ lines.push(format!("Git branch: {branch}"));
+ }
+
+ if !self.recent_commits.is_empty() {
+ lines.push(String::new());
+ lines.push("Recent commits:".to_string());
+ for entry in &self.recent_commits {
+ lines.push(format!(" {} {}", entry.hash, entry.subject));
+ }
+ }
+
+ if !self.staged_files.is_empty() {
+ lines.push(String::new());
+ lines.push("Staged files:".to_string());
+ for file in &self.staged_files {
+ lines.push(format!(" {file}"));
+ }
+ }
+
+ lines.join("\n")
+ }
+}
+
+fn read_branch(cwd: &Path) -> Option {
+ let output = Command::new("git")
+ .args(["rev-parse", "--abbrev-ref", "HEAD"])
+ .current_dir(cwd)
+ .output()
+ .ok()?;
+ if !output.status.success() {
+ return None;
+ }
+ let branch = String::from_utf8(output.stdout).ok()?;
+ let trimmed = branch.trim();
+ if trimmed.is_empty() || trimmed == "HEAD" {
+ None
+ } else {
+ Some(trimmed.to_string())
+ }
+}
+
+fn read_recent_commits(cwd: &Path) -> Vec {
+ let output = Command::new("git")
+ .args([
+ "--no-optional-locks",
+ "log",
+ "--oneline",
+ "-n",
+ &MAX_RECENT_COMMITS.to_string(),
+ "--no-decorate",
+ ])
+ .current_dir(cwd)
+ .output()
+ .ok();
+ let Some(output) = output else {
+ return Vec::new();
+ };
+ if !output.status.success() {
+ return Vec::new();
+ }
+ let stdout = String::from_utf8(output.stdout).unwrap_or_default();
+ stdout
+ .lines()
+ .filter_map(|line| {
+ let line = line.trim();
+ if line.is_empty() {
+ return None;
+ }
+ let (hash, subject) = line.split_once(' ')?;
+ Some(GitCommitEntry {
+ hash: hash.to_string(),
+ subject: subject.to_string(),
+ })
+ })
+ .collect()
+}
+
+fn read_staged_files(cwd: &Path) -> Vec {
+ let output = Command::new("git")
+ .args(["--no-optional-locks", "diff", "--cached", "--name-only"])
+ .current_dir(cwd)
+ .output()
+ .ok();
+ let Some(output) = output else {
+ return Vec::new();
+ };
+ if !output.status.success() {
+ return Vec::new();
+ }
+ let stdout = String::from_utf8(output.stdout).unwrap_or_default();
+ stdout
+ .lines()
+ .filter(|line| !line.trim().is_empty())
+ .map(|line| line.trim().to_string())
+ .collect()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{GitCommitEntry, GitContext};
+ use std::fs;
+ use std::process::Command;
+ use std::time::{SystemTime, UNIX_EPOCH};
+
+ fn temp_dir(label: &str) -> std::path::PathBuf {
+ let nanos = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .expect("time should be after epoch")
+ .as_nanos();
+ std::env::temp_dir().join(format!("runtime-git-context-{label}-{nanos}"))
+ }
+
+ fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+ crate::test_env_lock()
+ }
+
+ fn ensure_valid_cwd() {
+ if std::env::current_dir().is_err() {
+ std::env::set_current_dir(env!("CARGO_MANIFEST_DIR"))
+ .expect("test cwd should be recoverable");
+ }
+ }
+
+ #[test]
+ fn returns_none_for_non_git_directory() {
+ // given
+ let _guard = env_lock();
+ ensure_valid_cwd();
+ let root = temp_dir("non-git");
+ fs::create_dir_all(&root).expect("create dir");
+
+ // when
+ let context = GitContext::detect(&root);
+
+ // then
+ assert!(context.is_none());
+ fs::remove_dir_all(root).expect("cleanup");
+ }
+
+ #[test]
+ fn detects_branch_name_and_commits() {
+ // given
+ let _guard = env_lock();
+ ensure_valid_cwd();
+ let root = temp_dir("branch-commits");
+ fs::create_dir_all(&root).expect("create dir");
+ git(&root, &["init", "--quiet", "--initial-branch=main"]);
+ git(&root, &["config", "user.email", "tests@example.com"]);
+ git(&root, &["config", "user.name", "Git Context Tests"]);
+ fs::write(root.join("a.txt"), "a\n").expect("write a");
+ git(&root, &["add", "a.txt"]);
+ git(&root, &["commit", "-m", "first commit", "--quiet"]);
+ fs::write(root.join("b.txt"), "b\n").expect("write b");
+ git(&root, &["add", "b.txt"]);
+ git(&root, &["commit", "-m", "second commit", "--quiet"]);
+
+ // when
+ let context = GitContext::detect(&root).expect("should detect git repo");
+
+ // then
+ assert_eq!(context.branch.as_deref(), Some("main"));
+ assert_eq!(context.recent_commits.len(), 2);
+ assert_eq!(context.recent_commits[0].subject, "second commit");
+ assert_eq!(context.recent_commits[1].subject, "first commit");
+ assert!(context.staged_files.is_empty());
+ fs::remove_dir_all(root).expect("cleanup");
+ }
+
+ #[test]
+ fn detects_staged_files() {
+ // given
+ let _guard = env_lock();
+ ensure_valid_cwd();
+ let root = temp_dir("staged");
+ fs::create_dir_all(&root).expect("create dir");
+ git(&root, &["init", "--quiet", "--initial-branch=main"]);
+ git(&root, &["config", "user.email", "tests@example.com"]);
+ git(&root, &["config", "user.name", "Git Context Tests"]);
+ fs::write(root.join("init.txt"), "init\n").expect("write init");
+ git(&root, &["add", "init.txt"]);
+ git(&root, &["commit", "-m", "initial", "--quiet"]);
+ fs::write(root.join("staged.txt"), "staged\n").expect("write staged");
+ git(&root, &["add", "staged.txt"]);
+
+ // when
+ let context = GitContext::detect(&root).expect("should detect git repo");
+
+ // then
+ assert_eq!(context.staged_files, vec!["staged.txt"]);
+ fs::remove_dir_all(root).expect("cleanup");
+ }
+
+ #[test]
+ fn render_formats_all_sections() {
+ // given
+ let context = GitContext {
+ branch: Some("feat/test".to_string()),
+ recent_commits: vec![
+ GitCommitEntry {
+ hash: "abc1234".to_string(),
+ subject: "add feature".to_string(),
+ },
+ GitCommitEntry {
+ hash: "def5678".to_string(),
+ subject: "fix bug".to_string(),
+ },
+ ],
+ staged_files: vec!["src/main.rs".to_string()],
+ };
+
+ // when
+ let rendered = context.render();
+
+ // then
+ assert!(rendered.contains("Git branch: feat/test"));
+ assert!(rendered.contains("abc1234 add feature"));
+ assert!(rendered.contains("def5678 fix bug"));
+ assert!(rendered.contains("src/main.rs"));
+ }
+
+ #[test]
+ fn render_omits_empty_sections() {
+ // given
+ let context = GitContext {
+ branch: Some("main".to_string()),
+ recent_commits: Vec::new(),
+ staged_files: Vec::new(),
+ };
+
+ // when
+ let rendered = context.render();
+
+ // then
+ assert!(rendered.contains("Git branch: main"));
+ assert!(!rendered.contains("Recent commits:"));
+ assert!(!rendered.contains("Staged files:"));
+ }
+
+ #[test]
+ fn limits_to_five_recent_commits() {
+ // given
+ let _guard = env_lock();
+ ensure_valid_cwd();
+ let root = temp_dir("five-commits");
+ fs::create_dir_all(&root).expect("create dir");
+ git(&root, &["init", "--quiet", "--initial-branch=main"]);
+ git(&root, &["config", "user.email", "tests@example.com"]);
+ git(&root, &["config", "user.name", "Git Context Tests"]);
+ for i in 1..=8 {
+ let name = format!("file{i}.txt");
+ fs::write(root.join(&name), format!("{i}\n")).expect("write file");
+ git(&root, &["add", &name]);
+ git(&root, &["commit", "-m", &format!("commit {i}"), "--quiet"]);
+ }
+
+ // when
+ let context = GitContext::detect(&root).expect("should detect git repo");
+
+ // then
+ assert_eq!(context.recent_commits.len(), 5);
+ assert_eq!(context.recent_commits[0].subject, "commit 8");
+ assert_eq!(context.recent_commits[4].subject, "commit 4");
+ fs::remove_dir_all(root).expect("cleanup");
+ }
+
+ fn git(cwd: &std::path::Path, args: &[&str]) {
+ let status = Command::new("git")
+ .args(args)
+ .current_dir(cwd)
+ .output()
+ .unwrap_or_else(|_| panic!("git {args:?} should run"))
+ .status;
+ assert!(status.success(), "git {args:?} failed");
+ }
+}
diff --git a/rust/crates/runtime/src/lane_events.rs b/rust/crates/runtime/src/lane_events.rs
index c96f829e..96a9ac8a 100644
--- a/rust/crates/runtime/src/lane_events.rs
+++ b/rust/crates/runtime/src/lane_events.rs
@@ -1,3 +1,4 @@
+#![allow(clippy::similar_names)]
use serde::{Deserialize, Serialize};
use serde_json::Value;
@@ -76,6 +77,20 @@ pub struct LaneEventBlocker {
pub detail: String,
}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaneCommitProvenance {
+ pub commit: String,
+ pub branch: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub worktree: Option,
+ #[serde(rename = "canonicalCommit", skip_serializing_if = "Option::is_none")]
+ pub canonical_commit: Option,
+ #[serde(rename = "supersededBy", skip_serializing_if = "Option::is_none")]
+ pub superseded_by: Option
+ 
