substrate-setup 0.2.2__tar.gz → 0.3.0__tar.gz

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substrate-setup
-Version: 0.2.2
+Version: 0.3.0
 Summary: One-shot local configurator for coding agents against a Substrate gateway
 Project-URL: Homepage, https://github.com/FrankXiaA/substrate-solutions
 Project-URL: Source, https://github.com/FrankXiaA/substrate-solutions/tree/main/substrate-api/substrate_setup
@@ -20,6 +20,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27
 Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: tomli-w>=1.2
 Provides-Extra: dev
 Requires-Dist: mypy<2,>=1.13; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
@@ -64,6 +65,17 @@ substrate-setup remove             # strip the substrate-managed entries
 substrate-setup --help
 ```
 
-Supported agents: `hermes`, `cursor`, `aider`, `continue`.
+Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
 
 Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
+
+### Per-agent catalog UX (0.3.0+)
+
+| Agent | How it learns about Substrate's models |
+|---|---|
+| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
+| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
+| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
+| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. **Note:** requires Substrate's `/v1/messages` endpoint, which is gated behind a Fly feature flag — until it's flipped, requests return 404. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. Set `SUBSTRATE_API_KEY` in your shell rc. **Note:** requires Substrate's `/v1/responses` endpoint (gateway protocol adapters Phase 2 — not yet started). |

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/README.md

@@ -35,6 +35,17 @@ substrate-setup remove             # strip the substrate-managed entries
 substrate-setup --help
 ```
 
-Supported agents: `hermes`, `cursor`, `aider`, `continue`.
+Supported agents: `hermes`, `cursor`, `aider`, `continue`, `claude-code`, `codex`.
 
 Subset with `--agents-only hermes,aider`. Preview without writing: `--dry-run`. Override the gateway base URL: `--base-url https://your-gateway.example.com`.
