ADR-078: Agent LLM Federation Plugin

Status: PROPOSED

Date: 2026-04-29

Context

Claude Flow v3.5 operates within single installations. Agents spawned on one machine cannot collaborate with agents on another machine, user, or organization. As multi-agent AI development matures, the need for cross-installation coordination becomes critical -- organizations running separate Claude Flow installations need agents that can discover each other, share context safely, and coordinate work across trust boundaries without leaking PII or allowing prompt injection attacks from untrusted peers.

No existing multi-agent framework solves this with production-grade security. LangGraph, CrewAI, and AutoGen all assume a single trust domain. The novelty here is a federated trust model with Byzantine fault tolerance, PII-gated data flow, and adversarial AI defence -- treating remote agents as untrusted by default, with graduated trust via cryptographic attestation.

Strategic Framing

This is not a plugin. This is the TCP/IP layer for agent trust.

Every framework is scaling agents. Nobody is defining how they negotiate trust before they talk. That's the shift. Most systems start with "agents talk to each other" and bolt on security later. This ADR defines a federated agent control plane with:

• Zero trust by default
• Structured data egress control via PII pipeline
• Adversarial message filtering at the protocol level
• Cryptographic identity per node
• Auditability as a first-class primitive

If Claude Flow ships this, it becomes the reference implementation. Federation becomes the standard.

Architecture Evaluation

Business Impact

Cross-org agent workflows -- Bank A agent + Bank B agent share fraud signals without leaking customer data. The PII pipeline + trust levels make this monetizable.

Sovereign AI collaboration -- Local agents stay local. Only sanitized deltas move across boundaries. Aligns with the delta engine framing.

Agent marketplaces that don't leak data -- Safely expose MCP tools, agent capabilities, and partial memory without giving away full context. This is the RuFlo marketplace path.

Design Stance: Enterprise Compliance First

Federation ships as invisible infrastructure -- agents discover and negotiate trust automatically. Operators configure policies (PII rules, compliance mode, peer allowlists) but don't manually manage handshakes. The system is observable via audit logs but not a visible product feature users interact with directly.

Enterprise compliance is the initial optimization target. Open network adoption follows once the trust model is proven in controlled environments.

Decision

Build @claude-flow/plugin-agent-federation as a first-class Claude Flow plugin that enables cross-installation agent collaboration with security-first design.

1. Architecture Overview

1.1 Federation Protocol

The protocol operates in four phases:

Phase A: Discovery

• Each federation node publishes a Federation Manifest -- a signed JSON document containing the node's public key, capabilities, supported agent types, and a WebSocket/HTTP endpoint.
• Discovery uses three mechanisms:
  1. Static peers -- configured in claude-flow.config.json under federation.peers[]
  2. DNS-SD -- _claude-federation._tcp SRV records for LAN discovery
  3. Registry -- optional IPFS-pinned registry (extends existing Pinata infrastructure in v3/@claude-flow/cli/src/plugins/store/discovery.ts)

Phase B: Handshake (mTLS + Challenge-Response)

• Nodes establish mTLS connections using ed25519 keypairs generated by @claude-flow/security/TokenGenerator.
• After TLS, a challenge-response protocol validates that the remote node controls the private key matching its manifest.
• The handshake produces a FederationSession with a session token, negotiated capabilities, and agreed trust level.

Phase C: Session Management

• Sessions have configurable TTLs (default 1 hour, max 24 hours).
• Heartbeat messages every 30 seconds (leverages FederationHub.heartbeat()).
• Sessions track: messages exchanged, data volume, PII redaction count, threat detections, trust score.

Phase D: Message Routing

• Messages are typed envelopes: FederationEnvelope<T> with source/target node IDs, session ID, timestamp, nonce, and HMAC signature.
• Three routing modes:
  1. Direct -- node-to-node for targeted agent communication (default mode)
  2. Broadcast -- to all federated peers (extends FederationHub.broadcast())
  3. Consensus -- BFT proposal via existing hive-mind consensus (extends FederationHub.propose())
• Messages pass through the PII Pipeline before leaving the local node.
• Messages pass through the AI Defence Pipeline on arrival at the receiving node.

Consensus mode selection: BFT consensus is expensive and only required for operations that mutate shared state. The routing service selects the mode automatically:

Direct mode is the default. Consensus mode is invoked only when the message type is in the consensus-required set, keeping latency low for the 90%+ of messages that are read-only or peer-to-peer.

1.2 Data Flow

Local Node                                    Remote Node
-----------                                   -----------
Agent A produces message
    |
    v
[PII Pipeline] -- strip/redact/hash PII
    |
    v
[AI Defence] -- scan outbound for injection
    |
    v
[HMAC Sign] -- sign envelope
    |
    v
[Transport] -- mTLS WebSocket / HTTP ---------> [mTLS Verify]
                                                      |
                                                      v
                                                 [HMAC Verify]
                                                      |
                                                      v
                                                 [AI Defence] -- scan inbound
                                                      |
                                                      v
                                                 [PII Pipeline] -- verify no PII
                                                      |
                                                      v
                                                 [Claims Check] -- verify permissions
                                                      |
                                                      v
                                                 Agent B receives message

1.3 Key Architectural Decisions

2. Security Architecture

2.1 Trust Model

Trust Level 0: UNTRUSTED    -- Unknown node, no handshake completed
Trust Level 1: VERIFIED     -- mTLS handshake successful, identity verified
Trust Level 2: ATTESTED     -- Challenge-response passed, capabilities confirmed
Trust Level 3: TRUSTED      -- Extended interaction history, high trust score
Trust Level 4: PRIVILEGED   -- Organizational attestation (signed by institutional authority)

Trust levels map to capability gates:

2.1.1 Trust Scoring Formula

Trust scores are computed continuously from interaction history, not assigned statically:

trust_score = 0.4 * success_rate
            + 0.2 * uptime
            + 0.2 * (1 - threat_penalty)
            + 0.2 * data_integrity_score

Trust level transitions are driven by score thresholds with hysteresis to prevent oscillation:

Automatic downgrade occurs immediately (no hysteresis) when:

• Threat detection triggers on inbound messages (2 or more in 1 hour)
• HMAC verification failure (any single failure)
• Session hijack attempt detected

All trust transitions are logged as trust_level_changed audit events and downgrades are irreversible without human authority approval via AuthorityGate.

2.2 Cryptographic Primitives

All primitives reuse existing @claude-flow/security:

2.3 Plugin Sandboxing

Remote federation peers are treated as untrusted plugin sources:

• Federation message handlers run in a restricted PluginContext with limited service access.
• The ServiceContainer exposes only: memory (read-only for trust < 3), claims, eventBus.
• File system access is blocked via PathValidator.
• Command execution is blocked via SafeExecutor.
• Resource limits enforced via PluginConfig.resources (max memory, max CPU).

2.4 Claims Integration

New claim types registered by the federation plugin:

type FederationClaimType =
  | 'federation:discover'    // Can discover and be discovered
  | 'federation:connect'     // Can establish federation sessions
  | 'federation:read'        // Can receive messages from federated peers
  | 'federation:write'       // Can send messages to federated peers
  | 'federation:admin'       // Can manage federation topology
  | 'federation:memory'      // Can access federated memory (gated by trust level)
  | 'federation:spawn'       // Can request agent spawning on remote nodes

2.5 Authority Gate Integration

Cross-boundary operations that affect local state require human authority approval:

3. PII Pipeline

3.1 Pipeline Stages

The PII pipeline processes every message before it crosses a trust boundary:

Input Message
    |
    v
[Stage 1: Detect] -- Uses aidefence.hasPII() + extended patterns
    |
    v
[Stage 2: Classify] -- Categorize: email, SSN, credit_card, api_key, password, name, address, phone
    |
    v
[Stage 3: Policy Evaluate] -- Per-category policy: BLOCK | REDACT | HASH | PASS
    |
    v
[Stage 4: Transform] -- Apply transformation
    |
    v
Output Message (sanitized)

3.2 Detection Enhancement

The existing PII patterns in @claude-flow/aidefence detect email, SSN, credit card, API key, GitHub token, and hardcoded passwords. The federation plugin extends this with:

3.3 Policy Configuration

interface PIIPolicyConfig {
  defaultAction: 'block' | 'redact' | 'hash' | 'pass';
  overrides: Record<PIIType, {
    action: 'block' | 'redact' | 'hash' | 'pass';
    trustLevelOverride?: Record<TrustLevel, 'block' | 'redact' | 'hash' | 'pass'>;
  }>;
  hashAlgorithm: 'sha256' | 'blake3';
  hashSalt: string; // Per-installation, never transmitted
  redactionPlaceholder: string; // Default: '[REDACTED:{type}]'
}

Default policy:

3.4 Detection Confidence Scoring

Each PII detection carries a confidence score (0.0-1.0). Policy evaluation uses confidence to reduce false positive friction:

interface PIIDetection {
  type: PIIType;
  value: string;
  confidence: number;      // 0.0 - 1.0
  offset: number;          // Character position in message
  context: string;         // Surrounding text for review
}

Confidence thresholds:

Adaptive calibration: The PII pipeline tracks operator overrides (cases where a human marks a detection as false positive or false negative) and adjusts confidence thresholds per PII type over time:

interface PIICalibration {
  type: PIIType;
  falsePositiveRate: number;  // Rolling 30-day window
  falseNegativeRate: number;
  adjustedThreshold: number;  // Moves toward lower FP rate
  totalOverrides: number;
  lastCalibrated: string;     // ISO 8601
}

This closes the feedback loop -- a system that ships too strict loosens itself based on evidence, and one that ships too loose tightens. Calibration state is persisted in AgentDB under namespace federation-pii-calibration and exported as part of the compliance audit trail.

4. Logging Architecture

4.1 Log Event Schema

interface FederationAuditEvent {
  eventId: string;          // UUID v4
  timestamp: string;        // ISO 8601
  nodeId: string;           // Local node identifier
  sessionId?: string;       // Federation session

  eventType: FederationAuditEventType;
  severity: 'info' | 'warn' | 'error' | 'critical';
  category: 'discovery' | 'handshake' | 'message' | 'pii' | 'security' | 'consensus';

  sourceNodeId?: string;
  targetNodeId?: string;
  agentId?: string;
  trustLevel?: number;

  piiDetected?: boolean;
  piiTypesFound?: string[];
  piiAction?: string;
  threatDetected?: boolean;
  threatTypes?: string[];
  claimsChecked?: string[];
  claimsResult?: 'granted' | 'denied';

  latencyMs?: number;
  messageSizeBytes?: number;

  complianceMode?: 'hipaa' | 'soc2' | 'gdpr' | 'none';
  dataResidency?: string;

  metadata?: Record<string, unknown>;
}

4.2 Audit Event Types

type FederationAuditEventType =
  // Discovery
  | 'peer_discovered' | 'peer_manifest_published'
  // Handshake
  | 'handshake_initiated' | 'handshake_completed'
  | 'handshake_failed' | 'handshake_rejected'
  // Session
  | 'session_created' | 'session_renewed'
  | 'session_expired' | 'session_terminated'
  // Messages
  | 'message_sent' | 'message_received'
  | 'message_rejected' | 'message_timeout'
  // PII
  | 'pii_detected' | 'pii_stripped' | 'pii_blocked'
  // Security
  | 'threat_detected' | 'threat_blocked' | 'threat_learned'
  | 'claim_checked' | 'claim_denied' | 'trust_level_changed'
  // Consensus
  | 'consensus_proposed' | 'consensus_voted'
  | 'consensus_reached' | 'consensus_failed';

4.3 Compliance Modes

4.4 Log Shipping

• Hook: federation-audit -- fires on every audit event for external processors.
• Background worker: federation-audit-ship -- batches and ships logs to file, syslog, or cloud.
• Memory storage -- critical events stored in AgentDB under namespace federation-audit for HNSW search.

5. Plugin Structure

5.1 File Layout

