feat: Chapter 7 — Permission system with danger command blocking

Demo code:
- Add utils/permissions.ts with DEFAULT_RULES (13 rules),
  checkPermission(), createPermissionContext()
- Three-tier rules: read-only allow, dangerous deny, write ask
- Three modes: default (strict), auto (read-only auto-allow),
  bypassPermissions (skip all)
- Integrate into query.ts via optional checkPermission callback
- Permission checked before every tool execution in Agentic Loop
- Update main.ts with 4 permission test cases (allow/ask/deny)

Documentation:
- Add "Hands-on: Permission Check Integration" to Ch7 (zh-CN/en)
- Explain decision flow, rule hierarchy, mode comparison

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anthhub

demo/main.ts

@@ -30,11 +30,10 @@ import type {
   ContentBlock,
   Tool,
   AppConfig,
-  PermissionRule,
-  PermissionContext,
-  PermissionDecision,
 } from "./types/index.js";
 
+import { createPermissionContext, createCheckPermissionFn, DEFAULT_RULES } from "./utils/permissions.js";
+
 import { buildTool } from "./Tool.js";
 import { allTools, findToolByName, getToolsForAPI } from "./tools.js";
 import { query } from "./query.js";
@@ -79,44 +78,14 @@ const messages: Message[] = [userMsg, assistantMsg];
 
 // ─── 验证权限系统 ──────────────────────────────────────────────────────────
 
-// 定义权限规则
-const permissionRules: PermissionRule[] = [
-  { toolName: "Read", behavior: "allow", source: "default", reason: "只读操作无风险" },
-  { toolName: "Bash", pattern: "rm -rf", behavior: "deny", source: "default", reason: "危险的删除操作" },
-  { toolName: "Bash", behavior: "ask", source: "default", reason: "Shell 命令可能有副作用" },
-];
+const permCtx = createPermissionContext("default");
+const checkPerm = createCheckPermissionFn(permCtx);
 
-// 构建权限上下文
-const permissionCtx: PermissionContext = {
-  mode: "default",
-  cwd: process.cwd(),
-  rules: permissionRules,
-};
-
-// 简单的权限检查函数（模拟真实 Claude Code 的 canUseTool）
-function checkPermission(
-  toolName: string,
-  input: Record<string, unknown>,
-  rules: PermissionRule[]
-): PermissionDecision {
-  for (const rule of rules) {
-    if (rule.toolName !== "*" && rule.toolName !== toolName) continue;
-    if (rule.pattern) {
-      const command = String(input.command ?? "");
-      if (!command.includes(rule.pattern)) continue;
-    }
-    if (rule.behavior === "allow") return { behavior: "allow" };
-    if (rule.behavior === "deny") return { behavior: "deny", message: rule.reason ?? "Denied" };
-    return { behavior: "ask", message: rule.reason ?? "需要确认" };
-  }
-  return { behavior: "ask", message: "默认需要确认" };
-}
-
-// 测试权限检查
 const permTests = [
   { tool: "Read", input: { file_path: "main.ts" } },
   { tool: "Bash", input: { command: "ls -la" } },
   { tool: "Bash", input: { command: "rm -rf /" } },
+  { tool: "Write", input: { file_path: "test.txt", content: "hello" } },
 ];
 
 // ─── 输出验证结果 ─────────────────────────────────────────────────────────
@@ -159,13 +128,13 @@ console.log(`  模型: ${DEFAULT_CONFIG.model}`);
 console.log(`  最大 Token: ${DEFAULT_CONFIG.maxTokens}`);
 console.log(`  权限模式: ${DEFAULT_CONFIG.permissionMode}`);
 console.log();
-console.log(`权限系统 (模式: ${permissionCtx.mode}):`);
-permTests.forEach((tc) => {
-  const decision = checkPermission(tc.tool, tc.input, permissionCtx.rules);
+console.log(`权限系统 (模式: ${permCtx.mode}, 规则数: ${permCtx.rules.length}):`);
+for (const tc of permTests) {
+  const decision = await checkPerm(tc.tool, tc.input);
   const icon = decision.behavior === "allow" ? "✅" : decision.behavior === "deny" ? "🚫" : "❓";
   const cmd = (tc.input.command ?? tc.input.file_path) as string;
   console.log(`  ${icon} ${tc.tool}("${cmd}") → ${decision.behavior}`);
-});
+}
 console.log();
 // 实际执行工具
 console.log();
