Improve Claude SDK compatibility

Author: lijiuyang.5137

README.md

@@ -454,7 +454,7 @@ through the tap.
 
 ## Compatibility Matrix
 
-Captured from `claude --help` on Claude Code `2.1.146`.
+Captured from `claude --help` on Claude Code `2.1.148`.
 
 Status legend:
 
@@ -497,8 +497,8 @@ Status legend:
 | `--input-format` | Supported | `text` prompts are read from argv/stdin. `stream-json` SDK input is read from stdin. | Fake-PTY test, Python SDK test, TypeScript SDK test, plus live Python/TypeScript SDK game tests. |
 | `--json-schema` | Partial | Forwarded, but `cctty` synthesizes result frames when interactive transcript lacks one; `structured_output` parity is not proven. | Parser coverage only. Needs structured-output differential. |
 | `--max-budget-usd` | Partial | Forwarded, but Claude documents this as print-only. Underlying interactive behavior is not proven equivalent. | Parser coverage only. |
-| `--mcp-config` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. SDK MCP control messages are not bridged yet. |
-| `--mcp-debug` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
+| `--mcp-config` | Supported | Normal Claude-compatible stdio/SSE MCP configs are forwarded to interactive Claude. SDK in-process MCP servers are bridged: TypeScript `initialize.sdkMcpServers` and Python `{ "type": "sdk" }` entries are rewritten into a temporary stdio MCP proxy, and `mcp_message` control requests are round-tripped back to the SDK. | Parser coverage, fake-PTY argv passthrough for normal MCP configs, and TS/Python SDK-MCP round-trip tests covering `initialize`, `tools/list`, and `tools/call`. |
+| `--mcp-debug` | Pass-through | Forwarded to interactive Claude. | Parser coverage plus fake-PTY argv passthrough test. |
 | `--model` | Pass-through | Forwarded to interactive Claude. | Parser coverage and live differential with default configured model path. Specific model aliases not exhaustively tested. |
 | `-n`, `--name` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
 | `--no-chrome` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
@@ -515,7 +515,7 @@ Status legend:
 | `--session-id` | Supported | Forwarded and used to locate the transcript. If omitted in print mode, `cctty` creates one. | Fake-PTY and live differential cover session-id based transcript tailing. |
 | `--setting-sources` | Pass-through | Forwarded to interactive Claude. | Parser coverage, including `--setting-sources=project`. |
 | `--settings` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
-| `--strict-mcp-config` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
+| `--strict-mcp-config` | Pass-through | Forwarded to interactive Claude. | Parser coverage plus fake-PTY argv passthrough test. |
 | `--system-prompt` | Pass-through | Non-empty values are forwarded to interactive Claude. Empty or whitespace-only SDK values are consumed so they do not erase Claude Code's built-in interactive system prompt. | Parser coverage for non-empty pass-through and empty-value consumption. |
 | `--tmux` | Pass-through | Forwarded. `--tmux=classic` is preserved as an equals-form flag; plain `--tmux` does not swallow the prompt. | Parser regression test. |
 | `--tools` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. |
@@ -529,10 +529,14 @@ Some SDKs pass flags that are not listed in current `claude --help`.
 
 | Option(s) | Status | Current handling | Notes |
 | --- | --- | --- | --- |
