[design] Agent-mediated transfer — "transfer me to that agent", seamlessly, in hands-free

[serge-ivo]

Design ticket — for assessment before any implementation.

The ask: talking to the Coder Lead, it mentions something about a subordinate; I say "transfer me
to that agent" and I am seamlessly talking to it, still hands-free. Like a call transfer.

Distinct from #277 ("next" = I pick the next agent that wants me). Same destination, different
trigger: #277 is user-initiated selection, this is agent-mediated handoff. They should share one
switch primitive and differ only in who invokes it.

Is it possible? Yes. Nothing exotic is required.

What already exists:

Piece	Where
An agent knows its subordinates, with ids	list_subordinates / subordinate_status
A scoping rule for who an agent may address	supervision graph — "You may only delegate to agents that appear here"
An app-level slot above the routes	lib/HeaderContext.tsx — HeaderProvider, useHeaderSlot
Durable per-instance transcript	AgentDO messages
Voice stack	useVoice (SDK)

Three parts are missing. One of them is the real work.

Part 1 — the directive channel

An agent must be able to say "take the user to instance X". Two options:

(a) Make the transfer a message. A typed system message in the thread (transfer, with to +
reason). The console already refetches the transcript on its tiered poll, so it arrives with no
new transport.

(b) Use the WebSocket. AgentDO.broadcast() already emits {type:"message"|"status"} and
/v1/agents/:id/ws exists — but the console does not use it at all (it is poll-only via
useTieredPolling, and #83 deliberately moved toward tiered polling).

Recommend (a). A transfer is a conversational event: as a message it is durable, appears in the
transcript, is auditable after the fact, and survives reload. A WS directive that leaves no trace
would be invisible the moment you scroll back. Cost is one poll interval of latency, which is
acceptable for a handoff the user just asked for.

Part 2 — conversation state above the page (the prerequisite)

InstanceDetail currently owns the chat AND the voice session. A transfer unmounts it, which closes
the mic and cuts TTS — the opposite of seamless.

The conversation's identity and the voice session itself must live above the router:
useVoice instantiated once at app level, with a provider holding
{ instanceId, name, voiceMode, runActive }. HeaderContext already proves this shape works.

This is the actual engineering, and it is shared with #277 and #278. Both are blocked on it.
Mic/TTS lifecycle across a route change is the risk in this whole feature — not the transfer logic.

Part 3 — the handoff note (what makes it a transfer, not a navigation)

A transfer without context is just hanging up. The Lead should pass a short note that lands in the
target's thread before the user's first word:

Transferred from Coder Lead — about issue #36, the SSE ordering bug in fws/platform.

The target then opens knowing why. Without it the user re-explains everything and the feature is
worth nothing. This is a system message in the target instance — a primitive that already exists.

Constraints to design in, not bolt on

Scope. Only instances in the current agent's supervision graph, and only instances the user
owns. A Repo Coder reads untrusted repo files and issue bodies; if injected text can steer the user
somewhere, that is a navigation hijack. This is a new capability class — an agent acting on the
client rather than on the world — and deserves the same scoping discipline as connector
write-consent.

User-requested ≠ agent-initiated.

• "Transfer me to the FWS coder" → the user asked. Act.
• Lead spontaneously deciding to transfer → offer, do not act. "Want me to hand you to FWS
  platform?" In hands-free, a spontaneous transfer means your next sentence goes to an agent you
  did not choose.

Always announce out loud. Same requirement as #277. Hands-free means not looking; the switch
must be spoken, and the #278 indicator must update.

Never mid-turn. Do not transfer while the user is mid-utterance or TTS is mid-sentence — finish
or explicitly abandon. That is the #175 loss class.

Dependency order

#278  hoist conversation + voice above the page   ← foundation, blocks both below
  ├── #277  "next"  — user picks the next agent that wants them
  └── this  transfer — the agent hands the user over, with a note

Worth deciding as one design: #277 and this are two triggers for the same "switch the active
conversation to instance X" primitive. Building them separately would produce two switch paths that
disagree about voice state.

Open questions for assessment

1. Does the mic stay open across the switch, or close and reopen with a spoken cue? (Reopening is
   simpler and probably honest; "seamless" may not require literal continuity.)
2. Should a transfer be reversible — "go back" returning to the Lead with its own handoff note?
3. Should the Lead be able to transfer to an agent that is busy, or only to an idle one?

[serge-ivo]

Self-correction: "make the transfer a message" is the weakest part of this design, and I would reverse it

I recommended (a) — the directive as a typed system message — on durability and auditability. Those
arguments hold, but I skipped two problems that make it the wrong primitive.

1. It puts control in the data plane. The transcript is a record of what was said. A message
the client executes turns it into a command bus. Everything that touches the transcript then has
side effects: DELETE /v1/instances/:id/messages (clear chat) would delete transfer history, and
any future path that writes a system message becomes a way to steer the client. System messages are
platform-authored today (agent-do.ts writes them for tool logs, errors, loop-complete,
interrupted turns) — but that is a convention, not a boundary.

2. Replay. The transcript is re-read on every poll and on every reload. A directive sitting in
it has no notion of "already acted on". Reload the page and the client re-reads a transfer message
and transfers again. I did not address consumed-tracking at all, and bolting it on means inventing
per-client acknowledgement state inside a message list — which is the hacky version of the thing
below.

Better: a first-class pending-handoff record

• A small durable record — { userId, fromInstance, toInstance, reason, createdAt, consumedAt }
  — that the client reads and acknowledges. Idempotent by construction, no replay, no coupling
  to chat retention.
• The transcript still gets a human-readable line ("Transferred you to FWS platform — about issue
  [Admin][UI] Overview dashboard #36") for the audit trail. Note, not directive.
• Clearing the chat then loses the narration, not the mechanism.

Same shape the platform already uses elsewhere: work is a row (agent_loop_runs,
instance_runtime_tasks), and the chat reports it. Transfer should follow that, not invent a
second pattern.

Also: scope alone does not stop injection — consent does

I claimed the supervision graph protects against a prompt-injected agent steering the user. It does
not, quite. A Repo Coder with no subordinates cannot transfer anywhere — fine. But the Lead reads
subordinate summaries, which contain agent-authored text, so injected content in a subordinate's
status could induce the Lead to transfer. The graph bounds where, not whether.

What actually protects the user is the rule already in the design: user-requested → act,
agent-initiated → offer. That is doing the security work, and the ticket should say so plainly
rather than resting on scope.

[serge-ivo]

Assessment: feasible, and now mostly unblocked — but it should NOT ship as designed above

Delivered alongside #277 and #278 (commit 918a5d1). This comment is the design deliverable
the ticket asked for. Short version: the dependency analysis in the ticket is right, the
prerequisite is now built, and the one substantive disagreement is over Part 2 — hoisting
useVoice to app level is not required, and buying it would cost more than it returns.

---

What the three tickets actually are

One problem: the product is hands-free right up to the moment you need to change which agent
you are talking to, and then it demands the screen. Three faces of it:

	who chooses	who is served
#277 next	the user	"someone needs me, take me there"
#278 indicator	the user, later	"I wandered off — take me back"
#279 transfer	the agent	"this belongs to someone else"

They are one move with three triggers, so they share one primitive rather than three code paths
that would drift about the mic. That primitive now exists:

• prepareConversationSwitch (packages/sdk/src/voice/machine.ts, pure + tested) — the guard.
  Given the mode, whether TTS is speaking, and the utterance in flight, it answers: cut the speech?
  clear the utterance? what words would this destroy (recovered to the composer — the Voice transcription lost when agent message arrives mid-dictation #175
  contract, which is exactly the "never mid-turn" constraint this ticket lists)? and which voice
  mode to carry.
• ConversationProvider / useConversationSwitch (store/console/src/lib/ConversationContext.tsx)
  — the conversation's identity above the router, plus switchTo(instance, {mode, reason, announce}).
  switchTo is the whole of this ticket's Part 2, already written. A transfer is
  switchTo(target, { mode: carryMode, reason: handoffNote }).
• The handoff baton — a one-shot {instanceId, mode, say} the arriving page consumes: reopen
  the mic in that mode, then say the line.

So #279 is now: a directive channel (Part 1), a note (Part 3), and a scoping rule. Not a
foundation.

---

Part 2 — disagreement: do NOT hoist useVoice above the router

The ticket says the voice session itself must live at app level, and calls that "the actual
engineering". Having built the rest, I think it is the wrong buy:

1. The page is keyed on the instance id deliberately ([bug] Switching agents reuses the tab component — stale data on screen, and a save can write one agent's values onto another #240). That keying is what stops agent
   A's board, forms, draft message and in-flight fetches appearing under agent B's name. Voice
   would be hoisted out; everything else would still remount, so the switch is a remount either
   way and only the mic would be continuous.
2. useVoice is instance-scoped in ways that are not incidental — instanceId picks the voice
   config (language, STT/TTS provider, per-agent command words), the transcribe vocabulary bias,
   and the technical speech cleaner. Hoisting means re-pointing all of it at switch time, i.e.
   rebuilding the recognizer and TTS anyway. The "continuity" would be a getUserMedia stream
   surviving a config swap — most of the teardown still happens.
3. The thing that actually broke across a route change was priming, not the session. iOS grants
   audio from a gesture, and VoiceTts closed its AudioContext on unmount — so the next agent
   built a fresh suspended one outside any gesture and silently degraded to the browser voice. That
   is fixed properly, by making the context a page-wide singleton (voice/tts.ts); browser
   SpeechSynthesis priming was already module-level and already survived. Seamlessness was a
   priming bug wearing a lifecycle costume.
4. That leaves reopening the mic — which is open question 1, and the answer is the one the
   ticket already suspects: close and reopen with a spoken cue. Literal continuity is not what
   "seamless" means to a user who is not looking. What they need is to know who they are talking
   to now, which is the announcement, and that costs a few hundred ms of mic downtime.

Recommendation: keep useVoice on the page. If a measured gap in the reopen proves
intolerable in real use, revisit — the provider is the seam it would move behind, and nothing
here forecloses it.

---

Part 1 — directive channel: agree, make it a message

Endorsed as written, for the reason given: a transfer is a conversational event, and one that
leaves no trace is invisible the moment you scroll back. Concretely:

• a system message with {kind:"transfer", to, reason}, written by a registry tool
  (transfer_conversation), so it is gated by the same capabilities.tools allowlist and
  write-consent machinery every other tool goes through — not a new special case;
• the console's existing tiered poll picks it up; the client turns it into switchTo(...);
• do not use the WebSocket. The console does not use it at all (CODER-007 — (Stretch) Real-time status push instead of polling (Durable Object / relay) #83 moved deliberately to
  tiered polling), and a directive with no transcript entry is unauditable.

One correction to the ticket's cost estimate: latency is not "one poll interval" in the case that
matters. A user-requested transfer arrives at the end of a chat turn the client is already
awaiting — the tool result is in that response, so it is immediate. The poll interval only applies
to a spontaneous transfer, which per the rule below must be an offer anyway.

---

Part 3 — the handoff note: agree, and it is already carried

switchTo takes reason, and announceSwitch(name, reason) speaks it. #277 fills it with the
notification title; a transfer fills it with the Lead's note. The durable half — a system
message in the TARGET instance, so the receiving agent opens knowing why — is the remaining work,
and is one POST /v1/instances/:id/system-message, which exists.

Note what this makes possible and what it does not: the note is context, not authority. The
target must treat it as untrusted input from another agent, exactly like RAG text
(agent-think.ts already fences that class).

---

Scope — the part that needs the most discipline

Agreed that this is a new capability class: an agent acting on the client rather than on the
world. Enforce server-side, at the tool, not in the console:

1. Target must be an instance the CALLING USER owns. Non-negotiable, same tenant check every
   :instanceId route already does.
2. Target must be in the caller's supervision graph. A Repo Coder reads untrusted repo files
   and issue bodies; without this, injected text is a navigation hijack.
3. A destination is an id, never a name. Resolving "the FWS coder" by string on the server is
   an injection surface; the agent picks from list_subordinates, which already returns ids.
4. transfer_conversation is a WRITE tool → per-instance write-consent ([connectors] Connector consent + write-scope safety + admin visibility #90), so the user has
   opted into "this agent may move me" before it ever can.

User-requested vs agent-initiated

Endorsed, and it should be structural rather than trusted: the agent cannot reliably classify
its own initiative. So expose the capability as an OFFER by default — the message carries
{kind:"transfer_offer"}, the console renders "Hand you to FWS platform?" and speaks it, and in
hands-free "yes" accepts. Immediate transfer is a separate, narrower affordance: allowed only when
the user's own most recent turn asked for it. If that is hard to establish cleanly, ship offers
only — an offer costs one word and removes the entire class of "my next sentence went to an agent
I did not choose".

---

The three open questions

1. Mic across the switch — closes and reopens, with the switch spoken on arrival. Reopening is
   honest and simple; the real seamlessness bug (audio priming) is fixed independently. Answered
   and shipped in Voice command "next" — switch to the agent that wants you, without touching the screen #277.
2. Reversible? — yes, and cheaply: lastEngagedId already exists in the provider (it is what
   makes next toggle between two agents rather than cycle the roster). "Go back" is a next-style
   command reading it, with its own note: "Back from FWS platform — nothing was changed."
3. Transfer to a busy agent? — yes, allow it. Busy is normal and [bug] Navigating back loses 'working on it' — the run is still going and the API already reports it #252 established that a run
   outlives the tab; the Persistent top-bar indicator for the conversation you are in — get back to it from anywhere #278 indicator exists precisely to make "something is still happening"
   visible. Refusing would make the graph's usefulness depend on timing. Announce it, though —
   "…it's mid-run" — so the user is not talking into a thread that is about to answer something
   else.

---

What is left to build

1. transfer_conversation registry tool + the four scoping rules (the real work — server-side).
2. {kind:"transfer_offer"} system message + the console's accept/decline, wired to switchTo.
3. The handoff note written into the TARGET's transcript before the user's first word.
4. "Go back", off lastEngagedId.

Leaving this ticket open — it is design-assessed, not implemented, and forcing an
implementation to close it would be the wrong trade. #277 and #278 are done.

[serge-ivo]

Prerequisite check — #278 is closed, but only half of what this needs shipped

This design says it is blocked on #278. #278 is now closed, so it reads as unblocked. It is not.

Shipped: a conversation store above the router — lib/ConversationContext.tsx, lib/conversation.ts with tests, driving the top-bar indicator. That is the identity half, and hoisting only that was the right call.

Not shipped: the voice session is still instantiated per page — useVoice(id, …) appears exactly once, at pages/InstanceDetail.tsx:184. So a route change still tears down mic and TTS.

That matters here because "seamlessly start talking to that agent in hands-free" is the whole request. With voice page-owned, a transfer is navigate → unmount → remount → reopen the mic, which is a gap and a re-prompt risk, not a handoff.

Also worth re-reading before anyone builds from this: I reversed the design's main recommendation in the comment above — the directive should be a pending-handoff record the client acknowledges, not a typed chat message. The message version replays on every poll and reload, and puts control in the data plane.

So the real dependency is narrower than "#278": it is hoisting the voice session specifically, which #302's evidence makes riskier than it looked — use-voice.ts is back to 1532 LOC and is imperative sequencing over shared mutable refs, which is exactly the thing you do not want at application scope.

[serge-ivo]

Second assessment: transfer is next with the resolver moved to the server — and the only genuinely new thing is a channel the platform spent a commit closing

Design deliverable, same treatment as #322. I re-tested this ticket against main at 7332a5e,
after 2532f00 (#385/#386/#387) changed the command matcher, and after switchTo shipped.

The three comments above are still broadly right and I am not going to re-argue them. What has
changed is that the switch primitive now EXISTS and has a live consumer, so the question is no
longer "can this be built" but "what, exactly, is left". The answer is smaller and more awkward
than the ticket implies: the move is free, the note is nearly free, the resolver is real work,
and the directive channel is the one piece where I disagree with every option debated so far —
including both of mine.

---

1. Is transfer a new primitive? No. It is switchTo plus a resolver, and next proves it

The switch is one function and it already takes a destination:

// store/console/src/lib/ConversationContext.tsx:135
const switchTo = useCallback((to: {instanceId, name}, opts: {mode?, reason?, announce?}) => {
  beginHandoff({ instanceId: to.instanceId, mode: opts.mode ?? null,
                 say: opts.announce === false ? "" : announceSwitch(to.name, opts.reason) });
  navigate(`/instances/${to.instanceId}/chat`);
}, [beginHandoff, navigate]);

next is not a separate path — it is a resolver in front of that call. switchToNext
(ConversationContext.tsx:163-192) makes two requests, hands them to the pure
pickNextConversation (lib/nextAgent.ts:158-178), and ends at switchTo(pick, {mode: from.mode, reason: pick.reason}) (:188). The voice half is equally generic: nextFromCommand
(packages/sdk/src/voice/use-voice.ts:1363-1386) resolves the teardown from ONE snapshot through
prepareConversationSwitch (voice/machine.ts:212-227), recovers the words the switch would have
destroyed, cuts TTS, tears the session down and hands back carryMode. Nothing in either is about
notifications. The arriving side is equally generic — takeHandoff → setVoiceMode → speak
(pages/InstanceDetail.tsx:358-366).

So: the ticket's "Part 2, the actual engineering" is done, and the ticket's own framing was
right — one move, three triggers. A transfer is switchTo(target, {mode: carryMode, reason: note}). The client work is not "small", it is zero new mechanism.

What is NOT there is the resolver, and that is where the whole feature lives. next's resolver
runs entirely client-side, off data the console already polls, and returns an instance id. A
transfer's destination is chosen by the agent, inside a turn, on the server. That is a different
shape, not a different primitive — but it drags in name resolution (§3), scoping (§5) and a way
for the answer to reach the browser (§4).

The one thing that IS new, and it points the wrong way

Everything above is a switch the USER caused. A transfer is the first case where an agent acts on
the client instead of on the world — the ticket says this, and it is the most important sentence
in it.

Notice what the platform did about that class three days ago. 2532f00 (#386) exists because the
agent's own voice was issuing client commands: the control listener judged interims inside the echo
window, so an agent saying "Stop me if this is wrong" produced a first interim of exactly "stop",
whole-utterance-matched the built-in exit word, and tore hands-free down with the user silent
(voice/convo.ts:509-561, use-voice.ts:849-874). The fix raises the bar rather than closing the
door: no partials while echoing, whole-utterance only on finals. The listed failures are "say mute
mute to silence me" and — verbatim — "a coordinator naming the next agent".

That is this ticket's scenario, arriving accidentally, and the platform's answer was to make it
impossible. Building transfer means re-opening it deliberately, through a channel that is
supervised. Fine — but it means the design bar is "why is this channel safe when the accidental one
was not", and the answer cannot be "we ask the agent nicely to only do it when asked". §4 is my
answer.

And what happens today, which is worse than nothing

"transfer me to that agent" is not in NEXT_BY_LANG (convo.ts:260-271) and there is no
parameterised matcher anywhere, so it is not a command. It goes to the agent as a chat message. The
agent has no transfer tool, so it answers conversationally — and this codebase already has the
report of what that looks like: bare "stop" used to reach the agent as a message and the reply was
"Got it. Stopped.", described at convo.ts:205-216 as the worst available outcome, because the
reply CONFIRMS an action nobody performed. A Lead asked to transfer you will say something that
sounds like it worked, and in hands-free you will keep talking to it. That is a real argument for
building something, and it is a better one than seamlessness.

---

2. What "seamlessly" requires, one carrier at a time

Four things could have to cross. They have four different answers and only one is contentious.

The voice session — carried, and already shipped. carryMode rides the baton; the mic genuinely
closes and reopens on the far side, announced on arrival. ConversationContext.tsx:14-23 states the
reasoning and answers the ticket's open question 1 in the ticket's own words. The announcement is
spoken by the agent you ARRIVE at, because the outgoing hook is about to be unmounted mid-sentence.
Settled; do not reopen it, and do not hoist useVoice (the comment above is right, and use-voice.ts
is 1691 lines of imperative sequencing over shared mutable refs — the last thing to lift to app scope).

The runner binding — nothing to carry. pags up is multiplexed per USER, not per conversation;
one runner registers every instance whose capabilities.runtime != null. A transfer between two
runner-backed agents moves nothing, because the runner was never bound to the conversation. This is
the one carrier the ticket lists that is a non-problem, and it is worth saying so explicitly so
nobody budgets for it.

In-flight work — survives, and becomes INVISIBLE. A run outlives the tab (#252) and
runActive is on the snapshot (InstanceDetail.tsx:322), so leaving a busy agent does not stop it.
But ConversationProvider holds exactly ONE conversation (ConversationContext.tsx:67) and
resolveConversationIndicator renders exactly one pill (lib/conversation.ts:70-105). Transfer away
from a busy agent and the pill now points at the agent you arrived at; nothing anywhere says the one
you left is still working. The ticket's open question 3 asks about transferring TO a busy agent,
which is the easy direction. Transferring FROM one is the one that loses information, and it is a
pre-existing gap in #278 rather than something transfer introduces — but transfer is what makes it
routine.

Conversation context — cannot carry, and should not. This is the tension the ticket asks about,
and I think it dissolves rather than resolves.

Every input to a turn is per-instance DO state: the transcript (msg: keys in the AgentDO), memory,
RAG over that instance's vectors, tasks, settings, behaviour, attached repos —
runAgentThink assembles all of it from state/engine/instanceCfg for one instance
(agent-think.ts:158-330). There is no cross-instance read anywhere on that path, deliberately: the
marketplace invariant is that a creator never sees client data and one client's instance never sees
another's.

But the ticket does not actually ask for context. It asks for a note — "Transferred from Coder
Lead — about issue #36, the SSE ordering bug in fws/platform" — and a note is not context, it is a
claim by another agent about what you want. The platform already has the correct treatment for
that class and the ticket's Part 3 is one call away from it: POST /v1/instances/:id/system-message
exists and is owner-authenticated (routes/instances-chat.ts:164-180), and fenceUntrusted
(agent-think.ts:246-256) is the fence agent-authored text must arrive behind. So the honest design
is: the note carries, fenced; the context does not carry, ever. No invariant is bent. If the note
is not enough to make the second conversation useful, the answer is a better note, not a shared DO.

Worth naming the cost plainly: the user WILL sometimes have to repeat themselves, because a
three-sentence note is not twenty turns of history. That is the correct trade and it should be
stated in the product, not engineered around.

---

3. Disambiguation — the resolver already exists, is server-side, and refuses to guess

This is the part I expected to be the problem and it is mostly already solved, in a place the ticket
does not mention.

resolveSubordinate (lib/connectors/supervision.ts:95-116) takes however the model named an agent
and resolves it against the roster: exact match on name or id wins outright, then a
prefix/contains pass, and ambiguity is refused rather than guessed — "matches FAS platform and
FAS platform 2 — name one exactly, or use its instance id". It exists because of #320, where the
Lead said "FAS platform" four times and got "you do not supervise that agent" four times. Its own
comment states the safety property transfer needs verbatim: it resolves only WITHIN rows that are
already the caller's subordinates, so widening how a subordinate may be NAMED cannot widen WHICH
agents are reachable.

That is the resolver. It should be reused, not reimplemented — and specifically, resolution must
happen on the server against the supervision graph, never in the console against
/v1/instances/my/instances. The roster is every instance you own; the graph is a subset an owner
configured (delegate-instance.ts:56-65 re-checks it rather than trusting the caller). Resolving
client-side would silently widen the destination set to everything.

Does #371–#373's vocabulary bias apply? Yes — and it already shipped for exactly this

deriveVoiceVocabulary (lib/voice-vocabulary.ts:99-147) builds the transcription bias list per
instance, and its third query is:

SELECT i.config, a.name FROM agent_supervision s
  JOIN agent_instances i ON i.id = s.subordinate_instance_id ...

with the entry-rule comment at :24 reading: "the names of subordinate instances — said aloud
precisely to delegate ('ask the auditor')". So the exact word class this ticket needs transcribed
correctly is already biased, already scoped to the graph, already capped
(MAX_DERIVED_TERMS = 20, :55), and already refreshed on every mic start. No new work.

Three residual failures, all concrete, none of which the bias fixes:

"Agent 2" is spoken as "Agent two". A second subscription auto-names as ${agent.name} ${nth}
(routes/instances.ts:140) — literally Repo Coder 2. resolveSubordinate does exact then
prefix/contains on the raw string; "repo coder two" matches neither branch and comes back as a
refusal. The transcriber will not write the digit. This is the ticket's own multi-instance case and
it fails cleanly rather than dangerously — which is the right direction, but it means the honest
answer to "transfer me to the second one" is "say its exact name", i.e. tell the user to open the
screen, which is the failure the whole ticket exists to remove. The cheap fix is a rename prompt,
not a resolver change: an agent you talk to by voice needs a name you can say.

Punctuation. The voice stack normalises through normalizeSpeech (voice/normalize.ts:60-69),
which reduces every Unicode punctuation class to a space, precisely because Whisper renders
"stop stop" as "Stop-stop." (#334). resolveSubordinate normalises with .trim().toLowerCase()
alone (supervision.ts:103-104). Today its only caller is the model, which writes clean names, so
this is latent. Route a transcript into it and "FAS platform." misses exact AND fuzzy and returns
"you do not supervise that". Any transfer design that lets spoken text reach this function has to
put both sides through the same normaliser — the #334 lesson, in a second place.

The #332 echo, which gets worse. Proper nouns are the class that comes back verbatim from a
low-information clip and reads as the user's own words — the reported instance was two consecutive
phantom turns both reading "Coder Lead". isTranscribeBiasEcho (voice/prompt.ts:208-212)
catches multi-word terms only, and single words pass by design (:210) because "commit"/"deploy" are
real one-word turns. Transfer raises the stakes on that residual: a phantom "Auditor" today is a
confusing message; in a world where agent names are actionable it is one matcher away from being a
navigation. This is an argument for NOT making a spoken bare name a client-side command — §6.

---

4. The directive channel: not the transcript, not a pending record, and not the WebSocket

Three options have been on the table. I think all three are wrong and there is a fourth that is
strictly smaller.

The WebSocket is out on facts. The console does not use it. openAgentChatSocket
(store/console/src/lib/chatSocket.ts:27) has exactly one reference in the repo and it is
chatSocket.test.ts. There is no production consumer.

A typed system message replays, which the self-correction above establishes and I agree with. The
transcript is re-read on every poll and every reload; a directive sitting in it has no notion of
"already acted on".

A pending-handoff record with an acknowledgement is correct and is more machinery than this
needs: a table, a migration, a consumed-at column, an ack endpoint, a sweeper for records nobody
acked, and a new failure mode where a directive fires on a browser that was opened an hour later.

The fourth option: put it on the chat RESPONSE. A user-requested transfer arrives at the end of a
turn the client is already awaiting. The tool runs inside runAgentThink, which returns
{response, toolCalls} (agent-think.ts:157); agent-do.ts:529 builds
json({message, toolMessage}); routes/instances-chat.ts:126 returns that object to the browser
untouched. One extra field through three hops.

Everything the other options were reaching for falls out for free:

• Idempotence by construction. A response is consumed once because it is a response. No consumed
  flag, no ack, no replay on reload, nothing in the data plane.
• No latency. It is the same round trip the user's sentence was already making. The poll interval
  never applies.
• It cannot carry a spontaneous transfer. There is no response to ride on unless the user just
  spoke. That is not a rule an agent could misclassify — it is a property of the channel.

That last point is the design. The ticket asks for user-requested-to-act and agent-initiated-to-offer,
and correctly worries that the agent cannot reliably classify its own initiative. Choose a channel
that can only physically carry the first case, and the classification problem does not exist. An
agent mid-loop that decides you should be elsewhere has notifyUser and the next command, which is
the offer, already built, already opt-in by a spoken word.

The transcript still gets a human-readable line — narration, not directive — for the audit trail, and
the note goes into the TARGET via the existing system-message route. Clearing the chat then loses the
narration and not the mechanism, which was the self-correction's requirement.

---

5. Scoping, and what it is actually buying

Enforce at the tool, server-side. Three of the four rules the comment above lists are free because
runRegistryTool already applies them: the declared-capabilities.tools gate, the connector scope
check, and the per-instance write-consent gate (lib/tool-registry.ts:396-428). A write-scoped
transfer_conversation on the supervision connector inherits all three, so "this agent may move
me" is something the owner opted into once, in the place they opted into everything else.

The fourth — target must be in the caller's supervision graph — is resolveSubordinate +
subordinatesOf, already the posture delegate_goal takes (supervision.ts:502-532,
delegate-instance.ts:56-65).

Be honest about what that scoping costs, though: it means transfer only exists for users who have
configured a supervision graph. A user with two unrelated agents cannot transfer between them. I
think that is fine, and not because the graph is sacred — because for that user next already IS the
feature. The agent notifies, the user says one word, they move. Transfer adds nothing there. It adds
something only in the ticket's own scenario, where the Lead knows a subordinate the user does not
have a notification from.

And the scoping does not stop injection, as the self-correction says. The Lead reads
subordinate_status output that contains agent-authored text every turn. The graph bounds WHERE, and
the response channel bounds WHETHER — you had to speak to get one at all.

---

6. What cannot be undone, and what "transfer back" means

The misdirected sentence is the irreversible one, and the platform documents why. Deleting a turn
exists (turnSpanFor, lib/chat-turns.ts; handleDeleteTurn, agent-do.ts:810-824) and removes the
messages and the R2 recording. It explicitly does NOT remove what was derived from them:

// agent-do.ts:804
* What is NOT removed, deliberately: conversation summaries and the facts extracted from them.
* Clear chat drops those wholesale because it is dropping everything; for one turn there is no
* precise removal — a summary is an aggregate over twenty messages and cannot be un-mixed.

Summarisation is fire-and-forget after every turn (agent-do.ts:518-527) and extracts facts into that
instance's memory. So a sentence spoken into the wrong agent — a credential, a client name, a salary
figure, whatever you were mid-way through telling the Lead — can be absorbed into a second instance's
durable memory, and the only remedy is Clear chat on an agent you never meant to talk to. That is the
real cost of getting a transfer wrong, it is worse than "confusing", and it is an argument for the
announcement being loud rather than tasteful.

Two mitigations already exist and should be treated as load-bearing rather than nice: the switch never
silently discards an utterance in flight — prepareConversationSwitch recovers it to the composer
(machine.ts:212-227, the #175 contract) — and announceSwitch speaks the destination by name
(lib/conversation.ts:116-119).

"Transfer back" is cheap and must ship in the same change. lastEngagedId exists and is
maintained (ConversationContext.tsx:68, :77). But do not implement "go back" as next: next
only returns you to lastEngagedId if that agent appears in attentionByInstance, i.e. has an unread
notification (nextAgent.ts:168-172). Transferring away from an agent does not notify you about it,
so "go back" through next would silently do nothing or take you somewhere third. It needs its own
two-line resolver over lastEngagedId, with its own note — "Back from FWS platform. Nothing was
changed." Shipping transfer without it is shipping a one-way door.

---

7. Recommendation: build the reduced version — user-requested only, on the response channel

Build:

1. transfer_conversation — a write-scoped registry tool on the supervision connector, resolving
   through resolveSubordinate, returning a destination id + the agent's note. Inherits the declared-
   tools gate, the scope check and write consent from runRegistryTool unchanged.
2. A structured field on the chat response, threaded agent-think.ts:157 → agent-do.ts:529 →
   routes/instances-chat.ts:126, and dropped by every other caller that ignores it.
3. The console turns it into the existing switchTo(target, {mode: carryMode, reason: note}). No new
   client primitive, no new state, no new poll.
4. The note into the target via POST /:id/system-message, read back fenced as untrusted.
5. "Go back", off lastEngagedId, with its own resolver, in the same PR.

Do not build:

1. A spoken transfer to <name> client command. There is no parameterised matcher anywhere in the
   voice vocabulary — every command is a fixed phrase list matched whole-utterance or as a whole-word
   run (convo.ts:415-422), and the one time a phrase was allowed to match inside a sentence it fired
   on "the next agent in the chain is the builder" (convo.ts:246-258). A prefix-plus-payload matcher
   is a new false-positive class over ordinary speech, it would have to resolve names client-side
   against the whole roster rather than server-side against the graph, and it hands the single-word
   bias-echo residual of §3 a navigation to fire. Let the sentence be a sentence and let the agent
   call the tool.
2. Any spontaneous, agent-initiated transfer. Not "offer it instead" — do not build a channel that
   can carry one. notifyUser + next is the offer, and it is already shipped and already gated on
   the user saying a word.
3. Carrying conversation context across instances. The note carries; the context does not. §2.
4. Hoisting useVoice above the router. Settled by Voice command "next" — switch to the agent that wants you, without touching the screen #277; nothing here reopens it.
5. A pending-handoff table, a WebSocket directive, or a directive in the transcript. §4.
6. Transfer to an instance outside the supervision graph. For those users, next is already the
   whole feature.

Where a maintainer could reasonably disagree with me. If you read the ask as literally "I say the
words and I am moved", then routing it through a chat turn costs a full BYOK Claude round trip — call
it two to five seconds of the user talking into a mic that has not moved yet — and you would want the
client-side command instead. That is a defensible reading of the ticket, which does say "seamlessly".
I think it is wrong because the user is speaking, not clicking: every other sentence they say pays
that same latency and they experience it as the agent thinking, not as the app being slow. But that is
a judgement about what a voice user perceives as a gap, not a fact about the code, and the code
supports building either.

And one thing I would add that the ticket does not ask for, on the strength of §6: before any of
this, make the announcement mandatory and non-suppressible on a transfer. switchTo takes
announce: false (ConversationContext.tsx:136) and that is correct for a tap on the indicator, where
the user is looking at what they clicked. A transfer must not be able to reach it. The cost of a silent
switch is a sentence in a stranger's summary that cannot be deleted.

---

Two things noticed in passing that are not this ticket's: openAgentChatSocket
(store/console/src/lib/chatSocket.ts:27) has no consumer outside its own test, so the WS chat path is
dead code in the console; and resolveSubordinate (lib/connectors/supervision.ts:103-104) normalises
with trim().toLowerCase() while every other spoken-text comparison in the codebase goes through
normalizeSpeech — harmless while its only caller is a model writing clean names, wrong the moment a
transcript reaches it.

Leaving this open — design-assessed, not implemented.

[serge-ivo]

This was built in 697f605 and was unreachable by every agent. Fixed in 4a678ae; verified live.

697f605 shipped the reduced version from the assessment above, complete on every axis but one:
the transfer_conversation registry tool with resolveSubordinate and a canceled-subscription
guard, the destination riding the chat response, the console's switchTo consumer, the spoken
"go back", and tests on all of it. It never got a comment here, so this is the record.

The missing axis made the whole feature inert. capabilities.tools is an authoritative
allowlist — toolNamesFor REPLACES the per-surface default with the declared list rather than
adding to it — and no agent declared the name. Measured against coder-lead's effective declaration
(0063 → 0067 → 0101) before writing the fix:

CREATOR_SELECTABLE_TOOLS.has("transfer_conversation")       true
toolNamesFor(leadDeclaration).has("transfer_conversation")  false     ← the whole feature
toolNamesFor(leadDeclaration).has("delegate_goal")          true

So the one agent on the platform with subordinates — the agent this ticket was written for — could
not call it.

This is #415's failure class, three days later and in the same table, and it is invisible
precisely because the registry half is complete: nothing throws, no test fails, and the agent just
answers conversationally. For this feature that is the worst available outcome rather than a mild
one, and the codebase already says why — convo.ts:205-216 records what happened when bare "stop"
reached the agent as a message instead of matching a command: the reply confirmed an action nobody
performed. A Lead asked to transfer you says something that sounds like it worked, and in
hands-free you keep talking to it.

The fix

Migration 0107 declares transfer_conversation on coder-lead only — that is the whole
population, since the tool refuses any destination outside the caller's supervision graph. No new
gate: it is scope:"write" on supervision, already behind the per-instance write-consent the Lead
needed for delegate_goal. What bounds the capability is the channel, not the grant.

Four assertions in coder2-parity.test.ts, verified to fail with the migration removed. One
checks the declaration through toolNamesFor rather than by reading the list, because a declared
name outside CREATOR_SELECTABLE_TOOLS is declared and still invisible — the trap under the trap.

Verified live in production

GET /v1/instances/5fab318d-…/tools   → transfer_conversation
     "allowed": true, "reason": "ok", "writeConsent": "granted"

Before this it was allowed:false, reason:"not_declared". Capabilities on /v1/instances/my/instances
now carry the name. CI green including Playwright; Deploy API Worker green with 0107 applied.

Checked against today's voice work, and deliberately unchanged

The stack moved a long way after 697f605 (#420, #421, #425, and ADR 0001 in #388). The risk worth
testing was a handoff whose announcement speaks before the session that carries the control
listener exists — ADR 0001 M1's speaking phase with no way to say "mute". It does not happen:
InstanceDetail's handoff effect awaits setVoiceMode(h.mode) before speak(h.say), so the
session is up first, and convo.ts already reasons about reversing a transfer while muted. No
change was needed and none was made.

The design's build list, item by item

1. transfer_conversation + the four scoping rules — shipped, and now reachable.
2. The structured field on the chat response — shipped (agent-think → agent-do → the route,
   which needed no change).
3. The console turning it into switchTo — shipped.
4. The note into the TARGET's transcript — deliberately not built, and the reasoning in
   lib/conversation-transfer.ts is better than the assessment's: summarisation is fire-and-forget
   after every turn and extracts facts into that instance's durable memory, which deleting a turn
   explicitly never removes. The note is one agent's claim about what the user wants, so it is
   read to the person, who is the only party able to correct it. Nothing is written into the
   destination.
5. "Go back" off lastEngagedId — shipped, with its own resolver rather than through next.

Plus the addition the assessment asked for: the arrival announcement is non-suppressible from this
path.

Closing. Everything in the recommendation is either shipped or explicitly declined with a
reason, and the capability is live. The two residuals are separate and neither is this ticket's:
the "Agent 2" spoken-name case wants a rename prompt, and leaving a busy agent still loses its
indicator (one conversation in the provider, one pill) — a pre-existing #278 gap that transfer
makes routine, worth its own issue if it bites.