autosnippet 3.2.1 → 3.2.3

package/lib/external/mcp/McpServer.js

@@ -4,7 +4,7 @@
  * Model Context Protocol (stdio transport)
  * 提供给 IDE AI Agent (Cursor/VSCode Copilot) 的工具集
  *
- * V3.1 整合：39 → 20 工具（16 agent + 4 admin）
+ * V3.1 整合：39 → 22 工具（18 agent + 4 admin）
  * 通过 ASD_MCP_TIER 环境变量控制可见工具集（agent/admin）
  *
  * 冷启动双路径:
@@ -38,7 +38,11 @@ import * as systemHandlers from './handlers/system.js';
 // ─── External Agent Bootstrap 新 handler ──────────────────────
 
 import { bootstrapExternal } from './handlers/bootstrap-external.js';
-import { dimensionComplete } from './handlers/dimension-complete-external.js';import { taskHandler } from './handlers/task.js';import { wikiFinalize, wikiPlan } from './handlers/wiki-external.js';
+import { decideHandler } from './handlers/decide.js';
+import { dimensionComplete } from './handlers/dimension-complete-external.js';
+import { readyHandler } from './handlers/ready.js';
+import { taskHandler } from './handlers/task.js';
+import { wikiFinalize, wikiPlan } from './handlers/wiki-external.js';
 
 // ─── McpServer 类 ─────────────────────────────────────────────
 
