@enrichlayer/el-linear 1.25.0 → 1.26.0

package/README.md

@@ -766,6 +766,39 @@ existing markdown or Slack links, angle-bracket autolinks, and bare URLs, so
 it's safe to pipe documents that already contain a mix of formatted links
 and bare identifiers.
 
+## Relation-candidate confirmation prompt
+
+When `el-linear search` or `el-linear issues search` returns results that
+carry issue identifiers (the "I just ran a duplicate/related check" shape),
+the JSON envelope embeds a structured `_warnings` line:
+
+```json
+{
+  "data": [{ "identifier": "DEV-2134", "title": "…" }, /* … */],
+  "meta": { "count": 3, "query": "auth flicker" },
+  "_warnings": [
+    "relation_candidates: Found 3 candidate related issues (DEV-2134, FIN-77, ALL-672). To link them as related: reply with the IDs you want linked (e.g. \"link DEV-2134 and FIN-77\"). To skip linking: reply \"no links\". (Agent-inferred IDs are blocked by auto-mode; user-named IDs pass — DEV-4494.)"
+  ]
+}
+```
+
+Why it exists: Claude Code's auto-mode permission classifier blocks
+`el-linear issues relate <source> --related-to "<ids>"` calls when the IDs
+were inferred by the agent from its own search rather than typed by the
+user — because each listed peer is a write target. The prompt nudges the
+caller (typically an agent driving the `linear-operations` skill) to surface
+the candidates verbatim and have the user name which IDs to link; any
+subsequent `issues relate` call then carries user-specified IDs and the
+guard passes naturally. **The fix is not to weaken the guard** — see
+[DEV-4494](https://linear.app/verticalint/issue/DEV-4494/) for the original
+incident (PYT-213 triage, 2026-06-04).
+
+The `relation_candidates:` prefix is a stable token so a skill or harness
+can grep for it without parsing free-form prose, matching the existing
+`results_truncated:` convention. Non-issue rows (projects, documents,
+initiatives) are ignored; the warning is suppressed when no result carries
+an identifier.
+
 ## Use with Claude Code
 
 el-linear ships a Claude Code skill at `claude-skills/linear-operations/SKILL.md`.

package/claude-skills/linear-operations/SKILL.md

@@ -181,6 +181,45 @@ el-linear issues search "keywords from proposed title" --include-closed 2>&1
    el-linear issues create "Title" --team ENG --related-to "ENG-456,ENG-789" ... 2>&1
    ```
 
+### Surfacing relation candidates — explicit user reply required ([DEV-4494](https://linear.app/verticalint/issue/DEV-4494/))
+
+When `el-linear issues search` (or the cross-resource `search`) returns rows
+carrying issue identifiers, the JSON envelope embeds a `_warnings` line
+starting with `relation_candidates:` that enumerates the candidate IDs and
+asks the user to reply with which ones to link. Treat it as a hard step,
+not a hint:
+
+1. **Surface the IDs to the user verbatim.** Show the `relation_candidates:`
+   line (or paraphrase it preserving every ID + the example reply). Do **not**
+   skip ahead to `issues relate`.
+2. **Wait for an explicit reply naming the IDs to link** (e.g. `link DEV-2134
+   and ALL-672`) or a clear skip (`no links`).
+3. **Only the user-named IDs** go into the next `el-linear issues relate
+   <source> --related-to "<ids>"` call. Never pass IDs the user did not name,
+   even if your earlier search obviously surfaced them.
+
+Why this matters: Claude Code's auto-mode permission classifier blocks
+`issues relate --related-to "<ids>"` when the IDs were *agent-inferred*
+(came from your own search) rather than *user-specified* (typed by the human),
+because each listed peer is a write target. Routing the IDs through an
+explicit human reply converts them from agent-inferred → user-specified;
+the existing search step (above) stays intact; auto-mode's guard is not
+weakened. The fix is the loop shape, not the guard.
+
+Anti-patterns:
+
+- **Calling `issues relate` directly off your own search output** — even if
+  the IDs are real and the candidates look obvious, this is the exact path
+  the auto-mode guard refuses.
+- **Splitting one relate call into N single-ID calls** to "look smaller" —
+  same provenance problem, same block, just multiplied.
+- **Asking the user a yes/no question** ("Should I link these?") instead of
+  having them name the IDs — yes answers stay agent-inferred, the reply
+  must carry the IDs to convert them to user-specified.
+
+If `--include-closed` search returns no matches, no `relation_candidates:`
+warning is emitted (nothing to confirm) and the flow proceeds normally.
+
 ### Viewing existing relations
 
 ```bash

package/dist/commands/issues.js

@@ -14,6 +14,7 @@ import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } from "../utils/output.js";
+import { buildRelationCandidatePrompt } from "../utils/relation-candidate-prompt.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
@@ -269,6 +270,15 @@ async function handleSearchIssues(query, options, command) {
         outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
     }
     warnIfTruncated(result.length, limit);
