RFC: native mentionable bgagent identity across interaction channels

Start by reading the shared comment trigger parser, channel adapter registry, and channel metadata contracts, then review the linked issues and ADR-018 for existing identity assumptions. Define the capability and identity model without implementing every channel; done means the RFC is accepted with documented per-channel results and follow-up implementation issues.

Primary area

Cross-cutting / multiple

Related issue or feature request

• #576 — Jira @bgagent comment-triggered PR iteration
• #587 — proposed GitHub @bgagent comment-triggered PR iteration
• #642 — Jira app identity for outbound actions
• ADR-018 — Linear agent-session as a future interaction channel

Summary

Define a channel capability and identity model that makes bgagent a native, discoverable mention target wherever the integration platform supports it. A user typing @ in Jira, Linear, GitHub, Slack, or a future channel should be able to select the ABCA agent from the platform's autocomplete UI instead of memorizing and manually typing a magic @bgagent string.

The selected mention should arrive at ABCA as structured platform identity metadata when available. Literal text parsing remains a compatibility fallback for channels or installations that cannot expose a native bot/app identity.

Use case and motivation

ABCA currently documents comments such as @bgagent update the README to iterate on an existing pull request. The backend primarily recognizes this through a token-bounded string match. That works after users learn the convention, but it is not reliably discoverable:

• The agent may not appear in the platform's @ autocomplete dropdown.
• Users cannot tell whether bgagent is an installed app, a real account, or only a magic command string.
• A mistyped handle silently becomes an ordinary comment or requires near-miss handling.
• App identity, outbound comment authorship, trigger identity, and human task attribution are easy to conflate.
• Each new channel risks implementing a different hardcoded mention convention.

The desired experience is:

1. The user types @ in a supported issue, thread, or channel.
2. The platform offers bgagent as a selectable app/bot/agent identity.
3. Selecting it creates the platform's native mention representation.
4. ABCA validates that structured identity and routes the remaining text to the appropriate workflow, such as coding/pr-iteration-v1.
5. ABCA acknowledges and reports progress using the same recognizable app identity while preserving the triggering human as the task owner.

Proposal

1. Define channel mention capabilities

Extend the channel adapter contract with explicit capabilities rather than assuming every channel behaves like a plain-text comment surface:

mention_identity:
  mode: native_agent | native_app | bot_user | text_fallback | unsupported
  stable_actor_id: channel-specific immutable identity
  display_name: bgagent
  handles: accepted textual aliases
  structured_mentions: true | false
  supports_autocomplete: true | false
  supports_thread_trigger: true | false

This may be configuration or an internal typed contract; the RFC should determine the final representation.

2. Prefer stable structured identity over display text

When a platform supplies mention entities, user IDs, app IDs, or event types, adapters should validate the configured stable actor identity. Display text such as @bgagent must not be the security or routing boundary because names can be renamed, spoofed, localized, or duplicated.

The shared comment-trigger parser remains a compatibility path for integrations without structured mentions and for existing installations during migration.

3. Specify channel behavior separately

• Linear: Preserve the existing actor=app installation with app:mentionable. Evaluate the native Agents API / AgentSessionEvent direction in ADR-018 once stable enough, while retaining the comment path during migration.
• Jira: Determine whether the installed Forge app identity from #642 can be exposed as a selectable mention target in Jira comments. If Forge app users cannot participate in Jira mention autocomplete, document the platform limitation and evaluate the narrowest supported alternative without creating misleading human-user attribution.
• GitHub: Determine whether a GitHub App bot identity can be selected in issue/PR comment autocomplete and whether a structured app/bot mention event exists. Do not assume a textual @bgagent handle maps to the installed GitHub App. Document whether a dedicated bot user would be required and its operational/security tradeoffs.
• Slack: Use the installed Slack app/bot user and native app_mention/structured mention events where supported. Preserve thread context and avoid treating example text or bot-authored messages as triggers.
• Future channels: Require each adapter to declare its capability and fallback explicitly.

4. Separate identities and responsibilities

