Status: tracking document for the Linear adapter (experimental).
This document compares the Linear adapter against Linear's agent documentation:
- Developing the Agent Interaction: https://linear.app/developers/agent-interaction
- Signals: https://linear.app/developers/agent-signals
- Interaction Best Practices: https://linear.app/developers/agent-best-practices
- Getting Started: https://linear.app/developers/agents
The adapter implements the full agent activity surface (ADR 0008), generic
issue/comment participation (ADR 0013), rate-limit retry (ADR 0005), and
multi-tenant installs (ADR 0006). Linear's Agent API is itself in Developer
Preview upstream and may change. The remaining gaps below are operations a
production-quality agent may need that currently require the GraphQL escape
hatch rather than typed helpers.
| Linear capability | Current support | Notes |
|---|---|---|
| App actor auth with client credentials | Supported | Default scopes include read, write, app:mentionable, and app:assignable; startup verifies Linear granted all requested scopes. |
| Multi-tenant installs | Supported | Per-install webhook secrets and client credentials or pre-exchanged access tokens through chat.InstallStore (ADR 0006). Per-tenant lazy token refresh applies to client-credential installs only; a pre-exchanged AccessToken is used as-is until the install store supplies a replacement. |
| Agent session webhooks | Supported | Handles AgentSessionEvent created and prompted, including Linear-created assignment/delegation sessions. |
| Generic issue/comment participation | Supported | Comments that @-mention the app arrive on comment-kind threads (routing to OnNewMention while unsubscribed); Thread.Post replies as an issue comment (ADR 0013). |
| Inbox notification webhooks | Not normalized | Ignored by the adapter, matching upstream Chat SDK. |
| Mention-created sessions | Supported | Created sessions with agentSession.comment route to OnNewMention (on unsubscribed threads; normal routing precedence applies — a subscribed thread routes everything to OnSubscribedMessage). |
| Delegation-created sessions | Supported | Created sessions without agentSession.comment route to OnNewMention using promptContext and session id fallbacks. |
| Follow-up prompts | Supported | Prompted events route according to runtime subscription state and read agentActivity.body with a content-body fallback. |
| Agent activities (all five content types) | Supported | CreateAgentActivity sends thought, elicitation, action, response, and error with signal, signalMetadata, and ephemeral (only thought and action may be ephemeral). |
| Typed activity helpers | Supported | PostThought, PostAction, PostElicitation, PostError; Thread.Post creates the response activity. |
| Agent-to-human signals | Supported | auth and select signals with metadata pass through CreateAgentActivity / PostElicitation. |
| Human-to-agent stop signal | Supported | RawMessageFrom(ev.Message) exposes Signal / StopRequested(); see the routing caveat below. |
| Session updates | Supported | UpdateSession sets externalUrls and replaces the session plan array. |
| GraphQL escape hatch | Supported | GraphQL (single-install) and GraphQLForTenant (multi-tenant) reuse adapter auth and token refresh, surface GraphQL errors, and never expose tokens. |
| Proactive agent session creation | Supported | CreateSessionOnIssue / CreateSessionOnComment (plus ForTenant variants) wrap agentSessionCreateOnIssue / agentSessionCreateOnComment; the returned CreatedAgentSession carries the adapter's opaque ThreadID (#47). |
| Repository suggestions | Supported | SuggestRepositories wraps issueRepositorySuggestions with typed candidates and confidence-scored results (#48). |
| Worked UX examples | Supported | Auth/select elicitation loops, externalUrls updates, stop handling, proactive sessions, and repository suggestions are worked through in docs/how-to/linear-agent-sessions.md, extracted from the tested runnable example (#49). |
| Rate-limit handling | Supported | Bounded retry on HTTP 429 and GraphQL RATELIMITED with a typed *linear.RateLimited error (ADR 0005). |
| Message history read-through | Supported | chat.HistoryReader reads agent-session activities and issue-comment threads, newest-first with Before paging (ADR 0009). |
| Thread reconstruction | Supported | Stored Linear ThreadIDs (agent-session and comment kinds) reconstruct a Thread for later posting. |
| Tenant-correct thread identity | Supported | Opaque Linear thread ids include organization, issue, optional comment, and session ids. |
| Raw payload escape hatch | Supported | RawMessage preserves kind, action, session context, signal, signal metadata, source comment, and the full webhook envelope. |
Status: Missing typed helpers; possible via GraphQL.
Linear's best practices recommend moving delegated issues to a started
workflow state when work begins and setting the agent as Issue.delegate.
This likely belongs in a higher-level helper package or example workflow, not
the core adapter.
Status: Inherent limitation; needs an application-owned pattern.
The stop signal arrives as a prompted event on the same thread, so it is
serialized behind the thread lock like any other event: it cannot preempt a
handler that is already running (ConcurrencyDrop discards it during a
conflict; ConcurrencyQueue delivers it only after the in-flight handler
returns). There is no pre-lock interception hook, so Linear's Stop control
cannot drive active cancellation through this adapter today. Workable
patterns: split sessions into short handler turns that check StopRequested
at each turn boundary, or deliver the stop out-of-band (an application-owned
webhook/endpoint outside the runtime's serialized dispatch that sets a
cancellation flag handlers poll). The turn-boundary pattern is worked through
in docs/how-to/linear-agent-sessions.md
(confirmStop); the serialization limitation itself remains.
Status: Partial.
The adapter does not normalize Inbox Notification or Permission Change
webhooks. Assignment/delegation enters the runtime through Linear's
AgentSessionEvent created webhook.
Setup footgun: if direct mentions create sessions but assignment/delegation
does not, reinstall the app actor after confirming app:assignable is in the
authorization URL. Linear can keep stale install/app state after scope
changes; during dogfooding we had to delete and recreate the OAuth app before
assignment-created sessions started arriving.
Upstream Vercel Chat SDK precedent, checked on May 13, 2026: its Linear
adapter registers handlers for OAuthApp revocation, Comment,
AgentSessionEvent, and Reaction, and has no normalized callbacks for
Inbox Notification or Permission Change payloads. This adapter follows that
model. Reaction webhooks are not normalized here either.
Future work is sequenced on the public issue tracker, not in this document; this page tracks current capability status only. The former tracked gaps for proactive session creation (#47), repository suggestions (#48), and worked UX examples (#49) shipped as typed helpers and documented loops; see the Current Support table above.