How coordination works

AgentCollision starts by blocking a second writer: when two chats reach for the same file, the later one is denied before its edit lands. That stops the clash — but the two agents could go further and just sort it out: reach out, agree who goes first, hand off the file. That's coordination, and how far it goes is entirely up to you.

The one knob: autonomy_level

Rather than wire up half a dozen switches, you set one value and AgentCollision maps it onto the individual behaviors.

• manual — detection only. Collisions are blocked and recorded; you handle every handoff by hand. Nothing is sent to a peer automatically.
• assist — agents flag, you confirm. A blocked agent messages the holder and opens a negotiation, but the actual handoff waits for a human.
• auto — end-to-end. The daemons broker an idle holder's lease and release it automatically; the blocked agent just proceeds.

Set it interactively — this walks you through solo / small-team / compliance presets and writes the config for you:

agc arc-claim policy

Or set it directly in ~/.agentcollision/claims_policy.yaml:

session:
  autonomy_level: assist   # manual | assist | auto

Reach-out: a heads-up on conflict

At assist and above, when your edit is denied because a peer holds the file, your daemon automatically messages the holder — “I need src/auth.ts, you're holding it; can you wrap up?” — instead of you noticing the denial and pinging by hand. It's deduped per (you, holder, file) on a cooldown (default 5 minutes), so nobody gets spammed about the same file.

Negotiation: brokering the handoff

Reach-out is a heads-up. Negotiation is the brokered exchange that can actually free the file. When you hit a held file, your daemon opens a negotiation proposing an outcome, and the holder's daemon decides — in a strict priority order:

1. Policy first. If negotiation is off, or the policy says “decline” / “ask a human”, it never auto-grants.
2. Protect the active first-holder. If the holder has a tool in flight, or has held the file only briefly (default under 120 seconds), the daemon counters or declines. Being first and active is the strongest claim — AgentCollision will not pull a file out from under an agent mid-edit.
3. Idle-grant. Only when policy allows and the holder is genuinely idle does the lease release to the requester.

When the holder proposes a wait (a counter), it becomes a tracked, multi-turn exchange — countered → accepted → resolved — that you can watch live on the dashboard. This priority order is why auto is safe to turn on: it only ever releases leases that are already idle.

Automatic handoff

Under auto, when a negotiation resolves to a grant (idle holder, policy permits), the holder's daemon releases the lease immediately. The blocked agent's next check finds the file free and acquires it — the handoff completes with no human and no extra round trip. It's best-effort and only ever fires on an idle grant; an active holder is always protected.

Branch-level collisions

Collisions aren't only about the same file. If two chats are working on the same git branch in the same repo, they'll diverge even if they never touch the same line. At session start, AgentCollision checks for another active agent on your branch and, if it finds one, flags it — an event plus a heads-up message naming the peer and branch. This is advisory: it never blocks a write, it just makes sure you know up front. It's on whenever reach-out or negotiation is enabled (i.e. assist or auto).

The Protection page

The dashboard's Protection page (at /protection) is the single view of everything AgentCollision has governed for you, over a window you choose:

• Collisions prevented — a second writer was blocked off a held file.
• Conflicts caught — unmanaged writes, bypassed commits, and branch contentions flagged.
• Edits coordinated — edits that ran under a lease, with no clash.
• Coordinated autonomously — handoffs the daemons brokered and completed without a human.

Alongside the protection metrics, the page shows your real AI usage — calls, tokens, and cost per chat — read from your local Claude Code logs (Pro/Max) and the spend proxy (API-key agents). It opens at localhost:7777/protection locally or dashboard.agentcollision.com/protection hosted.

How this fits together

• Blocking is the floor — on at every level, including manual. Nobody silently overwrites anybody.
• Coordination is what you opt into on top: reach-out, negotiation, and automatic handoff, scaled by autonomy_level.
• Yield requests are the explicit, human-initiated version of the same idea — “please release this lease” — for when you want to ask directly rather than wait for a conflict.

Next steps

• Quickstart — install the daemon and see a block in two minutes
• CLI reference — agc arc-claim policy and every other command
• Invite your team — and lock autonomy_level as a standard
• FAQ for common questions