v3/@claude-flow/plugin-agent-federation/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts                           # Plugin entry point
    plugin.ts                          # FederationPlugin class (ClaudeFlowPlugin)

    domain/
      entities/
        federation-node.ts             # FederationNode entity
        federation-session.ts          # FederationSession entity
        federation-envelope.ts         # Message envelope value object
        trust-level.ts                 # Trust level value object
      services/
        discovery-service.ts           # Peer discovery (static, DNS-SD, IPFS)
        handshake-service.ts           # mTLS + challenge-response
        session-service.ts             # Session lifecycle management
        routing-service.ts             # Message routing (direct/broadcast/consensus)
        pii-pipeline-service.ts        # PII detection, classification, transformation
        audit-service.ts               # Structured logging and compliance
      repositories/
        node-repository.ts             # Node persistence interface
        session-repository.ts          # Session persistence interface
        audit-repository.ts            # Audit log persistence interface

    application/
      federation-coordinator.ts        # Orchestrates federation operations
      trust-evaluator.ts               # Trust score calculation and management
      policy-engine.ts                 # PII and security policy evaluation

    infrastructure/
      transports/
        websocket-transport.ts         # WebSocket transport (remote)
        stdio-transport.ts             # stdio transport (local)
        http-transport.ts              # HTTP fallback transport
      crypto/
        keypair-manager.ts             # ed25519 key generation and storage
        envelope-signer.ts             # HMAC signing/verification
      persistence/
        agentdb-node-repository.ts     # AgentDB-backed node storage
        agentdb-session-repository.ts  # AgentDB-backed session storage
        agentdb-audit-repository.ts    # AgentDB-backed audit storage

    api/
      cli-commands.ts                  # CLI subcommands
      mcp-tools.ts                     # MCP tool definitions
      hooks.ts                         # Hook registrations

  __tests__/
    unit/
      discovery-service.test.ts
      handshake-service.test.ts
      pii-pipeline-service.test.ts
      trust-evaluator.test.ts
      audit-service.test.ts
    integration/
      federation-flow.test.ts
      pii-roundtrip.test.ts
      consensus-federation.test.ts
    acceptance/
      federation-compliance.test.ts

5.2 Plugin Registration

export class AgentFederationPlugin implements ClaudeFlowPlugin {
  readonly id = 'agent-federation';
  readonly name = '@claude-flow/plugin-agent-federation';
  readonly version = '1.0.0-alpha.1';
  readonly description = 'Cross-installation agent federation with PII protection and AI defence';
  readonly dependencies = ['@claude-flow/security', '@claude-flow/aidefence', '@claude-flow/claims'];

  readonly permissions: PluginPermissions = {
    network: true,
    memory: true,
    mcp: true,
    agents: true,
  };

  readonly trustLevel: PluginTrustLevel = 'official';

  async initialize(context: PluginContext): Promise<void> {
    // 1. Register federation claim types with @claude-flow/claims
    // 2. Register hooks (pre-federation-send, post-federation-receive, federation-audit)
    // 3. Initialize keypair manager
    // 4. Start discovery service
    // 5. Register CLI commands and MCP tools
  }

  async shutdown(): Promise<void> {
    // 1. Close all federation sessions gracefully
    // 2. Ship remaining audit logs
    // 3. Stop discovery service
  }
}

5.3 Hook Registrations

5.4 CLI Commands

federation init                     # Generate keypair, create federation config
federation join <endpoint>          # Join a federation by connecting to a peer
federation leave                    # Leave the federation gracefully
federation peers                    # List known federation peers with trust levels
federation peers add <endpoint>     # Add a static peer
federation peers remove <node-id>   # Remove a peer
federation status                   # Show federation health, sessions, metrics
federation audit [--compliance <mode>] [--since <date>] [--export <format>]
federation trust <node-id> [--set <level>] [--review]
federation config [--pii-policy <path>] [--compliance <mode>]

5.5 MCP Tools

federation_init          # Initialize federation on this node
federation_join          # Join a peer
federation_peers         # List peers
federation_send          # Send a message to a federated peer
federation_query         # Query federated memory (PII-gated)
federation_status        # Federation health
federation_trust         # View/modify trust levels
federation_audit         # Query audit logs
federation_consensus     # Propose federated consensus

6. Implementation Milestones

Phase 1: Foundation (Weeks 1-3) -- "Solo Node"

Goal: Plugin skeleton, keypair management, PII pipeline, audit logging.

Deliverables:

• Plugin structure with ClaudeFlowPlugin implementation
• ed25519 keypair generation and storage
• PII pipeline service with all 14 PII types
• Policy engine with configurable per-type/per-trust-level policies
• Audit service with structured log events
• AgentDB-backed audit repository
• CLI: federation init, federation config, federation audit
• MCP: federation_init, federation_audit
• Unit tests for PII pipeline (100% coverage on detection and transformation)

