feat(claude): add forward_host_credentials support

Reads the host's Claude OAuth session key from ~/.claude.json at launch and forwards it only to the egress sidecar (never to the agent), placing a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent env so Claude Code starts without seeing the real credential. Mirrors the existing Codex forward_host_credentials flow (PRD 0029). Adds claude_auth.py to extract and validate the sessionKey, a CLAUDE_HOST_CREDENTIAL_TOKEN_REF constant in egress.py, and updates manifest_agent.py to allow the flag for both 'codex' and 'claude' templates. Also adds a mutual-exclusion check that rejects setting both auth_token and forward_host_credentials together. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): read credentials from ~/.claude/.credentials.json The actual OAuth token is in ~/.claude/.credentials.json under claudeAiOauth.accessToken, not in ~/.claude.json. ~/.claude.json holds only UI state and profile metadata (oauthAccount has no token fields). expiresAt in the credentials file is milliseconds, not seconds. Discovered after testing against Claude Code 2.1.198. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): fall back to macOS Keychain for credentials On macOS, Claude Code stores credentials in the Keychain under service "Claude Code-credentials" rather than in a file. When ~/.claude/.credentials.json is absent, shell out to: security find-generic-password -s "Claude Code-credentials" -w and parse the result as the same JSON schema. ~/.claude.json holds only profile/UI metadata (oauthAccount has no token fields). expiresAt in the credentials is milliseconds. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> docs(prd): fix credential path references (~/.claude/.credentials.json) fix(test): suppress gitleaks false positives on synthetic Claude tokens
chore: update quality badges
2026-07-18 09:55:03 +00:00 · 2026-07-18 09:15:12 +00:00 · 2026-07-18 05:14:27 -04:00 · 2026-07-18 05:14:27 -04:00 · 2026-07-18 05:14:27 -04:00 · 2026-07-18 05:11:48 -04:00
39 changed files with 795 additions and 643 deletions
@@ -22,10 +22,7 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4

-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python: canaries are stdlib unittest on the image's
+      # system Python 3.12 (older act_runner mishandles setup-python's PATH).
      - name: Run canaries
        run: python3 -m unittest discover -t . -s tests/canaries -v
@@ -13,31 +13,19 @@ jobs:
    steps:
      - uses: actions/checkout@v3

-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python: the runner image already ships Python 3.12,
+      # and older act_runner engines mishandle setup-python's PATH. Install
+      # into the ephemeral job container's system Python — the pylint/pyright
+      # console scripts land on /usr/local/bin (on PATH) so the steps below
+      # still resolve. --break-system-packages is safe: the container is
+      # disposable.
      - name: Install dev dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements-dev.txt
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

      - name: Run pylint
        run: |
-          # Pylint's normal exit code is nonzero for any emitted finding,
-          # regardless of --fail-under. Preserve the full report but enforce
-          # the aggregate score this workflow promises.
-          set +e
-          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' \
-            | xargs pylint --fail-under=8.0 \
-            | tee /tmp/pylint-output.txt
-          set -e
-          SCORE=$(sed -n \
-            's/^Your code has been rated at \([-0-9.]*\)\/10.*/\1/p' \
-            /tmp/pylint-output.txt | tail -1)
-          test -n "$SCORE"
-          awk -v score="$SCORE" 'BEGIN { exit !(score >= 8.0) }'
+          # Run pylint on all Python files in the repo
+          find . -name '*.py' -not -path './.venv/*' -not -path './.git/*' | xargs pylint --fail-under=8.0

      - name: Run pyright
        run: |
@@ -37,11 +37,8 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python: the inline script is stdlib-only on the
+      # image's system Python 3.12 (older act_runner mishandles its PATH).
      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
@@ -34,13 +34,13 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4

-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python: the runner image already ships Python 3.12,
+      # and older act_runner engines mishandle setup-python's PATH (coverage
+      # lands in one interpreter, `python3` resolves to another). Install
+      # straight into the ephemeral job container's system Python —
+      # --break-system-packages is safe because the container is disposable.
      - name: Install dev requirements
-        run: python3 -m pip install -r requirements-dev.txt
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

      - name: Run unit tests
        run: python3 -m coverage run -m unittest discover -t . -s tests/unit -v
@@ -54,11 +54,8 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4

-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python (see the note in the `unit` job); the
+      # container's system Python 3.12 runs the stdlib test suite directly.
      - name: Show environment
        run: |
          python3 --version
@@ -88,13 +85,13 @@ jobs:
        with:
          fetch-depth: 0

-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
+      # No actions/setup-python: the runner image already ships Python 3.12,
+      # and older act_runner engines mishandle setup-python's PATH (coverage
+      # lands in one interpreter, `python3` resolves to another). Install
+      # straight into the ephemeral job container's system Python —
+      # --break-system-packages is safe because the container is disposable.
      - name: Install dev requirements
-        run: python3 -m pip install -r requirements-dev.txt
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

      - name: Combined coverage report (unit + integration)
        run: PYTHON=python3 bash scripts/coverage.sh critical
@@ -1,33 +0,0 @@
-name: tracker-policy
-
-on:
-  issues:
-    types: [opened, unlabeled]
-  pull_request:
-    types: [opened, edited, reopened, synchronized, labeled, unlabeled]
-
-jobs:
-  label-issue:
-    if: ${{ github.event_name == 'issues' }}
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-    steps:
-      - uses: actions/checkout@v4
-      - name: Ensure the issue has a label
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python3 scripts/tracker_policy.py label-issue
-
-  check-pr:
-    if: ${{ github.event_name == 'pull_request' }}
-    runs-on: ubuntu-latest
-    permissions:
-      issues: read
-      pull-requests: read
-    steps:
-      - uses: actions/checkout@v4
-      - name: Require an unlabeled PR linked to an issue
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python3 scripts/tracker_policy.py check-pr
@@ -20,21 +20,18 @@ jobs:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.12'
-
+      # No actions/setup-python: the runner image ships Python 3.12 and older
+      # act_runner engines mishandle setup-python's PATH. Install into the
+      # ephemeral job container's system Python (--break-system-packages is
+      # safe because the container is disposable).
      - name: Install dev dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements-dev.txt
+        run: python3 -m pip install --break-system-packages -r requirements-dev.txt

      - name: Run coverage and extract percentage
        id: coverage
        run: |
