fix: resolve parentId to UUID in linear_issues tool + add smoke test

The linear_issues tool was passing the identifier string (e.g. "UAT-335")
as parentId in the GraphQL mutation instead of the resolved UUID. Linear
mutations require UUIDs for ID fields. Now resolves via getIssueDetails.

Adds tool-level smoke test (6 tests) that exercises the full
linear_issues tool execute path against real Linear API: create parent,
read parent, create sub-issue with parentIssueId, verify parent
relationship, cleanup.

Also adds 2 webhook scenario tests verifying sub-issue guidance appears
in agent prompts for triaged issues and is absent for backlog issues.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: calltelemetry-jason

src/__test__/smoke-linear-api.test.ts

@@ -14,6 +14,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { LinearAgentApi } from "../api/linear-api.js";
+import { createLinearIssuesTool } from "../tools/linear-issues-tool.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -684,6 +685,147 @@ describe("Linear API smoke tests", () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // Tool-level sub-issue creation (linear_issues tool)
+  // ---------------------------------------------------------------------------
+
+  describe("tool-level sub-issue creation (linear_issues tool)", () => {
+    let toolParentIdentifier: string | null = null;
+    let toolSubIdentifier: string | null = null;
+    let toolParentId: string | null = null;
+    let toolSubId: string | null = null;
+    let tool: any;
+
+    function parseToolResult(result: any): any {
+      if (result?.content && Array.isArray(result.content)) {
+        const textBlock = result.content.find((r: any) => r.type === "text");
+        if (textBlock) return JSON.parse(textBlock.text);
+      }
+      if (result?.details) return result.details;
+      return typeof result === "string" ? JSON.parse(result) : result;
+    }
+
+    it("instantiates linear_issues tool with real credentials", () => {
+      const apiKey = loadApiKey();
+      const pluginApi = {
+        logger: {
+          info: (...args: any[]) => console.log("[tool-smoke]", ...args),
+          warn: (...args: any[]) => console.warn("[tool-smoke]", ...args),
+          error: (...args: any[]) => console.error("[tool-smoke]", ...args),
+          debug: () => {},
+        },
+        pluginConfig: { accessToken: apiKey },
+      };
+      tool = createLinearIssuesTool(pluginApi as any);
+      expect(tool).toBeTruthy();
+      expect(tool.name).toBe("linear_issues");
+    });
+
+    it("creates a parent issue via tool action=create", async () => {
+      const result = parseToolResult(
+        await tool.execute("smoke-call-1", {
+          action: "create",
+          title: "[SMOKE TEST] Tool Sub-Issue Parent",
+          description:
+            "Auto-generated by tool-level smoke test.\n" +
+            "Tests linear_issues tool can create parent + sub-issues.\n\n" +
+            `Created: ${new Date().toISOString()}`,
+          teamId: TEAM_ID,
+          priority: 4,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+      expect(result.identifier).toBeTruthy();
+      expect(result.id).toBeTruthy();
+
+      toolParentIdentifier = result.identifier;
+      toolParentId = result.id;
+      console.log(`Tool created parent: ${result.identifier} (${result.id})`);
+    });
+
+    it("reads parent issue via tool action=read (by identifier)", async () => {
+      expect(toolParentIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-2", {
+          action: "read",
+          issueId: toolParentIdentifier!,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.identifier).toBe(toolParentIdentifier);
+      expect(result.title).toContain("[SMOKE TEST]");
+      expect(result.team.id).toBe(TEAM_ID);
+      expect(result.parent).toBeNull();
+      console.log(`Tool read parent: ${result.identifier} (status=${result.status})`);
+    });
+
+    it("creates a sub-issue via tool action=create with parentIssueId (identifier)", async () => {
+      expect(toolParentIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-3", {
+          action: "create",
+          title: "[SMOKE TEST] Tool Sub-Issue: Backend work",
+          description:
+            "Sub-issue created via linear_issues tool with parentIssueId.\n" +
+            "Verifies identifier → UUID resolution and teamId inheritance.",
+          parentIssueId: toolParentIdentifier!,
+          priority: 3,
+          estimate: 2,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+      expect(result.identifier).toBeTruthy();
+      expect(result.id).toBeTruthy();
+      expect(result.parentIssueId).toBe(toolParentIdentifier);
+
+      toolSubIdentifier = result.identifier;
+      toolSubId = result.id;
+      console.log(`Tool created sub-issue: ${result.identifier} (parent=${toolParentIdentifier})`);
+    });
+
+    it("verifies sub-issue has correct parent via tool action=read", async () => {
+      expect(toolSubIdentifier).toBeTruthy();
+
+      const result = parseToolResult(
+        await tool.execute("smoke-call-4", {
+          action: "read",
+          issueId: toolSubIdentifier!,
+        }),
+      );
+
+      expect(result.error).toBeUndefined();
+      expect(result.identifier).toBe(toolSubIdentifier);
+      expect(result.parent).not.toBeNull();
+      expect(result.parent.identifier).toBe(toolParentIdentifier);
+      // teamId was inherited from parent (not provided explicitly in create)
+      expect(result.team.id).toBe(TEAM_ID);
+      console.log(`Tool sub-issue parent confirmed: ${result.parent.identifier}`);
+    });
+
+    it("cleans up: cancels tool-created issues", async () => {
+      const states = await api.getTeamStates(TEAM_ID);
+      const canceledState = states.find(
+        (s) => s.type === "canceled" || s.name.toLowerCase().includes("cancel"),
+      );
+
+      for (const id of [toolSubId, toolParentId]) {
+        if (!id || !canceledState) continue;
+        try {
+          await api.updateIssue(id, { stateId: canceledState.id });
+        } catch {
+          // Best effort
+        }
+      }
+    });
+  });
+
   describe("cleanup", () => {
     it("cancels the smoke test issue", async () => {
       if (!smokeIssueId) return;

src/__test__/webhook-scenarios.test.ts

@@ -82,6 +82,7 @@ vi.mock("../pipeline/pipeline.js", () => ({
   runPlannerStage: vi.fn().mockResolvedValue("mock plan"),
   runFullPipeline: vi.fn().mockResolvedValue(undefined),
   resumePipeline: vi.fn().mockResolvedValue(undefined),
+  buildProjectContext: () => "",
 }));
 
 vi.mock("../pipeline/active-session.js", () => ({
@@ -787,4 +788,47 @@ describe("webhook scenario tests — full handler flows", () => {
       expect(msg).toContain("Cached guidance from session event");
     });
   });
+
+  describe("Sub-issue guidance in agent prompt", () => {
+    it("created: triaged issue includes sub-issue guidance with parentIssueId", async () => {
+      // Issue is "In Progress" (type: "started") — triaged, so full tool access
+      mockGetIssueDetails.mockResolvedValue(makeIssueDetails({
+        state: { name: "In Progress", type: "started" },
+      }));
+
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated();
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+
+      // Verify sub-issue guidance text includes the correct parentIssueId
+      expect(msg).toContain("Sub-issue guidance");
+      expect(msg).toContain("break it into sub-issues");
+      expect(msg).toContain('parentIssueId="ENG-123"');
+    });
+
+    it("created: backlog issue does NOT include sub-issue guidance", async () => {
+      // Issue is "Backlog" (type: "backlog") — untriaged, so read-only tool access
+      mockGetIssueDetails.mockResolvedValue(makeIssueDetails({
+        state: { name: "Backlog", type: "backlog" },
+      }));
+
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated();
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+
+      // Backlog issues get READ ONLY access — no sub-issue guidance
+      expect(msg).not.toContain("Sub-issue guidance");
+      expect(msg).toContain("READ ONLY");
+    });
+  });
 });

src/tools/linear-issues-tool.test.ts

@@ -342,7 +342,7 @@ describe("linear_issues tool", () => {
         projectId: "proj-1",
         title: "Sub-task: handle edge case",
         description: "Fix the edge case for empty input",
-        parentId: "ENG-123",
+        parentId: "issue-1",  // Resolved UUID from getIssueDetails, not the identifier "ENG-123"
       });
       expect(result.success).toBe(true);
       expect(result.identifier).toBe("ENG-201");

src/tools/linear-issues-tool.ts

@@ -86,12 +86,14 @@ async function handleCreate(api: LinearAgentApi, params: ToolParams) {
   // Resolve teamId: explicit param, or derive from parent issue
   let teamId = params.teamId;
   let projectId = params.projectId;
+  let resolvedParentId: string | undefined;
 
   if (params.parentIssueId) {
-    // Fetch parent to get teamId and projectId
+    // Fetch parent to get teamId, projectId, and resolved UUID
     const parent = await api.getIssueDetails(params.parentIssueId);
     teamId = teamId ?? parent.team.id;
     projectId = projectId ?? parent.project?.id ?? undefined;
+    resolvedParentId = parent.id;
   }
 
   if (!teamId) {
@@ -106,7 +108,7 @@ async function handleCreate(api: LinearAgentApi, params: ToolParams) {
   };
 
   if (params.description) input.description = params.description;
-  if (params.parentIssueId) input.parentId = params.parentIssueId;
+  if (resolvedParentId) input.parentId = resolvedParentId;
   if (projectId) input.projectId = projectId;
   if (params.priority != null) input.priority = params.priority;
   if (params.estimate != null) input.estimate = params.estimate;