Tau Tool Verification Agent Coordination

Tau Tool Verification Agent Coordination

Load tau-tool-verification first for the shared output structure, escaping, line handling, tool-description, availability, and reporting guidelines. This skill supplies the focused verification guidance for this tool group.

Message tool verification plan

Use this plan when asked to verify the message tool, especially in multi-agent scenarios. Prove routing among the main agent, children, siblings, sessions, post-final but still-live agents, stopped/unloaded/canceled agents, and invalid/unknown recipients. Also verify timing, sender IDs, async delivery, payload escaping in hidden prompts, exact durable AgentMessage payloads, and error behavior.

Do not rely on memory. Give every sub-agent a self-contained prompt. A delegated agent starts with a clean context and does not know this skill, the parent conversation, or the IDs of other agents unless you include them in its prompt or later messages.

What to verify

Record all of these observations:

• Main agent to sub-agent delivery.
• Multiple messages to the same live sub-agent.
• Sub-agent to sibling sub-agent delivery.
• Sub-agent to the main agent using the main agent recipient ID.
• Exact user recipient rejection without sender or recipient projection.
• Main agent to itself, after the main agent recipient ID is known.
• Delivery while a sub-agent is sleeping, backgrounded on a long tool, queued behind another tool call, or otherwise between model turns.
• Delivery order, or any reorderings, especially for parallel message calls.
• Sender IDs visible to recipients.
• Message payload preservation in durable events, and exact-close framing in hidden prompts, for multiline content, blank lines, unicode, JSON-like text, backticks, and literal <message> tags inside the payload.
• Error for an unknown recipient ID.
• Successful follow-up delivery to a final-responded but still-loaded sub-agent.
• Error for a genuinely stopped, unloaded, or canceled sub-agent recipient ID.
• Error for an empty message.
• agent_start, agent_watch, and wait behavior around long-running sub-agents; in current Tau, sub-agent responses arrive by watch notifications rather than slow agent_start results.

Phase 1: spawn two peer agents and report to the parent

Start with two shared delegates. Name them Agent A and Agent B. Their initial prompts wait for a bootstrap message because the parent self_agent_id is returned only after agent_start submits those prompts.

Use this prompt for Agent A, replacing only the agent name where needed for Agent B:

You are Agent A in a Tau message-tool verification test. Goal: verify
cross-agent messaging behavior. You have a clean context; follow these
instructions exactly.

Important:
- Incoming messages from the Tau `message` tool may appear as hidden prompts in your conversation. Treat every new prompt/message you see after starting as an inbound test message.
- Keep a full log of every inbound message you receive after this initial task prompt. Include exact text, apparent sender/recipient if visible, and when you noticed it.
- You may use only safe commands. Use short `sleep` commands only to stay alive and give the parent/peer time to send messages.
- If you receive a message containing `COMMAND: SEND_PEER`, parse `recipient_id={id}` and `text={text}`, then call the `message` tool to send exactly `{text}` to that recipient. Log the tool result.
- Your first inbound message must be `BOOTSTRAP parent_id={main_agent_id}`.
  Save that ID and use it as `{main_agent_id}` below.
- If you receive a message containing `COMMAND: REPORT`, send a `message` to `{main_agent_id}` with your current full log.
- Do not finish early. Run four observation rounds.

Procedure:
1. Wait for the `BOOTSTRAP` message, then send a message to `{main_agent_id}`
   with exactly: `READY Agent A: started message-tool test`.
2. For rounds 1 through 4:
   a. Run `sleep 3` using the shell tool.
   b. After the sleep result, inspect any new inbound messages/prompts you have received.
   c. Execute any `COMMAND: SEND_PEER` instructions you have newly received.
   d. Send a message to `{main_agent_id}` starting with `REPORT Agent A round {n}:` and include all newly observed inbound messages since the previous report and any message-tool actions/results. If none, say `none`.
3. Final answer: return `FINAL Agent A` plus your complete inbound-message log and all message-tool actions/results.

You are expected to receive messages from the parent and possibly from Agent B. Be precise and do not invent messages.

After the agent_start results return, note the caller self_agent_id and each sub_agent_id. In legacy/background agent_start sessions, also note any returned agent_start tool-call ids. Send BOOTSTRAP parent_id={self_agent_id} to each sub_agent_id, wait for both READY reports, then send the first batch of messages in parallel:

To Agent A:
- MAIN to A direct message 1. nonce=main-a-001. Please log exact text.
- MAIN to A direct message 2. nonce=main-a-002. Please log exact text.
- COMMAND: SEND_PEER recipient_id={agent_b_id} text=PEER A to B message from Agent A. nonce=peer-a-b-001. Please log exact text.
- COMMAND: REPORT from main to Agent A after initial sends. nonce=report-a-001.

