fix: prevent internal options from leaking as CLI flags

- Add missing control_timeout nil guard in convert_option
- Change catch-all from blindly converting to CLI flags to logging a
  warning and returning nil
- Change extra_args from list to map (flag => value or true for boolean
  flags) to align with the Python SDK
- Add .claude/rules/options.md to remind about keeping Options and
  CLI.Command in sync

Author: guess

.claude/rules/options.md

@@ -0,0 +1,6 @@
+---
+paths:
+  - "lib/claude_code/options.ex"
+---
+
+When adding, editing, or removing options from the session schema, update the corresponding `convert_option` clause in `lib/claude_code/cli/command.ex`. Options that are not CLI flags need a `defp convert_option(:option_name, _value), do: nil` clause to prevent them from leaking to the CLI.

lib/claude_code/cli/command.ex

@@ -11,6 +11,8 @@ defmodule ClaudeCode.CLI.Command do
 
   alias ClaudeCode.Session.PermissionMode
 
+  require Logger
+
   @required_flags ["--output-format", "stream-json", "--verbose", "--print"]
 
   @doc """
@@ -69,7 +71,7 @@ defmodule ClaudeCode.CLI.Command do
         nil -> acc
       end
     end)
-    |> Enum.reverse(Keyword.get(opts, :extra_args, []))
+    |> Enum.reverse(build_extra_args(Keyword.get(opts, :extra_args, %{})))
   end
 
   # -- Private: option conversion ---------------------------------------------
@@ -358,6 +360,7 @@ defmodule ClaudeCode.CLI.Command do
   defp convert_option(:sandbox, _value), do: nil
   defp convert_option(:thinking, _value), do: nil
   defp convert_option(:enable_file_checkpointing, _value), do: nil
+  defp convert_option(:control_timeout, _value), do: nil
   defp convert_option(:callers, _value), do: nil
   defp convert_option(:stub_name, _value), do: nil
   defp convert_option(:env, _value), do: nil
@@ -367,10 +370,22 @@ defmodule ClaudeCode.CLI.Command do
   defp convert_option(:prompt_suggestions, _value), do: nil
   defp convert_option(:tool_config, _value), do: nil
 
-  defp convert_option(key, value) do
-    # Convert unknown keys to kebab-case flags
-    flag_name = "--" <> (key |> to_string() |> String.replace("_", "-"))
-    {flag_name, to_string(value)}
+  # If this fires, a new option was added to Options but not handled here.
+  defp convert_option(key, _value) do
+    Logger.warning("ClaudeCode.CLI.Command: unknown option #{inspect(key)} — needs a convert_option clause")
+
+    nil
+  end
+
+  # -- Private: extra args conversion ------------------------------------------
+
+  defp build_extra_args(extra_args) when map_size(extra_args) == 0, do: []
+
+  defp build_extra_args(extra_args) do
+    Enum.flat_map(extra_args, fn
+      {flag, true} -> [flag]
+      {flag, value} -> [flag, value]
+    end)
   end
 
   # -- Private: setting sources preprocessing ----------------------------------

lib/claude_code/options.ex

@@ -133,7 +133,7 @@ defmodule ClaudeCode.Options do
   | `cli_path`                  | atom/string | `:bundled` | CLI binary resolution: `:bundled` (auto-install), `:global` (system), or explicit path |
   | `file`                      | list        | -          | File resources to download at startup (`"file_id:relative_path"` format) |
   | `enable_file_checkpointing` | boolean     | false      | Track file changes for rewinding. See [File Checkpointing](file-checkpointing.md) |
-  | `extra_args`                | list        | `[]`       | Additional CLI arguments passed directly to the binary |
+  | `extra_args`                | map         | `%{}`      | Additional CLI arguments passed directly to the binary (flag → value or `true` for boolean flags) |
 
   ### Debugging
 
@@ -533,10 +533,10 @@ defmodule ClaudeCode.Options do
         ~s|Per-tool configuration for built-in tools. Map of tool name to config map (e.g. %{"askUserQuestion" => %{"previewFormat" => "html"}})|
     ],
     extra_args: [
-      type: {:list, :string},
-      default: [],
+      type: {:map, :string, {:or, [:string, {:in, [true]}]}},
+      default: %{},
       doc:
-        ~s{Additional CLI arguments passed directly to the claude binary. Each element is a separate argument (e.g. ["--flag", "value"]).}
+        ~s|Additional CLI arguments passed directly to the claude binary. Map of flag name to value string, or `true` for boolean flags (e.g. %{"--some-flag" => "value", "--bool-flag" => true}).|
     ],
     max_buffer_size: [
       type: :pos_integer,

test/claude_code/cli/command_test.exs

@@ -1089,28 +1089,35 @@ defmodule ClaudeCode.CLI.CommandTest do
       refute "--enable-file-checkpointing" in args
     end
 
-    test "extra_args are appended at end of CLI args" do
-      opts = [model: "opus", extra_args: ["--new-flag", "value"]]
+    test "extra_args map with value is appended at end of CLI args" do
+      opts = [model: "opus", extra_args: %{"--new-flag" => "value"}]
 
       args = Command.to_cli_args(opts)
       assert "--model" in args
       assert "opus" in args
-      assert List.last(args) == "value"
-      assert Enum.at(args, -2) == "--new-flag"
+      assert "--new-flag" in args
+      assert "value" in args
+    end
+
+    test "extra_args map with boolean flag" do
+      opts = [extra_args: %{"--bool-flag" => true}]
+
+      args = Command.to_cli_args(opts)
+      assert "--bool-flag" in args
+      refute "true" in args
     end
 
     test "empty extra_args produces no extra arguments beyond options" do
-      opts = [model: "opus", extra_args: []]
+      opts = [model: "opus", extra_args: %{}]
 
       args = Command.to_cli_args(opts)
       assert "--model" in args
       assert "opus" in args
-      # --setting-sources "" is always added by ensure_setting_sources
       refute "--extra-args" in args
     end
 
     test "extra_args appear after all converted options" do
-      opts = [model: "opus", max_turns: 10, extra_args: ["--custom"]]
+      opts = [model: "opus", max_turns: 10, extra_args: %{"--custom" => true}]
 
       args = Command.to_cli_args(opts)
       custom_pos = Enum.find_index(args, &(&1 == "--custom"))

test/claude_code/options_test.exs

@@ -462,16 +462,16 @@ defmodule ClaudeCode.OptionsTest do
       assert validated[:enable_file_checkpointing] == false
     end
 
-    test "validates extra_args option as list of strings" do
-      opts = [extra_args: ["--some-flag", "value"]]
+    test "validates extra_args option as map" do
+      opts = [extra_args: %{"--some-flag" => "value", "--bool-flag" => true}]
       assert {:ok, validated} = Options.validate_session_options(opts)
-      assert validated[:extra_args] == ["--some-flag", "value"]
+      assert validated[:extra_args] == %{"--some-flag" => "value", "--bool-flag" => true}
     end
 
-    test "defaults extra_args to empty list" do
+    test "defaults extra_args to empty map" do
       opts = []
       assert {:ok, validated} = Options.validate_session_options(opts)
-      assert validated[:extra_args] == []
+      assert validated[:extra_args] == %{}
     end
 
     test "validates max_buffer_size option" do