feat(linear): teach agent to fetch attachments + docs via Linear MCP

Linear-channel tasks now know how (and when) to discover paperclip
attachments, project documents, and post-task-start comments via the
already-loaded `mcp__linear-server__*` tools. The webhook processor
issues a single GraphQL probe per triggered issue to flag presence of
attachments / project docs and prepends a one-line hint to the task
description so the agent has a reason to invoke the MCP. No new IAM,
tables, env vars, or CDK constructs — purely prompt + GraphQL.

The screened description-image pipeline (`extractImageUrlAttachments`)
is unchanged; embedded `![alt](https://…)` images still go through
Bedrock Guardrails at task-creation time. The new MCP path is
additive coverage for paperclips, project wikis, and live comments.

(cherry picked from commit 8a75afc)

Author: isadeks

agent/src/prompt_builder.py

@@ -155,6 +155,8 @@ def _channel_prompt_addendum(config: TaskConfig) -> str:
         return ""
     issue_identifier = config.channel_metadata.get("linear_issue_identifier") or ""
     issue_ref = f" (`{issue_identifier}`)" if issue_identifier else ""
+    issue_id = config.channel_metadata.get("linear_issue_id") or ""
+    project_id = config.channel_metadata.get("linear_project_id") or ""
     return (
         "\n\n## Linear issue progress updates (REQUIRED)\n\n"
         f"This task was submitted from Linear issue{issue_ref}. The Linear MCP "
@@ -182,7 +184,47 @@ def _channel_prompt_addendum(config: TaskConfig) -> str:
         "agent-side completion comment would just stack two near-identical "
         "comments on the issue.\n\n"
         "Keep the start + PR-opened comments concise. Do not mirror the full "
-        "agent transcript back to Linear."
+        "agent transcript back to Linear.\n\n"
+        "## Linear context discovery (on demand)\n\n"
+        "The same Linear MCP exposes tools for fetching extra context on the "
+        "issue when you need it. Use them sparingly — only when the task "
+        "description references material you don't have, when the description "
+        "is ambiguous and project-level context would clarify, or when a "
+        "decision point benefits from a fresh look at the issue thread. Do "
+        "NOT call these on every task; the issue title + description are "
+        "usually sufficient.\n\n"
+        f"- **Issue + paperclip attachments.** Call `mcp__linear-server__get_issue` "
+        f'with `id: "{issue_id}"` to fetch the full issue, including its '
+        "`attachments` connection (paperclip-icon files like PDFs, logs, "
+        "spec docs that aren't embedded as markdown images). Read the "
+        "attachment titles first; for each one that looks relevant, call "
+        "`mcp__linear-server__get_attachment` with that attachment id. Skip "
+        "ones that look unrelated (e.g. screenshots from prior debugging "
+        "sessions).\n"
+        "- **Embedded images.** Description and comment images that look "
+        "like `![alt](https://uploads.linear.app/…)` may have stale signed "
+        "URLs by the time you run. If you need to actually look at one, call "
+        "`mcp__linear-server__extract_images` to get fresh signed URLs, then "
+        "use the built-in `WebFetch` tool to download. (The screened "
+        "description-image path runs at task-creation time and is separate "
+        "from this — you don't need to re-screen.)\n"
+        "- **Project documents.** When the issue belongs to a project and "
+        "the task is ambiguous enough that project-level context (specs, "
+        "design docs, RFCs) would help, call "
+        f"`mcp__linear-server__list_documents` filtered to "
+        f'`projectId: "{project_id}"` (skip if the issue has no project). '
+        "Read the titles. For documents that clearly relate to your task, "
+        "call `mcp__linear-server__get_document` to read the body. Don't "
+        "fetch every document.\n"
+        "- **Comments posted after task start.** Comments left while you're "
+        "running (e.g. clarifications, approve/deny signals from the "
+        "requester) are not in your task description. Before opening the PR, "
+        f"and again before merging if asked, call `mcp__linear-server__list_comments` "
+        f'with `issueId: "{issue_id}"` and look for new comments since '
+        "task start. Respect any clear approve / deny / block / hold signals "
+        "from the original requester (the issue creator or the person who "
+        "applied the trigger label) — if they say stop, stop and post a "
+        "comment explaining why."
     )
 
 

