Agents & MCP.

The tool surface

The bridge registers the coordination tools agents use most:

Task orchestration adds create_task, claim_task, update_task, list_tasks, assign_tasks, and advance_tasks — see Orchestration. update_task records the outcome on the task itself: result (text, up to 8192 chars) and artifacts (up to 32 paths or URLs) are stored with result_by and result_at, completion events carry has_result, and check_handoffs delivers a task's result in-band to its assignee.

The fence & blocked-claim pattern

A successful claim_path returns a fence — pass it back to release_claim later to prove you still own the file. A claim on a held file comes back as an MCP error whose text leads with ⛔ and carries a machine-readable resolution; agents should read the body, not just the status:

⛔ public/index.html is held by claude (frontend)
resolution: {
  "auto_handoff": true,
  "queue_position": 1,
  "blocked_by": { "agent": "claude", "tool": "claude-code", "role": "frontend", "age_seconds": 42 },
  "recommended": "work_elsewhere"
}

You're already queued — don't spin. Either take an unclaimed file in your own lane, or poll check_handoffs on your next turn; the moment the holder releases, the file is yours with a fresh fence. MCP can't push, so this in-band poll (carrying a cursor) is the intended pattern.

Signing

The bridge holds a per-session Ed25519 key and signs each claim and message, so the event log is cryptographically attributable (verify offline with regente verify). Regente stores bounded key history per agent, so a normal MCP restart and key rotation does not invalidate older signed events. Signing is on by default; set REGENTE_SIGN=0 to disable. The engine stays backward-compatible — it accepts unsigned actions and only rejects a wrong signature once a public key is on file for that agent.

The session hook

regente install registers regente-hook in each tool's config (e.g. .claude/settings.json). On session-start it joins the workspace; later hook calls are heartbeats that refresh presence without re-declaring the session — and deliver pending direct messages into the session, stamping delivered_at — and a PreToolUse (claude-code) / BeforeTool (gemini) hook runs the edit guard. Identity is derived from the session id (not the process tree), which keeps stale "ghost" agents from accumulating — and the guard maps that session back to the agent that claimed under it, so the owner is never blocked from its own file (set REGENTE_AGENT_ID for a fully deterministic identity). Codex has hooks and MCP, but no live pre-tool edit hook in this release, so Regente installs a git pre-commit guard for Codex-driven repos. Cursor has no native hook — the default install writes its project MCP config and onboarding rules, and it joins on its first join_workspace call. After installing, restart a running session so the hook and MCP load.

Adapter health tools

Agents and humans can inspect the same adapter truth. adapter_status and regente doctor --adapters report whether the session hook, heartbeat hook, edit guard or pre-commit guard, MCP command, MCP args, env.REGENTE_ROOT, and cwd are valid. discover_agents and regente discover --json collapse helper process trees and classify sessions as connected, detected, or external.

regente doctor --repair
regente discover --json

HTTP API

For non-MCP automation, the local server exposes the same engine over loopback (127.0.0.1:8787, JSON, 1 MiB cap). Reads: GET /api/state, /api/discovery, /api/adapters/status, /api/metrics, /api/symbols?path=, delivery events in GET /api/state, and a live GET /api/events (SSE) stream. Writes mirror the CLI:

POST /api/join · /api/heartbeat · /api/claim · /api/release
POST /api/message · /api/ack · /api/handoff · /api/adapters/install
POST /api/init   · /api/task/create · /api/task/update · /api/role
POST /api/enforce · /api/context · /api/plan · /api/assign · /api/drive

The server binds to loopback only and isn't exposed on the network by default.