Python Agent SDK docs omit public options/types still present in `claude-agent-sdk==0.1.80`

[oubeichen]

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

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:

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:

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:

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:

system_prompt: str | SystemPromptPreset | SystemPromptFile | None = None

But the docs show only:

system_prompt: str | SystemPromptPreset | None = None

SystemPromptFile is also not documented, despite being a public type:

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

3. PermissionMode omits "auto"

The installed package defines:

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:

@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:

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:

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:

@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:

@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:

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.