+
+### Per-agent catalog UX (0.3.0+)
+
+| Agent | How it learns about Substrate's models |
+|---|---|
+| `hermes` | Live URL fetch via `model_catalog.providers.substrate.url`. Picker shows all chat-capable Substrate models, refreshed on Hermes' 24h TTL. |
+| `cursor` | Walkthrough printed after configure — copy the base URL, key, and model ids into Cursor's Settings → Models. |
+| `aider` | `~/.aider.model.metadata.json` written with one entry per chat-capable Substrate model. Use `--model openai/<id>` to switch. |
+| `continue` | All chat-capable Substrate models written as separate `models:` entries in `~/.continue/config.yaml`. |
+| `claude-code` | `~/.claude/settings.json` env block (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`). The `/model` picker stays opus/sonnet/haiku — use `claude --model openai/<id>` for any other Substrate model. **Note:** requires Substrate's `/v1/messages` endpoint, which is gated behind a Fly feature flag — until it's flipped, requests return 404. |
+| `codex` | `~/.codex/config.toml` `[model_providers.substrate]` block with `wire_api = "responses"`. Set `SUBSTRATE_API_KEY` in your shell rc. **Note:** requires Substrate's `/v1/responses` endpoint (gateway protocol adapters Phase 2 — not yet started). |

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "substrate-setup"
-version = "0.2.2"
+version = "0.3.0"
 description = "One-shot local configurator for coding agents against a Substrate gateway"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
   "httpx>=0.27",
   "ruamel.yaml>=0.18",
+  "tomli-w>=1.2",
 ]
 
 [project.urls]

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/substrate_setup/__init__.py

@@ -3,4 +3,4 @@
 See https://github.com/FrankXiaA/substrate-solutions for the gateway it
 configures against.
 """
-__version__ = "0.2.2"
+__version__ = "0.3.0"

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/substrate_setup/agents/__init__.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 
 from substrate_setup.agents.aider import AiderAgent
 from substrate_setup.agents.base import Agent
+from substrate_setup.agents.claude_code import ClaudeCodeAgent
+from substrate_setup.agents.codex import CodexAgent
 from substrate_setup.agents.continue_dev import ContinueAgent
 from substrate_setup.agents.cursor import CursorAgent
 from substrate_setup.agents.hermes import HermesAgent
@@ -15,6 +17,8 @@ ALL_AGENTS: list[Agent] = [
     CursorAgent(),
     AiderAgent(),
     ContinueAgent(),
+    ClaudeCodeAgent(),
+    CodexAgent(),
 ]
 
 AGENT_NAMES: list[str] = [a.name for a in ALL_AGENTS]

{substrate_setup-0.2.2 → substrate_setup-0.3.0}/substrate_setup/agents/aider.py

@@ -1,44 +1,47 @@
-"""Aider integration (0.2.0 — single conf.yml, no metadata file).
+"""Aider integration (0.3.0 — conf.yml + model-metadata sidecar).
 
 Files:
-  ~/.aider.conf.yml — openai-api-base, openai-api-key, model (default)
-
-Why no `.aider.model.metadata.json` (was written by 0.1)
--------------------------------------------------------
-Aider routes everything through one OpenAI-compatible endpoint set via
-``openai-api-base``. Per-model LiteLLM metadata (context length, cost
-per token) lives upstream on the gateway, not in Aider; the metadata
-file was over-engineered. 0.2.0 drops it. A user who wants a specific
-model passes ``--model <id>`` on the Aider CLI; otherwise the ``model:``
-key in ``~/.aider.conf.yml`` is used.
+  ~/.aider.conf.yml             — openai-api-base, openai-api-key, model
+  ~/.aider.model.metadata.json  — per-model LiteLLM hints (re-added in 0.3.0)
+
+Why metadata.json is back (0.3.0)
+---------------------------------
+0.2.0 dropped the file because Aider routes everything through one
+OpenAI-compatible endpoint and the per-model metadata duplicated info
+the gateway already knows. The 0.3.0 multi-agent catalog reverses this:
+the file is now used to advertise every chat-capable Substrate model
+to Aider so ``--model openai/<id>`` works for any catalog entry without
+each user having to memorise the prefix discipline. Keys use the
+``openai/<gateway_id>`` form aider's OpenAI-compatible provider
+requires. Image-gen catalog entries (``output_modality != "text"``) are
+filtered out — Aider only routes chat completions.
 
 Why no `~/.env` (was written by 0.1)
 ------------------------------------
 Aider's docs say the inline ``openai-api-key`` in ``~/.aider.conf.yml``
 is the supported way to authenticate against OpenAI-compatible
 gateways. Writing a shared ``~/.env`` was an over-reach that risked
-clobbering other tools' OPENAI_API_KEY. 0.2.0 drops the env write.
-``remove()`` still cleans up a legacy ``~/.aider.model.metadata.json``
-and a substrate-shaped ``OPENAI_API_KEY=`` line in ``~/.env`` if they
-were planted by 0.1.
+clobbering other tools' OPENAI_API_KEY. 0.2.0 dropped the env write.
+``remove()`` still strips a substrate-shaped ``OPENAI_API_KEY=`` line
+from ``~/.env`` if planted by 0.1 (best-effort legacy cleanup).
 
 Marker discipline
 -----------------
-Since the keys we own (``openai-api-base``, ``openai-api-key``,
-``model``) sit at the top level of a user-shared YAML doc, we write
-a sibling marker:
+Two markers, one per file:
 
-    _substrate_setup_managed_keys:
-      - "openai-api-base"
-      - "openai-api-key"
-      - "model"
+  conf.yml: top-level ``_substrate_setup_managed_keys`` list naming the
+    three keys we own (``openai-api-base``, ``openai-api-key``, ``model``).
+    Configure/remove refuse to touch the file if absent + user-set values.
 
-If the marker is absent AND any of those three keys are user-set,
-configure()/remove() refuses to touch them.
+  metadata.json: top-level sentinel ``_substrate_setup_managed: true``.
+    Configure refuses to overwrite an unmarked file; remove deletes the
+    file only if the marker is present. An unmarked file is treated as
+    user-owned and left alone.
 """
 from __future__ import annotations
 
 import io
+import json
 import os
 import sys
 from pathlib import Path
@@ -57,12 +60,18 @@ from substrate_setup.backup import backup_once
 MANAGED_KEYS_MARKER = "_substrate_setup_managed_keys"
 MANAGED_KEYS: list[str] = ["openai-api-base", "openai-api-key", "model"]
 
+# 0.3.0: ~/.aider.model.metadata.json is now substrate-managed (sidecar
+# to ~/.aider.conf.yml). The top-level sentinel below differentiates a
+# substrate-written file from a user-authored one.
+META_MARKER_KEY = "_substrate_setup_managed"
+
 
 def _conf_path() -> Path:
     return Path.home() / ".aider.conf.yml"
 
 
-def _legacy_meta_path() -> Path:
+def _meta_path() -> Path:
+    """Path to the Aider model-metadata JSON file (peer of .aider.conf.yml)."""
     return Path.home() / ".aider.model.metadata.json"
 
 
@@ -70,6 +79,38 @@ def _legacy_env_path() -> Path:
     return Path.home() / ".env"
 
 
+def _meta_has_marker(meta: dict[str, Any]) -> bool:
+    return meta.get(META_MARKER_KEY) is True
+
+
+def _is_chat_capable(entry: Any) -> bool:
+    """True if the catalog entry is a chat model (not image-gen).
+
+    Catalog entries without an explicit ``output_modality`` default to
+    ``text`` (chat).
+    """
+    return getattr(entry, "output_modality", "text") == "text"
+
+
+def _build_metadata_payload(catalog: list[Any]) -> dict[str, Any]:
+    """Build the JSON payload aider reads.
+
+    Keys use the ``openai/<gateway_id>`` form because aider's
+    OpenAI-compatible provider always prefixes with ``openai/``. The
+    sentinel ``_substrate_setup_managed: true`` carries marker
+    discipline so remove() knows the file is ours.
+    """
+    out: dict[str, Any] = {META_MARKER_KEY: True}
+    for entry in catalog:
+        if not _is_chat_capable(entry):
+            continue
+        out[f"openai/{entry.id}"] = {
+            "litellm_provider": "openai",
+            "mode": "chat",
+        }
+    return out
+
+
 def _yaml() -> YAML:
     y = YAML()
     y.preserve_quotes = True
@@ -191,6 +232,35 @@ class AiderAgent(Agent):
         if not ctx.dry_run:
             _dump_yaml(conf, payload)
 
+        # Write the model-metadata sidecar file. If a user-owned file
+        # already exists (no marker), refuse to clobber it — same
+        # refusal pattern as the conf.yml block above.
+        meta_path = _meta_path()
+        if meta_path.exists():
+            try:
+                existing_meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                existing_meta = {}
+            if not isinstance(existing_meta, dict):
+                existing_meta = {}
+            if not _meta_has_marker(existing_meta):
+                return AgentResult(
+                    ResultStatus.ERROR,
+                    f"Aider {meta_path} exists but is not substrate-managed; "
+                    "refused to overwrite. Delete the file or add "
+                    f"`{META_MARKER_KEY}: true` at the top to take over.",
+                    tuple(backups),
+                )
+            backup = backup_once(meta_path)
+            if backup is not None:
+                backups.append(backup)
+        new_meta = _build_metadata_payload(ctx.catalog)
+        if not ctx.dry_run:
+            meta_path.write_text(
+                json.dumps(new_meta, indent=2) + "\n", encoding="utf-8"
+            )
+            _restrict_file_mode(meta_path)
+
         return AgentResult(
             ResultStatus.SUCCESS,
             f"Wrote openai-api-base + openai-api-key + model into {conf}.",
@@ -261,6 +331,18 @@ class AiderAgent(Agent):
         if not ctx.dry_run:
             _dump_yaml(conf, payload)
 
+        # Drop the model-metadata sidecar if it's ours.
+        meta_path = _meta_path()
+        if meta_path.exists():
+            try:
+                existing_meta = json.loads(meta_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                existing_meta = {}
+            if isinstance(existing_meta, dict) and _meta_has_marker(existing_meta):
+                if not ctx.dry_run:
+                    meta_path.unlink()
+            # If no marker (user-owned), leave it alone.
+
         # Also clean up legacy artifacts written by 0.1 (best-effort).
         self._clean_legacy(ctx, backups=backups)
 
@@ -274,22 +356,17 @@ class AiderAgent(Agent):
     def _clean_legacy(
         ctx: ConfigureContext, *, backups: list[Path] | None = None
     ) -> bool:
-        """Delete 0.1 artifacts: ~/.aider.model.metadata.json and substrate
-        entries in ~/.env. Returns True if anything was cleaned."""
+        """Strip substrate entries from ~/.env (0.1 legacy).
+
+        ~/.aider.model.metadata.json is no longer treated as legacy in
+        0.3.0 — it's a substrate-managed sidecar with its own marker
+        discipline handled directly in configure()/remove(). This
+        helper now covers only the ~/.env case.
+        """
         if backups is None:
             backups = []
         did_something = False
 
-        # ~/.aider.model.metadata.json
-        legacy_meta = _legacy_meta_path()
-        if legacy_meta.exists():
-            backup = backup_once(legacy_meta)
-            if backup is not None:
-                backups.append(backup)
-            if not ctx.dry_run:
-                legacy_meta.unlink()
-            did_something = True
-
         # ~/.env: strip the OPENAI_API_KEY line if its value starts with "sk-substrate-".
         legacy_env = _legacy_env_path()
         if legacy_env.exists():

substrate_setup-0.3.0/substrate_setup/agents/claude_code.py

@@ -0,0 +1,339 @@
+"""Claude Code (Anthropic) integration.
+
+Claude Code reads its config from ``~/.claude/settings.json``. We
+merge three env keys into the ``env:`` block:
+
+  - ANTHROPIC_BASE_URL — Substrate gateway, WITHOUT /v1 suffix
+    (Claude Code appends /v1/messages itself)
+  - ANTHROPIC_AUTH_TOKEN — Substrate API key
+  - ANTHROPIC_MODEL — default model for chat sessions
+
+Claude Code's /model slash-command picker is hardcoded
+(opus/sonnet/haiku) and not externally extensible. To use other
+Substrate models the user passes ``claude --model openai/gpt-5.5``
+(or any chat-capable catalog id) on the command line. configure()
+prints a walkthrough listing the available model ids.
+
+Marker discipline:
+  Because we share settings.json with other Claude Code config
+  (skill registry, hooks, theme, etc.), we use a dedicated top-level
+  list ``_substrate_setup_managed_env_keys`` enumerating which env
+  keys we own. The settings.json itself never gets deleted — even
+  when remove() runs.
+
+Gateway dependency:
+  Claude Code reaches Substrate via /v1/messages. The route was
+  merged in gateway protocol adapters Phase 1 (PR #57) and is
+  mounted behind the ``GATEWAY_PROTOCOL_ADAPTERS_ENABLED`` Fly
+  secret. Until that flag is flipped, requests return 404 — the
+  walkthrough below tells the user this so they're not surprised.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from substrate_setup.agents.base import (
+    Agent,
+    AgentResult,
+    ConfigureContext,
+    ResultStatus,
+)
+from substrate_setup.backup import backup_once
+
+MANAGED_ENV_KEYS_MARKER = "_substrate_setup_managed_env_keys"
+MANAGED_ENV_KEYS: list[str] = [
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_MODEL",
+]
+
+
+def _claude_dir() -> Path:
+    return Path.home() / ".claude"
+
+
+def _settings_path() -> Path:
+    return _claude_dir() / "settings.json"
+
+
+def _strip_v1_suffix(base_url: str) -> str:
+    """Claude Code appends /v1/messages itself.
+
+    The Substrate gateway base is `https://...fly.dev/v1`; Hermes/Aider/
+    Continue.dev want the `/v1` in their base URL (they hit
+    `/v1/chat/completions`); Claude Code does NOT. Strip a trailing `/v1`
+    (and any trailing slash) if present.
+    """
+    trimmed = base_url.rstrip("/")
+    if trimmed.endswith("/v1"):
+        return trimmed[: -len("/v1")]
+    return trimmed
+
+
+def _load_settings(path: Path) -> tuple[dict[str, Any] | None, AgentResult | None]:
+    if not path.exists():
+        return {}, None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return None, AgentResult(
+            ResultStatus.ERROR,
+            f"Claude Code {path} is not valid JSON: {exc.msg} at "
+            f"line {exc.lineno}. Fix the file and re-run.",
+        )
+    if not isinstance(data, dict):
+        return None, AgentResult(
+            ResultStatus.ERROR,
+            f"Claude Code {path} root is not an object; refused to merge.",
+        )
+    return data, None
+
+
+def _has_managed_marker(payload: dict[str, Any]) -> bool:
+    marker = payload.get(MANAGED_ENV_KEYS_MARKER)
+    if not isinstance(marker, list):
+        return False
+    return set(MANAGED_ENV_KEYS).issubset(set(marker))
+
+
+def _user_owns_anthropic_env(env_block: dict[str, Any]) -> bool:
+    for key in MANAGED_ENV_KEYS:
+        v = env_block.get(key)
+        if isinstance(v, str) and v.strip():
+            return True
+    return False
+
+
+def _existing_matches_substrate_shape(
+    env_block: dict[str, Any], ctx: ConfigureContext
+) -> bool:
+    """Auto-claim heuristic for an existing config."""
+    expected_base = _strip_v1_suffix(ctx.base_url)
+    if env_block.get("ANTHROPIC_BASE_URL") != expected_base:
+        return False
+    token = env_block.get("ANTHROPIC_AUTH_TOKEN")
+    if not isinstance(token, str) or not token.startswith("sk-substrate-"):
+        return False
+    return True
+
+
+def _chat_capable(catalog: list[Any]) -> list[Any]:
+    return [e for e in catalog if e.output_modality == "text"]
+
+
+def _restrict_file_mode(path: Path) -> None:
+    if sys.platform == "win32":
+        return
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+class ClaudeCodeAgent(Agent):
+    name = "claude-code"
+    pretty_name = "Claude Code"
+
+    def detect(self) -> Path | None:
+        """Three layered signals:
+          1. settings.json present (strongest)
+          2. ~/.claude/ directory present (Claude Code ran at least once)
+          3. `claude` binary on PATH (pipx install, never run)
+        """
+        settings = _settings_path()
+        if settings.exists():
+            return settings
+        claude_dir = _claude_dir()
+        if claude_dir.exists():
+            return claude_dir
+        binary = shutil.which("claude")
+        if binary:
+            return Path(binary)
+        return None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        claude_dir = _claude_dir()
+        claude_dir.mkdir(parents=True, exist_ok=True)
+
+        settings_path = _settings_path()
+        backups: list[Path] = []
+        notes: list[str] = []
+
+        payload, err = _load_settings(settings_path)
+        if err is not None:
+            return err
+        assert payload is not None
+
+        env_block = payload.get("env") or {}
+        if not isinstance(env_block, dict):
+            env_block = {}
+
+        if not _has_managed_marker(payload):
+            if _user_owns_anthropic_env(env_block):
+                if _existing_matches_substrate_shape(env_block, ctx):
+                    notes.append(
+                        "Claude Code settings.json had substrate-shaped env "
+                        "keys but no marker; auto-claiming ownership."
+                    )
+                else:
+                    return AgentResult(
+                        ResultStatus.ERROR,
+                        "Claude Code settings.json has user-owned ANTHROPIC_* "
+                        "env keys but no substrate-setup marker; refused to "
+                        "overwrite. To take over, delete those keys from "
+                        "settings.json and re-run substrate-setup.",
+                        tuple(backups),
+                    )
+
+        if settings_path.exists():
+            backup = backup_once(settings_path)
+            if backup is not None:
+                backups.append(backup)
+
+        chat_models = _chat_capable(ctx.catalog)
+        if not chat_models:
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Cannot configure Claude Code with an empty chat-model "
+                "catalog.",
+                tuple(backups),
+            )
+        default_model = chat_models[0].id
+
+        env_block["ANTHROPIC_BASE_URL"] = _strip_v1_suffix(ctx.base_url)
+        env_block["ANTHROPIC_AUTH_TOKEN"] = ctx.api_key
+        env_block["ANTHROPIC_MODEL"] = default_model
+        payload["env"] = env_block
+
+        payload[MANAGED_ENV_KEYS_MARKER] = list(MANAGED_ENV_KEYS)
+
+        if not ctx.dry_run:
+            settings_path.write_text(
+                json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+            )
+            _restrict_file_mode(settings_path)
+
+        bullets = "\n".join(f"     - {m.id}" for m in chat_models)
+        print(
+            "Claude Code configured to use the Substrate gateway.\n"
+            "\n"
+            f"  Default model: {default_model}\n"
+            "  The /model slash command stays opus/sonnet/haiku (built-in).\n"
+            "  To use any other Substrate model, pass --model on the CLI:\n"
+            "\n"
+            "      claude --model openai/gpt-5.5 \"...\"\n"
+            "\n"
+            "  Available chat-capable Substrate models:\n"
+            f"{bullets}\n"
+            "\n"
+            "  NOTE: Claude Code reaches Substrate via /v1/messages. The route\n"
+            "  was added in gateway protocol adapters Phase 1 (PR #57) and is\n"
+            "  mounted behind a Fly feature flag — until that flag is flipped\n"
+            "  on, requests return 404."
+        )
+
+        msg = f"Wrote {','.join(MANAGED_ENV_KEYS)} into {settings_path}."
+        if notes:
+            msg += "\n" + "\n".join(notes)
+        return AgentResult(ResultStatus.SUCCESS, msg, tuple(backups))
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        settings_path = _settings_path()
+        if not settings_path.exists():
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Claude Code settings.json does not exist",
+            )
+        payload, err = _load_settings(settings_path)
+        if err is not None:
+            return err
+        assert payload is not None
+
+        if not _has_managed_marker(payload):
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Claude Code settings.json is not managed by substrate-setup "
+                f"(marker `{MANAGED_ENV_KEYS_MARKER}` missing or incomplete)",
+            )
+
+        env_block = payload.get("env") or {}
+        if not isinstance(env_block, dict):
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Claude Code env block is malformed",
+            )
+
+        problems: list[str] = []
+        expected_base = _strip_v1_suffix(ctx.base_url)
+        if env_block.get("ANTHROPIC_BASE_URL") != expected_base:
+            problems.append(
+                f"ANTHROPIC_BASE_URL: expected {expected_base!r}, "
+                f"got {env_block.get('ANTHROPIC_BASE_URL')!r}"
+            )
+        token = env_block.get("ANTHROPIC_AUTH_TOKEN")
+        if not isinstance(token, str) or len(token) < 20:
+            problems.append(
+                "ANTHROPIC_AUTH_TOKEN: missing or implausibly short"
+            )
+        chat_models = _chat_capable(ctx.catalog)
+        expected_default = chat_models[0].id if chat_models else None
+        if env_block.get("ANTHROPIC_MODEL") != expected_default:
+            problems.append(
+                f"ANTHROPIC_MODEL: expected {expected_default!r}, "
+                f"got {env_block.get('ANTHROPIC_MODEL')!r}"
+            )
+
+        if problems:
+            return AgentResult(ResultStatus.ERROR, "; ".join(problems))
+        return AgentResult(ResultStatus.SUCCESS, "in sync")
+
+    def remove(self, ctx: ConfigureContext) -> AgentResult:
+        settings_path = _settings_path()
+        if not settings_path.exists():
+            return AgentResult(
+                ResultStatus.SKIPPED, "Claude Code not configured"
+            )
+        payload, err = _load_settings(settings_path)
+        if err is not None:
+            return err
+        assert payload is not None
+
+        if not _has_managed_marker(payload):
+            return AgentResult(
+                ResultStatus.SKIPPED,
+                "Claude Code settings.json is not managed by substrate-setup; "
+                "refusing to delete keys we don't own",
+            )
+
+        backups: list[Path] = []
+        backup = backup_once(settings_path)
+        if backup is not None:
+            backups.append(backup)
+
+        env_block = payload.get("env") or {}
+        if isinstance(env_block, dict):
+            for key in MANAGED_ENV_KEYS:
+                env_block.pop(key, None)
+            if env_block:
+                payload["env"] = env_block
+            else:
+                payload.pop("env", None)
+
+        payload.pop(MANAGED_ENV_KEYS_MARKER, None)
+
+        if not ctx.dry_run:
+            settings_path.write_text(
+                json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+            )
+            _restrict_file_mode(settings_path)
+
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            f"Removed substrate-managed env keys from {settings_path}",
+            tuple(backups),
+        )