@winspan/claude-forge 0.1.1

package/dist/doc-sync/index.js

@@ -0,0 +1,190 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../utils/logger.js';
+// 写操作工具名
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+// 扫描时排除的目录
+const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.claude-forge', 'coverage']);
+/**
+ * 从会话事件中提取本次被修改的文件路径（去重）
+ */
+export function extractChangedFiles(events) {
+    const files = new Set();
+    for (const e of events) {
+        if (!WRITE_TOOLS.has(e.tool_name ?? ''))
+            continue;
+        const input = e.tool_input;
+        if (!input)
+            continue;
+        const p = (input['file_path'] ?? input['path']);
+        if (p && typeof p === 'string')
+            files.add(p);
+    }
+    return [...files];
+}
+/**
+ * 递归扫描 projectPath 下所有 .md 文件（排除常见无关目录）
+ */
+export function findProjectDocs(projectPath) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (EXCLUDE_DIRS.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(full);
+            }
+        }
+    }
+    walk(projectPath);
+    return results;
+}
+export class DocSyncEngine {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    /**
+     * 主入口：根据本次会话事件，找出受影响的文档并更新
+     */
+    async sync(sessionId, projectPath, events) {
+        const changedFiles = extractChangedFiles(events);
+        if (changedFiles.length === 0) {
+            logger.info('[Forge:文档同步] 本次会话无写操作，跳过');
+            return;
+        }
+        const allDocs = findProjectDocs(projectPath);
+        if (allDocs.length === 0) {
+            logger.info('[Forge:文档同步] 项目内无 .md 文档，跳过');
+            return;
+        }
+        logger.info(`[Forge:文档同步] 本次改动文件 ${changedFiles.length} 个，扫描到文档 ${allDocs.length} 个`);
+        // 第一步：让 AI 判断哪些文档受影响
+        const affected = await this.detectAffectedDocs(changedFiles, allDocs, projectPath);
+        if (affected.length === 0) {
+            logger.info('[Forge:文档同步] AI 判断无文档需要更新');
+            return;
+        }
+        logger.info(`[Forge:文档同步] 受影响文档 ${affected.length} 个：${affected.map(p => path.relative(projectPath, p)).join(', ')}`);
+        // 第二步：逐个更新受影响的文档
+        for (const docPath of affected) {
+            await this.updateDoc(docPath, changedFiles, projectPath, sessionId);
+        }
+    }
+    async detectAffectedDocs(changedFiles, allDocs, projectPath) {
+        const relChanged = changedFiles.map(f => path.relative(projectPath, f));
+        const relDocs = allDocs.map(f => path.relative(projectPath, f));
+        const prompt = `你是一个代码项目的文档维护助手。
+
+本次会话修改了以下文件：
+${relChanged.map(f => `- ${f}`).join('\n')}
+
+项目中存在以下文档：
+${relDocs.map(f => `- ${f}`).join('\n')}
+
+请判断哪些文档的内容可能因上述文件改动而需要更新（例如：API 文档、设计文档、优化计划、README 等记录了相关模块功能或状态的文档）。
+
+只返回需要更新的文档路径列表，每行一个相对路径，不需要解释。如果没有文档需要更新，返回空内容。`;
+        const result = await this.api.complete(prompt, 'doc-sync-detect', 2, 60_000);
+        return result
+            .split('\n')
+            .map(l => l.trim().replace(/^-\s*/, ''))
+            .filter(l => l.length > 0)
+            .map(rel => path.join(projectPath, rel))
+            .filter(abs => allDocs.includes(abs));
+    }
+    async updateDoc(docPath, changedFiles, projectPath, sessionId) {
+        let current;
+        try {
+            current = fs.readFileSync(docPath, 'utf-8');
+        }
+        catch {
+            logger.warn(`[Forge:文档同步] 读取文档失败：${docPath}`);
+            return;
+        }
+        // 读取改动文件的内容摘要（只取前 300 字符）
+        const changedSummaries = changedFiles
+            .map(f => {
+            try {
+                const content = fs.readFileSync(f, 'utf-8');
+                return `### ${path.relative(projectPath, f)}\n${content}`;
+            }
+            catch {
+                return `### ${path.relative(projectPath, f)}\n（文件不存在或已删除）`;
+            }
+        })
+            .join('\n\n');
+        const prompt = `你是一个代码项目的文档维护助手。
+
+以下是本次会话修改的文件内容摘要：
+${changedSummaries}
+
+以下是需要更新的文档（${path.relative(projectPath, docPath)}）的当前内容：
+${current}
+
+请根据文件改动，以 JSON 数组格式返回需要修改的行（仅返回有变化的行），格式如下：
+[{"old":"原始行内容（精确匹配）","new":"替换后的行内容"}]
+
+规则：
+- 将未完成的条目（[ ]）标记为已完成（[x]），并在行末补充日期（如 [x] 2026-04-11）
+- 若某功能被废弃，在行末标注（已废弃）
+- 只返回 JSON 数组本身，不要用代码块包裹，不要任何解释
+- 如果没有需要修改的行，返回空数组 []`;
+        let patchJson;
+        try {
+            patchJson = await this.api.complete(prompt, 'doc-sync-update', 1, 60_000);
+        }
+        catch (err) {
+            logger.warn(`[Forge:文档同步] AI 更新文档失败（${path.relative(projectPath, docPath)}）：${err}`);
+            return;
+        }
+        // 解析 patch JSON 并应用行级替换
+        let patches;
+        try {
+            // 优先从 ```json ... ``` 代码块中提取
+            const fenceMatch = patchJson.match(/```(?:json)?\s*([\s\S]*?)```/);
+            const jsonStr = fenceMatch ? fenceMatch[1].trim() : patchJson.trim();
+            // 从提取内容中找 JSON 数组
+            const jsonMatch = jsonStr.match(/\[\s*\{[\s\S]*\}\s*\]/) ?? jsonStr.match(/\[\s*\]/);
+            patches = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
+        }
+        catch {
+            logger.warn(`[Forge:文档同步] patch 解析失败，跳过：${path.relative(projectPath, docPath)}`);
+            logger.warn(`[Forge:文档同步] AI 原始返回：${patchJson.slice(0, 300)}`);
+            return;
+        }
+        if (!patches.length) {
+            logger.info(`[Forge:文档同步] 文档无变化：${path.relative(projectPath, docPath)}`);
+            return;
+        }
+        let updated = current;
+        for (const { old: oldLine, new: newLine } of patches) {
+            if (oldLine && updated.includes(oldLine)) {
+                updated = updated.replace(oldLine, newLine);
+            }
+        }
+        if (updated === current) {
+            logger.info(`[Forge:文档同步] patch 未命中任何行：${path.relative(projectPath, docPath)}`);
+            return;
+        }
+        try {
+            fs.writeFileSync(docPath, updated, 'utf-8');
+            logger.info(`[Forge:文档同步] 已更新（${patches.length} 处）：${path.relative(projectPath, docPath)}`);
+        }
+        catch (err) {
+            logger.warn(`[Forge:文档同步] 写入文档失败（${path.relative(projectPath, docPath)}）：${err}`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/doc-sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doc-sync/index.ts"],"names":[],"mappings":"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"}

package/dist/hooks/check-context-limit.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# 检查当前 session 的 context token 使用量，接近限制时发出预警
+
+WARN_THRESHOLD="${CONTEXT_WARN_THRESHOLD:-150000}"
+ALERT_THRESHOLD="${CONTEXT_ALERT_THRESHOLD:-180000}"
+
+# 从 stdin 读取 hook 输入，提取 session_id 和 cwd
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("session_id",""))' 2>/dev/null || echo "")
+CWD=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo "")
+
+# 定位 session 文件
+find_session_file() {
+    local session_id="$1"
+    local cwd="$2"
+
+    if [ -n "$cwd" ]; then
+        local sanitized
+        sanitized=$(echo "$cwd" | sed 's|/|-|g')
+        local project_dir="$HOME/.claude/projects/${sanitized}"
+        if [ -n "$session_id" ] && [ -f "$project_dir/${session_id}.jsonl" ]; then
+            echo "$project_dir/${session_id}.jsonl"
+            return
+        fi
+        local latest
+        latest=$(ls -t "$project_dir"/*.jsonl 2>/dev/null | head -1)
+        [ -n "$latest" ] && echo "$latest"
+    fi
+}
+
+SESSION_FILE=$(find_session_file "$SESSION_ID" "$CWD")
+
+if [ -z "$SESSION_FILE" ] || [ ! -f "$SESSION_FILE" ]; then
+    exit 0
+fi
+
+CONTEXT_TOKENS=$(python3 - "$SESSION_FILE" <<'PYEOF'
+import sys, json
+
+session_file = sys.argv[1]
+max_tokens = 0
+
+with open(session_file) as f:
+    for line in f:
+        try:
+            d = json.loads(line)
+            if d.get('type') == 'assistant' and 'message' in d:
+                usage = d['message'].get('usage', {})
+                total = (usage.get('input_tokens', 0) +
+                         usage.get('cache_read_input_tokens', 0) +
+                         usage.get('cache_creation_input_tokens', 0))
+                if total > max_tokens:
+                    max_tokens = total
+        except Exception:
+            pass
+
+print(max_tokens)
+PYEOF
+)
+
+CONTEXT_TOKENS="${CONTEXT_TOKENS:-0}"
+
+# 冷却机制：同一会话 60 秒内只触发一次告警，避免每次 PostToolUse 重复输出
+COOLDOWN_SECS="${CONTEXT_ALERT_COOLDOWN:-60}"
+ALERT_FLAG_DIR="${TMPDIR:-/tmp}/claude-forge-ctx"
+mkdir -p "$ALERT_FLAG_DIR"
+ALERT_FLAG="$ALERT_FLAG_DIR/${SESSION_ID}.alert"
+
+is_in_cooldown() {
+    [ -f "$ALERT_FLAG" ] || return 1
+    local last_alert
+    last_alert=$(cat "$ALERT_FLAG" 2>/dev/null)
+    local now
+    now=$(date +%s)
+    [ -n "$last_alert" ] && [ $((now - last_alert)) -lt "$COOLDOWN_SECS" ]
+}
+
+if [ "$CONTEXT_TOKENS" -ge "$ALERT_THRESHOLD" ] 2>/dev/null; then
+    if ! is_in_cooldown; then
+        date +%s > "$ALERT_FLAG"
+        # 告急：注入 systemMessage 提示用户手动执行 /compact
+        echo "{\"systemMessage\": \"⚠️ Context 告急：当前已用 ${CONTEXT_TOKENS} tokens（阈值 ${ALERT_THRESHOLD}），请立即执行 /compact 压缩上下文。\"}"
+    fi
+
+elif [ "$CONTEXT_TOKENS" -ge "$WARN_THRESHOLD" ] 2>/dev/null; then
+    if ! is_in_cooldown; then
+        date +%s > "$ALERT_FLAG"
+        # 预警：在命令行输出提示（stderr → 终端可见，不影响 Claude Code 响应）
+        echo "⚠️  Context 预警：已用 ${CONTEXT_TOKENS} tokens，建议执行 /compact" >&2
+    fi
+    exit 0
+else
+    # 低于预警阈值时清除冷却标记，允许下次超限时重新告警
+    rm -f "$ALERT_FLAG"
+fi
+
+exit 0

package/dist/hooks/hooks/check-context-limit.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# 检查当前 session 的 context token 使用量，接近限制时发出预警
+
+WARN_THRESHOLD="${CONTEXT_WARN_THRESHOLD:-150000}"
+ALERT_THRESHOLD="${CONTEXT_ALERT_THRESHOLD:-180000}"
+
+# 从 stdin 读取 hook 输入，提取 session_id 和 cwd
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("session_id",""))' 2>/dev/null || echo "")
+CWD=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo "")
+
+# 定位 session 文件
+find_session_file() {
+    local session_id="$1"
+    local cwd="$2"
+
+    if [ -n "$cwd" ]; then
+        local sanitized
+        sanitized=$(echo "$cwd" | sed 's|/|-|g')
+        local project_dir="$HOME/.claude/projects/${sanitized}"
+        if [ -n "$session_id" ] && [ -f "$project_dir/${session_id}.jsonl" ]; then
+            echo "$project_dir/${session_id}.jsonl"
+            return
+        fi
+        local latest
+        latest=$(ls -t "$project_dir"/*.jsonl 2>/dev/null | head -1)
+        [ -n "$latest" ] && echo "$latest"
+    fi
+}
+
+SESSION_FILE=$(find_session_file "$SESSION_ID" "$CWD")
+
+if [ -z "$SESSION_FILE" ] || [ ! -f "$SESSION_FILE" ]; then
+    exit 0
+fi
+
+CONTEXT_TOKENS=$(python3 - "$SESSION_FILE" <<'PYEOF'
+import sys, json
+
+session_file = sys.argv[1]
+max_tokens = 0
+
+with open(session_file) as f:
+    for line in f:
+        try:
+            d = json.loads(line)
+            if d.get('type') == 'assistant' and 'message' in d:
+                usage = d['message'].get('usage', {})
+                total = (usage.get('input_tokens', 0) +
+                         usage.get('cache_read_input_tokens', 0) +
+                         usage.get('cache_creation_input_tokens', 0))
+                if total > max_tokens:
+                    max_tokens = total
+        except Exception:
+            pass
+
+print(max_tokens)
+PYEOF
+)
+
+CONTEXT_TOKENS="${CONTEXT_TOKENS:-0}"
+
+# 冷却机制：同一会话 60 秒内只触发一次告警，避免每次 PostToolUse 重复输出
+COOLDOWN_SECS="${CONTEXT_ALERT_COOLDOWN:-60}"
+ALERT_FLAG_DIR="${TMPDIR:-/tmp}/claude-forge-ctx"
+mkdir -p "$ALERT_FLAG_DIR"
+ALERT_FLAG="$ALERT_FLAG_DIR/${SESSION_ID}.alert"
+
+is_in_cooldown() {
+    [ -f "$ALERT_FLAG" ] || return 1
+    local last_alert
+    last_alert=$(cat "$ALERT_FLAG" 2>/dev/null)
+    local now
+    now=$(date +%s)
+    [ -n "$last_alert" ] && [ $((now - last_alert)) -lt "$COOLDOWN_SECS" ]
+}
+
+if [ "$CONTEXT_TOKENS" -ge "$ALERT_THRESHOLD" ] 2>/dev/null; then
+    if ! is_in_cooldown; then
+        date +%s > "$ALERT_FLAG"
+        # 告急：注入 systemMessage 提示用户手动执行 /compact
+        echo "{\"systemMessage\": \"⚠️ Context 告急：当前已用 ${CONTEXT_TOKENS} tokens（阈值 ${ALERT_THRESHOLD}），请立即执行 /compact 压缩上下文。\"}"
+    fi
+
+elif [ "$CONTEXT_TOKENS" -ge "$WARN_THRESHOLD" ] 2>/dev/null; then
+    if ! is_in_cooldown; then
+        date +%s > "$ALERT_FLAG"
+        # 预警：在命令行输出提示（stderr → 终端可见，不影响 Claude Code 响应）
+        echo "⚠️  Context 预警：已用 ${CONTEXT_TOKENS} tokens，建议执行 /compact" >&2
+    fi
+    exit 0
+else
+    # 低于预警阈值时清除冷却标记，允许下次超限时重新告警
+    rm -f "$ALERT_FLAG"
+fi
+
+exit 0

package/dist/hooks/hooks/notification.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Claude Forge - Notification Hook
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# 读取 stdin
+INPUT=$(cat)
+
+# 提取 cwd
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_PROJECT_PATH="$PROJECT_PATH" FORGE_INPUT="$INPUT" \
+  python3 -c "
+import json, os
+from datetime import datetime
+try:
+    tool_input = json.loads(os.environ.get('FORGE_INPUT', '{}'))
+except Exception:
+    tool_input = {}
+print(json.dumps({
+    'hook_type': 'Notification',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': 'notification',
+    'tool_input': tool_input,
+}))
+" 2>/dev/null)
+
+echo "$EVENT" | nc -U -w 1 "$SOCKET_PATH" 2>/dev/null || true
+exit 0

package/dist/hooks/hooks/post-tool-use.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Claude Forge - PostToolUse Hook
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# 读取 stdin
+INPUT=$(cat)
+
+# 提取字段（tool_response 是 Claude Code 的字段名）
+TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("tool_name",""))' 2>/dev/null || echo '')}"
+TOOL_INPUT=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get("tool_input",{})))' 2>/dev/null || echo '{}')
+TOOL_OUTPUT=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get("tool_response",{})))' 2>/dev/null || echo '{}')
+# cwd 是 Claude Code 的项目根目录
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_TOOL_NAME="$TOOL_NAME" FORGE_TOOL_INPUT="$TOOL_INPUT" FORGE_TOOL_OUTPUT="$TOOL_OUTPUT" FORGE_PROJECT_PATH="$PROJECT_PATH" \
+  python3 -c "
+import json, os
+from datetime import datetime
+try:
+    tool_input = json.loads(os.environ.get('FORGE_TOOL_INPUT', '{}'))
+except Exception:
+    tool_input = {}
+try:
+    tool_output = json.loads(os.environ.get('FORGE_TOOL_OUTPUT', '{}'))
+except Exception:
+    tool_output = {}
+print(json.dumps({
+    'hook_type': 'PostToolUse',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': os.environ.get('FORGE_TOOL_NAME', ''),
+    'tool_input': tool_input,
+    'tool_output': tool_output,
+}))
+" 2>/dev/null)
+
+# 发送到 daemon（PostToolUse 也需要等待响应以支持通知注入）
+RESPONSE=$(echo "$EVENT" | nc -U -w 5 "$SOCKET_PATH" 2>/dev/null || true)
+if [ -n "$RESPONSE" ]; then
+  HAS_CONTEXT=$(echo "$RESPONSE" | python3 -c 'import sys,json; d=json.load(sys.stdin); print("yes" if d.get("additionalContext") else "no")' 2>/dev/null || echo 'no')
+  if [ "$HAS_CONTEXT" = "yes" ]; then
+    echo "$RESPONSE"
+  fi
+fi
+exit 0

package/dist/hooks/hooks/pre-tool-use.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Claude Forge - PreToolUse Hook（双向通信）
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# 读取 stdin（Claude Code 传入的 JSON）
+INPUT=$(cat)
+
+# 提取字段
+TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("tool_name",""))' 2>/dev/null || echo '')}"
+TOOL_INPUT=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get("tool_input",{})))' 2>/dev/null || echo '{}')
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_TOOL_NAME="$TOOL_NAME" FORGE_TOOL_INPUT="$TOOL_INPUT" FORGE_PROJECT_PATH="$PROJECT_PATH" \
+  python3 -c "
+import json, os
+from datetime import datetime
+tool_input_raw = os.environ.get('FORGE_TOOL_INPUT', '{}')
+try:
+    tool_input = json.loads(tool_input_raw)
+except Exception:
+    tool_input = {}
+print(json.dumps({
+    'hook_type': 'PreToolUse',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': os.environ.get('FORGE_TOOL_NAME', ''),
+    'tool_input': tool_input,
+}))
+" 2>/dev/null)
+
+# 发送事件并等待响应（双向通信，5 秒超时）
+RESPONSE=$(echo "$EVENT" | nc -U -w 5 "$SOCKET_PATH" 2>/dev/null)
+
+if [ -n "$RESPONSE" ]; then
+  # 解析响应
+  ALLOW=$(echo "$RESPONSE" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(str(d.get("allow",True)).lower())' 2>/dev/null || echo 'true')
+
+  if [ "$ALLOW" = "false" ]; then
+    # 输出拦截 JSON 到 stdout（Claude Code 读取）
+    echo "$RESPONSE"
+    exit 2
+  fi
+
+  # 有 additionalContext 时输出
+  HAS_CONTEXT=$(echo "$RESPONSE" | python3 -c 'import sys,json; d=json.load(sys.stdin); print("yes" if d.get("additionalContext") else "no")' 2>/dev/null || echo 'no')
+  if [ "$HAS_CONTEXT" = "yes" ]; then
+    echo "$RESPONSE"
+  fi
+fi
+
+exit 0

package/dist/hooks/hooks/stop.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Claude Forge - Stop Hook
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# 读取 stdin
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# 提取 cwd
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_PROJECT_PATH="$PROJECT_PATH" \
+  python3 -c "
+import json, os
+from datetime import datetime
+print(json.dumps({
+    'hook_type': 'Stop',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': 'stop',
+    'tool_input': {},
+}))
+" 2>/dev/null)
+
+echo "$EVENT" | nc -U -w 1 "$SOCKET_PATH" 2>/dev/null || true
+exit 0

package/dist/hooks/hooks/user-prompt-submit.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Claude Forge - UserPromptSubmit Hook
+# 拦截用户输入，触发意图分析和自动 Pipeline 编排
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# daemon 未运行，快速跳过
+if [ ! -S "$SOCKET_PATH" ]; then
+  exit 0
+fi
+
+# 读取 stdin（Claude Code 传入的 JSON）
+INPUT=$(cat)
+
+# 提取字段
+USER_PROMPT=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("prompt",""))' 2>/dev/null || echo '')
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 空 prompt 跳过
+if [ -z "$USER_PROMPT" ]; then
+  exit 0
+fi
+
+# 安全地构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_USER_PROMPT="$USER_PROMPT" FORGE_PROJECT_PATH="$PROJECT_PATH" \
+  python3 -c "
+import json, os
+from datetime import datetime
+print(json.dumps({
+    'hook_type': 'UserPromptSubmit',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': 'UserPrompt',
+    'tool_input': {'user_prompt': os.environ.get('FORGE_USER_PROMPT', '')},
+}))
+" 2>/dev/null)
+
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+# 发送事件并等待响应（10 秒超时，AI 分析可能需要更多时间）
+RESPONSE=$(echo "$EVENT" | nc -U -w 10 "$SOCKET_PATH" 2>/dev/null)
+
+if [ -n "$RESPONSE" ]; then
+  HAS_CONTEXT=$(echo "$RESPONSE" | python3 -c 'import sys,json; d=json.load(sys.stdin); print("yes" if d.get("additionalContext") else "no")' 2>/dev/null || echo 'no')
+  if [ "$HAS_CONTEXT" = "yes" ]; then
+    # stderr 输出到终端，让用户实时看到决策过程
+    # 用 fd3 保存真实 stderr，python3 错误丢弃，面板输出保留
+    exec 3>&2
+    echo "$RESPONSE" | python3 -c '
+import sys, json, os
+d = json.load(sys.stdin)
+ctx = d.get("additionalContext", "")
+lines = []
+for line in ctx.split("\n"):
+    if line.startswith("请在回复"):
+        break
+    if line.strip():
+        lines.append(line)
+if lines:
+    os.write(3, ("\033[36m" + "\n".join(lines) + "\033[0m\n").encode())
+' 2>/dev/null
+    exec 3>&-
+    # stdout 返回给 Claude Code
+    echo "$RESPONSE"
+  fi
+fi
+
+exit 0

package/dist/hooks/notification.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Claude Forge - Notification Hook
+
+SOCKET_PATH="${CLAUDE_FORGE_SOCKET:-$HOME/.claude-forge/daemon.sock}"
+
+# 读取 stdin
+INPUT=$(cat)
+
+# 提取 cwd
+PROJECT_PATH=$(echo "$INPUT" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d.get("cwd",""))' 2>/dev/null || echo '')
+PROJECT_PATH="${PROJECT_PATH:-${PWD}}"
+
+# 构造事件 JSON（通过环境变量传参，避免 shell 注入）
+EVENT=$(FORGE_PROJECT_PATH="$PROJECT_PATH" FORGE_INPUT="$INPUT" \
+  python3 -c "
+import json, os
+from datetime import datetime
+try:
+    tool_input = json.loads(os.environ.get('FORGE_INPUT', '{}'))
+except Exception:
+    tool_input = {}
+print(json.dumps({
+    'hook_type': 'Notification',
+    'timestamp': datetime.now().strftime('%Y-%m-%dT%H:%M:%S'),
+    'session_id': os.environ.get('CLAUDE_CODE_SESSION_ID', 'cli'),
+    'project_path': os.environ.get('FORGE_PROJECT_PATH', ''),
+    'tool_name': 'notification',
+    'tool_input': tool_input,
+}))
+" 2>/dev/null)
+
+echo "$EVENT" | nc -U -w 1 "$SOCKET_PATH" 2>/dev/null || true
+exit 0