Add teaching Python agent CLI with Poetry and CI

docs/02-tools-permissions-and-execution.md

@@ -0,0 +1,119 @@
+# 02. 工具、权限与执行链需求文档
+
+## 1. 为什么工具系统是产品核心
+
+如果模型不能操作环境，它只是建议生成器。这个产品的目标是帮助用户推进真实工程任务，因此必须具备正式的工具系统。
+
+## 2. 工具系统需求
+
+### 2.1 基础工具能力
+产品至少需要以下工具类别：
+- 读文件
+- 改文件
+- 写文件
+- 搜索文件
+- 搜索内容
+- shell / 命令执行
+- todo / 任务管理
+- 用户追问
+- 启动子 agent
+- 调用外部 MCP 工具
+
+### 2.2 工具使用规范
+系统必须对模型明确规定工具使用优先级，避免：
+- 用 shell 替代专用文件工具
+- 误删或误改文件
+- 低效重复操作
+
+## 3. 权限系统需求
+
+### 3.1 用户控制边界
+用户必须能控制哪些工具自动允许，哪些要询问，哪些禁止。
+
+### 3.2 权限决策来源
+权限决策至少可能来自：
+- 当前模式
+- 用户规则
+- 项目规则
+- Hook 决策
+- 特殊工具安全策略
+
+### 3.3 被拒后的行为要求
+如果某次工具调用被拒绝，系统不能机械重试，而应：
+- 理解拒绝信号
+- 调整方案
+- 必要时向用户澄清
+
+## 4. 执行链路需求
+
+工具执行不能是“模型决定 -> 直接运行”。产品需要一条正式执行链：
+
+1. 找到工具
+2. 校验输入结构
+3. 做额外 validateInput
+4. 执行 PreToolUse hooks
+5. 做权限决策
+6. 真正执行工具
+7. 记录 telemetry
+8. 执行 PostToolUse hooks
+9. 格式化结果回流给模型
+
+## 5. 为什么需要 Hook
+
+Hook 的需求本质是：
+- 让组织规则进入运行时
+- 让系统可以插入额外检查
+- 让工具调用具备动态治理能力
+
+### Hook 至少要支持的行为
+- 返回消息
+- 阻断执行
+- 修改输入
+- 提供 allow / ask / deny 建议
+- 注入额外上下文
+
+## 6. 为什么输入校验是必需的
+
+模型本身会生成错误参数，因此产品必须在执行层拦住：
+- schema 不合法
+- 参数越界
+- 缺字段
+- 类型错误
+
+## 7. shell 类工具的特殊需求
+
+shell 工具的风险高于读写文件类工具，因此需要：
+- 更严格的权限策略
+- 可能的前置分类器检查
+- 更强的审计能力
+
+## 8. 工具执行结果的产品要求
+
+工具执行结果不仅要“返回成功/失败”，还要满足：
+- 可读
+- 可追踪
+- 能被后续 Hook 处理
+- 能成为 transcript 的一部分
+
+## 9. 伪代码表达
+
+```python
+def execute_tool(tool_name, raw_input, context):
+    tool = find_tool(tool_name)
+    validated = schema_validate(tool, raw_input)
+    validated = run_custom_validation(tool, validated)
+
+    hook_result = run_pre_hooks(tool, validated, context)
+    decision = resolve_permission(hook_result, context)
+    if decision == 'deny':
+        return denied_result()
+
+    final_input = maybe_update_input(validated, hook_result)
+    output = tool.call(final_input)
+    run_post_hooks(tool, final_input, output, context)
+    return output
+```
+
+## 10. 产品经理视角下的总需求句
+
+> 工具系统必须从“可调用”升级到“可治理”：既要让模型拥有执行能力，也要在执行前后经过校验、权限、Hook、审计与结果回流，确保整个过程安全、稳定、可追踪。