Document and enforce the distinction between:

• Trigger identity: the installed app/bot/agent being mentioned.
• Human actor: the person who selected the mention and remains the ABCA task owner for authorization, audit, concurrency, and cost attribution.
• Outbound writer: the identity used for acknowledgement, progress, and terminal comments.
• Text handle: a presentation alias, not necessarily a stable platform identity.

5. Provide setup validation and operator visibility

Channel setup commands should verify native mention readiness where APIs permit it and report a capability summary, for example:

Mention identity: bgagent
Autocomplete: supported
Structured mention events: supported
PR iteration trigger: ready
Fallback text trigger: enabled

Add diagnostics to the relevant bgagent <channel> setup or status command rather than allowing an installation to appear healthy when users cannot actually discover or mention the agent.

6. Migration and compatibility

• Keep existing @bgagent string-trigger behavior initially.
• Deduplicate events if a native mention produces both a structured event and a generic comment webhook.
• Prevent self-trigger loops from ABCA-authored comments containing usage examples.
• Allow display-name changes without changing the stable actor identity.
• Decide whether textual aliases are configurable per installation or fixed compatibility names.

Acceptance criteria for follow-up implementation issues

• Each supported channel has a documented capability result: native autocomplete, structured mention, text fallback, or unsupported.
• Linear, Jira, GitHub, and Slack each receive a channel-specific implementation or documented limitation issue after the RFC decision.
• Where native mention identity is supported, setup verifies the installed identity and ABCA routes using stable structured metadata rather than display-text matching alone.
• Typing @ presents bgagent in the platform UI for every channel classified as supporting native autocomplete.
• The triggering human remains the task owner; selecting the bot/app does not collapse human and agent attribution.
• Native and fallback events cannot create duplicate tasks.
• Existing @bgagent comment workflows remain backward compatible through the migration period.

Out of scope

• Replacing labels as the initial issue/task trigger.
• Defining arbitrary natural-language commands after the mention.
• Making every platform offer capabilities its API does not support.
• Creating human-looking service accounts solely to simulate an app identity without an explicit security and lifecycle decision.
• Changing task ownership, billing attribution, or user-linking rules.
• Implementing every channel in this RFC itself; implementation should be split into approved channel-specific issues after the design is accepted.

Potential challenges

• Platforms use different identity primitives: app actors, bot users, Forge app users, GitHub Apps, and human/service accounts are not equivalent.
• Some platforms may render an app as an author but not allow users to mention it from autocomplete.
• Display names and handles can change, while webhook payloads may expose different IDs on different event types.
• A native mention can generate more than one webhook surface, creating duplicate-task risk.
• Dedicated bot-user fallbacks introduce credential rotation, licensing, offboarding, impersonation, and audit concerns.
• Native agent APIs such as Linear's may still be preview-only or impose acknowledgement timing constraints.
• Public/shared channels require authorization checks so mentionability does not imply permission to spend or mutate repositories.

Dependencies and integrations

• Shared comment trigger parsing and orchestration routing.
• Channel adapter registry and channel metadata contracts.
• Jira Forge app identity from #642.
• Jira iteration path from #576.
• GitHub iteration proposal #587.
• Linear OAuth app scopes (app:mentionable) and ADR-018.
• Slack app installation and event subscriptions.
• Existing channel user-linking and task attribution tables.

Alternative solutions

1. Keep literal @bgagent string matching everywhere. Simple, but undiscoverable, typo-prone, spoofable as presentation text, and increasingly inconsistent across channels.
2. Create a human service account on every platform. Often autocomplete-friendly, but adds licenses, passwords/tokens, lifecycle management, and misleading attribution. This should only be a documented channel-specific fallback after explicit review.
3. Use slash commands or labels only. More deterministic on some platforms but does not satisfy conversational PR iteration in existing issue threads.
4. Choose one universal implementation. Not viable because the platforms expose materially different bot, app, mention, and webhook models.

---

Note: Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

• RFC PR:
• Approved by:
• Reviewed by: