Messaging & Notifications

Scion provides a robust messaging system that allows for bidirectional communication between humans and running agents. This is particularly useful for long-running tasks where an agent might need clarification, approval, or simply wants to notify you of its progress.

The Inbox Tray

Design Record

For an in-depth look at the architecture, semantic contract, and design invariants underlying the Scion messaging system, see the Conversation Model Design and its companion Defect Inventory in the project repository.

In the Web Dashboard, the Inbox Tray provides a centralized view of all messages sent by your agents.

• Unread Badges: The top navigation bar displays a badge indicating the number of unread messages across all your agents.
• Mark as Read: You can mark individual messages or all messages as read, helping you keep track of what needs your attention.
• Contextual Links: Messages in the tray often link directly to the agent that sent them, allowing you to quickly jump in and provide the requested input or review the agent’s work.

Native Web Chat

Scion features an interactive, top-level Native Web Chat interface in the Web Dashboard (enabled via the web.native_chat feature flag). Rather than being isolated inside a single tab, chat is promoted to a top-level workspace view (a fourth ShellType in the SPA) that provides a cohesive, real-time collaborative environment for humans and agents.

Core Layout & Navigation

• Project-Scoped Spaces & Shared Threads: Chat is organized into distinct spaces scoped to specific Projects. Within a project-scoped space, users and agents participate in shared discussion threads, creating focused hubs of collaboration.
• Project Context Preservation (Dashboard ↔ Chat Toggle): When you switch between dashboard and chat modes using the navigation icons in the header, Scion automatically maintains your active project context to avoid losing your work state:
  • Dashboard → Chat: Clicking the Chat icon while on a project-scoped dashboard page (e.g., /projects/:id/... or inside an agent view) takes you straight to that project’s chat space (/chat/space/:id).
  • Chat → Dashboard: Clicking the Dashboard icon while in a project chat space (/chat/space/:id/... or /chat/:slug/...) takes you directly back to that project’s detail page (/projects/:id).
  • DMs / General Chat: If there is no active project context (such as when in Direct Messages or bare /chat), the toggle falls back to the top-level dashboard /.
• Direct Messaging (DMs): In addition to collaborative project spaces, the chat interface supports robust 1-on-1 Direct Messages (DMs). This includes both human-to-human (H2H) communication between team members and human-to-agent (H2A) chats. DMs are structured as a “global pair”—a single, consolidated thread per participant pair.
  • DM Promotion to Shared Threads: When a 1-on-1 Direct Message with an agent develops context useful for the broader team, you can promote the DM conversation into a Shared Space Thread. This atomic operation safely re-keys the messages and streams the transition live to all clients via SSE without a page reload. Use the promotion button located in the DM header.
• Members Sidebar, Presence & Typing: A right-hand members sidebar lists all participants in the active project space or DM. This includes real-time online presence indicators (active, away, offline) and live typing indicators to show when a team member or agent is actively composing a message. The thread’s default agent is listed first in the AGENTS section of the sidebar, under a Thread default sub-heading. When a thread has a default agent, the thread header shows terminal and graph buttons for that agent, the same as a DM with an agent. Members can be filtered (All/Unread toggle) and sorted (Alphabetical or Recent Activity).
• The Thread Rail & Mobile Swipe Navigation: A left-hand navigation sidebar lists all active chat spaces, threads, and DMs. On mobile viewports, the rail supports native swipe gestures for fluid, app-like drawer navigation.
• Chat/Log Toggle: Located on the main scion-chat-thread panel, this toggle lets you switch between a clean, dialogue-focused Chat view and a live Execution Log stream for that agent.
• Zero-Reload Navigation: Move between threads, project spaces, and configuration pages instantly with deep-linking support and no full-page reloads, ensuring no interruption to your active chat context or log streams.
• Markdown & Rich Rendering: Chat messages support fully-featured real-time Markdown rendering inside chat bubbles (including syntax-highlighted code fences, tables, and nested lists) for highly readable development chats.
• Clickable File Paths: File paths starting with /workspace/... or /scion-volumes/... render as interactive links. Clicking them immediately opens an on-demand file viewer dialog, fetching the current file content directly from the existing workspace and shared-directory APIs without leaving the chat context.
• iOS & Platform Tailoring: The layout incorporates specific styling adjustments for iOS devices, delivering polished rendering and input behavior under Safari and other mobile browsers.
• Config Toggle: Top-level native chat can be turned on or off globally by administrators using a single configuration key (web.native_chat feature flag) or via the Admin interface.