-| `--permission-prompt-tool stdio` | Partial | Consumed by `cctty`, not forwarded to interactive Claude. In `stream-json` mode, `cctty` watches transcript `assistant.tool_use` entries and also recognizes real TTY permission forms when Claude has not persisted the transcript yet. It emits SDK-style `control_request` / `can_use_tool`, waits for the matching `control_response`, then drives the interactive permission UI by keyboard. Bash allow confirms the selected row; Bash deny selects menu item `2` and pastes the SDK denial message into Claude's follow-up form when present. File create/write/edit/update forms are mapped to `Write`/`Edit` with `file_path`; allow confirms the selected row, while deny selects the file prompt's `3. No` row to avoid accidentally choosing "allow all edits during this session". `AskUserQuestion` form tool uses are forwarded with their original structured `questions` input when available; if only the TTY form is visible, cctty parses that form and sends an SDK-shaped fallback request. SDK-returned structured answers are textified and sent through Claude's follow-up prompt, or submitted as the next user message if Claude returns to the main prompt after cancelling the form. If interactive Claude returns to the prompt after a rejected tool without writing a final result, `cctty` emits a synthetic error result with `result: "Permission denied"`. | Fake-PTY tests cover transcript-first allow/deny, Bash TTY-form-before-transcript, file Write TTY-form-before-transcript, transcript-vs-TTY description precedence, `AskUserQuestion` structured form answer round-trip, and TTY-form-before-transcript `AskUserQuestion` fallback. Live Claude Code `2.1.148` coverage forces `Bash(printf:*)` approval with project-local settings and verifies both allow and deny; live `AskUserQuestion` smoke verifies TTY fallback, answer textification, main-prompt answer injection, and final `result`. Live Python and TypeScript SDK game tests exercise `Write` approval through real file-creation TTY forms. Still partial: broader `Edit`/`MultiEdit` TTY variants, exact `permission_suggestions`, and exact `blocked_path` parity are not complete. |
+| `--permission-prompt-tool`, `--permission-prompt-tool stdio` | Partial | `stdio` is consumed by `cctty`, not forwarded to interactive Claude. In `stream-json` mode, `cctty` watches transcript `assistant.tool_use` entries and also recognizes real TTY permission forms when Claude has not persisted the transcript yet. It emits SDK-style `control_request` / `can_use_tool`, waits for the matching `control_response`, then drives the interactive permission UI by keyboard. Bash allow confirms the selected row; Bash deny selects menu item `2` and pastes the SDK denial message into Claude's follow-up form when present. File create/write/edit/update forms are mapped to `Write`/`Edit` with `file_path`; allow confirms the selected row, while deny selects the file prompt's `3. No` row to avoid accidentally choosing "allow all edits during this session". `AskUserQuestion` form tool uses are forwarded with their original structured `questions` input when available; if only the TTY form is visible, cctty parses that form and sends an SDK-shaped fallback request. SDK-returned structured answers are textified and sent through Claude's follow-up prompt, or submitted as the next user message if Claude returns to the main prompt after cancelling the form. If interactive Claude returns to the prompt after a rejected tool without writing a final result, `cctty` emits a synthetic error result with `result: "Permission denied"`. | Fake-PTY tests cover transcript-first allow/deny, Bash TTY-form-before-transcript, file Write TTY-form-before-transcript, transcript-vs-TTY description precedence, `AskUserQuestion` structured form answer round-trip, and TTY-form-before-transcript `AskUserQuestion` fallback. Live Claude Code `2.1.148` coverage forces `Bash(printf:*)` approval with project-local settings and verifies both allow and deny; live `AskUserQuestion` smoke verifies TTY fallback, answer textification, main-prompt answer injection, and final `result`. Live Python and TypeScript SDK game tests exercise `Write` approval through real file-creation TTY forms. Still partial: broader `Edit`/`MultiEdit` TTY variants, exact `permission_suggestions`, and exact `blocked_path` parity are not complete. |
 | `--permission-prompt-tool <name>` | Pass-through | Non-`stdio` values are forwarded to interactive Claude. `cctty` does not emulate custom permission prompt tools itself. | Parser coverage only. |
