skyloom 1.13.5 → 1.13.7

package/src/core/agent/task.ts

@@ -1,100 +1,100 @@
-/**
- * Agent domain model — states and the Task DAG node.
- *
- * Extracted from the monolithic agent.ts (Phase 3). Pure, dependency-free,
- * and unit-testable in isolation. `agent.ts` re-exports these so external
- * importers of `../core/agent` are unaffected.
- */
-
-/** Lifecycle state of a running agent. */
-export enum AgentState {
-  IDLE = 'idle',
-  THINKING = 'thinking',
-  ACTING = 'acting',
-  WAITING = 'waiting',
-  ERROR = 'error',
-}
-
-/** Lifecycle state of an orchestrated task. */
-export enum TaskState {
-  PENDING = 'pending',
-  RUNNING = 'running',
-  COMPLETED = 'completed',
-  FAILED = 'failed',
-  SKIPPED = 'skipped',
-}
-
-/** Allowed task state transitions. A terminal state has no outgoing edges. */
-export const VALID_TRANSITIONS: Record<TaskState, Set<TaskState>> = {
-  [TaskState.PENDING]: new Set([TaskState.RUNNING, TaskState.SKIPPED, TaskState.FAILED]),
-  [TaskState.RUNNING]: new Set([TaskState.RUNNING, TaskState.COMPLETED, TaskState.FAILED]),
-  [TaskState.FAILED]: new Set([TaskState.RUNNING, TaskState.SKIPPED]),
-  [TaskState.COMPLETED]: new Set(),
-  [TaskState.SKIPPED]: new Set(),
-};
-
-/** A node in the orchestration DAG. */
-export class Task {
-  id: string;
-  description: string;
-  assignedTo: string | null = null;
-  parentId: string | null = null;
-  dependsOn: string[] = [];
-  status: TaskState = TaskState.PENDING;
-  priority: number = 0;
-  result: string | null = null;
-  metadata: Record<string, any> = {};
-
-  constructor(config: {
-    id: string;
-    description: string;
-    assignedTo?: string | null;
-    parentId?: string | null;
-    dependsOn?: string[];
-    status?: TaskState;
-    priority?: number;
-    result?: string | null;
-    metadata?: Record<string, any>;
-  }) {
-    this.id = config.id;
-    this.description = config.description;
-    this.assignedTo = config.assignedTo ?? null;
-    this.parentId = config.parentId ?? null;
-    this.dependsOn = config.dependsOn || [];
-    this.status = config.status ?? TaskState.PENDING;
-    this.priority = config.priority ?? 0;
-    this.result = config.result ?? null;
-    this.metadata = config.metadata || {};
-  }
-
-  transitionTo(newState: TaskState): void {
-    const allowed = VALID_TRANSITIONS[this.status] || new Set();
-    if (!allowed.has(newState)) {
-      throw new Error(
-        `Invalid task state transition: ${this.status} -> ${newState}`
-      );
-    }
-    this.status = newState;
-  }
-
-  get allDeps(): string[] {
-    const deps = [...this.dependsOn];
-    if (this.parentId && !deps.includes(this.parentId)) {
-      deps.push(this.parentId);
-    }
-    return deps;
-  }
-}
-
-/** Result of executing a single task. */
-export class TaskResult {
-  success: boolean;
-  content: string;
-  data: Record<string, any> = {};
-
-  constructor(success: boolean, content: string, data?: Record<string, any>) {
-    this.success = success;
-    this.content = content;
-    this.data = data || {};
-  }
-}
+/**
+ * Agent domain model — states and the Task DAG node.
+ *
+ * Extracted from the monolithic agent.ts (Phase 3). Pure, dependency-free,
+ * and unit-testable in isolation. `agent.ts` re-exports these so external
+ * importers of `../core/agent` are unaffected.
+ */
+
+/** Lifecycle state of a running agent. */
+export enum AgentState {
+  IDLE = 'idle',
+  THINKING = 'thinking',
+  ACTING = 'acting',
+  WAITING = 'waiting',
+  ERROR = 'error',
+}
+
+/** Lifecycle state of an orchestrated task. */
+export enum TaskState {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  SKIPPED = 'skipped',
+}
+
+/** Allowed task state transitions. A terminal state has no outgoing edges. */
+export const VALID_TRANSITIONS: Record<TaskState, Set<TaskState>> = {
+  [TaskState.PENDING]: new Set([TaskState.RUNNING, TaskState.SKIPPED, TaskState.FAILED]),
+  [TaskState.RUNNING]: new Set([TaskState.RUNNING, TaskState.COMPLETED, TaskState.FAILED]),
+  [TaskState.FAILED]: new Set([TaskState.RUNNING, TaskState.SKIPPED]),
+  [TaskState.COMPLETED]: new Set(),
+  [TaskState.SKIPPED]: new Set(),
+};
+
+/** A node in the orchestration DAG. */
+export class Task {
+  id: string;
+  description: string;
+  assignedTo: string | null = null;
+  parentId: string | null = null;
+  dependsOn: string[] = [];
+  status: TaskState = TaskState.PENDING;
+  priority: number = 0;
+  result: string | null = null;
+  metadata: Record<string, any> = {};
+
+  constructor(config: {
+    id: string;
+    description: string;
+    assignedTo?: string | null;
+    parentId?: string | null;
+    dependsOn?: string[];
+    status?: TaskState;
+    priority?: number;
+    result?: string | null;
+    metadata?: Record<string, any>;
+  }) {
+    this.id = config.id;
+    this.description = config.description;
+    this.assignedTo = config.assignedTo ?? null;
+    this.parentId = config.parentId ?? null;
+    this.dependsOn = config.dependsOn || [];
+    this.status = config.status ?? TaskState.PENDING;
+    this.priority = config.priority ?? 0;
+    this.result = config.result ?? null;
+    this.metadata = config.metadata || {};
+  }
+
+  transitionTo(newState: TaskState): void {
+    const allowed = VALID_TRANSITIONS[this.status] || new Set();
+    if (!allowed.has(newState)) {
+      throw new Error(
+        `Invalid task state transition: ${this.status} -> ${newState}`
+      );
+    }
+    this.status = newState;
+  }
+
+  get allDeps(): string[] {
+    const deps = [...this.dependsOn];
+    if (this.parentId && !deps.includes(this.parentId)) {
+      deps.push(this.parentId);
+    }
+    return deps;
+  }
+}
+
+/** Result of executing a single task. */
+export class TaskResult {
+  success: boolean;
+  content: string;
+  data: Record<string, any> = {};
+
+  constructor(success: boolean, content: string, data?: Record<string, any>) {
+    this.success = success;
+    this.content = content;
+    this.data = data || {};
+  }
+}

