@winspan/claude-forge 8.41.0 → 8.51.0

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Claude Forge - PreToolUse Hook（双向通信）
+
+# shellcheck source=./hook-lib.sh
+source "$(dirname "$0")/hook-lib.sh"
+
+AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
+
+# 读取 stdin（Claude Code 传入的 JSON）
+INPUT=$(cat)
+
+# 提取字段（单次 jq 调用，替代 3 个 python3 进程）
+TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | jq -r '.tool_name // ""')}"
+TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
+RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
+SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+
+# 构造事件 JSON（jq -n 替代 python3 heredoc）
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+EVENT=$(jq -n \
+  --arg hook_type "PreToolUse" \
+  --arg timestamp "$TIMESTAMP" \
+  --arg session_id "$SESSION_ID" \
+  --arg project_path "$PROJECT_PATH" \
+  --arg tool_name "$TOOL_NAME" \
+  --argjson tool_input "$TOOL_INPUT" \
+  --arg auth "$AUTH_TOKEN" \
+  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
+    project_path: $project_path, tool_name: $tool_name, tool_input: $tool_input,
+    _auth: $auth}')
+
+# 发送事件（5 秒超时；失败时入队）
+send_event_or_enqueue "$EVENT" 5
+RESPONSE="$HOOK_RESPONSE"
+
+if [ -n "$RESPONSE" ]; then
+  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true')
+
+  if [ "$ALLOW" = "false" ]; then
+    # 优先使用 hookSpecificOutput（Claude Code 官方格式），否则降级到 stderr + exit 2
+    HAS_HOOK_OUTPUT=$(echo "$RESPONSE" | jq -r 'if .hookSpecificOutput then "yes" else "no" end')
+    if [ "$HAS_HOOK_OUTPUT" = "yes" ]; then
+      # 输出 hookSpecificOutput 格式到 stdout，但必须 exit 非0 才能真正阻止工具执行
+      echo "$RESPONSE" | jq '{hookSpecificOutput: .hookSpecificOutput}'
+      exit 1
+    else
+      # 降级：输出原因到 stderr，exit 2 强制阻断
+      REASON=$(echo "$RESPONSE" | jq -r '.reason // "操作被 Forge 阻断"')
+      echo "$REASON" >&2
+      exit 2
+    fi
+  fi
+
+  # 有 additionalContext 时输出
+  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
+  if [ "$HAS_CONTEXT" = "yes" ]; then
+    echo "$RESPONSE"
+  fi
+fi
+
+exit 0

