docs(cli): replace legacy droid exec tool flags with --only-tools/--add-tools/--remove-tools

[lukealvoeiro]

Gap

EXEC-22 / DOC-2 / EXEC-60 (docs make a command fail, P2). The docs teach hidden legacy tool-selection flags (--restrict-tools, --additional-tools, --disabled-tools), and the CLI reference examples use a tool ID (Bash) that does not exist, so they fail at startup.

Evidence

• Docs:
  • docs/reference/cli-reference.mdx:130-132 (JP :62-64): droid exec --restrict-tools ApplyPatch,Bash, droid exec --additional-tools ApplyPatch,Bash
  • docs/cli/droid-exec/overview.mdx:66-68 (JP :65-67): help block lists the legacy flags; :376-382 (JP :336-342) uses them in examples
  • docs/cli/configuration/mcp.mdx:443 (EN and JP): says MCP filtering mirrors --restrict-tools / --disabled-tools
• Code (factory-mono): apps/cli/src/entrypoints/exec/command.ts:109-126 defines the visible --only-tools, --add-tools, --remove-tools; lines 127-150 keep --enabled-tools, --additional-tools, --disabled-tools, --restrict-tools with .hideHelp(). apps/cli/src/commands/resolveToolSelection.ts:413-416 throws Unknown tool identifier(s). droid exec --list-tools lists Execute; there is no Bash tool.
• Commands run (CLI built from source on dev, hermetic env, no network):

  $ droid exec --restrict-tools ApplyPatch,Bash "x"
  Unknown tool identifier(s)
  exit=1
  $ droid exec --additional-tools ApplyPatch,Bash "x"
  Unknown tool identifier(s)
  exit=1
  $ droid exec --help    # tool flags shown:
    --only-tools <ids>          Use only tool IDs or MCP:<server>[/<tool>] selectors
    --add-tools <ids>           Add tool IDs or MCP:<server>[/<tool>] selectors
    --remove-tools <ids>        Remove tool IDs or MCP:<server>[/<tool>] selectors
  

Why it matters

The CLI reference examples fail as written, and the flags the docs teach are hidden from droid exec --help, so users cannot discover the supported ones from the docs.

Fix

• Replace --restrict-tools, --additional-tools, --disabled-tools with --only-tools, --add-tools, --remove-tools in the help block, examples and both reference tables (EN and JP), and in the MCP filtering note.
• Replace the invalid Bash ID with Execute (ApplyPatch and execute-cli are valid and kept).
• The help-block lines now match current droid exec --help text.

Validation

Every new example run against the source-built CLI (offline, so a run that passes flag validation stops at the model connection):

$ droid exec --only-tools ApplyPatch "refactor files"                -> Connection error (flags accepted)
$ droid exec --add-tools ApplyPatch "refactor files"                 -> Connection error (flags accepted)
$ droid exec --auto medium --remove-tools execute-cli "run edits only" -> Connection error (flags accepted)
$ droid exec --only-tools ApplyPatch,Execute --list-tools            -> exit 0; ApplyPatch and Execute "allowed", others "blocked"
$ droid exec --add-tools ApplyPatch,Execute --list-tools             -> exit 0; "ApplyPatch (Apply Patch) - status: allowed override"
$ droid exec --remove-tools execute-cli --list-tools                 -> exit 0; "Execute - status: blocked override"
$ droid exec --only-tools ApplyPatch,Bash "x"                        -> Unknown tool identifier(s), exit 1 (confirms Bash is not a tool ID)

After the change, docs/ (EN and JP) has no remaining restrict-tools, additional-tools, disabled-tools or ApplyPatch,Bash.

Found by the scheduled CLI arguments audit.

[factory-droid]

Droid finished @lukealvoeiro's task —— View job

---

LGTM. No actionable issues found in the documentation updates.

0 inline comments posted