[BUG] mismatch between the Claude CLI control protocol and can_use_tool permission

[nshkrdotcom]

There is a bug in claude-agent-sdk-python. Tracking it down:

 ▐▛███▜▌   Claude Code v2.1.6
▝▜█████▛▘  Sonnet 4.5 · Claude API
  ▘▘ ▝▝    ~/p/g/n/claude-agent-sdk-python

❯ We’re seeing a mismatch between the Claude CLI control protocol and the Python/Elixir SDKs’ can_use_tool permission
  callbacks. We need to determine whether the CLI is supposed to emit control_request events (subtype: "can_use_tool")
  when
  --permission-prompt-tool stdio is active, and why it isn’t in CLI 2.1.6.
  Context / expectation
  - Both SDKs implement can_use_tool by enabling the control protocol and setting --permission-prompt-tool stdio.
  - The control protocol defines control_request with subtype: "can_use_tool" and expects the SDK to respond
  allow/deny.
  - If the CLI does not emit those control callbacks, permission hooks can never fire (even though tool use itself
  works).
  What I did
  I added a Python‑side repro script that uses the local SDK source (no install needed) and registers a can_use_tool
  callback. It forces a Write tool call and fails if no permission callbacks are observed.
  Script path:
  /home/home/p/g/n/claude-agent-sdk-python/examples/permission_callback_probe.py
  Current status / repro output (CLI 2.1.6)
  $ python3 /home/home/p/g/n/claude-agent-sdk-python/examples/permission_callback_probe.py
  ====================================================================
  Permission Callback Probe (Python SDK, live CLI)
  ====================================================================
  Claude CLI: claude
  Claude CLI version: 2.1.6 (Claude Code)
  Prompt:
  Use the Write tool to create a file with the exact path and content below.
  file_path: /home/home/p/g/n/claude-agent-sdk-python/examples/_output/permissions_callback_probe.txt
  content: hello from permissions probe
  After the write completes, reply with exactly: WROTE
  WROTE
  FAILED:
  - No can_use_tool callbacks observed from CLI control protocol.
  Claude CLI version: 2.1.6 (Claude Code)
  Why this matters
  - Tool use is happening and the CLI completes the action, but no can_use_tool control callbacks are ever emitted, so
  SDK
  permission hooks never run.
  - This blocks the SDK from enforcing/observing tool permissions even though the protocol says it should.
  Questions
  1. Is CLI 2.1.6 expected to emit control_request / can_use_tool callbacks when --permission-prompt-tool stdio is
  set?
  2. If yes, is this a known CLI regression?
  3. If no, is the SDK’s permission callback feature ahead of the CLI and should be documented as not supported?
  4. Is there a CLI flag or config required to enable these callbacks beyond --permission-prompt-tool stdio?
  We need to confirm whether this is a CLI bug, a protocol mismatch, or a missing CLI flag.

[nshkrdotcom]

Below is a detailed reproduction report for issue #469. This is a comment body only (not a new issue). It includes full background, setup steps, the exact output observed, and the complete minimal script so maintainers can copy/paste it into their repo.

---

Background / Context

I am the author of the Elixir port of the Claude Agent SDK and am trying to match CLI behavior precisely. The Python SDK appears to support can_use_tool callbacks via the control protocol (permission_prompt_tool_name forced to "stdio"), but in practice the callback is never invoked even when the CLI performs a tool call successfully. This report provides an isolated, minimal reproduction using the official Python SDK.

The expected behavior is:

• CLI emits control_request with subtype can_use_tool when a tool call (e.g. Write) occurs.
• Python SDK receives this and invokes the can_use_tool callback.

The observed behavior is:

• CLI executes the tool successfully (file is created).
• The stream includes a ToolUseBlock for Write.
• No can_use_tool callback is invoked.

This indicates a mismatch between the Python SDK control-protocol expectations and the CLI behavior (or a CLI bug / SDK integration bug).

---

Environment

• Python: 3.12.3 (main, Jan 8 2026, 11:30:50) [GCC 13.3.0]
• Platform: Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.39
• SDK version: 0.1.19
• Repo path: /home/home/p/g/n/claude_agent_sdk/anthropics/claude-agent-sdk-python
• Repo git: 8602ff4
• CLI path: /home/home/.local/bin/claude
• CLI version: 2.1.7 (Claude Code)

---

Reproduction Steps (clean, explicit)

1. Clone the SDK repo and enter it:

git clone https://github.com/anthropics/claude-agent-sdk-python
cd claude-agent-sdk-python

2. Create and activate a virtualenv:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies (editable install):

pip install -e .

4. Create a file named examples/permission_callback_probe_minimal.py with the exact script below.

5. Run the script:

python3 examples/permission_callback_probe_minimal.py

---

Exact Output Observed

python3 examples/permission_callback_probe_minimal.py
==============================================================================
BUG REPORT: can_use_tool callback not invoked
==============================================================================

