pybao-cli 1.5.19 → 1.5.21

package/dist/{chunk-L6J4MPRE.js → chunk-CPYDPN2J.js}

@@ -41,57 +41,57 @@ import {
   runWithTaskListEnv,
   runWithTaskListId,
   updateTask
-} from "./chunk-ZWB3VSTH.js";
+} from "./chunk-6UNYL6XK.js";
 import {
   getCurrentSessionId
 } from "./chunk-XKYHFZEC.js";
 import {
   queryLLM
-} from "./chunk-VB3UZHV6.js";
+} from "./chunk-4ZGZTWMR.js";
 import {
   FallbackToolUseRejectedMessage,
   MCPTool,
   getClients,
   getMCPTools
-} from "./chunk-KX7DKI3A.js";
+} from "./chunk-H2ZE5QDY.js";
 import {
   emitReminderEvent
-} from "./chunk-OMCKTGQ5.js";
+} from "./chunk-ZQR3MM2D.js";
 import {
   getActiveAgents,
   getAgentByType,
   getAvailableAgentTypes
-} from "./chunk-IYGHQUN2.js";
+} from "./chunk-NRQHLVJJ.js";
 import {
   INTERRUPT_MESSAGE,
   createAssistantMessage,
   createUserMessageFromBlocks,
   createUserMessageFromText,
   getLastAssistantMessageId
-} from "./chunk-BPY6R2EU.js";
+} from "./chunk-YQ2RQUQF.js";
 import {
   formatDuration,
   formatNumber
 } from "./chunk-OUXHGDLH.js";
 import {
   getAbsolutePath
-} from "./chunk-M3AEV7WD.js";
+} from "./chunk-HA7FKBZI.js";
 import {
   LspFacade,
   formatDiagnosticsPretty
-} from "./chunk-KRBHZ2NW.js";
+} from "./chunk-XRLMQN3Q.js";
 import {
   getModelManager
-} from "./chunk-CGFEVSPI.js";
+} from "./chunk-25GZITCX.js";
 import {
   getContext
-} from "./chunk-FYOORPZ4.js";
+} from "./chunk-RQ5X6LFM.js";
 import {
   getTheme
-} from "./chunk-YKSGF3T7.js";
+} from "./chunk-56IL2VXC.js";
 import {
   debug
-} from "./chunk-LXJUYOGP.js";
+} from "./chunk-TBEA6BY3.js";
 import {
   BunShell,
   MEMORY_DIR,
@@ -103,7 +103,7 @@ import {
   overwriteLog,
   readTaskOutput,
   resolveXdgDataPath
-} from "./chunk-VSKWAGTO.js";
+} from "./chunk-VP5A6FKG.js";
 
 // src/tools/index.ts
 import { memoize as memoize2 } from "lodash-es";
