feat(build): selective tool upgrade + dedicated cctrace layer

cctrace ships faster than everything else; upgrading it should not cost
a full-manifest re-resolve or a full image rebuild.

- version-upgrade.sh --only tool[,tool] / ONLY= env: selected tools get
  latest, everything else folds into the pinned pathway via versions.env
  (manifest shows them as pinned; no downstream changes needed)
- make versions-up ONLY=cctrace passthrough
- install-agent-tooling.sh DEVA_TOOLING_STAGE=agents|cctrace|all
- both Dockerfiles: cctrace gets its own RUN with ARG+LABEL declared
  adjacent. ARGs poison the cache of every later RUN when changed;
  declared early, a cctrace bump rebuilt the whole npm layer (and the
  rust image's Playwright layer). Now it rebuilds one small layer.

Closes #419

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Selective tool upgrade: `make versions-up ONLY=cctrace` upgrades one
+  tool (comma list supported) while everything else stays pinned to
+  versions.env (#419)
+- cctrace installs in its own Docker layer in both images, with its ARG
+  declared adjacent — a cctrace-only bump no longer rebuilds the npm
+  agent layer or (rust image) the Playwright layer (#419)
 - `--trace` for codex and grok via cctrace client profiles (#418).
   `deva codex -- --trace exec "..."` / `deva grok -- --trace -p "..."`
   wrap the agent with `cctrace <client> --no-open --`; always MITM capture

Dockerfile

@@ -209,14 +209,12 @@ FROM agent-base AS final
 
 # Declare ARGs immediately before usage to minimize cache invalidation
 ARG CLAUDE_CODE_VERSION=2.1.143
-ARG CCTRACE_VERSION=0.11.0
 ARG CODEX_VERSION=0.131.0
 ARG GEMINI_CLI_VERSION=0.42.0
 ARG GROK_CLI_VERSION=0.2.93
 
 # Record key tool versions as labels for quick inspection
 LABEL org.opencontainers.image.claude_code_version=${CLAUDE_CODE_VERSION}
-LABEL org.opencontainers.image.cctrace_version=${CCTRACE_VERSION}
 LABEL org.opencontainers.image.codex_version=${CODEX_VERSION}
 LABEL org.opencontainers.image.gemini_cli_version=${GEMINI_CLI_VERSION}
 LABEL org.opencontainers.image.grok_cli_version=${GROK_CLI_VERSION}
@@ -228,7 +226,15 @@ LABEL org.opencontainers.image.ccx_version=${CCX_VERSION}
 COPY --chown=deva:deva scripts/install-agent-tooling.sh /tmp/install-agent-tooling.sh
 
 RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sharing=locked \
-    bash /tmp/install-agent-tooling.sh && \
+    DEVA_TOOLING_STAGE=agents bash /tmp/install-agent-tooling.sh
+
+# cctrace moves fast: own ARG + layer, declared here so a pin bump
+# rebuilds only this layer, not the npm agent layer above.
+ARG CCTRACE_VERSION=0.11.0
+LABEL org.opencontainers.image.cctrace_version=${CCTRACE_VERSION}
+
+RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sharing=locked \
+    DEVA_TOOLING_STAGE=cctrace bash /tmp/install-agent-tooling.sh && \
     rm -f /tmp/install-agent-tooling.sh
 
 USER root

Dockerfile.rust

@@ -9,7 +9,6 @@ LABEL org.opencontainers.image.title="deva-rust"
 LABEL org.opencontainers.image.description="Rust development environment with full toolchain"
 
 ARG CLAUDE_CODE_VERSION=2.1.143
-ARG CCTRACE_VERSION=0.11.0
 ARG CODEX_VERSION=0.131.0
 ARG GEMINI_CLI_VERSION=0.42.0
 ARG GROK_CLI_VERSION=0.2.93
@@ -20,7 +19,6 @@ ARG RUST_DEFAULT_TOOLCHAIN="stable"
 ARG RUST_TARGETS="wasm32-unknown-unknown"
 
 LABEL org.opencontainers.image.claude_code_version=${CLAUDE_CODE_VERSION}
-LABEL org.opencontainers.image.cctrace_version=${CCTRACE_VERSION}
 LABEL org.opencontainers.image.codex_version=${CODEX_VERSION}
 LABEL org.opencontainers.image.gemini_cli_version=${GEMINI_CLI_VERSION}
 LABEL org.opencontainers.image.grok_cli_version=${GROK_CLI_VERSION}
@@ -115,8 +113,7 @@ USER $DEVA_USER
 COPY --chown=deva:deva scripts/install-agent-tooling.sh /tmp/install-agent-tooling.sh
 
 RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sharing=locked \
-    bash /tmp/install-agent-tooling.sh && \
-    rm -f /tmp/install-agent-tooling.sh
+    DEVA_TOOLING_STAGE=agents bash /tmp/install-agent-tooling.sh
 
 # Install Playwright + both chromium binaries. Runs after install-agent-tooling.sh
 # so npm prefix ($DEVA_HOME/.npm-global) is already configured. System deps are
@@ -148,6 +145,15 @@ RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sh
     test -d "$(find "$PLAYWRIGHT_BROWSERS_PATH" -maxdepth 1 -type d -name 'chromium_headless_shell-*' -print -quit)" && \
     npm cache clean --force
 
+# cctrace moves fast: own ARG + layer, declared last among the tool layers
+# so a pin bump rebuilds only this, not npm tooling or playwright above.
+ARG CCTRACE_VERSION=0.11.0
+LABEL org.opencontainers.image.cctrace_version=${CCTRACE_VERSION}
+
+RUN --mount=type=cache,target=/home/deva/.npm,uid=${DEVA_UID},gid=${DEVA_GID},sharing=locked \
+    DEVA_TOOLING_STAGE=cctrace bash /tmp/install-agent-tooling.sh && \
+    rm -f /tmp/install-agent-tooling.sh
+
 USER root
 
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh

Makefile

@@ -247,6 +247,7 @@ versions-up:
 	 RUST_IMAGE=$(RUST_IMAGE) \
 	 DOCKERFILE=$(DOCKERFILE) \
 	 RUST_DOCKERFILE=$(RUST_DOCKERFILE) \
+	 ONLY=$(ONLY) \
 	 $(VERSION_QUERY_OVERRIDES) \
 	 ./scripts/version-upgrade.sh
 
@@ -406,6 +407,7 @@ help:
 	@echo "  toolchains           List pinned toolchains and managed build tools"
 	@echo "  versions             Compare built vs latest versions with changelogs"
 	@echo "  versions-up          Build both images with latest upstream agent versions"
+	@echo "                       ONLY=cctrace upgrades one tool, rest stay pinned"
 	@echo "  versions-pin         Refresh $(VERSION_PINS_FILE) from upstream"
 	@echo "  scripts              List repo helper scripts"
 	@echo "  commands             Alias for help"
@@ -458,3 +460,4 @@ help:
 	@echo "  make versions                                 # Check current versions"
 	@echo "  make PLAYWRIGHT_VERSION=1.60.0 build-rust     # Override rust browser tooling"
 	@echo "  make versions-up                              # Upgrade to latest upstream versions"
+	@echo "  make versions-up ONLY=cctrace                 # Upgrade just cctrace, rest pinned"

scripts/install-agent-tooling.sh

@@ -315,12 +315,29 @@ install_cctrace() {
     log "cctrace installed"
 }
 
+# DEVA_TOOLING_STAGE splits installs across Docker layers so fast-moving
+# tools (cctrace) can bump without busting the big npm layer.
 main() {
     ensure_safe_cwd
-    log "Installing shared agent tooling into $DEVA_HOME"
-    install_npm_agent_tooling
-    install_ccx
-    install_cctrace
+    local stage="${DEVA_TOOLING_STAGE:-all}"
+    log "Installing shared agent tooling into $DEVA_HOME (stage: $stage)"
+    case "$stage" in
+        agents)
+            install_npm_agent_tooling
+            install_ccx
+            ;;
+        cctrace)
+            install_cctrace
+            ;;
+        all)
+            install_npm_agent_tooling
+            install_ccx
+            install_cctrace
+            ;;
+        *)
+            die "unknown DEVA_TOOLING_STAGE: $stage (agents|cctrace|all)"
+            ;;
+    esac
 }
 
 main "$@"