Summary
-------
- Write tool executed (file created) but can_use_tool callback did not fire.
- This demonstrates a mismatch between the Python SDK's control-protocol expectations and CLI behavior.
- Result: permission callbacks are unusable even though tool execution succeeds.

Environment
-----------
- Python: 3.12.3 (main, Jan  8 2026, 11:30:50) [GCC 13.3.0]
- Platform: Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.39
- SDK version: 0.1.19
- Repo path: /home/home/p/g/n/claude_agent_sdk/anthropics/claude-agent-sdk-python
- Repo git: 8602ff4
- CLI path: /home/home/.local/bin/claude
- CLI version: 2.1.7 (Claude Code)

Repro steps
-----------
- Create ClaudeSDKClient with can_use_tool callback and permission_mode=default.
- Allow only the Write tool (tools=['Write'], allowed_tools=['Write']).
- Prompt the model to write a file via Write tool.
- Wait for streaming responses to complete.
- Check that the file was written and whether callbacks fired.

Expected behavior
-----------------
- CLI emits control_request subtype can_use_tool for Write.
- Python SDK invokes can_use_tool callback at least once.
- Callback receives tool name and tool input before execution.

Observed behavior
-----------------
- File written: True
- File contents: 'hello from permission callback probe'
- Tool use blocks seen in stream: 1
- can_use_tool callbacks observed: 0
- Received message types: ['SystemMessage', 'AssistantMessage', 'UserMessage', 'AssistantMessage', 'ResultMessage']

Evidence
--------
- Target file: /home/home/p/g/n/claude_agent_sdk/anthropics/claude-agent-sdk-python/examples/_output/permission_callback_probe_minimal.txt
- Tool use blocks: [
  {
    "name": "Write",
    "id": "toolu_01CUFHPFQHE2dpuFetBT4nx3",
    "input": {
      "file_path": "/home/home/p/g/n/claude_agent_sdk/anthropics/claude-agent-sdk-python/examples/_output/permission_callback_probe_minimal.txt",
      "content": "hello from permission callback probe"
    }
  }
]
- Callback log: []

Notes
-----
- When can_use_tool is set, the SDK forces permission_prompt_tool_name='stdio'.
- If callbacks are missing, the CLI is not emitting can_use_tool requests.
- This is a functional bug in the Python SDK/CLI integration.
- Related: https://github.com/anthropics/claude-agent-sdk-python/issues/469

==============================================================================

---

Full Script (copy/paste)

#!/usr/bin/env python3
"""
Bug report reproduction: can_use_tool callback never fires.

This script is intentionally verbose. If the callback does not fire, it prints
an explicit, standalone bug report suitable for filing upstream.

WARNING: Running this script invokes the Claude Code CLI. It will attempt to
create a file via the Write tool and expects the CLI to emit can_use_tool
control callbacks. If no callbacks are observed, it exits with a non-zero code.
"""

from __future__ import annotations

import asyncio
import json
import os
import platform
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Any, Iterable

REPORT_WIDTH = 78


def _section(title: str, lines: Iterable[str]) -> None:
    print("\n" + title)
    print("-" * len(title))
    for line in lines:
        print(f"- {line}")


def _json_dump(value: Any) -> str:
    return json.dumps(value, indent=2, default=str)


def _run_command(args: list[str]) -> tuple[str | None, int | None]:
    try:
        result = subprocess.run(
            args,
            check=False,
            capture_output=True,
            text=True,
        )
    except FileNotFoundError:
        return None, None

    output = (result.stdout or "") + (result.stderr or "")
    return output.strip() or None, result.returncode


def _print_report(report: dict[str, list[str]]) -> None:
    print("=" * REPORT_WIDTH)
    print("BUG REPORT: can_use_tool callback not invoked")
    print("=" * REPORT_WIDTH)
    for title, lines in report.items():
        _section(title, lines)

    print("\n" + "=" * REPORT_WIDTH)