@@ -784,7 +784,7 @@ async function analyzeOutputWithLsp(output, exitCode) {
   if (exitCode !== 0 || errorCount > 0 || warningCount > 0) {
     try {
       const { isAbsolute: isAbsolute2, resolve: resolve3 } = await import("path");
-      const { getSessionRoot: getSessionRoot2 } = await import("./state-YDKD6B6T.js");
+      const { getSessionRoot: getSessionRoot2 } = await import("./state-T57IG35V.js");
       const lines = output.split("\n");
       const uniqueFiles = /* @__PURE__ */ new Set();
       const lspSuggestions = [];
@@ -1154,7 +1154,7 @@ var DeleteTool = {
         }
         if (!force) {
           try {
-            const { LspFacade: LspFacade2 } = await import("./lsp-XVTWUOP7.js");
+            const { LspFacade: LspFacade2 } = await import("./lsp-CTPOMI7O.js");
             const referenceDetail = await LspFacade2.checkFileReferences(fullPath);
             if (referenceDetail) {
               failedItems.push(
@@ -2688,12 +2688,20 @@ function mapStatusToOutput(status) {
   return status;
 }
 function toTaskListItem(task) {
-  return {
+  const projection = getTaskCollaborationProjection(task);
+  const item = {
     id: task.id,
     subject: task.subject,
     status: mapStatusToOutput(task.status),
     blockedBy: task.blockedBy ?? []
   };
+  if (projection.owner) item.owner = projection.owner;
+  if (projection.worktree) item.worktree = projection.worktree;
+  if (projection.lane) item.lane = projection.lane;
+  if (projection.agent) item.agent = projection.agent;
+  if (projection.created_at !== void 0) item.created_at = projection.created_at;
+  if (projection.updated_at !== void 0) item.updated_at = projection.updated_at;
+  return item;
 }
 function toTaskDetail(task) {
   return {
@@ -2708,13 +2716,33 @@ function toTaskDetail(task) {
   };
 }
 function toTaskGetDetail(task) {
-  return {
+  const projection = getTaskCollaborationProjection(task);
+  const detail = {
     subject: task.subject,
     description: task.description,
+    activeForm: task.activeForm,
     status: mapStatusToOutput(task.status),
+    metadata: task.metadata,
     blocks: task.blocks ?? [],
     blockedBy: task.blockedBy ?? []
   };
+  if (projection.owner) detail.owner = projection.owner;
+  if (projection.worktree) detail.worktree = projection.worktree;
+  if (projection.lane) detail.lane = projection.lane;
+  if (projection.agent) detail.agent = projection.agent;
+  if (projection.created_at !== void 0) detail.created_at = projection.created_at;
+  if (projection.updated_at !== void 0) detail.updated_at = projection.updated_at;
+  return detail;
+}
+function getTaskCollaborationProjection(task) {
+  const metadata = task.metadata ?? {};
+  const owner = typeof metadata.owner === "string" ? metadata.owner : void 0;
+  const worktree = typeof metadata.worktree === "string" ? metadata.worktree : void 0;
+  const lane = typeof metadata.lane === "string" ? metadata.lane : void 0;
+  const agent = typeof metadata.agent === "string" ? metadata.agent : void 0;
+  const created_at = typeof metadata.created_at === "number" || typeof metadata.created_at === "string" ? metadata.created_at : void 0;
+  const updated_at = typeof metadata.updated_at === "number" || typeof metadata.updated_at === "string" ? metadata.updated_at : void 0;
+  return { owner, worktree, lane, agent, created_at, updated_at };
 }
 function createTaskToolError(params) {
   return {
@@ -2756,15 +2784,24 @@ Skip using this tool only when:
 - Use TaskCreate when scope changes during execution.
 - Use TaskCreate when a milestone is completed and the next concrete work unit begins.
 
+## Core Workflow
+
+**The Two-Phase Pattern (IMPORTANT):**
+- **Phase 1 - Create**: Create all tasks one by one WITHOUT dependencies (blockedBy=[]).
+- **Phase 2 - Link**: Use TaskUpdate to add blockedBy AFTER all related tasks exist.
+
+This pattern ensures clean dependency graph construction and prevents reference errors.
+
 ## Input Notes
 - subject is required.
 - listId is optional; omit to use the default list.
 - TaskCreate only supports single-task creation; create multiple tasks one by one.
 - For multi-step plans, create the structured task list without dependencies and add blockedBy later via TaskUpdate.
-- activeForm is required and must not equal subject.
+- activeForm is required.
+- metadata is optional and should only include stable coordination fields you want to persist.
 - blockedBy is always stored as an array (empty when not used).
 - description and blockedBy are kept separate in JSON; any joining is only for terminal rendering.
-- Task ordering relies on task id; do not use priority fields.
+- Task ordering relies on task id; 
 - Use metadata.planFinalized="true" in TaskUpdate when dependencies are ready to be validated globally.
 - Do not mention tool names or tool usage in user-facing messages.
 - When uncertain whether to track, prefer tracking.
@@ -2788,50 +2825,296 @@ Preferred single-task template:
 ## Status Notes
 - Use pending when dependencies prevent work and fill blockedBy.
 
+## Task Lifecycle Overview
+
+Tasks flow through these states:
+
+- pending --(start work)--> in_progress --(complete)--> done
+- pending --(cancel)--> deleted
+- in_progress --(cancel)--> deleted
+
+**State Definitions:**
+- **pending**: Not started, may be blocked by dependencies
+- **in_progress**: Currently being worked on (only ONE task at a time)
+- **done**: Successfully completed (triggers unlock propagation)
+- **deleted**: Cancelled or no longer needed
+
+**Ready vs Blocked:**
+- A task is **ready** when: status=pending AND blockedBy=[] (all dependencies satisfied)
+- A task is **blocked** when: blockedBy contains task IDs that are not yet done/deleted
+
+## Dependency Relationships
+
+Tasks can have dependencies on other tasks:
+
+- **blockedBy**: List of task IDs that must complete before this task can start
+- **blocks**: List of task IDs that are waiting for this task (auto-synced, do not set manually)
+
+**How it works:**
+
+Task A (blockedBy: [])
+Task B (blockedBy: ["A"])  \u2190 B waits for A
+Task C (blockedBy: ["A"])  \u2190 C waits for A
+
+When Task A completes:
+  - blockedBy is cleared from B and C
+  - Both B and C become ready (can run in parallel)
+
+**Important:** When you set blockedBy via TaskUpdate, the reverse blocks relationship is automatically synchronized. Never manually set blocks.
+
+## Handling Natural Language Requests
+
+When users provide vague or high-level requests (e.g., "build a user auth module"), you must:
+1. **Decompose** the request into logical subtasks based on software engineering best practices
+2. **Identify dependencies** between subtasks (what must complete before what can start)
+3. **Create tasks first** with blockedBy=[] for all tasks
+4. **Add dependencies second** using TaskUpdate.addBlockedBy
+
+Common decomposition patterns:
+- **Database/API pattern**: Schema design \u2192 Table implementation \u2192 API endpoints \u2192 Tests
+- **Frontend pattern**: Design \u2192 Components \u2192 Integration \u2192 Testing
+- **Full-stack pattern**: Backend \u2192 API \u2192 Frontend \u2192 Integration tests
+
 ## Examples of When to Use TaskCreate
 
+### Category A: No Explicit Dependencies or Order (Most Common)
+
+User provides a high-level request without specifying how to break it down or what should be done first.
+
 <example>
-User: I need to implement user registration, product catalog, and checkout.
-Assistant: I will create tasks for each feature one by one.
-*Creates tasks:*
-1. User registration
-2. Product catalog
-3. Checkout flow
+User: Build a user authentication module
+
+Assistant: This is a complex feature that requires multiple components. Let me plan the implementation steps.
+
+*Creates tasks (Phase 1):*
+TaskCreate(subject="Design auth database schema", activeForm="Designing auth database schema")
+TaskCreate(subject="Implement users table", activeForm="Implementing users table")
+TaskCreate(subject="Implement sessions table", activeForm="Implementing sessions table")
+TaskCreate(subject="Build auth API endpoints", activeForm="Building auth API endpoints")
+TaskCreate(subject="Write unit tests", activeForm="Writing unit tests")
+TaskCreate(subject="Write integration tests", activeForm="Writing integration tests")
+
+*Adds dependencies (Phase 2):*
+TaskUpdate(taskId="2", addBlockedBy=["1"])
+TaskUpdate(taskId="3", addBlockedBy=["1"])
+TaskUpdate(taskId="4", addBlockedBy=["2", "3"])
+TaskUpdate(taskId="5", addBlockedBy=["4"])
+TaskUpdate(taskId="6", addBlockedBy=["4"])
+
+Auth module planned: 6 tasks with dependency graph established. Starting with database design.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. User provided a high-level feature request without task breakdown
+2. Authentication module requires multiple components (database, tables, API, tests)
+3. The assistant inferred dependencies based on software engineering practices: schema before tables, tables before API, API before tests
+4. Two-phase pattern: create all tasks first, then link dependencies
+</reasoning>
 </example>
 
 <example>
-User: Please add tests and run lint after the refactor.
-Assistant: I'll seed tasks for the refactor and verification steps.
-*Creates tasks:*
-1. Refactor target module
-2. Add tests
-3. Run lint and typecheck
+User: I want to add a dark mode toggle to the application settings. Make sure you run the tests when you're done!
+
+Assistant: I'll help add a dark mode toggle. Let me plan the implementation steps.
+
+*Creates tasks (Phase 1):*
+TaskCreate(subject="Create dark mode toggle component", activeForm="Creating dark mode toggle component")
+TaskCreate(subject="Add dark mode state management", activeForm="Adding dark mode state management")
+TaskCreate(subject="Implement dark theme styles", activeForm="Implementing dark theme styles")
+TaskCreate(subject="Update components for theme switching", activeForm="Updating components for theme switching")
+TaskCreate(subject="Run tests and fix failures", activeForm="Running tests and fixing failures")
+
+*Adds dependencies (Phase 2):*
+TaskUpdate(taskId="3", addBlockedBy=["2"])
+TaskUpdate(taskId="4", addBlockedBy=["1", "3"])
+TaskUpdate(taskId="5", addBlockedBy=["4"])
+
+Dark mode toggle planned: 5 tasks. Starting with the toggle component.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. Adding dark mode is a multi-step feature requiring UI, state management, and styling changes
+2. User explicitly requested tests be run afterward - this becomes the final task
+3. Dependencies inferred: styles depend on state management, components depend on toggle and styles, tests run last
+</reasoning>
 </example>
 
 <example>
-User: The API task depends on database schema changes.
-Assistant: I'll create the tasks first, then add blockedBy using TaskUpdate.
-*Creates tasks without dependencies, then updates blockedBy*
+User: Help optimize my React app performance, rendering is slow
+
+Assistant: Let me first examine the codebase to identify performance bottlenecks.
+
+*Examines component structure, render patterns, state management*
+
+After analyzing the codebase, I've identified several performance issues. Let me plan the optimizations.
+
+*Creates tasks (Phase 1):*
+TaskCreate(subject="Add memoization to ProductList calculations", activeForm="Adding memoization to ProductList")
+TaskCreate(subject="Implement virtualization for Dashboard lists", activeForm="Implementing list virtualization")
+TaskCreate(subject="Optimize image loading in Gallery", activeForm="Optimizing image loading")
+TaskCreate(subject="Fix state update loops in ShoppingCart", activeForm="Fixing state update loops")
+
+*Dependencies: These can be done at the same time, no specific order needed*
+
+React performance optimization planned: 4 tasks. Starting with ProductList memoization.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. First examined the codebase to identify specific performance issues
+2. Multiple independent optimizations were identified - each becomes a task
+3. These tasks have NO dependencies - they can run in parallel
+4. Todo list helps track which optimizations have been addressed
+</reasoning>
+</example>
+
+### Category B: Explicit Order Specified by User
+
+User clearly indicates what should be done first, second, etc. using words like "first... then... finally..." or numbered lists.
+
+<example>
+User: First design the database, then create the users table and sessions table, then write the API, and finally test
+
+Assistant: User has explicitly specified the order. Let me plan tasks according to this sequence.
+
+*Creates tasks (Phase 1):*
+TaskCreate(subject="Design database schema", activeForm="Designing database schema")
+TaskCreate(subject="Implement users table", activeForm="Implementing users table")
+TaskCreate(subject="Implement sessions table", activeForm="Implementing sessions table")
+TaskCreate(subject="Build API endpoints", activeForm="Building API endpoints")
+TaskCreate(subject="Write tests", activeForm="Writing tests")
+
+*Adds dependencies based on user's explicit order (Phase 2):*
+TaskUpdate(taskId="2", addBlockedBy=["1"])  // users table waits for database
+TaskUpdate(taskId="3", addBlockedBy=["1"])  // sessions table waits for database
+TaskUpdate(taskId="4", addBlockedBy=["2", "3"])  // API waits for both tables
+TaskUpdate(taskId="5", addBlockedBy=["4"])  // tests wait for API
+
+Tasks planned in your specified order: database \u2192 users/sessions tables \u2192 API \u2192 tests
+
+<reasoning>
+The assistant used TaskCreate because:
+1. User explicitly specified the order: database first, then tables, then API, finally tests
+2. This order translates directly into dependency relationships
+3. Users table and sessions table can run in parallel after database (both depend only on task 1)
+4. Two-phase pattern: create all tasks, then add dependencies matching user's specified order
+</reasoning>
 </example>
 
 <example>
-User: Let's sketch the task list first and add dependencies later.
-Assistant: I'll create the tasks now and we can add blockedBy with TaskUpdate afterward.
-*Creates tasks without blockedBy*
+User: I need to add a character limit to the bio field. First, add the validation logic to the backend, then update the frontend form.
+
+Assistant: I'll plan this with the order you specified.
+
+*Creates tasks (Phase 1):*
+TaskCreate(subject="Add backend validation for bio character limit", activeForm="Adding backend validation")
+TaskCreate(subject="Update frontend form to enforce character limit", activeForm="Updating frontend form")
+
+*Adds dependencies (Phase 2):*
+TaskUpdate(taskId="2", addBlockedBy=["1"])  // frontend waits for backend
+
+Bio character limit planned: backend validation first, then frontend update.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. User used "First... then..." which explicitly defines the order
+2. Backend must be done before frontend - this is a dependency relationship
+3. Two tasks with one dependency
+</reasoning>
 </example>
 
 <example>
-User: Create just one task.
-Assistant: I'll create a single task.
-*Creates one task without auto dependency chaining*
+User: I need to implement user registration, product catalog, shopping cart, and checkout flow
+
+Assistant: These are core e-commerce features. Let me plan tasks for each module.
+
+*Creates tasks for each feature (Phase 1):*
+TaskCreate(subject="Implement user registration", activeForm="Implementing user registration")
+TaskCreate(subject="Implement product catalog", activeForm="Implementing product catalog")
+TaskCreate(subject="Implement shopping cart", activeForm="Implementing shopping cart")
+TaskCreate(subject="Implement checkout flow", activeForm="Implementing checkout flow")
+
+*Adds dependencies (Phase 2):*
+TaskUpdate(taskId="3", addBlockedBy=["2"])  // cart depends on product catalog
+TaskUpdate(taskId="4", addBlockedBy=["1", "3"])  // checkout depends on registration and cart
+
+E-commerce features planned: user registration and product catalog can start together, cart waits for catalog, checkout waits for registration and cart.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. User provided multiple complex features in a comma-separated list
+2. These features have natural dependencies: cart needs products, checkout needs user and cart
+3. Registration and catalog can run in parallel (no dependency between them)
+4. Todo list helps organize these large features into manageable tasks
+</reasoning>
+</example>
+
+### Category C: Simple or Single Task
+
+User's request is straightforward and doesn't require complex planning.
+
+<example>
+User: Just fix the typo in the documentation
+
+Assistant: This is a straightforward fix. I'll create a single task to track it.
+
+*Creates one task:*
+TaskCreate(subject="Fix typo in documentation", activeForm="Fixing documentation typo")
+
+<reasoning>
+The assistant used TaskCreate because:
+1. This is a single task that can be tracked
+2. No complex breakdown needed
+3. Still useful to track for completeness and progress visibility
+</reasoning>
+</example>
+
+<example>
+User: Add a comment to the calculateTotal function explaining what it does
+
+Assistant: This is a simple single-step task.
+
+*Creates one task:*
+TaskCreate(subject="Add comment to calculateTotal function", activeForm="Adding function comment")
+
+<reasoning>
+The assistant used TaskCreate because:
+1. Single straightforward task in one location
+2. Creating a task helps track completion
+</reasoning>
+</example>
+
+### Category D: Adding Forgotten Tasks
+
+User realizes something was missed after the initial plan.
+
+<example>
+User: I forgot, we also need logging for the auth module
+
+Assistant: Let me add the logging task and link it appropriately.
+
+TaskCreate(subject="Add auth logging", activeForm="Adding auth logging")
+
+*The logging task depends on API endpoints being ready:*
+TaskUpdate(taskId="7", addBlockedBy=["4"])  // logging depends on API
+
+Auth logging added. It will be done after the API endpoints are complete.
+
+<reasoning>
+The assistant used TaskCreate because:
+1. User added a new requirement after initial planning
+2. New task was created first with TaskCreate
+3. Then linked to existing tasks via TaskUpdate.addBlockedBy
+4. Logging logically depends on API endpoints existence
+</reasoning>
 </example>
 `.trim();
 
 // src/tools/interaction/TaskCreateTool/TaskCreateTool.tsx
 var inputSchema8 = z9.strictObject({
+  listId: z9.string().min(1).optional(),
   subject: z9.string().min(1),
   description: z9.string().min(1),
-  activeForm: z9.string().min(1).optional(),
+  activeForm: z9.string().min(1),
   metadata: metadataSchema.optional()
 });
 var TaskCreateTool = {
@@ -2876,14 +3159,17 @@ var TaskCreateTool = {
         description: input.description,
         activeForm: input.activeForm,
         metadata: input.metadata
-      });
-      const { listId } = getTaskListPaths();
-      emitReminderEvent("task.created", {
+      }, { listId: input.listId });
+      const { listId } = getTaskListPaths(input.listId);
+      const timestamp = Date.now();
+      const payload = {
         listId,
         taskId: task.id,
         task,
-        timestamp: Date.now()
-      });
+        timestamp
+      };
+      emitReminderEvent("task.created", payload);
+      emitReminderEvent("task.created.v1", payload);
       yield {
         type: "result",
         data: {
@@ -2941,6 +3227,7 @@ Assistant: I'll fetch the task details first.
 
 // src/tools/interaction/TaskGetTool/TaskGetTool.tsx
 var inputSchema9 = z10.strictObject({
+  listId: z10.string().min(1).optional(),
   taskId: z10.string().min(1)
 });
 var TaskGetTool = {
@@ -2978,8 +3265,8 @@ var TaskGetTool = {
     return null;
   },
   async *call(input) {
-    const { listId } = getTaskListPaths();
-    const task = getTask(input.taskId);
+    const { listId } = getTaskListPaths(input.listId);
+    const task = getTask(input.taskId, { listId: input.listId });
     if (!task) {
       yield {
         type: "result",
@@ -3026,6 +3313,7 @@ Skip using this tool when:
 NOTE that TaskList is for summaries and readiness; use TaskGet for details.
 
 ## Input Notes
+- listId is optional; omit to use the default list.
 - status filters the returned items; omit to exclude deleted tasks by default.
 - blockedBy may be empty early in planning and will appear as dependencies are added.
 - Do not mention tool names or tool usage in user-facing messages.
@@ -3053,6 +3341,7 @@ Assistant: I'll list tasks to show the updated ready/blocked breakdown.
 
 // src/tools/interaction/TaskListTool/TaskListTool.tsx
 var inputSchema10 = z11.strictObject({
+  listId: z11.string().min(1).optional(),
   status: z11.enum(["pending", "in_progress", "completed", "deleted"]).optional()
 });
 var filterByStatus = (tasks, statuses) => {
@@ -3069,6 +3358,21 @@ var mapStatusFilterInput = (input) => {
   if (input === "pending") return ["pending"];
   return ["in_progress"];
 };
+var getActiveBlockers = (task, tasksById) => {
+  const blockers = task.blockedBy ?? [];
+  const active = [];
+  for (const blockerId of blockers) {
+    const blocker = tasksById.get(blockerId);
+    if (!blocker) {
+      active.push(blockerId);
+      continue;
+    }
+    if (blocker.status !== "done" && blocker.status !== "deleted") {
+      active.push(blockerId);
+    }
+  }
+  return active;
+};
 var TaskListTool = {
   name: "TaskList",
   cachedDescription: DESCRIPTION7,
@@ -3105,10 +3409,19 @@ var TaskListTool = {
   },
   async *call(input) {
     try {
-      const { listId } = getTaskListPaths();
-      const tasks = listTasks();
+      const { listId } = getTaskListPaths(input.listId);
+      const tasks = listTasks({ listId: input.listId });
       const filtered = filterByStatus(tasks, mapStatusFilterInput(input.status));
-      const items = filtered.map(toTaskListItem);
+      const tasksById = new Map(tasks.map((task) => [task.id, task]));
+      const items = filtered.map((task) => {
+        const base = toTaskListItem(task);
+        const activeBlockers = getActiveBlockers(task, tasksById);
+        return {
+          ...base,
+          ready: task.status === "pending" && activeBlockers.length === 0,
+          activeBlockers
+        };
+      });
       yield {
         type: "result",
         data: {
@@ -3157,40 +3470,350 @@ NOTE that TaskUpdate should be used when you need to persist task changes.
 - listId is optional; omit to use the default list.
 - Dependencies are validated for cycles; invalid cycles will be rejected.
 - Use TaskUpdate to add blockedBy after tasks are created.
+- Use addBlocks when the current task should block other tasks; the reverse blockedBy relation is synchronized.
 - You can set metadata.planFinalized="true" to trigger a full dependency validation pass.
-- activeForm must be provided; it is not generated from subject.
+- activeForm is optional in updates; when omitted, existing value is preserved.
 - blockedBy is always stored as an array (empty when not used).
 - description and blockedBy are kept separate in JSON; any joining is only for terminal rendering.
 - Task ordering relies on task id; do not use priority fields.
 - Do not mention tool names or tool usage in user-facing messages.
 
+## The Two Usage Patterns
+
+### Pattern 1: Dependency Linking (After TaskCreate)
+Use TaskUpdate to establish dependencies AFTER all tasks are created:
+- Create tasks with TaskCreate (blockedBy=[])
+- Link dependencies with TaskUpdate.addBlockedBy or TaskUpdate.addBlocks
+- This ensures reference validity and clean graph construction
+
+### Pattern 2: Status Progression
+Use TaskUpdate to move tasks through the execution lifecycle:
+- pending \u2192 in_progress: When starting work on a task
+- in_progress \u2192 completed: When task is done (triggers unlock propagation)
+- Any \u2192 deleted: When task is obsolete or cancelled
+
+## Update Patterns
+- Simple status-only update: update one task status directly (pending \u2192 in_progress \u2192 completed) when no dependency change is needed.
+- Complex dependency and unlock update: update blockedBy/addBlocks and status together, then consume unlockResult.readyNow immediately.
+- Cancel or retire path: use deleted when a task is intentionally retired and should no longer appear in default lists.
+
 ## Field Guidance
 - activeForm: short verb phrase describing the in-progress action.
 - description: prefer a one-line overview plus bullet points for multi-step tasks; for very simple tasks a short sentence is fine.
+- collaboration metadata keys:
+  - metadata.owner for task owner identity
+  - metadata.worktree for bound worktree name
+  - metadata.lane for collaboration lane
+  - metadata.agent for agent role or identifier
+  - metadata.created_at for creation timestamp
+  - metadata.updated_at for update timestamp
 
 ## Status Notes
 - Use in_progress for the task you are actively working on.
 - Use pending when dependencies prevent progress and set blockedBy.
 - Use completed only when all dependencies are satisfied.
+- When status becomes completed, consume unlockResult.readyNow immediately.
+- If readyNow is returned, continue with those tasks without calling TaskList.
+
+## Task Lifecycle Overview
+
+Tasks flow through these states:
+
+- pending --(start work)--> in_progress --(complete)--> done
+- pending --(cancel)--> deleted
+- in_progress --(cancel)--> deleted
+
+**State Definitions:**
+- **pending**: Not started, may be blocked by dependencies
+- **in_progress**: Currently being worked on (only ONE task at a time)
+- **done**: Successfully completed (triggers unlock propagation)
+- **deleted**: Cancelled or no longer needed
+
+**Ready vs Blocked:**
+- A task is **ready** when: status=pending AND blockedBy=[] (all dependencies satisfied)
+- A task is **blocked** when: blockedBy contains task IDs that are not yet done/deleted
+
+## Dependency Relationships
+
+Tasks can have dependencies on other tasks:
+
+- **blockedBy**: List of task IDs that must complete before this task can start
+- **blocks**: List of task IDs that are waiting for this task (auto-synced, do not set manually)
+
+**How it works:**
+
+Task A (blockedBy: [])
+Task B (blockedBy: ["A"])  \u2190 B waits for A
+Task C (blockedBy: ["A"])  \u2190 C waits for A
+
+When Task A completes:
+  - blockedBy is cleared from B and C
+  - Both B and C become ready (can run in parallel)
+
+**Important:** When you set blockedBy via TaskUpdate, the reverse blocks relationship is automatically synchronized. Never manually set blocks.
+
+## Understanding Unlock Propagation
+
+When a task is marked as completed:
+1. It is removed from the blockedBy list of all tasks it was blocking
+2. Any tasks that become unblocked (blockedBy becomes empty) appear in unlockResult.readyNow
+3. You should immediately continue with those readyNow tasks without calling TaskList
+
+This enables efficient "chain execution" without redundant status checks.
 
 ## Examples of When to Use TaskUpdate
 
+### Category A: Status Progression (Moving Tasks Forward)
+
 <example>
-User: Mark the API task as in progress.
-Assistant: I'll update the task status.
-*Updates task status to in_progress*
+User: The database design is done, let's start on the users table
+
+Assistant: Database design is complete. Let me update the task status and continue to the next step.
+
+TaskUpdate(taskId="1", status="completed")
+*Result shows readyNow: ["2", "3"]*
+
+Both the users table and sessions table are now ready. I'll start with the users table.
+
+TaskUpdate(taskId="2", status="in_progress")
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User indicated the database design is done
+2. Completing task 1 triggers unlock - tasks 2 and 3 become ready
+3. User said to start the users table
+4. The unlockResult.readyNow tells us what tasks are now unblocked
+</reasoning>
+</example>
+
+<example>
+User: I've finished the API endpoints. What should I work on next?
+
+Assistant: Let me mark the API task complete and see what's unblocked.
+
+TaskUpdate(taskId="4", status="completed")
+*Result shows readyNow: ["5", "6"]*
+
+The unit tests and integration tests are now ready. Would you like to start with unit tests?
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User said they finished the API endpoints
+2. Completing this task triggers unlock propagation
+3. The readyNow field shows which tasks can now start
+4. This enables efficient "chain execution" without calling TaskList
+</reasoning>
+</example>
+
+<example>
+User: Start writing the tests
+
+Assistant: I'll mark the test task as in progress.
+
+TaskUpdate(taskId="5", status="in_progress")
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User wants to start working on tests
+2. Simple status progression: pending \u2192 in_progress
+</reasoning>
+</example>
+
+### Category B: Task Completion and Chain Execution
+
+<example>
+User: The database design is complete
+
+Assistant: Database design task is complete. Let me check what tasks are now ready.
+
+TaskUpdate(taskId="1", status="completed")
+*Result shows unlockResult.readyNow: ["2", "3"]*
+
+The users table and sessions table can now be done together. I'll continue with the users table.
+
+TaskUpdate(taskId="2", status="in_progress")
+*Continuing with unblocked task without calling TaskList*
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User reported completion of database design
+2. unlockResult.readyNow shows tasks 2 and 3 are now unblocked and can run in parallel
+3. Assistant immediately continues with task 2 - efficient chain execution
+4. No need to call TaskList to check status
+</reasoning>
+</example>
+
+### Category C: Task Obsolescence or Cancellation
+
+<example>
+User: This feature is no longer needed, let's skip it for now
+
+Assistant: I'll mark this task as deleted.
+
+TaskUpdate(taskId="3", status="deleted")
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User said the feature is no longer needed
+2. "deleted" status removes it from active task flow
+3. This may unblock other tasks that were waiting on this one
+</reasoning>
+</example>
+
+<example>
+User: Actually, we don't need the session table anymore. We're using JWT instead.
+
+Assistant: I'll mark the session table task as deleted since we're switching to JWT.
+
+TaskUpdate(taskId="3", status="deleted")
+
+*If task 3 was blocking other tasks, they may now be unblocked*
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User indicated a change in approach (JWT instead of sessions)
+2. The session table task is now obsolete
+3. Marking as deleted removes it from active work
+</reasoning>
+</example>
+
+### Category D: Adding New Requirements During Execution
+
+<example>
+User: The auth module also needs a password reset feature
+
+Assistant: Adding password reset functionality. Let me create a new task and add it to the existing plan.
+
+TaskCreate(subject="Implement password reset", activeForm="Implementing password reset")
+
+*This new task may need to be linked to existing tasks:*
+TaskUpdate(taskId="7", addBlockedBy=["4"])  // password reset depends on API endpoints
+
+Password reset feature added to task list, depends on API endpoints completion.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User added a new requirement during execution
+2. New task was created first
+3. Then dependency was added using TaskUpdate
+4. Password reset logically depends on the API endpoints being ready
+</reasoning>
+</example>
+
+<example>
+User: We need to add rate limiting to the auth endpoints too
+
+Assistant: I'll add a rate limiting task and link it appropriately.
+
+TaskCreate(subject="Add rate limiting to auth endpoints", activeForm="Adding rate limiting")
+TaskUpdate(taskId="8", addBlockedBy=["4"])  // rate limiting depends on API
+
+Rate limiting task added. It will start after the API endpoints are complete.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User added a new requirement
+2. Create task first, then add dependency
+3. Rate limiting applies to API endpoints, so it depends on task 4
+</reasoning>
+</example>
+
+### Category E: Dependency Adjustment
+
+<example>
+User: The users table doesn't need to wait for database design, we can do it at the same time
+
+Assistant: I'll remove this dependency.
+
+TaskUpdate(taskId="2", blockedBy=[])
+
+The users table can now start immediately, no need to wait for database design.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User said the users table no longer needs to wait for database design
+2. Setting blockedBy=[] removes all blockers
+3. Task 2 is now ready to start immediately
+</reasoning>
 </example>
 
 <example>
-User: The UI task depends on the API task now.
-Assistant: I'll update dependencies.
-*Updates blockedBy to include the API task*
+User: Tests should wait until all development tasks are complete
+
+Assistant: I'll set the test task to wait for all development tasks.
+
+TaskUpdate(taskId="5", addBlockedBy=["1", "2", "3", "4"])
+
+The test task will now wait for tasks 1-4 to all complete before starting.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User specified that tests should wait for all development tasks
+2. addBlockedBy adds new dependencies without removing existing ones
+3. Task 5 will only be ready after all four development tasks complete
+</reasoning>
 </example>
 
 <example>
-User: We've finished adding dependencies and want to finalize the plan.
-Assistant: I'll set metadata.planFinalized to trigger the global validation.
-*Updates metadata.planFinalized to "true"*
+User: The API doesn't need to wait for the sessions table anymore, just the users table
+
+Assistant: I'll adjust the API's dependencies.
+
+TaskUpdate(taskId="4", blockedBy=["2"])  // only keep users table dependency
+
+The API now only needs to wait for the users table to complete.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User specified a change in dependencies
+2. Sessions table is no longer a blocker for API
+3. Setting the full blockedBy list replaces the previous one
+</reasoning>
+</example>
+
+### Category F: Changing Execution Order
+
+User wants to change the planned execution order.
+
+<example>
+User: Wait, let's do the users table first, then the database
+
+Assistant: I understand you want to change the execution order. Let me adjust the dependencies.
+
+*Current state: users table (task 2) depends on database (task 1)*
+
+TaskUpdate(taskId="2", blockedBy=[])  // users table no longer waits for database
+TaskUpdate(taskId="1", addBlockedBy=["2"])  // database now waits for users table
+
+Order adjusted: users table first, then database. The users table can start immediately.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User requested a reversal of execution order
+2. First, remove the existing dependency from task 2
+3. Then, create a reverse dependency where database waits for users table
+4. Task 2 is now unblocked and ready to start immediately
+</reasoning>
+</example>
+
+<example>
+User: Actually, let's do the users table and sessions table first, before the database design
+
+Assistant: I'll reverse the dependency chain so both tables come before database design.
+
+TaskUpdate(taskId="2", blockedBy=[])  // users table no longer blocked
+TaskUpdate(taskId="3", blockedBy=[])  // sessions table no longer blocked
+TaskUpdate(taskId="1", addBlockedBy=["2", "3"])  // database waits for both tables
+
+Both tables can now start immediately. Database design will wait for both to complete.
+
+<reasoning>
+The assistant used TaskUpdate because:
+1. User wanted to completely reverse the execution order
+2. Multiple dependencies needed to be cleared first
+3. Then reverse dependencies were added via addBlockedBy
+4. Tasks 2 and 3 are now unblocked and can run in parallel
+</reasoning>
 </example>
 `.trim();
 
@@ -3264,6 +3887,7 @@ var compareTaskId = (left, right) => {
   return left.id.localeCompare(right.id);
 };
 var inputSchema11 = z12.strictObject({
+  listId: z12.string().min(1).optional(),
   taskId: z12.string().min(1),
   subject: z12.string().optional(),
   description: z12.string().optional(),
@@ -3308,8 +3932,8 @@ var TaskUpdateTool = {
     return null;
   },
   async *call(input) {
-    const { listId } = getTaskListPaths();
-    const existing = getTask(input.taskId);
+    const { listId } = getTaskListPaths(input.listId);
+    const existing = getTask(input.taskId, { listId: input.listId });
     if (!existing) {
       yield {
         type: "result",
@@ -3322,7 +3946,7 @@ var TaskUpdateTool = {
       };
       return;
     }
-    const tasks = listTasks();
+    const tasks = listTasks({ listId: input.listId });
     const subject = input.subject ?? existing.subject;
     const mergedBlockedBy = mergeDeps(existing.blockedBy, input.addBlockedBy);
     const mappedStatus = mapStatusInput(input.status);
@@ -3454,7 +4078,7 @@ var TaskUpdateTool = {
           }
         }
         if (same) continue;
-        updateTask(task.id, { blockedBy: merged });
+        updateTask(task.id, { blockedBy: merged }, { listId: input.listId });
       }
       const result = updateTask(
         input.taskId,
@@ -3465,23 +4089,30 @@ var TaskUpdateTool = {
           status: mappedStatus,
           metadata: metadataUpdate,
           blockedBy: mergedBlockedBy
-        }
+        },
+        { listId: input.listId }
       );
       const didDepsChange = depsChanged(existing, result.task);
-      emitReminderEvent("task.updated", {
+      const updatedTimestamp = Date.now();
+      const updatedPayload = {
         listId,
         taskId: result.task.id,
         task: result.task,
-        timestamp: Date.now()
-      });
+        timestamp: updatedTimestamp
+      };
+      emitReminderEvent("task.updated", updatedPayload);
+      emitReminderEvent("task.updated.v1", updatedPayload);
       if (existing.status !== result.task.status) {
-        emitReminderEvent("task.status_changed", {
+        const statusTimestamp = Date.now();
+        const statusPayload = {
           listId,
           taskId: result.task.id,
           previousStatus: existing.status,
           status: result.task.status,
-          timestamp: Date.now()
-        });
+          timestamp: statusTimestamp
+        };
+        emitReminderEvent("task.status_changed", statusPayload);
+        emitReminderEvent("task.status_changed.v1", statusPayload);
       }
       if (didDepsChange) {
         emitReminderEvent("task.deps_changed", {
@@ -3492,12 +4123,33 @@ var TaskUpdateTool = {
           timestamp: Date.now()
         });
       }
+      if (result.unlockResult) {
+        emitReminderEvent("task.unblocked.v1", {
+          listId,
+          taskId: result.task.id,
+          unblocked: result.unlockResult.unblocked.map((task) => task.id),
+          readyNow: result.unlockResult.readyNow.map((task) => task.id),
+          touchedTaskIds: result.unlockResult.unlockSummary.touchedTaskIds,
+          timestamp: Date.now()
+        });
+      }
       yield {
         type: "result",
         data: {
           listId,
           item: toTaskDetail(result.task),
-          depsChanged: didDepsChange
+          depsChanged: didDepsChange,
+          unlockResult: result.unlockResult ? {
+            unblocked: result.unlockResult.unblocked.map(toTaskDetail),
+            partiallyUnblocked: result.unlockResult.partiallyUnblocked.map(
+              (item) => ({
+                task: toTaskDetail(item.task),
+                remainingBlockers: item.remainingBlockers
+              })
+            ),
+            readyNow: result.unlockResult.readyNow.map(toTaskDetail),
+            unlockSummary: result.unlockResult.unlockSummary
+          } : void 0
         }
       };
     } catch (error) {