@winspan/claude-forge 8.41.0 → 8.51.0

package/src/core/utils/token-tracker.ts

@@ -0,0 +1,97 @@
+/**
+ * Token usage tracker — centralized token recording and budget alerting
+ */
+
+import type { SQLiteStorage } from '../storage/sqlite.js';
+import type { TokenUsage } from '../ai/types.js';
+import { logger } from './logger.js';
+
+export interface TokenRecordParams {
+  session_id: string;
+  usage: TokenUsage;
+  model?: string;
+  tool_name?: string;
+}
+
+export class TokenTracker {
+  private storage: SQLiteStorage;
+  private budgetPerSession: number;
+  private warningThreshold: number;
+
+  constructor(storage: SQLiteStorage, options?: {
+    budgetPerSession?: number;
+    warningThreshold?: number;
+  }) {
+    this.storage = storage;
+    this.budgetPerSession = options?.budgetPerSession
+      ?? parseInt(process.env.TOKEN_BUDGET_PER_SESSION ?? '1000000');
+    this.warningThreshold = options?.warningThreshold ?? 0.8;
+  }
+
+  /**
+   * Record token usage and check budget
+   */
+  record(params: TokenRecordParams): void {
+    try {
+      this.storage.writeTokenUsage({
+        session_id: params.session_id,
+        input_tokens: params.usage.input_tokens,
+        output_tokens: params.usage.output_tokens,
+        model: params.model,
+        tool_name: params.tool_name,
+      });
+
+      this.checkBudget(params.session_id);
+    } catch (err) {
+      logger.debug(`[TokenTracker] Failed to record token usage: ${err}`);
+    }
+  }
+
+  /**
+   * Check if session has exceeded budget thresholds
+   */
+  private checkBudget(session_id: string): void {
+    try {
+      const usage = this.storage.getTokenUsageBySession(session_id);
+      const usageRatio = usage.total_tokens / this.budgetPerSession;
+
+      if (usageRatio >= 1.0) {
+        console.error(
+          `\x1b[31m🚨 [Forge:Token预算] Session ${session_id.slice(0, 8)} 已超预算！\x1b[0m\n` +
+          `   已用: ${usage.total_tokens.toLocaleString()} tokens\n` +
+          `   预算: ${this.budgetPerSession.toLocaleString()} tokens\n` +
+          `   超出: ${((usageRatio - 1) * 100).toFixed(1)}%`
+        );
+        logger.warn(
+          `[TokenTracker] Session ${session_id} exceeded budget: ${usage.total_tokens}/${this.budgetPerSession}`
+        );
+      } else if (usageRatio >= this.warningThreshold) {
+        console.warn(
+          `\x1b[33m⚠️  [Forge:Token预算] Session ${session_id.slice(0, 8)} 已用 ${(usageRatio * 100).toFixed(1)}% 预算\x1b[0m\n` +
+          `   已用: ${usage.total_tokens.toLocaleString()} tokens\n` +
+          `   预算: ${this.budgetPerSession.toLocaleString()} tokens`
+        );
+      }
+    } catch (err) {
+      logger.debug(`[TokenTracker] Failed to check budget: ${err}`);
+    }
+  }
+
+  /**
+   * Get current usage for a session
+   */
+  getSessionUsage(session_id: string): {
+    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
+    budget: number;
+    usage_ratio: number;
+  } {
+    const usage = this.storage.getTokenUsageBySession(session_id);
+    return {
+      ...usage,
+      budget: this.budgetPerSession,
+      usage_ratio: usage.total_tokens / this.budgetPerSession,
+    };
+  }
+}

package/src/daemon/event-parser.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { ForgeEvent, ToolInputFields } from '../core/types.js';
+import { randomUUID } from 'crypto';
+
+const RawHookEventSchema = z.object({
+  hook_type: z.enum(['PreToolUse', 'PostToolUse', 'Notification', 'Stop', 'UserPromptSubmit']),
+  timestamp: z.string(),
+  session_id: z.string(),
+  project_path: z.string(),
+  tool_name: z.string().optional(),
+  tool_input: z.record(z.string(), z.unknown()).optional(),
+  tool_output: z.record(z.string(), z.unknown()).optional(),
+  user_prompt: z.string().optional(),
+  ai_response: z.string().optional(),
+  event_id: z.string().uuid().optional(),
+});
+
+export class EventParser {
+  parse(raw: string): ForgeEvent {
+    const json = JSON.parse(raw);
+    const validated = RawHookEventSchema.parse(json);
+
+    return {
+      event_id: validated.event_id ?? randomUUID(),
+      session_id: validated.session_id,
+      project_path: validated.project_path,
+      timestamp: validated.timestamp,
+      hook_type: validated.hook_type,
+      tool_name: validated.tool_name,
+      tool_input: validated.tool_input as ToolInputFields | undefined,
+      tool_output: validated.tool_output as Record<string, unknown> | undefined,
+      user_prompt: validated.user_prompt,
+      ai_response: validated.ai_response,
+    };
+  }
+}

