[Relay] Add scoped nested delegation and immutable grants

[ranveersequeira]

Parent

#377

What to build

Allow an Agentify-managed child to spawn or message another worker through injected relay MCP tools, while making escalation structurally impossible.

The broker—not the model and not caller-supplied fields—must own the authoritative task tree, remaining budgets, workspace roots, provider allowlist, delegation depth, fan-out, and permission grant.

User story

As a repository owner, I can permit one bounded level of Claude↔Codex delegation without allowing a child agent to broaden its authority, spend indefinitely, inspect unrelated tasks, or write to the workspace.

Effective grant

A child's effective authority is the intersection of:

repository policy
∩ controlling client grant
∩ parent task remaining grant
∩ provider capability
∩ operating-system enforcement capability

At minimum, a grant records:

• parent task and immutable depth;
• allowed operations and visible task IDs;
• provider/model/route allowlist;
• maximum children and total descendants;
• remaining time, turn, token/cost budget where measurable;
• workspace roots and read-only access in this slice;
• terminal/network/MCP permission policy;
• expiry, nonce, and revocation state.

Required behavior

• Inject a task-scoped relay MCP endpoint/capability into eligible managed children.
• Derive parent task, depth, and visibility from the authenticated connection; ignore caller-supplied attempts to spoof them.
• Default maxDepth to 0. Nested delegation requires explicit repository/operator enablement.
• Recommended first enabled policy is maxDepth: 1, bounded children, read-only, and explicit provider allowlist.
• A child can only narrow limits. It cannot renew, transfer, mint, or widen its own grant.
• Charge child reservations/usage against the authoritative parent budget and concurrency pool.
• Prevent sibling observation or messaging unless explicitly granted by their common parent.
• Detect cycles and reject task-tree references outside the caller's visibility.
• Revoke descendant capabilities when the parent is cancelled or expires.
• Fail closed when budget telemetry is unavailable; record whether each limit is native, broker-enforced, pre-run-only, advisory, or unavailable.
• Do not treat AGENTIFY_CTX=off as the authorization mechanism; retain it only for context-capture recursion behavior.

Permission behavior

• Read-only filesystem is the maximum grant in this slice.
• Terminal and network default to deny or explicit ask according to repository policy.
• Non-interactive undecidable requests fail closed.
• Provider-native approval prompts cannot widen Agentify policy.
• A model cannot delegate permission approval to another model.
• Environment inheritance uses an explicit allowlist and never includes broker secrets beyond the scoped capability required for this task.

Acceptance criteria

• Nested spawn is denied by default and enabled only by explicit policy.
• An enabled parent can create a bounded child through the same MCP contract from [Relay] Expose scoped read-only collaboration tools through MCP #379.
• The broker derives parent/depth/visibility and rejects forged parent IDs, depth values, task IDs, or capabilities.
• Child provider, workspace, time, concurrency, fan-out, and budget limits never exceed the parent's remaining grant.
• Sibling task events/messages are invisible without an explicit delegated visibility capability.
• Parent cancellation or expiry revokes new child operations and propagates bounded cancellation to descendants.
• Cycles, excessive depth/fan-out, expired capabilities, replayed nonces, and revoked tokens fail deterministically.
• Budget reservation prevents concurrent children from each claiming the full remaining parent budget.
• Enforcement provenance is visible in dry-run/spawn receipts and terminal usage.
• Unavailable provider-native budget/turn enforcement is never represented as a hard cap.
• Capability tokens, authentication values, and environment secrets never enter public events or task reports.
• Deterministic tests cover Claude→Codex, Codex→Claude, depth exhaustion, sibling isolation, cancellation, expiry, and concurrent budget reservation.

Out of scope

• Write-capable nested workers.
• Shared-write workspaces.
• Model-controlled grant escalation.
• Remote or multi-user authentication.
• Arbitrary peer-to-peer agent messaging outside the broker.
• Guaranteeing a model will choose to use an available collaboration tool.

Blocked by

• Blocked by [Relay] Expose scoped read-only collaboration tools through MCP #379

[aeoess]

One thing I'd separate in the effective-grant model: repository policy, the controlling client grant, and the parent grant define what the child is authorized to do. Provider and OS capabilities define what of that authority can actually be enforced. So it may be useful to keep an authorized grant as the three-way intersection, then derive the effective grant from that plus provider/OS capability, while keeping the existing native / broker-enforced / advisory / unavailable provenance per limit. That preserves the fail-closed behavior without making an advisory limit look equivalent to a hard-enforced one.

For the test side, Agent Authority Conformance has four relevant negative paths with named error codes and a runner: scope expansion, depth violation, signature substitution, and expired validity: https://github.com/Agent-Authority-Conformance/aps-conformance-suite/tree/main/fixtures/composition/a2a-1496-negative-paths

It doesn't cover replay or revocation in that set. Happy to adapt the fixture shape to the grant record here if useful.