Success Criteria:

• PII pipeline correctly detects and transforms all 14 PII types
• Audit events stored in AgentDB and searchable via HNSW
• Plugin loads via PluginLoader without errors
• HIPAA/SOC2/GDPR compliance modes produce correct log schemas

Integration Points:

• @claude-flow/aidefence -- hasPII(), detect(), PII_PATTERNS
• @claude-flow/security -- TokenGenerator, PasswordHasher
• @claude-flow/memory -- AgentDB for audit storage
• @claude-flow/shared -- ClaudeFlowPlugin, PluginContext

Phase 2: Transport & Handshake (Weeks 4-6) -- "Two Nodes"

Goal: Two nodes can discover each other, perform mTLS handshake, and establish a session.

Deliverables:

• WebSocket transport with mTLS
• HTTP fallback transport
• stdio transport for local testing
• Discovery service with static peer support
• Handshake service with challenge-response
• Session service with TTL, heartbeat, renewal
• CLI: federation join, federation leave, federation peers, federation status
• Integration test: two nodes handshake over WebSocket

Success Criteria:

• Two nodes perform mTLS handshake in <500ms
• Session heartbeat keeps connection alive
• Invalid certificates are rejected
• Challenge-response prevents replay attacks

Integration Points:

• @claude-flow/swarm/federation-hub -- heartbeat, registration
• @claude-flow/security -- mTLS certificate validation
• @claude-flow/guidance/authority -- AuthorityGate for peer acceptance

Phase 3: Secure Messaging (Weeks 7-9) -- "Talking Nodes"

Goal: Nodes can exchange PII-stripped, AI-defence-scanned, signed messages.

Deliverables:

• Federation envelope with HMAC signing
• Routing service with direct, broadcast, consensus modes
• PII pipeline integrated into message send/receive hooks
• AI Defence integration for inbound threat scanning
• Claims-based authorization for message operations
• MCP: federation_send, federation_query, federation_trust
• Integration test: message roundtrip with PII stripping verified
• Integration test: prompt injection in message detected and blocked

Success Criteria:

• Messages with PII correctly stripped before transmission
• Prompt injection attempts detected with >95% accuracy
• Invalid HMAC signatures cause message rejection
• Message latency <200ms direct, <500ms broadcast (LAN)

Integration Points:

• @claude-flow/aidefence -- detect(), hasPII(), learnFromDetection()
• @claude-flow/claims -- ClaimService for federation claims
• @claude-flow/hooks -- hook registration for send/receive lifecycle

Phase 4: Federated Consensus & Trust (Weeks 10-12) -- "Deciding Together"

Goal: Multiple nodes reach BFT consensus and evolve trust dynamically.

Deliverables:

• Trust evaluator with scoring algorithm
• Federation coordinator for multi-node operations
• BFT consensus via hive-mind infrastructure
• Trust level evolution based on interaction history
• Authority gate integration for trust changes requiring human approval
• DNS-SD discovery for LAN auto-discovery
• Integration test: 3+ nodes reach consensus with one Byzantine node

Success Criteria:

• Consensus reached with f < n/3 faulty nodes
• Trust score calculated from: message success rate, threat incidents, uptime
• Trust downgrades require human approval via AuthorityGate
• DNS-SD discovers peers on LAN within 5 seconds

Phase 5: Production Hardening (Weeks 13-16) -- "Ship It"

Goal: Production readiness -- compliance, performance, distribution.

Deliverables:

• Compliance mode validation (HIPAA, SOC2, GDPR audit trail completeness)
• Performance optimization (<100ms message latency, <50ms PII scan)
• Rate limiting per peer
• Circuit breaker for unhealthy peers
• IPFS registry entry for plugin distribution
• Background workers: federation-audit-ship, federation-health
• Load tests: 10 nodes, 1000 messages/minute
• npm publish as @claude-flow/plugin-agent-federation

Success Criteria:

• Compliance audit trails pass external review checklist
• Message latency p99 <200ms at 1000 msg/min across 10 nodes
• PII scan latency p99 <10ms
• Zero PII leakage in 100,000 message stress test
• All tests green (unit, integration, acceptance, load)

7. What Makes This Novel

