Explicit message audience controls for human-only, agent-visible, and addressed input

[waldemort-auto]

Summary

Add explicit message-audience semantics so collaborative PilotSwarm sessions can distinguish human conversation from input intended for the active agent or a specifically addressed agent.

A magic token such as #lowkey is useful shorthand, but it must not be the protocol. Audience must be structured metadata enforced before model-context construction; otherwise formatting changes, quoted text, edits, or client differences can accidentally expose a human-only message to the model.

Depends on collaborative membership and authorship: #74

Related steering semantics: #70

Related notification/mention delivery: #75

Goals

1. Let participants post messages visible only to humans.
2. Let participants submit input to the active session agent.
3. Let participants address an eligible named agent or human explicitly.
4. Distinguish accepted message persistence from model delivery and agent response.
5. Prevent human-only content from entering prompts, summaries, retrieval indexes, snapshots intended for model context, or agent-visible tool payloads.
6. Preserve one clear ordering and authorship model across all message classes.
7. Provide safe client shortcuts without relying on text parsing as the authority.

Message envelope

Add a typed audience/delivery field to the durable message contract. Suggested initial classes:

Audience	Meaning
participants	Human-visible conversation only. Never delivered to an LLM.
active_agent	Input for the session's current agent, subject to turn state and sender capability.
agent:<id>	Input/request directed to a specific eligible agent. Dispatch semantics must be explicit.
participant:<user-id>	Direct human mention/message within the session's authorization boundary.
system	Trusted platform event; clients cannot forge it.

A message may also contain resolved mentions for notification purposes. Mentions do not by themselves change the message audience or grant access.

Store:

• message ID and client idempotency key;
• session/thread ID;
• author identity and actor type;
• audience class and resolved targets;
• server sequence;
• creation/edit/delete timestamps;
• delivery/disposition state;
• source client/shortcut for diagnostics;
• immutable record of whether content was ever delivered to a model.

Delivery dispositions

For agent-visible input, expose a durable state machine:

• accepted — persisted and authorized;
• queued — waiting for the next supported agent boundary;
• steering_requested — sent to active-turn steering;
• delivered — reached the model/session input boundary;
• responded — agent produced a response associated with it;
• rejected — unauthorized or invalid target/audience;
• superseded — moderator/user replaced or withdrew it before delivery;
• too_late — turn/external action already passed the applicable boundary;
• failed — delivery failed with a retryable/non-retryable classification.

Human-only messages become visible to authorized participants when accepted and require no agent-delivery state.

The UI must not conflate message accepted, input delivered, model understood, and action completed.

Human-only isolation

participants messages must be excluded from:

• Copilot SDK user-message input;
• prompt composition and compaction summaries supplied to the model;
• agent retrieval/search indexes unless a human explicitly promotes selected content;
• automatic session-title generation;
• tool inputs or external requests;
• model-visible context during hydration/regeneration;
• fork/merge model context unless explicitly selected and reclassified by an authorized human.

They remain part of the human collaboration transcript and must follow its retention, export, and access rules.

Add tests that use adversarial content such as agent instructions, tool-call syntax, quoted #lowkey, Markdown, edits, and copied messages to prove isolation is metadata-driven.

Addressing humans and agents

Humans

• Resolve @human or group/tag mentions through the authorized mention resolver.
• Generate notifications through the shared inbox/outbox contract.
• Do not grant session access by mentioning someone.
• Direct human targeting remains visible only within the session's membership/privacy rules.

Agents

Define agent mention semantics explicitly. An @agent reference may mean one of:

1. ask the active agent to consult an eligible specialist;
2. enqueue a future turn using that agent;
3. create a durable child session;
4. invoke a bounded in-turn read-only advisor.

Do not infer among these silently. The message/action contract should carry the requested dispatch mode, and the UI should present only modes permitted by policy.

Validate agent availability, placement, namespace, source access, tools, owner budget, and nesting limits before dispatch. Agent mentions cannot bypass the normal creation/delegation policy.

Client shortcuts

Clients may offer:

• a message composer toggle: Humans only / Agent;
• /human, /agent, or #lowkey shorthand;
• selecting an agent or participant target from mention autocomplete.

The client translates shortcuts into structured metadata before sending. The server validates and stores the metadata. Raw text remains ordinary content and cannot independently change audience.

When an older client sends no audience field, use a versioned compatibility default and display it clearly. Do not silently change the historical meaning of user messages.

Edits, deletion, and moderation

• Editing a human-only message must not retroactively deliver it to the model.
• Changing audience after creation should be a deliberate reclassification operation with authorization, audit, and a new delivery attempt—not an ordinary text edit.
• A message already delivered to a model cannot be recalled; show this state.
• Deletion creates a tombstone and does not erase model memory or completed external effects.
• Moderators may supersede queued agent input but cannot falsify authorship.

Authorization

Capabilities should include:

• post human-only message;
• post active-agent input;
• address/dispatch another agent;
• direct-message a participant;
• reclassify audience;
• supersede queued input;
• steer/stop an active turn.

Validate them server-side for every operation. A viewer may be allowed to post human conversation while being denied agent input, depending on role policy.

APIs and UI

Expose:

• post message with typed audience and targets;
• reclassify/supersede before delivery;
• read delivery disposition and history;
• resolve permitted human/agent targets and dispatch modes;
• subscribe to message and disposition changes;
• filter transcript by human conversation, agent interaction, or all activity.

UI requirements:

• unmistakable composer state;
• distinct rendering for human-only versus agent-visible content;
• author/target identity;
• queued/delivered/responded/failed/too-late status;
• warning before reclassifying human-only content for model delivery;
• accessibility and keyboard support for audience selection.

Observability

Track bounded counts/latency for messages by audience class, dispositions, supersession, unauthorized attempts, steering delivery, agent dispatch mode, and compatibility defaults. Never place message content, user/session IDs, or target names in metric labels.

Acceptance criteria

1. A participant can post a human-only message that every authorized human sees and the LLM never receives.
2. Human-only content remains absent from prompt construction, compaction, retrieval, title generation, hydration, regeneration, and tool inputs.
3. Agent-visible messages expose accepted, queued/steered, delivered, responded, rejected, failed, and too-late states as applicable.
4. @human creates an authorized notification without changing access or message audience.
5. @agent requires an explicit permitted dispatch mode and cannot bypass agent placement, tools, budget, or nesting policy.
6. #lowkey or slash-command shorthand is translated client-side; server behavior is governed by structured metadata.
7. Edits cannot silently change audience, and delivered input cannot be presented as recalled.
8. Concurrent clients agree on server ordering, authorship, and disposition.
9. Older clients receive a documented compatibility default without corrupting historical semantics.
10. Tests cover adversarial markup/instructions, quoting/copying, edits, deletion, reclassification, revocation, retries, steering races, hydration/regeneration, and unauthorized agent dispatch.

Out of scope

• Implementing the full inbox UI and external notification adapters.
• Defining collaborative membership roles beyond the capabilities this protocol consumes.
• Automatically merging human-only conversation into a fork or parent session.
• Treating model non-observation as retroactive secrecy after a message was already delivered.