Agent Lease

agent-lease-mcp

Keep two coding agents (Claude Code and Codex, or two sessions of either) from overwriting each other's work in the same repository.

agent-lease gives them leases on paths, presence and a shared message log — and the lease is enforced by a PreToolUse hook, not by good intentions. An agent that tries to edit a file another agent is working on is refused before the edit happens.

Česky / Czech version

Why it exists

9 September 2026. A coordination file, docs/AGENT-HANDOFF.md, existed and both agents knew about it. At 22:28 they still both touched deploy/make-work-package.sh: one was editing it while the other was running it. Bash reads a script as it goes, the text shifted under the running process, and instead of a 3.7 GB installer the build produced a useless 198 MB one.

The lesson the whole project rests on: coordination that can be ignored will be ignored. Not out of malice — an agent at work simply does not look at the notice board.

The same collision was later replayed on purpose: Codex ran the script, Claude Code tried to edit it mid-run, and the hook refused the edit. The file stayed intact.

How it differs

Advisory locks get broken; AgentRoom documents this itself. Claude Code and Codex both have PreToolUse hooks with the same semantics (exit 2 = block, reason on stderr), so a lease can be enforced deterministically at the tool-call level. One script serves both clients.

Rules it is built on

• A lease, not a lock. 30-minute TTL. A crashed agent cannot block the repo forever.
• All or nothing. A claim on several paths succeeds completely or not at all.
• A lease on a directory covers everything under it.
• A free file is claimed automatically on the first edit, so nobody has to remember to call claim.
• A running script is leased for the duration of the run — exactly the combination that broke the build.
• Fail-open by default. Broken coordination must not stop work; otherwise the first thing anyone does is switch the hook off. AGENT_LEASE_FAIL_CLOSED=1 flips this for unattended runs.

What runs on its own

Injections stay silent when there is nothing to say.

Waking a sleeping agent

Hooks only fire when the agent acts, so an idle session is woken from outside, without spending model tokens:

• Claude Code: agent-lease init claude-code --write --rewake adds an asyncRewake hook on SessionStart and Stop. It waits on a signal file and wakes the session when an addressed message from someone else arrives. Broadcasts and automatic receipts do not wake it.
• Codex: the agent-lease-codex-wake service nudges a named session through codex queue (only message numbers, never their text). After a provider limit ends, it nudges once for unfinished work. Setup: /rename nox in Codex, AGENT_LEASE_CODEX_THREAD=nox in ~/.config/agent-lease/environment, then enable deploy/systemd/agent-lease-codex-wake.service.

A message from another agent is information, not a human instruction. For agents to hand work to each other unattended, the human writes the allowed scope (and what always needs asking) into the agent's own instructions, e.g. ~/.codex/AGENTS.md. Template and details (in Czech): docs/ZPRAVY-A-POTVRZENI.md.

Tools

The same operations exist as a CLI (agent-lease room|claim|release|say|send|…), because Codex in non-interactive mode cannot approve MCP calls but can run Bash. agent-lease wait --for blocks without spending model tokens and wakes a background session when a message arrives.

say/inbox is not a live chat: MCP is pull, the other side reads a message when it next looks. For a live view there is a local web room: agent-lease web --open (loopback only, see Security).

Quick start (two minutes)

uv tool install agent-lease-mcp

agent-lease init claude-code --write --rewake # writes all hooks, keeps a .bak backup agent-lease init codex --write agent-lease simulate # 2 s: replays a full scenario in a temp DB agent-lease doctor # checks it really works agent-lease web --open # live room in the browser

init without --write only shows what it would write. Manual setup below.

Install

uv tool install agent-lease-mcp

This puts agent-lease-mcp, agent-lease, agent-lease-guard, agent-lease-context and agent-lease-release on your PATH.

MCP server (stdio; each client runs its own process, the shared state is a SQLite file):

# Claude Code

claude mcp add agent-lease -e AGENT_NAME=claude-code -- agent-lease-mcp

# Codex — ~/.codex/config.toml

[mcp_servers.agent-lease] command = "agent-lease-mcp" env = { AGENT_NAME = "codex" }

Codex writes to ~/.agent-lease, outside the workspace — allow it:

[sandbox_workspace_write] writable_roots = ["/home/YOU/.agent-lease"]

Hooks — without them this is just a polite notice board:

// ~/.claude/settings.json

{ "hooks": { "PreToolUse": [{ "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash", "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-guard" }] }], "SessionStart": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-context" }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-context" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-release" }] }] } }

// ~/.codex/hooks.json — same events, AGENT_NAME=codex

{ "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "AGENT_NAME=codex agent-lease-guard" }] }] } }

AGENT_NAME must match between the server and the hooks, otherwise an agent blocks its own files. An agent called unconfigured-* in room means exactly that.

Optional: Bash safety gate

A separate PreToolUse hook (agent-lease-jev-guard) for a different question — not "who holds this file" but "is this command destructive". Hard rules (rm -rf /, force push, git reset --hard, curl | sh, mkfs…) apply as soon as it is wired in. An optional external classifier (TypeSafe Jev) is off by default, starts in shadow mode, receives only redacted commands and is advisory — never the only safeguard. Details in ADR 0003.

Receipts, failover, bridge and broker

• Every addressed message has a visible state ⏳ → 👁 seen → ✔ taking → done. "Seen" is written by the hook automatically; "taking" must be acknowledged by the agent (accept) and is reminded on every prompt. Nothing gets lost silently. agent-lease overdue lists what nobody acknowledged.
• Limits and failover. Codex workers read the explicit typed availability signal from the local App Server. Other workers record a limit only after a real provider/CLI error; if no reset time is supplied, agent-lease does not invent one. Manual agent-lease limit / MCP report_limit remains available. Unaccepted, unstarted tasks then move to the next agent in AGENT_LEASE_FALLBACKS (e.g. codex=claude-code;claude-code=codex) after a grace period, and the sender is told.
• Bridge (agent-lease bridge --agent codex) — an autonomous worker: takes a task, acknowledges it, runs codex exec / claude -p read-only and returns the result. --provider openrouter --model sends it to any model through OpenRouter as plain text without tools (read-only; good for review and a second opinion). Keys only from the environment. Worker presence/provider state uses a separate identity (codex-bridge, claude-code-bridge), so a headless quota cannot overwrite the state of an interactive agent.
• A task never runs twice. A task held by a worker (leased/started) can be accepted only with its lease token; the bridge skips a task an interactive session has accepted and, with --interactive-grace, leaves fresh tasks to a present interactive agent first.
• Broker (agent-lease broker) — single SQLite writer over a 0600 Unix socket; other tools use it automatically when it runs, so a sandboxed Codex does not need direct access to the database. Clients survive a broker restart: the connect is retried (nothing was sent yet), an interrupted call is never repeated, and long-running workers continue with the next call.
• Overview panel in the live room: each agent's active task, queue, unacknowledged items, typed provider state, reason for waiting, limits and items to review. Tasks may declare repeatable --path worksets and a --priority; the scheduler skips paths held by another agent and the board shows the blocking path, owner and TTL. agent-lease notify --loop sends to Telegram only what waits on the human, each event at most once (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID from the environment; --dry to test).
• Operating workers safely. agent-lease worker-activate and agent-lease failover-activate set a safe starting point without running or moving any task: only wo