Support Linear agent sessions as a first-class mention surface

[vincelwt]

What this adds

Linear opens an agent session when a workspace member @mentions or delegates an issue to an installed app. Hub could not receive one: the Linear provider only understood issue and comment webhooks, and its authorization requested neither scope that makes an app mentionable. The practical result was that "mentioning" Paseo meant text-matching @paseo in a comment body, with no session UI, no progress, and a reply that arrived as a loose comment.

This makes Paseo a real Linear agent.

• AgentSessionEvent deliveries are accepted on the existing signed webhook (payload.agentSession, created and prompted) and routed to a new linear.agent_session trigger.
• The mention text becomes the prompt, so declared inputs parse straight from it and the existing named-agent select expression picks the agent: @Paseo agent=fast summarize this runs the fast choice.
• Hub narrates the run back as Linear activities: a thought on pickup, an external link to the run, the agent's own reply as the session response, and an error activity carrying the failure reason.
• ${{ paseo.context }} uses Linear's rendered promptContext, so session runs no longer backfill comment history through the API.

Notable decisions

No actor allowlist for sessions. validateTriggerLaunchSecurity requires a non-empty filters.from_users for externally sourced events. A session is exempt: Linear creates one only when a member addresses this app by name, delivers it to no other app, and the install already scoped which teams can see it. Requiring an allowlist would make the documented mention flow impossible to configure. Project, label, state, and actor filters all still apply when set.

Scopes are requested, not required. agentActivityCreate is rejected with Invalid scope: `write` required under the narrow comments:create grant, so write joins app:mentionable and app:assignable. Adding them to LINEAR_REQUIRED_SCOPES would flip every existing connection to requiresReauthorization and silently drop its issue and comment events, so they live in a separate LINEAR_AGENT_SCOPES set instead. Existing workspaces keep working and only miss mentions until they reconnect.

One response per session. Linear ends a session when it sees a response. The agent's own reply is the good one, so a small in-process tracker records that it arrived and the terminal hook only fills a gap rather than talking over it. In-memory is deliberate: a restart mid-run costs at most one duplicate closing line.

Activity failures never fail a run. Every emission is wrapped and reported; a session that cannot be narrated still runs to completion.

Linear answers a malformed GraphQL document with a bare 400, so the response body is now included in the thrown error. Without it every schema mismatch looked identical in the logs, which is how the write scope requirement above was found.

Verification

Unit tests cover normalization of both actions, webhook routing and signature rejection, filter behaviour including connection scoping, prompt and input parsing, context materialization without API reads, activity emission and its tolerance of Linear failures, and the session-aware reply path.

Also exercised end to end against a real Linear workspace on a self-hosted Hub:

• @Paseo appears in Linear's mention menu and opens a session.
• The session leaves its unresponsive state, shows the Hub link, and completes with the agent's answer.
• A failing run surfaces as an error activity with the reason.
• @Paseo agent=fast Reply with only your model name answered claude-haiku-4-5 while the trigger default is claude-opus-5, confirming per-mention agent selection.

Not included

Follow-up prompted events currently start a fresh execution rather than continuing the live agent, because the Hub to daemon protocol has no prompt message (HubExecutionControlActionSchema is interrupt and archive only). Conversational sessions and mapping permission_requested to an elicitation both depend on that addition and are better as a separate change spanning both repositories.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[vincelwt]

Closing: this is private Hub work, not for upstream.