《AI Agent 高级编程》3.1 核心概念：subagent/hooks/权限/session 搭研究任务

$ which claude
/opt/homebrew/bin/claude
$ ls -l /opt/homebrew/bin/claude
lrwxr-xr-x  claude -> /opt/homebrew/Caskroom/claude-code/2.1.285/claude

import claude_agent_sdk as s
print([n for n in dir(s) if n in
       ("ClaudeAgentOptions", "AgentDefinition", "HookMatcher",
        "query", "ClaudeSDKClient")])

['AgentDefinition', 'ClaudeAgentOptions', 'ClaudeSDKClient', 'HookMatcher', 'query']

import dataclasses
from claude_agent_sdk import AgentDefinition, HookMatcher

for f in dataclasses.fields(AgentDefinition):
    print(f.name)

description
prompt
tools
disallowedTools
model
skills
memory
mcpServers
initialPrompt
maxTurns
background
effort
permissionMode

for f in dataclasses.fields(HookMatcher):
    print(f.name)

matcher
hooks
timeout

import inspect
from claude_agent_sdk import query, ClaudeSDKClient
print(inspect.signature(query))
print(inspect.signature(ClaudeSDKClient.__init__))

(*, prompt: str | collections.abc.AsyncIterable[dict[str, Any]], options: ClaudeAgentOptions | None = None, transport: Transport | None = None) -> collections.abc.AsyncIterator[UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | RateLimitEvent | ConversationResetMessage]
(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)

from claude_agent_sdk import AgentDefinition

agents = {
    "researcher": AgentDefinition(
        description="负责检索资料并返回要点，适合需要外部信息的问题",
        prompt="你是资料检索员。用 WebSearch/WebFetch 找证据，返回带来源的要点。",
        tools=["WebSearch", "WebFetch", "Read"],
    ),
    "summarizer": AgentDefinition(
        description="把长材料压缩成结构化摘要",
        prompt="你是摘要员。把输入压成不超过 5 条的要点。",
        tools=["Read"],
    ),
}

from claude_agent_sdk import HookMatcher

async def audit_bash(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    print(f"[audit] Bash: {command}")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "禁止执行 rm -rf",
            }
        }
    return {}

hooks = {"PreToolUse": [HookMatcher(matcher="Bash", hooks=[audit_bash])]}

# claude_agent_sdk/_internal/client.py（本机实测）
agents_dict = None
if configured_options.agents:
    agents_dict = {
        name: {k: v for k, v in asdict(agent_def).items() if v is not None}
        for name, agent_def in configured_options.agents.items()
    }

typing.Literal['default', 'acceptEdits', 'plan', 'bypassPermissions', 'dontAsk', 'auto'] | None

# research_sdk.py —— 需要活的 Claude 会话才能运行，本节未执行
import anyio
from claude_agent_sdk import (
    ClaudeAgentOptions, AgentDefinition, HookMatcher, query,
    AssistantMessage, ResultMessage,
)

async def audit(input_data, tool_use_id, context):
    print(f"[hook] {input_data['tool_name']} 被调用")
    return {}

OPTIONS = ClaudeAgentOptions(
    system_prompt="你是研究助理。先检索、再摘要，最后给出带来源的结论。",
    agents={
        "researcher": AgentDefinition(
            description="检索资料并返回带来源的要点",
            prompt="用 WebSearch/WebFetch 找证据，返回要点与来源 URL。",
            tools=["WebSearch", "WebFetch"],
        ),
        "summarizer": AgentDefinition(
            description="把长材料压缩成不超过 5 条要点",
            prompt="只做压缩，不新增事实。",
        ),
    },
    allowed_tools=["WebSearch", "WebFetch", "Read"],
    permission_mode="default",
    hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[audit])]},
    max_turns=12,
)

async def main():
    async for msg in query(prompt="调研 2026 年 Agent 记忆系统的三种主流方案", options=OPTIONS):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if getattr(block, "type", "") == "text":
                    print(block.text)
        elif isinstance(msg, ResultMessage):
            print("轮数:", msg.num_turns, "成本 USD:", msg.total_cost_usd)

anyio.run(main)

（本代码需要活的 Claude 会话才能运行，本节未执行，故不贴输出。）