claw-code 源码分析：Tool Pool 组装——默认策略、过滤、MCP 开关如何影响「可用工具面」？

涉及源码：src/tool_pool.py、src/tools.py、src/permissions.py、src/main.py、src/system_init.py；衔接result/08.md、result/09.md、result/05.md。

1. 「可用工具面」在本仓库里的精确定义

这里说的不是哲学上的「模型理论上能用什么」，而是某次调用get_tools(...)/assemble_tool_pool(...)得到的PortingModule元组：
在那一刻，系统把哪些工具条目视为允许进入池子（给 UI 列表、给报告、给未来的 tool schema 装配）。

全集来自快照，进程内常量为PORTED_TOOLS：

# 37:37:src/tools.pyPORTED_TOOLS=load_tool_snapshot()

池子是在全集上做一串确定性过滤的结果；默认策略即各开关取默认值、且无ToolPermissionContext时的结果。

2. 组装流水线：assemble_tool_pool→get_tools

# 28:37:src/tool_pool.pydefassemble_tool_pool(simple_mode:bool=False,include_mcp:bool=True,permission_context:ToolPermissionContext|None=None,)->ToolPool:returnToolPool(tools=get_tools(simple_mode=simple_mode,include_mcp=include_mcp,permission_context=permission_context),simple_mode=simple_mode,include_mcp=include_mcp,)

ToolPool本身只缓存策略参数 + 过滤后的元组，并用 Markdown 输出总数与前 15 条（便于扫一眼，不全量刷屏）：

# 16:25:src/tool_pool.pydefas_markdown(self)->str:lines=['# Tool Pool','',f'Simple mode:{self.simple_mode}',f'Include MCP:{self.include_mcp}',f'Tool count:{len(self.tools)}',]lines.extend(f'-{tool.name}—{tool.source_hint}'fortoolinself.tools[:15])return'\n'.join(lines)

CLI 默认报表：python3 -m src.main tool-pool调用assemble_tool_pool()无参，即simple_mode=False、include_mcp=True、permission_context=None—— 在代码能力上等于「快照全集再过一遍权限过滤器（空）」，也就是最大池（与get_tools()默认一致）。

3. 过滤顺序与语义：get_tools的三段闸门

# 62:72:src/tools.pydefget_tools(simple_mode:bool=False,include_mcp:bool=True,permission_context:ToolPermissionContext|None=None,)->tuple[PortingModule,...]:tools=list(PORTED_TOOLS)ifsimple_mode:tools=[moduleformoduleintoolsifmodule.namein{'BashTool','FileReadTool','FileEditTool'}]ifnotinclude_mcp:tools=[moduleformoduleintoolsif'mcp'notinmodule.name.lower()and'mcp'notinmodule.source_hint.lower()]returnfilter_tools_by_permission_context(tuple(tools),permission_context)

3.1 Simple mode：硬编码「三件套」

开启后只保留BashTool、FileReadTool、FileEditTool三个精确工具名。
效果：可用工具面急剧收缩到「最小可讲清楚的 demo 面」，适合教学、沙箱、或先不接复杂工具生态。

边界：名字不在集合内的「基础」工具也会被砍掉——这是刻意极端的产品策略占位，不是自动推断「安全工具」。

3.2 MCP 开关：子串启发式

include_mcp=False时，丢弃满足以下任一条件的条目：

• module.name.lower()含mcp，或
• module.source_hint.lower()含mcp。

效果：把MCP 相关工具族从整体池里剥离（例如MCPTool、ListMcpResourcesTool等路径里带mcp的条目）。

边界：这是字符串启发式，不是协议层注册表；误杀/漏杀都可能在（例如路径改名不含mcp但实际是 MCP 工具）。成熟产品通常会改为显式kind/protocol字段。

3.3 权限上下文：按工具名 deny

# 56:59:src/tools.pydeffilter_tools_by_permission_context(tools:tuple[PortingModule,...],permission_context:ToolPermissionContext|None=None)->tuple[PortingModule,...]:ifpermission_contextisNone:returntoolsreturntuple(moduleformoduleintoolsifnotpermission_context.blocks(module.name))

# 18:20:src/permissions.pydefblocks(self,tool_name:str)->bool:lowered=tool_name.lower()returnloweredinself.deny_namesorany(lowered.startswith(prefix)forprefixinself.deny_prefixes)

效果：被 block 的工具不出现在池子里（能力面收缩）。这与PermissionDenial事件是两条线：前者是「列表里就没有」，后者是「模型点了但被拒」（见result/05.md）。

顺序：先 simple → 再 MCP → 再 permission。若 simple 已只剩 3 个工具，MCP 与 deny 只在这 3 个上继续过滤。

4. CLI 如何把策略旋钮暴露给用户

tools子命令把与池子相同的参数接到get_tools：

# 40:46:src/main.pytools_parser=subparsers.add_parser('tools',help='list mirrored tool entries from the archived snapshot')tools_parser.add_argument('--limit',type=int,default=20)tools_parser.add_argument('--query')tools_parser.add_argument('--simple-mode',action='store_true')tools_parser.add_argument('--no-mcp',action='store_true')tools_parser.add_argument('--deny-tool',action='append',default=[])tools_parser.add_argument('--deny-prefix',action='append',default=[])

# 132:140:src/main.pyifargs.command=='tools':ifargs.query:print(render_tool_index(limit=args.limit,query=args.query))else:permission_context=ToolPermissionContext.from_iterables(args.deny_tool,args.deny_prefix)tools=get_tools(simple_mode=args.simple_mode,include_mcp=notargs.no_mcp,permission_context=permission_context)output_lines=[f'Tool entries:{len(tools)}','']output_lines.extend(f'-{module.name}—{module.source_hint}'formoduleintools[:args.limit])print('\n'.join(output_lines))return0

注意--query分支：走render_tool_index→find_tools，它在PORTED_TOOLS上搜索，不应用simple/MCP/permission 过滤。用途是「在全镜像里找关键词」，不是「当前池里找」。

测试test_tool_permission_filtering_cli_runs验证--deny-prefix mcp后列表中不再出现MCPTool。

5. 关键边界：池子不等于路由全宇宙

PortRuntime.route_prompt在全量PORTED_TOOLS上匹配，而不是get_tools()过滤后的子集（见result/08.md、result/09.md）。
因此：

• Tool Pool /tools列表描述的是策略下的「展示给模型/用户的候选面」；
• 路由仍可能在策略禁止的工具名上命中——产品化时需要在路由后二次过滤或只把池内名字暴露给模型。

6.system_init与池策略的错位（阅读源码时要留意）

build_system_init_message使用无参get_tools()：

# 8:12:src/system_init.pydefbuild_system_init_message(trusted:bool=True)->str:setup=run_setup(trusted=trusted)commands=get_commands()tools=get_tools()

因此bootstrap报告里的 “Loaded tool entries” 计数对应默认最大池，不一定等于你刚用--simple-mode在 CLI 里看到的列表。若未来要在报告里体现「当前会话策略」，需要把同一套get_tools参数贯穿bootstrap_session/system_init。

7. 小结表

一句话：Tool Pool 组装把「可用工具面」变成可配置、可打印、可测试的函数；理解它的关键是过滤顺序、启发式边界、以及与路由/查询路径是否共用同一过滤。