feat(FN-4045): surface and handle delegate task collision errors

Added delegate collision detection and error surfacing across the task creation and delegation pipeline. The core store now throws a typed `DelegateCollisionError` when `createTask` encounters a duplicate task ID, the engine's `delegate_task` tool propagates these errors with context, and the CLI ex

Fusion-Task-Id: FN-4045

.changeset/fn-4045-collision-errors.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Surface task ID collision errors for task creation and delegation tools.

docs/agents.md

@@ -884,6 +884,7 @@ Create a new task and assign it to a specific agent for execution. The task goes
 - `"ERROR: Agent {agent_id} not found"`
 - `"ERROR: Cannot delegate to ephemeral/runtime agent {agent_id}"`
 - `"ERROR: Agent {agent_id} has role \"...\"; implementation task <new> requires an \"executor\"-role agent by default, with durable \"engineer\" supported only for explicit routing. Pass override=true to bypass."`
+- `"ERROR: Task ID already exists: {id}"` (allocator collision; request fails without mutating the existing task)
 
 ### `agent_create`
 

packages/cli/src/__tests__/extension-integration.test.ts

@@ -245,4 +245,23 @@ describe.skipIf(!SHOULD_RUN_EXTENSION_INTEGRATION)("built fn pi extension integr
     expect(rejected.isError).toBe(true);
     expect(rejected.content[0].text).toContain("ephemeral/runtime agent");
   });
+
+  it("returns explicit error when fn_delegate_task hits task-id collision", async () => {
+    const agent = await seedAgent(tmpDir, { name: "release-agent" });
+    const delegateTool = api.tools.get("fn_delegate_task")!;
+    const createSpy = vi.spyOn(TaskStore.prototype, "createTask").mockRejectedValueOnce(new Error("Task ID already exists: FN-001"));
+
+    const result = await delegateTool.execute(
+      "delegate-collision",
+      { agent_id: agent.id, description: "collision task" },
+      undefined,
+      undefined,
+      makeCtx(tmpDir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Task ID already exists: FN-001");
+    expect(result.details.error).toContain("Task ID already exists: FN-001");
+    createSpy.mockRestore();
+  });
 });

packages/cli/src/__tests__/extension.test.ts

@@ -1474,6 +1474,24 @@ describe("fn pi extension (runnable structured-output regression slice)", () =>
     expect(result.content[0].text).toContain(ephemeralId);
   });
 
+  it("returns explicit collision error when fn_task_create hits an existing task id", async () => {
+    const createSpy = vi.spyOn(TaskStore.prototype, "createTask").mockRejectedValueOnce(new Error("Task ID already exists: FN-001"));
+    const createTool = api.tools.get("fn_task_create")!;
+
+    const result = await createTool.execute(
+      "create-collision",
+      { description: "collision task" },
+      undefined,
+      undefined,
+      makeCtx(tmpDir),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Task ID already exists: FN-001");
+    expect(result.details.error).toContain("Task ID already exists: FN-001");
+    createSpy.mockRestore();
+  });
+
   it("fn_task_create allows durable engineer assignment for implementation tasks", async () => {
     const agentStore = new AgentStore({ rootDir: join(tmpDir, ".fusion") });
     await agentStore.init();

packages/cli/src/extension.ts

@@ -425,6 +425,7 @@ export default function kbExtension(pi: ExtensionAPI) {
         }
       }
 
+      try {
         const task = await store.createTask({
           description: params.description.trim(),
           dependencies: params.depends,
@@ -460,6 +461,16 @@ export default function kbExtension(pi: ExtensionAPI) {
             assignedAgentId: task.assignedAgentId,
           },
         };
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Task ID already exists:")) {
+          return {
+            content: [{ type: "text", text: `ERROR: ${error.message}` }],
+            isError: true,
+            details: { error: error.message },
+          };
+        }
+        throw error;
+      }
     },
   });
 
@@ -2763,6 +2774,7 @@ export default function kbExtension(pi: ExtensionAPI) {
       await agentStore.init();
       const agent = await agentStore.getAgent(params.agent_id);
 
+      try {
         // Create task assigned to the target agent
         const store = await getStore(ctx.cwd);
         const task = await store.createTask({
@@ -2785,6 +2797,16 @@ export default function kbExtension(pi: ExtensionAPI) {
           }],
           details: { taskId: task.id, agentId: agent!.id, agentName: agent!.name },
         };
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Task ID already exists:")) {
+          return {
+            content: [{ type: "text", text: `ERROR: ${error.message}` }],
+            isError: true,
+            details: { error: error.message },
+          };
+        }
+        throw error;
+      }
     },
   });
 

packages/engine/src/__tests__/agent-tools-delegation.test.ts

@@ -256,6 +256,22 @@ describe("createDelegateTaskTool", () => {
     expect(taskStore.createTask).not.toHaveBeenCalled();
   });
 
+  it("returns explicit collision error when delegated createTask hits existing id", async () => {
+    const agent = createAgent({ id: "agent-001", name: "Bob" });
+    vi.mocked(agentStore.getAgent).mockResolvedValue(agent);
+    vi.mocked(taskStore.createTask).mockRejectedValue(new Error("Task ID already exists: FN-050"));
+
+    const tool = createDelegateTaskTool(agentStore, taskStore);
+    const result = await tool.execute("session-1", {
+      agent_id: "agent-001",
+      description: "Write tests",
+    }, undefined as any, undefined as any, undefined as any);
+
+    expect((result as { isError?: boolean }).isError).toBe(true);
+    expect((result.content[0] as { text: string }).text).toBe("ERROR: Task ID already exists: FN-050");
+    expect(result.details).toEqual({});
+  });
+
   it("allows durable engineer target without override", async () => {
     const engineer = createAgent({ id: "agent-009", name: "Eli", role: "engineer" });
     vi.mocked(agentStore.getAgent).mockResolvedValue(engineer);

packages/engine/src/agent-tools.ts

@@ -623,6 +623,7 @@ export function createTaskCreateTool(
       "or the current task should wait for the new one).",
     parameters: taskCreateParams,
     execute: async (_id: string, params: Static<typeof taskCreateParams>) => {
+      try {
         const task = await createAgentTask(store, {
           description: params.description,
           dependencies: params.dependencies,
@@ -641,6 +642,16 @@ export function createTaskCreateTool(
           }],
           details: { taskId: task.id },
         };
+      } catch (err) {
+        if (err instanceof Error && err.message.startsWith("Task ID already exists:")) {
+          return {
+            content: [{ type: "text" as const, text: `ERROR: ${err.message}` }],
+            details: {},
+            isError: true,
+          };
+        }
+        throw err;
+      }
     },
   };
 }
@@ -1761,6 +1772,7 @@ export function createDelegateTaskTool(
         };
       }
 
+      try {
         // Create task assigned to the target agent
         const task = await createAgentTask(taskStore, {
           description: params.description,
@@ -1782,6 +1794,16 @@ export function createDelegateTaskTool(
           }],
           details: { taskId: task.id, agentId: agent.id, agentName: agent.name },
         };
+      } catch (err) {
+        if (err instanceof Error && err.message.startsWith("Task ID already exists:")) {
+          return {
+            content: [{ type: "text" as const, text: `ERROR: ${err.message}` }],
+            details: {},
+            isError: true,
+          };
+        }
+        throw err;
+      }
     },
   };
 }