Repository navigation
CLI --session flag rejects external session IDs that don't start with 'ses' #29964
Description
Bug Description
When using opencode run --session <external-id>, the Zod schema validation requires session IDs to start with ses. This blocks external orchestrators that manage session IDs in their own format (e.g. catagent-*, custom UUIDs, etc.) from passing session IDs via the --session flag.
Error observed in opencode stderr:
ERROR service=server error=Expected a string starting with "ses", got "catagent-1780062945254-girppr"
This is structurally the same class of problem as #21745 and #29868 — the Zod validation starts_with("ses") on session ID — but the trigger path is different: here it's the --session CLI flag receiving a perfectly valid string from an external tool, not an internal dispatch bug.
Steps to Reproduce
- Run opencode with any well-formed string that doesn't start with
ses:echo "hello" | opencode run --format json -m deepseek/deepseek-chat -s "my-custom-session-id"
- Observe the Zod validation error on stderr
- The process exits (exit code depends on version; see opencode run -s <missing-session-id> exits 0 with zero stdout instead of failing #27559)
Expected Behavior
The --session CLI flag should accept any valid string as a session identifier. OpenCode should either:
- Option A: Relax the Zod schema to accept arbitrary session ID strings on the
--sessionCLI path (while keeping stricter validation for internal API routes if needed) - Option B: If
--sessionis only intended for internal opencode-generated IDs, then the CLI should surface a clear error message (e.g. "Session not found: ") with a non-zero exit code, rather than a raw Zod validation error
Actual Behavior
The Zod schema validation starts_with("ses") rejects the input before any session lookup occurs, producing a raw validation error that is indistinguishable from other Zod failures.
Environment
- OpenCode version: observed in multiple versions (1.4.1 via Subagent dispatch fails with session ID validation error: must start with "ses" #21745, 1.14.19 via opencode run -s <missing-session-id> exits 0 with zero stdout instead of failing #27559, 1.15.12 via TUI hangs in infinite render loop after auto-resume abort fails with session ID parse error #29868)
- Use case: Cat Cafe (open-source multi-agent CLI orchestrator) wraps opencode as a subprocess and passes its own managed session IDs via
--session
Additional Context
- Related: Subagent dispatch fails with session ID validation error: must start with "ses" #21745 (internal subagent dispatch hits same Zod validation)
- Related: TUI hangs in infinite render loop after auto-resume abort fails with session ID parse error #29868 (template literal not interpolated, hits same Zod validation)
- Related: opencode run -s <missing-session-id> exits 0 with zero stdout instead of failing #27559 (missing session exits 0 — compounds the problem for external tools)
- The
starts_with("ses")Zod constraint appears to be a recurring friction point for any code path that passes a session ID that didn't originate from opencode's own session factory
Activity