-| `--system-prompt-file` | Pass-through | Forwarded to interactive Claude. | Parser coverage because SDKs/older CLIs may emit it. |
-| `--task-budget`, `--max-thinking-tokens`, `--thinking`, `--thinking-display`, `--managed-settings`, `--resume-session-at` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. These are SDK/newer-CLI compatibility entries, not from the captured help output above. |
+| `--max-turns`, `--task-budget`, `--max-thinking-tokens`, `--thinking`, `--thinking-display` | Pass-through | Forwarded to interactive Claude. These are emitted by official SDK thinking, budget, and turn-limit options. | Parser coverage only. Print-mode parity still belongs to real Claude. |
+| `--system-prompt-file`, `--append-system-prompt-file`, `--managed-settings`, `--resume-session-at` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. These are SDK/newer-CLI compatibility entries, not from the captured public help output above. |
+| `--session-mirror`, `--sdk-url` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. These are hidden SDK transport/session flags; cctty does not implement the remote SDK transport itself. |
+| `--advisor`, `--channels`, `--dangerously-load-development-channels`, `--plan-mode-instructions`, `--plan-mode-required` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. Hidden/native Claude behavior is not differential-tested. |
+| `--agent-id`, `--agent-name`, `--team-name`, `--agent-color`, `--agent-type`, `--parent-session-id`, `--teammate-mode` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. These hidden teammate/team flags are treated as native Claude-owned semantics. |
+| `--remote`, `--rc`, `--teleport`, `--prefill`, `--prefill-b64`, `--rewind-files`, `--deep-link-cwd-b64`, `--deep-link-last-fetch`, `--deep-link-origin`, `--deep-link-repo`, `--enable-auth-status`, `--enable-auto-mode`, `--init`, `--init-only`, `--maintenance`, `--workload`, `--cowork`, `--xaa` | Pass-through | Forwarded to interactive Claude. | Parser coverage only. These are hidden/native flags found in the installed Claude binary; users should prefer documented flags unless an SDK or host app emits them. |
 
 ### Current High-Risk Gaps
 

src/args.rs