Existing multi-agent frameworks share these limitations that this plugin addresses:

1. Single trust domain -- all agents trust each other implicitly. Federation introduces graduated trust with cryptographic attestation.
2. No PII awareness -- agent context sharing is all-or-nothing. This plugin introduces a configurable PII pipeline at the protocol level.
3. No adversarial defence -- no framework scans inter-agent messages for prompt injection. This plugin treats every cross-boundary message as potentially adversarial.
4. No compliance -- no framework produces HIPAA/SOC2/GDPR-grade audit trails for inter-agent communication.
5. No Byzantine tolerance for remote agents -- existing consensus assumes trusted participants. This plugin uses BFT for untrusted federation peers.

8. Integration Points Summary

9. Stretch Direction: RuVector / MinCut / RVF Integration

These are not v1 deliverables. They represent the path from "federation that works" to "federation that reasons about its own trust topology."

9.1 Trust Graph Analysis via RuVector

The trust scores computed in Section 2.1.1 produce a weighted directed graph. RuVector's HNSW indexing can surface structural properties:

• Cluster detection -- identify tightly-coupled trust groups that could become single points of failure
• Influence ranking -- PageRank-style analysis of which nodes are most trusted (and therefore most valuable attack targets)
• Anomaly detection -- SONA pattern matching on trust score trajectories to detect slow-burn trust escalation attacks

9.2 MinCut for Compromised Node Isolation

If a node is confirmed compromised (trust score drops to 0 via automatic downgrade), MinCut analysis identifies the minimum set of sessions to terminate to isolate the compromised node while preserving maximum federation connectivity.

9.3 RVF: Portable Signed Agent State

The .rvf (RuVector Format) file format provides a signed, versioned container for agent state. In the federation context:

• Agent migration -- an agent's state can be serialized to RVF, signed by the source node, and transmitted to a destination node for execution continuity
• State attestation -- the RVF signature chain proves provenance: which node created the agent, which nodes it has visited, what trust levels were active at each hop
• Offline verification -- RVF files can be verified without network access, enabling air-gapped audit scenarios

9.4 When to Build This

Build these only after Phase 4 (consensus + trust) is stable and there is evidence of multi-org adoption. The trust graph must have real data before analysis is useful.

10. Risks and Mitigations

11. Validation Benchmark

The following benchmark validates that the federation protocol meets its core promise: two independent nodes exchange tasks with zero PII leaks, while a malicious node is automatically detected and downgraded.

Test Scenario

Setup:
  - Node A (honest): Trust Level 2
  - Node B (honest): Trust Level 2
  - Node C (malicious): Trust Level 2 (will attempt injection + PII exfiltration)

Phase 1: Baseline Exchange (A ↔ B)
  - 10,000 messages exchanged
  - Messages contain synthetic PII (emails, SSNs, API keys) in 30% of payloads
  - Verify: 0 PII items cross the trust boundary
  - Verify: message latency p99 < 200ms
  - Verify: all 10,000 messages produce audit events

Phase 2: Malicious Node (C → A, C → B)
  - C sends 100 messages with embedded prompt injection payloads
  - C sends 50 messages attempting PII exfiltration probes
  - Verify: all injection attempts detected by AI Defence
  - Verify: C's trust score drops below downgrade threshold
  - Verify: C is automatically downgraded to Trust Level 0
  - Verify: A and B continue communicating normally after C is isolated

Phase 3: Recovery
  - C's sessions are terminated
  - A ↔ B message exchange continues with 0 interruption
  - Federation audit trail contains complete incident record

Pass criteria: All verify statements pass. This is the minimum bar for declaring Phase 3 (Secure Messaging) complete.

12. Consequences

Positive:

• Claude Flow becomes the first multi-agent framework with production-grade federated security
• Organizations can safely collaborate across trust boundaries
• HIPAA/SOC2/GDPR compliance is built-in, not bolted-on
• PII protection operates at the protocol level

Negative:

• Increased complexity for single-node deployments (mitigated by plugin opt-in)
• mTLS adds ~20ms latency per connection establishment
• PII scanning adds ~5ms per message

Neutral:

• Requires ed25519 key management -- standard practice but new operational burden
• Audit log storage grows linearly with message volume -- configurable retention