[DOCS] Terminology Collision: Inconsistent meaning of `allowedTools` between CLI and Agent SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/cli-reference.md - docs/en/agent-sdk/overview.md - docs/en/agent-sdk/typescript.md - docs/en/agent-sdk/python.md

Section/Topic

Tool configuration and permission management logic when transitioning from CLI usage to SDK integration.

Current Documentation

In CLI Reference:

--tools: "Restrict which built-in tools Claude can use (works in both interactive and print modes)." --allowedTools: "Tools that execute without prompting for permission. To restrict which tools are available, use --tools instead."

In Agent SDK Overview/Reference:
The SDK uses allowedTools (TS) or allowed_tools (Python) as the primary way to define the toolset:

options: { allowedTools: ["Read", "Edit", "Bash"] } allowed_tools: list[str] = field(default_factory=list) # List of allowed tool names

What's Wrong or Missing?

There is a significant terminology mismatch between the CLI and the SDK that will cause logic errors for developers:

1. Functional Swap: In the CLI, allowedTools is a permission bypass (auto-approval). In the SDK, allowedTools is the tool registry (the list of tools the agent can see).
2. Conflicting Expectations: A developer moving from the CLI to the SDK will likely assume that passing a list to allowedTools in the SDK will automatically approve those tools. However, in the SDK, tools listed in allowedTools still trigger the canUseTool callback or follow the permissionMode, unless bypassPermissions is explicitly set.
3. Ambiguity: The CLI uses --tools to define availability, but the SDK uses allowedTools to define availability.

Suggested Improvement

The documentation needs to explicitly call out this distinction to prevent security or workflow misunderstandings.

Proposed Changes:

1. In the Agent SDK Overview, add a "Note for CLI Users" box:

> Note for CLI Users: In the SDK, allowedTools defines the tools available to the agent (equivalent to the CLI's --tools flag). To configure auto-approval (the behavior of the CLI's --allowedTools flag), use the permissionMode option or the canUseTool callback.

1. Update the parameter descriptions in typescript.md and python.md to reflect that allowedTools is for registration, not prompt-skipping.

1. (Long term/API Suggestion): Consider aliasing allowedTools to tools in the SDK to match the CLI’s tools flag, making the terminology consistent across the ecosystem.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: [SDK Permissions Guide in /docs/en/agent-sdk/permissions]
• Impact: This collision increases the "Time to Hello World" for developers who have grown accustomed to the CLI's terminology and might inadvertently write SDK code that they believe is auto-approving tools when it is actually just enabling them for manual approval.