{"id":"agent-mail","name":"agent-mail","summary":"Agent Mailは、明示的に連携したライター向けのオプションのメッセージングおよびファイル予約アダプターとして使用してください。","body":"# Agent Mail — optional coordination adapter\n\nAgent Mail carries messages, acknowledgements, identities, and temporary file\nreservations. It is not a task tracker, queue, proof ledger, or lifecycle\ncontroller.\n\nReservations are **advisory**: they prevent collisions only because every\ncooperating writer checks them against the same absolute project path, and one\nwriter registered against a different path resolution makes the whole ledger\nadvisory fiction. Agent Mail enforces nothing on a writer that does not check.\n\nNamed failure mode — **silence-as-status**: reading an unanswered thread as\n\"work stalled\" or \"work done\"; mail silence proves only that no mail arrived.\n\nAnti-pattern: widening or renewing a reservation unprompted when a conflict\nappears. Corrective: report the conflict to the caller as-is; scope and TTL\nchanges are the caller's call.\n\n## Boundary\n\n- Skip Agent Mail for a single writer.\n- The caller supplies the absolute project path, agent identities, thread id,\n  participants, paths, exclusivity, reason, and TTL.\n- Reservations prevent accidental overlap among cooperating writers. They do not\n  create work ownership or affect Plan, Candidate, or verdict semantics.\n- Mail silence proves nothing about work status.\n- A message or acknowledgement is evidence that communication occurred, not\n  evidence that a change is correct or complete. The adapter cannot select\n  AgentOps semantics, issue a binding verdict, or turn factory completion into\n  delivery or validation proof.\n- Release a reservation, including any `force_release`, only on the caller's\n  explicit request for that exact reservation. Force-release has no autonomous\n  trigger; a conflict is reported, not force-cleared.\n- Agent Mail never selects work, changes tracker state, commits code, validates,\n  integrates, closes, releases, or delivers work.\n\n## Modes and authority\n\nTwo disjoint surfaces; do not reach the second from the first:\n\n- **Coordination mode (default).** Register identity, reserve/release the\n  caller's paths, send/read/acknowledge the caller's threads. This is the whole\n  of routine use, and all of it writes durable Agent Mail records.\n- **Admin / disaster-recovery mode (explicitly caller-authorized only).**\n  Installing the git pre-commit guard, `doctor repair`, backup/restore, and the\n  irreversible `clear-and-reset-everything` are a separate mode. Each requires\n  the caller's explicit authorization for that specific operation; none is ever\n  performed as a side effect of coordination. `clear-and-reset-everything`\n  deletes the database and all storage and cannot be undone — never run it, even\n  with `--force`, without an explicit destructive-reset authorization from the\n  caller.\n\n## Surfaces\n\nChoose exactly one mailbox owner and access mode for each storage root. When an\nHTTP/MCP daemon owns the root, use its MCP tools; do not point the direct `am`\nCLI at the same database. Use the CLI fallback only with a root not owned by a\nrunning Agent Mail runtime. A busy mailbox activity lock or a bounded read\ntimeout is a degraded adapter result, not permission to restart the service,\nrepair the database, or silently switch roots.\n\nUse the MCP tools when they are present. Otherwise use the self-describing `am`\nCLI. Pin the intended storage root explicitly, and discover current syntax with\n`am mail --help`, `am file_reservations --help`, and related group help; do not\ninfer commands from remembered aliases. If a direct macOS read rejects a\nsymlinked snapshot directory such as `/var`, use a caller-scoped, non-symlinked\ntemporary directory for that isolated invocation or report the adapter\ndegraded; never weaken the traversal check.\n\n## One-shot use\n\n1. Confirm that multiple explicitly coordinated writers share the repository.\n2. Freeze one storage root and either MCP/server mode or direct-CLI mode; never\n   mix both against the same live database.\n3. Register the caller-supplied identity against the same absolute project path.\n4. Reserve only the supplied paths, with a bounded TTL.\n5. Report conflicts without waiting, narrowing scope, or changing the plan.\n6. Send the supplied message once and record its id.\n7. Read or acknowledge only the requested thread.\n8. Before the caller advances a declared transition, verify every\n   acknowledgement-required message in that transition has the intended\n   recipient acknowledgement. Later traffic is not an implicit acknowledgement.\n9. Release only reservations the caller explicitly asks to release.\n\n## Output\n\nReturn the project, identity, thread/message ids, reservation ids and paths\n(with their TTLs), conflicts, and timestamps. The caller owns all subsequent\ndecisions.\n\nTerminal outcomes are explicit, never silent:\n\n- **Adapter unavailable** — neither the MCP tools nor the `am` CLI is present:\n  report that Agent Mail is unavailable and stop. Do not fall back to\n  hand-written coordination or treat the absence as \"no conflicts\".\n- **Reservation conflict** — report the conflicting reservation as-is; do not\n  narrow, widen, renew, or force-release it.\n- **Mailbox ownership conflict** — a daemon and direct CLI contend for one\n  storage root: report the lock owner/mode and stop; do not restart, repair, or\n  bypass the lock as a coordination side effect.\n- **Required acknowledgement pending** — report the exact message and intended\n  recipient and stop the dependent transition. Do not infer acknowledgement\n  from a later reply or repair it after validation.\n- **Timeout / degraded surface** — report the operation as timed out or degraded\n  with what was and was not observed; a timeout is evidence, not \"done\".\n- **Cleanup** — reservations released this session are listed by id; any left\n  in place (still holding a TTL) are named so the caller can see what remains.\n\n## References\n\n- [CLI and MCP surface notes](references/TOOLS.md)\n- [Coordination patterns](references/WORKFLOWS.md)\n- [Troubleshooting](references/RECOVERY.md)","author":"@boshu2","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/boshu2/agentops/tree/main/images/gemini/skills/agent-mail","license":"Apache-2.0","category":"document","lang":"en","tokens":1260,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}