@@ -309,9 +309,19 @@ fn flag_arity(arg: &str) -> FlagArity {
     match flag {
         "--add-dir" | "--allowedTools" | "--allowed-tools" | "--betas" | "--disallowedTools"
         | "--disallowed-tools" | "--file" | "--mcp-config" | "--tools" => FlagArity::Many,
+        "--channels" | "--dangerously-load-development-channels" => FlagArity::Many,
         "--agent"
+        | "--advisor"
+        | "--agent-color"
+        | "--agent-id"
+        | "--agent-name"
+        | "--agent-type"
         | "--agents"
         | "--append-system-prompt"
+        | "--append-system-prompt-file"
+        | "--deep-link-cwd-b64"
+        | "--deep-link-last-fetch"
+        | "--deep-link-repo"
         | "--debug-file"
         | "--effort"
         | "--fallback-model"
@@ -323,22 +333,30 @@ fn flag_arity(arg: &str) -> FlagArity {
         | "--model"
         | "--name"
         | "-n"
+        | "--parent-session-id"
         | "--permission-mode"
         | "--permission-prompt-tool"
+        | "--plan-mode-instructions"
         | "--plugin-dir"
         | "--plugin-url"
+        | "--prefill"
+        | "--prefill-b64"
+        | "--rewind-files"
         | "--resume-session-at"
         | "--remote-control-session-name-prefix"
+        | "--sdk-url"
         | "--setting-sources"
         | "--settings"
         | "--system-prompt"
         | "--system-prompt-file"
         | "--task-budget"
+        | "--team-name"
+        | "--teammate-mode"
         | "--thinking"
-        | "--thinking-display" => FlagArity::One,
-        "--debug" | "-d" | "--from-pr" | "--remote-control" | "--worktree" | "-w" => {
-            FlagArity::Optional
-        }
+        | "--thinking-display"
+        | "--workload" => FlagArity::One,
+        "--debug" | "-d" | "--from-pr" | "--rc" | "--remote" | "--remote-control"
+        | "--teleport" | "--worktree" | "-w" => FlagArity::Optional,
         _ => FlagArity::None,
     }
 }
@@ -497,6 +515,40 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parse_passes_hidden_sdk_and_native_option_shapes() {
+        for case in hidden_sdk_and_native_option_cases() {
+            let mut argv = vec![
+                "cctty".to_owned(),
+                "--output-format".to_owned(),
+                "stream-json".to_owned(),
+            ];
+            argv.extend(case.argv.iter().map(|value| value.to_string()));
+            argv.push("--input-format".to_owned());
+            argv.push("stream-json".to_owned());
+
+            let invocation = Invocation::parse(argv)
+                .unwrap_or_else(|error| panic!("{} failed to parse: {error}", case.name));
+            assert_eq!(
+                invocation.input_format,
+                InputFormat::StreamJson,
+                "{} swallowed --input-format",
+                case.name
+            );
+            for expected in case.expected_passthrough {
+                assert!(
+                    invocation
+                        .passthrough_args
+                        .iter()
+                        .any(|arg| arg == expected),
+                    "{} did not pass through {expected:?}; got {:?}",
+                    case.name,
+                    invocation.passthrough_args
+                );
+            }
+        }
+    }
+
     #[test]
     fn parse_tracks_permission_prompt_stdio() {
         let invocation = Invocation::parse(vec![
@@ -729,6 +781,68 @@ mod tests {
         ]
     }
 
+    fn hidden_sdk_and_native_option_cases() -> Vec<OptionCase> {
+        vec![
+            pass("--advisor", &["--advisor", "sonnet"]),
+            pass("--agent-color", &["--agent-color", "blue"]),
+            pass("--agent-id", &["--agent-id", "agent_0000000000000000"]),
+            pass("--agent-name", &["--agent-name", "Test Agent"]),
+            pass("--agent-type", &["--agent-type", "reviewer"]),
+            pass(
+                "--append-system-prompt-file",
+                &["--append-system-prompt-file", "append.md"],
+            ),
+            pass("--channels", &["--channels", "server-a", "server-b"]),
+            pass("--cowork", &["--cowork"]),
+            pass(
+                "--dangerously-load-development-channels",
+                &[
+                    "--dangerously-load-development-channels",
+                    "server-a",
+                    "server-b",
+                ],
+            ),
+            pass("--deep-link-cwd-b64", &["--deep-link-cwd-b64", "L3RtcA=="]),
+            pass("--deep-link-last-fetch", &["--deep-link-last-fetch", "0"]),
+            pass("--deep-link-origin", &["--deep-link-origin"]),
+            pass("--deep-link-repo", &["--deep-link-repo", "owner/repo"]),
+            pass("--enable-auth-status", &["--enable-auth-status"]),
+            pass("--enable-auto-mode", &["--enable-auto-mode"]),
+            pass("--init", &["--init"]),
+            pass("--init-only", &["--init-only"]),
+            pass("--maintenance", &["--maintenance"]),
+            pass("--managed-settings", &["--managed-settings", "{}"]),
+            pass("--max-thinking-tokens", &["--max-thinking-tokens", "1024"]),
+            pass("--max-turns", &["--max-turns", "1"]),
+            pass("--parent-session-id", &["--parent-session-id", "parent-1"]),
+            pass(
+                "--plan-mode-instructions",
+                &["--plan-mode-instructions", "Write a short plan first"],
+            ),
+            pass("--plan-mode-required", &["--plan-mode-required"]),
+            pass("--prefill", &["--prefill", "Draft text"]),
+            pass("--prefill-b64", &["--prefill-b64", "RHJhZnQ="]),
+            pass("--rc", &["--rc", "mobile"]),
+            pass("--remote", &["--remote", "session"]),
+            pass("--resume-session-at", &["--resume-session-at", "message-1"]),
+            pass("--rewind-files", &["--rewind-files", "message-1"]),
+            pass("--sdk-url", &["--sdk-url", "ws://127.0.0.1:1234"]),
+            pass("--session-mirror", &["--session-mirror"]),
+            pass(
+                "--system-prompt-file",
+                &["--system-prompt-file", "system.md"],
+            ),
+            pass("--task-budget", &["--task-budget", "2048"]),
+            pass("--team-name", &["--team-name", "Test Team"]),
+            pass("--teammate-mode", &["--teammate-mode", "auto"]),
+            pass("--teleport", &["--teleport", "session-1"]),
+            pass("--thinking", &["--thinking", "adaptive"]),
+            pass("--thinking-display", &["--thinking-display", "full"]),
+            pass("--workload", &["--workload", "test-workload"]),
+            pass("--xaa", &["--xaa"]),
+        ]
+    }
+
     fn pass(name: &'static str, argv: &'static [&'static str]) -> OptionCase {
         OptionCase {
             name,

src/lib.rs

@@ -8,6 +8,10 @@ mod transcript;
 pub use error::{CcttyError, Result};
 
 pub async fn run_cli(argv: Vec<String>) -> Result<i32> {
+    if argv.get(1).map(String::as_str) == Some("__cctty-mcp-proxy") {
+        return runner::run_mcp_proxy(argv);
+    }
+
     let invocation = match args::Invocation::parse(argv) {
         Ok(invocation) => invocation,
         Err(error) => {