package/src/daemon/handlers/history-exporter.ts

@@ -0,0 +1,117 @@
+/**
+ * HistoryExporter — exports session history to markdown
+ *
+ * Writes session history to .claude-forge/history/YYYY-MM-DD-{session}.md
+ * Adapted from src-old with simplified dependencies.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ForgeEvent } from '../../core/types.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { logger } from '../../core/utils/logger.js';
+import { truncateSessionId } from '../../core/utils/session.js';
+import { normalizeTimestamp } from '../../core/utils/time.js';
+
+export class HistoryExporter {
+  constructor(private storage: SQLiteStorage) {}
+
+  async export(event: ForgeEvent): Promise<void> {
+    const { session_id, project_path } = event;
+    if (!project_path) return;
+
+    try {
+      const historyDir = path.join(project_path, '.claude-forge', 'history');
+      if (!fs.existsSync(historyDir)) {
+        fs.mkdirSync(historyDir, { recursive: true });
+      }
+
+      const events = this.storage.queryEvents({
+        session_id,
+        project_path,
+      });
+      if (events.length === 0) return;
+
+      const now = new Date();
+      const dateStr = now.toISOString().slice(0, 10);
+      const shortSession = truncateSessionId(session_id);
+      const filePath = path.join(
+        historyDir,
+        `${dateStr}-${shortSession}.md`
+      );
+
+      const content = this.buildMarkdown(events, session_id, project_path);
+      fs.writeFileSync(filePath, content, 'utf-8');
+      logger.info(`[HistoryExporter] Wrote ${filePath}`);
+    } catch (err) {
+      logger.warn(`[HistoryExporter] Export failed: ${err}`);
+    }
+  }
+
+  private buildMarkdown(
+    events: ForgeEvent[],
+    sessionId: string,
+    projectPath: string
+  ): string {
+    const lines: string[] = [];
+    const startTime = normalizeTimestamp(events[0]?.timestamp ?? new Date().toISOString());
+    const endTime = normalizeTimestamp(events[events.length - 1]?.timestamp ?? startTime);
+
+    lines.push(`# 会话记录 ${truncateSessionId(sessionId)}`);
+    lines.push('');
+    lines.push(`- **时间**: ${startTime} → ${endTime}`);
+    lines.push(`- **项目**: ${projectPath}`);
+    lines.push(`- **事件数**: ${events.length}`);
+    lines.push('');
+
+    // User prompt summary
+    const prompts = events.filter(
+      (e) => e.hook_type === 'UserPromptSubmit' && e.user_prompt
+    );
+    if (prompts.length > 0) {
+      lines.push('## 用户指令');
+      lines.push('');
+      for (const p of prompts) {
+        const time = new Date(p.timestamp).toLocaleTimeString();
+        const text = (p.user_prompt as string).slice(0, 200);
+        lines.push(`- **${time}**: ${text}`);
+      }
+      lines.push('');
+    }
+
+    // Tool call timeline
+    const toolCalls = events.filter(
+      (e) => e.hook_type === 'PostToolUse' && e.tool_name
+    );
+    if (toolCalls.length > 0) {
+      lines.push('## 工具调用');
+      lines.push('');
+      const grouped = new Map<string, number>();
+      for (const t of toolCalls) {
+        grouped.set(t.tool_name!, (grouped.get(t.tool_name!) ?? 0) + 1);
+      }
+      for (const [tool, count] of grouped) {
+        lines.push(`- ${tool}: ${count} 次`);
+      }
+      lines.push('');
+
+      lines.push('### 时间线');
+      lines.push('');
+      for (const t of toolCalls.slice(-30)) {
+        const time = new Date(t.timestamp).toLocaleTimeString();
+        const input = t.tool_input;
+        const filePath = input?.file_path ?? input?.command ?? '';
+        const summary =
+          typeof filePath === 'string' ? filePath.slice(0, 80) : '';
+        lines.push(`- ${time} \`${t.tool_name}\` ${summary}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('---');
+    lines.push(`_生成时间: ${new Date().toISOString()}_`);
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}

package/src/daemon/handlers/post-tool-use.ts

@@ -0,0 +1,54 @@
+/**
+ * PostToolUseHandler — handles PostToolUse hook
+ *
+ * Simplified: only tracks token usage if available.
+ * Also observes Agent tool calls to update routing_events.
+ */
+
+import type { PostToolUseEvent, HookResult } from '../../core/types.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { logger } from '../../core/utils/logger.js';
+import { TokenTracker } from '../../core/utils/token-tracker.js';
+import { getSubagentType } from '../../core/event-fields.js';
+
+export class PostToolUseHandler {
+  private tokenTracker: TokenTracker | null = null;
+
+  constructor(
+    private storage: SQLiteStorage | null = null,
+  ) {
+    if (storage) {
+      this.tokenTracker = new TokenTracker(storage);
+    }
+  }
+
+  async handle(event: PostToolUseEvent): Promise<HookResult> {
+    // Observe Agent tool calls and update routing_events
+    if (this.storage && event.tool_name === 'Agent') {
+      try {
+        // PostToolUseEvent.tool_input is already a Record (narrowed by type guard).
+        const agentType = getSubagentType(event) ?? 'general-purpose';
+
+        // Find the most recent PENDING routing_event for this session
+        // (obeyed IS NULL). Filtering on pending prevents re-overwriting an
+        // already-completed event when 2+ Agents fire within the same prompt,
+        // or when an old obeyed=1 row leaks past a missed UserPromptSubmit.
+        const recentEvent = this.storage.getRecentPendingRoutingEvent(event.session_id);
+        if (recentEvent) {
+          this.storage.updateRoutingEvent(recentEvent.id, {
+            routed_to_type: 'agent',
+            routed_to_name: agentType,
+            obeyed: 1,
+            first_tool_name: 'Agent',
+            first_tool_ts: Date.now(),
+          });
+          logger.debug(`[PostToolUse] Updated routing_event ${recentEvent.id} with Agent: ${agentType}`);
+        }
+      } catch (err) {
+        logger.debug(`[PostToolUse] Failed to update routing_event: ${err}`);
+      }
+    }
+
+    return { allow: true };
+  }
+}

