@enrichlayer/el-linear 1.24.0 → 1.26.0

package/README.md

@@ -528,11 +528,48 @@ continue to accept their per-command formats too: `table`, `md`,
 `markdown`, `csv` — those go to the per-command rendering path. The
 global `summary` value works on every read/list command.
 
-`--format summary` does not compose with `--jq` (jq is JSON-only) or
-`--fields` (fields filter the JSON shape, not the rendered text). Use
+`--format summary` does not compose with `--jq` (jq is JSON-only). Use
 `--raw` together with `--format summary` to render a list envelope as a
 bare item-list rather than an envelope.
 
+#### `--fields` on `--format summary` — project additional columns
+
+`--fields` on a summary render is a **projection request**, not a
+JSON-shape filter (DEV-4750). For list outputs it sets the column set;
+for single-resource outputs it filters the labelled field block beneath
+the headline. Order is preserved: `--fields project,identifier,title`
+renders `PROJECT  ID  TITLE`.
+
+Currently wired through:
+
+| Resource | Defaults | Extras you can request |
+|----------|----------|------------------------|
+| `issues list` | `id, title, state, assignee` | `project, cycle, milestone, labels, url, priority, estimate, createdAt, updatedAt, team` |
+| `projects list` | `name, state, progress, lead` | `teams, target, url, updatedAt` |
+| `issues read` (single) | `state, assignee, project, cycle, milestone, labels, url` | `priority, estimate, created, updated` |
+| `projects read` (single) | `state, lead, teams, target, progress, url` | (filter only — no extras) |
+
+`identifier`, `id`, `title` and `name` are headline-only on single-resource summaries and are filtered out of the labelled block (they remain on the title line above). `status` is accepted as a synonym for `state`, `owner` for `assignee`, `targetDate` for `target`.
+
+```bash
+# issues list with project column (the gap that motivated DEV-4750):
+el-linear issues list --status "In Progress" --format summary \
+  --fields identifier,title,status,assignee,project
+# ID        TITLE                          STATE        ASSIGNEE    PROJECT
+# -----------------------------------------------------------------------------
+# DEV-1     Migrate auth middleware        In Progress  Alice       Auth Refactor
+# ...
+
+# projects list with teams column:
+el-linear projects list --format summary --fields name,state,progress,lead,teams
+# NAME                STATE    PROGRESS  LEAD     TEAMS
+# ---------------------------------------------------------
+# Auth Refactor       started  65%       Alice    DEV, FE
+# ...
+```
+
+Unrecognized field names are reported as a `_warnings:` line appended after the summary block (`fields_unprojectable: --format summary on issues list does not project foo, bar; ...`) — same signal scripts get on the JSON path. Resources whose summary formatter doesn't yet wire `--fields` (cycles, milestones, comments, teams, labels, users, documents, templates, attachments, releases, search results) emit the same warning and render their default summary.
+
 ### Windowed metadata (`WindowedMeta`)
 
 When a command returns less than its complete result set — because it
@@ -729,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/issue-id.js

@@ -21,7 +21,20 @@ import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 // Branch naming conventions — kept in sync with branch-name validators
 // elsewhere in the workspace. Any addition here is the single point of
 // truth that all skills rely on.
