Zone Claims

Preemptive territory: how an agent tells the rest of the fleet to stay out of its working set.

Why This Exists

Collision detection is reactive. It fires after two agents have already converged on the same node. That's good enough when the edits are small, but it's the wrong shape of tool for a forty-minute refactor that touches a whole module. You do not want to discover on edit forty that three other agents have been independently rewriting the same files.

Zone claims are the preemptive layer. An agent declares up front: "I am working on this directory, this file, this function, for the next N minutes. Please coordinate with me before touching it." Other agents see that claim before they even call aura_snapshot, and they behave accordingly.

A zone claim is a social contract with machine enforcement. It says what the claimer is doing and costs the other agents almost nothing to respect.

The Sentinel enforces two grades of claim: warning zones, which advise other agents to coordinate but permit edits, and blocked zones, which cause other agents' edit tools to refuse outright. The distinction matters because most shared work is warning-grade — "heads up, I'm here" — while a small number of large refactors are genuinely block-grade.

How It Works

A zone is a tuple of:

A scope — a path glob, a specific file, or a fully-qualified logic node.
A mode — warn or block.
A TTL — how long the claim lives before it auto-expires.
An owner — the agent session that claimed it.
A reason — human-readable text that other agents will see.

Claims live in the Sentinel state store, replicated to the Mothership for team visibility, and they interact with the rest of Sentinel in two places:

Pre-edit check. aura_snapshot evaluates the target file against every active zone. A warning zone adds a banner to the response; a blocked zone turns the response into an error.
Pre-commit hook. When an agent that does not own a blocked zone tries to commit files inside it, the hook refuses the commit with a reference to the owning agent.