agent/tests/test_entrypoint.py

@@ -500,3 +500,106 @@ def test_selects_pr_review_prompt(self):
         assert "READ-ONLY" in prompt
         assert "must NOT modify" in prompt
         assert "55" in prompt
+
+
+# ---------------------------------------------------------------------------
+# _build_system_prompt — Linear channel addendum
+# ---------------------------------------------------------------------------
+
+
+class TestBuildSystemPromptLinearChannel:
+    """The Linear-channel addendum is appended only for channel_source=='linear'."""
+
+    def _setup(self) -> RepoSetup:
+        return RepoSetup(
+            repo_dir="/workspace/t1",
+            branch="b",
+            default_branch="main",
+            notes=[],
+        )
+
+    def test_no_addendum_when_channel_is_blank(self):
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        assert "Linear issue progress updates" not in prompt
+        assert "Linear context discovery" not in prompt
+
+    def test_no_addendum_for_slack_channel(self):
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="slack",
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        assert "Linear issue progress updates" not in prompt
+        assert "Linear context discovery" not in prompt
+
+    def test_addendum_present_for_linear_channel(self):
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="linear",
+            channel_metadata={
+                "linear_issue_id": "issue-uuid-1",
+                "linear_issue_identifier": "ABC-42",
+                "linear_project_id": "project-uuid-1",
+            },
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        assert "Linear issue progress updates" in prompt
+        assert "Linear context discovery" in prompt
+        assert "ABC-42" in prompt
+
+    def test_linear_addendum_names_attachment_tools(self):
+        # The agent must know the exact MCP tool names — vague references
+        # would cause it to grope. Lock these in so a rename triggers the test.
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="linear",
+            channel_metadata={"linear_issue_id": "issue-uuid-1"},
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        for tool in (
+            "mcp__linear-server__get_issue",
+            "mcp__linear-server__get_attachment",
+            "mcp__linear-server__extract_images",
+            "mcp__linear-server__list_documents",
+            "mcp__linear-server__get_document",
+            "mcp__linear-server__list_comments",
+        ):
+            assert tool in prompt, f"expected {tool} to be named in the Linear addendum"
+
+    def test_linear_addendum_inlines_issue_id_and_project_id(self):
+        config = TaskConfig(
+            repo_url="o/r",
+            task_id="t1",
+            max_turns=10,
+            github_token="ghp_test",
+            aws_region="us-east-1",
+            channel_source="linear",
+            channel_metadata={
+                "linear_issue_id": "issue-uuid-deadbeef",
+                "linear_project_id": "project-uuid-cafebabe",
+            },
+        )
+        prompt = _build_system_prompt(config, self._setup(), None, "")
+        # The agent shouldn't have to guess the ids — they're in the metadata,
+        # so we surface them directly in the prompt.
+        assert "issue-uuid-deadbeef" in prompt
+        assert "project-uuid-cafebabe" in prompt

cdk/src/handlers/linear-webhook-processor.ts

@@ -22,6 +22,10 @@ import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';
 import { createTaskCore } from './shared/create-task-core';
 import { reactToComment, replyToComment, reportIssueFailure, EMOJI_STARTED } from './shared/linear-feedback';
+import {
+  probeLinearIssueContext,
+  renderIssueContextHint,
+} from './shared/linear-issue-context-probe';
 import { resolveLinearOauthToken } from './shared/linear-oauth-resolver';
 import { fetchIssueParentId } from './shared/linear-subissue-fetch';
 import { resolveTaskByLinearIssue, prNumberFromTask } from './shared/linear-task-by-issue';
