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

[coygeek]

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.

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

3. (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.

[github-actions]

Found 3 possible duplicate issues:

1. Is --allowedTools with --permission-mode bypassPermissions behavior expected? #12232
2. [DOCS] Conflicting "Default" Logic between claude_code System Prompt Preset and CLAUDE.md Loading #17576
3. Skill allowed-tools doesn't grant permission for Bash commands #14956

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[coygeek]

Following up on my previous report regarding the terminology and logic mismatch between the Claude Code CLI and the Agent SDK. After reviewing the latest documentation, here is the status of the requested changes.

1. What’s FIXED

• Introduction of the tools parameter in the SDK: The SDK has successfully implemented the "Long term/API Suggestion" to include a tools parameter that aligns with the CLI's --tools flag. This allows developers to define the base toolset or use the claude_code preset.
  • Reference: https://platform.claude.com/docs/en/agent-sdk/typescript (Options table) and https://platform.claude.com/docs/en/agent-sdk/python (ClaudeAgentOptions section).
• Clarification of Permission Modes: The documentation at https://platform.claude.com/docs/en/agent-sdk/permissions now provides a much clearer hierarchy of how permissions are evaluated, explicitly separating "Permission rules" and "Permission modes" from the tool registry.

2. What’s UNRESOLVED

• Missing "Note for CLI Users": The critical suggestion to add a warning box in the Agent SDK Overview (https://platform.claude.com/docs/en/agent-sdk/overview) was not implemented. This remains a major friction point. A developer moving from the CLI (where --allowedTools grants auto-approval) to the SDK will still likely see allowedTools in the code examples and assume it functions as a permission bypass rather than a registry.
• Ambiguous allowedTools Definition: In the technical references for both languages, the definition for allowedTools remains "List of allowed tool names."
  • Reference: https://platform.claude.com/docs/en/agent-sdk/typescript#options.
  • Technical Nuance: This description fails to specify that tools in this list still require manual approval via the canUseTool callback or a permissive permissionMode. Without an explicit "Note: This does not auto-approve," the functional swap between CLI and SDK remains obscured.
• Terminology Confusion in Permissions Guide: At https://platform.claude.com/docs/en/agent-sdk/mcp#grant-access-with-allowedtools, the phrasing "Grant access with allowedTools" is used. In a security context, "granting access" often implies bypassing a gate. For an MCP user, this reinforces the incorrect assumption that allowedTools is the mechanism for auto-approval.

3. Conclusion

I am keeping this issue open.

While the addition of the tools parameter is a positive step toward parity, the documentation has not yet addressed the primary trap for developers: the fact that allowedTools in the SDK behaves like --tools in the CLI.

To resolve this, we still need:

1. A prominent "Note for CLI Users" in the https://platform.claude.com/docs/en/agent-sdk/overview guide.
2. An update to the allowedTools / allowed_tools parameter descriptions in the TS and Python references to explicitly state: "This defines tool availability, not auto-approval. For auto-approval, use permissionMode."

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.