The owner can edit their zone freely. Humans (recognized by Aura's identity system) always bypass blocks, but the block is logged and the owning agent is notified.

Claim shapes

Scope types accepted by aura_zone_claim:

path:   src/auth/**            — a glob of files
file:   src/auth/user.py       — one file
node:   py:src/auth.py::login  — a single logic node

Node-level claims are the most precise and the least disruptive. File and path claims are coarser and should be reserved for the cases where the change really is module-wide.

TTL semantics

Every claim has a TTL. The default is one hour. The maximum is eight hours — long enough for a deep session, short enough that a forgotten claim can't paralyze the team overnight. When the TTL expires the claim is removed automatically; the owner can extend it with another call.

The TTL is a feature, not a limitation. It forces agents to work in bounded chunks and declare their scope out loud. An agent that needs to claim src/** for eight hours is almost certainly doing the wrong thing.

Warning vs Blocked

The difference between warning and blocked is the difference between information and enforcement.

| Property | Warning | Blocked | | --- | --- | --- | | Other agent can aura_snapshot the file | Yes | No (error) | | Other agent can commit | Yes, with log entry | No, hook refuses | | Other agent is notified | Yes, on every tool call touching the zone | Yes, with a stronger banner | | Humans can override | N/A, no block to override | Yes, always | | Default for aura zone claim | Yes (unless --block passed) | No, opt-in | | Good for | "heads up, I'm refactoring" | "do not touch, structural change in flight" |

The rule of thumb: default to warning. Reach for blocked only when a mid-flight edit by another agent would genuinely corrupt your work — large renames, API surface changes, migrations, anything where a concurrent edit would produce a broken semantic merge even if the text merges cleanly.

Examples

Claiming a file for a refactor

From a terminal, or via the equivalent MCP tool:

aura zone claim \
  --path "src/auth/**" \
  --ttl 2h \
  --mode block \
  --reason "OAuth 2.1 migration in progress. See RFC-023."

Any other agent that tries to touch a file under src/auth/:

[Gemini] → aura_snapshot file=src/auth/oauth.py
         ← 🚨 TEAM ZONE BLOCKED
            owner: claude session 7f3a2b
            reason: "OAuth 2.1 migration in progress. See RFC-023."
            expires: 2026-04-21T18:00Z
            You cannot edit this file until the zone is released.

Claiming a single node

Most of the time the right claim is node-level — it tells other agents exactly what you are editing without walling off the whole file.

aura_zone_claim
  scope: "node:py:src/payments.py::PaymentProcessor.charge"
  mode: warn
  ttl: 45m
  reason: "Adding Stripe 3DS support — safe to edit other methods"

Now other agents can still work inside payments.py — they just get a banner when they look at charge itself.

Releasing early

Claims are explicit contracts. Release them the moment you are done.

aura zone release --id zone_7f3a2b_1

Or via MCP:

aura_sentinel_release zone_id=zone_7f3a2b_1

The Sentinel will also auto-release a claim when the owning session ends cleanly, and it will prompt the owner to release when aura_log_intent is called on a commit that completes the stated reason.

Listing active zones

aura zone list

Output:

ID                OWNER               SCOPE                        MODE    EXPIRES
zone_7f3a2b_1     claude/7f3a2b       src/auth/**                  block   in 1h 47m
zone_def456_2     cursor/def456       node:...::payment_webhook    warn    in 22m
zone_gem0091_3    gemini/0091         file:docs/architecture.md    warn    in 3h 04m

Overriding a block (human-only)

If you are a human developer and you know better than the blocked agent:

aura zone override --id zone_7f3a2b_1 --reason "Urgent hotfix, Claude notified"

The owning agent's session receives a SENTINEL ZONE OVERRIDE event on its next call with your reason attached.

Configuration

[sentinel.zones]
default_ttl = "1h"
max_ttl = "8h"
default_mode = "warn"
auto_release_on_intent = true    # release when log_intent matches reason
broadcast_to_mothership = true

[sentinel.zones.policy]
# Per-agent defaults
"claude-code" = { max_ttl = "4h" }
"cursor"      = { max_ttl = "2h" }
"copilot"     = { max_ttl = "30m" }

auto_release_on_intent is worth highlighting. When an agent logs intent that matches the stated reason of its claim (a fuzzy match on the text), the zone is released automatically. This keeps the zone registry clean without the agent having to remember the release call.

API Surface

The full MCP surface for zones is small and easy to memorize.

| Tool | Purpose | | --- | --- | | aura_zone_claim | Create a new claim (path, file, or node). | | aura_sentinel_release | Release a claim by id. | | aura_sentinel_status | List claims relevant to your session. | | aura_sentinel_agents | See every active agent and their claims. |

Every one of these tools is agent-agnostic. Claude, Cursor, Gemini, and Copilot all call the same endpoints with the same payloads.

Patterns and Anti-Patterns

Do claim a node when your refactor will rewrite its body.

Do claim a file when your change restructures its top-level layout.

Do claim a directory (warn mode) for migrations that move files around.

Don't claim the entire repo. If your work is that broad, it needs a human-scoped plan, not a zone.

Don't hold a blocked claim overnight. TTLs exist for a reason.

Don't use block as the default. You will quickly become the agent everyone else ignores.

A well-run agent fleet makes dozens of small zone claims a day. It makes one or two big ones a week. The ratio tells you whether your team is cooperating or colonizing.

Zones in Practice

A few patterns show up repeatedly once a team has been running Sentinel for a few weeks.

The morning claim. An agent's first action on a large task is to claim its scope. This is habitual; it takes five seconds and saves an hour of downstream confusion. Good protocol files (CLAUDE.md, .cursorrules, GEMINI.md) all codify this expectation.

The shrinking claim. An agent starts with a file-level warning claim while it figures out the scope, then narrows to a node-level claim once the scope is clear. This is polite and produces the least disruption for other agents.

The escalation. A warning claim becomes a block claim when the scope turns out to be bigger than expected. This is better than keeping a too-small warning claim and hoping nobody crosses it.

The release at intent. auto_release_on_intent = true means the agent doesn't have to remember the release call. The claim evaporates when the stated work is done.

The override log. Humans overriding blocks is normal. The log of overrides is a useful signal — if a particular agent's blocks are being overridden frequently, that agent's scope-setting is off.

Debugging Zones

When something is wrong with zones — a claim you can't release, a phantom claim from a crashed session, a block that shouldn't be there — aura doctor --zones is the tool:

aura doctor --zones

active zones: 4
  zone_7f3a2b_1  claude/7f3a2b  src/auth/**         block  expired 14m ago (stuck)
  zone_def456_2  cursor/def456  node:...::webhook   warn   ok
  zone_gem0091_3 gemini/0091    file:docs/arch.md   warn   ok
  zone_orphan_4  session ended  src/api/**          block  ORPHANED

recommendations:
  - zone_7f3a2b_1: auto-release failed, run `aura zone release --id zone_7f3a2b_1 --force`
  - zone_orphan_4: session is gone, sweep with `aura zone sweep-orphans`

The doctor prints these findings on every session start if it detects stuck state, so in practice teams rarely need to run it manually.

Why Not Per-Branch Locks?

A reasonable question: why does Sentinel use zones instead of exclusive branch-level locks, which are more familiar from older VCS systems like Perforce or TFS?

The answer is that branch locks are too coarse and too brittle. Agents branch frequently, often without human supervision. A branch-level lock system either grants locks too easily (defeating the purpose) or too strictly (serializing work). Zones sidestep the question by operating at the scope the work actually lives in — a file, a module, a function — and by being negotiable through messages rather than permissions.

The other answer is that branch locks assume a one-to-one mapping between agents and branches, which does not match reality. A single Claude session might touch four branches during a rebase. Four agents might all be working on the same branch. Zones are agnostic to branch structure.

Zones are the right unit because work is the right unit. Branches are an implementation detail.