Azure / Azure/kars

Trust Circles: Parent-Mediated Sub-Agent Isolation (enhancement)

Open
#241 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Rust
Stars
42
Forks
10
Avg merge
1d 11h
Merged PRs (30d)
19

Description

## TL;DR
Add a logical **trust circle** abstraction to AGT so a sub-agent can only KNOCK its parent and its same-circle siblings. Cross-circle data flow must traverse parents (the audit + policy boundary). Top-level peer agents ("main" agents) continue to interconnect freely.

This is an **enhancement to defense-in-depth, not a from-zero security feature.** We already have multiple layers — see *Existing Controls* below. What's missing is a logical boundary that ties a sub-agent's allowed peers to its parent's task scope.

## Existing Controls (already shipped)
1. **Per-sandbox `NetworkPolicy`** — controller reconciles a NetworkPolicy per sandbox namespace. Direct pod→pod TCP between sandbox namespaces is blocked at the CNI layer; AGT traffic is forced through relay+registry in the `agentmesh` namespace. (`controller/src/reconciler/mod.rs`)
2. **Egress-guard** — sandbox pods drop UID 1000 to localhost+DNS only via iptables init container.
3. **AGT KNOCK protocol** — sessions only establish after a policy-gated KNOCK; handler in `inference-router/src/handoff/mod.rs`.
4. **AGT trust scoring** — `AGT_TRUST_THRESHOLD` (default 500 in sandboxes) gates all peer connections. Anonymous (score 0) rejected; verified Tier 1 GitHub OAuth (score 600+) passes.
5. **E2E encryption** — Signal Protocol (X3DH + Double Ratchet); the relay never sees plaintext.
6. **Per-agent identity binding** — every AMID is cryptographically bound to its workload identity.

What's missing: trust score answers "is this peer verified?" but not "does this peer belong to your task?"

## Proposed Enhancement: Trust Circles
A **trust circle** is the set of agents spawned (directly or transitively) under a single top-level task. Within a circle, peers may communicate freely. Across circles, only **top-level** peers may interconnect; sub-agents are circle-locked.

### Communication matrix
```
Parent A SubA* Parent B SubB* External (A2A)
Parent A ✅ ✅ ✅ ❌ per-policy
SubA* (A's sub-tree) ✅ ✅ ❌ ❌ ❌
Parent B ✅ ❌ ✅ ✅ per-policy
SubB* (B's sub-tree) ❌ ❌ ✅ ✅ ❌
```
Cross-circle data flow: SubA1 → ParentA → ParentB → SubB1.

## Implementation Outline (multi-PR)

### PR1 — circle_id plumbing
- Extend `ClawSandbox` CRD: `spec.circleId` (UUID) + `spec.role` (`top-level` | `sub-agent`) + `spec.parentAmid` (sub-agents only).
- Reconciler propagates `CIRCLE_ID`, `AGENT_ROLE`, `PARENT_AMID` env vars to the pod.
- Vendored `@agentmesh/sdk` + registry: include `circle_id` in registration metadata. (Vendor patch #19.)

### PR2 — KNOCK-time enforcement (the real gate)
Extend KNOCK policy in `inference-router/src/handoff/mod.rs`:
```
allow_knock(my, peer):
if my.role == 'sub-agent':
return peer.amid == my.parent_amid
|| peer.circle_id == my.circle_id
if my.role == 'top-level':
return peer.role == 'top-level'
|| peer.parent_amid == my.amid
|| (per-pair allowlist for cross-org)
```
Reject before session establishment; emit a governance event so dashboards show denied attempts.

### PR3 — discovery filtering + system-prompt reinforcement
- Router-side `discover` filter:
- Sub-agents see: parent + same-circle siblings only.
- Top-level agents see: all top-level peers + their own sub-tree.
- `runtimes/openclaw/src/core/agt-task-loop.ts:83`: add Trust Circle paragraph to the sub-agent system prompt.

### PR4 — parent-mediated cross-circle bridge (optional escape hatch)
- New sub-agent tool: `request_cross_circle(target_role, message)` — proxies through parent.
- Parent receives a `cross_circle_request`; parent decides whether to forward to ParentB.
- Audit-logged in the `governance` namespace.

### PR5 — A2A interop (forward-looking)
When A2A ships, only top-level peers are externally reachable. Trust Circle becomes the unit that A2A "agent cards" map to.

## Industry Alignment
- **OpenAI Swarm / Anthropic** — orchestrator-mediated handoffs; sub-agents don't cross.
- **AutoGen GroupChat / Magentic** — manager pattern; sub-agents speak through the manager.
- **Google A2A agent cards** — per-agent ACLs at the org boundary.
- **K8s namespaces + NetworkPolicies** — same blast-radius pattern we already use at the pod layer, lifted to AGT.

## Non-Goals
- Not a replacement for trust scoring (additive).
- Not a tenant-isolation feature on its own (that's K8s namespaces + RBAC + per-tenant subscriptions).
- Not a substitute for Content Safety on each LLM hop.

## Risks & Mitigations
| Risk | Mitigation |
|------|------------|
| Top-level peer-to-peer flows misclassified as cross-circle | Role-aware policy: top-level peers freely interconnect by default. |
| circle_id spoofing | circle_id signed by the parent's identity at spawn; verified at KNOCK. |
| Registry / KNOCK overhead | Single UUID field; KNOCK already has metadata exchange. |
| Breaks existing demos that depend on sub-agent↔sub-agent | Same-circle siblings ARE allowed. Only cross-circle is blocked. |

## Acceptance Criteria
- [ ] `circle_id` field in CRD, plumbed through reconciler, registry, and KNOCK.
- [ ] KNOCK denies cross-circle sub-agent traffic with a clear governance event.
- [ ] `discover` filters results per requester role.
- [ ] Sub-agent system prompt mentions trust circle; tests verify the constraint.
- [ ] Existing intra-circle pipelines (analyst→viz→writer demo) continue to work.
- [ ] Conformance test: spawn two parents, each with one sub; assert the two subs cannot KNOCK each other; assert the two parents can.

## Related
- Routing-bug fix that prompted this design: agent system-prompt revision in `runtimes/openclaw/src/core/agt-task-loop.ts:83` (in flight).
- AGT vendored patches: `vendor/agentmesh-sdk/README.md`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.