Claude Code SDK #4：内置工具全解——11 种工具 × 5 种权限模式，精准控制 Agent 能干什么

11 种内置工具，先看全貌

allowed_tools vs disallowed_tools：两个过滤器的本质区别

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="分析这个仓库里的所有 Python 文件，找出潜在的安全问题",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],  # 这三个直接放行，不追问
    ),
):
    if hasattr(message, "result"):
        print(message.result)

options = ClaudeAgentOptions(
    disallowed_tools=["Write", "Edit", "Bash(rm *)"],
)

5 种 permission_mode：从最严格到最宽松

# TypeScript 示例
const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk",
};
// 效果：只有这三个工具能跑，其他所有工具调用直接拒绝，不发起询问

权限评估的 5 步顺序

1. 运行 Hooks：PreToolUse hook 可直接拒绝，但 hook 返回 allow 不会跳过后续步骤
2. 检查 deny 规则：disallowed_tools 匹配则立即拦截，bypassPermissions 也不例外
3. 应用当前 permission_mode：bypassPermissions 放行一切，acceptEdits 放行文件操作
4. 检查 allow 规则：allowed_tools 匹配则批准
5. 调用 canUseTool 回调：dontAsk 模式在此步直接拒绝

代码组合示例：三种典型配置

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def analyze_codebase():
    async for message in query(
        prompt="找出所有 TODO 注释并生成汇总报告",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="dontAsk",  # 固定工具范围，不询问
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(analyze_codebase())

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Write", "Bash"],
    disallowed_tools=["Bash(rm *)", "Bash(rmdir *)"],  # 显式拦截删除命令
    permission_mode="acceptEdits",
)

options = ClaudeAgentOptions(
    disallowed_tools=["WebSearch", "WebFetch"],  # 断网，但代码工具全开
    permission_mode="bypassPermissions",
)

子代理继承的注意点

实践建议

1. 先列出 allowed_tools 白名单，不需要的工具不要加。Bash 特别危险，只有真正需要执行命令时才加入
2. 对 Bash 用作用域写法精细化限制，比如 allowed_tools=["Bash(git log *)"] 只允许 git 只读命令
3. 无人值守脚本一律用 dontAsk，防止 Claude 在执行过程中等待用户输入而卡死
4. bypassPermissions 只在沙盒或测试环境中用，生产代码里出现它需要在代码审查时重点关注
5. 要屏蔽的底线用 disallowed_tools 而非依赖「不加进 allowed_tools」，两者的覆盖范围不同