@@ -311,8 +315,6 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     return;
   }
 
-  const taskDescription = buildTaskDescription(issue);
-
   const channelMetadata: Record<string, string> = {
     linear_issue_id: issue.id,
     linear_workspace_id: workspaceId,
@@ -343,6 +345,7 @@ export async function handler(event: ProcessorEvent): Promise<void> {
   // is guaranteed present (we return otherwise), so the token is set
   // whenever the registry table is configured.
   let resolvedAccessToken: string | undefined;
+  let contextHint = '';
   if (WORKSPACE_REGISTRY_TABLE) {
     const resolved = await resolveLinearOauthToken(workspaceId, WORKSPACE_REGISTRY_TABLE);
     if (!resolved) {
@@ -355,6 +358,12 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     channelMetadata.linear_oauth_secret_arn = resolved.oauthSecretArn;
     channelMetadata.linear_workspace_slug = resolved.workspaceSlug;
     resolvedAccessToken = resolved.accessToken;
+    // Best-effort presence probe: ask Linear once whether the issue has
+    // paperclip attachments or sits in a project with documents. The agent
+    // will fetch the actual content via the Linear MCP at runtime — this
+    // step only flags that there's something worth fetching.
+    const probe = await probeLinearIssueContext(resolved.accessToken, issue.id);
+    contextHint = renderIssueContextHint(probe);
   }
 
   // #247 Mode A — parent/sub-issue orchestration. Env-var gated: until
@@ -577,6 +586,8 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     // path below (issue had no sub-issues).
   }
 
+  const taskDescription = buildTaskDescription(issue, contextHint);
+
   // Extract embedded image URLs from the issue description markdown.
   // These become URL attachments that are fetched and screened during context hydration.
   const attachments = extractImageUrlAttachments(issue.description);
@@ -1098,13 +1109,17 @@ function buildCreateTaskFailureMessage(statusCode: number, rawBody: string): str
   return `❌ ABCA couldn't create this task (status ${statusCode}). Check the ABCA admin logs for details.`;
 }
 
-function buildTaskDescription(issue: LinearIssueEvent['data']): string {
+function buildTaskDescription(issue: LinearIssueEvent['data'], contextHint: string = ''): string {
   const parts: string[] = [];
   if (issue.identifier && issue.title) {
     parts.push(`${issue.identifier}: ${issue.title}`);
   } else if (issue.title) {
     parts.push(issue.title);
   }
+  if (contextHint) {
+    parts.push('');
+    parts.push(contextHint);
+  }
   if (issue.description && issue.description.trim()) {
     parts.push('');
     parts.push(issue.description.trim());

cdk/src/handlers/shared/linear-issue-context-probe.ts

@@ -0,0 +1,164 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { logger } from './logger';
+
+/**
+ * Best-effort probe for additional Linear context attached to an issue —
+ * paperclip attachments and project documents — that the agent should
+ * fetch on demand via the Linear MCP at runtime.
+ *
+ * The webhook payload itself does NOT carry attachments or
+ * project.documents, so we ask Linear's GraphQL API once at task-creation
+ * time. The result is a tiny presence signal (titles + counts) that lets
+ * the webhook processor prepend a hint to the task description; it does
+ * NOT pre-fetch bodies, screen content, or upload to S3 — that path is
+ * still owned by `extractImageUrlAttachments` for description-embedded
+ * markdown images.
+ */
+
+const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
+const REQUEST_TIMEOUT_MS = 5000;
+
+const ISSUE_CONTEXT_QUERY = `
+query IssueContext($id: String!) {
+  issue(id: $id) {
+    id
+    attachments(first: 25) {
+      nodes {
+        id
+        title
+      }
+    }
+    project {
+      id
+      name
+      documents(first: 1) {
+        nodes { id }
+      }
+    }
+  }
+}
+`.trim();
+
+export interface LinearIssueContextProbe {
+  /** Paperclip attachment titles surfaced on the issue, if any. */
+  readonly attachmentTitles: readonly string[];
+  /** Project name (only present when the issue belongs to a project). */
+  readonly projectName: string | null;
+  /** True when the issue's project has at least one document attached. */
+  readonly projectHasDocuments: boolean;
+}
+
+const EMPTY: LinearIssueContextProbe = {
+  attachmentTitles: [],
+  projectName: null,
+  projectHasDocuments: false,
+};
+
+/**
+ * Issue the GraphQL query. Returns an empty probe on any failure
+ * (network, auth, GraphQL errors). Never throws — the caller treats
+ * absence of context the same as no extra context being available.
+ */
+export async function probeLinearIssueContext(
+  accessToken: string,
+  issueId: string,
+): Promise<LinearIssueContextProbe> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const resp = await fetch(LINEAR_GRAPHQL_URL, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        query: ISSUE_CONTEXT_QUERY,
+        variables: { id: issueId },
+      }),
+      signal: controller.signal,
+    });
+    if (!resp.ok) {
+      logger.warn('Linear issue context probe non-2xx', { status: resp.status, issue_id: issueId });
+      return EMPTY;
+    }
+    const body = (await resp.json()) as {
+      data?: {
+        issue?: {
+          attachments?: { nodes?: Array<{ id?: string; title?: string }> };
+          project?: {
+            id?: string;
+            name?: string;
+            documents?: { nodes?: Array<{ id?: string }> };
+          } | null;
+        };
+      };
+      errors?: unknown;
+    };
+    if (body.errors) {
+      logger.warn('Linear issue context probe graphql errors', { issue_id: issueId, errors: body.errors });
+      return EMPTY;
+    }
+    const issue = body.data?.issue;
+    if (!issue) return EMPTY;
+    const attachmentTitles = (issue.attachments?.nodes ?? [])
+      .map((a) => (typeof a?.title === 'string' ? a.title.trim() : ''))
+      .filter((t): t is string => t.length > 0);
+    const project = issue.project ?? null;
+    const projectName = typeof project?.name === 'string' && project.name.trim() ? project.name.trim() : null;
+    const projectHasDocuments = (project?.documents?.nodes ?? []).length > 0;
+    return { attachmentTitles, projectName, projectHasDocuments };
+  } catch (err) {
+    logger.warn('Linear issue context probe request failed', {
+      issue_id: issueId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return EMPTY;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Render a one-paragraph hint the webhook processor prepends to the task
+ * description when the probe surfaced anything worth flagging. Returns
+ * an empty string when there's nothing to hint about — the processor
+ * skips the prepend in that case.
+ *
+ * The wording deliberately points at MCP tool names so the agent's
+ * channel-prompt addendum reinforces (and is reinforced by) the same
+ * vocabulary.
+ */
+export function renderIssueContextHint(probe: LinearIssueContextProbe): string {
+  const bits: string[] = [];
+  if (probe.attachmentTitles.length > 0) {
+    const titles = probe.attachmentTitles.slice(0, 5).map((t) => `"${t}"`).join(', ');
+    const more = probe.attachmentTitles.length > 5 ? ` (+${probe.attachmentTitles.length - 5} more)` : '';
+    bits.push(`paperclip attachments — ${titles}${more} (fetch via \`mcp__linear-server__get_issue\` then \`mcp__linear-server__get_attachment\`)`);
+  }
+  if (probe.projectHasDocuments && probe.projectName) {
+    bits.push(`project "${probe.projectName}" has wiki documents (browse with \`mcp__linear-server__list_documents\` if the task is ambiguous)`);
+  } else if (probe.projectHasDocuments) {
+    bits.push('the project has wiki documents (browse with `mcp__linear-server__list_documents` if the task is ambiguous)');
+  }
+  if (bits.length === 0) return '';
+  return `Linear may have additional context for this issue: ${bits.join('; ')}.`;
+}