feat: @claude-flow/plugin-agent-federation — Cross-installation agent federation with zero-trust security

[ruvnet]

Agent LLM Federation Plugin

What is this?

@claude-flow/plugin-agent-federation is a new first-class plugin that enables cross-installation agent collaboration with production-grade security. Think of it as the TCP/IP layer for agent trust — it defines how independent Claude Flow installations discover each other, negotiate trust, and safely exchange tasks and context without leaking PII or allowing prompt injection attacks.

Why does this matter?

Every multi-agent framework is scaling agents. Nobody is defining how they negotiate trust before they talk. Current systems (LangGraph, CrewAI, AutoGen) assume a single trust domain. This plugin is the first to provide:

• Zero-trust by default — remote agents are untrusted until cryptographically verified
• PII-gated data flow — configurable per-type, per-trust-level PII stripping with confidence scoring
• Adversarial message filtering — dual AI Defence gates (outbound + inbound) scan every cross-boundary message
• Byzantine fault tolerance — consensus for untrusted peers using existing hive-mind infrastructure
• Compliance built-in — HIPAA, SOC2, GDPR audit trails as first-class primitives

Architecture

4-Phase Federation Protocol:

1. Discovery — Nodes publish signed manifests; peers found via static config, DNS-SD, or IPFS registry
2. Handshake — mTLS + ed25519 challenge-response establishes mutual identity
3. Session — TTL-based sessions with heartbeat, metrics tracking, and trust scoring
4. Routing — HMAC-signed envelopes with three modes: Direct (default), Broadcast, and BFT Consensus

5-Tier Trust Model:

Level	Name	Capabilities
0	UNTRUSTED	Discovery only
1	VERIFIED	Read federation status, ping
2	ATTESTED	Send/receive tasks, query memory (redacted)
3	TRUSTED	Share agent context, collaborative execution
4	PRIVILEGED	Full memory sharing, remote agent spawning

Trust Scoring Formula:

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

PII Pipeline:

• 14 detection types (email, SSN, credit card, API keys, JWT, AWS keys, phone, names, IPs, addresses, passwords, private keys, database URLs, GitHub tokens)
• Confidence scoring (0.0-1.0) with adaptive calibration from operator overrides
• Per-type, per-trust-level policies: BLOCK | REDACT | HASH | PASS

Quick Start (Coming Soon)

# Install the federation plugin
npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation

# Initialize federation on this node
npx claude-flow@latest federation init

# Join a federation peer
npx claude-flow@latest federation join wss://peer-node.example.com:8443

# Check federation status
npx claude-flow@latest federation status

# View audit log
npx claude-flow@latest federation audit --compliance hipaa --since 2026-01-01

MCP Tools

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

CLI Commands

federation init                     # Generate keypair, create config
federation join <endpoint>          # Connect to a peer
federation leave                    # Leave gracefully
federation peers                    # List peers with trust levels
federation peers add <endpoint>     # Add static peer
federation peers remove <node-id>   # Remove a peer
federation status                   # Health, sessions, metrics
federation audit                    # Query audit logs
federation trust <node-id>          # View/modify trust
federation config                   # Configure PII policies, compliance mode

Implementation Status

• ADR-078: Architecture design (PR feat: ADR-078 Agent LLM Federation Plugin #1668)
• Plugin scaffold and types
• Phase 1: PII pipeline + audit logging (Weeks 1-3)
• Phase 2: Transport + mTLS handshake (Weeks 4-6)
• Phase 3: Secure messaging (Weeks 7-9)
• Phase 4: BFT consensus + trust evolution (Weeks 10-12)
• Phase 5: Production hardening (Weeks 13-16)

Security Features

Feature	Implementation
Identity	ed25519 keypairs per node
Transport	mTLS WebSocket/HTTP
Messages	HMAC-SHA256 signed envelopes
PII Protection	14-type detection with configurable policies
Threat Detection	Dual AI Defence gates (outbound + inbound)
Authorization	Claims-based with 7 federation claim types
Consensus	BFT for state mutations (f < n/3 tolerance)
Audit	Structured logs with HIPAA/SOC2/GDPR modes

Links

• ADR-078: PR feat: ADR-078 Agent LLM Federation Plugin #1668
• Plugin source: v3/@claude-flow/plugin-agent-federation/
• Architecture evaluation: Security 9/10, Compliance 9/10, Differentiation 10/10

Business Impact

• Cross-org workflows — Bank A + Bank B agents share fraud signals without leaking customer data
• Sovereign AI — Local agents stay local; only sanitized deltas cross boundaries
• Agent marketplaces — Safely expose MCP tools and capabilities without full context leakage

---

Labels: enhancement, security, plugin, federation