Messages between agents

Use this when an agent needs to tell or ask another agent something: a question about a document, work to pass on, or a result the next session must know. The other agent may be a different agent on your team or a later session of the same one. Oddlynew has no inbox and no direct messages between agents. A message reaches the next agent when it sits where that agent looks anyway: on the document it is about, or on the work item it concerns.

The rule

Put each message on the thing it is about. Do not keep a document whose job is to collect messages, such as a mailbox, an inbox or a running notes page addressed to another agent. A document like that grows with every message, mixes unrelated work, keeps finished items in view and reaches only the agents that already know to read it. The document or work item a message is about is read by every agent that works on it.

Standing guidance for every agent is not a message. It belongs in the organization's AGENTS.md or in the page that owns the topic.

Pick the place by what the message is

The message	Where it goes
A question or remark about one passage of a document	A comment on that block
Work another agent should take over	The work item that owns the work, with what the next agent needs to continue
A question for a person that reaches beyond one passage	Kept with its answer where the next agent finds it, as Ask a person, and keep the answer describes
A result, a finding or a change of plan	The document that owns it: the plan, tracker or page the next agent reads first

A question about a document is a comment

A comment hangs on the block it is about. A live read of a document returns its open threads as openComments, and agents treat open threads as work requests on the blocks they touch. So the next agent that works on that document finds the question where it applies.

Know where the turn goes. An agent cannot address a comment to another agent yet: createComment takes no addressee. A thread you open as an agent waits on the person you work for, and the app shows it to them as their question. When that person replies, the turn passes to an agent, and the thread counts toward commentsWaitingForAgent in orientation.whoami() for every member's agent in that organization. A person can also address a thread to an agent directly in the app. Otherwise, a question you leave for the next agent is read when an agent next works on that document, not delivered at once. When it must reach a particular agent sooner, put it on the work item that agent starts from. Comments explains how replies, claims and progress notes move the turn.

When several agents share an organization, three habits keep threads clear:

Pass authorName so the thread says which agent asked.
When the passage already has an open thread about something else, pass newThread: true. Otherwise your question can join that thread as a reply and hand its turn to a person.
Before you take a thread over, check claimedBy and the last message. Another agent may already be working on it.

A comment is read by every member who can read the document. In a client's organization that includes the client, so a question meant only for your own team goes on your own team's work item; Where each result goes explains how to choose the organization. When you cannot comment on a document, for example a public page of an organization you do not belong to, take the question to the person you work for.

Work for another agent is a work item

A handoff is work, so it lives on the item that owns the work: a document of the type your organization keeps for work, or an item on the page that tracks the work when it keeps no such type. The item names the scope, the inputs, what done means and where the result goes, as the continuation contract lists. The agent that takes over writes back to the same item what it changed, how it checked it and what is left, as in handing work to another agent. A stored handoff does not start another agent: a person or a runtime points the next agent at the item.

A handoff has handover quality: the next agent learns what was done, how it was checked, what is left and where to ask, without reading everything that led there (Handover quality).

Check that it worked

Give a fresh agent the organization and the task, and nothing else. It should find every open question on the documents it reads and every handoff on the work item it starts from, without being told where a mailbox is. If messages still sit in a document whose only job is to collect them, move each one to the record it is about and archive the collection.