package/src/daemon/handlers/stop.ts

@@ -0,0 +1,208 @@
+/**
+ * StopHandler — handles Stop hook
+ *
+ * Responsibilities:
+ * 1. Mark current task complete
+ * 2. Save resume info
+ * 3. Export session history
+ * 4. Clear skill invocation guard
+ */
+
+import type { StopEvent, HookResult } from '../../core/types.js';
+import type { HistoryExporter } from './history-exporter.js';
+import type { ResumeManager } from '../../claudemd/resume-manager.js';
+import type { TaskSegmenter } from '../services/task-segmenter.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { InvocationGuard } from '../../skills/invocation-guard.js';
+import type { UserPromptHandler } from './user-prompt.js';
+import { logger } from '../../core/utils/logger.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { formatError, truncateString } from '../../core/utils/format.js';
+import { truncateSessionId } from '../../core/utils/session.js';
+
+const execFileAsync = promisify(execFile);
+
+export class StopHandler {
+  constructor(
+    private exporter: HistoryExporter,
+    private resume: ResumeManager | null = null,
+    private taskSegmenter: TaskSegmenter | null = null,
+    private storage: SQLiteStorage | null = null,
+    private invocationGuard: InvocationGuard | null = null,
+    private userPromptHandler: UserPromptHandler | null = null,
+  ) {}
+
+  async handle(event: StopEvent): Promise<HookResult> {
+    try {
+      // 1. Mark current task complete
+      if (this.taskSegmenter) {
+        try {
+          this.taskSegmenter.completeCurrentTask(event.session_id, event.timestamp);
+        } catch (err) {
+          logger.debug(`[Stop] task completion failed: ${formatError(err)}`);
+        }
+      }
+
+      // 2. Save resume info with behavior summary
+      if (this.resume) {
+        let resumeContent = this.resume.generate(event.session_id, event.project_path);
+        if (resumeContent) {
+          // Append behavior summary before saving
+          const behaviorSummary = this.generateBehaviorSummary(event.session_id);
+          if (behaviorSummary) {
+            resumeContent = this.appendBehaviorSummary(resumeContent, behaviorSummary);
+          }
+          this.resume.save(event.project_path, resumeContent);
+          logger.info(`[Stop] Resume saved for ${event.project_path}`);
+        }
+      }
+
+      // 3. Export history
+      logger.info(`[Stop] Exporting history for session ${event.session_id}`);
+      await this.exporter.export(event);
+
+      // 4. Clear skill invocation guard for this session
+      if (this.invocationGuard) {
+        try {
+          this.invocationGuard.clear(event.session_id);
+          logger.debug(`[Stop] InvocationGuard cleared for session ${truncateSessionId(event.session_id)}`);
+        } catch (err) {
+          logger.debug(`[Stop] InvocationGuard clear failed: ${formatError(err)}`);
+        }
+      }
+
+      // 5. Clear UserPromptHandler injection tracking for this session
+      if (this.userPromptHandler) {
+        try {
+          const sessionKey = `${event.session_id}:${event.project_path}`;
+          this.userPromptHandler.clearSession(sessionKey);
+          logger.debug(`[Stop] UserPromptHandler session cleared for ${truncateSessionId(event.session_id)}`);
+        } catch (err) {
+          logger.debug(`[Stop] UserPromptHandler clear failed: ${formatError(err)}`);
+        }
+      }
+
+      // 6. Write session_id to git note on HEAD commit (fire-and-forget, async)
+      // 不 await：git 操作不影响 handler 响应，失败已在内部 catch
+      void this.writeGitNote(event);
+
+      return { allow: true };
+    } catch (err) {
+      logger.warn(`[Stop] Handler failed: ${formatError(err)}`);
+      return { allow: true };
+    }
+  }
+
+  // ── Private: Git Note ──────────────────────────────────────────────────
+
+  /**
+   * Write session_id into a git note on the current HEAD commit.
+   * Uses `git notes append` so multiple sessions can be associated with one commit.
+   * Silently ignores failures (no git repo, no commits, etc.).
+   *
+   * 异步实现：3 个 git 调用有序依赖（rev-parse HEAD 依赖 work-tree 检查通过；
+   * notes append 依赖 HEAD hash），因此 rev-parse 串行；但整体 fire-and-forget，
+   * 不阻塞 handler 主响应。
+   */
+  private async writeGitNote(event: StopEvent): Promise<void> {
+    const projectPath = event.project_path;
+    if (!projectPath) return;
+
+    const opts = {
+      cwd: projectPath,
+      timeout: 5000,
+    };
+
+    try {
+      // Check if inside a git work tree
+      await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], opts);
+
+      // Get HEAD commit hash
+      const { stdout: headStdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], opts);
+      const head = headStdout.toString().trim();
+
+      if (!head) return;
+
+      // Append session_id to git note on HEAD
+      await execFileAsync(
+        'git',
+        ['notes', 'append', '-m', `forge-session: ${event.session_id}`, head],
+        opts,
+      );
+
+      logger.debug(
+        `[Stop] Git note appended: forge-session: ${truncateSessionId(event.session_id)} on ${truncateString(head, 8)}`,
+      );
+    } catch (err) {
+      logger.debug(`[Stop] Git note write skipped: ${formatError(err)}`);
+    }
+  }
+
+  // ── Private: Behavior Summary ──────────────────────────────────────────
+
+  /**
+   * Generate a brief behavior summary for the session by querying event stats.
+   */
+  private generateBehaviorSummary(sessionId: string): string | null {
+    if (!this.storage) return null;
+
+    try {
+      // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+
+      // 1. Tool usage stats
+      const toolStats = this.storage.aggregateToolUsageBySession(sessionId);
+      const totalToolCalls = toolStats.reduce((sum, row) => sum + row.count, 0);
+
+      // 2. Agent/Task delegation stats
+      const agentStats = this.storage.aggregateAgentTypeBySession(sessionId);
+      const totalAgentCalls = agentStats.reduce((sum, row) => sum + row.count, 0);
+      const agentNames = agentStats
+        .filter(row => row.agent_type)
+        .map(row => row.agent_type as string);
+
+      // 3. Skill invocation count
+      const skillCount = this.storage.countSkillInvocationsBySession(sessionId);
+
+      // Build summary
+      if (totalToolCalls === 0) return null;
+
+      const parts: string[] = [];
+      parts.push(`工具调用 ${totalToolCalls} 次`);
+
+      if (totalAgentCalls > 0) {
+        const agentDetail = agentNames.length > 0
+          ? ` (${agentNames.slice(0, 3).join(', ')})`
+          : '';
+        parts.push(`Agent 委托 ${totalAgentCalls} 次${agentDetail}`);
+      } else {
+        parts.push('Agent 委托 0 次');
+      }
+
+      parts.push(`Skill 调用 ${skillCount} 次`);
+
+      return `**会话行为**: ${parts.join(' | ')}`;
+    } catch (err) {
+      logger.debug(`[Stop] Behavior summary generation failed: ${formatError(err)}`);
+      return null;
+    }
+  }
+
+  /**
+   * Append behavior summary to resume content, inserting before the timestamp line.
+   */
+  private appendBehaviorSummary(resumeContent: string, summary: string): string {
+    // Insert before the final "_生成时间:" line
+    const timestampPattern = /\n_生成时间:/;
+    const match = resumeContent.match(timestampPattern);
+    if (match && match.index !== undefined) {
+      return (
+        resumeContent.slice(0, match.index) +
+        '\n' + summary + '\n' +
+        resumeContent.slice(match.index)
+      );
+    }
+    // Fallback: append at end
+    return resumeContent + '\n' + summary;
+  }
+}