scripts/version-upgrade.sh

@@ -58,9 +58,14 @@ Usage: $(basename "$0") [OPTIONS]
 
 Options:
   -y, --yes       Skip confirmation countdown
+  --only LIST     Upgrade only these tools (comma-separated); the rest
+                  stay pinned to versions.env. Tools: claude-code,
+                  cctrace, codex, gemini-cli, grok-cli, ccx,
+                  copilot-api, playwright
   -h, --help      Show this help
 
 Environment:
+  ONLY                  Same as --only (e.g. make versions-up ONLY=cctrace)
   MAIN_IMAGE            Main image name (default: ghcr.io/thevibeworks/deva:latest)
   CORE_IMAGE            Core image name (default: ghcr.io/thevibeworks/deva:core)
   RUST_IMAGE            Rust image name (default: ghcr.io/thevibeworks/deva:rust)
@@ -76,16 +81,55 @@ Environment:
 EOF
 }
 
+ONLY="${ONLY:-}"
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -y|--yes) AUTO_YES=1; shift ;;
+        --only) ONLY="${2:-}"; [[ -n $ONLY ]] || { echo "--only requires a tool list"; exit 1; }; shift 2 ;;
+        --only=*) ONLY="${1#--only=}"; shift ;;
         -h|--help) usage; exit 0 ;;
         *) echo "Unknown option: $1"; usage; exit 1 ;;
     esac
 done
 