@@ -49,11 +53,34 @@ export class McpServer {
     this.bootstrap = options.bootstrap || null;
     this.server = null;
     this._startedAt = Date.now();
+
+    // ── P0: Decision 注入缓存 ──
+    this._decisionCache = {
+      decisions: [], // [{ id, title }]
+      fetchedAt: 0, // timestamp ms
+      ttl: 60_000, // 60s TTL
+      _pending: null, // 防并发重复查询的 pending promise
+    };
+
+    // ── P3: Session 管理 ──
+    this._session = {
+      id: `ses-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+      startedAt: Date.now(),
+      readyCalled: false,
+      toolCallCount: 0,
+      toolsUsed: new Set(),
+      lastActivityAt: Date.now(),
+    };
   }
 
   /** 共享上下文对象，传给所有 handler */
   get _ctx() {
-    return { container: this.container, logger: this.logger, startedAt: this._startedAt };
+    return {
+      container: this.container,
+      logger: this.logger,
+      startedAt: this._startedAt,
+      session: this._session,
+    };
   }
 
   async initialize() {
@@ -160,6 +187,9 @@ export class McpServer {
     const wrapped = wrapHandler(name, handler);
     const result = await wrapped(ctx, args);
 
+    // ── P0+P3: Decision 注入 + Session 追踪 ──
+    await this._injectDecisions(name, result);
+
     // ── 首次成功 tool call → 标记 autoApprove（one-shot） ──
     // 用户已手动授权了至少一个工具，标记后下次 MCP 启动注入 autoApprove
     if (!this._autoApproveMarked) {
@@ -167,19 +197,159 @@ export class McpServer {
       try {
         const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
         markAutoApproveNeeded(projectRoot, this.logger);
-      } catch { /* non-blocking */ }
+      } catch {
+        /* non-blocking */
+      }
+    }
+
+    return result;
+  }
+
+  // ─── P0: Decision 自动注入 ────────────────────────────
+
+  /**
+   * 在工具返回结果中注入 decisions 摘要 + 更新 session 统计
+   *
+   * 策略：
+   *   - ready: 刷新缓存，不额外注入（response 本身含 decisions）
+   *   - decide 写操作: invalidate 缓存（下次查询拉最新）
+   *   - 其他工具: 注入 _activeDecisions 摘要
+   *   - 首次未调 ready 的工具: 注入更强提醒
+   *
+   * @param {string} toolName
+   * @param {object} result — handler 返回的 envelope 对象
+   */
+  async _injectDecisions(toolName, result) {
+    // ── P3: Session 统计 ──
+    this._session.toolCallCount++;
+    this._session.toolsUsed.add(toolName);
+    this._session.lastActivityAt = Date.now();
+
+    // 1) ready 工具：刷新缓存 + 标记 session
+    if (toolName === 'autosnippet_ready') {
+      this._session.readyCalled = true;
+      this._refreshCacheFromReady(result);
+      return result;
+    }
+
+    // 2) decide 写操作：invalidate 缓存（record/revise/unpin 改变了 decisions）
+    if (toolName === 'autosnippet_decide') {
+      this._decisionCache.fetchedAt = 0;
+      this._decisionCache._pending = null;
+      return result;
+    }
+
+    // 3) autosnippet_task 也不注入（task 操作返回值已足够，避免 token 膨胀）
+    if (toolName === 'autosnippet_task') {
+      return result;
+    }
+
+    // 4) 对非 ready/decide 工具：注入 decisions 摘要
+    const decisions = await this._getDecisionsSummary();
+    if (decisions.length > 0 && typeof result === 'object' && result !== null) {
+      result._activeDecisions = decisions;
+
+      // P3: 如果 ready 从未被调用，注入更强提醒
+      if (!this._session.readyCalled) {
+        result._decisionReminder =
+          '⚠️ You have NOT called autosnippet_ready() yet this session. ' +
+          'These decisions may affect your work. Call autosnippet_ready() for full context.';
+      } else {
+        result._decisionReminder =
+          'Respect these team decisions. Call autosnippet_decide({ operation: "list" }) for full details.';
+      }
     }
 
     return result;
   }
 
+  /**
+   * 获取 decisions 摘要（带缓存 + 防并发）
+   * @private
+   * @returns {Promise<Array<{id: string, title: string}>>}
+   */
+  async _getDecisionsSummary() {
+    const cache = this._decisionCache;
+    const now = Date.now();
+
+    // 缓存有效（包括缓存了"空 decisions"的情况），直接返回
+    if (cache.fetchedAt > 0 && now - cache.fetchedAt < cache.ttl) {
+      return cache.decisions;
+    }
+
+    // 防并发：如果有正在进行的查询，等它完成
+    if (cache._pending) {
+      try {
+        return await cache._pending;
+      } catch {
+        return cache.decisions; // 降级返回旧缓存
+      }
+    }
+
+    // 发起新查询
+    cache._pending = this._fetchDecisionsSummary();
+    try {
+      const result = await cache._pending;
+      return result;
+    } finally {
+      cache._pending = null;
+    }
+  }
+
+  /**
+   * 从 DB 查询 decisions 摘要（仅 id + title）
+   * @private
+   */
+  async _fetchDecisionsSummary() {
+    const cache = this._decisionCache;
+    try {
+      const taskService = this.container?.get('taskGraphService');
+      if (!taskService) {
+        return cache.decisions;
+      }
+
+      // 使用 service 公共 API（不直接访问 repo）
+      const pinned = await taskService.list(
+        { status: 'pinned', taskType: 'decision' },
+        { limit: 50 }
+      );
+      cache.decisions = pinned.map((d) => ({
+        id: d.id,
+        title: d.title,
+      }));
+      cache.fetchedAt = Date.now();
+    } catch (err) {
+      // 查询失败不阻塞，保留旧缓存
+      this.logger.debug('_fetchDecisionsSummary error', { error: err.message });
+    }
+    return cache.decisions;
+  }
+
+  /**
+   * 从 ready 响应结果中刷新缓存（避免额外 DB 查询）
+   * @private
+   */
+  _refreshCacheFromReady(readyResult) {
+    try {
+      // readyResult 是 envelope({ data: { decisions: [...] } })
+      const decisions = readyResult?.data?.decisions || [];
+      this._decisionCache.decisions = decisions.map((d) => ({
+        id: d.id,
+        title: d.title,
+      }));
+      this._decisionCache.fetchedAt = Date.now();
+    } catch {
+      /* ignore */
+    }
+  }
+
   /**
    * 解析工具名到 handler 函数（V3 整合版）
    * @private
    */
   _resolveHandler(name) {
     const HANDLER_MAP = {
-      // ── Agent 层 (16) ──
+      // ── Agent 层 (18) ──
       autosnippet_health: (ctx) => systemHandlers.health(ctx),
       autosnippet_capabilities: () => systemHandlers.capabilities(),
       autosnippet_search: (ctx, args) => consolidated.consolidatedSearch(ctx, args),
@@ -192,6 +362,8 @@ export class McpServer {
         knowledgeHandlers.submitKnowledgeBatch(ctx, args),
       autosnippet_save_document: (ctx, args) => knowledgeHandlers.saveDocument(ctx, args),
       autosnippet_skill: (ctx, args) => consolidated.consolidatedSkill(ctx, args),
+      autosnippet_ready: (ctx, args) => readyHandler(ctx, args),
+      autosnippet_decide: (ctx, args) => decideHandler(ctx, args),
       autosnippet_task: (ctx, args) => taskHandler(ctx, args),
       // ── External Agent Bootstrap (v3.1) ──
       autosnippet_bootstrap: (ctx, _args) => bootstrapExternal(ctx),
@@ -270,7 +442,9 @@ export class McpServer {
     const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
     try {
       applyPendingAutoApprove(projectRoot, this.logger);
-    } catch { /* non-blocking */ }
+    } catch {
+      /* non-blocking */
+    }
 
     const transport = new StdioServerTransport();
     await this.server.connect(transport);

package/lib/external/mcp/handlers/bootstrap/shared/bootstrap-phases.js

@@ -542,7 +542,8 @@ export async function runAllPhases(projectRoot, ctx, options = {}) {
   // ── Phase 1: 文件收集 ──
   const p1Start = Date.now();
   const phase1 = await runPhase1_FileCollection(projectRoot, ctx.logger, options);
-  const { allFiles, allTargets, discoverer, langStats } = phase1;
+  let { allFiles, allTargets, discoverer, langStats } = phase1;
+
   if (report) report.phases.fileCollection = { fileCount: allFiles.length, targetCount: allTargets.length, ms: Date.now() - p1Start };
 
   if (allFiles.length === 0) {

package/lib/external/mcp/handlers/decide.js

@@ -0,0 +1,109 @@
+/**
+ * MCP Handler — autosnippet_decide
+ *
+ * 决策管理独立入口。Agent 与用户达成共识时调用。
+ * 操作：record / revise / unpin / list
+ */
+
+import { envelope } from '../envelope.js';
+
+/**
+ * @param {object} ctx — { container }
+ * @param {object} args — { operation, title, description, rationale, tags, relatedTaskId, id, reason }
+ */
+export async function decideHandler(ctx, args) {
+  const taskService = ctx.container.get('taskGraphService');
+  const op = args.operation || 'list';
+
+  switch (op) {
+    case 'record':
+      return _record(taskService, args);
+    case 'revise':
+      return _revise(taskService, args);
+    case 'unpin':
+      return _unpin(taskService, args);
+    case 'list':
+      return _list(taskService);
+    default:
+      return envelope({
+        success: false,
+        message: `Unknown decide operation: ${op}. Use: record, revise, unpin, list`,
+        meta: { tool: 'autosnippet_decide' },
+      });
+  }
+}
+
+async function _record(svc, args) {
+  if (!args.title) {
+    return envelope({ success: false, message: 'title is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  if (!args.description) {
+    return envelope({ success: false, message: 'description is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  const { task, isDuplicate } = await svc.recordDecision({
+    title: args.title,
+    description: args.description,
+    rationale: args.rationale || '',
+    tags: args.tags || [],
+    relatedTaskId: args.relatedTaskId || null,
+  });
+  return envelope({
+    success: true,
+    data: task.toJSON(),
+    message: isDuplicate
+      ? `⚠ Decision already recorded: ${task.id}`
+      : `✅ Decision pinned: ${task.id} — "${args.title}"`,
+    meta: { tool: 'autosnippet_decide' },
+  });
+}
+
+async function _revise(svc, args) {
+  if (!args.id) {
+    return envelope({ success: false, message: 'id of old decision is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  if (!args.title) {
+    return envelope({ success: false, message: 'title of new decision is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  if (!args.description) {
+    return envelope({ success: false, message: 'description of new decision is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  const result = await svc.reviseDecision({
+    oldDecisionId: args.id,
+    title: args.title,
+    description: args.description,
+    rationale: args.rationale || '',
+    reason: args.reason || '',
+  });
+  return envelope({
+    success: true,
+    data: {
+      newDecision: result.newDecision.toJSON(),
+      superseded: result.oldDecisionId,
+    },
+    message: `✅ Decision revised: ${result.oldDecisionId} → ${result.newDecision.id}`,
+    meta: { tool: 'autosnippet_decide' },
+  });
+}
+
+async function _unpin(svc, args) {
+  if (!args.id) {
+    return envelope({ success: false, message: 'id is required', meta: { tool: 'autosnippet_decide' } });
+  }
+  const task = await svc.unpinDecision(args.id, args.reason || '');
+  return envelope({
+    success: true,
+    data: task.toJSON(),
+    message: `Decision ${args.id} unpinned and closed`,
+    meta: { tool: 'autosnippet_decide' },
+  });
+}
+
+async function _list(svc) {
+  const decisions = await svc.list({ status: 'pinned', taskType: 'decision' }, { limit: 50 });
+  return envelope({
+    success: true,
+    data: decisions.map(d => d.toJSON()),
+    message: `${decisions.length} active decision(s)`,
+    meta: { tool: 'autosnippet_decide' },
+  });
+}

package/lib/external/mcp/handlers/ready.js

@@ -0,0 +1,42 @@
+/**
+ * MCP Handler — autosnippet_ready
+ *
+ * Agent 的首要入口：加载项目上下文 + 就绪任务 + 团队决策。
+ * 等同于 Beads 的 `bd ready`，但含知识桥接和决策持久化。
+ *
+ * 无参数即可调用。Agent 看到工具名就知道"先看看有什么可做的"。
+ */
+
+import { envelope } from '../envelope.js';
+
+/**
+ * @param {object} ctx — { container }
+ * @param {object} args — { limit?, withKnowledge? }
+ */
+export async function readyHandler(ctx, args = {}) {
+  const taskService = ctx.container.get('taskGraphService');
+  const result = await taskService.prime({
+    limit: args.limit || 10,
+    withKnowledge: args.withKnowledge !== false,
+  });
+
+  const decisionCount = (result.decisions || []).length;
+  const staleCount = (result.staleDecisions || []).length;
+  const decisionTitles = (result.decisions || []).map((d) => d.title).join('; ');
+  const statsLine = `${result.inProgress.length} in-progress, ${result.ready.length} ready, ${result.stats.total} total`;
+
+  let message;
+  if (decisionCount > 0) {
+    const stalePart = staleCount > 0 ? ` ${staleCount} stale.` : '';
+    message = `⚠️ ${decisionCount} ACTIVE DECISION(S): [${decisionTitles}].${stalePart} ${statsLine}.`;
+  } else {
+    message = `${statsLine}.`;
+  }
+
+  return envelope({
+    success: true,
+    data: result,
+    message,
+    meta: { tool: 'autosnippet_ready' },
+  });
+}

package/lib/external/mcp/handlers/system.js

@@ -133,6 +133,18 @@ export async function health(ctx) {
       checks,
       services: ctx.container.getServiceNames(),
       knowledgeBase,
+      // P3: Session 信息
+      ...(ctx.session
+        ? {
+            session: {
+              id: ctx.session.id,
+              readyCalled: ctx.session.readyCalled,
+              toolCallCount: ctx.session.toolCallCount,
+              toolsUsed: Array.from(ctx.session.toolsUsed),
+              durationMs: Date.now() - ctx.session.startedAt,
+            },
+          }
+        : {}),
       ...(issues.length ? { issues } : {}),
       ...(actionHints.length ? { actionHints } : {}),
     },

package/lib/external/mcp/handlers/task.js

@@ -1,9 +1,11 @@
 /**
- * MCP Handler — TaskGraph 任务管理
+ * MCP Handler — autosnippet_task (Task CRUD)
  *
- * 操作路由：
- *   create / decompose / claim / close / fail / defer / progress
- *   ready / prime / show / list / blocked / dep_add / dep_tree / stats
+ * Operations: create / decompose / claim / close / fail / defer / progress
+ *             ready / show / list / blocked / dep_add / dep_tree / stats
+ *
+ * Session entry point → autosnippet_ready
+ * Decision management → autosnippet_decide
  */
 
 import { envelope } from '../envelope.js';
@@ -31,8 +33,6 @@ export async function taskHandler(ctx, args) {
       return _defer(taskService, args);
     case 'progress':
       return _progress(taskService, args);
-    case 'prime':
-      return _prime(taskService);
     case 'decompose':
       return _decompose(taskService, args);
     case 'show':
@@ -50,7 +50,7 @@ export async function taskHandler(ctx, args) {
     default:
       return envelope({
         success: false,
-        message: `Unknown operation: ${args.operation}`,
+        message: `Unknown operation: ${args.operation}. Use autosnippet_ready for session context, autosnippet_decide for decisions.`,
         meta: { tool: 'autosnippet_task' },
       });
   }
@@ -175,18 +175,6 @@ async function _progress(svc, args) {
   });
 }
 
-// ── prime — 会话恢复 ──
-
-async function _prime(svc) {
-  const result = await svc.prime({ withKnowledge: true });
-  return envelope({
-    success: true,
-    data: result,
-    message: `${result.inProgress.length} in-progress, ${result.ready.length} ready, ${result.stats.total} total`,
-    meta: { tool: 'autosnippet_task' },
-  });
-}
-
 // ── decompose ──
 
 async function _decompose(svc, args) {

package/lib/external/mcp/tools.js

@@ -1,7 +1,8 @@
 /**
- * MCP 工具定义 — V3 整合版 (16 agent + 4 admin = 20 工具)
+ * MCP 工具定义 — V3 整合版 (18 agent + 4 admin = 22 工具)
  *
- * 从 39 → 20 工具（参数路由合并同类工具 + 外部 Agent 冷启动新架构 + TaskGraph）。
+ * 从 39 → 22 工具（参数路由合并同类工具 + 外部 Agent 冷启动新架构 + TaskGraph 三工具拆分）。
+ * TaskGraph 拆分: autosnippet_ready + autosnippet_decide + autosnippet_task
  * 每个工具声明增加 tier 字段（agent / admin）。
  * tools.js 只包含 JSON Schema 声明 + Gateway 映射，不含业务逻辑。
  *
@@ -44,6 +45,15 @@ export const TOOL_GATEWAY_MAP = {
   autosnippet_submit_knowledge: { action: 'knowledge:create', resource: 'knowledge' },
   autosnippet_submit_knowledge_batch: { action: 'knowledge:create', resource: 'knowledge' },
   autosnippet_save_document: { action: 'knowledge:create', resource: 'knowledge' },
+  // decide 写操作（record/revise/unpin）
+  autosnippet_decide: {
+    resolver: (args) =>
+      ({
+        record: { action: 'task:create', resource: 'tasks' },
+        revise: { action: 'task:update', resource: 'tasks' },
+        unpin: { action: 'task:update', resource: 'tasks' },
+      })[args?.operation] || null, // list 只读
+  },
   // task 写操作（create/claim/close/fail/defer/decompose/dep_add）
   autosnippet_task: {
     resolver: (args) =>
@@ -56,7 +66,7 @@ export const TOOL_GATEWAY_MAP = {
         progress: { action: 'task:update', resource: 'tasks' },
         decompose: { action: 'task:create', resource: 'tasks' },
         dep_add: { action: 'task:update', resource: 'tasks' },
-      })[args?.operation] || null, // ready/prime/show/list/blocked/dep_tree/stats 只读
+      })[args?.operation] || null, // ready/show/list/blocked/dep_tree/stats 只读
   },
   // admin 工具
   autosnippet_enrich_candidates: { action: 'knowledge:update', resource: 'knowledge' },
@@ -67,7 +77,7 @@ export const TOOL_GATEWAY_MAP = {
 
 export const TOOLS = [
   // ══════════════════════════════════════════════════════
-  //  Tier: agent — Agent 核心工具集 (16 个)
+  //  Tier: agent — Agent 核心工具集 (18 个)
   // ══════════════════════════════════════════════════════
 
   // 1. 健康检查
@@ -528,68 +538,99 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
-  // 13. TaskGraph 任务管理
+  // 13. autosnippet_ready — Agent 会话入口（like beads_ready）
+  {
+    name: 'autosnippet_ready',
+    tier: 'agent',
+    description:
+      'Session entry point. Call FIRST at conversation start to load project context, active decisions, and available tasks.\n' +
+      'Returns: in-progress tasks, ready tasks (with knowledge context), pinned decisions, and stats.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', default: 10, description: 'Max ready tasks to return' },
+        withKnowledge: { type: 'boolean', default: true, description: 'Attach knowledge context to ready tasks' },
+      },
+      required: [],
+    },
+  },
+
+  // 14. autosnippet_decide — 决策管理
+  {
+    name: 'autosnippet_decide',
+    tier: 'agent',
+    description:
+      'Decision management. Record, revise or unpin project decisions that persist across conversations.\n' +
+      'Call record when you and user reach agreement. Decisions are shown in every autosnippet_ready call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        operation: {
+          type: 'string',
+          enum: ['record', 'revise', 'unpin', 'list'],
+          description: 'record=pin new decision, revise=supersede old, unpin=close, list=show active',
+        },
+        title: { type: 'string', description: 'Decision title (record/revise)' },
+        description: { type: 'string', description: 'Decision description (record/revise)' },
+        rationale: { type: 'string', description: 'Why this decision (record/revise)' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Classification tags (record)' },
+        relatedTaskId: { type: 'string', description: 'Related task ID (record)' },
+        id: { type: 'string', description: 'Decision ID (revise/unpin)' },
+        reason: { type: 'string', description: 'Reason for revision/unpin' },
+      },
+      required: ['operation'],
+    },
+  },
+
+  // 15. autosnippet_task — 任务 CRUD
   {
     name: 'autosnippet_task',
     tier: 'agent',
     description:
-      '任务图管理。创建/查询/认领/关闭任务，管理依赖关系。' +
-      '用于 Agent 自主拆解和执行复杂多步骤工作。' +
-      'ready 返回任务 + 相关知识上下文。prime 恢复会话状态。',
+      'Task CRUD operations. Create tasks, claim work, close completed, track dependencies.\n' +
+      'For session context use autosnippet_ready. For decisions use autosnippet_decide.',
     inputSchema: {
       type: 'object',
       properties: {
         operation: {
           type: 'string',
           enum: [
-            'create',
-            'ready',
-            'claim',
-            'close',
-            'fail',
-            'defer',
-            'progress',
-            'show',
-            'list',
-            'blocked',
-            'decompose',
-            'dep_add',
-            'dep_tree',
-            'prime',
-            'stats',
+            'create', 'ready', 'claim', 'close', 'fail', 'defer',
+            'progress', 'show', 'list', 'stats',
+            'blocked', 'decompose', 'dep_add', 'dep_tree',
           ],
-          description: '操作类型',
+          description: 'Operation type',
         },
-        title: { type: 'string', description: '任务标题（create）' },
-        description: { type: 'string', description: '任务描述（create/progress）' },
-        design: { type: 'string', description: '设计说明（create）' },
-        acceptance: { type: 'string', description: '验收标准（create）' },
-        priority: { type: 'number', description: '优先级 0-4, 0=最高（create）' },
+        title: { type: 'string', description: 'Task title (create)' },
+        description: { type: 'string', description: 'Task description (create/progress)' },
+        design: { type: 'string', description: 'Design notes (create)' },
+        acceptance: { type: 'string', description: 'Acceptance criteria (create)' },
+        priority: { type: 'number', description: 'Priority 0-4, 0=highest (create)' },
         taskType: {
           type: 'string',
           enum: ['epic', 'task', 'bug', 'chore'],
-          description: '任务类型（create）',
+          description: 'Task type (create)',
         },
-        parentId: { type: 'string', description: '父任务 ID（create 子任务）' },
-        id: { type: 'string', description: '任务 ID（claim/close/fail/defer/show/dep_add/dep_tree/progress）' },
-        reason: { type: 'string', description: '原因（close/fail/defer）' },
-        dependsOn: { type: 'string', description: '依赖的任务 ID（dep_add）' },
+        parentId: { type: 'string', description: 'Parent task ID (create subtask)' },
+        id: { type: 'string', description: 'Task ID (claim/close/fail/defer/show/dep_add/dep_tree/progress)' },
+        reason: { type: 'string', description: 'Reason (close/fail/defer)' },
+        dependsOn: { type: 'string', description: 'Dependency target task ID (dep_add)' },
         depType: {
           type: 'string',
-          enum: ['blocks', 'parent-child', 'waits-for', 'discovered-from', 'related', 'knowledge-ref'],
+          enum: ['blocks', 'parent-child', 'waits-for', 'discovered-from', 'related', 'knowledge-ref', 'supersedes'],
           default: 'blocks',
-          description: '依赖类型（dep_add）',
+          description: 'Dependency type (dep_add)',
         },
-        limit: { type: 'number', default: 10, description: '结果数量限制（ready/list）' },
+        limit: { type: 'number', default: 10, description: 'Result limit (ready/list)' },
         status: {
           type: 'string',
-          enum: ['open', 'in_progress', 'deferred', 'closed'],
-          description: '状态过滤（list）',
+          enum: ['open', 'in_progress', 'deferred', 'closed', 'pinned'],
+          description: 'Status filter (list)',
         },
         withKnowledge: {
           type: 'boolean',
           default: true,
-          description: '是否附加知识上下文（ready）',
+          description: 'Attach knowledge context (ready)',
         },
         subtasks: {
           type: 'array',
@@ -600,11 +641,11 @@ export const TOOLS = [
               description: { type: 'string' },
               priority: { type: 'number' },
               taskType: { type: 'string' },
-              blockedByIndex: { type: 'number', description: '被 subtasks 数组中哪个 index 的子任务阻塞' },
+              blockedByIndex: { type: 'number', description: 'Index in subtasks array that blocks this subtask' },
             },
             required: ['title'],
           },
-          description: '子任务列表（decompose）',
+          description: 'Subtasks list (decompose)',
         },
       },
       required: ['operation'],