To Agent B:
- MAIN to B direct message 1. nonce=main-b-001. Please log exact text.
- MAIN to B direct message 2. nonce=main-b-002. Please log exact text.
- COMMAND: SEND_PEER recipient_id={agent_a_id} text=PEER B to A message from Agent B. nonce=peer-b-a-001. Please log exact text.
- COMMAND: REPORT from main to Agent B after initial sends. nonce=report-b-001.

Sleep for about four seconds in the main agent, then send a delayed batch in parallel:

To Agent A:
- MAIN to A delayed direct message 3. nonce=main-a-003. Please log exact text.
- COMMAND: SEND_PEER recipient_id={agent_b_id} text=PEER A to B delayed message from Agent A. nonce=peer-a-b-002. Please log exact text.
- COMMAND: REPORT from main to Agent A after delayed sends. nonce=report-a-002.

To Agent B:
- MAIN to B delayed direct message 3. nonce=main-b-003. Please log exact text.
- COMMAND: SEND_PEER recipient_id={agent_a_id} text=PEER B to A delayed message from Agent B. nonce=peer-b-a-002. Please log exact text.
- COMMAND: REPORT from main to Agent B after delayed sends. nonce=report-b-002.

Also send one message to a clearly invalid recipient such as engineer_does_not_exist_message_validation; expect a tool error with the unknown recipient ID and echoed message fields. Send one message to exact recipient user; expect an unsupported-recipient tool error and, when event logs are available, confirm that it creates neither a sender nor recipient projection.

Wait for both delegates. In their final logs, verify that:

• The agent_start result exposes self_agent_id and sub_agent_id without redundant aliases.
• Each agent saw the direct main-agent messages addressed to it.
• Each agent saw the peer message from the other agent.
• Each COMMAND: SEND_PEER caused exactly one peer message call with result beginning Message committed: msg- and ending response not guaranteed.
• Delayed messages arrived even though the agents were already running.
• The visible sender ID for messages from the main agent is present and matches the self_agent_id from the agent_start result. Save that sender ID; it is the main agent recipient ID for the next phase.

After both delegates emit final responses, send a follow-up message to each old sub_agent_id. A final response ends a turn but does not stop a still-loaded agent, so expect a committed message and potentially a new response turn. Separately test a genuinely unloaded, canceled, or explicitly stopped agent and expect stopped message recipient; a never-known ID must remain unknown message recipient.

When a controlled cold-restart fixture is available, start a durable child, stop the harness while its delegation route is not resumable, restore the session, and message the restored child ID before starting a replacement. Expect exactly restored message recipient cannot resume its pre-restart delegation: \<id>`; start a replacement` and no sent/received projection. If the live session cannot create this restart cut, mark the restored-unavailable category conditional/unavailable rather than inferring it.

Phase 2: verify delivery to a delegate queued behind a backgrounded tool

Start one shared sub-agent with agent_start whose job is to create the message-delivery edge case where the sub-agent has a long backgrounded tool still actually running and a second not-yet-started tool queued behind it.

Use this prompt:

You are a Tau message-tool verification sub-agent for queued-tool preemption. Goal: prove parent messages are delivered even when your next tool call would otherwise be queued behind a long backgrounded tool.

Procedure:
1. Start a long shell command: `sleep 30`.
2. After Tau returns the background placeholder for that shell call, immediately request another shell command: `sleep 5`.
3. If you receive any inbound `[tau-internal]` message from the parent, respond to `{main_agent_id}` exactly: `QUEUED-TOOL MESSAGE RECEIVED nonce=queued-tool-message-001` plus the exact inbound message text and visible sender id.
4. After sending the parent message, final answer exactly: `FINAL queued-tool message probe reported to parent`.
5. If no inbound message arrives, final answer exactly: `UNEXPECTED queued-tool message missing`.

Do not invent messages. Do not finish before checking for the parent message.

After the agent_start result returns, wait until the delegate has had enough time for the first sleep 30 to background and for the second sleep 5 request to be queued. In normal UI output this often looks like delegate progress with a running/backgrounded shell call and no response from the second shell yet.

Send a message to the delegate sub_agent_id:

Parent queued-tool delivery probe. nonce=queued-tool-message-001. Reply via message to `{main_agent_id}` when received.

Expected behavior:

• The message call returns Message committed: <message-id>; recipient was live; response not guaranteed.
• The delegate responds to the parent with QUEUED-TOOL MESSAGE RECEIVED nonce=queued-tool-message-001 instead of remaining stuck behind the queued sleep 5.
• If event logs are available, verify that the AgentMessage was recorded, the not-yet-started queued tool call was terminalized with ToolCancelled, and a new AgentPromptCreated was emitted for the delegate message prompt.
• The long backgrounded sleep 30 may still complete later in the delegate conversation. Its completion should not be delivered to the parent conversation or block the message response.

This scenario specifically protects the code path where agent.message delivery preempts queued-but-not-started tool calls behind an already-backgrounded exclusive tool. Without that behavior, the message can be received by the harness but never become a model-visible prompt for the sub-agent.

