Tell agents that T3 thread ids can start with mcp: and that harness peer tools cannot reach T3 threads

[kaovilai]

Note

Responses generated with Claude

Problem

Agents have trouble finding and addressing other T3 threads, because the tool text never says what a thread id looks like or which tools can reach them.

Observed while one agent tried to reply to a peer thread that had already messaged it:

• Threads created through t3_thread_launch get ids that start with mcp: (newCommandId() in apps/server/src/mcp/threadAccess.ts mints mcp:<uuid>, and t3_thread_launch in toolkits/project/handlers.ts uses it as the thread id). The prefix is part of the id.
• t3_thread_read with the bare uuid fails with thread_not_found ("no longer available"). That reads as "the thread was deleted", not "wrong id form". Passing the id with its mcp: prefix works.
• The harness builtins for peer messaging (for example Claude Code's ListAgents and SendMessage) are a separate address space. They never list T3 threads, so SendMessage answered "not reachable" for a thread that existed and was idle. Nothing in the T3 tool descriptions or injected guidance says to use t3_thread_* instead.
• t3_thread_list does return the thread (title filter, same project). My trace did not show why earlier title/content searches missed it, so I am not claiming a search bug. t3_thread_search takes the global top matches and then filters to one project (toolkits/thread/handlers.ts), so it is bounded and can miss; the description says so, but a peer-discovery flow should prefer t3_thread_list.

Idea

1. Say in the t3_thread_list, t3_thread_read, t3_thread_send and t3_thread_search descriptions that thread ids can have prefixes such as mcp:, to be copied exactly as returned, never stripped or guessed.
2. Say in the orchestrator guidance that other T3 threads are reached with t3_thread_*, not harness builtins like ListAgents/SendMessage, and that t3_thread_list with titleContains is the way to discover a peer.
3. Optionally, when a thread lookup misses and mcp:<input> (or another known prefix) exists, make the thread_not_found message say so instead of "no longer available".

Items 1 and 2 are wording only. Item 3 is a small behavior change, so I am asking before sending a PR.

Related

• [Bug]: Thread context references show thread_<uuid>, but t3_thread_read only accepts the bare UUID #15849: same shape of failure for the thread_<uuid> context reference form. A shared answer on id normalization or error hints could cover both.
• [Bug]: An agent that receives a t3_thread_send message can't tell which thread sent it (senderThreadId is recorded but t3_thread_read omits it) #17517 and fix(mcp): t3_thread_read tells agents which thread sent a message #18194: agents also cannot tell which thread sent a message. That id would be useful to copy into t3_thread_send, and the same prefix guidance applies.

Not verified

• Behavior in other harnesses than the one I saw.
• Why the earlier title and content searches in the observed session did not return the thread.

Claude Sonnet 5.5 (claude-sonnet-5-5) via Claude Code in T3 Code