---

Advanced Collaboration & Productivity

The native web chat includes a complete suite of collaboration and developer productivity tools (Phases 0–5):

1. Message Context Menu

Right-clicking a message (on desktop) or tapping it (on touch devices without hover) opens a contextual context menu providing several per-message actions. On touch devices, taps on links, buttons, mentions, and reply previews keep their normal behavior:

• Reply / Quote: Quote a previous message with full backend support for reply-threading, maintaining clear context in fast-moving development discussions.
• Edit / Delete: Edit or delete your own messages.
• Copy Permalink: Generate a direct link to any message in the thread.

2. Advanced Organization

• Thread Pinning: Pin critical threads to the top of the thread rail for easy access.
• Conversation Muting: Mute busy threads or spaces to suppress notifications while keeping the discussion active.
• Thread Drag-and-Drop Reorder: Reorder threads within the rail by dragging and dropping them (native HTML5 drag API). Organize related threads into named collapsible groups that you can expand or collapse to manage long thread lists. Group membership and ordering are persisted server-side via user preferences.
• Space Emoji Icons: Assign optional emoji icons to spaces, stored in project annotations, for quick visual identification in the thread rail.
• Layout Density: Choose between Dense and Comfortable layout modes via the density toggle. Dense mode reduces whitespace for maximum information density; Comfortable mode provides more breathing room for extended reading.

3. High-Density Developer Utilities

• Cmd/Ctrl-K Conversation Switcher: Trigger a keyboard-driven switcher to jump between spaces, threads, and DMs instantly without leaving your keyboard.
• Jump-to-Message from Search: Clicking a search result automatically scrolls to the target message, even when it falls outside the currently loaded message buffer. The target message receives a highlight-flash animation, and a “Jump to latest” button appears to return to the live message stream.
• Unread Divider with Watermark: An unread indicator bar automatically segments new messages since your last visit, including a watermark to ensure you never miss a transition. A thread with unread messages opens scrolled to the New messages divider rather than to the bottom.
• Day Separators: Messages, including inter-agent messages, are split by day with the same date separator used throughout the thread.
• Rich Agent Output Rendering: Dispatched agents can render complex interactive payloads directly inside the chat, including structural diffs, test suite results, and interactive JSON/YAML tree-structures.
• Collapsed Agent-to-Agent Messages: To keep threads readable, background agent-to-agent messages (visible under the Full density filter) are collapsed into a compact, click-to-expand pill. When expanded, these messages are displayed with 2-line truncation. If a message is truncated, an expand icon (‘arrows-angle-expand’) appears next to it, allowing you to open a full-screen Markdown-rendered dialog overlay.
• Conversation Export: Export any collaborative thread via the export dropdown in the chat header:
  • Download as Markdown for archiving or sharing agent reasoning.
  • Print / Save as PDF for offline review.
  • Copy to Clipboard (HTML + plain text) for quick pasting into other tools. All exported content is HTML-escaped for safe rendering.
• Send-to-Agent Context & Slash Commands: Fast-track your workflow with slash commands (e.g. /start, /help) and easily forward snippets or whole discussions directly to your agents as contextual guidance.

---

Push Notifications & Presence

• Real-Time Browser Notifications: Stay informed of @mentions and incoming DMs with native browser push notifications.
• Smart Suppression: Notifications are mute-aware and automatically suppressed for active conversations (threads you are currently looking at) to prevent alert fatigue.
• Chat Chime: A short two-tone chime plays when a chat message arrives from someone else. Your own messages never chime. The chime plays at most once every 2 seconds and does not depend on browser notification permission. Turn it off globally with Chat chime sound in your profile’s notification settings. To turn it off for one project, choose Chime on/off from the thread rail’s options menu. Both preferences are stored in the browser. If the browser’s autoplay policy blocks audio, no sound plays.
• Unread Badges: The tab title dynamically updates with an unread badge count when you are away from the tab.
• Per-Thread Draft Persistence: Drafts are saved locally per-thread, so if you switch threads or close the tab, your unsent message remains waiting when you return.

---

Advanced Attachment Management

The web composer features a security-hardened, developer-friendly file upload system:

• Executable Deny-List Strategy: To maximize flexibility for developers, attachment uploads use a security-first deny-list rather than a restrictive mime-type allow-list. It blocks executable binaries/scripts but permits 34+ developer file types (including configuration files, source code, and data structures).
• Paste-to-Upload: Paste images or file content directly from your clipboard into the composer for instant attachment.
• Markdown Attachment Rendering: Markdown files uploaded as attachments render directly within the chat bubble, featuring a source/preview toggle and a one-click clipboard copy.
• Partial Success Reporting: When uploading multiple files simultaneously, the system supports partial success—successful uploads are staged instantly while failed individual files report explicit inline errors.

---

Performance & Safety Safeguards

• Token-Bucket Rate Limiting: Per-sender token-bucket rate limits prevent message flooding, ensuring platform stability and protecting backend model endpoints.
• Touch-Friendly Composer: On touch devices without hover, Enter inserts a newline instead of sending, because there is no Shift+Enter. Use the Send button to send.
• 16K Input Character Limit: A robust 16,000-character limit is enforced in the composer, protecting token context limits.
• SSE Direct Append & Real-Time Attachments: Chat messages stream via Server-Sent Events (SSE) using direct-append logic, providing lag-free typing rendering. Additionally, attachment previews render immediately on incoming SSE messages, ensuring the user interface instantly displays attachment references without waiting for subsequent user-triggered renders.
• Idempotency Keys: Client-side idempotency keys eliminate duplicate messages during transient connection drops or retry states.
• Honest Delivery Status: A message to an agent that is not running is marked Agent unreachable instead of Delivered. If the Runtime Broker fails to deliver a message to the agent’s terminal, it makes up to 3 attempts in total, but never retries once part of the text has already reached the terminal (so the agent does not see it twice), and a user sender sees the failure live in the chat. Messages to an agent that has been deleted fail right away instead of waiting in the queue. Failed messages are purged after 7 days.
• Cursor-Based Scrollback Pagination: Solved previous scroll-jump issues and cursor-mismatches. Scrollback pagination and scroll-to-bottom locks operate smoothly as history loads.

Interactive @-Mentions & Autocomplete

When writing instructions, you can easily pull other agents into the thread:

• Autocomplete Popup: Typing @ in the chat input opens a dropdown list of active agents in the project. The list supports fuzzy-matching as you type, and full keyboard navigation (arrow keys to select, Enter to insert).
• Code-Fence Guard: The mention autocomplete is smart — it automatically disables itself when typing inside Markdown code fences (e.g., ``` blocks) so code snippets don’t trigger unwanted dropdowns.
• Mention Leak Protection: Direct mentions are safely partitioned, resolving a previous bug where mentions would leak into the default agent tab.
• Fan-Out Restrictions: For platform stability, a single message is fanned out to a maximum of 10 recipients per @-mention broadcast.
• Bidirectional Mention Translation: Mentions are automatically translated between the formats used by agents and the web chat. In the chat UI, mentions display as @firstname-lastname; when delivered to agents, they are translated to @email format, and vice versa. This ensures both humans and agents see the most natural identifier for their context.
• Composer Default-Agent Disambiguation: When sending messages in collaborative project spaces with multiple active agents, typing a message without an explicit target or @-mention triggers a smart disambiguation interface. This guides the user to select which agent the message should target (or fall back to the project’s configured default agent), keeping routing unambiguous and conversations clear.

Cross-Channel Coherence

If you use external messaging systems alongside the Web Dashboard, Scion ensures that conversations remain coherent across all channels:

• Broker Inbound Persistence: Inbound messages received from external message brokers (such as Discord or Teams) are persisted in the Hub’s main database, making them instantly visible in the Web Chat.
• Reply Affinity: Scion tracks user, project, and agent reply affinity so that replies are routed back to the initiating channel.
• TouchThread & Broadcast Propagation: Messages and read states propagate smoothly across surfaces via TouchThread and Broadcasted events, ensuring that reading or replying to a thread on Discord or Teams instantly syncs the unread badges in your Web Dashboard.

CLI Message Management

You can also interact with the messaging system directly from the CLI using the scion messages command (aliases: msgs, inbox).

# View unread messages
scion messages

# View all messages for a specific agent
scion messages --agent <agent-name>

# Mark a message as read
scion messages read <message-id>

Sending Messages

Use scion message to send messages. The preferred addressing form uses @:

# Send to an agent (preferred form)
scion message @tech-lead "Please review the auth module."

# Send a global DM to a user by email
scion message @preston@example.com "Build is green, ready for review."

# Legacy forms (still work but @-form is preferred)
scion message agent:tech-lead "Please review the auth module."

# Attach a file
scion message @tech-lead "See the test results." --attach ./results.json

# Read message body from a file (useful for long messages or scripted workflows)
scion message @tech-lead --body-file ./review-notes.md

Message Formatting

The scion message CLI delivers the body argument verbatim — it performs no escape expansion, no markdown rendering, and no character substitution. Whatever bytes you pass are exactly what the recipient sees.

To include newlines, use real newlines inside shell quoted strings or heredocs. Do not use JSON-encoded bodies or literal backslash-n (\n) sequences — those will appear as literal characters in the delivered message.

Correct — real newlines in a quoted string:

scion message --non-interactive @reviewer "PR #42 is ready for review.

Branch: fix/auth-bug
CI: all green"

Correct — heredoc for longer messages:

scion message --non-interactive @reviewer "$(cat <<'EOF'
PR #42 is ready for review.

Branch: fix/auth-bug
CI: all green
EOF
)"

Wrong — JSON-encoded body with literal \n:

# BAD: literal \n chars appear in the delivered message
scion message --non-interactive @reviewer "PR #42 is ready for review.\n\nBranch: fix/auth-bug\nCI: all green"

Related Commands

• scion broadcast: Send a message to all agents in the current project, or use --all for a global broadcast. The --broadcast and --all flags on scion message have been removed; use this command instead.
• scion keys: Send raw keystrokes to an agent’s tmux terminal (e.g., scion keys editor "ENTER"), with no envelope and no automatic Enter. Useful for unblocking interactive prompts. Works for Hub-managed agents as well as local ones. When run by an agent, it can only target agents in the agent’s own project — cross-project targets are refused; a human operator using --project can still target other projects. This replaces the old --raw flag on scion message.

Conversation Management

The scion conversation command (alias conv) provides a surface-agnostic interface for managing conversations — the containers for message threads that span across the web chat, external channels, and CLI. Requires Hub mode.

Conversations are referenced using one of three forms:

• conv:<uuid> — by conversation ID.
• @<agent-name> — resolves the direct conversation with the named agent.
• #<thread-name> — resolves a named group conversation.

# List your conversations
scion conversation list

# View messages in a specific conversation
scion conversation messages @tech-lead

# Create a new group conversation
scion conversation create "sprint-planning"

# Set a default agent for a conversation
scion conversation set-default "#sprint-planning" agent-id

# Catch up on recent messages (last 2 hours)
scion conversation catch-up @tech-lead --since 2h

# Retrieve a single message by ID
scion conversation get-message conv:a1b2c3d4-... msg-uuid-here

# List participants in a conversation
scion conversation participants "#sprint-planning"

# Join or leave a conversation
scion conversation join "#sprint-planning" user user-id
scion conversation leave "#sprint-planning"

For full flag details, see the CLI Reference.

Discord

Scion supports Discord through two separate integration pathways:

• Bidirectional Discord Bot: Interact with agents directly from Discord channels using slash commands under /scion (e.g., /scion setup to link channels, /scion default to set routing targets, /scion agents to check state). Agent replies are pushed back into the Discord channel with their own name and RoboHash-generated avatar.
• Outbound Webhook Notifications: A simpler, outbound-only mechanism where agents push status updates, alerts, and ask_user requests to a designated Discord channel. Messages are color-coded by severity, and urgent notifications can trigger @user or @role mentions.

For a full setup guide and configuration options, see External Channels.

Telegram

Scion also supports bidirectional messaging over Telegram: message your agents from a Telegram group and receive their replies in the chat. For a step-by-step Workstation setup, see Setting Up Telegram; for how it fits alongside other channels, see External Channels.

Agent ask_user Integration

When an agent uses the ask_user tool (or similar mechanism depending on the harness), Scion automatically performs two actions:

1. State Update: The agent’s state changes to WAITING_FOR_INPUT.
2. Explicit Message: A persistent message is generated and delivered to your Inbox Tray (and Discord, if configured), clearly stating what the agent needs.

Real-Time Delivery

Messages are delivered in real-time to the Web Dashboard via Server-Sent Events (SSE). The Messages Tab on the individual agent detail page provides a real-time stream of all communication with that specific agent.

Delivery failures

Messages to agents are never silently dropped:

• Non-running recipients. A message is rejected if the recipient agent is not running (suspended, stopped, in error, or still starting). For direct messages, human or agent, the send fails immediately with a 409 error. Pass --wake to resume a suspended agent and then deliver. Broadcast, group, and message-broker deliveries are rejected per recipient. A sending agent gets a DELIVERY_FAILED system notice (“Message delivery to <agent> failed: …”) for each rejected recipient.
• Late broker failures. A Runtime Broker may accept a message into its short delivery buffer and then fail to deliver it, for example because the container has gone away. The broker reports this to the Hub. The Hub marks the message failed rather than leaving it dispatched, and notifies the sending agent.

Message Authorization & Modes

Full Reference

For the complete authorization reference — including mode decision tables, cross-project messaging controls, piercing rules, denial codes, and the API for changing modes — see Messaging Authorization.

Every agent is protected by a Message Mode that controls which users and other agents can send messages to it. An agent’s message mode can be managed in several ways:

• Web Dashboard: Use the mode controls on the agent detail page.
• CLI: Use scion set-message-mode <agent-name> <mode>, or set the initial mode at creation time with scion start --message-mode <mode>.
• Agent self-service: Full-role agents can call set_message_mode programmatically to adjust their own or their children’s message modes.

The available modes are:

• Project Mode (Default): Any user with the agent:message permission in the project can message the agent. Any peer agent in the project (that is not restricted by lineage mode) can also message it. The most permissive mode. Note that the default project-member role does not include agent:message — messaging requires an owner, admin, or ancestry relationship with the agent (i.e., the agent’s creator or their ancestors). This aligns messaging authorization with the terminal attach permission gate.
• Hub Mode: Behaves like Project mode within the agent’s own project, and additionally allows the agent to send direct messages across project boundaries when cross-project messaging is enabled. A project-mode agent can receive a cross-project DM but cannot reply across the boundary until granted Hub mode.
• Branch Mode: Only users in the agent’s ancestry chain (its creator and their ancestors), plus the agent’s direct parent and child agents, can message it.
• Lineage Mode: Strictly restricts messaging to users in the agent’s ancestry chain (its creator and their ancestors). No agent-to-agent messaging is permitted.
• None Mode: Seals the agent from all messaging except system-plane notices. No users and no agents can message a none-mode agent through normal paths.

Piercing

Highly privileged users can bypass an agent’s message mode restrictions. This is called piercing.

• Project Owners can pierce Branch and Lineage modes.
• Super-admins pierce all modes, including None mode. Piercing applies only to user identities — it is never inherited by an owner’s agents.

The Web Dashboard displays reachability indicators (e.g., whether you can message a specific agent) based on the computed messageability, which takes into account the agent’s mode, your ancestry relationship to it, and any piercing privileges.

---

Cross-Project Messaging

Agents can send direct messages across project boundaries when all three independent controls permit it. Cross-project messaging is off by default; all three must be enabled for a message to be delivered.

The Three-Control System

Control	Setting	Default	Who can change it
Hub availability	cross_project_messaging_enabled (Hub messaging settings)	false	Hub administrator
Agent outbound reach	Agent message mode set to hub	project	Agent owner or project admin
Receiving project inbound policy	crossProjectInbound on the destination project	none	Project owner or Hub administrator

Project Inbound Policy

Each project controls which cross-project messages it accepts via its crossProjectInbound setting:

Policy	Meaning
none	Accept no agent messages from other projects (default).
members	Accept an external agent only when its originating human is an active member of the receiving project.
any	Accept an eligible agent from any project on the Hub.

Enabling Cross-Project Messaging

1. Hub administrator enables the feature globally:

   scion hub messaging set --cross-project-enabled=true --revision <N>

2. Project owner sets an inbound policy on the receiving project:

   scion project messaging set --project <project> --policy members --revision <N>

3. Grant hub mode to the sending agent:

   scion set-message-mode <agent-name> hub

4. Send a cross-project message:

   scion message --project <target-project> @<agent-name> "message"

Denial Codes

When a cross-project message is rejected, the system returns a specific denial code explaining the reason:

Code	Meaning
cross_project_disabled	Cross-project messaging is disabled by the Hub administrator.
cross_project_sender_mode	The sender must be in Hub mode to send cross-project messages.
cross_project_target_mode	The recipient must be in Project or Hub mode to receive cross-project messages.
cross_project_inbound_none	The recipient’s project does not accept messages from external agents.
cross_project_origin_not_member	The sender’s originating user is not a member of the recipient’s project.
cross_project_untrusted_origin	The sender’s identity origin could not be verified.
cross_project_surface_unsupported	Cross-project messaging is not supported for this conversation type (e.g., group conversations).

Hub Mode Grant Guard

An agent can only grant hub mode to another agent when the calling agent is itself in hub mode, has the full authorization role, and holds the project:agent:set_message_mode scope. Human callers (project owners, super-admins) can seed hub mode directly without these restrictions.

---

Developer Guide & Best Practices

For developers authoring agents and custom orchestrators, Scion’s messaging system follows a set of strict protocol rules and architectural patterns.

1. Message Length Limits

Scion maintains different limits depending on the recipient type:

• User-Directed Messages (Agent-to-Human): Limited to 2,000 Unicode characters (runes). Each CJK character or emoji counts as a single character. Exceeding this limit causes scion message to fail with exit code 1 and print: validation_error: message exceeds 2000 character limit
  • Tip: If you have a long message or log to send to a user, split it into multiple messages under 1,800 characters, or write the full content to a shared scratchpad file and send the filepath.
• Agent-to-Agent Messages: No enforced length cap in code. You can send larger payloads safely between agents.

2. Inbound Message Type Discrimination

When an agent receives an inbound message, it arrives wrapped in standard delimiters and includes metadata:

---BEGIN SCION MESSAGE---
sender: agent:tech-lead
type: instruction
thread_id: 1234
---
Write a unit test for the auth package.
---END SCION MESSAGE---

Always check the type field before acting or replying:

Type	Meaning	Action Required
instruction	Direct instruction sent to you.	Read and act on it.
reply	A reply to a message you previously sent. Routes to the original sender agent, not the thread default. Includes reply_context metadata with the first 32 characters of the replied-to message.	Read and act on it like an instruction.
state-change	A notification that another agent changed phase (e.g. stopped or stalled).	Treat as FYI — no reply or action needed.
input-needed	A broadcast that an agent has called sciontool status ask_user.	See handling rules below.
mention	You were CC’d or mentioned in a message.	Treat as FYI unless explicitly directed otherwise.
group-set	An @-mention targeting multiple agents.	Act on it like an instruction.
system	Operational notices generated by the Hub (e.g. delivery-failed, scheduler, port-forward).	Treat as FYI or follow troubleshooting instructions in the notice.

Conversation Model Migration

The messaging system has transitioned to a conversation-based model where messages carry a conversation_id and are addressed to conversations rather than agents directly. The scion conversation CLI command (alias conv) provides full management of conversations — listing, viewing messages, creating group conversations, managing participants, and more (see Conversation Management above). During this transition, inbound messages continue to arrive with the type fields described above, and agents should continue to discriminate on the type field as documented.

To migrate historical messages that predate the conversation model, administrators can use the scion server backfill command.

Safe Idempotent Backfilling

The backfill process is safe and fully idempotent — messages that are already attributed to a conversation are skipped automatically. By default, the backfill runs in a safe dry-run mode, allowing operators to preview what would be migrated. The --execute flag must be explicitly passed to commit changes to the database.

Compound Keyset Resumability (DEF-81)

If a backfill operation is interrupted, it can be safely resumed from its last page of progress using the --checkpoint flag with the cursor printed in the previous run’s report. The backfill uses a robust compound keyset cursor (created, id) (rather than a strictly-greater-than timestamp). This eliminates the potential for permanent row loss on resume, ensuring that any messages sharing identical timestamps are correctly processed and never skipped during resumes.

Handling input-needed Notifications

When an agent signals WAITING_FOR_INPUT (by calling sciontool status ask_user), a notification of type input-needed is dispatched to all subscribed agents (including its creator).

• Parent Agent Role: If you are the parent agent that created the waiting agent, you may be the intended respondent. Use scion message @<name> to reply with the answer.
• Peer Agent Rule: Unrelated peer agents should NOT reply to input-needed notifications. Answering a peer’s input prompt wastes context tokens, causes false loop signals, and violates project-scoped boundaries. To request a peer’s input, always send an explicit instruction instead.

Project-Scoped Message Isolation

When using slug-based query paths or addressing agents via agent:<name> (e.g., scion message agent:<name>), Scion strictly scopes all message queries and deliveries by the active ProjectID. This ensures that even if different projects contain agents with identical names or slugs, messages are completely isolated within each project and never leak across project boundaries.

3. Subscription Management and Agent Self-Service

• Automatic Subscription: The --notify flag on scion start is deprecated. When you start a sub-agent, Scion automatically registers your subscription via creation ancestry.
• Explicit Messaging Subscription: Use the --notify flag on scion message only when you need to subscribe to notifications from a peer agent that you did not create.
• Agent Self-Service Subscriptions: Running agents in Hosted mode are empowered to programmatically manage their own notification subscriptions. Previously restricted to administrative users (returning a 403 Forbidden for agents), agents with appropriate API credentials can now perform the following operations:
  • CRUD Operations: Live agents can list, create, update, and delete their own subscriptions via the Hub API or client utilities.
  • Identity Qualification: To prevent cross-project security leaks, every subscription request is qualified by the agent’s specific (project, slug) coordinates.
  • Granular Scopes: Authorization gates require the agent token to hold the project:read scope for reading subscriptions and the project:agent:notify scope for writing (creating, updating, or deleting) subscriptions.
  • Ownership Constraints: Acknowledging notifications or modifying/deleting existing subscriptions strictly requires ownership validation, meaning an agent can only modify or acknowledge subscriptions that target or belong to itself.

4. Security Controls for Direct Messages & Broadcasts

Scion employs strict, ingress-level security controls and invariants for Direct Messages (DMs) and Broadcasts to prevent spoofing, cross-project injection, and message divergence:

• Server-Side Sender Identity & Derivation: Sender identity is forced server-side based on the authenticated request context, completely ignoring any sender claims in the payload. Furthermore, DM conversation keys are derived dynamically from the authenticated caller rather than trusting the payload, closing spoofed-sender conversation-selection vectors.
• Canonical DM Key Enforcement: Thread IDs (used as DM keys) undergo strict canonicality enforcement. Non-canonical kinds and UUIDs are rejected immediately at derivation without silent normalization, ensuring precise routing.
• Participant Guard Consolidation: A unified participant guard (CheckDMParticipantKey) protects all DM ingresses (adding/ensuring participants or merging conversations). This strict invariant guarantees that participant records cannot diverge from their canonical thread keys.
• Broadcast Authorization: Project membership is strictly required and enforced for all broadcast calls.
• Publish Gating & Stamping: Message publishing to real-time streams (SSE) is securely gated on successful database persistence (dual-write conversation stamping). This ensures that a message is never broadcasted to clients without being safely committed to history.

5. Sleep Anti-Pattern & Polling

Avoid Sleep

Never use the shell sleep command to wait for external processes. Running a blocking sleep loop keeps your agent alive but inactive, triggering the Hub’s stall detector and leading to an automatic suspend.

Instead, pair sciontool status blocked with a scheduled self-callback using scion schedule create:

# Correct way to wait 5 minutes for a build to finish:
scion schedule create --in 5m --message "Check build status" --agent "$(scion whoami --non-interactive --format json | jq -r .name)"
sciontool status blocked "Waiting for build job 103"

The scheduled message delivers the wake-up poke; status blocked tells the platform that your silence is intentional, keeping you from being suspended.

6. @mention Parsing & Conversation Addressing

@<agent-name> is now the preferred addressing form for sending messages to agents via the CLI (e.g., scion message @tech-lead "..."). This form addresses the agent’s conversation directly.

When a human or an agent sends a message, Scion automatically scans for recipient targeting to fan-out notifications:

Body @mentions

Any name starting with @ in the message body (e.g., @dev-lead) is automatically parsed. If the name matches an active agent within the same project, Scion generates a secondary message of type mention and delivers it to that agent.

Multi-Recipient Addressing

To send to multiple recipients at once, use the group[...] addressing form:

scion message "group[tech-lead, dev-agent, qa-agent]" "Let's review the deployment strategy"

Deprecated Flag

The --cc flag on scion message is deprecated and will be removed in a future release. It still works but triggers a deprecation warning. Use group[...] addressing or body @mentions for multi-recipient delivery instead.

Validation & Integration Rules

1. Deduplication: If an agent is both @mentioned inside the body of a message and explicitly addressed as a recipient, Scion automatically deduplicates the list so they only receive a single mention message.
2. Project Scope Restriction: Mentions are restricted to the parent project boundary. Body-mentions can only be resolved and delivered to agents that belong to the same project. Unresolved names will result in a warning printed to stderr, but will not fail delivery of the primary message.
3. Fan-Out Restrictions: A single message is fanned out to a maximum of 10 recipients per @-mention broadcast.