[DOCS] Agent SDK Python examples use inconsistent import paths for HookMatcher and related types

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://docs.anthropic.com/en/docs/agent-sdk/hooks - https://docs.anthropic.com/en/docs/agent-sdk/user-input - https://docs.anthropic.com/en/docs/agent-sdk/python - https://docs.anthropic.com/en/docs/agent-sdk/overview

Section/Topic

Import statements in Python code examples across Agent SDK documentation pages.

Current Documentation

Pattern A - Root package import (hooks.md, overview.md, python.md):

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

Pattern B - Types submodule import (user-input.md, python.md):

from claude_agent_sdk.types import HookMatcher, PermissionResultAllow
from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

Specific locations:

• hooks.md line 26: from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
• overview.md line 113: from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
• python.md line 1335: from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
• user-input.md lines 78-83: imports from claude_agent_sdk.types
• user-input.md line 211: from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny
• user-input.md line 585: from claude_agent_sdk.types import HookMatcher, PermissionResultAllow
• python.md line 385: from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

What's Wrong or Missing?

The documentation provides conflicting import paths for HookMatcher:

1. Some examples import from the root package: from claude_agent_sdk import HookMatcher
2. Other examples import from the types submodule: from claude_agent_sdk.types import HookMatcher

This inconsistency can cause:

• Runtime errors if one import path doesn't work (e.g., if HookMatcher is not re-exported in __init__.py)
• User confusion about the canonical import style
• Copy-paste failures when combining code snippets from different documentation pages

The same inconsistency affects PermissionResultAllow, PermissionResultDeny, and HookContext.

Suggested Improvement

1. Determine canonical import path: Check whether HookMatcher and permission types are explicitly re-exported in claude_agent_sdk/__init__.py

1. Standardize all examples: Use ONE consistent import pattern across all documentation:

If types are re-exported (preferred for ergonomics):
``python
from claude_agent_sdk import (
query,
ClaudeAgentOptions,
HookMatcher,
PermissionResultAllow,
PermissionResultDeny
)
``

If types are NOT re-exported:
``python
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import HookMatcher, PermissionResultAllow, PermissionResultDeny
``

1. Add an imports reference section to the Python SDK reference page showing all public exports and their locations.

Impact

High - Prevents users from using a feature

Additional Context

• Affects 4 documentation pages in the Agent SDK section
• TypeScript SDK uses consistent import patterns
• Similar to PEP 8 recommendation for consistent import style within a project