+    // DEV-4494: surface the explicit "reply with the IDs to link" prompt
+    // whenever an issue search returns candidate identifiers. The
+    // `linear-operations` skill consumes this `_warnings` line and shows it
+    // to the user so any subsequent `issues relate` call is user-specified
+    // rather than agent-inferred (which auto-mode blocks).
+    const relationPrompt = buildRelationCandidatePrompt(result);
+    if (relationPrompt) {
+        outputWarning(relationPrompt);
+    }
     outputIssues(result, options.format, options.fields, { query });
 }
 /**

package/dist/commands/search.js

@@ -1,7 +1,8 @@
 import { resolveTeam, resolveUserDisplayName } from "../config/resolver.js";
 import { SEMANTIC_SEARCH_QUERY } from "../queries/search.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { buildRelationCandidatePrompt } from "../utils/relation-candidate-prompt.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
 const TEMPLATES_QUERY = `
@@ -180,9 +181,19 @@ export function setupSearchCommands(program) {
             const templates = templateResult.templates ?? [];
             data = [...data, ...searchTemplates(templates, query)];
         }
+        const finalData = data.slice(0, limit);
+        // DEV-4494: when results carry issue identifiers, nudge the
+        // caller to surface them to the user verbatim and have the
+        // user name which IDs to link via `issues relate`. Keeps
+        // agent-inferred IDs out of relate calls without weakening
+        // auto-mode's guard.
+        const relationPrompt = buildRelationCandidatePrompt(finalData);
+        if (relationPrompt) {
+            outputWarning(relationPrompt);
+        }
         outputSuccess({
-            data: data.slice(0, limit),
-            meta: { count: Math.min(data.length, limit), query },
+            data: finalData,
+            meta: { count: finalData.length, query },
         });
     }));
 }

package/dist/utils/relation-candidate-prompt.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Relation-candidate confirmation prompt — DEV-4494.
+ *
+ * When `el-linear search` or `el-linear issues search` returns results that
+ * carry issue identifiers (the "I just ran a dup-check" shape), we emit a
+ * structured `_warnings` line that nudges the *caller* (typically a Claude
+ * agent driving `linear-operations`) to surface the IDs to the user verbatim
+ * and wait for an explicit reply naming which ones to link.
+ *
+ * Why the explicit reply matters
+ * ------------------------------
+ * Claude Code's auto-mode permission classifier blocks
+ * `el-linear issues relate <source> --related-to "<ids>"` when the IDs were
+ * inferred by the agent from its own search rather than typed by the user —
+ * because creating a relation writes onto *every* listed peer issue, and the
+ * IDs must be user-specified, not agent-inferred, to clear the guard.
+ *
+ * The fix isn't to weaken the guard. It's to tighten the loop: surface the
+ * candidates, ask the human to name which IDs to link, and only THEN call
+ * `issues relate` — at which point the IDs are user-specified by
+ * construction and the guard passes naturally.
+ *
+ * This module produces the warning. The actual UX is enforced by the
+ * `linear-operations` skill (it consumes the warning and shows it to the
+ * user) and by the existing auto-mode guard (it continues to block
+ * agent-inferred relate calls).
+ *
+ * Reference: https://linear.app/verticalint/issue/DEV-4494/
+ */
+/**
+ * Extract issue identifiers from a heterogeneous result array.
+ *
+ * Accepts the union of shapes used across the search commands:
+ * - `issues search` rows (`LinearIssue`) carry `identifier` at the top level
+ * - cross-resource `search` rows transform to `{ type: "issue", identifier }`
+ *   for issue rows; non-issue rows (`project`, `document`, …) have no
+ *   identifier and are skipped.
+ *
+ * Deduplicates and preserves insertion order so the prompt enumerates IDs
+ * in the same order they appear on screen.
+ */
+export declare function extractCandidateIdentifiers(rows: unknown[]): string[];
+/**
+ * Build the relation-candidate confirmation warning string, or `null` when
+ * the result set has no identifier-bearing rows (nothing to confirm).
+ *
+ * Shape (single line, structured-prose so a skill can match on the prefix):
+ *
+ *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
+ *     To link them as related: reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *
+ * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * convention in `outputWarning` callers — a stable token a skill / agent
+ * harness can grep for without parsing free-form prose.
+ */
+export declare function buildRelationCandidatePrompt(rows: unknown[]): string | null;