-          python -m coverage run -m unittest discover -t . -s tests/unit > /dev/null 2>&1 || true
-          PERCENT=$(python -m coverage report 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
+          python3 -m coverage run -m unittest discover -t . -s tests/unit > /dev/null 2>&1 || true
+          PERCENT=$(python3 -m coverage report 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
          echo "percent=$PERCENT" >> $GITHUB_OUTPUT
          echo "Coverage: $PERCENT%"

@@ -45,7 +42,7 @@ jobs:
          # the single source of truth in scripts/critical-modules.txt; every
          # core module is unit-tested, so the unit-only run is accurate for it.
          INCLUDE=$(grep -vE '^[[:space:]]*(#|$)' scripts/critical-modules.txt | paste -sd, -)
-          PERCENT=$(python -m coverage report --include="$INCLUDE" 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
+          PERCENT=$(python3 -m coverage report --include="$INCLUDE" 2>/dev/null | grep '^TOTAL' | grep -oP '\d+(?=%)' | tail -1)
          echo "percent=$PERCENT" >> $GITHUB_OUTPUT
          echo "Core coverage: $PERCENT%"

@@ -16,10 +16,12 @@
 # Layout:
 #
 #   /usr/bin/gitleaks                    gitleaks binary
-#   /app/egress_addon.py + siblings      mitmproxy addon (egress)
+#   /app/egress_addon.py                 mitmproxy addon entry point
 #   /app/egress-entrypoint.sh            mitmdump launcher
-#   /app/supervise_server.py + .py       supervise MCP server
-#   /app/gateway_init.py                 PID 1 supervisor
+#   /usr/local/lib/python*/bot_bottle/   installed package (all daemons + shared modules)
+#   /app/egress_addon.py                 one-line shim: re-exports addons from package
+#                                        (mitmdump -s requires a file path, not a module)
+#   /etc/egress/routes.yaml              bind-mounted at run time
 #   /etc/git-gate/pre-receive            docker-cp'd at start time
 #   /git-gate-entrypoint.sh              docker-cp'd at start time
 #   /git-gate/creds/*                    docker-cp'd at start time
@@ -87,27 +89,16 @@ RUN arch="${TARGETARCH:-$(dpkg --print-architecture)}" \
 && tar -xzf /tmp/gitleaks.tar.gz -C /usr/bin gitleaks \
 && rm /tmp/gitleaks.tar.gz

-# Project Python: addon + server modules + the init supervisor.
-# Kept flat under /app/ so mitmdump's loader resolves them as
-# top-level siblings (absolute imports), matching the prior
-# Dockerfile.egress / Dockerfile.supervise layout.
-COPY bot_bottle/egress_addon_core.py /app/egress_addon_core.py
-COPY bot_bottle/egress_dlp_config.py /app/egress_dlp_config.py
-COPY bot_bottle/egress_addon.py      /app/egress_addon.py
-COPY bot_bottle/policy_resolver.py   /app/policy_resolver.py
-COPY bot_bottle/dlp_detectors.py     /app/dlp_detectors.py
-COPY bot_bottle/yaml_subset.py       /app/yaml_subset.py
-COPY bot_bottle/paths.py             /app/paths.py
-COPY bot_bottle/migrations.py        /app/migrations.py
-COPY bot_bottle/db_store.py          /app/db_store.py
-COPY bot_bottle/supervise_types.py   /app/supervise_types.py
-COPY bot_bottle/queue_store.py       /app/queue_store.py
-COPY bot_bottle/audit_store.py       /app/audit_store.py
-COPY bot_bottle/store_manager.py     /app/store_manager.py
-COPY bot_bottle/supervise.py         /app/supervise.py
-COPY bot_bottle/supervise_server.py  /app/supervise_server.py
-COPY bot_bottle/gateway_init.py      /app/gateway_init.py
-COPY bot_bottle/git_http_backend.py  /app/git_http_backend.py
+# Install bot_bottle as a proper package so entry-point scripts can use
+# `from bot_bottle.X import Y` absolute imports. A rename or a missing
+# module is caught at pip-install time — not at container runtime.
+COPY pyproject.toml /src/
+COPY bot_bottle/    /src/bot_bottle/
+RUN pip install --no-cache-dir /src/
+
+# mitmdump -s requires a file path, not a module. Write a one-line shim that
+# re-exports `addons` from the installed package; mitmdump finds it there.
+RUN printf 'from bot_bottle.egress_addon import addons\n' > /app/egress_addon.py
 COPY bot_bottle/egress_entrypoint.sh /app/egress-entrypoint.sh
 RUN chmod +x /app/egress-entrypoint.sh

@@ -126,10 +117,8 @@ RUN mkdir -p \
 # subset the bottle uses.
 EXPOSE 8888 9099 9418 9420 9100

-# WORKDIR matches Dockerfile.supervise's prior layout so the
-# in-app same-dir import in supervise_server.py stays deterministic.
 WORKDIR /app

 # PID 1 is the supervisor. It owns signal handling and exit-code
 # propagation; no `exec` chain in the entrypoint itself.
-ENTRYPOINT ["python3", "/app/gateway_init.py"]
+ENTRYPOINT ["python3", "-m", "bot_bottle.gateway_init"]
@@ -5,8 +5,8 @@
 # bot-bottle

 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)](https://coverage.readthedocs.io/)
-[![core coverage](https://img.shields.io/badge/core%20coverage-95%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
+[![coverage](https://img.shields.io/badge/coverage-81%25-brightgreen)](https://coverage.readthedocs.io/)
+[![core coverage](https://img.shields.io/badge/core%20coverage-94%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)

 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.

@@ -171,15 +171,6 @@ When an outbound DLP detector matches a token, the route's `dlp.outbound_on_matc

 More examples in `examples/`. Full design lives under `docs/prds/`; the trust-boundary rationale is in `docs/prds/0011-per-file-md-manifest.md`.

-## Tracker policy
-
-Issues are the canonical work items and own all tracker labels; every issue
-must have at least one. Pull requests stay unlabeled and deliberately reference
-an issue with `Closes #…`, `Part of #…`, or another form defined in
-[`ADR 0005`](docs/decisions/0005-issues-own-tracker-metadata.md). Gitea Actions
-enforces the convention for new work from 2026-07-18 onward. Earlier closed
-PRs are grandfathered rather than given artificial retrospective issues.
-
 ## Trademarks

 bot-bottle is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic, PBC; the project name uses "claude" descriptively to indicate that the tool runs Claude Code inside a sandbox.
@@ -45,6 +45,10 @@ PROVIDER_TEMPLATES = frozenset({PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_PI})
 # forward_host_credentials is enabled. Pipelock must pass these through
 # (no TLS MITM) or its header DLP blocks the injected JWT.
 CODEX_HOST_CREDENTIAL_HOSTS = ("api.openai.com", "chatgpt.com")
+
+# Host that egress injects the host Claude bearer on when Claude
+# forward_host_credentials is enabled.
+CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)
 PromptMode = Literal[
    "append_file",
    "read_prompt_file",
@@ -40,7 +40,7 @@ from abc import ABC, abstractmethod
 from contextlib import AbstractContextManager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Generic, Sequence, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, Sequence, TypeVar

 from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
 from ..egress import EgressPlan
@@ -54,6 +54,9 @@ from ..workspace import WorkspacePlan, workspace_plan
 from .print_util import print_multi, visible_agent_env_names
 from .util import host_skill_dir

+if TYPE_CHECKING:
+    from .freeze import CommitCancelled, Freezer, get_freezer
+

@dataclass(frozen=True)
 class BottleSpec:
@@ -584,28 +587,63 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
        Not called by the launch path or the test suite."""


-# Import concrete backend classes AFTER the base types are defined, so
-# each backend module can pull BottleSpec / BottlePlan / BottleBackend
-# via `from . import ...` without hitting a partially-initialized module.
-from .docker import DockerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
-from .firecracker import FirecrackerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
-from .macos_container import MacosContainerBottleBackend  # noqa: E402  # pylint: disable=wrong-import-position
-
-# Freezer is imported after the backend classes for the same reason:
-# Freezer.commit_slug constructs ActiveAgent, which must be fully
-# defined first.
-from .freeze import CommitCancelled, Freezer, get_freezer  # noqa: E402  # pylint: disable=wrong-import-position
+# _backends is None until the first call to _get_backends(), at which
+# point all three concrete backend classes are imported and instantiated.
+# Keeping the imports out of module scope means that importing any
+# backend sub-module (e.g. `backend.docker.util`) no longer drags the
+# firecracker and macos-container implementations into memory.
+#
+# Tests may replace _backends with a {name: fake} dict via patch.object;
+# _get_backends() returns the current module-level value as-is when it
+# is not None, so test fakes take effect without triggering real imports.
+_backends: dict[str, BottleBackend[Any, Any]] | None = None


-# The dict is heterogeneous: each value is a BottleBackend specialized
-# over its own plan type. Concrete plan types are erased here because
-# the registry is selected at runtime and the CLI only needs the
-# unparameterized methods (prepare → plan → launch(plan), cleanup, etc.).
-_BACKENDS: dict[str, BottleBackend[Any, Any]] = {
-    "docker": DockerBottleBackend(),
-    "firecracker": FirecrackerBottleBackend(),
-    "macos-container": MacosContainerBottleBackend(),
-}
+def _get_backends() -> dict[str, BottleBackend[Any, Any]]:
+    """Return the registry of all backend instances, loading lazily on first call."""
+    global _backends  # pylint: disable=global-statement
+    if _backends is None:
+        from .docker import DockerBottleBackend
+        from .firecracker import FirecrackerBottleBackend
+        from .macos_container import MacosContainerBottleBackend
+        _backends = {
+            "docker": DockerBottleBackend(),
+            "firecracker": FirecrackerBottleBackend(),
+            "macos-container": MacosContainerBottleBackend(),
+        }
+    return _backends
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily surface concrete backend classes and freeze symbols at the
+    package level so existing `from bot_bottle.backend import X` and
+    `patch.object(backend_mod, X, ...)` call-sites keep working without
+    forcing an import of every backend at module-init time."""
+    if name == "DockerBottleBackend":
+        from .docker import DockerBottleBackend
+        globals()[name] = DockerBottleBackend
+        return DockerBottleBackend
+    if name == "FirecrackerBottleBackend":
+        from .firecracker import FirecrackerBottleBackend
+        globals()[name] = FirecrackerBottleBackend
+        return FirecrackerBottleBackend
+    if name == "MacosContainerBottleBackend":
+        from .macos_container import MacosContainerBottleBackend
+        globals()[name] = MacosContainerBottleBackend
+        return MacosContainerBottleBackend
+    if name == "CommitCancelled":
+        from .freeze import CommitCancelled
+        globals()[name] = CommitCancelled
+        return CommitCancelled
+    if name == "Freezer":
+        from .freeze import Freezer
+        globals()[name] = Freezer
+        return Freezer
+    if name == "get_freezer":
+        from .freeze import get_freezer
+        globals()[name] = get_freezer
+        return get_freezer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


 def get_bottle_backend(
@@ -623,10 +661,11 @@ def get_bottle_backend(
    Dies with a pointer at the known backends if the chosen name
    isn't implemented."""
    resolved = name or os.environ.get("BOT_BOTTLE_BACKEND") or _default_backend_name()
-    if resolved not in _BACKENDS:
-        known = ", ".join(sorted(_BACKENDS))
+    backends = _get_backends()
+    if resolved not in backends:
+        known = ", ".join(sorted(backends))
        die(f"unknown backend {resolved!r}; known backends: {known}")
-    return _BACKENDS[resolved]
+    return backends[resolved]


 def _default_backend_name() -> str:
@@ -636,16 +675,17 @@ def _default_backend_name() -> str:
    # `firecracker` binary isn't installed yet: selecting it here routes
    # start through firecracker's preflight, which prints an install
    # pointer, instead of silently falling back to docker.
+    from .firecracker import FirecrackerBottleBackend
    if FirecrackerBottleBackend.is_host_capable():
        return "firecracker"
    return "docker"


 def known_backend_names() -> tuple[str, ...]:
-    """Sorted tuple of all backend keys in `_BACKENDS`. Used by
+    """Sorted tuple of all backend keys in `_get_backends()`. Used by
    argparse (`--backend` choices) and the dashboard's backend
    picker."""
-    return tuple(sorted(_BACKENDS))
+    return tuple(sorted(_get_backends()))


 def has_backend(name: str) -> bool:
@@ -657,9 +697,10 @@ def has_backend(name: str) -> bool:

    Returns False for unknown names so callers can pass
    arbitrary input without separate validation."""
-    if name not in _BACKENDS:
+    backends = _get_backends()
+    if name not in backends:
        return False
-    return _BACKENDS[name].is_available()
+    return backends[name].is_available()


 def enumerate_active_agents() -> list[ActiveAgent]:
@@ -675,10 +716,11 @@ def enumerate_active_agents() -> list[ActiveAgent]:
    deterministic tiebreaker. Agents with missing metadata
    (`started_at == ""`) sort first."""
    out: list[ActiveAgent] = []
-    for name in known_backend_names():
-        if not has_backend(name):
+    backends = _get_backends()
+    for name in sorted(backends):
+        if not backends[name].is_available():
            continue
-        out.extend(_BACKENDS[name].enumerate_active())
+        out.extend(backends[name].enumerate_active())
    out.sort(key=lambda a: (a.started_at, a.slug))
    return out

@@ -8,7 +8,7 @@ import os
 import re
 import shutil
 import subprocess
-from typing import Iterable, Iterator
+from typing import Iterator

 from ...docker_cmd import run_docker
 from ...log import die, info
@@ -32,12 +32,7 @@ def container_name_candidates(base: str) -> Iterator[str]:
 def runsc_available() -> bool:
    """Return True if the Docker daemon has the gVisor (`runsc`) runtime
    registered. Called once per prepare; the result lives on the plan."""
-    r = subprocess.run(
-        ["docker", "info", "--format", "{{json .Runtimes}}"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
+    r = run_docker(["docker", "info", "--format", "{{json .Runtimes}}"])
    return r.returncode == 0 and "runsc" in r.stdout


@@ -51,20 +46,15 @@ def require_docker() -> None:


 def image_exists(ref: str) -> bool:
-    return _silent_run(["docker", "image", "inspect", ref]) == 0
+    return run_docker(["docker", "image", "inspect", ref]).returncode == 0


 def container_exists(name: str) -> bool:
    """Returns True if a container (running or stopped) with the given
    name exists. Uses `docker ps -a -q -f name=^<name>$` so substring
    matches don't false-positive."""
-    result = subprocess.run(
-        ["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"],
-        capture_output=True,
-        text=True,
-        check=True,
-    )
-    return bool(result.stdout.strip())
+    result = run_docker(["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"])
+    return result.returncode == 0 and bool(result.stdout.strip())


 def force_remove_container(name: str) -> None:
@@ -72,12 +62,7 @@ def force_remove_container(name: str) -> None:
    doesn't — and the rm itself is best-effort (errors swallowed) so
    this is safe to register as a teardown callback."""
    if container_exists(name):
-        subprocess.run(
-            ["docker", "rm", "-f", name],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
+        run_docker(["docker", "rm", "-f", name])


 def docker_exec_root(container: str, argv: list[str]) -> None:
@@ -205,22 +190,10 @@ def verify_agent_image(image: str, argv: tuple[str, ...]) -> None:
 def commit_container(container_name: str, image_tag: str) -> None:
    """Run `docker commit <container_name> <image_tag>` to snapshot the
    running container's filesystem state as a local Docker image."""
-    result = subprocess.run(
-        ["docker", "commit", container_name, image_tag],
-        capture_output=True, text=True, check=False,
-    )
+    result = run_docker(["docker", "commit", container_name, image_tag])
    if result.returncode != 0:
        die(
            f"docker commit {container_name!r} → {image_tag!r} failed: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
    info(f"committed {container_name!r} → {image_tag!r}")
-
-
-def _silent_run(cmd: Iterable[str]) -> int:
-    return subprocess.run(
-        list(cmd),
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-        check=False,
-    ).returncode
@@ -0,0 +1,17 @@
+"""Shared wire-protocol constants for gateway-bundled modules.
+
+Single source of truth for values that appear across the egress addon,
+git-http backend, supervise server, and git-gate renderer. Importing
+from this module instead of duplicating the literals means a rename is
+a one-line change and is caught by the type checker at the import site."""
+
+# App-layer identity token header. Delivered as proxy credentials
+# (HTTPS_PROXY=http://<bottle_id>:<token>@gw) by launch; the egress
+# addon reads and strips it, the supervise server and git-http backend
+# read it for attribution, and none of them forward it upstream.
+IDENTITY_HEADER = "x-bot-bottle-identity"
+
+# Shared timeout (seconds) for all git-gate subprocess and CGI calls:
+# git daemon (--timeout/--init-timeout), the access-hook subprocess in
+# git_http_backend, and the git http-backend CGI subprocess.
+GIT_GATE_TIMEOUT_SECS = 15
@@ -23,8 +23,9 @@ from ...agent_provider import (
    provider_startup_args,
 )
 from ...backend.docker import util as docker_mod
-from ...egress import EgressRoute
+from ...egress import CLAUDE_HOST_CREDENTIAL_TOKEN_REF, EgressRoute
 from ...log import die, info, warn
+from .claude_auth import claude_host_access_token


 if TYPE_CHECKING:
@@ -118,7 +119,6 @@ class ClaudeAgentProvider(AgentProvider):
        color: str = "",
        provider_settings: dict[str, object] | None = None,
    ) -> AgentProvisionPlan:
-        del forward_host_credentials, host_env
        resolved_guest_env = dict(guest_env or {})
        startup_args = provider_startup_args(provider_settings)
        guest_home = self.guest_home
@@ -180,13 +180,24 @@ class ClaudeAgentProvider(AgentProvider):
                claude_settings,
                f"{guest_home}/.claude/settings.json",
            ))
+        provisioned_env: dict[str, str] = {}
+        if forward_host_credentials:
+            _host_env = host_env or dict(os.environ)
+            provisioned_env[CLAUDE_HOST_CREDENTIAL_TOKEN_REF] = (
+                claude_host_access_token(_host_env)
+            )
+
+        cred_token_ref = (
+            CLAUDE_HOST_CREDENTIAL_TOKEN_REF if forward_host_credentials
+            else auth_token
+        )
        egress_routes = (EgressRoute(
            host="api.anthropic.com",
-            auth_scheme="Bearer" if auth_token else "",
-            token_ref=auth_token,
+            auth_scheme="Bearer" if (auth_token or forward_host_credentials) else "",
+            token_ref=cred_token_ref,
        ),)
        hidden_env_names: frozenset[str] = frozenset()
-        if auth_token:
+        if auth_token or forward_host_credentials:
            env_vars["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
            hidden_env_names = frozenset({"CLAUDE_CODE_OAUTH_TOKEN"})

@@ -208,6 +219,7 @@ class ClaudeAgentProvider(AgentProvider):
            files=tuple(files),
            egress_routes=egress_routes,
            hidden_env_names=hidden_env_names,
+            provisioned_env=provisioned_env,
        )

    def provision_skills(self, plan: "BottlePlan", bottle: "Bottle") -> None:
@@ -0,0 +1,114 @@
+"""Host Claude auth helpers.
+
+Reads the host's Claude Code credentials and returns only the access
+token needed by egress. Does not expose refresh tokens or raw payloads.
+
+Credential storage by platform:
+  Linux  — ~/.claude/.credentials.json
+  macOS  — macOS Keychain, service "Claude Code-credentials"
+            (file path is tried first; Keychain is the fallback)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ...log import die
+
+
+_KEYCHAIN_SERVICE = "Claude Code-credentials"
+
+
+def claude_auth_path(host_env: dict[str, str] | None = None) -> Path:
+    env = os.environ if host_env is None else host_env
+    home = env.get("HOME")
+    if home:
+        return Path(home) / ".claude" / ".credentials.json"
+    return Path.home() / ".claude" / ".credentials.json"
+
+
+def _read_keychain() -> dict[str, object] | None:
+    """Try the macOS Keychain. Returns parsed JSON dict or None."""
+    if sys.platform != "darwin":
+        return None
+    try:
+        result = subprocess.run(
+            ["security", "find-generic-password", "-s", _KEYCHAIN_SERVICE, "-w"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0 or not result.stdout.strip():
+        return None
+    try:
+        raw = json.loads(result.stdout.strip())
+    except json.JSONDecodeError:
+        return None
+    return raw if isinstance(raw, dict) else None
+
+
+def claude_host_access_token(
+    host_env: dict[str, str] | None = None,
+    *,
+    now: datetime | None = None,
+) -> str:
+    path = claude_auth_path(host_env)
+    raw: dict[str, object] | None = None
+
+    if path.is_file():
+        try:
+            raw = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError) as e:
+            die(f"claude host credentials: could not read valid JSON at {path}: {e}")
+        if not isinstance(raw, dict):
+            die(f"claude host credentials: {path} must contain a JSON object")
+    else:
+        raw = _read_keychain()
+        if raw is None:
+            die(
+                f"claude host credentials: auth file missing at {path} and "
+                f"macOS Keychain lookup for '{_KEYCHAIN_SERVICE}' failed. "
+                "Run `claude login` on the host or disable "
+                "agent_provider.forward_host_credentials."
+            )
+
+    oauth = raw.get("claudeAiOauth")
+    if not isinstance(oauth, dict):
+        die(
+            "claude host credentials: claudeAiOauth is missing from credentials. "
+            "Run `claude login` on the host or disable "
+            "agent_provider.forward_host_credentials."
+        )
+
+    access_token = oauth.get("accessToken")
+    if not isinstance(access_token, str) or not access_token:
+        die(
+            "claude host credentials: claudeAiOauth.accessToken is missing or empty. "
+            "Run `claude login` on the host and restart the bottle."
+        )
+
+    # expiresAt is in milliseconds
+    expires_at = oauth.get("expiresAt")
+    if isinstance(expires_at, (int, float)):
+        check_now = now or datetime.now(timezone.utc)
+        exp_dt = datetime.fromtimestamp(float(expires_at) / 1000.0, timezone.utc)
+        if exp_dt <= check_now:
+            die(
+                "claude host credentials: host Claude access token is expired. "
+                "Run `claude login` on the host and restart the bottle."
+            )
+
+    return access_token
+
+
+__all__ = [
+    "claude_auth_path",
+    "claude_host_access_token",
+]
@@ -3,9 +3,8 @@
 Pure Python, no mitmproxy dependency. Each detector is a module-level
 function returning `ScanResult | None`.

-Ships flat into the gateway image alongside
-`egress_addon_core.py` — both this file and the package source use
-the same try/except import shim pattern.
+Available in the gateway via the installed `bot_bottle` package
+(see `Dockerfile.gateway`).
 """

 from __future__ import annotations
@@ -20,10 +19,7 @@ from math import log2
 from collections import Counter
 from urllib.parse import quote as url_quote

-try:
-    from egress_addon_core import ScanResult  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover - host-side path
-    from .egress_addon_core import ScanResult
+from .egress_addon_core import ScanResult


 # ---------------------------------------------------------------------------
@@ -30,6 +30,7 @@ if TYPE_CHECKING:
    from .manifest import ManifestBottle

 CODEX_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CODEX_HOST_ACCESS_TOKEN"
+CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"

 EGRESS_HOSTNAME = "egress"

@@ -400,6 +401,7 @@ class Egress(ABC):
        )

 __all__ = [
+    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
    "CODEX_HOST_CREDENTIAL_TOKEN_REF",
    "EGRESS_HOSTNAME",
    "EGRESS_ROUTES_FILENAME",
@@ -15,7 +15,9 @@ import typing

 from mitmproxy import http  # type: ignore[import-not-found]  # pylint: disable=import-error

-from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: disable=import-error
+from bot_bottle.constants import IDENTITY_HEADER
+from bot_bottle.dlp_detectors import redact_tokens, strip_crlf
+from bot_bottle.egress_addon_core import (
    LOG_BLOCKS,
    LOG_FULL,
    DEFAULT_OUTBOUND_ON_MATCH,
@@ -38,24 +40,8 @@ from egress_addon_core import (  # type: ignore[import-not-found]  # pylint: dis
    scan_inbound,
    scan_outbound,
 )
-
-try:
-    from dlp_detectors import redact_tokens, strip_crlf  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover - host-side path
-    from bot_bottle.dlp_detectors import (  # type: ignore[import-not-found]
-        redact_tokens,
-        strip_crlf,
-    )
-
-try:
-    import supervise as _sv  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover - host-side path
-    from bot_bottle import supervise as _sv  # type: ignore[import-not-found]
-
-try:
-    from policy_resolver import PolicyResolver  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover - host-side path
-    from bot_bottle.policy_resolver import PolicyResolver
+from bot_bottle import supervise as _sv
+from bot_bottle.policy_resolver import PolicyResolver


 INTROSPECT_HOST = "_egress.local"
@@ -66,13 +52,6 @@ INTROSPECT_HOST = "_egress.local"
 # back to — so an unset value is a fatal misconfiguration (see __init__).
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"

-# App-layer identity token. Delivered as proxy credentials
-# (`HTTPS_PROXY=http://<bottle_id>:<token>@gw`): clients honor it as part of
-# the proxy protocol without app changes, and the addon reads + strips it so
-# it never leaks upstream. The legacy `x-bot-bottle-identity` request header
-# is still stripped defensively (git-http uses that header on its own port).
-IDENTITY_HEADER = "x-bot-bottle-identity"
-
 # Per-flow key under which `request()` stashes the resolved (Config, supervise
 # slug, env) so the later `response()` and `websocket_message()` hooks scan
 # against the *calling bottle's* policy — the same one the request was decided
@@ -6,9 +6,9 @@ exercise the parse + decision functions without depending on the
 `mitmproxy.http.HTTPFlow` API and is loaded inside the gateway
 container.

-Imports: stdlib + `yaml_subset` (which is itself stdlib-only and
-ships flat into the gateway image alongside this file —
-see `Dockerfile.gateway`)."""
+Imports: stdlib + sibling package modules (`yaml_subset`,
+`egress_dlp_config`). Available in the gateway via the installed
+`bot_bottle` package (see `Dockerfile.gateway`)."""

 from __future__ import annotations

@@ -16,36 +16,20 @@ import re
 import typing
 from dataclasses import dataclass

-try:
-    from yaml_subset import YamlSubsetError, parse_yaml_subset  # type: ignore[import-not-found]
-except ImportError:  # pragma: no cover - host-side path
-    from .yaml_subset import YamlSubsetError, parse_yaml_subset
+from .yaml_subset import YamlSubsetError, parse_yaml_subset

-# DLP detector-config parsing lives in a sibling module (also flat-bundled
-# into the gateway — see Dockerfile.gateway). Re-exported below so existing
-# `from egress_addon_core import ON_MATCH_*` callers keep working.
-try:
-    from egress_dlp_config import (  # type: ignore[import-not-found]
-        DEFAULT_OUTBOUND_ON_MATCH,
-        INBOUND_DETECTOR_NAMES,
-        ON_MATCH_BLOCK,
-        ON_MATCH_REDACT,
-        ON_MATCH_SUPERVISE,
-        OUTBOUND_DETECTOR_NAMES,
-        OUTBOUND_ON_MATCH_VALUES,
-        parse_dlp_block,
-    )
-except ImportError:  # pragma: no cover - host-side path
-    from .egress_dlp_config import (
-        DEFAULT_OUTBOUND_ON_MATCH,
-        INBOUND_DETECTOR_NAMES,
-        ON_MATCH_BLOCK,
-        ON_MATCH_REDACT,
-        ON_MATCH_SUPERVISE,
-        OUTBOUND_DETECTOR_NAMES,
-        OUTBOUND_ON_MATCH_VALUES,
-        parse_dlp_block,
-    )
+# DLP detector-config parsing lives in a sibling module. Re-exported below
+# so existing `from egress_addon_core import ON_MATCH_*` callers keep working.
+from .egress_dlp_config import (
+    DEFAULT_OUTBOUND_ON_MATCH,
+    INBOUND_DETECTOR_NAMES,
+    ON_MATCH_BLOCK,
+    ON_MATCH_REDACT,
+    ON_MATCH_SUPERVISE,
+    OUTBOUND_DETECTOR_NAMES,
+    OUTBOUND_ON_MATCH_VALUES,
+    parse_dlp_block,
+)


 # ---------------------------------------------------------------------------
@@ -78,8 +78,8 @@ def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
 _DAEMONS: tuple[_DaemonSpec, ...] = (
    _DaemonSpec("egress", ("/bin/sh", "/app/egress-entrypoint.sh")),
    _DaemonSpec("git-gate", ("/bin/sh", "/git-gate-entrypoint.sh")),
-    _DaemonSpec("git-http", ("python3", "/app/git_http_backend.py")),
-    _DaemonSpec("supervise", ("python3", "/app/supervise_server.py")),
+    _DaemonSpec("git-http", ("python3", "-m", "bot_bottle.git_http_backend")),
+    _DaemonSpec("supervise", ("python3", "-m", "bot_bottle.supervise_server")),
 )


@@ -14,18 +14,12 @@ import shlex
 from dataclasses import dataclass
 from pathlib import Path

+from .constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
 from .manifest import ManifestBottle, ManifestGitEntry

 # Short network alias for git-gate inside the gateway. The
 # agent's `.gitconfig` insteadOf rewrites resolve through this name.
 GIT_GATE_HOSTNAME = "git-gate"
-# App-layer identity token header the agent's git sends to git-http and the
-# gateway validates (mirrors egress_addon / git_http_backend IDENTITY_HEADER).
-IDENTITY_HEADER = "x-bot-bottle-identity"
-# Shared timeout (seconds) for all git-gate subprocess and CGI calls:
-# git daemon (--timeout/--init-timeout), the access-hook subprocess in
-# git_http_backend, and the git http-backend CGI subprocess.
-GIT_GATE_TIMEOUT_SECS = 15


@dataclass(frozen=True)
@@ -26,16 +26,8 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from urllib.parse import urlsplit

-# policy_resolver ships flat alongside this file in the gateway
-# image (see Dockerfile.gateway); the bot_bottle.* fallback is the
-# host-side / test path. Mirrors egress_addon's import shape.
-try:
-    from policy_resolver import (  # type: ignore[import-not-found]
-        PolicyResolveError,
-        PolicyResolver,
-    )
-except ImportError:  # pragma: no cover - host-side path
-    from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
+from bot_bottle.constants import GIT_GATE_TIMEOUT_SECS, IDENTITY_HEADER
+from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver


 DEFAULT_PORT = 9420
@@ -46,12 +38,6 @@ DEFAULT_PORT = 9420
 # repo-root fallback.
 ORCHESTRATOR_URL_ENV = "BOT_BOTTLE_ORCHESTRATOR_URL"

-# App-layer identity token (defense-in-depth over the source-IP invariant);
-# the agent injects it, the backend reads it for attribution and never
-# forwards it to `git http-backend`. Mirrors egress_addon.IDENTITY_HEADER
-# (duplicated, not imported: egress_addon pulls in mitmproxy).
-IDENTITY_HEADER = "x-bot-bottle-identity"
-
 # The base under which each bottle's `<bottle_id>` repo namespace is nested.
 DEFAULT_REPO_ROOT = "/git"

@@ -89,13 +75,6 @@ def resolve_sandbox_root(
        return None  # bottle_id tried to escape the root → deny
    return namespace

-# Mirrors git_gate_render.GIT_GATE_TIMEOUT_SECS. Duplicated rather than
-# imported: this module ships as a flat top-level sibling in the gateway
-# bundle image (see Dockerfile.gateway), not as part of the bot_bottle
-# package, so `bot_bottle.git_gate` and its dependency chain aren't
-# available at runtime.
-GIT_GATE_TIMEOUT_SECS = 15
-
 # Bound memory use while still allowing ordinary git push packfiles.
 MAX_BODY_BYTES = 100 * 1024 * 1024

@@ -25,8 +25,9 @@ class ManifestAgentProvider:
    header, and sets a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent
    so the Claude Code CLI starts.

-    `forward_host_credentials` forwards the host Codex auth token into
-    the egress daemon (Codex only).
+    `forward_host_credentials` forwards the host provider auth token into
+    the egress sidecar (Codex and Claude). For Codex this reads
+    `~/.codex/auth.json`; for Claude it reads `~/.claude/.credentials.json`.
    """

    template: str = "claude"
@@ -92,10 +93,15 @@ class ManifestAgentProvider:
                f"is only supported for built-in templates "
                f"({', '.join(sorted(PROVIDER_TEMPLATES))})"
            )
-        if forward_host_credentials and template != "codex":
+        if forward_host_credentials and template not in {"codex", "claude"}:
            raise ManifestError(
                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "is currently only supported for template 'codex'"
+                "is only supported for templates 'codex' and 'claude'"
+            )
+        if forward_host_credentials and auth_token:
+            raise ManifestError(
+                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
+                "and auth_token both set; use one or the other"
            )
        settings = _parse_provider_settings(bottle_name, template, d.get("settings"))
        return cls(
@@ -22,8 +22,7 @@ closed too rather than silently serving stale or empty policy.

 The resolved value is the policy blob the orchestrator stores verbatim; the
 consumer parses it (e.g. the egress addon's `load_config`). This module is
-stdlib-only and free of bot-bottle imports so it can be COPYed flat into
-the gateway.
+stdlib-only and free of bot-bottle imports.
 """

 from __future__ import annotations
@@ -37,40 +37,22 @@ from abc import ABC
 from dataclasses import dataclass
 from pathlib import Path

-try:
-    from .supervise_types import (
-        ACTION_OPERATOR_EDIT,
-        AuditEntry,
-        Proposal,
-        Response,
-        STATUSES,
-        STATUS_APPROVED,
-        STATUS_MODIFIED,
-        STATUS_REJECTED,
-        TOOLS,
-        TOOL_EGRESS_ALLOW,
-        TOOL_EGRESS_BLOCK,
-        TOOL_EGRESS_TOKEN_ALLOW,
-        TOOL_GITLEAKS_ALLOW,
-        TOOL_LIST_EGRESS_ROUTES,
-    )
-except ImportError:
-    from supervise_types import (  # type: ignore[import-not-found,no-redef]  # pylint: disable=import-error,no-name-in-module
-        ACTION_OPERATOR_EDIT,
-        AuditEntry,
-        Proposal,
-        Response,
-        STATUSES,
-        STATUS_APPROVED,
-        STATUS_MODIFIED,
-        STATUS_REJECTED,
-        TOOLS,
-        TOOL_EGRESS_ALLOW,
-        TOOL_EGRESS_BLOCK,
-        TOOL_EGRESS_TOKEN_ALLOW,
-        TOOL_GITLEAKS_ALLOW,
-        TOOL_LIST_EGRESS_ROUTES,
-    )
+from .supervise_types import (
+    ACTION_OPERATOR_EDIT,
+    AuditEntry,
+    Proposal,
+    Response,
+    STATUSES,
+    STATUS_APPROVED,
+    STATUS_MODIFIED,
+    STATUS_REJECTED,
+    TOOLS,
+    TOOL_EGRESS_ALLOW,
+    TOOL_EGRESS_BLOCK,
+    TOOL_EGRESS_TOKEN_ALLOW,
+    TOOL_GITLEAKS_ALLOW,
+    TOOL_LIST_EGRESS_ROUTES,
+)


 try:
@@ -26,9 +26,8 @@ Speaks MCP over HTTP+JSON-RPC. Methods handled:

 Everything else returns JSON-RPC error -32601 (method not found).

-Stdlib-only. The Dockerfile copies this file + bot_bottle/supervise.py
-into the image; the server imports `supervise` for the queue / Proposal
-plumbing.
+The Dockerfile copies this script to /app/supervise_server.py and installs
+the bot_bottle package so its `from bot_bottle.*` imports resolve.
 """

 from __future__ import annotations
@@ -42,29 +41,18 @@ import time
 import typing
 from dataclasses import dataclass, replace

-try:
-    # Same-directory imports inside the bundle container; these files are
-    # COPYed flat under /app by Dockerfile.gateway.
-    from egress_addon_core import (
-        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
-    )
-    from policy_resolver import PolicyResolveError, PolicyResolver
-    import supervise as _sv
-except ModuleNotFoundError:
-    # Package imports for host-side tests and tooling.
-    from .egress_addon_core import (
-        LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
-    )
-    from .policy_resolver import PolicyResolveError, PolicyResolver
-    from . import supervise as _sv
+from bot_bottle.constants import IDENTITY_HEADER
+from bot_bottle.egress_addon_core import (
+    LOG_OFF, load_config, resolve_client_context, route_to_yaml_dict,
+)
+from bot_bottle.policy_resolver import PolicyResolveError, PolicyResolver
+from bot_bottle import supervise as _sv


 # --- JSON-RPC / MCP plumbing ----------------------------------------------


 MCP_PROTOCOL_VERSION = "2024-11-05"
-# App-layer identity token header (mirrors egress_addon / git_http_backend).
-IDENTITY_HEADER = "x-bot-bottle-identity"
 SERVER_NAME = "bot-bottle-supervise"
 SERVER_VERSION = "0.1.0"

@@ -1,57 +0,0 @@
-# ADR 0005: Keep tracker metadata on issues
-
- **Status:** Accepted
- **Date:** 2026-07-18
- **Deciders:** didericis
-
-## Context
-
-Gitea exposes labels on both issues and pull requests. Applying the same labels
-to both copies planning metadata, creates a synchronization obligation, and
-makes disagreements between the two records possible. At the same time,
-unlabelled objects look accidental unless the repository states which object
-owns the metadata.
-
-The repository already uses issues as work items and PRs as implementations of
-those work items. At this decision's cutoff, all open PRs reference issues, but
-121 of 219 historically merged PRs do not. Manufacturing retrospective issues
-for that history would create records that never participated in planning and
-would make the issue history less truthful.
-
-## Decision
-
-Issues are the canonical tracker records and own labels. Every issue has at
-least one label. An issue opened or left without labels receives
-`Status/Needs Triage` automatically until it is classified.
-
-Pull requests carry no labels. Every new PR deliberately references at least
-one existing issue in its title or description with one of these forms:
-
- `Closes #123`, `Fixes #123`, or `Resolves #123` when merging completes it.
- `Part of #123`, `Related to #123`, `Refs #123`, or `References #123` when it
-  contributes without completing it.
-
-Gitea Actions enforces both PR rules as a status check and repairs the empty
-issue-label state. Branch protection makes the PR policy check required.
-
-The policy applies from 2026-07-18 onward. Existing issues may be labelled as
-they are encountered, but closed PRs are grandfathered: no retrospective
-issues or PR labels are created solely to make history conform.
-
-## Consequences
-
- Classification, priority, and workflow metadata have one source of truth.
- A PR's issue link is the navigation path to its planning metadata.
- Multi-PR issues do not require copied or synchronized labels.
- `Status/Needs Triage` is an intentional fallback, not a final
-  classification.
- Direct issue creation remains convenient; automation repairs a missing label
-  immediately after creation because Gitea has no native required-label rule.
- The required check must be configured in branch protection after this
-  workflow lands.
-
-## Links
-
- Issue #405.
- `.gitea/workflows/tracker-policy.yml`.
- `scripts/tracker_policy.py`.
@@ -0,0 +1,146 @@
+# PRD prd-new: Claude forward_host_credentials
+
+- **Status:** Draft
+- **Author:** claude
+- **Created:** 2026-07-01
+- **Issue:** #325
+
+## Summary
+
+Add `agent_provider.forward_host_credentials: true` support for the
+`claude` template, mirroring the existing Codex flow. When enabled,
+bot-bottle reads the host's Claude OAuth session key from
+`~/.claude/.credentials.json` at launch, forwards it only to the egress sidecar,
+and injects a placeholder `CLAUDE_CODE_OAUTH_TOKEN` into the agent so
+Claude Code starts without ever seeing the real credential.
+
+## Problem
+
+Running a Claude agent in a container today requires the operator to
+manually extract a long-lived OAuth token (`claude setup-token`), export
+it as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`, and reference it explicitly in
+the manifest with `agent_provider.auth_token:
+"BOT_BOTTLE_CLAUDE_OAUTH_TOKEN"`. This is a two-step manual ceremony
+that is easy to skip or do incorrectly.
+
+The host already stores a valid Claude session in `~/.claude/.credentials.json`
+after `claude login`. Codex already automates an
+equivalent extraction from `~/.codex/auth.json`. There is no reason
+Claude bottles cannot do the same.
+
+## Goals / Success Criteria
+
+- A Claude bottle with `forward_host_credentials: true` in the manifest
+  uses the host's `~/.claude/.credentials.json` session key at launch with no
+  additional operator steps.
+- The agent container receives only `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder`
+  — never the real token.
+- The real session key lives only in the egress sidecar's environment.
+- Missing, malformed, or expired host Claude auth fails launch with a
+  clear operator-facing message.
+- Existing `auth_token` behavior is unchanged.
+- `forward_host_credentials: true` is rejected in the manifest when both
+  `auth_token` and `forward_host_credentials` are set, since they serve
+  the same purpose.
+
+## Non-goals
+
+- Refreshing Claude OAuth tokens in the sidecar.
+- Writing a dummy `~/.claude.json` auth state to the agent (unlike the
+  Codex flow, Claude Code reads its credential from `CLAUDE_CODE_OAUTH_TOKEN`
+  in env, not from an auth file — no guest-side auth marker is needed).
+- Supporting `forward_host_credentials` for providers other than `codex`
+  and `claude`.
+
+## Design
+
+### Manifest schema
+
+```yaml
+agent_provider:
+  template: claude
+  forward_host_credentials: true
+```
+
+Rejects in manifest validation when:
+- Template is not `codex` or `claude`.
+- Both `auth_token` and `forward_host_credentials` are set.
+
+### Host auth extraction (`contrib/claude/claude_auth.py`)
+
+Claude Code credential storage varies by platform:
+
+- **Linux**: `~/.claude/.credentials.json`
+- **macOS**: macOS Keychain, service `"Claude Code-credentials"`
+  (the file path is tried first; Keychain is the fallback when the file
+  is absent)
+
+`~/.claude.json` contains only UI state and profile metadata — no token.
+
+The credentials JSON schema (same whether from file or Keychain):
+
+```json
+{
+  "claudeAiOauth": {
+    "accessToken": "<access-token>",
+    "refreshToken": "<refresh-token>",
+    "expiresAt": 1748276587173,
+    "scopes": ["user:inference", "user:profile"]
+  }
+}
+```
+
+`expiresAt` is in **milliseconds** (not seconds).
+
+At prepare/launch time, when `forward_host_credentials: true`:
+
+1. Try `~/.claude/.credentials.json`; on macOS, if absent, run
+   `security find-generic-password -s "Claude Code-credentials" -w`
+   and parse its stdout as JSON.
+2. Require a `claudeAiOauth` dict.
+3. Require a non-empty `claudeAiOauth.accessToken` string.
+4. If `claudeAiOauth.expiresAt` is present, divide by 1000 and require
+   the result to be in the future.
+5. Return only the access token to the launch path.
+
+Errors name the missing or invalid condition and point the operator at
+`claude login`, without printing token values.
+
+### Egress route
+
+When `forward_host_credentials: true`:
+
+- Provision the session key in `provisioned_env` under
+  `BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN` (new constant in `egress.py`).
+- Set up the `api.anthropic.com` egress route with `auth_scheme: Bearer`
+  and `token_ref: BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN`.
+- Set `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder` in the agent env and
+  add it to `hidden_env_names`.
+
+No dummy auth file and no `verify` step are needed — Claude Code reads
+the credential from the env var, not from a file.
+
+### Constants
+
+- `CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"`
+  in `egress.py` (alongside the existing `CODEX_HOST_CREDENTIAL_TOKEN_REF`).
+- `CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)` in
+  `agent_provider.py` (alongside the existing `CODEX_HOST_CREDENTIAL_HOSTS`).
+
+### Data flow
+
+```
+Host ~/.claude/.credentials.json  →  bot-bottle launch
+                            │
+                            ├──► egress sidecar env (real token only)
+                            │
+                            └──► agent env: CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder
+
+Agent  →  HTTPS to api.anthropic.com (via egress)
+Egress →  injects Authorization: Bearer <real token>
+Egress →  forwards to api.anthropic.com
+```
+
+## Open questions
+
+None — the Codex precedent makes the design clear.
@@ -0,0 +1,8 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "bot-bottle"
+version = "0.0.0"
+requires-python = ">=3.11"
@@ -1,135 +0,0 @@
-#!/usr/bin/env python3
-"""Enforce the repository's issue/PR metadata policy in Gitea Actions."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import urllib.error
-import urllib.request
-from pathlib import Path
-from typing import Any
-
-
-ISSUE_REFERENCE = re.compile(
-    r"(?im)\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|part\s+of|"
-    r"related\s+to|refs?|references)\s+#(\d+)\b"
-)
-TRIAGE_LABEL = "Status/Needs Triage"
-
-
-def deliberate_issue_numbers(title: str, body: str) -> set[int]:
-    """Return same-repository issue numbers referenced intentionally."""
-    return {int(match) for match in ISSUE_REFERENCE.findall(f"{title}\n{body}")}
-
-
-class GiteaApi:
-    """Small API client using the Actions-provided repository token."""
-
-    def __init__(self, api_url: str, repository: str, token: str) -> None:
-        self.base = f"{api_url.rstrip('/')}/repos/{repository}"
-        self.token = token
-
-    def request(self, method: str, path: str, payload: object | None = None) -> Any:
-        data = None if payload is None else json.dumps(payload).encode()
-        request = urllib.request.Request(
-            f"{self.base}{path}",
-            data=data,
-            method=method,
-            headers={
-                "Authorization": f"token {self.token}",
-                "Content-Type": "application/json",
-            },
-        )
-        with urllib.request.urlopen(request, timeout=15) as response:
-            if response.status == 204:
-                return None
-            return json.load(response)
-
-
-def check_pull_request(event: dict[str, Any], api: GiteaApi) -> list[str]:
-    """Return policy violations for a pull_request event."""
-    pull = event["pull_request"]
-    errors: list[str] = []
-    labels = pull.get("labels") or []
-    if labels:
-        errors.append(
-            "PRs must be unlabeled; put tracker metadata on the linked issue "
-            f"(found: {', '.join(label['name'] for label in labels)})."
-        )
-
-    numbers = deliberate_issue_numbers(pull.get("title", ""), pull.get("body", ""))
-    if not numbers:
-        errors.append(
-            "PR must reference an issue with Closes/Fixes/Resolves #N, "
-            "Part of #N, Related to #N, Refs #N, or References #N."
-        )
-        return errors
-
-    real_issues = 0
-    for number in sorted(numbers):
-        try:
-            item = api.request("GET", f"/issues/{number}")
-        except urllib.error.HTTPError as error:
-            if error.code == 404:
-                errors.append(f"Referenced issue #{number} does not exist.")
-                continue
-            raise
-        if item.get("pull_request") is not None:
-            errors.append(f"#{number} is a pull request, not an issue.")
-        else:
-            real_issues += 1
-
-    if not real_issues and not errors:
-        errors.append("PR must reference at least one real issue.")
-    return errors
-
-
-def ensure_issue_label(event: dict[str, Any], api: GiteaApi) -> bool:
-    """Apply the triage label if an issue event leaves the issue unlabeled."""
-    issue = event["issue"]
-    if issue.get("pull_request") is not None or issue.get("labels"):
-        return False
-    labels = api.request("GET", "/labels?limit=100")
-    triage = next((label for label in labels if label["name"] == TRIAGE_LABEL), None)
-    if triage is None:
-        raise RuntimeError(f"repository label {TRIAGE_LABEL!r} does not exist")
-    api.request("POST", f"/issues/{issue['number']}/labels", {"labels": [triage["id"]]})
-    return True
-
-
-def _load_event(path: str) -> dict[str, Any]:
-    return json.loads(Path(path).read_text(encoding="utf-8"))
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("command", choices=("check-pr", "label-issue"))
-    parser.add_argument("--event", default=os.environ.get("GITHUB_EVENT_PATH"))
-    args = parser.parse_args()
-    if not args.event:
-        parser.error("--event or GITHUB_EVENT_PATH is required")
-
-    api = GiteaApi(
-        os.environ["GITHUB_API_URL"],
-        os.environ["GITHUB_REPOSITORY"],
-        os.environ["GITHUB_TOKEN"],
-    )
-    event = _load_event(args.event)
-    if args.command == "check-pr":
-        errors = check_pull_request(event, api)
-        if errors:
-            print("\n".join(f"::error::{error}" for error in errors))
-            return 1
-        print("PR tracker policy passed.")
-        return 0
-
-    changed = ensure_issue_label(event, api)
-    print(f"Applied {TRIAGE_LABEL}." if changed else "Issue already has a label.")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
@@ -9,11 +9,15 @@ import unittest
 from pathlib import Path

 from bot_bottle.agent_provider import (
+    CLAUDE_HOST_CREDENTIAL_HOSTS,
    CODEX_HOST_CREDENTIAL_HOSTS,
    build_agent_provision_plan,
    prompt_args,
 )
-from bot_bottle.egress import CODEX_HOST_CREDENTIAL_TOKEN_REF
+from bot_bottle.egress import (
+    CLAUDE_HOST_CREDENTIAL_TOKEN_REF,
+    CODEX_HOST_CREDENTIAL_TOKEN_REF,
+)


 def _jwt(exp: int) -> str:
@@ -292,6 +296,67 @@ class TestAgentProviderRuntime(unittest.TestCase):
            )
        self.assertEqual({}, plan.provisioned_env)

+    def test_claude_forward_host_credentials_populates_egress_route(self):
+        access_token = "sk-ant-oat01-test-key"  # gitleaks:allow
+        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
+            home = Path(tmp) / "host-claude"
+            cred_dir = home / ".claude"
+            cred_dir.mkdir(parents=True)
+            (cred_dir / ".credentials.json").write_text(json.dumps({
+                "claudeAiOauth": {"accessToken": access_token},
+            }))
+            plan = build_agent_provision_plan(
+                template="claude",
+                dockerfile="",
+                state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
+                forward_host_credentials=True,
+                host_env={"HOME": str(home)},
+            )
+        self.assertEqual(1, len(plan.egress_routes))
+        route = plan.egress_routes[0]
+        self.assertIn(route.host, CLAUDE_HOST_CREDENTIAL_HOSTS)
+        self.assertEqual("Bearer", route.auth_scheme)
+        self.assertEqual(CLAUDE_HOST_CREDENTIAL_TOKEN_REF, route.token_ref)
+        self.assertEqual("egress-placeholder", plan.env_vars["CLAUDE_CODE_OAUTH_TOKEN"])
+        self.assertEqual(frozenset({"CLAUDE_CODE_OAUTH_TOKEN"}), plan.hidden_env_names)
+
+    def test_claude_forward_host_credentials_populates_provisioned_env(self):
+        access_token = "sk-ant-oat01-test-key"  # gitleaks:allow
+        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
+            home = Path(tmp) / "host-claude"
+            cred_dir = home / ".claude"
+            cred_dir.mkdir(parents=True)
+            (cred_dir / ".credentials.json").write_text(json.dumps({
+                "claudeAiOauth": {"accessToken": access_token},
+            }))
+            plan = build_agent_provision_plan(
+                template="claude",
+                dockerfile="",
+                state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
+                forward_host_credentials=True,
+                host_env={"HOME": str(home)},
+            )
+        self.assertEqual(
+            {CLAUDE_HOST_CREDENTIAL_TOKEN_REF: access_token},
+            plan.provisioned_env,
+        )
+
+    def test_claude_without_forward_host_credentials_has_empty_provisioned_env(self):
+        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
+            plan = build_agent_provision_plan(
+                template="claude",
+                dockerfile="",
+                state_dir=Path(tmp),
+                instance_name="bot-bottle-test",
+                prompt_file=Path(tmp) / "prompt.txt",
+                forward_host_credentials=False,
+            )
+        self.assertEqual({}, plan.provisioned_env)
+
    def test_pi_plan_writes_default_ollama_models(self):
        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
            plan = build_agent_provision_plan(
@@ -40,7 +40,7 @@ class TestGetBottleBackend(unittest.TestCase):
                return True

        with patch.dict(os.environ, {}, clear=True), \
-             patch.object(backend_mod, "_BACKENDS", {
+             patch.object(backend_mod, "_backends", {
                 "macos-container": _FakeBackend(),
                 "docker": _FakeBackend(),
             }):
@@ -61,7 +61,7 @@ class TestGetBottleBackend(unittest.TestCase):
        with patch.dict(os.environ, {}, clear=True), \
             patch.object(backend_mod.FirecrackerBottleBackend,
                          "is_host_capable", classmethod(lambda cls: False)), \
-             patch.object(backend_mod, "_BACKENDS", {
+             patch.object(backend_mod, "_backends", {
                 "macos-container": _FakeBackend("macos-container", False),
                 "docker": _FakeBackend("docker", True),
             }):
@@ -83,7 +83,7 @@ class TestGetBottleBackend(unittest.TestCase):
        with patch.dict(os.environ, {}, clear=True), \
             patch.object(backend_mod.FirecrackerBottleBackend,
                          "is_host_capable", classmethod(lambda cls: True)), \
-             patch.object(backend_mod, "_BACKENDS", {
+             patch.object(backend_mod, "_backends", {
                 "macos-container": _FakeBackend("macos-container", False),
                 "firecracker": _FakeBackend("firecracker", False),
                 "docker": _FakeBackend("docker", True),
@@ -133,7 +133,7 @@ class TestEnumerateActiveAgents(unittest.TestCase):
                return self._items

        with patch.object(
-            backend_mod, "_BACKENDS",
+            backend_mod, "_backends",
            {"docker": _FakeBackend([a]), "firecracker": _FakeBackend([b])},
        ):
            self.assertEqual([a, b], enumerate_active_agents())
@@ -167,7 +167,7 @@ class TestEnumerateActiveAgents(unittest.TestCase):
                return self._items

        with patch.object(
-            backend_mod, "_BACKENDS",
+            backend_mod, "_backends",
            {
                "docker": _FakeBackend([newer, tie_b]),
                "firecracker": _FakeBackend([missing_metadata, tie_a]),
@@ -187,7 +187,7 @@ class TestEnumerateActiveAgents(unittest.TestCase):
                return []

        with patch.object(
-            backend_mod, "_BACKENDS",
+            backend_mod, "_backends",
            {"docker": _FakeBackend(), "firecracker": _FakeBackend()},
        ):
            self.assertEqual([], enumerate_active_agents())
@@ -218,7 +218,7 @@ class TestEnumerateActiveAgents(unittest.TestCase):
                return self._items

        with patch.object(
-            backend_mod, "_BACKENDS",
+            backend_mod, "_backends",
            {
                "docker": _FakeBackend([present], available=True),
                "firecracker": _FakeBackend([hidden], available=False),
@@ -234,7 +234,7 @@ class TestHasBackend(unittest.TestCase):
                return False

        with patch.object(
-            backend_mod, "_BACKENDS", {"docker": _FakeBackend()},
+            backend_mod, "_backends", {"docker": _FakeBackend()},
        ):
            from bot_bottle.backend import has_backend
            self.assertFalse(has_backend("docker"))
@@ -0,0 +1,186 @@
+"""Unit: host Claude auth extraction."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.contrib.claude.claude_auth import (
+    claude_auth_path,
+    claude_host_access_token,
+)
+from bot_bottle.log import Die
+
+
+def _cred_json(access_token: str, **extra: object) -> str:
+    payload: dict[str, object] = {"claudeAiOauth": {"accessToken": access_token, **extra}}
+    return json.dumps(payload)
+
+
+class TestClaudeHostAccessToken(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory(prefix="bb-claude-auth.")
+        self.home = Path(self.tmp.name)
+        self.cred_dir = self.home / ".claude"
+        self.cred_dir.mkdir()
+        self.auth_path = self.cred_dir / ".credentials.json"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _write(self, payload: dict) -> None:  # type: ignore[no-untyped-def]
+        self.auth_path.write_text(json.dumps(payload))
+
+    def test_auth_path_uses_home_env(self):
+        self.assertEqual(
+            self.auth_path,
+            claude_auth_path({"HOME": str(self.home)}),
+        )
+
+    # --- file-based (Linux) ---
+
+    def test_file_returns_access_token(self):
+        key = "sk-ant-oat01-real-key"  # gitleaks:allow
+        self._write({"claudeAiOauth": {"accessToken": key}})
+        out = claude_host_access_token({"HOME": str(self.home)})
+        self.assertEqual(key, out)
+
+    def test_file_missing_claude_ai_oauth_dies(self):
+        self._write({"hasCompletedOnboarding": True})
+        with self.assertRaises(Die):
+            claude_host_access_token({"HOME": str(self.home)})
+
+    def test_file_missing_access_token_dies(self):
+        self._write({"claudeAiOauth": {"expiresAt": 2000000000000}})
+        with self.assertRaises(Die):
+            claude_host_access_token({"HOME": str(self.home)})
+
+    def test_file_empty_access_token_dies(self):
+        self._write({"claudeAiOauth": {"accessToken": ""}})
+        with self.assertRaises(Die):
+            claude_host_access_token({"HOME": str(self.home)})
+
+    def test_file_expired_token_dies(self):
+        # expiresAt is milliseconds; 1_000_000 ms is year 1970
+        self._write({
+            "claudeAiOauth": {"accessToken": "sk-ant-oat01-x", "expiresAt": 1_000_000},  # gitleaks:allow
+        })
+        with self.assertRaises(Die):
+            claude_host_access_token(
+                {"HOME": str(self.home)},
+                now=datetime(2026, 1, 1, tzinfo=timezone.utc),
+            )
+
+    def test_file_future_expiry_is_accepted(self):
+        key = "sk-ant-oat01-y"  # gitleaks:allow
+        # 2_000_000_000_000 ms ≈ year 2033
+        self._write({
+            "claudeAiOauth": {"accessToken": key, "expiresAt": 2_000_000_000_000},
+        })
+        out = claude_host_access_token(
+            {"HOME": str(self.home)},
+            now=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        )
+        self.assertEqual(key, out)
+
+    def test_file_absent_expiry_is_accepted(self):
+        key = "sk-ant-oat01-z"  # gitleaks:allow
+        self._write({"claudeAiOauth": {"accessToken": key}})
+        out = claude_host_access_token({"HOME": str(self.home)})
+        self.assertEqual(key, out)
+
+    def test_file_non_json_dies(self):
+        self.auth_path.write_text("not json {{{")
+        with self.assertRaises(Die):
+            claude_host_access_token({"HOME": str(self.home)})
+
+    def test_file_json_array_root_dies(self):
+        self.auth_path.write_text("[]")
+        with self.assertRaises(Die):
+            claude_host_access_token({"HOME": str(self.home)})
+
+    def test_file_extra_fields_are_ignored(self):
+        key = "sk-ant-oat01-real"  # gitleaks:allow
+        self._write({
+            "claudeAiOauth": {
+                "accessToken": key,
+                "refreshToken": "sk-ant-ort01-secret",  # gitleaks:allow
+                "scopes": ["user:inference"],
+                "expiresAt": 2_000_000_000_000,
+            },
+        })
+        out = claude_host_access_token({"HOME": str(self.home)})
+        self.assertEqual(key, out)
+
+    # --- macOS Keychain fallback ---
+
+    def _home_without_creds(self) -> Path:
+        """A home dir that has .claude/ but no .credentials.json."""
+        empty = self.home / "no-creds"
+        (empty / ".claude").mkdir(parents=True)
+        return empty
+
+    def _mock_keychain(self, stdout: str, returncode: int = 0) -> MagicMock:
+        mock = MagicMock()
+        mock.returncode = returncode
+        mock.stdout = stdout
+        return mock
+
+    def test_keychain_used_when_file_absent(self):
+        key = "sk-ant-oat01-keychain"  # gitleaks:allow
+        home = self._home_without_creds()
+        with patch(
+            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
+            return_value=self._mock_keychain(_cred_json(key)),
+        ), patch(
+            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
+        ):
+            out = claude_host_access_token({"HOME": str(home)})
+        self.assertEqual(key, out)
+
+    def test_keychain_failure_when_file_absent_dies(self):
+        home = self._home_without_creds()
+        with patch(
+            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
+            return_value=self._mock_keychain("", returncode=44),
+        ), patch(
+            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
+        ):
+            with self.assertRaises(Die):
+                claude_host_access_token({"HOME": str(home)})
+
+    def test_no_file_no_keychain_on_linux_dies(self):
+        home = self._home_without_creds()
+        with patch("bot_bottle.contrib.claude.claude_auth.sys.platform", "linux"):
+            with self.assertRaises(Die):
+                claude_host_access_token({"HOME": str(home)})
+
+    def test_keychain_non_json_dies(self):
+        home = self._home_without_creds()
+        with patch(
+            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
+            return_value=self._mock_keychain("not-json"),
+        ), patch(
+            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
+        ):
+            with self.assertRaises(Die):
+                claude_host_access_token({"HOME": str(home)})
+
+    def test_keychain_security_not_found_dies(self):
+        home = self._home_without_creds()
+        with patch(
+            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
+            side_effect=FileNotFoundError,
+        ), patch(
+            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
+        ):
+            with self.assertRaises(Die):
+                claude_host_access_token({"HOME": str(home)})
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -29,7 +29,7 @@ def _fail(stderr: str = "boom") -> subprocess.CompletedProcess:  # type: ignore
 class TestCommitContainer(unittest.TestCase):
    def test_runs_docker_commit(self):
        with patch.object(
-            docker_mod.subprocess, "run", return_value=_ok(),
+            docker_mod, "run_docker", return_value=_ok(),
        ) as run, patch.object(docker_mod, "info"):
            docker_mod.commit_container(
                "bot-bottle-dev-abc12",
@@ -47,7 +47,7 @@ class TestCommitContainer(unittest.TestCase):

    def test_dies_on_docker_commit_failure(self):
        with patch.object(
-            docker_mod.subprocess, "run", return_value=_fail("No such container"),
+            docker_mod, "run_docker", return_value=_fail("No such container"),
        ), patch.object(
            docker_mod, "die", side_effect=SystemExit("die"),
        ) as die:
@@ -58,7 +58,7 @@ class TestCommitContainer(unittest.TestCase):

    def test_die_message_includes_image_tag(self):
        with patch.object(
-            docker_mod.subprocess, "run", return_value=_fail("boom"),
+            docker_mod, "run_docker", return_value=_fail("boom"),
        ), patch.object(
            docker_mod, "die", side_effect=SystemExit("die"),
        ) as die:
@@ -18,7 +18,7 @@ from unittest.mock import patch


 # ---------------------------------------------------------------------------
-# Gateway-import shims — must run before importing egress_addon
+# mitmproxy stub — must run before importing egress_addon
 # ---------------------------------------------------------------------------

 def _ensure_shims() -> None:
@@ -32,9 +32,6 @@ def _ensure_shims() -> None:
        setattr(_mm, "http", _mh)
        sys.modules["mitmproxy"] = _mm
        sys.modules["mitmproxy.http"] = _mh
-    if "egress_addon_core" not in sys.modules:
-        import bot_bottle.egress_addon_core as _core
-        sys.modules["egress_addon_core"] = _core


 _ensure_shims()
@@ -190,9 +190,6 @@ def _ensure_shims() -> None:
        setattr(mh, "Response", _Response)
    if not hasattr(mh, "HTTPFlow"):
        setattr(mh, "HTTPFlow", object)
-    if "egress_addon_core" not in sys.modules:
-        import bot_bottle.egress_addon_core as _core
-        sys.modules["egress_addon_core"] = _core


 _ensure_shims()
@@ -80,11 +80,19 @@ class TestAgentProviderHostCredentials(unittest.TestCase):
                "forward_host_credentials": "yes",
            })

-    def test_forward_host_credentials_rejected_for_claude(self):
+    def test_forward_host_credentials_allowed_for_claude(self):
+        b = _provider_config_bottle({
+            "template": "claude",
+            "forward_host_credentials": True,
+        })
+        self.assertTrue(b.agent_provider.forward_host_credentials)
+
+    def test_forward_host_credentials_and_auth_token_rejected_together(self):
        with self.assertRaises(ManifestError):
            _provider_config_bottle({
                "template": "claude",
                "forward_host_credentials": True,
+                "auth_token": "SOME_TOKEN",
            })

    def test_auth_token_defaults_empty(self):
@@ -86,10 +86,22 @@ class TestAgentProviderValidation(unittest.TestCase):
                "b", {"forward_host_credentials": True, "template": "weird"}
            )

-    def test_forward_creds_non_codex_template(self) -> None:
+    def test_forward_creds_pi_template_rejected(self) -> None:
        with self.assertRaises(ManifestError):
            ManifestAgentProvider.from_dict(
-                "b", {"forward_host_credentials": True, "template": "claude"}
+                "b", {"forward_host_credentials": True, "template": "pi"}
+            )
+
+    def test_forward_creds_claude_allowed(self) -> None:
+        p = ManifestAgentProvider.from_dict(
+            "b", {"forward_host_credentials": True, "template": "claude"}
+        )
+        self.assertTrue(p.forward_host_credentials)
+
+    def test_forward_creds_and_auth_token_rejected(self) -> None:
+        with self.assertRaises(ManifestError):
+            ManifestAgentProvider.from_dict(
+                "b", {"forward_host_credentials": True, "auth_token": "T", "template": "claude"}
            )

    def test_valid_claude_auth_token(self) -> None:
@@ -2,7 +2,6 @@

 import http.client
 import json
-import sys
 import tempfile
 import threading
 import time
@@ -13,15 +12,9 @@ from unittest.mock import patch

 from tests.unit import use_bottle_root

-
-# The server module loads `supervise` via same-directory import inside
-# the container (Dockerfile.supervise WORKDIRs into /app). For tests
-# we mirror that by injecting bot_bottle/ onto sys.path under the
-# bare name `supervise`.
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "bot_bottle"))
-import supervise as _sv  # noqa: E402  # type: ignore
-import queue_store as _qs  # noqa: E402  # type: ignore
-import audit_store as _as  # noqa: E402  # type: ignore
+from bot_bottle import supervise as _sv
+from bot_bottle import queue_store as _qs
+from bot_bottle import audit_store as _as

 from bot_bottle import supervise_server  # noqa: E402
 from bot_bottle.supervise_server import (
@@ -1,62 +0,0 @@
-import unittest
-from unittest.mock import Mock
-
-from scripts.tracker_policy import (
-    TRIAGE_LABEL,
-    check_pull_request,
-    deliberate_issue_numbers,
-    ensure_issue_label,
-)
-
-
-class TestDeliberateIssueNumbers(unittest.TestCase):
-    def test_accepts_completing_and_noncompleting_forms(self):
-        self.assertEqual(
-            deliberate_issue_numbers("Fixes #12", "Part of #14; refs #15"),
-            {12, 14, 15},
-        )
-
-    def test_does_not_treat_incidental_number_as_link(self):
-        self.assertEqual(deliberate_issue_numbers("Audit #12", "See PR #14"), set())
-
-
-class TestCheckPullRequest(unittest.TestCase):
-    def test_accepts_unlabelled_pr_linked_to_real_issue(self):
-        api = Mock()
-        api.request.return_value = {"number": 12, "pull_request": None}
-        event = {"pull_request": {"title": "Change", "body": "Part of #12", "labels": []}}
-        self.assertEqual(check_pull_request(event, api), [])
-
-    def test_rejects_labels_and_pr_reference(self):
-        api = Mock()
-        api.request.return_value = {"number": 12, "pull_request": {}}
-        event = {
-            "pull_request": {
-                "title": "Change",
-                "body": "Closes #12",
-                "labels": [{"name": "Kind/Bug"}],
-            }
-        }
-        errors = check_pull_request(event, api)
-        self.assertEqual(len(errors), 2)
-        self.assertIn("unlabeled", errors[0])
-        self.assertIn("not an issue", errors[1])
-
-
-class TestEnsureIssueLabel(unittest.TestCase):
-    def test_adds_triage_label_to_unlabelled_issue(self):
-        api = Mock()
-        api.request.side_effect = [[{"id": 55, "name": TRIAGE_LABEL}], None]
-        event = {"issue": {"number": 405, "labels": [], "pull_request": None}}
-        self.assertTrue(ensure_issue_label(event, api))
-        api.request.assert_any_call("POST", "/issues/405/labels", {"labels": [55]})
-
-    def test_leaves_labelled_issue_unchanged(self):
-        api = Mock()
-        event = {"issue": {"number": 405, "labels": [{"name": "Kind/Documentation"}]}}
-        self.assertFalse(ensure_issue_label(event, api))
-        api.request.assert_not_called()
-
-
-if __name__ == "__main__":
-    unittest.main()
Author	SHA1	Message	Date
didericis-claude	f72785536a	feat(claude): add forward_host_credentials support test / integration (pull_request) Successful in 21s Details test / unit (pull_request) Successful in 31s Details test / coverage (pull_request) Successful in 38s Details lint / lint (push) Successful in 41s Details Reads the host's Claude OAuth session key from ~/.claude.json at launch and forwards it only to the egress sidecar (never to the agent), placing a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent env so Claude Code starts without seeing the real credential. Mirrors the existing Codex forward_host_credentials flow (PRD 0029). Adds claude_auth.py to extract and validate the sessionKey, a CLAUDE_HOST_CREDENTIAL_TOKEN_REF constant in egress.py, and updates manifest_agent.py to allow the flag for both 'codex' and 'claude' templates. Also adds a mutual-exclusion check that rejects setting both auth_token and forward_host_credentials together. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): read credentials from ~/.claude/.credentials.json The actual OAuth token is in ~/.claude/.credentials.json under claudeAiOauth.accessToken, not in ~/.claude.json. ~/.claude.json holds only UI state and profile metadata (oauthAccount has no token fields). expiresAt in the credentials file is milliseconds, not seconds. Discovered after testing against Claude Code 2.1.198. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(claude): fall back to macOS Keychain for credentials On macOS, Claude Code stores credentials in the Keychain under service "Claude Code-credentials" rather than in a file. When ~/.claude/.credentials.json is absent, shell out to: security find-generic-password -s "Claude Code-credentials" -w and parse the result as the same JSON schema. ~/.claude.json holds only profile/UI metadata (oauthAccount has no token fields). expiresAt in the credentials is milliseconds. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> docs(prd): fix credential path references (~/.claude/.credentials.json) fix(test): suppress gitleaks false positives on synthetic Claude tokens	2026-07-18 09:55:03 +00:00
Quality Badge Bot	aed686d85d	chore: update quality badges - Coverage: 81% - Core coverage: 94% [skip ci]	2026-07-18 09:15:12 +00:00
didericis-claude	410c19aaaf	fix(backend): fix pyright errors in lazy-load implementation test / integration (push) Successful in 10s Details test / coverage (push) Successful in 38s Details Update Quality Badges / update-badges (push) Successful in 37s Details lint / lint (push) Successful in 42s Details test / unit (push) Successful in 1m21s Details - Rename _BACKENDS → _backends: pyright treats uppercase module-level names as constants and flags the reassignment in _get_backends() as reportConstantRedefinition; lowercase avoids this. - Add TYPE_CHECKING guard importing CommitCancelled/Freezer/get_freezer from .freeze: pyright cannot see module-level __getattr__ bindings, so reportUnsupportedDunderAll fired for those three __all__ entries; the guard makes them visible to the type checker without running at import time. - Update test_backend_selection.py to patch _backends (lowercase).	2026-07-18 05:14:27 -04:00
didericis-claude	f0ba399f17	fix(backend): silence pylint false positives from lazy-load pattern `undefined-all-variable` fires on CommitCancelled / Freezer / get_freezer in __all__ because pylint can't see module-level __getattr__ bindings; `global-statement` fires on the _BACKENDS singleton setter. Both are intentional patterns — add inline disables rather than suppress globally.	2026-07-18 05:14:27 -04:00
didericis-claude	8b442b8718	perf: lazy-load backend modules and consolidate docker subprocess helpers Importing backend.docker.util previously triggered eager loading of all three backend packages (~76 modules) because backend/__init__.py imported DockerBottleBackend, FirecrackerBottleBackend, and MacosContainerBottleBackend at module scope. This made the module prohibitively expensive to import from the orchestrator layer and elsewhere. The three backend imports are now deferred into _get_backends(), which loads all three on first call and caches the result in the module-level _BACKENDS variable (initially None). Module-level __getattr__ exposes backend classes and freeze symbols lazily for existing import/patch sites. backend/docker/util.py raw subprocess.run(["docker", ...]) calls are replaced with the shared run_docker primitive from docker_cmd, eliminating the duplication between the backend and orchestrator implementations. _silent_run() is removed; image_exists() is inlined directly onto run_docker. The commit_container test is updated to patch run_docker instead of subprocess.run.	2026-07-18 05:14:27 -04:00
didericis	5eb6c8d99b	ci: drop actions/setup-python from the remaining workflows Applies the same fix as test/lint to every workflow that still used actions/setup-python, which the old act_runner engine mishandles: - update-badges: was broken identically to lint — setup-python + pip install hit the image's externally-managed system Python. Drop setup-python, install with --break-system-packages, and use `python3` (not bare `python`) for the coverage steps. - canaries, prd-number: no pip install, so not failing, but they carried the same fragile (and network-heavy) setup-python for stdlib-only work. Removed — the image's system Python 3.12 runs them directly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UoEZHDjv84ChoZbozQERhJ	2026-07-18 05:11:48 -04:00
didericis	4f10b810d4	ci(lint): drop actions/setup-python; install into the container's system Python lint / lint (push) Successful in 2m16s Details Same fix as the test workflow: the old act_runner engine mishandles actions/setup-python's PATH, so `pip install` hit the image's externally-managed system Python and failed with "externally-managed-environment" on the "Install dev dependencies" step. The runner image already ships Python 3.12 and the job container is ephemeral, so drop setup-python and install straight into system Python with --break-system-packages. pylint/pyright console scripts land on /usr/local/bin (on PATH), so the lint steps still resolve. Also drops the now-pointless `pip install --upgrade pip`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UoEZHDjv84ChoZbozQERhJ	2026-07-18 05:08:18 -04:00
didericis	d3c4fc0fd4	ci(test): drop actions/setup-python; install into the container's system Python test / integration (pull_request) Successful in 7s Details test / unit (pull_request) Successful in 44s Details test / coverage (pull_request) Successful in 36s Details test / integration (push) Successful in 7s Details Update Quality Badges / update-badges (push) Failing after 11s Details test / unit (push) Successful in 29s Details test / coverage (push) Successful in 35s Details lint / lint (push) Successful in 2m24s Details The old act_runner engine (v0.2.13 on the delphi-ci runner) mishandles actions/setup-python's PATH injection: pip installs coverage into the toolcache interpreter while `python3` in later steps resolves back to the image's system Python, so unit/coverage jobs failed with "No module named coverage". Newer runners (TrueNAS's v0.6.1) don't, which is why it only broke on delphi. The runner-images/act container already ships Python 3.12, and the job container is ephemeral, so drop setup-python entirely and install straight into the system Python with --break-system-packages. Every step now uses one interpreter consistently, on any runner version. Also removes the redundant setup-python step from the integration job (stdlib-only). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UoEZHDjv84ChoZbozQERhJ	2026-07-18 04:58:38 -04:00
didericis-claude	232dfdf37a	refactor(gateway): replace egress_addon.py copy with a one-line shim test / integration (pull_request) Successful in 1m15s Details test / coverage (pull_request) Failing after 1m13s Details test / unit (pull_request) Successful in 1m19s Details mitmdump -s requires a file path, not a module. Instead of copying the full egress_addon.py to /app/, write a one-line shim at image build time that re-exports addons from the installed package. mitmdump finds the addons list in the shim's namespace; all real addon code stays in bot_bottle/egress_addon.py.	2026-07-18 07:59:57 +00:00
didericis-claude	9a0dd821ef	refactor(gateway): invoke daemons via python3 -m instead of /app/ file copies lint / lint (push) Successful in 2m20s Details test / unit (pull_request) Successful in 1m12s Details test / integration (pull_request) Successful in 26s Details test / coverage (pull_request) Successful in 1m29s Details supervise_server, git_http_backend, and gateway_init all have __main__ guards, so python3 -m bot_bottle.X replaces the individual COPY lines to /app/. egress_addon.py stays as a file copy because mitmdump -s requires a file path rather than a module reference.	2026-07-18 07:55:38 +00:00
didericis-claude	5ad3449e3b	refactor(gateway): replace flat-file import shims with installed package lint / lint (push) Successful in 2m22s Details test / unit (pull_request) Successful in 1m12s Details test / integration (pull_request) Successful in 23s Details test / coverage (pull_request) Successful in 1m23s Details Install bot_bottle via pip in Dockerfile.gateway instead of COPYing individual .py files flat under /app/. This eliminates the try/except import shims in egress_addon_core, dlp_detectors, egress_addon, supervise, supervise_server, and git_http_backend that existed only to support the flat-bundle layout. Adds bot_bottle/constants.py as a single source of truth for IDENTITY_HEADER and GIT_GATE_TIMEOUT_SECS, removing the duplicated literal definitions in egress_addon.py, supervise_server.py, git_http_backend.py, and git_gate_render.py. Test files updated to match: test_supervise_server.py drops the sys.path.insert hack in favour of direct package imports; the egress_addon test shims no longer pre-populate sys.modules with a bare egress_addon_core alias.	2026-07-18 03:01:41 +00:00