Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat: ADR-078 Agent LLM Federation Plugin

Reuvenf3ea2d778116
diff --git a/v3/implementation/adrs/ADR-078-agent-llm-federation-plugin.md b/v3/implementation/adrs/ADR-078-agent-llm-federation-plugin.md
new file mode 100644
index 0000000000..7bd3a40823
--- /dev/null
+++ b/v3/implementation/adrs/ADR-078-agent-llm-federation-plugin.md
@@ -0,0 +1,643 @@
+# 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.
+
+## 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
+ 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.
+
+### 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
+
+| Decision | Rationale |
+|----------|-----------|
+| **Plugin, not core** | Federation is opt-in; many installations are single-node. Ships as `@claude-flow/plugin-agent-federation`. |
+| **mTLS, not API keys** | API keys are shared secrets -- one compromise exposes the federation. mTLS provides mutual authentication with per-node identity. |
+| **PII stripping before encryption** | Ensures PII never exists in the encrypted payload -- defense in depth against key compromise. |
+| **Byzantine consensus for untrusted peers** | Remote nodes may be compromised. BFT tolerates f < n/3 faulty nodes using existing `hive-mind` infrastructure. |
+| **Dual AI Defence gates** | Both outbound and inbound scanning. Outbound prevents accidental data leakage. Inbound prevents adversarial prompt injection from remote agents. |
+| **Claims-based authorization** | Every cross-boundary operation requires a claim. Extends `@claude-flow/claims` with federation-specific claim types. |
+
+---
+
+## 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:
+
+| Trust Level | Allowed Operations |
+|-------------|-------------------|
+| 0 | Discovery only |
+| 1 | Read federation status, ping |
+| 2 | Send/receive task messages, query memory (redacted) |
+| 3 | Share agent context, collaborative task execution |
+| 4 | Full memory sharing, direct agent spawning on remote node |
+
+### 2.2 Cryptographic Primitives
+
+All primitives reuse existing `@claude-flow/security`:
+
+| Primitive | Implementation | Source |
+|-----------|---------------|--------|
+| Key generation | ed25519 via `crypto.generateKeyPairSync` | New in federation |
+| Token signing | HMAC-SHA256 | `TokenGenerator` |
+| Password hashing | bcrypt (12 rounds) | `PasswordHasher` |
+| Session tokens | `crypto.randomBytes(32)` | `TokenGenerator.generate()` |
+| Nonce generation | `crypto.randomBytes(16)` | `TokenGenerator` |
+| Timing-safe compare | `crypto.timingSafeEqual` | `TokenGenerator.verify()` |
+
+### 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:
+
+```typescript
+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:
+
+| Action | Authority Level | Irreversibility |
+|--------|----------------|-----------------|
+| Accept federation peer | human | costly-reversible |
+| Share memory namespace | human | reversible |
+| Allow remote agent spawn | institutional | costly-reversible |
+| Grant `federation:admin` | institutional | costly-reversible |
+| Delete federation data | human | irreversible |
+
+---
+
+## 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:
+
+| Pattern | Type | Example |
+|---------|------|---------|
+| Phone numbers | `phone` | `+1-555-123-4567`, `(555) 123-4567` |
+| Names (NER-style) | `name` | Context-aware proper noun detection |
+| IP addresses | `ip_address` | `192.168.1.1`, `2001:db8::1` |
+| Physical addresses | `address` | Street address patterns |
+| JWT tokens | `jwt` | `eyJ...` base64 encoded tokens |
+| AWS keys | `aws_key` | `AKIA...` prefix detection |
+| Private keys | `private_key` | `-----BEGIN.*PRIVATE KEY-----` |
+| Database URLs | `database_url` | `postgres://user:pass@host/db` |
+
+### 3.3 Policy Configuration
+
+```typescript
+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:
+
+| PII Type | Trust 0-1 | Trust 2 | Trust 3 | Trust 4 |
+|----------|-----------|---------|---------|---------|
+| SSN | block | block | block | block |
+| credit_card | block | block | block | block |
+| api_key | block | block | block | redact |
+| password | block | block | block | block |
+| email | block | redact | hash | pass |
+| phone | block | redact | hash | pass |
+| name | block | redact | redact | pass |
+| ip_address | block | hash | hash | pass |
+
+---
+
+## 4. Logging Architecture
+
+### 4.1 Log Event Schema
+
+```typescript
+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
+
+```typescript
+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
+
+| Mode | Requirements |
+|------|-------------|
+| **HIPAA** | All PII events logged with full audit trail. Log retention 6 years. No PII in logs (log the redaction action, not the data). PHI detection patterns enabled. |
+| **SOC2** | Access control events logged. Change management trail. Availability monitoring (session health). |
+| **GDPR** | Data processing records. Right to erasure support. Consent tracking for data sharing. Data residency enforcement. |
+| **None** | Standard operational logging. Configurable retention. |
+
+### 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
+
+```typescript
+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
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `pre-federation-send` | Before outbound message | PII pipeline + AI defence scan + signing |
+| `post-federation-receive` | After inbound message | HMAC verify + AI defence scan + PII verify + claims check |
+| `federation-audit` | Every audit event | Log shipping, compliance, neural learning |
+| `federation-trust-change` | Trust level change | Notify, log, potentially escalate to human |
+| `federation-session-start` | Session created | Initialize session metrics |
+| `federation-session-end` | Session ended | Export session metrics, train patterns |
+
+### 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
+
+| Component | Existing File | Integration |
+|-----------|--------------|-------------|
+| Plugin interface | `shared/src/plugin-interface.ts` | Implements `ClaudeFlowPlugin` |
+| Plugin loader | `shared/src/plugin-loader.ts` | Loaded via `PluginLoader.loadPlugin()` |
+| AI Defence | `aidefence/src/index.ts` | Extends for PII stripping |
+| Threat detection | `aidefence/src/domain/services/threat-detection-service.ts` | Extends `PII_PATTERNS` |
+| Security module | `security/src/index.ts` | Uses `TokenGenerator`, `PasswordHasher`, `PathValidator` |
+| Federation hub | `swarm/src/federation-hub.ts` | Extends for cross-installation messaging |
+| Claims types | `claims/src/domain/types.ts` | Adds `FederationClaimType` values |
+| Authority gate | `guidance/src/authority.ts` | Trust level changes require human authority |
+| Plugin discovery | `cli/src/plugins/store/discovery.ts` | IPFS registry entry |
+
+---
+
+## 9. Risks and Mitigations
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| mTLS complexity across platforms | Medium | High | Use Node.js native `tls` module; self-signed cert generation in `federation init` |
+| PII false positives blocking data | Medium | Medium | Configurable sensitivity; allowlisting; feedback via `aidefence.learnFromDetection()` |
+| Network latency degrading coordination | Medium | Medium | Async message queuing; local cache; configurable timeout |
+| Byzantine node poisoning consensus | Low | High | BFT with n/3 threshold; trust score decay on suspicious behavior |
+| Key compromise | Low | Critical | Key rotation support; revocation via federation broadcast |
+
+## 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