先划边界，再给自由：防止 AI Agent 失控的权限审批管线与 Hooks 扩展点设计完全指南（learn-claude-code 深度拆解）

先划边界再给自由防止 AI Agent 失控的权限审批管线与 Hooks 扩展点设计完全指南learn-claude-code 深度拆解【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-codeAI Agent 一旦拥有执行 Bash 命令的能力一句帮我清理项目就可能演变成rm -rf /。learn-claude-code 是一个从 0 到 1 还原 claude code 式「Agent 脚手架harness」的开源教程项目其中s03 权限审批管线与s04 Hooks 扩展点两章正是防止 Agent 失控、同时让主循环保持干净的核心设计。本文带你读懂这套先划边界再给自由的安全架构 ️ 快速上手3 条命令跑通权限与 Hooks 示例git clone https://gitcode.com/GitHub_Trending/an/learn-claude-code cd learn-claude-code pip install -r requirements.txt随后运行两章的独立可执行示例python s03_permission/code.py # 三道闸门权限审批管线 python s04_hooks/code.py # Hooks 扩展点 运行前需在.env中配置 API Key步骤见 README.md 的 Quick Start 部分。️ 为什么 AI Agent 会失控信任模型不如信任代码在 s02 中Agent 已有 bash、read_file、write_file、edit_file、glob 五个工具。文件类工具受safe_path保护但 bash 是完全开放的——你无法靠相信模型会守规矩来保证安全。s03 给出的答案是安全必须由代码保证在每次工具执行前都过一遍检查。它不改动 Agent 主循环只在工具执行前插入一道check_permission()闸门按固定顺序穿过三道关卡闸门职责命中后的行为闸门 1拒绝列表永久禁止的危险操作rm -rf /、sudo、shutdown…立即阻止连问都不问闸门 2规则匹配上下文相关的风险操作写工作区外、执行rm文件…交给闸门 3 处理闸门 3用户审批暂停执行等待人类拍板用户决定允许或拒绝三道闸门全部未命中 → 直接执行。绝大多数日常操作走这条快路径体验不卡顿。闸门 1硬拒绝列表——一票否决拒绝列表用简单的字符串匹配实现定义见 s03_permission/code.py#L141DENY_LIST [rm -rf /, sudo, shutdown, reboot, mkfs, dd if, /dev/sda]设计要点在于顺序闸门 1 永远最先检查。这些是硬边界——无论模型给出多充分的理由命令也绝不会被执行。官方章节文档在 s03_permission/README.zh.md。闸门 2规则匹配——描述什么时候该问用户每条规则由「适用工具 判断条件 提示语」组成例如见 s03_permission/code.py#L151-L158文件工具read/write/edit目标路径解析后不在当前工作区内 → 提示访问工作区外bash命令中含rm、写/etc/、chmod 777→ 提示潜在破坏性命令规则的价值是把危险从模糊直觉变成了可枚举的条件清单新手也可以照着清单逐条扩展。闸门 3用户审批——把决定权交还人类闸门 2 命中后Agent 会打印风险原因、工具名和参数然后停下来等待你输入y/N——默认选项是拒绝不输就是拒绝。这个小细节很关键手滑按回车不会造成损失。如何接入主循环只加一行在工具分发处插入检查完整实现见 s03_permission/code.py#L176-L187if not check_permission(block): results.append({type: tool_result, content: Permission denied.}) continue值得玩味的细节拒绝结果会作为tool_result写回给模型。模型因此知道自己为什么被拦可以自动换一种安全的做法重试——边界不是死胡同而是反馈通道。 别把主循环改乱Hooks 扩展点把逻辑挂到外面s03 的检查是硬编码在循环里的。想再加点什么——记录每次 bash 调用日志写文件后自动 git add给 Slack 发通知——就得一次次改agent_loop函数体循环很快变成一团看不清的纠缠。s04 的答案只有一句话挂到循环上别写进循环里。四个核心事件覆盖 Agent 完整生命周期事件触发时机典型用途UserPromptSubmit用户输入后、进入 LLM 前输入校验、上下文注入PreToolUse工具执行前权限检查、日志记录PostToolUse工具执行后副作用自动 git add、大输出提醒Stop循环即将退出时清理收尾、判断是否继续注册表 触发器扩展逻辑的两个函数整个 Hooks 系统的骨架只有两小段见 s04_hooks/code.py#L123-L133HOOKS {UserPromptSubmit: [], PreToolUse: [], PostToolUse: [], Stop: []} def register_hook(event, callback): HOOKS[event].append(callback) def trigger_hooks(event, *args): # 按序执行回调非 None 立即短路返回 ...返回值即信号这是最优雅的设计PreToolUse返回非 None → 本次工具调用被阻止返回值写入tool_resultStop返回非 None → 把返回值注入为新消息强制循环继续UserPromptSubmit/PostToolUse的返回值不影响控制流只做观察权限检查从硬编码变成可插拔钩子s03 的check_permission()被原封不动地包装成PreToolUse钩子permission_hook见 s04_hooks/code.py#L140-L162主循环里只有一行变化# s03if not check_permission(block): ... # s04 blocked trigger_hooks(PreToolUse, block)保护能力一点没少但从此增删任何检查都不必再碰主循环——日志钩子、审批钩子、输出提醒钩子都只是注册表里的一行注册。 设计总结先划边界再给自由边界是代码不是承诺——模型的可靠性来自训练而安全必须来自确定性代码三道闸门顺序固定硬拒绝 → 规则匹配 → 用户审批未命中默认放行先拦后问绝不允许倒过来扩展逻辑挂在钩子上——循环是稳定的核心钩子是插座拒绝要写回tool_result——让模型看到边界并自我修正而不是撞墙后死循环一句话记忆模型是大脑边界是围栏Hooks 是扩展插座 围栏划得越清楚你才敢放心地把自由交给它。延伸阅读官方章节文档s03_permission/README.zh.md · s04_hooks/README.zh.md完整实现源码s03_permission/code.py · s04_hooks/code.py上一章工具分发s02_tool_use/README.zh.md下一章先计划再执行s05_todo_write/README.zh.md【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考