+tool_selected() {
+    [[ -z $ONLY ]] || [[ ",$ONLY," == *",$1,"* ]]
+}
+
+# --only: fold every non-selected tool into the "pinned" pathway by
+# treating its versions.env pin as a CLI override. Downstream resolution,
+# manifest display, and build args need no changes.
+apply_only_filter() {
+    [[ -n $ONLY ]] || return 0
+
+    local tool
+    local known="claude-code cctrace codex gemini-cli grok-cli ccx copilot-api playwright"
+    for tool in ${ONLY//,/ }; do
+        case " $known " in
+            *" $tool "*) ;;
+            *) echo "error: unknown tool in --only: $tool" >&2
+               echo "known: $known" >&2
+               exit 1 ;;
+        esac
+    done
+
+    tool_selected claude-code || _CLI_CLAUDE_CODE="${_CLI_CLAUDE_CODE:-$CLAUDE_CODE_VERSION}"
+    tool_selected cctrace     || _CLI_CCTRACE="${_CLI_CCTRACE:-$CCTRACE_VERSION}"
+    tool_selected codex       || _CLI_CODEX="${_CLI_CODEX:-$CODEX_VERSION}"
+    tool_selected gemini-cli  || _CLI_GEMINI="${_CLI_GEMINI:-$GEMINI_CLI_VERSION}"
+    tool_selected grok-cli    || _CLI_GROK="${_CLI_GROK:-$GROK_CLI_VERSION}"
+    tool_selected ccx         || _CLI_CCX="${_CLI_CCX:-$CCX_VERSION}"
+    tool_selected copilot-api || _CLI_COPILOT="${_CLI_COPILOT:-$COPILOT_API_VERSION}"
+    tool_selected playwright  || _CLI_PLAYWRIGHT="${_CLI_PLAYWRIGHT:-$PLAYWRIGHT_VERSION}"
+
+    echo "Selective upgrade: $ONLY (all other tools pinned to versions.env)"
+    echo ""
+}
+
 main() {
     load_version_pins
+    apply_only_filter
 
     echo -e "${CYAN}${BOLD}╔════════════════════════════════════════════════════╗${RESET}"
     echo -e "${CYAN}${BOLD}║  Upgrading to Latest Versions                      ║${RESET}"