anthropics / anthropics/claude-agent-sdk-python
Python Agent SDK docs omit public options/types still present in `claude-agent-sdk==0.1.80`
- Lingua principale
- Python
- Stelle
- 8.1k
- Fork
- 1.3k
- Merge medio
- 2g 31m
- PR unite (30g)
- 1
Descrizione
## Summary
The current Python Agent SDK reference page says it is a complete API reference, but several public fields, types, and literal options that exist in `claude-agent-sdk==0.1.80` are missing from the docs.
Docs page checked: https://code.claude.com/docs/en/agent-sdk/python
Package checked: `claude-agent-sdk==0.1.80`
Some of these entries were documented in the older `0.1.74` reference and appear to have been removed accidentally.
## Reproduction
```python
import importlib.metadata as md
from claude_agent_sdk import ClaudeAgentOptions
from claude_agent_sdk.types import (
PermissionMode,
ToolPermissionContext,
DeferredToolUse,
HookEventMessage,
TaskBudget,
SystemPromptFile,
)
print(md.version("claude-agent-sdk"))
print([name for name in [
"session_id",
"skills",
"load_timeout_ms",
"task_budget",
] if name in ClaudeAgentOptions.__dataclass_fields__])
print(PermissionMode)
print(ToolPermissionContext.__annotations__)
print(DeferredToolUse.__annotations__)
print(HookEventMessage.__annotations__)
```
Observed with `claude-agent-sdk==0.1.80`:
```text
0.1.80
['session_id', 'skills', 'load_timeout_ms', 'task_budget']
typing.Literal['default', 'acceptEdits', 'plan', 'bypassPermissions', 'dontAsk', 'auto']
ToolPermissionContext includes tool_use_id and agent_id
DeferredToolUse is exported
HookEventMessage is exported
```
## Missing or inconsistent documentation
### 1. `ClaudeAgentOptions` omits existing fields
The docs' `ClaudeAgentOptions` class snippet is missing these public dataclass fields:
```python
session_id: str | None = None
skills: list[str] | Literal["all"] | None = None
load_timeout_ms: int = 60000
task_budget: TaskBudget | None = None
```
The property table also omits:
```text
session_id
load_timeout_ms
task_budget
```
`skills` is present in the property table but missing from the class snippet, so the class snippet and table are inconsistent.
### 2. `system_prompt` type omits `SystemPromptFile`
The installed package supports:
```python
system_prompt: str | SystemPromptPreset | SystemPromptFile | None = None
```
But the docs show only:
```python
system_prompt: str | SystemPromptPreset | None = None
```
`SystemPromptFile` is also not documented, despite being a public type:
```python
class SystemPromptFile(TypedDict):
type: Literal["file"]
path: str
```
### 3. `PermissionMode` omits `"auto"`
The installed package defines:
```python
PermissionMode = Literal[
"default",
"acceptEdits",
"plan",
"bypassPermissions",
"dontAsk",
"auto",
]
```
The docs currently omit `"auto"`.
If `"auto"` is deprecated or discouraged, it would be helpful to document it as deprecated instead of removing it from the literal list while it remains accepted by the SDK.
### 4. `ToolPermissionContext` omits `tool_use_id` and `agent_id`
The installed package includes:
```python
@dataclass
class ToolPermissionContext:
signal: Any | None = None
suggestions: list[PermissionUpdate] = field(default_factory=list)
tool_use_id: str | None = None
agent_id: str | None = None
blocked_path: str | None = None
decision_reason: str | None = None
title: str | None = None
display_name: str | None = None
description: str | None = None
```
The docs currently omit:
```text
tool_use_id
agent_id
```
These are important for permission UIs because they let callers associate a permission callback with the exact tool call and sub-agent.
### 5. `DeferredToolUse` section was removed but the type is still referenced
The current docs still show:
```python
deferred_tool_use: DeferredToolUse | None = None
```
on `ResultMessage`, and `PreToolUseHookSpecificOutput.permissionDecision` now includes `"defer"`.
However, the `DeferredToolUse` type itself is no longer documented. The installed package exports:
```python
@dataclass
class DeferredToolUse:
id: str
name: str
input: dict[str, Any]
```
### 6. `HookEventMessage` section was removed but the type is still referenced
The `ClaudeAgentOptions.include_hook_events` description says hook lifecycle events are emitted as `HookEventMessage` objects, but the `HookEventMessage` type section is no longer present.
The installed package exports:
```python
@dataclass
class HookEventMessage(SystemMessage):
hook_event_name: str = ""
session_id: str | None = None
uuid: str | None = None
```
The docs should either restore this type section or update the `include_hook_events` documentation to point to the correct documented type.
### 7. `can_use_tool` behavior note was removed
The previous docs explained that `can_use_tool` is invoked only for permission decisions that reach the `"ask"` path. This is still the behavior described by the package source docstring:
- It is not invoked for tools already permitted by `allowed_tools`
- It is not invoked for tools allowed by `permission_mode`, such as `"acceptEdits"` or `"bypassPermissions"`
- It is not invoked for tools allowed by settings rules
- `PreToolUse` hooks should be used to observe or gate every tool call
This is important behavior for SDK users implementing permission UIs, and should remain documented.
## Expected result
The Python SDK reference should match the public API exported by the current package.
At minimum, please restore or add documentation for:
```text
ClaudeAgentOptions.session_id
ClaudeAgentOptions.skills in the class snippet
ClaudeAgentOptions.load_timeout_ms
ClaudeAgentOptions.task_budget
SystemPromptFile
PermissionMode "auto"
ToolPermissionContext.tool_use_id
ToolPermissionContext.agent_id
DeferredToolUse
HookEventMessage
can_use_tool "ask path only" behavior
```
## Impact
The current docs make existing SDK features hard to discover and can lead users to believe supported options were removed. The missing `DeferredToolUse` and `HookEventMessage` sections are especially confusing because the current page still references those types from other documented APIs.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.