feat(trace): codex/grok --trace + container-scoped CA trust, cctrace 0.11

cctrace 0.11 traces Codex and Grok through client profiles; wire deva's
--trace to all three agents and adopt #414's container CA model.

- codex.sh/grok.sh: --trace wraps AGENT_COMMAND with
  `cctrace <client> --no-open -- ...`; always mitm
- all traced sessions export DEVA_TRACE=1; the entrypoint installs the
  cctrace MITM CA into /usr/local/share/ca-certificates and runs
  update-ca-certificates, removing it on the next non-traced start.
  --print-ca runs as the deva user so CA material lands in the home
  with sane ownership
- CCTRACE_VERSION 0.4.0 -> 0.11.0 in both Dockerfiles

Container is the blast radius: the CA key already lives in the
container-readable home; trusting the cert adds convenience, not
attack surface. Host store untouched.

Closes #418
Closes #414

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

Author: lroolle

CHANGELOG.md

@@ -12,6 +12,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   against the agent config home (`~/.config/deva/<agent>/`) as a named
   credentials store; CWD checked first for compat. Provisioning a missing
   bare name creates it in the store (#417)
+- `--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
+- Container-scoped CA trust for traced sessions (#414): the entrypoint
+  installs the cctrace MITM CA into the container system store when
+  `DEVA_TRACE=1` and removes it on the next non-traced start. Covers
+  subprocesses and tools that ignore the CA env vars; never touches the
+  host trust store
+
+### Changed
+- cctrace pin bumped 0.4.0 -> 0.11.0 (client profiles, shape-first
+  categorization, `view --serve`)
 
 ## [0.14.1] - 2026-07-13
 

Dockerfile

@@ -209,7 +209,7 @@ 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.4.0
+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

Dockerfile.rust

@@ -9,7 +9,7 @@ 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.4.0
+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

agents/claude.sh

@@ -47,6 +47,9 @@ agent_prepare() {
     if [ "$use_trace" = true ]; then
         # Use cctrace wrapper: captures everything by default,
         # claude args go after "--"
+        # DEVA_TRACE=1 tells the entrypoint to install the cctrace MITM CA
+        # into the container system trust store (#414)
+        DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
         AGENT_COMMAND=("cctrace" "--no-open" "--")
         if [ "$has_dangerously" = false ]; then
             AGENT_COMMAND+=("--dangerously-skip-permissions")

agents/codex.sh

@@ -33,6 +33,21 @@ agent_prepare() {
     AUTH_METHOD="$PARSED_AUTH_METHOD"
     local -a remaining_args=("${PARSED_REMAINING_ARGS[@]+"${PARSED_REMAINING_ARGS[@]}"}")
 
+    # Detect --trace flag (cctrace codex client profile, cctrace >= 0.11)
+    local use_trace=false
+    if [ ${#remaining_args[@]} -gt 0 ]; then
+        local -a filtered_args=()
+        local arg
+        for arg in "${remaining_args[@]}"; do
+            if [ "$arg" = "--trace" ]; then
+                use_trace=true
+            else
+                filtered_args+=("$arg")
+            fi
+        done
+        remaining_args=("${filtered_args[@]+"${filtered_args[@]}"}")
+    fi
+
     local has_dangerous=false
     local has_model=false
 
@@ -74,6 +89,13 @@ agent_prepare() {
 
     AGENT_COMMAND+=("${remaining_args[@]+"${remaining_args[@]}"}")
 
+    if [ "$use_trace" = true ]; then
+        # cctrace codex profile: codex args go after "--"; always mitm.
+        # DEVA_TRACE=1 installs the MITM CA into the container store (#414).
+        DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
+        AGENT_COMMAND=("cctrace" "codex" "--no-open" "--" "${AGENT_COMMAND[@]:1}")
+    fi
+
     DOCKER_ARGS+=("-p" "127.0.0.1:1455:1455")
 
     setup_codex_auth "$AUTH_METHOD"

agents/grok.sh

@@ -18,10 +18,32 @@ agent_prepare() {
     AUTH_METHOD="$PARSED_AUTH_METHOD"
     local -a remaining_args=("${PARSED_REMAINING_ARGS[@]+"${PARSED_REMAINING_ARGS[@]}"}")
 
+    # Detect --trace flag (cctrace grok client profile, cctrace >= 0.11)
+    local use_trace=false
+    if [ ${#remaining_args[@]} -gt 0 ]; then
+        local -a filtered_args=()
+        local arg
+        for arg in "${remaining_args[@]}"; do
+            if [ "$arg" = "--trace" ]; then
+                use_trace=true
+            else
+                filtered_args+=("$arg")
+            fi
+        done
+        remaining_args=("${filtered_args[@]+"${filtered_args[@]}"}")
+    fi
+
     AGENT_COMMAND+=("--always-approve")
 
     AGENT_COMMAND+=("${remaining_args[@]+"${remaining_args[@]}"}")
 
+    if [ "$use_trace" = true ]; then
+        # cctrace grok profile: grok args go after "--"; always mitm.
+        # DEVA_TRACE=1 installs the MITM CA into the container store (#414).
+        DOCKER_ARGS+=("-e" "DEVA_TRACE=1")
+        AGENT_COMMAND=("cctrace" "grok" "--no-open" "--" "${AGENT_COMMAND[@]:1}")
+    fi
+
     setup_grok_auth "$AUTH_METHOD"
 }
 

docker-entrypoint.sh

@@ -332,6 +332,42 @@ build_gosu_env_cmd() {
     exec gosu "$user" env "HOME=$DEVA_HOME" "PATH=$PATH" "$@"
 }
 
+# Container-scoped CA trust for cctrace MITM (#414). The container is the
+# blast radius: the CA key already lives in the container-readable home, so
+# trusting the cert system-wide adds convenience, not attack surface. Runs
+# each start: installs when tracing, removes otherwise — trust exists only
+# in traced sessions.
+setup_trace_ca() {
+    local crt=/usr/local/share/ca-certificates/cctrace-mitm.crt
+
+    if [ "${DEVA_TRACE:-}" != "1" ]; then
+        if [ -f "$crt" ]; then
+            rm -f "$crt"
+            update-ca-certificates >/dev/null 2>&1 || true
+        fi
+        return 0
+    fi
+
+    if ! command -v cctrace >/dev/null 2>&1; then
+        echo "[entrypoint] warning: DEVA_TRACE=1 but cctrace not found; skipping CA trust" >&2
+        return 0
+    fi
+
+    # --print-ca generates the CA on first use; it must run as the deva user
+    # so the key lands under $DEVA_HOME/.local/share/cctrace with sane ownership.
+    local ca_path
+    ca_path=$(gosu "$DEVA_USER" env "HOME=$DEVA_HOME" "PATH=$PATH" cctrace --print-ca 2>/dev/null | tail -1)
+    if [ -z "$ca_path" ] || [ ! -f "$ca_path" ]; then
+        echo "[entrypoint] warning: cctrace --print-ca gave no usable path; skipping CA trust" >&2
+        return 0
+    fi
+
+    cp "$ca_path" "$crt"
+    update-ca-certificates >/dev/null 2>&1 || true
+    [ "$VERBOSE" = "true" ] && echo "[entrypoint] cctrace MITM CA trusted container-wide: $crt"
+    return 0
+}
+
 ensure_agent_binaries() {
     case "$DEVA_AGENT" in
     claude)
@@ -385,6 +421,7 @@ main() {
     setup_claude_chrome_bridge
     fix_rust_permissions
     fix_docker_socket_permissions
+    setup_trace_ca
     ensure_agent_binaries
 
     if [ $# -eq 0 ]; then

docs/advanced-usage.md

@@ -165,12 +165,21 @@ The printed `docker run` line is diagnostic output. It masks secrets and may con
 
 ```bash
 deva.sh claude -- --trace --continue
+deva.sh codex -- --trace exec "fix the failing tests"
+deva.sh grok -- --trace -p "explain this stack trace"
 ```
 
-`--trace` wraps Claude with [cctrace](https://github.com/thevibeworks/cctrace),
-which records every API call Claude makes — messages, OAuth, usage/credits,
-MCP — not just the chat endpoint. Everything else on the line goes to Claude
-unchanged.
+`--trace` wraps the agent with [cctrace](https://github.com/thevibeworks/cctrace),
+which records every API call the agent makes — messages, OAuth, usage/credits,
+MCP — not just the chat endpoint. Everything else on the line goes to the
+agent unchanged. Codex and Grok use cctrace client profiles (cctrace >= 0.11)
+and always run MITM capture.
+
+When tracing is on, the entrypoint installs the cctrace MITM CA into the
+container's system trust store (`update-ca-certificates`) so subprocesses and
+tools that ignore `NODE_EXTRA_CA_CERTS`/`SSL_CERT_FILE` still verify. The
+container is the blast radius: trust never touches the host store and is
+removed at the next non-traced start.
 
 Traces land in `.cctrace/` inside your workspace, so they survive the
 container. Each run writes a JSONL log plus a self-contained HTML snapshot you