[DOCS] `--permission-prompt-tool` flag has no usage documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

CLI reference > CLI flags table, specifically the --permission-prompt-tool row.

Current Documentation

The CLI reference lists:

--permission-prompt-tool | Specify an MCP tool to handle permission prompts in non-interactive mode | claude -p --permission-prompt-tool mcp_auth_tool "query"

This is the only mention of this flag anywhere in the documentation. No other page references it.

What's Wrong or Missing?

The flag is listed but there is no documentation explaining:

1. What MCP tool interface is expected? What input schema does the permission prompt tool receive? What output schema should it return?
2. What does the permission prompt contain? Does it include the tool name, tool input, description? What fields?
3. What response format is expected? How does the MCP tool signal allow vs deny? Can it modify the tool input (like the Agent SDK's canUseTool callback)?
4. How does it interact with permission modes? Does --permission-prompt-tool override the permission mode, or work alongside it?
5. When is this useful? What's the use case for routing permission prompts to an MCP tool vs using --allowedTools or --dangerously-skip-permissions?

The Agent SDK has thorough documentation for canUseTool callbacks (platform.claude.com/docs/en/agent-sdk/user-input) including input schemas, response types, and complete examples. The CLI --permission-prompt-tool flag appears to serve a similar purpose but via MCP, yet has zero documentation on how to implement the MCP tool side.

Suggested Improvement

Add a dedicated section (either on the headless page or as part of the CLI reference) covering:

1. The MCP tool input schema for permission prompts (what the tool receives)
2. The expected response format (allow/deny/modify)
3. A complete example showing an MCP server that handles permission prompts
4. How this interacts with --allowedTools and permission modes
5. A pointer to the Agent SDK's canUseTool documentation as the programmatic equivalent

Impact

Medium - Makes feature difficult to understand

Additional Context

This flag is particularly relevant for non-interactive automation scenarios where claude -p needs tool approval without --dangerously-skip-permissions. Without documentation, users have no way to implement custom permission handling in CLI mode short of using the Agent SDK library directly.