feat: add raw session args/opts

[NathanFlurry]

Summary

• Adds rawSessionArgs and rawSessionOptions fields to CreateSessionRequest for passing raw CLI arguments and options directly to agents at session creation
• Implements apply_raw_options_as_cli_args to convert JSON key-value pairs to --key value CLI flags for CLI-based agents (Claude, OpenCode, Amp)
• For Codex (JSON-RPC), raw options are merged into the thread/start config
• Updates agent capabilities to advertise rawSessionArgs and rawSessionOptions support
• Updates TypeScript SDK types, OpenAPI spec, docs, and agent research

Test plan

• Verify rawSessionArgs are appended to CLI agent spawn commands
• Verify rawSessionOptions are converted to --key value flags for CLI agents
• Verify rawSessionOptions are merged into Codex JSON-RPC config
• Verify boolean true/false handling in raw options (true → --flag, false → skipped)
• Run cargo test -p sandbox-agent --test agent_management

[railway-app]

🚅 Deployed to the sandbox-agent-pr-88 environment in sandbox-agent

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Feb 5, 2026 at 11:27 pm

[claude]

Code Review

Found 2 issues that need attention:

1. Documentation Inconsistency (CLAUDE.md violation)

File: docs/session-transcript-schema.mdx:91

The documentation shows a blank cell for Codex's "Raw Session Args" capability, but the implementation explicitly sets raw_session_args: false.

According to CLAUDE.md line 43, the UI must reflect every field in AgentCapabilities.

Issue: A blank cell is ambiguous. For consistency with other unsupported features in the table, please use an explicit indicator like - or ✗.

---

2. Compilation Error - Missing Required Fields

File: server/packages/sandbox-agent/src/router.rs:5320-5327

The CreateSessionRequest struct literal in test_utils::insert_session is missing the two new required fields (raw_session_args and raw_session_options). This will cause a compile error when the test-utils feature is enabled.

Fix: Add the missing fields with None values (see main.rs:591 and opencode_compat.rs:379 for examples).

[NathanFlurry]

• feat: add raw session args/opts #88 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.