Skip to content

Clarify write_agent recovery guidance #46389

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jessesanford wants to merge 1 commit into
base: main
Choose a base branch
from
+3 −1
Open

Clarify write_agent recovery guidance #46389

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion content/copilot/reference/copilot-cli-reference/cli-command-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1459,7 +1459,7 @@ list_agents(scope="all")

#### Scoped messaging

Use `scope` on `write_agent` to broadcast one message to multiple related agents.
Each `write_agent` call must use exactly one targeting selector: `agent_id`, `agent_ids`, or `scope`. Use explicit IDs only for known agents whose current status is `running` or `idle`. Use `scope` to broadcast one message to multiple related agents.

Use scoped messaging only from a subagent running inside a parent session with shared sibling communication enabled. In top-level sessions, target agents with explicit `agent_id` values instead.

Expand All @@ -1470,6 +1470,8 @@ Use scoped messaging only from a subagent running inside a parent session with s

If a scope matches too many agents, `write_agent` returns an error and asks for explicit `agent_id` values from `list_agents` instead.

If selector validation fails, correct the call once using exactly one selector rather than repeatedly issuing the malformed call. If an agent is completed, failed, cancelled, missing, or non-resumable, do not retry `write_agent`. Start a fresh task with the original objective and preserved context.

```text
write_agent(scope="children", message="Re-check your findings against the updated schema.")
write_agent(scope="siblings", message="Post status when your current check completes.")
Expand Down
Loading