@@ -199,6 +168,7 @@ if (process.env.ANTHROPIC_API_KEY) {
     {
       model: DEFAULT_MODEL,
       maxTokens: 4096,
+      checkPermission: checkPerm,
       onText: (text) => process.stdout.write(text),
       onToolUse: (name, input) => {
         console.log(`\n  [工具调用] ${name}(${JSON.stringify(input)})`);
@@ -220,4 +190,4 @@ if (process.env.ANTHROPIC_API_KEY) {
 }
 
 console.log();
-console.log("下一步: 第 5 章 - 完善工具实现（FileWrite、FileEdit、Glob）");
+console.log("下一步: 第 8 章 - REPL 交互式确认框");

demo/query.ts

@@ -10,7 +10,7 @@
  * 或达到最大轮次限制。
  */
 
-import type { Message, ContentBlock, ToolUseBlock } from "./types/index.js";
+import type { Message, ContentBlock, ToolUseBlock, CheckPermissionFn } from "./types/index.js";
 import { createClient, streamMessage } from "./services/api/claude.js";
 import { buildSystemPrompt } from "./context.js";
 import { allTools, findToolByName, getToolsForAPI } from "./tools.js";
@@ -35,6 +35,8 @@ export interface QueryOptions {
   onToolUse?: (name: string, input: Record<string, unknown>) => void;
   /** 工具结果回调 */
   onToolResult?: (name: string, result: string, isError: boolean) => void;
+  /** 权限检查函数（可选，不提供则跳过权限检查） */
+  checkPermission?: CheckPermissionFn;
 }
 
 /** 查询结果 */
@@ -74,6 +76,7 @@ export async function query(
     onText,
     onToolUse,
     onToolResult,
+    checkPermission,
   } = options;
 
   const client = createClient(apiKey);
@@ -200,6 +203,17 @@ export async function query(
     if (readOnlyTools.length > 0) {
       const results = await Promise.all(
         readOnlyTools.map(async (tu) => {
+          // 权限检查
+          if (checkPermission) {
+            const decision = await checkPermission(tu.name, tu.input);
+            if (decision.behavior === "deny") {
+              return createToolResultBlock(tu.id, `Permission denied: ${decision.message}`, true);
+            }
+            if (decision.behavior === "ask") {
+              // 在 CLI 环境中，默认允许（第 8 章的 REPL 才会真正弹出确认框）
+              onToolUse?.(`[权限: ${decision.message}] ${tu.name}`, tu.input);
+            }
+          }
           const tool = findToolByName(tu.name);
           if (!tool) {
             return createToolResultBlock(tu.id, `Error: Unknown tool '${tu.name}'`, true);
@@ -214,6 +228,20 @@ export async function query(
 
     // 串行执行读写工具
     for (const tu of writeTools) {
+      // 权限检查
+      if (checkPermission) {
+        const decision = await checkPermission(tu.name, tu.input);
+        if (decision.behavior === "deny") {
+          toolResultBlocks.push(
+            createToolResultBlock(tu.id, `Permission denied: ${decision.message}`, true)
+          );
+          continue;
+        }
+        if (decision.behavior === "ask") {
+          // 在 CLI 环境中，默认允许（第 8 章的 REPL 才会真正弹出确认框）
+          onToolUse?.(`[权限: ${decision.message}] ${tu.name}`, tu.input);
+        }
+      }
       const tool = findToolByName(tu.name);
       if (!tool) {
         toolResultBlocks.push(

demo/utils/permissions.ts

@@ -0,0 +1,119 @@
+/**
+ * utils/permissions.ts - 权限检查实现
+ *
+ * 对应真实 Claude Code: src/utils/permissions.ts + src/hooks/toolPermission/
+ *
+ * 确保 AI 不会未经用户同意执行危险操作。
+ * 每次工具调用前，根据权限规则决定：允许、拒绝、或询问用户。
+ */
+
+import type {
+  PermissionMode,
+  PermissionRule,
+  PermissionContext,
+  PermissionDecision,
+  CheckPermissionFn,
+} from "../types/index.js";
+
+/**
+ * 默认权限规则
+ *
+ * 真实 Claude Code 的规则更复杂，支持正则匹配、路径范围等。
+ * 我们定义核心规则：只读工具允许，危险命令拒绝，其他询问。
+ */
+export const DEFAULT_RULES: PermissionRule[] = [
+  // 只读工具：始终允许
+  { toolName: "Read", behavior: "allow", source: "default", reason: "只读操作" },
+  { toolName: "Grep", behavior: "allow", source: "default", reason: "只读搜索" },
+  { toolName: "Glob", behavior: "allow", source: "default", reason: "只读匹配" },
+  { toolName: "Echo", behavior: "allow", source: "default", reason: "只读回显" },
+
+  // 危险命令：始终拒绝
+  { toolName: "Bash", pattern: "rm -rf", behavior: "deny", source: "default", reason: "递归删除" },
+  { toolName: "Bash", pattern: "rm -r /", behavior: "deny", source: "default", reason: "删除根目录" },
+  { toolName: "Bash", pattern: "mkfs", behavior: "deny", source: "default", reason: "格式化磁盘" },
+  { toolName: "Bash", pattern: "> /dev/", behavior: "deny", source: "default", reason: "写入设备文件" },
+  { toolName: "Bash", pattern: ":(){ :|:& };:", behavior: "deny", source: "default", reason: "Fork 炸弹" },
+  { toolName: "Bash", pattern: "chmod -R 777", behavior: "deny", source: "default", reason: "不安全的权限修改" },
+
+  // 写操作：需要询问
+  { toolName: "Bash", behavior: "ask", source: "default", reason: "Shell 命令可能有副作用" },
+  { toolName: "Write", behavior: "ask", source: "default", reason: "文件写入操作" },
+  { toolName: "Edit", behavior: "ask", source: "default", reason: "文件编辑操作" },
+];
+
+/**
+ * 检查权限
+ *
+ * 按规则列表顺序匹配，返回第一个匹配的决策。
+ * 如果没有规则匹配，根据权限模式决定默认行为。
+ */
+export function checkPermission(
+  toolName: string,
+  input: Record<string, unknown>,
+  context: PermissionContext
+): PermissionDecision {
+  // bypassPermissions 模式跳过所有检查
+  if (context.mode === "bypassPermissions") {
+    return { behavior: "allow" };
+  }
+
+  // 遍历规则
+  for (const rule of context.rules) {
+    // 工具名匹配
+    if (rule.toolName !== "*" && rule.toolName !== toolName) continue;
+
+    // 模式匹配（如果有）
+    if (rule.pattern) {
+      const command = String(input.command ?? input.content ?? "");
+      if (!command.includes(rule.pattern)) continue;
+    }
+
+    // 匹配成功，返回决策
+    switch (rule.behavior) {
+      case "allow":
+        return { behavior: "allow" };
+      case "deny":
+        return { behavior: "deny", message: `Blocked: ${rule.reason ?? "policy violation"}` };
+      case "ask":
+        // auto 模式下，读操作自动放行
+        if (context.mode === "auto") {
+          // 简单的启发式：如果工具名暗示只读，自动放行
+          if (["Read", "Grep", "Glob", "Echo"].includes(toolName)) {
+            return { behavior: "allow" };
+          }
+        }
+        return { behavior: "ask", message: rule.reason ?? "需要确认" };
+    }
+  }
+
+  // 无匹配规则，默认询问
+  return { behavior: "ask", message: "未匹配任何规则，需要确认" };
+}
+
+/**
+ * 创建权限上下文
+ */
+export function createPermissionContext(
+  mode: PermissionMode = "default",
+  cwd: string = process.cwd(),
+  extraRules: PermissionRule[] = []
+): PermissionContext {
+  return {
+    mode,
+    cwd,
+    rules: [...extraRules, ...DEFAULT_RULES], // 用户规则优先
+  };
+}
+
+/**
+ * 创建权限检查函数
+ *
+ * 返回一个闭包，可以传递给 query() 使用。
+ * 这对应真实 Claude Code 中 canUseTool 回调的模式。
+ */
+export function createCheckPermissionFn(
+  context: PermissionContext
+): CheckPermissionFn {
+  return async (toolName, input) => checkPermission(toolName, input, context);
+}

docs/en/07-permission-system.md

@@ -16,6 +16,7 @@
 8. [Sandbox Integration](#8-sandbox-integration)
 9. [Hands-on: Build a Permission System](#9-hands-on-build-a-permission-system)
 10. [Key Takeaways & What's Next](#10-key-takeaways--whats-next)
+11. [Hands-on Build: Permission Check Integration](#hands-on-build-permission-check-integration)
 
 ---
 
@@ -582,4 +583,112 @@ Every `ask` result carries a `decisionReason` explaining *why* the tool needs ap
 
 ---
 
+## Hands-on Build: Permission Check Integration
+
+> **This section marks another significant upgrade to the demo.** We add `utils/permissions.ts` — a permission check module — and integrate it into the tool execution flow in `query.ts`, enabling mini-claude to intercept or prompt before executing dangerous operations.
+
+### Project Structure Update
+
+```
+demo/
+├── utils/
+│   ├── messages.ts      # Chapter 4
+│   └── permissions.ts   # ← New: permission check implementation
+├── query.ts             # Updated: permission check integration
+├── tools/
+│   ├── BashTool/
+│   ├── FileReadTool/
+│   ├── FileWriteTool/
+│   ├── FileEditTool/
+│   ├── GrepTool/
+│   └── GlobTool/
+├── main.ts
+├── Tool.ts
+├── context.ts
+├── services/api/
+└── types/
+```
+
+### utils/permissions.ts Walkthrough
+
+The permission check module implements the core decision flow of Claude Code's permission system:
+
+```
+Tool call → Iterate rules → First matching rule determines behavior
+  ↓              ↓              ↓
+  allow       deny          ask
+  (execute)  (reject+feedback to AI)  (prompt user)
+```
+
+**Default rule hierarchy:**
+
+1. Read-only tools (Read, Grep, Glob) → always `allow`
+2. Dangerous command patterns (`rm -rf`, `mkfs`, `dd if=`, etc.) → always `deny`
+3. Write operations (Bash, Write, Edit) → `ask`
+
+These three layers embody Claude Code's core security philosophy: **read-only operations pass freely, dangerous commands are firmly rejected, write operations are left to the user's judgment**.
+
+### Three Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Strict rule execution — read-only allow, dangerous deny, writes ask |
+| `auto` | Read-only operations auto-approve, writes still require confirmation (simplified `acceptEdits`) |
+| `bypassPermissions` | Skip all checks (development/debugging only, never use in production) |
+
+The real Claude Code has 7 modes (see Section 2 of this chapter); the demo simplifies to 3 to focus on core logic.
+
+### Integration with query.ts
+
+`checkPermission` is passed as an optional callback into `query()`, via a new field in `QueryOptions`:
+
+```typescript
+export interface QueryOptions {
+  // ...existing fields
+  checkPermission?: (toolName: string, input: Record<string, unknown>) => Promise<PermissionResult>;
+}
+```
+
+The integration point is before tool execution — after the Agentic Loop receives tool calls, it checks permissions first:
+
+- **allow** → execute the tool normally
+- **deny** → skip tool execution and return an error message to the AI (e.g., `"Permission denied: rm -rf is blocked by safety rules"`), which lets the AI adjust its strategy
+- **ask** → log and proceed (the current demo has no interactive UI; Chapter 8's REPL will display a confirmation dialog, implementing true interactive user confirmation)
+
+If no `checkPermission` callback is provided, behavior is identical to before — all tools execute unconditionally. This ensures backward compatibility.
+
+### Running the Demo
+
+```bash
+cd demo && bun run main.ts
+```
+
+Try these interactions to verify the permission system:
+
+```
+you> delete all files in the current directory
+# AI attempts rm -rf → denied → AI receives error and adjusts strategy
+
+you> read package.json
+# Read is a read-only tool → allowed directly, no confirmation needed
+
+you> create a test.txt file
+# Write is a write operation → ask → permission check info logged
+```
+
+### Mapping to Real Claude Code
+
+| Demo File | Real File | What's Simplified |
+|-----------|-----------|-------------------|
+| `utils/permissions.ts` | `src/utils/permissions/permissions.ts` | No multi-source rule priority, no wildcard matching engine |
+| `utils/permissions.ts` dangerous patterns | `src/utils/permissions/dangerousPatterns.ts` | Hardcoded few patterns, no tree-sitter AST analysis |
+| `utils/permissions.ts` mode switching | `src/utils/permissions/PermissionMode.ts` | 3 modes vs 7 modes |
+| `query.ts` (permission callback) | `src/hooks/toolPermission/` | No resolve-once racing, no classifier, no bridge |
+
+### What's Next
+
+Chapter 8 will implement an interactive terminal UI (React + Ink), including user input, message rendering, and permission confirmation dialogs. At that point, the `ask` permission will display a real dialog letting users choose "Allow" or "Deny", rather than merely logging.
+
+---
+
 *Source references verified against `anthhub-claude-code` commit tree.*