Phase 3: verify sub-agent to main-agent routing

Use the main agent recipient ID returned by agent_start in Phase 1. Spawn two fresh shared sub-agents with agent_start, Agent C and Agent D. These agents should report back to the main agent recipient ID, not to user. This proves that parent-directed messages are delivered as model-visible [tau-internal] inbound messages to the main agent.

Use this prompt for Agent C, replacing only the agent name where needed for Agent D and filling {main_agent_id} with the ID returned in Phase 1:

You are Agent C in a second Tau message-tool verification test. Parent/main agent recipient_id is `{main_agent_id}`. Goal: verify messages among parent, Agent C, and Agent D.

Rules:
- Incoming `message` tool messages may appear as hidden prompts. Log every inbound message you receive after this initial task prompt, with exact text and visible sender id.
- For every report, use the `message` tool to send to `recipient_id={main_agent_id}` (the parent/main agent), not `user`, unless the parent message fails. If it fails, log the failure and continue.
- If an inbound message contains `COMMAND: SEND_PEER recipient_id={id} text={text}`, send exactly `{text}` to `{id}` using the `message` tool and log the result.
- If an inbound message contains `COMMAND: REPORT_PARENT`, immediately message your current log to `{main_agent_id}`.
- Stay alive for three observation rounds using `sleep 2` each round. Do not finish early.

Procedure:
1. Send to `{main_agent_id}`: `READY Agent C to parent. nonce=ready-c-parent-001`.
2. Repeat three rounds: sleep 2 seconds; inspect new inbound messages; execute any SEND_PEER commands; message the parent with `REPORT Agent C round {n}:` plus new inbound messages and actions since previous report, or `none`.
3. Final answer: `FINAL Agent C` plus complete inbound log and all message-tool actions/results.

After the agent_start placeholders return, send this batch in parallel:

To Agent C:
- MAIN to C direct message. nonce=main-c-001. Please log exact text and sender id.
- COMMAND: SEND_PEER recipient_id={agent_d_id} text=PEER C to D from Agent C. nonce=peer-c-d-001. Please log exact text.
- COMMAND: REPORT_PARENT nonce=report-c-parent-001.

To Agent D:
- MAIN to D direct message. nonce=main-d-001. Please log exact text and sender id.
- COMMAND: SEND_PEER recipient_id={agent_c_id} text=PEER D to C from Agent D. nonce=peer-d-c-001. Please log exact text.
- COMMAND: REPORT_PARENT nonce=report-d-parent-001.

The main agent should receive [tau-internal] inbound messages from each sub-agent. Record whether the sender ID in those inbound messages matches the sub-agent sub_agent_id. Sleep for about three seconds, then send one delayed direct message to each agent:

To Agent C:
- MAIN to C delayed message. nonce=main-c-002. Please log exact text and sender id.

To Agent D:
- MAIN to D delayed message. nonce=main-d-002. Please log exact text and sender id.

Wait for both delegates. Verify that their final logs match the parent-visible reports already received by the main agent.

After both emit final responses, again verify follow-up messages succeed while the agents remain loaded. Do not label a final-answering agent completed or stopped without lifecycle evidence.

Phase 4: verify self, content, and simple validation errors

After the main agent recipient ID is known, send a message from the main agent to itself. Expect a model-visible [tau-internal] inbound message whose sender is the same main agent ID and whose payload is exact.

Then send a multiline self-message like this:

MULTILINE self content probe. nonce=self-main-002
line 2 unicode: café 🚀

line 4 xml-ish: <message>inner</message> & chars
line 5 code-ish: `backticks` and {"json":true}

Verify that blank lines, unicode, ampersands, backticks, JSON-like text, and literal inner <message> openings remain exact and readable. Exact </message> collisions must appear as </message>, and the delivered wrapper must contain exactly one exact close. If you inspect durable AgentMessage events, verify that the stored payload is still exact and unframed.

Finally, call message with an empty string to a valid recipient. Expect a tool error such as `message` must not be empty. Also verify an unknown recipient error if it was not already checked in Phase 1.

Reporting format for message verification

Report concise but complete findings:

• List each tested route and whether it passed: main to child, child to child, child to parent, rejected exact user, main to self, invalid recipient, post-final live recipient, stopped recipient, conditional restored-unavailable recipient, empty payload, rich content payload.
• Include exact unexpected errors or output.
• Mention any timing surprises, missed messages, duplicate messages, or ordering uncertainty.
• Confirm the message success output includes a stable message ID and response not guaranteed; it confirms async acceptance, not delivery completion.
• Include whether stopped recipients, restored-unavailable recipients, and never-known recipients produce their distinct errors.
• Include whether parent recipient ID discovery was clear from self_agent_id or still had to be inferred from sub-agent logs.
• Include whether the delivered wrapper preserved literal <message> openings and ampersands while replacing every exact </message> collision.