Supporting seperate coding agent layers

[anantshri]

Right now it seems all coding agents get installed in one set of overlay. i think a better approach would be that each coding agent maintains its own layer and if a specific agent is asked then that layer gets plugged and we get that agent.

[ai-anant]

🤖 Watchdog analysis

Root cause: All five coding agents are installed in a single Docker RUN, so they occupy one image layer and are always present regardless of which agent the user asked for.

In templates/devcontainer/Dockerfile.tmpl (lines 199–216 on main):

RUN mkdir -p \
      /home/vscode/.local/bin \
      /home/vscode/.claude \
      /home/vscode/.codex \
      /home/vscode/.config/opencode \
      /home/vscode/.cursor-agent \
      /home/vscode/.grok \
    && curl -fsSL https://claude.ai/install.sh | bash \
    && curl -fsSL https://chatgpt.com/codex/install.sh | sh \
    && curl -fsSL https://opencode.ai/install | bash -s -- --no-modify-path \
    && curl -fsS https://cursor.com/install | bash \
    && { cursor-agent --version || true; } \
    && curl -fsSL https://x.ai/cli/install.sh | GROK_BIN_DIR=/home/vscode/.local/bin bash

Runtime does not select a layer either. aidc::run_tool in lib/aidc.sh (~875–933) always starts the same project container (aidc::ensure_container_running) and then execs a different binary (claude / codex / opencode / grok / cursor-agent). Compose (templates/devcontainer/compose.yaml.tmpl) builds one workspace image with no per-agent build arg.

Splitting that RUN into five sequential RUNs would only help rebuild cache. Every layer would still land in every project image — it would not “plug” an agent when requested.

Existing PR status: No open PR references #30, and none of the open PRs implement per-agent plug-in layers.

Related but not this issue:

• #15 (AIDC_AGENTS) — opt-in which agents get installed at image build time. Still one image; aidc claude can seed AIDC_AGENTS=claude before first build, but switching agents later means rebuild, and agents are not independent overlay layers.
• #18 — shared aidc-base + thin per-project toolchain layer. Agents still live in the shared base, not per-agent overlays.
• #20 — shared read-only toolchain volumes (aidc_toolchains at /opt/toolchains). This is the closest existing pattern to “plug a layer on demand.”

Fix guidance: This is an architecture change, not a small patch. Recommended shape, matching #20 rather than baking binaries into the project Dockerfile:

1. Per-agent store images (new templates/devcontainer/Dockerfile.agent-<name>.tmpl or one parameterized Dockerfile.agent.tmpl with ARG AIDC_AGENT=claude|codex|opencode|cursor-agent|grok). Each store installs only that agent into /opt/agents-store/<name>/ (binary + any files that must not live in the home volume). Tag by content hash, same as feat: split image into shared aidc-base + thin per-project layer #18/feat: shared read-only toolchain volumes (one copy of Go/Rust/JDK for all projects) #20.
2. Shared named volumes, one per agent (e.g. aidc_agent_claude), populated once by the store image. Mount read-only into the project container at /opt/agents/<name> (or a single aidc_agents volume with subdirs). Put /opt/agents/<name> on PATH in the workspace image without installing the CLIs in Dockerfile.tmpl.
3. Plug at request time in aidc::run_tool / aidc::ensure_container_running:
   • Ensure the volume for $tool exists (aidc agents install claude / auto-ensure).
   • Do not rebuild the project image to add an agent.
   • If compose cannot hot-add a volume to a running container, document that the first use of a new agent requires aidc up recreate (compose volumes: list with all five mounts is fine — empty unused volumes are cheap; only populate the ones asked for).
4. Remove the five-installer RUN from Dockerfile.tmpl (lines 199–216) so the project/base image no longer contains agent blobs. Keep only the empty homedir mkdirs that the existing claude_home / codex_home / … volumes overlay (compose.yaml.tmpl 68–81) — those volumes are state, not the CLI layer.
5. Do not put agent binaries inside claude_home etc. Grok already has this footgun (GROK_BIN_DIR=/home/vscode/.local/bin comment at Dockerfile.tmpl 202–203): a home volume must not shadow the CLI.
6. Compose with feat: make coding-agent installs opt-in per project (AIDC_AGENTS) #15: AIDC_AGENTS can remain as “which volumes to ensure,” not “which curl | bash to run in the Dockerfile.” If feat: make coding-agent installs opt-in per project (AIDC_AGENTS) #15/feat: split image into shared aidc-base + thin per-project layer #18 merge first, rebase this on top and delete the agent loop from the base image rather than adding a second install path.
7. Pitfalls:
   • Agent installers write to ~/.local/bin and sometimes to homedirs; the store image must relocate binaries to /opt/agents-store/... before copying into the volume.
   • cursor-agent --version currently runs in the same RUN as the install (line 215) — keep that as a store-image sanity check, not in the project Dockerfile.
   • One running container serves every aidc <tool> call. Mount-all-volumes + populate-on-demand is simpler than swapping images per tool.
   • Unpinned curl | bash installers stay a supply-chain issue; pinning/checksums belong in the store image, not this issue’s core.

PR status: No new PR. Not a quick fix (new image/volume pipeline, compose + run_tool behavior, interaction with open PRs #15/#18/#20). No duplicate PR opened.

Verification: After implementation:

• docker history on the project image should show no claude/codex/opencode/cursor/grok install layer.
• aidc claude on a fresh repo populates only aidc_agent_claude; which claude inside the container is under /opt/agents/...; which codex is empty until aidc codex.
• bash -n, shellcheck -x, .github/scripts/bash-compat-check.sh (bash 3.2), tests/resolve-oauth-token.test.sh.
• Confirm home volumes still persist sessions and do not contain the agent binaries.