package/src/hooks/stop.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Claude Forge - Stop Hook
+
+# shellcheck source=./hook-lib.sh
+source "$(dirname "$0")/hook-lib.sh"
+
+AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
+
+# 读取 stdin
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# 提取 cwd，上溯 git root
+RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
+SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+
+# 构造事件 JSON
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+EVENT=$(jq -n \
+  --arg hook_type "Stop" \
+  --arg timestamp "$TIMESTAMP" \
+  --arg session_id "$SESSION_ID" \
+  --arg project_path "$PROJECT_PATH" \
+  --arg auth "$AUTH_TOKEN" \
+  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
+    project_path: $project_path, tool_name: "stop", tool_input: {}, _auth: $auth}')
+
+# 发送事件并读取响应（失败时入队）
+send_event_or_enqueue "$EVENT" 5
+RESPONSE="$HOOK_RESPONSE"
+
+# 解析响应：allow=false 时输出 reason 并以 exit 2 阻断
+if [ -n "$RESPONSE" ]; then
+  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true' 2>/dev/null)
+  if [ "$ALLOW" = "false" ]; then
+    REASON=$(echo "$RESPONSE" | jq -r '.reason // "质量门禁阻断"' 2>/dev/null)
+    echo "$REASON"
+    exit 2
+  fi
+fi
+
+exit 0

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Claude Forge - UserPromptSubmit Hook
+# 拦截用户输入，触发意图分析和自动 Pipeline 编排
+
+# shellcheck source=./hook-lib.sh
+source "$(dirname "$0")/hook-lib.sh"
+
+AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
+
+# 读取 stdin（Claude Code 传入的 JSON）
+INPUT=$(cat)
+
+# 提取字段（jq 替代 python3）
+USER_PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""')
+RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
+SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
+
+# 空 prompt 跳过
+if [ -z "$USER_PROMPT" ]; then
+  exit 0
+fi
+
+# 构造事件 JSON（jq -n 替代 python3 heredoc）
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+EVENT=$(jq -n \
+  --arg hook_type "UserPromptSubmit" \
+  --arg timestamp "$TIMESTAMP" \
+  --arg session_id "$SESSION_ID" \
+  --arg project_path "$PROJECT_PATH" \
+  --arg user_prompt "$USER_PROMPT" \
+  --arg auth "$AUTH_TOKEN" \
+  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
+    project_path: $project_path, tool_name: "UserPrompt",
+    user_prompt: $user_prompt, tool_input: {user_prompt: $user_prompt}, _auth: $auth}')
+
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+# 发送事件（10 秒超时，AI 分析可能需要更多时间）
+# 失败时自动入队（daemon 停机期间事件不丢失）
+send_event_or_enqueue "$EVENT" 10
+RESPONSE="$HOOK_RESPONSE"
+
+if [ -n "$RESPONSE" ]; then
+  HAS_SYSTEM=$(echo "$RESPONSE" | jq -r 'if .systemMessage and (.systemMessage != "") then "yes" else "no" end')
+  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
+
+  if [ "$HAS_SYSTEM" = "yes" ] || [ "$HAS_CONTEXT" = "yes" ]; then
+    # stderr 输出摘要到终端
+    if [ "$HAS_SYSTEM" = "yes" ]; then
+      SM_LEN=$(echo "$RESPONSE" | jq -r '.systemMessage | length')
+      printf '\033[36m💉 [Forge] 注入 systemMessage (%s chars)\033[0m\n' "$SM_LEN" >&2
+    fi
+    if [ "$HAS_CONTEXT" = "yes" ]; then
+      CONTEXT=$(echo "$RESPONSE" | jq -r '.additionalContext // ""')
+      DISPLAY_LINES=$(printf '%s' "$CONTEXT" | head -3)
+      if [ -n "$DISPLAY_LINES" ]; then
+        printf '\033[36m💉 [Forge] %s\033[0m\n' "$DISPLAY_LINES" >&2
+      fi
+    fi
+    # stdout 返回给 Claude Code
+    echo "$RESPONSE"
+  fi
+fi
+
+exit 0

package/src/mcp/server.ts

