Using Agent Mail

Core Insight: Agent Mail is the side channel for leases, notifications, acknowledgements, and handoffs. BR/beads is the durable coordination bus and source of truth for work state, evidence, and decisions.

⚠️ TWO SURFACES — read this first. Every operation has BOTH an MCP-tool form (send_message, fetch_inbox, …) AND a CLI form (am mail send, am mail inbox, …). The MCP tools are only present when the agent-mail MCP server is wired into your session's tool surface — a plain CLI/shell agent (or a session where the MCP server didn't load) will NOT have them. In that case use the am CLI, which works from any shell. Discoverability trap (br cp-jgcl): the send/reply verbs live under the am mail group, which am --help does NOT list, and the read commands have flat aliases (am inbox, am status) but am send does not exist — it is am mail send. When in doubt: am mail --help, am macros --help, am file_reservations --help.

Don't re-learn the command surface from this skill. The MCP server self-describes its tools and resources in your tool list; the CLI self-describes via am --help and the group helps above. This skill carries only the operating doctrine: when to use mail, the reservation discipline, and the coordination boundaries. Full tool/parameter catalog: TOOLS.md.

When this applies (scope guard). Agent Mail coordination — start-session, identity registration, file reservations, cross-lane ACKs — is required when ≥2 lanes/panes share the repo (a swarm, or you plus a concurrent peer session). With only one active writer (no second lane/pane), do not register or reserve against yourself — coordination is an escalation, not a session-start tax. If you are the sole writer, skip to the work. (Doctrine: operating-loop principle 8 — single-agent-first.)

Asymmetry guardrail — the part of the de-mandate that does NOT relax. AM answers a contention axis; ATM answers a separate durability axis (they're not a package — full 4-case matrix in using-atm). The de-mandate removes the single-writer session-start tax, not the collision guard. The costs are asymmetric: an unneeded AM call costs one command; a missing one lets two writers silently clobber a shared file and the merge looks like ordinary conflict cleanup while the design forked. So the ≥2-writers → reserve reflex stays non-negotiable. "Trust the models" does not grant two concurrent writers consistency on one path. Partition before you lock: if you can cut the write-sets disjoint (sole writer per file), do that instead of reserving — locks are the fallback when partition fails.

Coordination Boundary