package/src/core/agent.ts

@@ -14,25 +14,41 @@ import { Skill, SkillRegistry } from './skill';
 import { type ToolDefinition, ToolRegistry } from './tool';
 import {
   parseToolArgs,
-  looksLikeFailedToolResult,
   extractFilePathsFromMessages,
   enrichResponseWithArtifacts,
-  toolCallSignature,
-  textSimilarity,
   formatArgsParseError,
   suggestToolNames,
   toolStatusLabel,
   synthesizeDelegationSummary,
   parseExtractedFacts,
-  SIG_WINDOW,
-  SIG_LOOP_HINT,
-  SIG_LOOP_HARDSTOP,
 } from './agent_helpers';
 import { selectRelevantTools } from './tool_router';
 import { getModelInfo } from './catalog';
+import { LoopGuard } from './agent/guard';
 
 const log = getLogger('agent');
 
+/** Tools whose success means the filesystem changed (triggers the verify loop). */
+const WRITE_TOOL_RE = /^(write_|edit_|delete_|create_)|^run_bash$|^git_commit$/;
+
+/** Tools with side effects, hidden from the model while in plan mode. */
+const SIDE_EFFECT_TOOL_RE = /^(write_|edit_|delete_|create_|kill_|launch_|service_|browser_)|^run_bash$|^git_commit$|^open_path$|^delegate_to$/;
+
+/** Default context budget per recorded tool result (chars; ~3k tokens). */
+const TOOL_RESULT_LIMIT = 12000;
+
+/**
+ * Clamp an oversized tool result before it enters the context window:
+ * keep head + tail, tell the model what was cut and how to fetch precisely.
+ */
+export function clampToolResult(s: string, limit: number = TOOL_RESULT_LIMIT): string {
+  if (s.length <= limit) return s;
+  const head = s.slice(0, Math.floor(limit * 0.72));
+  const tail = s.slice(-Math.floor(limit * 0.18));
+  const cut = s.length - head.length - tail.length;
+  return `${head}\n…[工具结果过长，中间省略 ${cut} 字符 — 需要该部分时用更精确的参数重新调用（read_file 的 offset/limit、grep 定位、缩小查询范围）]\n${tail}`;
+}
+
 // Domain model lives in ./agent/task — re-exported here so importers of
 // '../core/agent' are unaffected by the Phase 3 split.
 import { AgentState, TaskState, Task, TaskResult } from './agent/task';