@@ -0,0 +1,322 @@
+/**
+ * MCP Server for claude-forge
+ *
+ * 嵌入在 daemon 进程内，通过 HTTP（Streamable HTTP transport）向 Claude Code
+ * 暴露以下工具：
+ *   - skill_invoke：Agent 按需获取某个 Skill 的方法论内容
+ *   - skill_list：列出所有可用 Skill（id / name / description / keywords）
+ *
+ * 调用链路：
+ *   Claude Code → HTTP POST /mcp → MCP server → skillInvoke()/skillList()
+ *                                            → writeSkillInvocation() 记录
+ *
+ * 设计要点：
+ *   - 复用现有 Express app（不新增端口），路径前缀固定为 /mcp
+ *   - 沿用 daemon auth token（Bearer），与 /api 写操作同一鉴权链路
+ *   - Stateless 模式：每个请求开一对 server/transport，避免长连接污染
+ *     daemon 主循环；Skill 调用本身是短平快、无需流式推送的场景
+ *   - Session 追踪：优先 header `X-Forge-Session-Id`，缺失时生成匿名 session
+ *     (Ruflo 模式下 Claude 自主决策，不需要 routing state 回退)
+ */
+
+import type { Application, Request, Response } from 'express';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+
+import type { SkillRegistry } from '../skills/registry.js';
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+import type { InvocationGuard } from '../skills/invocation-guard.js';
+import { skillInvoke } from '../skills/tools/skill-invoke.js';
+import { skillList } from '../skills/tools/skill-list.js';
+import { pipelineSuggest } from '../skills/tools/pipeline-suggest.js';
+import { logger } from '../core/utils/logger.js';
+import { requireAuth } from '../web/auth-middleware.js';
+
+/** Resolved session context for a single MCP tool call. */
+export interface SessionContext {
+  sessionId: string | null;
+  routeRequestId: string | null;
+  agentId: string | null;
+}
+
+export interface McpServerOptions {
+  skillRegistry: SkillRegistry;
+  storage: SQLiteStorage;
+  guard?: InvocationGuard;
+  /**
+   * Override the session-resolution strategy. Default behavior:
+   *   1. Read header `X-Forge-Session-Id` (passed by the harness if available)
+   *   2. Fallback: pick the freshest live routing entry from routingState
+   *   3. If neither yields a sessionId → return all-null context (invocation
+   *      will be recorded with session_id derived from the synthetic
+   *      "mcp-anon-<ts>" so the writeSkillInvocation NOT NULL constraint still
+   *      passes; see resolveSessionContext below).
+   */
+  resolveSession?: (req: Request) => SessionContext;
+}
+
+const SERVER_INFO = {
+  name: 'claude-forge',
+  version: '1.0.0',
+} as const;
+
+/**
+ * Resolve session context for a request.
+ *
+ * Priority order:
+ *   1. Explicit header `X-Forge-Session-Id` (+ optional `X-Forge-Route-Request-Id`,
+ *      `X-Forge-Agent-Id`).
+ *   2. routingState.getMostRecent() — heuristic fallback during the routing
+ *      window (≤30min TTL).
+ *   3. Synthetic anonymous session "mcp-anon-<unix-ts>" so we never blow the
+ *      NOT NULL session_id constraint when persisting invocations.
+ */
+function resolveSessionContext(req: Request): SessionContext {
+  const headerSession = req.header('X-Forge-Session-Id');
+  if (headerSession && headerSession.trim().length > 0) {
+    const headerRoute = req.header('X-Forge-Route-Request-Id');
+    const headerAgent = req.header('X-Forge-Agent-Id');
+    return {
+      sessionId: headerSession.trim(),
+      routeRequestId: headerRoute?.trim() || null,
+      agentId: headerAgent?.trim() || null,
+    };
+  }
+
+  // In Ruflo mode, Claude makes autonomous decisions via CLAUDE.md.
+  // MCP tools no longer need routing state fallback.
+  return {
+    sessionId: `mcp-anon-${Date.now()}`,
+    routeRequestId: null,
+    agentId: null,
+  };
+}
+
+/** Build a fresh MCP server instance bound to the given options & context. */
+function buildServer(
+  options: McpServerOptions,
+  sessionCtx: SessionContext,
+): McpServer {
+  const server = new McpServer(SERVER_INFO, {
+    capabilities: { tools: { listChanged: false } },
+  });
+
+  // ── Tool 1: skill_invoke ───────────────────────────────────────────────
+  server.registerTool(
+    'skill_invoke',
+    {
+      title: 'Invoke a claude-forge skill',
+      description:
+        '调用指定的 Skill，获取该方法论的完整内容。使用场景：当你需要特定领域的方法论指导（如 TDD、重构、性能优化）时。',
+      inputSchema: {
+        skill_id: z
+          .string()
+          .min(1)
+          .describe('Skill 的 ID（如 "official-tdd"）。可通过 skill_list 工具查询。'),
+        reason: z
+          .string()
+          .optional()
+          .describe('调用理由（可选，用于审计 / skill_invocations.reason 列）'),
+      },
+    },
+    async (args) => {
+      try {
+        const sessionId = sessionCtx.sessionId ?? `mcp-anon-${Date.now()}`;
+        const result = await skillInvoke(
+          { skill_id: args.skill_id, reason: args.reason },
+          {
+            skillRegistry: options.skillRegistry,
+            guard: options.guard,
+            storage: options.storage,
+            sessionId,
+            routeRequestId: sessionCtx.routeRequestId ?? undefined,
+            agentId: sessionCtx.agentId ?? undefined,
+            invocationType: 'dynamic',
+          },
+        );
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `# ${result.skill_name}\n\n${result.content}`,
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[MCP] skill_invoke failed: ${message}`);
+        return {
+          isError: true,
+          content: [{ type: 'text' as const, text: message }],
+        };
+      }
+    },
+  );
+
+  // ── Tool 2: skill_list ─────────────────────────────────────────────────
+  server.registerTool(
+    'skill_list',
+    {
+      title: 'List available claude-forge skills',
+      description: '列出所有可用的 Skill。可以通过 keywords 过滤（OR 语义）。',
+      inputSchema: {
+        keywords: z
+          .array(z.string())
+          .optional()
+          .describe('可选的关键词过滤（如 ["test", "tdd"]）'),
+      },
+    },
+    async (args) => {
+      try {
+        logger.info(`[MCP] skill_list called with args: ${JSON.stringify(args)}`);
+        const result = await skillList(
+          { keywords: args.keywords },
+          { skillRegistry: options.skillRegistry },
+        );
+        return {
+          content: [
+            { type: 'text' as const, text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[MCP] skill_list failed: ${message}`);
+        return {
+          isError: true,
+          content: [{ type: 'text' as const, text: message }],
+        };
+      }
+    },
+  );
+
+  // ── Tool 3: pipeline_suggest ───────────────────────────────────────────
+  server.registerTool(
+    'pipeline_suggest',
+    {
+      title: 'Suggest a swarm pipeline for a task',
+      description:
+        '根据任务特征判断是否需要启动多 Agent 协作的 Pipeline，并生成可直接使用的 Task({...}) 调用代码。',
+      inputSchema: {
+        task_description: z
+          .string()
+          .min(1)
+          .describe('任务描述（如 "修复用户登录时的 session 过期问题"）'),
+        file_count: z
+          .number()
+          .int()
+          .optional()
+          .describe('预估涉及的文件数量（>=2 时建议使用 Pipeline）'),
+        is_new_feature: z
+          .boolean()
+          .optional()
+          .describe('是否为新功能开发'),
+        is_refactor: z
+          .boolean()
+          .optional()
+          .describe('是否为重构任务'),
+        is_bug_fix: z
+          .boolean()
+          .optional()
+          .describe('是否为 Bug 修复'),
+        is_performance: z
+          .boolean()
+          .optional()
+          .describe('是否为性能优化'),
+        is_migration: z
+          .boolean()
+          .optional()
+          .describe('是否为技术迁移/升级'),
+        is_security: z
+          .boolean()
+          .optional()
+          .describe('是否为安全审计/漏洞修复'),
+      },
+    },
+    async (args) => {
+      try {
+        const result = await pipelineSuggest({
+          task_description: args.task_description,
+          file_count: args.file_count,
+          is_new_feature: args.is_new_feature,
+          is_refactor: args.is_refactor,
+          is_bug_fix: args.is_bug_fix,
+          is_performance: args.is_performance,
+          is_migration: args.is_migration,
+          is_security: args.is_security,
+        });
+        return {
+          content: [
+            { type: 'text' as const, text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[MCP] pipeline_suggest failed: ${message}`);
+        return {
+          isError: true,
+          content: [{ type: 'text' as const, text: message }],
+        };
+      }
+    },
+  );
+
+  return server;
+}
+
+/**
+ * Mount the MCP server endpoints on an existing Express application.
+ *
+ * Routes:
+ *   POST /mcp   — JSON-RPC over Streamable HTTP (initialize, tools/list, tools/call)
+ *   GET  /mcp   — Standalone SSE channel (server→client notifications)
+ *   DELETE /mcp — Session termination (stateful mode only; no-op in stateless)
+ *
+ * Authentication: every method requires the daemon Bearer token. Token-file
+ * absence still falls through (early-startup safety, identical to /api).
+ */
+export function mountMcpServer(app: Application, options: McpServerOptions): void {
+  const resolveSession = options.resolveSession ?? resolveSessionContext;
+
+  const handler = async (req: Request, res: Response): Promise<void> => {
+    // Stateless: build a fresh server+transport per request. The transport
+    // mutates res so it cannot be reused across requests anyway.
+    const sessionCtx = resolveSession(req);
+    const server = buildServer(options, sessionCtx);
+    const transport = new StreamableHTTPServerTransport({
+      // Stateless mode — no session ID generator.
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+
+    res.on('close', () => {
+      // best-effort cleanup; ignore errors because transport may already be closed
+      void transport.close().catch(() => undefined);
+      void server.close().catch(() => undefined);
+    });
+
+    try {
+      await server.connect(transport);
+      // express.json() has already populated req.body; pass it through.
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      logger.warn(`[MCP] request failed: ${err instanceof Error ? err.message : String(err)}`);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: 'Internal error' },
+          id: null,
+        });
+      }
+    }
+  };
+
+  // All MCP requests are auth-gated. We deliberately gate GET too because MCP
+  // tool-calls (sensitive ops) can come over GET via SSE; /api keeps GET open
+  // only for read-only dashboard polling.
+  app.post('/mcp', requireAuth, handler);
+  app.get('/mcp', requireAuth, handler);
+  app.delete('/mcp', requireAuth, handler);
+
+  logger.info('[MCP] Server mounted on /mcp (Streamable HTTP, stateless)');
+}

package/src/skills/index.ts

@@ -0,0 +1,2 @@
+export { SkillRegistry, type Skill } from './registry.js';
+export { matchKeywords, formatSkillRecommendation } from './matcher.js';

package/src/skills/invocation-guard.ts

@@ -0,0 +1,177 @@
+/**
+ * InvocationGuard — Skill 调用防护机制
+ *
+ * 防止 Agent 陷入无限调用 Skill 的循环，限制：
+ * - 单会话总调用次数（默认 10）
+ * - 单会话调用深度（默认 3）
+ * - 同 session 同 skill 幂等（避免重复调用）
+ * - TTL 机制：会话状态 30 分钟后自动过期
+ *
+ * 状态为进程内存，进程重启会清空；调用链路通常集中在单个会话内，
+ * 重启后重建状态是可接受的。
+ */
+
+const MAX_INVOCATIONS_PER_SESSION = 10;
+const MAX_INVOCATION_DEPTH = 3;
+const SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+export interface SessionInvocations {
+  total: number;
+  depth: number;
+  calledSkills: Set<string>;
+  lastAccessTime: number; // Timestamp of last access
+}
+
+export interface InvocationCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export class InvocationGuard {
+  private sessions = new Map<string, SessionInvocations>();
+  private cleanupTimer: NodeJS.Timeout | null = null;
+
+  constructor() {
+    // Start automatic cleanup timer
+    this.startCleanupTimer();
+  }
+
+  /**
+   * 检查是否允许调用。
+   * 不修改状态；调用方决定是否继续后调用 record()。
+   */
+  check(sessionId: string, skillId: string): InvocationCheckResult {
+    const session = this.sessions.get(sessionId) ?? {
+      total: 0,
+      depth: 0,
+      calledSkills: new Set<string>(),
+      lastAccessTime: Date.now(),
+    };
+
+    // Check if session has expired
+    if (Date.now() - session.lastAccessTime > SESSION_TTL_MS) {
+      this.sessions.delete(sessionId);
+      return { allowed: true }; // Expired session, allow new invocation
+    }
+
+    if (session.total >= MAX_INVOCATIONS_PER_SESSION) {
+      return {
+        allowed: false,
+        reason: `Reached max invocations per session (${MAX_INVOCATIONS_PER_SESSION})`,
+      };
+    }
+
+    if (session.depth >= MAX_INVOCATION_DEPTH) {
+      return {
+        allowed: false,
+        reason: `Reached max invocation depth (${MAX_INVOCATION_DEPTH})`,
+      };
+    }
+
+    if (session.calledSkills.has(skillId)) {
+      return {
+        allowed: false,
+        reason: `Skill '${skillId}' already invoked in this session (idempotent guard)`,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * 记录一次调用开始（递增 total 和 depth，登记 skill）。
+   */
+  record(sessionId: string, skillId: string): void {
+    const session = this.sessions.get(sessionId) ?? {
+      total: 0,
+      depth: 0,
+      calledSkills: new Set<string>(),
+      lastAccessTime: Date.now(),
+    };
+    session.total += 1;
+    session.depth += 1;
+    session.calledSkills.add(skillId);
+    session.lastAccessTime = Date.now(); // Update access time
+    this.sessions.set(sessionId, session);
+  }
+
+  /**
+   * 调用完成，递减 depth（不清除已调用 skills）。
+   */
+  complete(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.depth = Math.max(0, session.depth - 1);
+      session.lastAccessTime = Date.now(); // Update access time
+    }
+  }
+
+  /**
+   * 清理会话（Stop hook 或会话结束时调用）。
+   */
+  clear(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  /**
+   * 获取会话统计（调试/观测用）。
+   */
+  getStats(sessionId: string): SessionInvocations | null {
+    return this.sessions.get(sessionId) ?? null;
+  }
+
+  /**
+   * 清理过期会话（TTL 机制）。
+   */
+  private cleanupExpiredSessions(): void {
+    const now = Date.now();
+    const expiredSessions: string[] = [];
+
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (now - session.lastAccessTime > SESSION_TTL_MS) {
+        expiredSessions.push(sessionId);
+      }
+    }
+
+    for (const sessionId of expiredSessions) {
+      this.sessions.delete(sessionId);
+    }
+
+    if (expiredSessions.length > 0) {
+      // Use console.log instead of logger to avoid circular dependency
+      console.log(`[InvocationGuard] Cleaned up ${expiredSessions.length} expired sessions`);
+    }
+  }
+
+  /**
+   * 启动自动清理定时器。
+   */
+  private startCleanupTimer(): void {
+    if (this.cleanupTimer) return;
+
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupExpiredSessions();
+    }, CLEANUP_INTERVAL_MS);
+
+    // Prevent timer from keeping process alive
+    this.cleanupTimer.unref();
+  }
+
+  /**
+   * 停止自动清理定时器（用于测试或进程关闭）。
+   */
+  stopCleanupTimer(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  /**
+   * 获取当前会话数量（用于监控）。
+   */
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+}