Merge pull request #422 from thevibeworks/feat/trace-418

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

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

Makefile

@@ -31,7 +31,7 @@ DELTA_VERSION ?= 0.19.2
 TMUX_VERSION ?= 3.6a
 TMUX_SHA256 ?= b6d8d9c76585db8ef5fa00d4931902fa4b8cbe8166f528f44fc403961a3f3759
 CLAUDE_CODE_VERSION ?= 2.1.143
-CCTRACE_VERSION ?= 0.4.0
+CCTRACE_VERSION ?= 0.11.0
 CODEX_VERSION ?= 0.131.0
 GEMINI_CLI_VERSION ?= 0.42.0
 GROK_CLI_VERSION ?= 0.2.93

agents/claude.sh

@@ -47,6 +47,10 @@ 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")
+        DEVA_TRACE_ACTIVE=true
         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,14 @@ 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")
+        DEVA_TRACE_ACTIVE=true
+        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,33 @@ 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")
+        DEVA_TRACE_ACTIVE=true
+        AGENT_COMMAND=("cctrace" "grok" "--no-open" "--" "${AGENT_COMMAND[@]:1}")
+    fi
+
     setup_grok_auth "$AUTH_METHOD"
 }
 

deva.sh

@@ -3684,11 +3684,17 @@ if [ "$EPHEMERAL_MODE" = false ]; then
         update_session_file
     fi
 
+    # docker exec env overrides the container's creation-time env: pass the
+    # trace state explicitly so --trace works on an existing container and a
+    # non-traced attach un-trusts the CA installed by an earlier traced run.
+    _trace_env="DEVA_TRACE=0"
+    [ "${DEVA_TRACE_ACTIVE:-false}" = true ] && _trace_env="DEVA_TRACE=1"
+
     if [ "$AUTH_PROVISION_MODE" = true ]; then
-        docker exec "${DOCKER_TERMINAL_ARGS[@]}" "$CONTAINER_NAME" /usr/local/bin/docker-entrypoint.sh "${AGENT_COMMAND[@]}" || true
+        docker exec -e "$_trace_env" "${DOCKER_TERMINAL_ARGS[@]}" "$CONTAINER_NAME" /usr/local/bin/docker-entrypoint.sh "${AGENT_COMMAND[@]}" || true
         finish_auth_provision
     else
-        exec docker exec "${DOCKER_TERMINAL_ARGS[@]}" "$CONTAINER_NAME" /usr/local/bin/docker-entrypoint.sh "${AGENT_COMMAND[@]}"
+        exec docker exec -e "$_trace_env" "${DOCKER_TERMINAL_ARGS[@]}" "$CONTAINER_NAME" /usr/local/bin/docker-entrypoint.sh "${AGENT_COMMAND[@]}"
     fi
 else
     echo "Launching ${ACTIVE_AGENT} (ephemeral mode) via $(docker_image_ref)"

docker-entrypoint.sh

@@ -332,6 +332,48 @@ 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"
+            if ! update-ca-certificates >/dev/null 2>&1; then
+                echo "[entrypoint] warning: trust-store update failed; cctrace MITM CA may still be trusted" >&2
+            fi
+        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"
+    chmod 644 "$crt"
+    if update-ca-certificates >/dev/null 2>&1; then
+        [ "$VERBOSE" = "true" ] && echo "[entrypoint] cctrace MITM CA trusted container-wide: $crt"
+    else
+        echo "[entrypoint] warning: trust-store update failed; container-wide CA trust incomplete (cctrace env-scoped trust still applies)" >&2
+    fi
+    return 0
+}
+
 ensure_agent_binaries() {
     case "$DEVA_AGENT" in
     claude)
@@ -385,6 +427,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