package/dist/utils/relation-candidate-prompt.js

@@ -0,0 +1,94 @@
+/**
+ * Relation-candidate confirmation prompt — DEV-4494.
+ *
+ * When `el-linear search` or `el-linear issues search` returns results that
+ * carry issue identifiers (the "I just ran a dup-check" shape), we emit a
+ * structured `_warnings` line that nudges the *caller* (typically a Claude
+ * agent driving `linear-operations`) to surface the IDs to the user verbatim
+ * and wait for an explicit reply naming which ones to link.
+ *
+ * Why the explicit reply matters
+ * ------------------------------
+ * Claude Code's auto-mode permission classifier blocks
+ * `el-linear issues relate <source> --related-to "<ids>"` when the IDs were
+ * inferred by the agent from its own search rather than typed by the user —
+ * because creating a relation writes onto *every* listed peer issue, and the
+ * IDs must be user-specified, not agent-inferred, to clear the guard.
+ *
+ * The fix isn't to weaken the guard. It's to tighten the loop: surface the
+ * candidates, ask the human to name which IDs to link, and only THEN call
+ * `issues relate` — at which point the IDs are user-specified by
+ * construction and the guard passes naturally.
+ *
+ * This module produces the warning. The actual UX is enforced by the
+ * `linear-operations` skill (it consumes the warning and shows it to the
+ * user) and by the existing auto-mode guard (it continues to block
+ * agent-inferred relate calls).
+ *
+ * Reference: https://linear.app/verticalint/issue/DEV-4494/
+ */
+/** Cap how many candidate IDs the prompt enumerates inline. */
+const MAX_CANDIDATES_IN_PROMPT = 10;
+/**
+ * Extract issue identifiers from a heterogeneous result array.
+ *
+ * Accepts the union of shapes used across the search commands:
+ * - `issues search` rows (`LinearIssue`) carry `identifier` at the top level
+ * - cross-resource `search` rows transform to `{ type: "issue", identifier }`
+ *   for issue rows; non-issue rows (`project`, `document`, …) have no
+ *   identifier and are skipped.
+ *
+ * Deduplicates and preserves insertion order so the prompt enumerates IDs
+ * in the same order they appear on screen.
+ */
+export function extractCandidateIdentifiers(rows) {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        if (row === null || typeof row !== "object")
+            continue;
+        const r = row;
+        const id = typeof r.identifier === "string" ? r.identifier : undefined;
+        if (!id)
+            continue;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Build the relation-candidate confirmation warning string, or `null` when
+ * the result set has no identifier-bearing rows (nothing to confirm).
+ *
+ * Shape (single line, structured-prose so a skill can match on the prefix):
+ *
+ *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
+ *     To link them as related: reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *
+ * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * convention in `outputWarning` callers — a stable token a skill / agent
+ * harness can grep for without parsing free-form prose.
+ */
+export function buildRelationCandidatePrompt(rows) {
+    const ids = extractCandidateIdentifiers(rows);
+    if (ids.length === 0)
+        return null;
+    const shown = ids.slice(0, MAX_CANDIDATES_IN_PROMPT);
+    const overflow = ids.length - shown.length;
+    const idList = overflow > 0
+        ? `${shown.join(", ")}, … (+${overflow} more)`
+        : shown.join(", ");
+    // Build two concrete example IDs from the head of the list so the
+    // "reply with the IDs you want linked" example is realistic for the
+    // caller's actual search rather than a fixed placeholder. Single-result
+    // case still reads naturally ("link DEV-1").
+    const example = shown.length >= 2 ? `link ${shown[0]} and ${shown[1]}` : `link ${shown[0]}`;
+    const noun = ids.length === 1 ? "candidate related issue" : "candidate related issues";
+    return (`relation_candidates: Found ${ids.length} ${noun} (${idList}). ` +
+        `To link them as related: reply with the IDs you want linked ` +
+        `(e.g. "${example}"). To skip linking: reply "no links". ` +
+        `(Agent-inferred IDs are blocked by auto-mode; user-named IDs pass — DEV-4494.)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",