package/src/daemon/handlers/user-prompt.ts

@@ -0,0 +1,178 @@
+/**
+ * UserPromptHandler — handles UserPromptSubmit hook
+ *
+ * Pipeline:
+ *   1. Inject one-shot context (resume, convention — first prompt of session)
+ *   2. Skill fallback (inject skill guidance if matched)
+ */
+
+import type { UserPromptSubmitEvent, HookResult } from '../../core/types.js';
+import type { ResumeManager } from '../../claudemd/resume-manager.js';
+import type { ConventionExtractor } from '../../claudemd/convention-extractor.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { SkillRegistry } from '../../skills/registry.js';
+import { logger } from '../../core/utils/logger.js';
+import { randomUUID } from 'node:crypto';
+import { truncateString } from '../../core/utils/format.js';
+import { LRUCache } from '../../core/utils/lru-cache.js';
+
+export class UserPromptHandler {
+  private static readonly MAX_INJECTION_KEYS = 1000;
+  // Two independent caches: resume vs convention have separate inject-once
+  // semantics, so we keep them as separate LRU instances rather than merging
+  // their key spaces. Both store sessionKey → injection timestamp.
+  private resumeInjected = new LRUCache<string, number>(UserPromptHandler.MAX_INJECTION_KEYS);
+  private conventionInjected = new LRUCache<string, number>(UserPromptHandler.MAX_INJECTION_KEYS);
+
+  constructor(
+    private resume: ResumeManager | null = null,
+    private conventionExtractor: ConventionExtractor | null = null,
+    private storage: SQLiteStorage | null = null,
+    private skillRegistry: SkillRegistry | null = null,
+  ) {}
+
+  async handle(event: UserPromptSubmitEvent): Promise<HookResult> {
+    // UserPromptSubmitEvent.user_prompt is guaranteed by isUserPromptSubmit guard.
+    const prompt = event.user_prompt;
+    if (!prompt) {
+      return { allow: true };
+    }
+
+    try {
+      const sessionKey = `${event.session_id}:${event.project_path}`;
+      const contextParts: string[] = [];
+      const systemParts: string[] = [];
+
+      // 1. Resume (once per session)
+      if (this.resume && !this.hasInjected(this.resumeInjected, sessionKey)) {
+        this.markInjected(this.resumeInjected, sessionKey);
+        const resumeContent = this.resume.load(event.project_path);
+        if (resumeContent) {
+          contextParts.push(
+            `━━━ Forge Context (Read First) ━━━\n${resumeContent}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+          );
+          logger.info('[UserPrompt] Injected resume context');
+          this.resume.clear(event.project_path);
+        }
+      }
+
+      // 2. Convention (once per session)
+      if (this.conventionExtractor && !this.hasInjected(this.conventionInjected, sessionKey)) {
+        this.markInjected(this.conventionInjected, sessionKey);
+        const convention = this.conventionExtractor.extract(event.project_path);
+        if (convention) {
+          contextParts.push(
+            `━━━ Project Guidance (Read First) ━━━\n${convention}\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+          );
+          logger.info('[UserPrompt] Injected project conventions');
+        }
+      }
+
+      // 3. Skill fallback: try skill matching
+      if (this.skillRegistry) {
+        try {
+          const skillMatchResult = await this.skillRegistry.matchWithConfidence(prompt, []);
+          if (skillMatchResult) {
+            const { skill, source } = skillMatchResult;
+            systemParts.push(formatSkillDirective(skill.name, skill.content));
+            logger.info(`[UserPrompt] Skill matched: ${skill.id} (${source})`);
+
+            // Record skill invocation to database
+            if (this.storage) {
+              try {
+                this.storage.writeSkillInvocation({
+                  id: randomUUID(),
+                  route_request_id: null,
+                  session_id: event.session_id,
+                  agent_id: null,
+                  skill_id: skill.id,
+                  invocation_type: 'dynamic',
+                  reason: `Auto-matched by ${source} matching`,
+                  workflow: null,
+                  phase: null,
+                  feature_slug: null,
+                  artifact_path: null,
+                  depth: 0,
+                  success: 1,
+                  error: null,
+                  timestamp: Date.now(),
+                });
+                logger.debug(`[UserPrompt] Recorded skill invocation: ${skill.id}`);
+              } catch (err) {
+                logger.warn(`[UserPrompt] Failed to record skill invocation: ${err}`);
+              }
+            }
+          } else {
+            logger.debug(`[UserPrompt] No skill matched for prompt: "${truncateString(prompt, 80)}"`);
+          }
+        } catch (err) {
+          logger.warn(`[UserPrompt] Skill matching failed: ${err}`);
+        }
+      }
+
+      const result: HookResult = { allow: true };
+      if (contextParts.length > 0) result.additionalContext = contextParts.join('\n\n');
+      if (systemParts.length > 0) result.systemMessage = systemParts.join('\n\n');
+
+      // Write routing_event for observation (Agent spawn tracking)
+      if (this.storage) {
+        try {
+          this.storage.writeRoutingEvent({
+            session_id: event.session_id,
+            project_path: event.project_path,
+            ts: Date.now(),
+            prompt: prompt.substring(0, 500),
+            intent_json: JSON.stringify({ type: 'user_prompt' }),
+            routed_to_type: null,
+            routed_to_name: null,
+            is_forced: 0,
+            obeyed: null,
+          });
+        } catch (err) {
+          logger.debug(`[UserPrompt] Failed to write routing_event: ${err}`);
+        }
+      }
+
+      return result;
+    } catch (err) {
+      logger.warn(`[UserPrompt] Handler failed: ${err}`);
+      return { allow: true };
+    }
+  }
+  // ── Private: Injection tracking helpers ────────────────────────────────
+
+  /** Check if a sessionKey has been injected in the given cache. */
+  private hasInjected(cache: LRUCache<string, number>, key: string): boolean {
+    return cache.has(key);
+  }
+
+  /**
+   * Mark a sessionKey as injected, recording the current timestamp.
+   * LRUCache transparently evicts the oldest entry when capacity is reached.
+   */
+  private markInjected(cache: LRUCache<string, number>, key: string): void {
+    cache.set(key, Date.now());
+  }
+
+  // ── Public: Session cleanup ──────────────────────────────────────────────
+
+  /**
+   * Remove injection tracking entries for a given sessionKey.
+   * Called by StopHandler to clean up after a session ends.
+   */
+  public clearSession(sessionKey: string): void {
+    this.resumeInjected.delete(sessionKey);
+    this.conventionInjected.delete(sessionKey);
+  }
+}
+
+/**
+ * Format skill injection directive.
+ */
+function formatSkillDirective(skillName: string, skillContent: string): string {
+  return [
+    `[SKILL: ${skillName}] [AUTO_MATCHED]`,
+    '',
+    skillContent,
+  ].join('\n');
+}