fix(args): honor the -- contract — deva flags only before, verbatim after

deva's arg pipeline flattened AGENT_ARGS (pre-deva flags) and POST_ARGS
(post--- agent args) into a single AGENT_ARGV before agent_prepare saw
it, destroying the -- boundary. --trace and --auth-with were intercepted
from the flat array regardless of position, so `deva grok -- --trace`
ate the flag instead of passing it to grok.

Fix: inject a -- sentinel into AGENT_ARGV between the two sources.
Each agent's flag scanner stops interpreting at the sentinel and strips
it at command assembly. The contract:

  deva <agent> --trace -- --resume   # traced, --resume to agent
  deva <agent> -- --trace --resume   # NOT traced, both reach agent
  deva --trace <agent> -- --resume   # traced (--trace is a wrapper arg)

parse_auth_args in shared_auth.sh uses the same boundary for --auth-with.
gemini.sh (no --trace) strips the sentinel before command assembly.

Closes #427

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -37,6 +37,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   answers (poll-then-open; `DEVA_TRACE_OPEN=0` disables). Attaching to a
   persistent container created without the port warns instead (#425)
 
+### Fixed
+- `--` contract: deva-level flags (`--trace`, `--auth-with`) are now
+  interpreted only before `--`; everything after passes to the agent CLI
+  verbatim. `deva claude --trace -- --resume` traces; `deva claude --
+  --trace --resume` passes `--trace` through to claude as its own flag.
+  Previous behavior silently intercepted flags from both sides (#427)
+
 ### Changed
 - cctrace pin bumped 0.4.0 -> 0.11.0 (client profiles, shape-first
   categorization, `view --serve`)

agents/claude.sh

@@ -15,17 +15,30 @@ agent_prepare() {
     AUTH_METHOD="$PARSED_AUTH_METHOD"
     local -a remaining_args=("${PARSED_REMAINING_ARGS[@]+"${PARSED_REMAINING_ARGS[@]}"}")
 
-    # Detect --trace flag
+    # Detect --trace flag — only before the -- sentinel; after it, args
+    # belong to the agent CLI verbatim (#427). First -- is stripped.
     local use_trace=false
+    local seen_sep=false
     local -a claude_args=()
 
     if [ ${#remaining_args[@]} -gt 0 ]; then
         local i=0
         while [ $i -lt ${#remaining_args[@]} ]; do
             local arg="${remaining_args[$i]}"
             case "$arg" in
+                --)
+                    if [ "$seen_sep" = false ]; then
+                        seen_sep=true
+                    else
+                        claude_args+=("$arg")
+                    fi
+                    ;;
                 --trace)
-                    use_trace=true
+                    if [ "$seen_sep" = true ]; then
+                        claude_args+=("$arg")
+                    else
+                        use_trace=true
+                    fi
                     ;;
                 *)
                     claude_args+=("$arg")

agents/codex.sh

@@ -33,13 +33,17 @@ 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)
+    # Detect --trace flag — only before the -- sentinel; after it, args
+    # belong to the agent CLI verbatim (#427). First -- is stripped.
     local use_trace=false
+    local seen_sep=false
     if [ ${#remaining_args[@]} -gt 0 ]; then
         local -a filtered_args=()
         local arg
         for arg in "${remaining_args[@]}"; do
-            if [ "$arg" = "--trace" ]; then
+            if [ "$arg" = "--" ] && [ "$seen_sep" = false ]; then
+                seen_sep=true
+            elif [ "$arg" = "--trace" ] && [ "$seen_sep" = false ]; then
                 use_trace=true
             else
                 filtered_args+=("$arg")

agents/gemini.sh

@@ -20,7 +20,18 @@ agent_prepare() {
 
     AGENT_COMMAND+=("--yolo")
 
-    AGENT_COMMAND+=("${remaining_args[@]+"${remaining_args[@]}"}")
+    # Strip the deva -- sentinel; everything after it is verbatim (#427).
+    local -a clean_args=()
+    local first_sep=false
+    local arg
+    for arg in "${remaining_args[@]+"${remaining_args[@]}"}"; do
+        if [ "$arg" = "--" ] && [ "$first_sep" = false ]; then
+            first_sep=true
+        else
+            clean_args+=("$arg")
+        fi
+    done
+    AGENT_COMMAND+=("${clean_args[@]+"${clean_args[@]}"}")
 
     setup_gemini_auth "$AUTH_METHOD"
 }

agents/grok.sh

@@ -18,13 +18,17 @@ 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)
+    # Detect --trace flag — only before the -- sentinel; after it, args
+    # belong to the agent CLI verbatim (#427). First -- is stripped.
     local use_trace=false
+    local seen_sep=false
     if [ ${#remaining_args[@]} -gt 0 ]; then
         local -a filtered_args=()
         local arg
         for arg in "${remaining_args[@]}"; do
-            if [ "$arg" = "--trace" ]; then
+            if [ "$arg" = "--" ] && [ "$seen_sep" = false ]; then
+                seen_sep=true
+            elif [ "$arg" = "--trace" ] && [ "$seen_sep" = false ]; then
                 use_trace=true
             else
                 filtered_args+=("$arg")

agents/shared_auth.sh

@@ -447,10 +447,23 @@ parse_auth_args() {
     local auth_method=""
     local -a remaining_args=()
     local i=0
+    local seen_sep=false
 
     while [ $i -lt ${#args[@]} ]; do
         case "${args[$i]}" in
+            --)
+                # First -- is the deva sentinel; keep it for downstream
+                # flag scanners (#427). Later --s pass through as-is.
+                seen_sep=true
+                remaining_args+=("${args[$i]}")
+                i=$((i + 1))
+                ;;
             --auth-with)
+                if [ "$seen_sep" = true ]; then
+                    remaining_args+=("${args[$i]}")
+                    i=$((i + 1))
+                    continue
+                fi
                 if [ $((i + 1)) -ge ${#args[@]} ]; then
                     auth_error "--auth-with requires a method or file path"
                 fi

deva.sh

@@ -3278,12 +3278,17 @@ else
     parse_wrapper_args
 fi
 
+# Preserve the -- boundary so agent_prepare can distinguish deva-level
+# flags (--auth-with, --trace) from agent CLI args: flags are only
+# interpreted before the sentinel; everything after passes verbatim (#427).
 if [ ${#AGENT_ARGS[@]} -gt 0 ]; then
     if [ ${#AGENT_ARGV[@]} -gt 0 ]; then
-        AGENT_ARGV=("${AGENT_ARGS[@]}" "${AGENT_ARGV[@]}")
+        AGENT_ARGV=("${AGENT_ARGS[@]}" "--" "${AGENT_ARGV[@]}")
     else
         AGENT_ARGV=("${AGENT_ARGS[@]}")
     fi
+elif [ ${#AGENT_ARGV[@]} -gt 0 ]; then
+    AGENT_ARGV=("--" "${AGENT_ARGV[@]}")
 fi
 
 _step "start"

docs/advanced-usage.md

@@ -164,11 +164,14 @@ The printed `docker run` line is diagnostic output. It masks secrets and may con
 ## Request Tracing
 
 ```bash
-deva.sh claude -- --trace --continue
-deva.sh codex -- --trace exec "fix the failing tests"
-deva.sh grok -- --trace -p "explain this stack trace"
+deva.sh claude --trace -- --continue
+deva.sh codex --trace -- exec "fix the failing tests"
+deva.sh grok --trace -- -p "explain this stack trace"
 ```
 
+`--trace` goes before `--`. Everything after `--` passes to the agent CLI
+verbatim and is never intercepted by deva.
+
 `--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