agent-mail

name: agent-mail user-invocable: false skill_api_version: 1 hexagonal_role: supporting metadata: tier: execution description: "Use when coordinating agents with Agent Mail locks, inboxes, threads, and conflict-prevention handoffs." practices:

• pragmatic-programmer

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.

Coordination Boundary

Use Agent Mail to prevent collisions and notify active agents. Do not use it as the durable task queue, audit log, or final evidence store. If a mail thread and BR disagree, reconcile the bead first and link the mail thread from the bead note if the conversation matters.

One-writer-per-hot-dir rule: reserve the path before editing it. If the reservation conflicts, do not write into that path; coordinate with the holder, narrow scope, or wait for the lease to clear.

Coordination disciplines (2026-06-09, cards 1–5, cp-hhd7)

Durable lane identities (card 1, cp-9lrb)

Register a durable adjective+noun identity at session start. Pane text and human relay are unauditable and load the operator. The ledger is the bus — both lanes must be registered to exchange auditable messages. Do not coordinate via informal pane text when send_message + fetch_inbox is available.

Content-push, not pointers (card 2, cp-9lrb)

When sending a lane a message, push the content — include the actual text, diff, or decision. A pointer to a message-id the recipient cannot discover by inbox is still a relay. If the recipient's inbox is broken and they cannot read by-id, a pointer is a dead end. Short content fits in the body; long content goes to a committed artifact with an absolute path, not an AM-internal id.

Intent on the graph first — dedup (card 3, cp-hhtu)

Before any actor acts on a bead (intake, admit, implement, validate, mutate), update the bead status and set the actor on the graph first, then check for an existing actor. Parallel pipelines are blind to each other at every tier — dedup via the ledger, not behavioral coordination. Five exhibits of same-bead parallel work hit the fleet in one day (impl/validation/admission/mutation/intake, cp-hhtu). The fix is structural: intent on the graph is the lock.

ACK-with-id on routed writes (card 5, cp-fmt8)

When routing a write through a single writer (e.g. a beads-intake lane), require ACK-with-id back to the requester — the AM message id of the filed bead or the br show <id> output confirming the record exists. An unacknowledged routed write is invisible work. "Are these filed?" must not be a question — the ACK closes it.

When to Use What

Session Bootstrap

Call macro_start_session (or am macros start-session --project <abs> --program <p> --model <m> --task "<desc>") at the start of every agent session. One call: ensures project exists → registers your identity → fetches inbox. Returns {project, agent, file_reservations, inbox}.

Identity notes:

• Agents get adjective+noun names (GreenCastle, BlueLake). Omit name/--name to auto-generate a valid one.
• am macros start-session auto-generates a fresh identity per project; you will have a different name in each project. Confirm yours via am agent start.
• The other macros (macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake) and the fast resource:// reads are self-described by the server; catalog in TOOLS.md and RESOURCES.md.

File Reservations — Reserve Before Editing

The discipline, not the syntax (syntax: am file_reservations --help or the file_reservation_paths tool):

1. Reserve before the first write. Glob patterns are fine (src/auth/**/*.ts). Set a real ttl_seconds and put the bead id in reason.
2. Check conflicts in the response. On conflict: wait for TTL expiry, message the holder, or share with exclusive=false. Never write into a conflicted path.
3. Release when done (release_file_reservations / am file_reservations release <abs> <me>). Don't squat on leases across unrelated work.

Beads Integration

Use bead IDs as your threading anchor. BR remains authoritative; mail carries the lease, notification, and discussion side channel.

1. Pick work:        br ready --json → choose bd-123
2. Reserve files:    file_reservation_paths(..., reason="bd-123")
3. Announce:         send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
4. Work:             Reply in thread with progress
5. Record evidence:  br update bd-123 --notes "Validation: tests, commit, CI, or handoff proof"
6. Complete:         br close bd-123, release_file_reservations(...), final message

Bead ID (often bd-###) goes in: thread_id, subject prefix, reservation reason, commit message

Do not infer durable state from mail silence. A missing reply is not proof that a bead is abandoned, blocked, or complete. Check br show <id> --json, bv --robot-insights, git state, and CI evidence before changing work state.

Quick Troubleshooting

Deeper diagnostics (doctor check/repair), the pre-commit guard (install_precommit_guard), the human-overseer web UI, and FTS5 search syntax are all self-described by the server/CLI — see RECOVERY.md and ADVANCED.md.

References

Validation

curl http://127.0.0.1:8765/health   # → {"status": "healthy"}
am                                  # start server if needed