async def main() -> int:
    repo_root = Path(__file__).resolve().parents[1]
    output_dir = repo_root / "examples" / "_output"
    output_dir.mkdir(parents=True, exist_ok=True)
    target_file = output_dir / "permission_callback_probe_minimal.txt"

    if os.getenv("DRY_RUN") == "1":
        print("DRY_RUN=1: Not invoking Claude Code CLI.")
        print(f"Would write to: {target_file}")
        return 0

    from claude_agent_sdk import (
        AssistantMessage,
        ClaudeAgentOptions,
        ClaudeSDKClient,
        PermissionResultAllow,
        ToolUseBlock,
        __version__,
    )

    permission_calls: list[dict[str, Any]] = []

    async def can_use_tool(tool_name: str, input_data: dict, context: Any) -> PermissionResultAllow:
        permission_calls.append(
            {
                "tool": tool_name,
                "input": input_data,
                "suggestions": getattr(context, "suggestions", []),
            }
        )
        return PermissionResultAllow()

    options = ClaudeAgentOptions(
        can_use_tool=can_use_tool,
        permission_mode="default",
        tools=["Write"],
        allowed_tools=["Write"],
        cwd=str(repo_root),
    )

    prompt = f"""\
Use the Write tool to create a file with the exact path and content below.

file_path: {target_file}
content: hello from permission callback probe

After the write completes, reply with exactly: WROTE
"""

    tool_use_blocks: list[dict[str, Any]] = []
    received_message_types: list[str] = []

    async with ClaudeSDKClient(options) as client:
        await client.query(prompt)
        async for msg in client.receive_response():
            received_message_types.append(type(msg).__name__)
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, ToolUseBlock):
                        tool_use_blocks.append(
                            {
                                "name": block.name,
                                "id": block.id,
                                "input": block.input,
                            }
                        )

    file_written = target_file.exists()
    file_contents = None
    if file_written:
        file_contents = target_file.read_text(encoding="utf-8").strip()

    cli_path = shutil.which("claude")
    cli_version = None
    if cli_path:
        cli_version_output, _code = _run_command([cli_path, "--version"])
        cli_version = cli_version_output

    git_output, _git_code = _run_command(["git", "-C", str(repo_root), "rev-parse", "--short", "HEAD"])

    report = {
        "Summary": [
            "Write tool executed (file created) but can_use_tool callback did not fire.",
            "This demonstrates a mismatch between the Python SDK's control-protocol expectations and CLI behavior.",
            "Result: permission callbacks are unusable even though tool execution succeeds.",
        ],
        "Environment": [
            f"Python: {sys.version.splitlines()[0]}",
            f"Platform: {platform.platform()}",
            f"SDK version: {__version__}",
            f"Repo path: {repo_root}",
            f"Repo git: {git_output or 'unknown'}",
            f"CLI path: {cli_path or 'not found'}",
            f"CLI version: {cli_version or 'unknown'}",
        ],
        "Repro steps": [
            "Create ClaudeSDKClient with can_use_tool callback and permission_mode=default.",
            "Allow only the Write tool (tools=['Write'], allowed_tools=['Write']).",
            "Prompt the model to write a file via Write tool.",
            "Wait for streaming responses to complete.",
            "Check that the file was written and whether callbacks fired.",
        ],
        "Expected behavior": [
            "CLI emits control_request subtype can_use_tool for Write.",
            "Python SDK invokes can_use_tool callback at least once.",
            "Callback receives tool name and tool input before execution.",
        ],
        "Observed behavior": [
            f"File written: {file_written}",
            f"File contents: {file_contents!r}",
            f"Tool use blocks seen in stream: {len(tool_use_blocks)}",
            f"can_use_tool callbacks observed: {len(permission_calls)}",
            f"Received message types: {received_message_types}",
        ],
        "Evidence": [
            f"Target file: {target_file}",
            f"Tool use blocks: {_json_dump(tool_use_blocks)}",
            f"Callback log: {_json_dump(permission_calls)}",
        ],
        "Notes": [
            "When can_use_tool is set, the SDK forces permission_prompt_tool_name='stdio'.",
            "If callbacks are missing, the CLI is not emitting can_use_tool requests.",
            "This is a functional bug in the Python SDK/CLI integration.",
            "Related: https://github.com/anthropics/claude-agent-sdk-python/issues/469",
        ],
    }

    if not file_written:
        report["Observed behavior"].append("Failure reason: file not written.")
        _print_report(report)
        return 2

    if file_contents != "hello from permission callback probe":
        report["Observed behavior"].append("Failure reason: unexpected file contents.")
        _print_report(report)
        return 3

    if not permission_calls:
        _print_report(report)
        return 1

    print("=" * REPORT_WIDTH)
    print("OK: can_use_tool callback observed.")
    print("=" * REPORT_WIDTH)
    _section("Observed behavior", report["Observed behavior"])
    _section("Evidence", report["Evidence"])
    return 0


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))

---

Recommendations

1. Confirm whether Claude Code CLI 2.1.7 (and similar versions) emits control_request can_use_tool for built-in tool execution when permission_prompt_tool_name=stdio is set.
2. If the CLI no longer emits this control request, the SDK should detect and warn (e.g., explicit runtime warning if tool_use is observed but no permission callback is ever triggered).
3. If the CLI is supposed to emit can_use_tool, then the CLI should be fixed to emit the callback for built-in tools under the control protocol.

---

If you need any additional data (trace logs, additional reproductions, or a packet capture of the control stream), I can provide them.

[eharris128]

Would love to hear if this is being pursued.

My research attempts to build on top of can_use_tool led me to nearly the same fairly mode.

I was running 2.1.31 (Claude Code) and claude-agent-sdk 0.1.29