Multi-agent orchestration

ClaudusBridge 2.0 combines native agent identity, persistent sessions, enforced package leases, dirty ownership and a job queue. Several assistants can share one project backend while seeing who owns work and why a call was refused.

These controls coordinate bridge calls. They do not create parallel Unreal game threads, isolate arbitrary external edits, or make every engine operation reversible.

Identify each agent

Use a stable, distinct --agent value across that agent's commands. Choose a role with --role writer|reader|observer|admin; the project policy can restrict the effective role. Identity is carried by the native connection instead of trusting an arbitrary tool argument to impersonate another agent.

claudus.exe who --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe session info --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant

These probes do not launch a backend unless --launch-headless is supplied. Sessions and timeline describes resume and explicit session end.

Lease packages before editing

Use the same agent identity for acquire, edit and release:

claudus.exe lock acquire /Game/Materials/M_Demo --lease 300 --note "Adjust material parameters" --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe lock list --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe packages /Game/Materials/M_Demo --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe lock release /Game/Materials/M_Demo --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant

Run the intended edits and saves between acquire and release. For a single request, call ... --lock /Game/Materials/M_Demo --lease 300 acquires the lease before dispatch and releases it afterwards unless --keep-lock is supplied. Inspect a timed-out mutation before retrying it, even if its temporary lease was released.

• /Game/X and /Game/X.X normalize to the same package key.
• Another agent's targeted mutation is refused with E_LOCKED while its lease is active.
• An owner's calls can renew an existing lease; a first mutation can auto-lease its inferred target according to policy.
• Dirty ownership protects saves: a package first dirtied by another live session can require that owner to save it. Read packages to distinguish dirty ownership from a lease.
• A permitted administrator can force supported ownership operations. This is a deliberate override, not a default retry strategy.
• An untargeted operation may touch a locked package after dispatch. Such violations are recorded and reported to the owner; the bridge does not promise to undo that change automatically.

The orchestration toolset's AcquireAssetLock, ReleaseAssetLock and session methods remain available through tool discovery. Version 2.0 uses the backend's ownership records; the old description of all locks as advisory no longer applies when enforcement is enabled.

Project policy

The backend reads <Project>/.claudus/policy.json. For example:

{
  "defaults": { "role": "writer", "autoLockSeconds": 60, "enforceLocks": true },
  "agents": {
    "review-assistant": { "role": "reader" },
    "asset-assistant": { "role": "writer" }
  }
}

claudus policy show --project-path <absolute-project> --agent asset-assistant reads that policy without connecting. Role restrictions, ownership, per-agent quotas and draining state can refuse a request. Check the returned structured error rather than retrying in a loop.

Long-running jobs

Discover ClaudusBridgeEditor.ClaudusBridgeOrchestrationToolset for the current schemas. RunToolAsync accepts toolsetName, toolName, argumentsJson, agentName and priority, queues a request and returns a jobId.

Use GetJobStatus, GetJobResult and ListJobs to observe completion. Jobs are scheduled by priority and FIFO within a priority. One job runs at a time; a synchronous engine call can still occupy the game thread. The queue makes lifecycle and results explicit, but does not turn blocking engine code into background computation.

CancelJob can cancel queued jobs. Running tools have their own cancellation limits. The watchdog can mark a stuck job as failed; it cannot safely preempt every engine function. Do not queue a tool that needs a human dialog in a hidden backend.

Call GetEditorBusyState before expensive work to inspect shader activity, the queue and running jobs. Poll at a reasonable interval and inspect final tool success as well as job completion.

A practical work cycle

1. Give each assistant a distinct stable identity and discover the relevant schemas.
2. Inspect package state; acquire a lease for the packages it will edit.
3. Apply a bounded change and inspect its result. Queue long operations when that tool supports the workflow.
4. Save the intended packages, verify persistence where needed, and release the leases.
5. Leave a timeline checkpoint with completed work, verification and the next action.

Use Unreal Multi-User only when you need distinct editor participants. Multiple MCP agents sharing one backend do not need a Concert session.