@@ -70,6 +86,11 @@ export class BaseAgent {
   protected _pendingRequests: Map<string, { resolve: (value: string) => void; reject: (err: Error) => void }> = new Map();
   protected _bgTasks: Set<Promise<void>> = new Set();
   approvalCallback: ((toolName: string, args: Record<string, any>) => Promise<boolean>) | null = null;
+  /** Plan mode: read-only tool set + plan-first instructions on each turn. */
+  planMode: boolean = false;
+  /** Set when this turn executed a tool that mutates the filesystem (verify trigger). */
+  protected _turnWroteFiles: boolean = false;
+  private _hooks: import('./hooks').Hooks | null = null;
   protected _turnLock: Promise<void> = Promise.resolve();
   private _turnLockCounter: number = 0;
   private _turnLockResolve: (() => void) | null = null;
@@ -150,10 +171,10 @@ export class BaseAgent {
     const lang = (this.config as any).llm?.language || 'zh';
     if (lang === 'en') {
       return prompt +
-        `\n\n## Thinking Protocol\nBefore acting, briefly weigh: (1) **What** is the actual need? (2) **How** sure am I? If <80%, flag with [uncertain] and ask.\nIf stuck, admit it — propose a partial answer or ask the user. Never fabricate.\n\n## Behavior\n- Act, don't narrate. No "I will..." before tool calls.\n- Stay in scope. Do what's asked, then stop.\n- Batch independent tool calls in one response.\n- Verify writes: read back, report verified state.\n- Call list_skills when the task needs specialized capabilities.`;
+        `\n\n## Thinking Protocol\nBefore acting, briefly weigh: (1) **What** is the actual need? (2) **How** sure am I? If <80%, flag with [uncertain] and ask.\nIf stuck, admit it — propose a partial answer or ask the user. Never fabricate.\n\n## Behavior\n- Act, don't narrate. No "I will..." before tool calls.\n- Stay in scope. Do what's asked, then stop.\n- Batch independent tool calls in one response.\n- For tasks with 3+ steps, plan with todo_write first and update item status as you go.\n- Verify writes: read back, report verified state.\n- Call list_skills when the task needs specialized capabilities.`;
     }
     return prompt +
-      `\n\n## 思考协议\n行动前快速判断：(1) 用户真实需求是什么？(2) 我有多大把握？低于80%标注 [不确定] 并主动询问。\n卡住时承认，给出部分答案或请求用户指导。绝不编造。\n\n## 行为守则\n- 直接行动,不预告。不说「我将要...」,直接调用工具\n- 不擅自扩大范围。用户要什么做什么,核心完成即止\n- 独立的工具调用一次发出,并行执行\n- 写入后回读验证,汇报已验证状态而非仅尝试\n- 任务涉及专业能力时（PPT/Excel/PDF/网页设计/代码审查等），先调 list_skills 查看可用技能，再用 use_skill 激活`;
+      `\n\n## 思考协议\n行动前快速判断：(1) 用户真实需求是什么？(2) 我有多大把握？低于80%标注 [不确定] 并主动询问。\n卡住时承认，给出部分答案或请求用户指导。绝不编造。\n\n## 行为守则\n- 直接行动,不预告。不说「我将要...」,直接调用工具\n- 不擅自扩大范围。用户要什么做什么,核心完成即止\n- 独立的工具调用一次发出,并行执行\n- 3 步以上的任务先用 todo_write 列任务清单,开工/完成时逐项更新状态\n- 写入后回读验证,汇报已验证状态而非仅尝试\n- 任务涉及专业能力时（PPT/Excel/PDF/网页设计/代码审查等），先调 list_skills 查看可用技能，再用 use_skill 激活`;
   }
 
   protected injectProgrammingWisdom(prompt: string): string {
@@ -164,16 +185,34 @@ export class BaseAgent {
     return prompt + `\n\n## 工程能力\n顶级工程师:类型安全、真实的错误处理、按根因调试、按安全与性能审查。你可以阅读和修改 Skyloom 自身源码。`;
   }
 
+  /** Layered SKY.md / CLAUDE.md / AGENTS.md project memory (see core/skymd). */
+  protected injectProjectMemory(prompt: string): string {
+    try {
+      const { loadProjectMemory } = require('./skymd');
+      const mem = loadProjectMemory();
+      if (!mem.text) return prompt;
+      return prompt + `\n\n## 项目记忆 (SKY.md)\n用户与项目维护的约定，优先级高于你的通用习惯：\n\n${mem.text}`;
+    } catch {
+      return prompt;
+    }
+  }
+
   reinitLanguage(): void {
     this._baseSystemPrompt = '';
     this._baseSystemPrompt = this.resolveSystemPrompt();
     this._baseSystemPrompt = this.injectWorkspaceInfo(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectBehaviorRules(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProgrammingWisdom(this._baseSystemPrompt);
+    this._baseSystemPrompt = this.injectProjectMemory(this._baseSystemPrompt);
     this._baseSystemPrompt += '\n\n' + this.currentTimeTag();
     this.rebuildSystemPrompt();
   }
 
+  /** Re-read SKY.md layers into the system prompt (after `#` quick memory / edits). */
+  reloadProjectMemory(): void {
+    this.reinitLanguage();
+  }
+
   async init(): Promise<void> {
     if (this._baseSystemPrompt) return;
     await this.memory.initDb();
@@ -191,6 +230,7 @@ export class BaseAgent {
     this._baseSystemPrompt = this.injectWorkspaceInfo(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectBehaviorRules(this._baseSystemPrompt);
     this._baseSystemPrompt = this.injectProgrammingWisdom(this._baseSystemPrompt);
+    this._baseSystemPrompt = this.injectProjectMemory(this._baseSystemPrompt);
     this._baseSystemPrompt += '\n\n' + this.currentTimeTag();
     this.rebuildSystemPrompt();
     this._tools = this.toolRegistry.getTools();
@@ -217,6 +257,13 @@ export class BaseAgent {
       description: 'List all available skills with their names and descriptions. Use this first to discover what skills you can activate.',
       parameters: [],
       handler: async () => {
+        // live change detection: re-scan user/project skill folders so a
+        // SKILL.md edit or drop-in applies without restarting the session
+        try {
+          const { registerDynamicSkills } = require('../skills/loader');
+          registerDynamicSkills(self.skillRegistry);
+          self.loadSkills();
+        } catch { /* live reload is best-effort */ }
         const skills = self.getAvailableSkills();
         if (!skills.length) return 'No skills available.';
         const maxName = Math.max(...skills.map(s => s.name.length), 1);
@@ -558,9 +605,37 @@ export class BaseAgent {
         if (onStatus) onStatus(p.label);
         await this.setState(AgentState.ACTING);
 
+        // File checkpoint: snapshot the target before any mutating file tool
+        // runs, so /rewind can restore the pre-turn state.
+        try {
+          const { getFileCheckpoints } = require('./file_checkpoint');
+          const cp = getFileCheckpoints();
+          const snapPath = cp.pathToSnapshot(p.toolName, p.toolArgs || {});
+          if (snapPath) cp.snapshot(snapPath);
+        } catch { /* checkpointing must never block execution */ }
+
+        // pre_tool hooks are enforced policy: a non-zero exit blocks the call.
+        const hooks = this.getHooks();
+        if (hooks.preTool.length > 0) {
+          try {
+            const { runPreToolHooks } = require('./hooks');
+            const pre = runPreToolHooks(hooks, p.toolName, p.toolArgs || {}, this.name);
+            if (!pre.allowed) {
+              return { idx, result: { tc: p.tc, result: `[blocked by pre_tool hook] ${pre.reason}`, success: false, toolName: p.toolName } };
+            }
+          } catch { /* hook machinery must never break tool execution */ }
+        }
+
         try {
           const toolResult = await this.toolRegistry.execute(p.toolName, p.toolArgs || {});
           const resultStr = toolResult.result || toolResult.error || '(no output)';
+          if (toolResult.success && WRITE_TOOL_RE.test(p.toolName)) this._turnWroteFiles = true;
+          if (hooks.postTool.length > 0) {
+            try {
+              const { runPostToolHooks } = require('./hooks');
+              runPostToolHooks(hooks, p.toolName, p.toolArgs || {}, this.name);
+            } catch { /* best-effort */ }
+          }
           return { idx, result: { tc: p.tc, result: resultStr, success: toolResult.success, toolName: p.toolName } };
         } catch (e) {
           return { idx, result: { tc: p.tc, result: `Tool '${p.toolName}' execution failed: ${e}`, success: false, toolName: p.toolName } };
@@ -583,7 +658,9 @@ export class BaseAgent {
       }
     }
 
-    // Phase D: Record results to memory
+    // Phase D: Record results to memory (clamped — one runaway read_file or
+    // http_get must not flood the context window)
+    const resultLimit = Number((this.config as any)?.llm?.tool_result_limit) || undefined;
     for (const r of results) {
       if (!r) continue;
 
@@ -591,7 +668,7 @@ export class BaseAgent {
         if (suppressed) suppressed.add(r.toolName);
       }
 
-      this.memory.addMessage('tool', r.result, {
+      this.memory.addMessage('tool', clampToolResult(r.result, resultLimit), {
         name: r.toolName,
         toolCallId: r.tc.id,
         ephemeral,
@@ -731,7 +808,15 @@ export class BaseAgent {
     signal?: AbortSignal
   ): AsyncGenerator<Record<string, any>> {
     await this.setState(AgentState.THINKING);
-    this.memory.addMessage('user', message);
+    // Plan mode: the tag travels with the message so the model plans instead
+    // of acting, and the read-only tool filter below removes the temptation.
+    const userMessage = this.planMode
+      ? `[计划模式] 只读调研，不要执行任何修改。请输出一份编号的执行计划（涉及哪些文件、每步做什么、风险点），等待用户批准后再实施。\n\n${message}`
+      : message;
+    this.memory.addMessage('user', userMessage);
+    try {
+      require('./file_checkpoint').getFileCheckpoints().beginTurn(message);
+    } catch { /* optional */ }
     let assistantStored = false;
 
     if (this.shouldAutoCompact()) {
@@ -749,20 +834,22 @@ export class BaseAgent {
       );
     }
 
-    const recentToolOutcomes: boolean[] = [];
-    let stuckHintInjected = false;
-    const recentResponseTexts: string[] = [];
-    let repetitionHintInjected = false;
-    const recentToolSigs: string[] = [];
-    let toolLoopHintInjected = false;
+    const guard = new LoopGuard();
 
     let toolNamesCache: string[] | null = null;
     let cacheKey: string | null = null;
 
     const resolveToolNames = (): string[] => {
-      const key = JSON.stringify([[...suppressedTools].sort(), [...this._activeSkills].sort()]);
+      const key = JSON.stringify([[...suppressedTools].sort(), [...this._activeSkills].sort(), this.planMode]);
       if (toolNamesCache !== null && cacheKey === key) return toolNamesCache;
       let candidates = this.activeToolNames().filter(t => !suppressedTools.has(t));
+      if (this.planMode) {
+        candidates = candidates.filter(n => {
+          if (SIDE_EFFECT_TOOL_RE.test(n)) return false;
+          const t = this.toolRegistry.get(n);
+          return !(t as any)?.dangerous;
+        });
+      }
       const must = new Set<string>();
       for (const s of this._skills) {
         if (this._activeSkills.has(s.name)) {
@@ -914,82 +1001,12 @@ export class BaseAgent {
           return;
         }
 
-        // ── Narration-loop detection ──
-        const normalizedRound = roundContent.trim();
-        if (normalizedRound && recentResponseTexts.length > 0) {
-          const highSim = recentResponseTexts.slice(-2).some(prev => textSimilarity(normalizedRound, prev) >= 0.7);
-          if (highSim && !repetitionHintInjected) {
-            this.memory.addMessage('system', '[Stop narrating] Your last response is highly similar to your previous one. Stop writing prose. Either: (1) emit ONLY the next tool call, or (2) output the final deliverable.');
-            repetitionHintInjected = true;
-          }
-        }
-        recentResponseTexts.push(normalizedRound);
-        if (recentResponseTexts.length > 3) recentResponseTexts.shift();
-
-        // ── Tool-signature loop detection ──
-        for (const tc of toolCallsReceived) {
-          const tName = tc.function.name;
-          if (['task_done', 'list_skills', 'use_skill'].includes(tName)) continue;
-          const rawArgs = tc.function.arguments;
-          const tArgs = typeof rawArgs === 'string' ? parseToolArgs(rawArgs) : rawArgs;
-          const sig = toolCallSignature(tName, tArgs);
-          if (sig) recentToolSigs.push(sig);
-        }
-        if (recentToolSigs.length > SIG_WINDOW) {
-          recentToolSigs.splice(0, recentToolSigs.length - SIG_WINDOW);
-        }
-        if (recentToolSigs.length > 0) {
-          const counts = new Map<string, number>();
-          for (const s of recentToolSigs) counts.set(s, (counts.get(s) || 0) + 1);
-          let topSig = '';
-          let topCount = 0;
-          for (const [s, c] of counts) { if (c > topCount) { topSig = s; topCount = c; } }
-          if (topCount >= SIG_LOOP_HINT && !toolLoopHintInjected) {
-            this.memory.addMessage('system', `[Tool loop] You have called \`${topSig}\` ${topCount}x in the last ${recentToolSigs.length} tool calls — you are iterating without converging. STOP repeating it.`);
-            toolLoopHintInjected = true;
-          }
-          if (topCount >= SIG_LOOP_HARDSTOP) {
-            this.memory.addMessage('assistant', `I have repeated \`${topSig}\` ${topCount} times without converging. Stopping.`);
-            yield { type: 'content', text: `\n\n[stuck] tool \`${topSig}\` repeated ${topCount}x — stopping.` };
-            await this.setState(AgentState.IDLE);
-            yield { type: 'done' };
-            return;
-          }
-        }
-
-        // ── Stuck-loop detection ──
-        for (const r of execResults) {
-          if (!r || r.toolName === 'task_done') continue;
-          const failed = !r.success || (typeof r.result === 'string' && looksLikeFailedToolResult(r.result));
-          recentToolOutcomes.push(!failed);
-          if (recentToolOutcomes.length > 6) recentToolOutcomes.shift();
-        }
-
-        if (!stuckHintInjected && recentToolOutcomes.length >= 5 &&
-            recentToolOutcomes.filter(Boolean).length <= 1) {
-          this.memory.addMessage('system', '[Recovery hint] Your last several tool calls have mostly failed. Synthesize a partial answer from what worked or ask the user for guidance.');
-          stuckHintInjected = true;
-        }
-
-        if (recentToolOutcomes.length >= 8 && recentToolOutcomes.every(x => !x)) {
-          this.memory.addMessage('assistant', 'Every recent tool call failed. Please give me more context.');
-          yield { type: 'content', text: '\n\n[stuck] every recent tool call failed — stopping.\n' };
-          await this.setState(AgentState.IDLE);
-          yield { type: 'done' };
-          return;
-        }
-
-        // ── Search-storm detection ──
-        const searchStormCount = recentToolSigs.filter(s =>
-          s.startsWith('web_search:') || ['fetch_page', 'http_get'].includes(s)
-        ).length;
-        if (searchStormCount >= 8 && !toolLoopHintInjected) {
-          this.memory.addMessage('system', `[Search storm] ${searchStormCount} search calls. STOP searching and synthesize.`);
-          toolLoopHintInjected = true;
-        }
-        if (searchStormCount >= 12) {
-          this.memory.addMessage('assistant', 'Too many search requests. Synthesizing best answer.');
-          yield { type: 'content', text: `\n\n[stuck] excessive web searching (${searchStormCount} calls) — stopping.\n` };
+        // ── Anti-loop guard (narration / tool-signature / stuck / search-storm) ──
+        const decision = guard.observe(roundContent, toolCallsReceived, execResults);
+        for (const hint of decision.hints) this.memory.addMessage('system', hint);
+        if (decision.stop) {
+          this.memory.addMessage('assistant', decision.stop.note);
+          yield { type: 'content', text: decision.stop.contentLine };
           await this.setState(AgentState.IDLE);
           yield { type: 'done' };
           return;
@@ -1109,6 +1126,25 @@ export class BaseAgent {
     };
   }
 
+  /** Per-role token breakdown for the /context command. */
+  contextDetail(): Record<string, any> {
+    const byRole: Record<string, { tokens: number; count: number }> = {};
+    for (const m of this.memory.shortTerm) {
+      const extra = (m as any).toolCalls ? JSON.stringify((m as any).toolCalls).length : 0;
+      const tokens = Math.ceil(((m.content || '').length + extra) / 4);
+      const slot = byRole[m.role] || (byRole[m.role] = { tokens: 0, count: 0 });
+      slot.tokens += tokens;
+      slot.count += 1;
+    }
+    return {
+      ...this.contextUsage(),
+      byRole,
+      systemPromptTokens: Math.ceil(this._baseSystemPrompt.length / 4),
+      toolCount: this.activeToolNames().length,
+      activeSkills: [...this._activeSkills],
+    };
+  }
+
   protected shouldAutoCompact(): boolean {
     const usage = this.memory.getContextWindowUsage();
     // Compact before hitting the real window — leave ~20% headroom for the reply.
@@ -1339,9 +1375,43 @@ export class BaseAgent {
 
     this.memory.addMessage('user', prompt);
     const preLen = this.memory.shortTerm.length;
+    this._turnWroteFiles = false;
+    try {
+      require('./file_checkpoint').getFileCheckpoints().beginTurn(`[task] ${task.description}`);
+    } catch { /* optional */ }
 
     try {
-      const response = await this.llmLoop({ onStatus, ephemeral: true });
+      let response = await this.llmLoop({ onStatus, ephemeral: true });
+
+      // ── 验证闭环: if this task touched the filesystem and verify commands
+      // are configured (config.verify or SKY.md "## Verify"), run them and
+      // feed failures back for a bounded number of fix rounds. ──
+      try {
+        const { resolveVerifyConfig, runVerify } = require('./verify');
+        const vc = resolveVerifyConfig(this.config);
+        if (vc.commands.length > 0 && this._turnWroteFiles) {
+          for (let round = 0; round <= vc.maxFixRounds; round++) {
+            if (onStatus) onStatus(`verify: ${vc.commands.length} 条命令`);
+            const vr = runVerify(vc);
+            if (vr.ok) {
+              response.content += `\n\n[verify ✓ 全部通过]\n${vr.report}`;
+              break;
+            }
+            if (round === vc.maxFixRounds) {
+              response.content += `\n\n[verify ✗ 经 ${vc.maxFixRounds} 轮修复仍未通过]\n${vr.report.slice(0, 1500)}`;
+              break;
+            }
+            if (onStatus) onStatus(`verify 失败 — 修复第 ${round + 1}/${vc.maxFixRounds} 轮`);
+            log.warn('verify_failed_fixing', { agent: this.name, round: round + 1 });
+            this.memory.addMessage('user',
+              `[自动验证失败] 以下验证命令未通过。请定位根因并修复，确保它们全部通过：\n\n${vr.report}`);
+            response = await this.llmLoop({ onStatus, ephemeral: true });
+          }
+        }
+      } catch (e) {
+        log.warn('verify_loop_error', { error: String(e) });
+      }
+
       const filePaths = extractFilePathsFromMessages(this.memory.shortTerm.slice(preLen));
       const enriched = enrichResponseWithArtifacts(response.content, filePaths);
       this.memory.addMessage('assistant', enriched, { toolCalls: response.toolCalls, reasoningContent: response.reasoningContent });
@@ -1365,6 +1435,18 @@ export class BaseAgent {
   private _security: any = null;
   get security(): any { if (!this._security) { try { const { getSecurity } = require('./security'); this._security = getSecurity(); } catch { this._security = {}; } } return this._security; }
 
+  protected getHooks(): import('./hooks').Hooks {
+    if (!this._hooks) {
+      try {
+        const { loadHooks } = require('./hooks');
+        this._hooks = loadHooks(this.config);
+      } catch {
+        this._hooks = { sessionStart: [], preTool: [], postTool: [] };
+      }
+    }
+    return this._hooks!;
+  }
+
   protected async checkToolApproval(toolName: string, toolArgs: Record<string, any>): Promise<boolean> {
     try {
       const sec = this.security;