anthropics / anthropics/claude-agent-sdk-python
Python Agent SDK docs omit public options/types still present in `claude-agent-sdk==0.1.80`
- Linguagem predominante
- Python
- Estrelas
- 8.1k
- Forks
- 1.3k
- Merge médio
- 2d 31min
- PRs com merge (30d)
- 1
Descrição
## 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.
Guia de contribuição
Nenhum guia de contribuição indexado para este repositório
Avaliação
Esta issue ainda não foi avaliada.