-const BRANCH_RE = /^(?:feature|fix|chore|refactor|dev)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
+//
+// Accepted prefixes (DEV-4777 adds bug/spike; DEV-4660 added codex; both
+// mirror tools-repo DEV-4417):
+//   feature | fix | chore | refactor | dev   — SOP-canonical + Linear-CLI direct
+//   bug | spike                              — sanctioned Linear type labels
+//   codex                                    — Codex-authored branches (codex/<TEAM>-<N>-slug)
+// New authoring surfaces (Codex, future agent prefixes) and sanctioned Linear
+// type labels (bug, spike) get first-class issue detection so commit guards,
+// MR descriptions, and session handoff don't go dark on a branch a human
+// wouldn't even notice was prefixed differently.
+//
+// Mirror of cli/el-git/src/commands/context.ts:BRANCH_RE in the
+// vertical-int/tools repo. If you change one, change the other.
+const BRANCH_RE = /^(?:feature|fix|chore|refactor|bug|spike|dev|codex)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
 export function parseBranchName(branch) {
     const m = branch.match(BRANCH_RE);
     if (!m) {

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/formatters/summary.d.ts

@@ -14,10 +14,16 @@
  * pretty-print. Field ordering and labels should not change across
  * patch releases without a CHANGELOG entry.
  */
-export declare function formatIssueSummary(issue: Record<string, unknown>): string;
-export declare function formatIssueList(issues: unknown[]): string;
-export declare function formatProjectSummary(project: Record<string, unknown>): string;
-export declare function formatProjectList(projects: unknown[]): string;
+/**
+ * Drain the formatter-level `_warnings` buffer. Returns the collected
+ * warnings and resets the queue. Called by `outputSuccess` after every
+ * summary render to surface unprojectable-field hints to scripts.
+ */
+export declare function drainSummaryFieldWarnings(): string[];
+export declare function formatIssueSummary(issue: Record<string, unknown>, fields?: string[]): string;
+export declare function formatIssueList(issues: unknown[], fields?: string[]): string;
+export declare function formatProjectSummary(project: Record<string, unknown>, fields?: string[]): string;
+export declare function formatProjectList(projects: unknown[], fields?: string[]): string;
 export declare function formatCommentSummary(comment: Record<string, unknown>): string;
 export declare function formatCommentList(comments: unknown[]): string;
 export declare function formatCycleSummary(cycle: Record<string, unknown>): string;
@@ -55,11 +61,19 @@ export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" |
  */
 export declare function inferKindFromPayload(value: unknown): ResourceKind;
 /**
- * Central dispatch: given a resource kind and payload, return the
- * formatted string. The payload for list kinds may be either the raw
- * array or a `{ data: [...] }` envelope — both are handled.
+ * Central dispatch: given a resource kind, payload, and optional `--fields`
+ * projection list, return the formatted string. The payload for list kinds
+ * may be either the raw array or a `{ data: [...] }` envelope — both are
+ * handled.
+ *
+ * `fields` is forwarded to formatters that wire `--fields` projection
+ * (issues, projects). For other kinds it's an opt-out path: we emit a
+ * `fields_unprojectable` warning and render defaults. The eventual
+ * direction is to wire projection through every list formatter; until
+ * then the warning gives consumers a deterministic signal instead of
+ * silently ignoring their flag.
  */
-export declare function dispatch(kind: ResourceKind, payload: unknown): string;
+export declare function dispatch(kind: ResourceKind, payload: unknown, fields?: string[]): string;
 /**
  * One-line confirmation render for the `--quiet` write path.
  *

package/dist/utils/formatters/summary.js

@@ -116,6 +116,109 @@ function joinLabels(v) {
         .filter((x) => x && x !== "—")
         .join(", ");
 }
+/**
+ * Select the ordered column set for a `--fields` request. Returns
+ * `{ columns, unprojectable }` so the caller can render and warn.
+ *
+ * Resolution order per requested name (case-insensitive):
+ *
+ * 1. Synonym lookup (`status` → `state`, `id` → `identifier`).
+ * 2. Match against a `defaults` column header.
+ * 3. Match against an `extras` entry.
+ * 4. Otherwise → `unprojectable`.
+ *
+ * The returned columns preserve the order the user requested. This is the
+ * contract: `--fields project,identifier,title` renders `PROJECT  ID  TITLE`.
+ */
+function selectColumns(projection, requested) {
+    const columns = [];
+    const unprojectable = [];
+    const synonyms = projection.synonyms ?? {};
+    const extras = projection.extras ?? {};
+    // Build a lowercased default-header lookup once.
+    const defaultByHeader = new Map();
+    for (const col of projection.defaults) {
+        defaultByHeader.set(col.header.toLowerCase(), col);
+    }
+    for (const raw of requested) {
+        const name = raw.trim().toLowerCase();
+        if (!name)
+            continue;
+        const canonical = synonyms[name] ?? name;
+        const fromDefaults = defaultByHeader.get(canonical);
+        if (fromDefaults) {
+            columns.push(fromDefaults);
+            continue;
+        }
+        const fromExtras = extras[canonical];
+        if (fromExtras) {
+            columns.push(fromExtras);
+            continue;
+        }
+        unprojectable.push(raw);
+    }
+    return { columns, unprojectable };
+}
+/**
+ * Filter the single-resource HeaderField list by user-requested field
+ * names (DEV-4750). Matches each requested name against the field's
+ * lowercased label and an optional synonym map. Unknown names are
+ * reported in `unprojectable[]`.
+ *
+ * Order of the returned fields preserves the user's request order. The
+ * implicit headline (identifier line for issues, name for projects) is
+ * the caller's responsibility — `--fields` only filters the labelled
+ * key/value block beneath it.
+ */
+function selectHeaderFields(defaults, requested, synonyms = {}) {
+    const byLabel = new Map();
+    for (const f of defaults) {
+        byLabel.set(f.label.toLowerCase(), f);
+    }
+    const fields = [];
+    const unprojectable = [];
+    for (const raw of requested) {
+        const name = raw.trim().toLowerCase();
+        if (!name)
+            continue;
+        const canonical = synonyms[name] ?? name;
+        const match = byLabel.get(canonical);
+        if (match) {
+            fields.push(match);
+        }
+        else {
+            unprojectable.push(raw);
+        }
+    }
+    return { fields, unprojectable };
+}
+/**
+ * Module-level sink for unprojectable `--fields` names surfaced from the
+ * summary formatters. The output dispatcher (`outputSuccess` in
+ * `utils/output.ts`) drains this between renders and forwards them to
+ * `outputWarning` so they ride out on the next JSON envelope's
+ * `_warnings`. Kept here rather than in output.ts so the formatter stays
+ * the single source of truth on what is and isn't projectable.
+ *
+ * Internal — consumers should call `drainSummaryFieldWarnings()`.
+ */
+const summaryFieldWarnings = [];
+function recordUnprojectable(resource, names) {
+    if (names.length === 0)
+        return;
+    summaryFieldWarnings.push(`fields_unprojectable: --format summary on ${resource} does not project ${names.join(", ")}; ` +
+        `use --format json --fields ${names.join(",")} or omit the field(s).`);
+}
+/**
+ * Drain the formatter-level `_warnings` buffer. Returns the collected
+ * warnings and resets the queue. Called by `outputSuccess` after every
+ * summary render to surface unprojectable-field hints to scripts.
+ */
+export function drainSummaryFieldWarnings() {
+    const out = [...summaryFieldWarnings];
+    summaryFieldWarnings.length = 0;
+    return out;
+}
 /**
  * Render a list of rows as a fixed-width text table with a header,
  * separator, body, and "<N> <noun>s" footer.
@@ -164,62 +267,219 @@ function renderHeader(fields) {
         .join("\n");
 }
 // ── issues ─────────────────────────────────────────────────────
-export function formatIssueSummary(issue) {
-    const identifier = s(issue.identifier);
-    const title = s(issue.title);
-    const headerLine = `${identifier}  ${title}`;
-    const fields = [
+/**
+ * Map a user-requested field name → the canonical lookup key used by
+ * `selectColumns` for the issues *list* formatter. Canonical keys are
+ * the lowercased column header (`id`, `title`, `state`, `assignee`)
+ * for defaults; extras are looked up by their key in
+ * `ISSUE_LIST_EXTRAS`.
+ *
+ * `identifier` (the JSON key) → `id` (the column header). `status` and
+ * `owner` are natural-language aliases for `state` and `assignee`.
+ *
+ * `prioritylabel` / `projectmilestone` are the raw JSON-field spellings a
+ * script author might reach for; they map to the `priority` / `milestone`
+ * column keys so the list formatter accepts the same names the
+ * single-resource formatter does (`ISSUE_SUMMARY_SYNONYMS`) — keeping the
+ * two surfaces in sync.
+ */
+const ISSUE_LIST_SYNONYMS = {
+    identifier: "id",
+    status: "state",
+    owner: "assignee",
+    prioritylabel: "priority",
+    projectmilestone: "milestone",
+};
+/**
+ * Map a user-requested field name → the canonical lowercased label used
+ * by the single-resource issue formatter. Single-resource labels are
+ * full words (`Created`, `Updated`), so `createdat` / `updatedat`
+ * (JSON-field spellings) need mapping. `status` / `owner` carry over.
+ */
+const ISSUE_SUMMARY_SYNONYMS = {
+    status: "state",
+    owner: "assignee",
+    createdat: "created",
+    updatedat: "updated",
+    prioritylabel: "priority",
+    projectmilestone: "milestone",
+};
+function buildIssueHeaderFields(issue) {
+    return [
         { label: "State", value: getName(issue.state) },
         { label: "Assignee", value: getName(issue.assignee) },
         { label: "Project", value: getName(issue.project) },
         { label: "Cycle", value: getName(issue.cycle) },
         { label: "Milestone", value: getName(issue.projectMilestone) },
         { label: "Labels", value: joinLabels(issue.labels) },
+        { label: "Priority", value: s(issue.priorityLabel ?? issue.priority) },
+        { label: "Estimate", value: s(issue.estimate) },
+        { label: "Created", value: s(issue.createdAt) },
+        { label: "Updated", value: s(issue.updatedAt) },
         { label: "URL", value: s(issue.url) },
     ];
-    const header = renderHeader(fields);
+}
+export function formatIssueSummary(issue, fields) {
+    const identifier = s(issue.identifier);
+    const title = s(issue.title);
+    const headerLine = `${identifier}  ${title}`;
+    const allFields = buildIssueHeaderFields(issue);
+    let headerFields;
+    if (fields && fields.length > 0) {
+        // `identifier` / `title` make up the implicit headline above —
+        // strip them from the user's request so a `--fields title,state`
+        // doesn't try to render "Title:" inside the labelled block.
+        const filtered = fields.filter((f) => {
+            const name = f.trim().toLowerCase();
+            return name !== "identifier" && name !== "id" && name !== "title";
+        });
+        const selected = selectHeaderFields(allFields, filtered, ISSUE_SUMMARY_SYNONYMS);
+        recordUnprojectable("issue", selected.unprojectable);
+        headerFields = selected.fields;
+    }
+    else {
+        // Default issue summary historically omits priority / estimate / dates —
+        // keep that surface stable unless the caller asks for those columns.
+        const defaultLabels = new Set([
+            "state",
+            "assignee",
+            "project",
+            "cycle",
+            "milestone",
+            "labels",
+            "url",
+        ]);
+        headerFields = allFields.filter((f) => defaultLabels.has(f.label.toLowerCase()));
+    }
+    const header = renderHeader(headerFields);
     const body = clipDescription(issue.description);
     const parts = [headerLine, header];
     if (body)
         parts.push("", body);
     return parts.filter((p) => p !== "").join("\n");
 }
-export function formatIssueList(issues) {
-    return renderTable(issues.map((raw) => asObj(raw) ?? {}), [
-        { header: "ID", minWidth: 2, extract: (i) => s(i.identifier) },
-        {
-            header: "TITLE",
-            minWidth: 5,
-            maxWidth: TITLE_TRUNC,
-            extract: (i) => s(i.title),
-        },
-        { header: "STATE", minWidth: 5, extract: (i) => getName(i.state) },
-        {
-            header: "ASSIGNEE",
-            minWidth: 8,
-            extract: (i) => getName(i.assignee),
+const ISSUE_LIST_DEFAULTS = [
+    { header: "ID", minWidth: 2, extract: (i) => s(i.identifier) },
+    {
+        header: "TITLE",
+        minWidth: 5,
+        maxWidth: TITLE_TRUNC,
+        extract: (i) => s(i.title),
+    },
+    { header: "STATE", minWidth: 5, extract: (i) => getName(i.state) },
+    {
+        header: "ASSIGNEE",
+        minWidth: 8,
+        extract: (i) => getName(i.assignee),
+    },
+];
+const ISSUE_LIST_EXTRAS = {
+    project: {
+        header: "PROJECT",
+        minWidth: 7,
+        maxWidth: 40,
+        extract: (i) => getName(i.project),
+    },
+    cycle: {
+        header: "CYCLE",
+        minWidth: 5,
+        maxWidth: 20,
+        extract: (i) => getName(i.cycle),
+    },
+    milestone: {
+        header: "MILESTONE",
+        minWidth: 9,
+        maxWidth: 30,
+        extract: (i) => getName(i.projectMilestone),
+    },
+    labels: {
+        header: "LABELS",
+        minWidth: 6,
+        maxWidth: 40,
+        extract: (i) => joinLabels(i.labels),
+    },
+    url: {
+        header: "URL",
+        minWidth: 3,
+        maxWidth: 60,
+        extract: (i) => s(i.url),
+    },
+    priority: {
+        header: "PRIORITY",
+        minWidth: 8,
+        extract: (i) => s(i.priorityLabel ?? i.priority),
+    },
+    estimate: {
+        header: "ESTIMATE",
+        minWidth: 8,
+        extract: (i) => s(i.estimate),
+    },
+    createdat: {
+        header: "CREATED",
+        minWidth: 7,
+        extract: (i) => s(i.createdAt).slice(0, 10),
+    },
+    updatedat: {
+        header: "UPDATED",
+        minWidth: 7,
+        extract: (i) => s(i.updatedAt).slice(0, 10),
+    },
+    team: {
+        header: "TEAM",
+        minWidth: 4,
+        extract: (i) => {
+            // issues carry team as either {key, name} or a bare key string.
+            const team = i.team;
+            const o = asObj(team);
+            if (o)
+                return s(o.key ?? o.name);
+            return s(team);
         },
-    ], { emptyText: "(no issues)", itemNoun: "issue" });
+    },
+};
+export function formatIssueList(issues, fields) {
+    const rows = issues.map((raw) => asObj(raw) ?? {});
+    let columns = ISSUE_LIST_DEFAULTS;
+    if (fields && fields.length > 0) {
+        const selected = selectColumns({
+            defaults: ISSUE_LIST_DEFAULTS,
+            extras: ISSUE_LIST_EXTRAS,
+            synonyms: ISSUE_LIST_SYNONYMS,
+        }, fields);
+        recordUnprojectable("issues list", selected.unprojectable);
+        // If every requested name was unprojectable, fall back to defaults
+        // so the user still sees something useful with the warning attached.
+        columns =
+            selected.columns.length > 0 ? selected.columns : ISSUE_LIST_DEFAULTS;
+    }
+    return renderTable(rows, columns, {
+        emptyText: "(no issues)",
+        itemNoun: "issue",
+    });
 }
 // ── projects ───────────────────────────────────────────────────
-export function formatProjectSummary(project) {
+const PROJECT_SYNONYMS = {
+    targetdate: "target",
+};
+function joinTeamKeys(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return "";
+    return value
+        .map((team) => {
+        const o = asObj(team);
+        return o ? s(o.key ?? o.name) : s(team);
+    })
+        .filter((x) => x && x !== "—")
+        .join(", ");
+}
+export function formatProjectSummary(project, fields) {
     const name = s(project.name);
     const headerLine = name;
-    const teams = (() => {
-        const t = project.teams;
-        if (!Array.isArray(t) || t.length === 0)
-            return "";
-        return t
-            .map((team) => {
-            const o = asObj(team);
-            return o ? s(o.key ?? o.name) : s(team);
-        })
-            .join(", ");
-    })();
+    const teams = joinTeamKeys(project.teams);
     const progress = typeof project.progress === "number"
         ? `${Math.round(project.progress * 100)}%`
         : "";
-    const fields = [
+    const allFields = [
         { label: "State", value: s(project.state) },
         { label: "Lead", value: getName(project.lead) },
         { label: "Teams", value: teams },
@@ -227,7 +487,20 @@ export function formatProjectSummary(project) {
         { label: "Progress", value: progress },
         { label: "URL", value: s(project.url) },
     ];
-    const header = renderHeader(fields);
+    let headerFields;
+    if (fields && fields.length > 0) {
+        // `name` is the implicit headline above; drop it from the request
+        // so a user passing `--fields name,teams` doesn't render "Name:" in
+        // the labelled block beneath.
+        const filtered = fields.filter((f) => f.trim().toLowerCase() !== "name");
+        const selected = selectHeaderFields(allFields, filtered, PROJECT_SYNONYMS);
+        recordUnprojectable("project", selected.unprojectable);
+        headerFields = selected.fields;
+    }
+    else {
+        headerFields = allFields;
+    }
+    const header = renderHeader(headerFields);
     const body = clipDescription(project.description);
     const parts = [headerLine, header];
     if (body)
@@ -237,18 +510,58 @@ export function formatProjectSummary(project) {
 function pct(value) {
     return typeof value === "number" ? `${Math.round(value * 100)}%` : "—";
 }
-export function formatProjectList(projects) {
-    return renderTable(projects.map((raw) => asObj(raw) ?? {}), [
-        {
-            header: "NAME",
-            minWidth: 4,
-            maxWidth: TITLE_TRUNC,
-            extract: (p) => s(p.name),
-        },
-        { header: "STATE", minWidth: 5, extract: (p) => s(p.state) },
-        { header: "PROGRESS", minWidth: 8, extract: (p) => pct(p.progress) },
-        { header: "LEAD", minWidth: 4, extract: (p) => getName(p.lead) },
-    ], { emptyText: "(no projects)", itemNoun: "project" });
+const PROJECT_LIST_DEFAULTS = [
+    {
+        header: "NAME",
+        minWidth: 4,
+        maxWidth: TITLE_TRUNC,
+        extract: (p) => s(p.name),
+    },
+    { header: "STATE", minWidth: 5, extract: (p) => s(p.state) },
+    { header: "PROGRESS", minWidth: 8, extract: (p) => pct(p.progress) },
+    { header: "LEAD", minWidth: 4, extract: (p) => getName(p.lead) },
+];
+const PROJECT_LIST_EXTRAS = {
+    teams: {
+        header: "TEAMS",
+        minWidth: 5,
+        maxWidth: 30,
+        extract: (p) => joinTeamKeys(p.teams),
+    },
+    target: {
+        header: "TARGET",
+        minWidth: 6,
+        extract: (p) => s(p.targetDate),
+    },
+    url: {
+        header: "URL",
+        minWidth: 3,
+        maxWidth: 60,
+        extract: (p) => s(p.url),
+    },
+    updatedat: {
+        header: "UPDATED",
+        minWidth: 7,
+        extract: (p) => s(p.updatedAt).slice(0, 10),
+    },
+};
+export function formatProjectList(projects, fields) {
+    const rows = projects.map((raw) => asObj(raw) ?? {});
+    let columns = PROJECT_LIST_DEFAULTS;
+    if (fields && fields.length > 0) {
+        const selected = selectColumns({
+            defaults: PROJECT_LIST_DEFAULTS,
+            extras: PROJECT_LIST_EXTRAS,
+            synonyms: PROJECT_SYNONYMS,
+        }, fields);
+        recordUnprojectable("projects list", selected.unprojectable);
+        columns =
+            selected.columns.length > 0 ? selected.columns : PROJECT_LIST_DEFAULTS;
+    }
+    return renderTable(rows, columns, {
+        emptyText: "(no projects)",
+        itemNoun: "project",
+    });
 }
 // ── comments ───────────────────────────────────────────────────
 export function formatCommentSummary(comment) {
@@ -694,11 +1007,30 @@ function inferListKind(items) {
     return "generic";
 }
 /**
- * Central dispatch: given a resource kind and payload, return the
- * formatted string. The payload for list kinds may be either the raw
- * array or a `{ data: [...] }` envelope — both are handled.
+ * Resources where `--fields` projection is wired through to the formatter
+ * (DEV-4750). For any other kind, passing `--fields` records a
+ * deterministic unprojectable warning and renders the default summary.
  */
-export function dispatch(kind, payload) {
+const FIELDS_PROJECTED = new Set([
+    "issue",
+    "issue-list",
+    "project",
+    "project-list",
+]);
+/**
+ * Central dispatch: given a resource kind, payload, and optional `--fields`
+ * projection list, return the formatted string. The payload for list kinds
+ * may be either the raw array or a `{ data: [...] }` envelope — both are
+ * handled.
+ *
+ * `fields` is forwarded to formatters that wire `--fields` projection
+ * (issues, projects). For other kinds it's an opt-out path: we emit a
+ * `fields_unprojectable` warning and render defaults. The eventual
+ * direction is to wire projection through every list formatter; until
+ * then the warning gives consumers a deterministic signal instead of
+ * silently ignoring their flag.
+ */
+export function dispatch(kind, payload, fields) {
     const obj = asObj(payload);
     const list = (() => {
         if (Array.isArray(payload))
@@ -707,15 +1039,19 @@ export function dispatch(kind, payload) {
             return obj.data;
         return null;
     })();
+    const hasFields = Boolean(fields && fields.length > 0);
+    if (hasFields && !FIELDS_PROJECTED.has(kind)) {
+        recordUnprojectable(kind === "generic" ? "this resource" : kind, fields);
+    }
     switch (kind) {
         case "issue":
-            return formatIssueSummary((obj ?? {}));
+            return formatIssueSummary((obj ?? {}), fields);
         case "issue-list":
-            return formatIssueList(list ?? []);
+            return formatIssueList(list ?? [], fields);
         case "project":
-            return formatProjectSummary((obj ?? {}));
+            return formatProjectSummary((obj ?? {}), fields);
         case "project-list":
-            return formatProjectList(list ?? []);
+            return formatProjectList(list ?? [], fields);
         case "comment":
             return formatCommentSummary((obj ?? {}));
         case "comment-list":

package/dist/utils/output.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { dispatch as dispatchSummary, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
+import { dispatch as dispatchSummary, drainSummaryFieldWarnings, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
 import { logger } from "./logger.js";
 import { sanitizeForLog } from "./sanitize-for-log.js";
 const warningBuffer = [];
@@ -56,9 +56,14 @@ function filterFields(obj, fields) {
  * the heuristic would fall through to "generic", silently breaking
  * the issue-list table. Caching the pre-filter shape keeps the
  * formatter accurate regardless of how the user pared the JSON.
+ *
+ * `fields` (when set) is forwarded to the formatter as a projection
+ * request (DEV-4750). For summary the JSON-shape `filterFields` is a
+ * no-op — the formatter needs the full object to extract nested values
+ * like `project.name` or `teams[].key`.
  */
-function emitSummary(payload, kind) {
-    logger.info(dispatchSummary(kind, payload));
+function emitSummary(payload, kind, fields) {
+    logger.info(dispatchSummary(kind, payload, fields ?? undefined));
 }
 /**
  * Typed wrapper around `outputSuccess` for list responses — builds the
@@ -95,17 +100,7 @@ export function outputSingle(data) {
     outputSuccess(data);
 }
 export function outputSuccess(data) {
-    const warnings = drainWarnings();
-    let output;
-    if (warnings.length > 0 &&
-        data !== null &&
-        typeof data === "object" &&
-        !Array.isArray(data)) {
-        output = { ...data, _warnings: warnings };
-    }
-    else {
-        output = data;
-    }
+    let output = data;
     // Capture the kind from the original envelope shape BEFORE --raw /
     // --fields stripping. Otherwise filtering away signature fields (e.g.
     // `title` on an issue) breaks shape inference and the summary
@@ -115,9 +110,13 @@ export function outputSuccess(data) {
     // precedence on the write path and independent of --raw / --fields / --jq
     // (those reshape the payload the flag exists to avoid) — so we emit from
     // the full pre-filter object, otherwise `--fields identifier` would strip
-    // the state/url formatLine needs and break shape inference.
+    // the state/url formatLine needs and break shape inference. Drain any
+    // buffered warnings to preserve pre-DEV-4750 behavior (they were
+    // silently dropped on the quiet path; the contract is "one line only").
     if (quietMode) {
         logger.info(formatLine(output));
+        drainWarnings();
+        drainSummaryFieldWarnings();
         return;
     }
     // --raw: unwrap { data: [...] } to just the array
@@ -130,8 +129,12 @@ export function outputSuccess(data) {
             output = obj.data;
         }
     }
-    // --fields: filter object keys (applies to array items or flat objects)
-    if (fieldsFilter) {
+    // --fields on summary format is a *projection request* — the formatter
+    // consumes it directly to extend/replace its column set (DEV-4750). The
+    // JSON-shape `filterFields` step would otherwise strip nested values
+    // (project.name, teams[].key) the formatter needs to render. Skip the
+    // JSON filter when summary is active and let the formatter do the work.
+    if (fieldsFilter && outputFormat !== "summary") {
         if (Array.isArray(output)) {
             output = filterFields(output, fieldsFilter);
         }
@@ -145,13 +148,35 @@ export function outputSuccess(data) {
             }
         }
     }
-    // summary format takes the post-raw / post-fields value and renders it
-    // as a human-readable block. We bypass the jq path because jq is a
-    // JSON-shape filter — it doesn't compose with text output.
+    // summary format takes the post-raw value and renders it as a
+    // human-readable block. We bypass the jq path because jq is a
+    // JSON-shape filter — it doesn't compose with text output. The
+    // formatter records any unprojectable `--fields` names; we drain
+    // them after dispatch and append them as `_warnings: …` lines so
+    // the signal is visible without breaking the text contract.
     if (outputFormat === "summary") {
-        emitSummary(output, inferredKind);
+        emitSummary(output, inferredKind, fieldsFilter);
+        const summaryWarnings = [
+            ...drainWarnings(),
+            ...drainSummaryFieldWarnings(),
+        ];
+        if (summaryWarnings.length > 0) {
+            for (const w of summaryWarnings) {
+                logger.info(`_warnings: ${w}`);
+            }
+        }
         return;
     }
+    // JSON path: drain buffered warnings (including any
+    // fields_unprojectable surfaced from a prior dispatch) and embed
+    // them as `_warnings` on the envelope.
+    const warnings = [...drainWarnings(), ...drainSummaryFieldWarnings()];
+    if (warnings.length > 0 &&
+        output !== null &&
+        typeof output === "object" &&
+        !Array.isArray(output)) {
+        output = { ...output, _warnings: warnings };
+    }
     if (jqFilter) {
         const json = JSON.stringify(output);
         // Normalize common shell-escape artifacts (zsh history expansion)

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.24.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",