@hopping-dev/hub 0.1.0

package/dist/ipc/watcher.js

@@ -0,0 +1,745 @@
+"use strict";
+/**
+ * Hub IPC Watcher — Hook ↔ Hub 檔案交換橋樑
+ *
+ * === 架構背景 ===
+ *
+ * 問題：
+ *   pre-tool-use.js 是 Claude Code 為每次工具呼叫啟動的獨立 Node 程序。
+ *   Hub 使用 MCP stdio transport（由 Claude Code 以子程序啟動，透過 stdin/stdout 通訊）。
+ *   因此，Hook 程序無法直接連到 Hub（Hub 沒有 HTTP/WebSocket port）。
+ *
+ * 解決方案（檔案交換 IPC）：
+ *
+ *   pre-tool-use.js                        Hub（IpcWatcher）
+ *        |                                         |
+ *        | 1. 寫入 pending/{id}.json               |
+ *        |  （IpcPendingRequest JSON）              |
+ *        |---------------------------------------->|
+ *        |                                         | 2. chokidar 偵測到新檔案
+ *        |                                         | 3. PolicyEngine.evaluate()
+ *        |                                         | 4. 寫入 resolved/{id}.json
+ *        |                                         |  （IpcResolvedResponse JSON）
+ *        |<----------------------------------------|
+ *        | 5. polling 讀到 resolved 檔案            |
+ *        | 6. 輸出 permissionDecision 給 Claude Code|
+ *
+ * === 技術選擇 ===
+ *
+ * 為什麼用 chokidar（而不是 Node.js 原生 fs.watch）？
+ *   - chokidar 跨平台更穩定（macOS 的 kqueue、Linux 的 inotify、Windows 的 ReadDirectoryChanges）
+ *   - awaitWriteFinish 選項等待檔案寫入穩定後再觸發事件，避免讀到寫到一半的 JSON
+ *   - Hub 是長期執行的 MCP Server，穩定性比輕量更重要
+ *
+ * 為什麼用原子寫入（.tmp + rename）？
+ *   - rename 在同一 filesystem 上是原子操作（POSIX 保證）
+ *   - 避免 pre-tool-use.js 讀到 Hub 寫到一半的 resolved JSON（導致 JSON.parse 失敗）
+ *
+ * === Mode-Aware 行為（S4-HOOK-RPERM-001）===
+ *
+ *   IpcWatcher 依據 askMode 決定行為：
+ *   - local 模式（預設）：TD-007 觀測 — ALLOW/ASK/WARN 全部 approved=true
+ *   - away 模式：真正攔截 — ALLOW 自動放行，ASK/WARN 送 Cloud 等手機審核
+ *
+ *   避免重複審核：
+ *   - local 模式用戶在電腦前 → hopping.check 已處理審核，Hook 層不重複送 Cloud
+ *   - away 模式用戶不在電腦前 → Hook 層負責攔截，hopping.check 只在 Skill 呼叫時觸發
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpcWatcher = void 0;
+const chokidar_1 = __importDefault(require("chokidar"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const manager_1 = require("../config/manager");
+const risk_level_1 = require("../mcp/risk-level");
+const summary_1 = require("../mcp/summary");
+const tool_mapping_1 = require("../policy/tool-mapping");
+// ============================================
+// 常數
+// ============================================
+/**
+ * IPC 審核超時上限（毫秒）
+ *
+ * pre-tool-use.js 有 RESPONSE_TIMEOUT_MS = 120,000ms（2 分鐘）。
+ * IpcWatcher 的 approval timeout 必須小於此值，確保 Hub 回應 before hook 超時。
+ * 預留 10 秒 buffer：120,000 - 10,000 = 110,000ms。
+ */
+const MAX_IPC_TIMEOUT_MS = 110_000;
+// ============================================
+// IpcWatcher 類別
+// ============================================
+/**
+ * IPC Watcher：Hub 端的 Hook 請求處理器
+ *
+ * 在 Hub process 內執行，監聽 pending/ 目錄的新 JSON 檔案，
+ * 對每個審核請求執行 PolicyEngine 評估，並將結果寫回 resolved/ 目錄。
+ *
+ * S4-HOOK-RPERM-001: Mode-Aware
+ *   - local 模式 → TD-007 觀測（auto-approve）
+ *   - away 模式 → 真正攔截（ALLOW 放行，ASK/WARN 送 Cloud）
+ *
+ * 生命週期：
+ *   new IpcWatcher(opts) → start() → [處理請求...] → stop()
+ */
+class IpcWatcher {
+    opts;
+    /** pending/ 目錄完整路徑 */
+    pendingDir;
+    /** resolved/ 目錄完整路徑 */
+    resolvedDir;
+    /** chokidar FSWatcher 實例（null 表示尚未啟動或已停止） */
+    watcher = null;
+    /** 目前是否在執行中（防止重複 start()） */
+    isRunning = false;
+    /** 快取的 tool registry（避免每次 away-mode 審核都從磁碟讀取，隨實例生命週期管理） */
+    cachedRegistry = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.pendingDir = path.join(opts.ipcDir, 'pending');
+        this.resolvedDir = path.join(opts.ipcDir, 'resolved');
+    }
+    /**
+     * 啟動 IPC 監聽
+     *
+     * 建立必要目錄，並開始用 chokidar 監聽 pending/ 的新增 .json 檔案。
+     * 呼叫多次不會重複啟動（有 isRunning 保護）。
+     */
+    start() {
+        if (this.isRunning) {
+            this.opts.logger.warn('IpcWatcher: 已在執行中，忽略重複 start()');
+            return;
+        }
+        // 確保 IPC 目錄存在
+        // pre-tool-use.js 也會建立這些目錄，但 Hub 可能先啟動
+        fs.mkdirSync(this.pendingDir, { recursive: true });
+        fs.mkdirSync(this.resolvedDir, { recursive: true });
+        this.opts.logger.info('IpcWatcher: 啟動監聽', {
+            pendingDir: this.pendingDir,
+            resolvedDir: this.resolvedDir,
+        });
+        this.watcher = chokidar_1.default.watch(this.pendingDir, {
+            // persistent: true 確保 Node process 不因為只剩 watcher 而退出
+            // Hub 已由 MCP transport 保持存活，這裡主要是明確聲明意圖
+            persistent: true,
+            // depth: 0 只監聽 pending/ 目錄本身，不進入子目錄
+            // pending/ 是 flat 結構（{id}.json），不需要遞迴監聽
+            depth: 0,
+            // ignoreInitial: true 忽略 Hub 啟動時已存在的 pending 檔案
+            //
+            // 原因：這些是 Hub 上次關閉前遺留的「殭屍請求」：
+            //   - 對應的 pre-tool-use.js 程序早已超時退出（2 分鐘超時）
+            //   - 即使 Hub 回應了 resolved，也沒有任何程序在等待
+            //   - 處理這些殭屍請求只會浪費資源並堆積 resolved 檔案
+            ignoreInitial: true,
+            // awaitWriteFinish: 等待檔案寫入穩定後才觸發 'add' 事件
+            //
+            // 雖然 pre-tool-use.js 已使用原子寫入（.tmp + rename），
+            // 但某些 OS（尤其是 Windows/虛擬機）的 rename 可能觸發多次 fs 事件。
+            // 等待 100ms 穩定可以確保 chokidar 只觸發一次 'add' 事件。
+            awaitWriteFinish: {
+                stabilityThreshold: 100, // 100ms 內無變化視為寫入完成
+                pollInterval: 50, // 每 50ms 輪詢一次穩定性
+            },
+        });
+        // 'add' 事件：pending/ 目錄內出現新檔案（或 Hub 啟動後新增的檔案）
+        this.watcher.on('add', (filePath) => {
+            // 只處理 .json 檔案（忽略 .tmp 等臨時檔案）
+            if (!filePath.endsWith('.json'))
+                return;
+            this.opts.logger.debug('IpcWatcher: 偵測到新 pending 請求', {
+                file: path.basename(filePath),
+            });
+            // 非同步處理，但錯誤不拋出（確保 watcher 繼續運作）
+            // handlePendingFile 內部已有完整的錯誤處理
+            this.handlePendingFile(filePath).catch((err) => {
+                this.opts.logger.error('IpcWatcher: handlePendingFile 發生未預期錯誤', {
+                    filePath,
+                    error: err instanceof Error ? err.message : 'Unknown error',
+                });
+            });
+        });
+        // 'error' 事件：chokidar 內部錯誤（例如被監聽的目錄被刪除）
+        this.watcher.on('error', (err) => {
+            this.opts.logger.error('IpcWatcher: chokidar 錯誤', {
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+            // 不 throw，讓 watcher 繼續嘗試恢復（chokidar 會自動重試）
+        });
+        this.isRunning = true;
+    }
+    /**
+     * 停止 IPC 監聽
+     *
+     * 在 Hub 收到 SIGINT/SIGTERM 時呼叫（hub/src/index.ts 的 shutdown()）。
+     * 停止後 Hub 不再處理新的 pending 請求，但已在進行中的請求不受影響。
+     */
+    async stop() {
+        if (!this.isRunning)
+            return;
+        if (this.watcher) {
+            try {
+                // await chokidar.close() 確保所有 in-flight handler 完成後才繼續
+                // 避免 shutdown 時 DB 在 handler 寫入前就被關閉
+                await this.watcher.close();
+            }
+            catch (err) {
+                this.opts.logger.warn('IpcWatcher: watcher.close() 發生錯誤（忽略）', {
+                    error: err instanceof Error ? err.message : 'Unknown error',
+                });
+            }
+            this.watcher = null;
+        }
+        this.isRunning = false;
+        this.opts.logger.info('IpcWatcher: 已停止監聽');
+    }
+    // ============================================
+    // 內部方法
+    // ============================================
+    /**
+     * 處理一個新的 pending 請求檔案
+     *
+     * 完整流程：
+     *   1. 讀取並解析 JSON（IpcPendingRequest）
+     *   2. 判斷是否需要攔截（shouldIntercept）
+     *   3. 執行 PolicyEngine 評估（若需要攔截）
+     *   4. Mode-Aware 決策：
+     *      - ALLOW（any mode）→ auto-approve
+     *      - local + ASK/WARN → auto-approve（TD-007 觀測）
+     *      - away + ASK/WARN → 送 Cloud 等手機審核
+     *   5. 原子寫入 resolved 回應（IpcResolvedResponse）
+     *   6. 寫入 SQLite 操作記錄（若 store 可用）
+     *
+     * @param filePath - pending/ 目錄中的 JSON 檔案完整路徑
+     */
+    async handlePendingFile(filePath) {
+        // --- 步驟 1：讀取並解析請求 ---
+        let request;
+        try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            request = JSON.parse(content);
+        }
+        catch (err) {
+            // 檔案可能已被刪除（pre-tool-use.js 超時後會清理），或 JSON 格式錯誤
+            this.opts.logger.warn('IpcWatcher: 無法讀取/解析 pending 檔案', {
+                filePath,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+            return;
+        }
+        // 驗證必要欄位（防禦性檢查）
+        if (!request.id || !request.toolName) {
+            this.opts.logger.warn('IpcWatcher: pending 請求格式無效（缺少 id 或 toolName）', {
+                filePath,
+                request,
+            });
+            return;
+        }
+        // 防禦 path traversal：id 必須是單純的檔案名稱（不含路徑分隔符）
+        // 正常的 id 格式為 "hook-{uuid}"，不應包含 / 或 \
+        if (request.id !== path.basename(request.id)) {
+            this.opts.logger.warn('IpcWatcher: id 含路徑分隔符，拒絕處理（可能的 path traversal）', {
+                id: request.id,
+                filePath,
+            });
+            return;
+        }
+        const { id, toolName, sessionId } = request;
+        const now = new Date().toISOString();
+        this.opts.logger.info('IpcWatcher: 處理審核請求', {
+            id,
+            toolName,
+            sessionId,
+        });
+        // --- 步驟 2：判斷是否需要攔截 ---
+        if (!this.opts.shouldIntercept(toolName)) {
+            // dev-mode（isolated/allowlist）情況下，此工具不需要攔截 → 自動放行
+            //
+            // 這是「雞生蛋解法」的關鍵：
+            //   在 HOPPING_DEV_MODE=isolated 時，所有工具都自動放行，
+            //   避免用 Claude Code 開發 HopPing 本身時被自己攔截
+            this.opts.logger.debug('IpcWatcher: 自動放行（shouldIntercept 返回 false）', {
+                toolName,
+            });
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'Auto-approved (dev mode: not intercepting this tool)',
+                timestamp: now,
+            });
+            return;
+        }
+        // --- 步驟 3：執行 PolicyEngine 評估 ---
+        const evaluationContext = {
+            requestId: id,
+            agentId: sessionId ?? 'unknown',
+            agentType: this.opts.agentType,
+            operation: {
+                type: toolName,
+                target: request.cwd,
+            },
+            session: {
+                costUsd: 0,
+                durationSeconds: (Date.now() - this.opts.startTime) / 1000,
+                approvalCount: 0,
+            },
+            timestamp: now,
+        };
+        let policyResult = null;
+        try {
+            policyResult = await this.opts.policyEngine.evaluate(evaluationContext);
+            this.opts.logger.info('IpcWatcher: Policy 評估完成', {
+                id,
+                toolName,
+                finalAction: policyResult.finalAction,
+                triggeredPolicies: policyResult.triggeredPolicies.map((p) => p.policyName),
+            });
+        }
+        catch (err) {
+            // PolicyEngine 評估失敗 → 安全降級：auto-approve
+            this.opts.logger.error('IpcWatcher: PolicyEngine 評估失敗（降級 auto-approve）', {
+                id,
+                toolName,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'Policy evaluation failed; allowing in observation mode.',
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({
+                    id,
+                    toolName,
+                    request,
+                    approved: true,
+                    now,
+                    policyResult: null,
+                });
+            }
+            return;
+        }
+        // --- 步驟 4：Mode-Aware 決策 ---
+        // 統一計算 riskLevel（YOLO / away 模式皆需要，ALLOW / local 路徑成本極低可忽略）
+        const riskLevel = (0, risk_level_1.deriveRiskLevel)(policyResult.finalAction, toolName, request.toolInput ?? {});
+        // YOLO 模式：auto-approve（Policy 已執行，riskLevel 用於觀測記錄）
+        if (this.opts.isYoloMode?.()) {
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'YOLO mode: auto-approved (observation)',
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({
+                    id,
+                    toolName,
+                    request,
+                    approved: true,
+                    now,
+                    policyResult,
+                });
+            }
+            // 可選：透過 CloudConnector 發送 progress_update（Cloud 未連線則靜默略過）
+            const yoloConnector = this.opts.getCloudConnector?.();
+            if (yoloConnector?.isConnected) {
+                const agentId = this.opts.getAgentId?.() ?? 'unknown';
+                yoloConnector.sendProgressUpdate((0, risk_level_1.buildYoloProgressPayload)({
+                    agentId,
+                    sessionId: request.sessionId ?? agentId,
+                    toolName,
+                    riskLevel,
+                    timestamp: now,
+                    filePaths: extractFilePathsFromInput(toolName, request.toolInput ?? {}).filter(Boolean),
+                }));
+            }
+            return;
+        }
+        // ALLOW：任何模式都自動放行
+        if (policyResult.finalAction === 'ALLOW') {
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'Approved by local policy',
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({ id, toolName, request, approved: true, now, policyResult });
+            }
+            return;
+        }
+        // ASK/WARN：依 askMode 決策
+        const mode = this.opts.getAskMode();
+        if (mode === 'local') {
+            // local 模式：TD-007 觀測（auto-approve）
+            // 審核職責交由 Skill + hopping.check（避免重複審核）
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: `Observed (${policyResult.finalAction}) — local mode, approval delegated to hopping.check`,
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({ id, toolName, request, approved: true, now, policyResult });
+            }
+            return;
+        }
+        // away 模式：真正攔截
+        await this.handleAwayModeApproval(id, toolName, request, policyResult, filePath, now, riskLevel);
+    }
+    /**
+     * Away 模式的 Cloud 審核流程
+     *
+     * 1. Cloud connected → sendPermissionPrompt + waitForApproval
+     * 2. Cloud disconnected → auto-allow fallback（降級觀測）
+     * 3. Timeout → 依 riskLevel 決策
+     * 4. Denied → approved=false
+     */
+    async handleAwayModeApproval(id, toolName, request, policyResult, filePath, now, riskLevel) {
+        // S4-HUB-DONTASK-001: Session memory check — auto-approve if "don't ask again" was set
+        if (this.opts.sessionMemory?.has(toolName, riskLevel)) {
+            this.opts.logger.info('IpcWatcher: session memory hit — auto-approve', {
+                id,
+                toolName,
+                riskLevel,
+            });
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'Session memory: dont_ask_again',
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({
+                    id,
+                    toolName,
+                    request,
+                    approved: true,
+                    now,
+                    policyResult,
+                    promptType: 'native_permission',
+                    responseType: 'binary',
+                });
+            }
+            return;
+        }
+        const cloudConnector = this.opts.getCloudConnector();
+        // Cloud 未連線：auto-allow fallback（降級觀測模式）
+        if (!cloudConnector?.isConnected) {
+            this.opts.logger.warn('IpcWatcher: away 模式但 Cloud 未連線，降級 auto-allow', {
+                id,
+                toolName,
+                riskLevel,
+            });
+            this.writeResolved(id, {
+                id,
+                approved: true,
+                reason: 'Auto-allowed (Cloud offline, observation mode)',
+                timestamp: now,
+            });
+            this.cleanupPending(filePath);
+            if (this.opts.store) {
+                this.writeOperationRecord({
+                    id,
+                    toolName,
+                    request,
+                    approved: true,
+                    now,
+                    policyResult,
+                    promptType: 'native_permission',
+                    responseType: 'binary',
+                    overrideDecision: 'auto_allowed_offline',
+                });
+            }
+            return;
+        }
+        // Cloud 已連線：送 permission_prompt 並等待 Mobile 回應
+        this.opts.logger.info('IpcWatcher: away 模式，送 Cloud 審核', {
+            id,
+            toolName,
+            riskLevel,
+            finalAction: policyResult.finalAction,
+        });
+        // 取得 approval timeout 設定
+        const approvalConfig = await this.getApprovalConfigSafe();
+        const configTimeout = approvalConfig.timeouts[riskLevel];
+        const effectiveTimeout = Math.min(configTimeout, MAX_IPC_TIMEOUT_MS);
+        // 建立 summary 和 toolContext（registry 快取避免重複磁碟讀取）
+        const summary = (0, summary_1.generateSummary)(toolName, request.toolInput ?? {});
+        if (!this.cachedRegistry) {
+            this.cachedRegistry = (0, tool_mapping_1.loadBundledRegistry)();
+        }
+        const mappingEntry = (0, tool_mapping_1.resolveToolMapping)(toolName, this.opts.agentType, null, this.cachedRegistry);
+        const agentId = this.opts.getAgentId?.() ?? 'unknown';
+        // 先寫入 SQLite（decision 暫為 null，等待 Mobile 回應後更新）
+        if (this.opts.store) {
+            this.writeOperationRecord({
+                id,
+                toolName,
+                request,
+                approved: false,
+                now,
+                policyResult,
+                promptType: 'native_permission',
+                responseType: 'binary',
+            });
+        }
+        // 發送 permission_prompt 到 Cloud
+        const promptPayload = {
+            id,
+            agentId,
+            toolName,
+            riskLevel,
+            summary,
+            policyAction: policyResult.finalAction,
+            sessionId: request.sessionId,
+            timestamp: now,
+            timeoutMs: effectiveTimeout,
+            onTimeout: (0, manager_1.toApprovalDecision)(approvalConfig.onTimeout[riskLevel]),
+            promptType: 'native_permission',
+            responseType: 'binary',
+            toolContext: {
+                description: risk_level_1.OPERATION_TYPE_DESCRIPTIONS[mappingEntry.type] ?? risk_level_1.OPERATION_TYPE_DESCRIPTIONS['unknown'],
+                parameters: request.toolInput ?? {},
+            },
+        };
+        cloudConnector.sendPermissionPrompt(promptPayload);
+        // 等待 ApprovalManager 回傳決策
+        const result = await this.opts.approvalManager.waitForApproval(id, effectiveTimeout);
+        if (!result.timedOut) {
+            // Mobile 及時回應
+            const approved = result.approved;
+            const reason = approved
+                ? `Approved remotely${result.reason ? `: ${result.reason}` : ''}`
+                : `Denied remotely${result.reason ? `: ${result.reason}` : ''}`;
+            this.writeResolved(id, {
+                id,
+                approved,
+                reason,
+                timestamp: new Date().toISOString(),
+            });
+            this.cleanupPending(filePath);
+            // 更新 SQLite decision
+            if (this.opts.store) {
+                const decidedAt = new Date().toISOString();
+                this.opts.store.operations.updateDecision(id, approved ? 'approved' : 'denied', decidedAt);
+            }
+            return;
+        }
+        // Timeout：依 config 決策
+        const onTimeout = (0, manager_1.toApprovalDecision)(approvalConfig.onTimeout[riskLevel]);
+        const timeoutApproved = onTimeout === 'approved' || onTimeout === 'pending';
+        this.opts.logger.warn('IpcWatcher: away 模式審核超時', {
+            id,
+            toolName,
+            riskLevel,
+            onTimeout,
+            timeoutApproved,
+        });
+        this.writeResolved(id, {
+            id,
+            approved: timeoutApproved,
+            reason: `Approval timeout (${effectiveTimeout}ms), decision: ${onTimeout}`,
+            timestamp: new Date().toISOString(),
+        });
+        this.cleanupPending(filePath);
+        // 更新 SQLite
+        if (this.opts.store) {
+            const decidedAt = new Date().toISOString();
+            this.opts.store.operations.updateDecision(id, onTimeout, decidedAt);
+        }
+    }
+    /**
+     * 安全取得 ApprovalTimeoutConfig
+     */
+    async getApprovalConfigSafe() {
+        if (!this.opts.configManager)
+            return { ...manager_1.DEFAULT_APPROVAL_CONFIG };
+        try {
+            return await this.opts.configManager.getApprovalConfig();
+        }
+        catch {
+            return { ...manager_1.DEFAULT_APPROVAL_CONFIG };
+        }
+    }
+    /**
+     * 原子寫入 resolved 回應檔案
+     *
+     * 步驟：
+     *   1. 寫入 {id}.json.tmp（暫存）
+     *   2. rename 為 {id}.json（原子替換）
+     *
+     * 為什麼需要原子寫入？
+     *   pre-tool-use.js 每 200ms polling resolved/ 目錄，
+     *   若不用原子寫入，可能讀到寫到一半的 JSON（JSON.parse 失敗）。
+     *   rename 在同一 filesystem 上是 POSIX 原子操作，不存在這個問題。
+     *
+     * @param id - IPC 請求 ID（對應 pending 檔案名，不含副檔名）
+     * @param response - 要寫入的回應資料
+     */
+    writeResolved(id, response) {
+        const resolvedPath = path.join(this.resolvedDir, `${id}.json`);
+        const tmpPath = `${resolvedPath}.tmp`;
+        try {
+            // 先寫暫存檔
+            fs.writeFileSync(tmpPath, JSON.stringify(response, null, 2), 'utf8');
+            // 原子替換：rename 成功則 pre-tool-use.js 可以立刻讀到完整 JSON
+            fs.renameSync(tmpPath, resolvedPath);
+            this.opts.logger.debug('IpcWatcher: resolved 回應已寫入', {
+                id,
+                approved: response.approved,
+                resolvedPath,
+            });
+        }
+        catch (err) {
+            this.opts.logger.error('IpcWatcher: 寫入 resolved 失敗', {
+                id,
+                resolvedPath,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+            // 寫入失敗時，pre-tool-use.js 會在 2 分鐘超時後自動放行
+            // 這是 fallback 的 fallback：即使 Hub 出問題，Claude Code 不會永久阻塞
+        }
+    }
+    /**
+     * 清理 pending 檔案
+     */
+    cleanupPending(filePath) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch {
+            // 檔案可能已被 pre-tool-use.js 清理，忽略
+        }
+    }
+    /**
+     * 將操作記錄寫入 SQLite operations + metadata 表
+     */
+    writeOperationRecord(params) {
+        const { id, toolName, request, approved, now, policyResult, promptType, responseType, overrideDecision, } = params;
+        if (!this.opts.store)
+            return;
+        try {
+            const decision = (overrideDecision ?? (approved ? 'approved' : 'denied'));
+            // 從 PolicyEngine 結果或 content pattern 推導 riskLevel
+            const riskLevel = policyResult
+                ? (0, risk_level_1.deriveRiskLevel)(policyResult.finalAction, toolName, request.toolInput ?? {})
+                : null;
+            // 從 toolInput 提取受影響的檔案路徑
+            const filePaths = extractFilePathsFromInput(toolName, request.toolInput ?? {});
+            // 寫入 operations 表（含 v4 新欄位）
+            this.opts.store.operations.insert({
+                id,
+                approvalId: null,
+                toolName,
+                toolParams: request.toolInput ? JSON.stringify(request.toolInput) : null,
+                filePaths: filePaths.length > 0 ? JSON.stringify(filePaths) : null,
+                riskLevel,
+                decision: (overrideDecision === undefined && !approved
+                    ? null
+                    : decision),
+                createdAt: now,
+                decidedAt: overrideDecision === undefined && !approved ? null : now,
+                toolUseId: request.toolUseId ?? null,
+                promptType: promptType ?? null,
+                responseType: responseType ?? null,
+            });
+            // 寫入 metadata 表（source 修正為 'hook'）
+            this.opts.store.metadata.insert({
+                operationId: id,
+                agentType: this.opts.agentType,
+                sessionId: request.sessionId ?? 'unknown',
+                durationMs: null,
+                tokenUsage: null,
+                contextTags: null,
+                source: 'hook',
+                resultStatus: null,
+                toolResultSummary: null,
+                createdAt: now,
+            });
+            this.opts.logger.debug('IpcWatcher: 操作記錄已寫入 SQLite', {
+                operationId: id,
+                toolName,
+                decision,
+                riskLevel,
+                toolUseId: request.toolUseId,
+            });
+        }
+        catch (err) {
+            this.opts.logger.warn('IpcWatcher: SQLite 寫入失敗（不影響審核結果）', {
+                id,
+                toolName,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            });
+        }
+    }
+}
+exports.IpcWatcher = IpcWatcher;
+// ============================================
+// 輔助函式
+// ============================================
+/**
+ * 從 toolInput 中提取受影響的檔案路徑
+ *
+ * ⚠️ 同步要求：此函式的邏輯與 packages/hooks/hooks/post-tool-use.js 的
+ *   extractFilePaths() 完全一致。修改任一份時必須同步更新另一份。
+ *   兩份程式碼分屬不同 package（TS vs JS），無法直接共用。
+ */
+function extractFilePathsFromInput(toolName, toolInput) {
+    const paths = [];
+    if (toolInput.file_path && typeof toolInput.file_path === 'string') {
+        paths.push(toolInput.file_path);
+    }
+    if (toolInput.notebook_path && typeof toolInput.notebook_path === 'string') {
+        paths.push(toolInput.notebook_path);
+    }
+    if (toolInput.path &&
+        typeof toolInput.path === 'string' &&
+        toolName !== 'Bash' &&
+        !paths.includes(toolInput.path)) {
+        paths.push(toolInput.path);
+    }
+    return paths;
+}
+//# sourceMappingURL=watcher.js.map