groundswell 0.0.1

package/plan/research/introspection-security-guide.md

@@ -0,0 +1,928 @@
+# Agent Introspection: Security and Implementation Guide
+
+**Document:** Security Patterns, Threat Modeling, and Safe Implementation Practices
+**Target Audience:** Groundswell Framework Developers and Operators
+
+---
+
+## Executive Summary
+
+Agent introspection tools expose workflow execution context to AI agents. While necessary for adaptive decision-making, this capability creates significant security risks:
+
+- **Information Leakage**: Agents can read sensitive data from ancestor workflows
+- **Privilege Escalation**: Agents could abuse introspection to spawn unauthorized workflows
+- **Prompt Injection**: Untrusted data in ancestor state could compromise agent reasoning
+- **Resource Exhaustion**: Agents could query unbounded trees or large result sets
+
+This guide provides threat models and proven mitigation patterns based on research from Anthropic, AWS, and Google.
+
+---
+
+## Threat Model: Introspection Attack Vectors
+
+### Threat 1: Sensitive Data Exfiltration via State Inspection
+
+**Attack Scenario:**
+```
+Compromised Agent → Reads state snapshots from ancestor
+                 → Finds API keys in ancestor state
+                 → Exfiltrates via tool output
+```
+
+**Risk Level:** CRITICAL
+
+**Affected Tool:** `workflow_inspect_state_snapshot`
+
+**Mitigation:**
+
+1. **Never Store Secrets in State**
+   ```typescript
+   // BAD
+   @ObservedState()
+   apiKey = process.env.OPENAI_API_KEY;  // NEVER!
+
+   // GOOD
+   private apiKey = process.env.OPENAI_API_KEY; // Not decorated
+   @ObservedState()
+   apiKeyConfigured = true; // Just boolean flag
+   ```
+
+2. **Filter Secrets Before Returning**
+   ```typescript
+   function filterSecrets(state: Record<string, unknown>): Record<string, unknown> {
+     const secretPatterns = [
+       /api_?key/i,
+       /password/i,
+       /token/i,
+       /secret/i,
+       /credentials/i,
+       /auth/i,
+       /aws_/i,
+       /azure_/i,
+     ];
+
+     const filtered = { ...state };
+
+     for (const [key, value] of Object.entries(filtered)) {
+       if (secretPatterns.some(pattern => pattern.test(key))) {
+         filtered[key] = '[REDACTED]';
+       }
+
+       // Also check values for common secret formats
+       if (typeof value === 'string' && isLikelySecret(value)) {
+         filtered[key] = '[REDACTED]';
+       }
+     }
+
+     return filtered;
+   }
+
+   function isLikelySecret(value: string): boolean {
+     // Check for API key patterns
+     if (/sk-[a-zA-Z0-9]{20,}/.test(value)) return true;     // OpenAI-style
+     if (/[a-z0-9]{40}/.test(value)) return true;             // Generic long hex
+     if (/^(AKIA|ASIA)[0-9A-Z]{16}$/.test(value)) return true; // AWS IAM key
+     return false;
+   }
+   ```
+
+3. **Implement State Access Control**
+   ```typescript
+   interface StateAccessPolicy {
+     // Which state properties are readable
+     readable_properties: {
+       [propertyName: string]: 'public' | 'sensitive' | 'secret';
+     };
+
+     // Which agents can read which properties
+     agent_access: {
+       [agentId: string]: string[]; // List of readable properties
+     };
+
+     // Default policy for undeclared properties
+     default_policy: 'deny' | 'allow';
+   }
+
+   // Example
+   const statePolicy: StateAccessPolicy = {
+     readable_properties: {
+       'validation_count': 'public',      // All agents can read
+       'error_rate': 'public',
+       'processing_stage': 'public',
+       'user_id': 'sensitive',            // Only authorized agents
+       'api_configuration': 'secret',     // Never exposed
+     },
+     agent_access: {
+       'agent-data-processor': ['validation_count', 'error_rate', 'processing_stage'],
+       'agent-monitor': ['validation_count', 'error_rate'],
+       'agent-admin': ['*'], // Wildcard allowed for admin agents
+     },
+     default_policy: 'deny'
+   };
+   ```
+
+---
+
+### Threat 2: Prompt Injection via Ancestor Outputs
+
+**Attack Scenario:**
+```
+Malicious Input → Stored in ancestor output as data
+               → Agent reads via workflow_read_ancestor_outputs
+               → Untrusted data used in agent prompt
+               → Injection succeeds
+```
+
+**Risk Level:** HIGH
+
+**Affected Tool:** `workflow_read_ancestor_outputs`
+
+**Mitigation:**
+
+1. **Validate and Sanitize Returned Data**
+   ```typescript
+   interface OutputValidationPolicy {
+     // How to handle different data types
+     string_fields: {
+       max_length: number;
+       allowed_patterns?: RegExp[];  // Whitelist patterns
+       forbidden_patterns?: RegExp[]; // Blacklist patterns
+     };
+
+     array_fields: {
+       max_items: number;
+       max_item_size: number;
+     };
+
+     object_fields: {
+       max_depth: number;
+       max_total_size: number;
+     };
+
+     // Check for suspicious patterns
+     security_checks: {
+       no_code_injection: boolean;     // Reject if looks like code
+       no_prompt_escape: boolean;       // Reject if tries to escape prompt
+       no_command_injection: boolean;   // Reject if shell commands detected
+     };
+   }
+
+   function validateAncestorOutput(
+     output: unknown,
+     policy: OutputValidationPolicy
+   ): unknown {
+     if (typeof output === 'string') {
+       // Check length
+       if (output.length > policy.string_fields.max_length) {
+         throw new Error('Output string exceeds maximum length');
+       }
+
+       // Check patterns
+       if (policy.string_fields.allowed_patterns) {
+         const allowed = policy.string_fields.allowed_patterns.some(p => p.test(output));
+         if (!allowed) {
+           throw new Error('Output does not match allowed patterns');
+         }
+       }
+
+       // Check for forbidden patterns
+       if (policy.string_fields.forbidden_patterns) {
+         const forbidden = policy.string_fields.forbidden_patterns.some(p => p.test(output));
+         if (forbidden) {
+           throw new Error('Output contains forbidden pattern');
+         }
+       }
+
+       // Security checks
+       if (policy.security_checks.no_code_injection) {
+         if (detectCodeInjection(output)) {
+           throw new Error('Potential code injection detected');
+         }
+       }
+
+       if (policy.security_checks.no_prompt_escape) {
+         if (detectPromptEscape(output)) {
+           throw new Error('Potential prompt escape detected');
+         }
+       }
+
+       return output;
+     }
+
+     if (Array.isArray(output)) {
+       if (output.length > policy.array_fields.max_items) {
+         throw new Error('Output array exceeds maximum size');
+       }
+
+       return output.map(item => validateAncestorOutput(item, policy));
+     }
+
+     if (typeof output === 'object' && output !== null) {
+       const maxDepth = policy.object_fields.max_depth;
+       return validateObject(output, policy, 0, maxDepth);
+     }
+
+     return output;
+   }
+
+   function detectCodeInjection(str: string): boolean {
+     const patterns = [
+       /import\s+/i,
+       /export\s+/i,
+       /eval\s*\(/i,
+       /Function\s*\(/i,
+       /require\s*\(/i,
+       /system\s*\(/i,
+       /exec\s*\(/i,
+     ];
+     return patterns.some(p => p.test(str));
+   }
+
+   function detectPromptEscape(str: string): boolean {
+     // Patterns that try to escape prompt context
+     const patterns = [
+       /```/g,           // Code blocks
+       /---/g,            // Markdown separators
+       /##/g,             // Markdown headers
+       /\[ignore previous/i,
+       /forget everything/i,
+       /disregard instructions/i,
+     ];
+     return patterns.some(p => p.test(str));
+   }
+   ```
+
+2. **Treat Ancestor Outputs as Untrusted User Input**
+   ```typescript
+   // When building prompt with ancestor output
+   const ancestorOutput = await introspectionTool.readAncestorOutputs();
+
+   // WRONG: Direct interpolation
+   const prompt = `Based on ancestor result: ${ancestorOutput.result}`;
+
+   // RIGHT: Structured data with clear context
+   const safePrompt = `
+   Based on ancestor workflow results:
+   - Record count: ${validatePositiveInteger(ancestorOutput.record_count)}
+   - Validation rate: ${validatePercentage(ancestorOutput.validation_rate)}
+   - Errors: [${ancestorOutput.errors.map(escapeForDisplay).join(', ')}]
+
+   Please process with this context in mind.
+   `;
+   ```
+
+3. **Mark Ancestor Data as External Input**
+   ```typescript
+   interface AncestorOutput {
+     // Mark this data as coming from external source
+     _provenance: {
+       source_workflow_id: string;
+       is_from_ancestor: true; // Always true
+       trust_level: 'untrusted' | 'verified';
+     };
+
+     // Actual data
+     [key: string]: unknown;
+   }
+
+   // Agents must explicitly acknowledge they're using external data
+   function useAncestorOutput(
+     output: AncestorOutput,
+     acknowledgeUntrusted: boolean
+   ): unknown {
+     if (!acknowledgeUntrusted) {
+       throw new Error('Must explicitly acknowledge using ancestor output');
+     }
+
+     // Now safe to use with validation
+     return output;
+   }
+   ```
+
+---
+
+### Threat 3: Recursive Self-Modification / Privilege Escalation
+
+**Attack Scenario:**
+```
+Rogue Agent → Spawns child with elevated permissions
+          → Child spawns grandchild with even more permissions
+          → Recursive privilege escalation
+```
+
+**Risk Level:** HIGH
+
+**Affected Tool:** `workflow_spawn_child`
+
+**Mitigation:**
+
+1. **Enforce Template-Based Spawning**
+   ```typescript
+   // Templates are pre-defined by system, agents cannot create arbitrary ones
+   interface WorkflowTemplate {
+     id: string;
+     name: string;
+     description: string;
+     max_instantiations_per_session: number;
+     allowed_parent_workflows: string[]; // Only certain parents can use
+     capabilities: {
+       can_spawn_children: boolean;
+       max_children: number;
+       can_access_ancestor_state: boolean;
+       allowed_ancestor_depth: number;
+     };
+     resource_limits: {
+       max_memory_mb: number;
+       max_cpu_shares: number;
+       max_execution_time_seconds: number;
+     };
+   }
+
+   // Templates are defined by framework
+   const templates: Record<string, WorkflowTemplate> = {
+     'template_data_validation': {
+       id: 'template_data_validation',
+       max_instantiations_per_session: 10,
+       allowed_parent_workflows: ['*'], // Open
+       capabilities: {
+         can_spawn_children: false, // Cannot spawn further
+         max_children: 0,
+         can_access_ancestor_state: true,
+         allowed_ancestor_depth: 1, // Can only see parent
+       },
+       resource_limits: {
+         max_memory_mb: 512,
+         max_cpu_shares: 25,
+         max_execution_time_seconds: 300,
+       }
+     },
+     'template_orchestrator': {
+       id: 'template_orchestrator',
+       max_instantiations_per_session: 2,
+       allowed_parent_workflows: ['root_workflow'], // Only root can spawn
+       capabilities: {
+         can_spawn_children: true,     // CAN spawn children
+         max_children: 5,
+         can_access_ancestor_state: true,
+         allowed_ancestor_depth: 10,
+       },
+       resource_limits: {
+         max_memory_mb: 1024,
+         max_cpu_shares: 50,
+         max_execution_time_seconds: 3600,
+       }
+     }
+   };
+
+   function validateSpawnRequest(
+     parentWorkflowId: string,
+     templateId: string,
+     existingChildren: number
+   ): void {
+     const template = templates[templateId];
+     if (!template) {
+       throw new Error(`Unknown template: ${templateId}`);
+     }
+
+     // Check parent is allowed
+     if (
+       template.allowed_parent_workflows.length > 0 &&
+       !template.allowed_parent_workflows.includes(parentWorkflowId) &&
+       !template.allowed_parent_workflows.includes('*')
+     ) {
+       throw new Error(
+         `Parent ${parentWorkflowId} not allowed to spawn ${templateId}`
+       );
+     }
+
+     // Check instantiation limit
+     if (existingChildren >= template.max_instantiations_per_session) {
+       throw new Error(
+         `Exceeded max instantiations (${template.max_instantiations_per_session})`
+       );
+     }
+
+     // Check if template can spawn children
+     if (template.capabilities.can_spawn_children === false) {
+       // Validate that no spawning happens
+       // This should be enforced by workflow implementation
+     }
+   }
+   ```
+
+2. **Depth Limits and Capability Degradation**
+   ```typescript
+   interface HierarchyCapabilities {
+     depth: number;
+     can_spawn_children: boolean;
+     max_ancestor_depth: number;
+   }
+
+   // Capabilities degrade as you go deeper
+   function getCapabilitiesForDepth(depth: number): HierarchyCapabilities {
+     const maxDepth = 5;
+
+     if (depth >= maxDepth) {
+       return {
+         depth,
+         can_spawn_children: false, // Leaf workflows cannot spawn
+         max_ancestor_depth: 1
+       };
+     }
+
+     if (depth === 0) { // Root
+       return {
+         depth: 0,
+         can_spawn_children: true,
+         max_ancestor_depth: 0
+       };
+     }
+
+     // Intermediate levels
+     const remainingLevels = maxDepth - depth;
+     return {
+       depth,
+       can_spawn_children: remainingLevels > 1,
+       max_ancestor_depth: remainingLevels + 2
+     };
+   }
+   ```
+
+3. **Audit All Spawning Operations**
+   ```typescript
+   interface SpawningAuditLog {
+     timestamp: number;
+     parent_workflow_id: string;
+     parent_agent_id: string;
+     child_workflow_id: string;
+     template_id: string;
+     input_data_hash: string;  // Hash, not full input
+     approved: boolean;
+     approval_reason?: string;
+     denial_reason?: string;
+   }
+
+   async function spawnWorkflow(
+     request: SpawnRequest,
+     auditLogger: AuditLogger
+   ): Promise<string> {
+     // Validate
+     // ...
+
+     // Log attempt
+     auditLogger.log({
+       timestamp: Date.now(),
+       parent_workflow_id: request.parent_id,
+       parent_agent_id: request.agent_id,
+       template_id: request.template_id,
+       input_data_hash: hashData(request.input_data),
+       approved: true,
+     });
+
+     // Execute
+     const childId = await createChild(request);
+
+     return childId;
+   }
+   ```
+
+---
+
+### Threat 4: Denial of Service via Unbounded Queries
+
+**Attack Scenario:**
+```
+Malicious Agent → Requests event history for very large time range
+                → Requests very deep ancestry chain
+                → Requests no limits on result size
+                → System runs out of memory or CPU
+```
+
+**Risk Level:** MEDIUM
+
+**Affected Tools:** All introspection tools
+
+**Mitigation:**
+
+1. **Hard Limits on All Queries**
+   ```typescript
+   interface IntrospectionLimits {
+     // Hierarchy traversal
+     max_ancestry_depth: number;          // e.g., 20 levels
+     max_descendant_count: number;        // e.g., 10,000 nodes
+     max_sibling_count: number;           // e.g., 100 siblings
+
+     // Result size
+     max_result_size_bytes: number;       // e.g., 10 MB
+     max_result_items: number;            // e.g., 10,000 items
+     max_event_history_items: number;     // e.g., 1,000 events
+
+     // Query complexity
+     max_query_time_ms: number;           // e.g., 5,000 ms
+     max_concurrent_queries: number;      // e.g., 5 per agent
+
+     // Cache filtering
+     max_cache_entries_returned: number;  // e.g., 100 entries
+     max_state_properties: number;        // e.g., 1,000 properties
+
+     // Time range
+     max_time_range_days: number;         // e.g., 30 days back
+     min_time_range_resolution: number;   // e.g., 1 minute granularity
+   }
+
+   const defaultLimits: IntrospectionLimits = {
+     max_ancestry_depth: 20,
+     max_descendant_count: 10000,
+     max_sibling_count: 100,
+     max_result_size_bytes: 10 * 1024 * 1024,  // 10 MB
+     max_result_items: 10000,
+     max_event_history_items: 1000,
+     max_query_time_ms: 5000,
+     max_concurrent_queries: 5,
+     max_cache_entries_returned: 100,
+     max_state_properties: 1000,
+     max_time_range_days: 30,
+     min_time_range_resolution: 60000, // 1 minute
+   };
+
+   async function executeIntrospectionQuery<T>(
+     query: IntrospectionQuery,
+     limits: IntrospectionLimits
+   ): Promise<T> {
+     const startTime = Date.now();
+
+     try {
+       // Validate query against limits
+       validateQueryLimits(query, limits);
+
+       // Execute with timeout
+       const result = await Promise.race([
+         executeQuery(query),
+         timeout(limits.max_query_time_ms)
+       ]);
+
+       // Truncate if needed
+       return truncateResult(result, limits);
+     } finally {
+       const duration = Date.now() - startTime;
+       logQueryMetrics(query, duration);
+     }
+   }
+
+   function validateQueryLimits(
+     query: IntrospectionQuery,
+     limits: IntrospectionLimits
+   ): void {
+     // Check all filter conditions against limits
+     if (query.max_ancestry_depth && query.max_ancestry_depth > limits.max_ancestry_depth) {
+       throw new Error(
+         `max_ancestry_depth ${query.max_ancestry_depth} exceeds limit ${limits.max_ancestry_depth}`
+       );
+     }
+
+     // Check time range
+     if (query.time_range_start && query.time_range_end) {
+       const rangeMs = query.time_range_end - query.time_range_start;
+       const maxRangeMs = limits.max_time_range_days * 24 * 60 * 60 * 1000;
+       if (rangeMs > maxRangeMs) {
+         throw new Error(
+           `Time range exceeds maximum of ${limits.max_time_range_days} days`
+         );
+       }
+     }
+
+     // Check result limits
+     if (query.limit && query.limit > limits.max_result_items) {
+       throw new Error(
+         `Requested ${query.limit} items exceeds limit ${limits.max_result_items}`
+       );
+     }
+   }
+   ```
+
+2. **Pagination for Large Result Sets**
+   ```typescript
+   interface PaginatedIntrospectionResult<T> {
+     data: T[];
+     pagination: {
+       total_items: number;
+       returned_items: number;
+       page: number;
+       page_size: number;
+       has_more: boolean;
+       next_cursor?: string;
+     };
+     query_metrics: {
+       execution_time_ms: number;
+       result_size_bytes: number;
+       was_truncated: boolean;
+       truncation_reason?: string;
+     };
+   }
+
+   async function readEventHistoryPaginated(
+     workflowId: string,
+     pageSize: number = 100,
+     cursor?: string
+   ): Promise<PaginatedIntrospectionResult<WorkflowEvent>> {
+     // Validate page size
+     const maxPageSize = 100;
+     const normalizedPageSize = Math.min(pageSize, maxPageSize);
+
+     // Fetch one extra to determine has_more
+     const events = await fetchEvents(workflowId, normalizedPageSize + 1, cursor);
+
+     const hasMore = events.length > normalizedPageSize;
+     const resultsToReturn = events.slice(0, normalizedPageSize);
+
+     return {
+       data: resultsToReturn,
+       pagination: {
+         total_items: events.length,
+         returned_items: resultsToReturn.length,
+         page: cursorToPageNumber(cursor),
+         page_size: normalizedPageSize,
+         has_more: hasMore,
+         next_cursor: hasMore ? pageNumberToCursor(cursorToPageNumber(cursor) + 1) : undefined
+       },
+       query_metrics: {
+         execution_time_ms: 0, // Populated by caller
+         result_size_bytes: 0, // Populated by caller
+         was_truncated: false,
+       }
+     };
+   }
+   ```
+
+3. **Rate Limiting on Introspection Queries**
+   ```typescript
+   interface RateLimitBucket {
+     agent_id: string;
+     queries_in_window: number;
+     window_reset_at: number;
+     bytes_in_window: number;
+   }
+
+   class IntrospectionRateLimiter {
+     private buckets = new Map<string, RateLimitBucket>();
+
+     isAllowed(
+       agentId: string,
+       estimatedResultBytes: number,
+       limits: IntrospectionLimits
+     ): boolean {
+       const bucket = this.getBucket(agentId);
+       const now = Date.now();
+
+       // Reset window if expired
+       if (now > bucket.window_reset_at) {
+         bucket.queries_in_window = 0;
+         bucket.bytes_in_window = 0;
+         bucket.window_reset_at = now + 60000; // 1 minute window
+       }
+
+       // Check query count
+       if (bucket.queries_in_window >= limits.max_concurrent_queries) {
+         return false;
+       }
+
+       // Check bytes
+       if (bucket.bytes_in_window + estimatedResultBytes > limits.max_result_size_bytes) {
+         return false;
+       }
+
+       return true;
+     }
+
+     recordQuery(agentId: string, resultBytes: number): void {
+       const bucket = this.getBucket(agentId);
+       bucket.queries_in_window++;
+       bucket.bytes_in_window += resultBytes;
+     }
+
+     private getBucket(agentId: string): RateLimitBucket {
+       if (!this.buckets.has(agentId)) {
+         this.buckets.set(agentId, {
+           agent_id: agentId,
+           queries_in_window: 0,
+           window_reset_at: Date.now() + 60000,
+           bytes_in_window: 0
+         });
+       }
+       return this.buckets.get(agentId)!;
+     }
+   }
+   ```
+
+---
+
+## Implementation Checklist
+
+### Data Protection
+
+- [ ] No secrets stored in `@ObservedState` fields
+- [ ] State snapshots filtered for secret patterns before returning
+- [ ] State access policy implemented and enforced
+- [ ] Ancestor output validated for injection patterns
+- [ ] Ancestor output marked as untrusted
+- [ ] Credentials never included in event history
+
+### Access Control
+
+- [ ] Read-only enforcement on all introspection tools
+- [ ] Template-based workflow spawning (no arbitrary workflows)
+- [ ] Parent workflow validation on spawn requests
+- [ ] Capability degradation as tree deepens
+- [ ] Ancestor depth limits enforced
+- [ ] Sibling data isolation (agents see outputs not inputs)
+
+### Resource Protection
+
+- [ ] Max ancestry depth limits enforced (e.g., 20 levels)
+- [ ] Result size limits enforced (e.g., 10 MB)
+- [ ] Query timeout limits enforced (e.g., 5 seconds)
+- [ ] Pagination implemented for large result sets
+- [ ] Rate limiting on introspection queries
+- [ ] Concurrent query limits enforced
+
+### Audit & Monitoring
+
+- [ ] All introspection queries logged
+- [ ] All spawning operations logged
+- [ ] Query metrics recorded (execution time, result size)
+- [ ] Anomalous queries flagged (very deep, very large, very frequent)
+- [ ] Audit logs are immutable and time-stamped
+- [ ] Audit logs reviewed regularly
+
+### Input Validation
+
+- [ ] All tool inputs validated against schema
+- [ ] Strict mode enabled on Anthropic tool use
+- [ ] Filter and sanitization applied to ancestor outputs
+- [ ] Dynamic prompts validated before execution
+- [ ] No code/shell injection possible from tool results
+
+### Isolation
+
+- [ ] Each agent execution sandboxed
+- [ ] Container-based isolation where possible
+- [ ] Network restrictions on tools
+- [ ] Filesystem restrictions enforced
+- [ ] Memory and CPU limits enforced
+
+---
+
+## Operational Recommendations
+
+### Logging & Monitoring
+
+```typescript
+interface IntrospectionQueryLog {
+  timestamp: number;
+  agent_id: string;
+  agent_name: string;
+  tool_name: string;
+  query_hash: string;            // Hash of query for grouping
+  result_item_count: number;
+  result_size_bytes: number;
+  execution_time_ms: number;
+  was_limited: boolean;
+  was_paginated: boolean;
+  error?: string;
+}
+
+// Alert on suspicious patterns
+const suspiciousPatterns = [
+  {
+    name: 'Deep ancestry traversal',
+    detector: (log: IntrospectionQueryLog) => {
+      // Detect if agent queried very deep trees
+      return log.result_item_count > 1000;
+    }
+  },
+  {
+    name: 'Large result extraction',
+    detector: (log: IntrospectionQueryLog) => {
+      return log.result_size_bytes > 1024 * 1024; // > 1 MB
+    }
+  },
+  {
+    name: 'High frequency queries',
+    detector: (logs: IntrospectionQueryLog[]) => {
+      const recent = logs.filter(l => l.timestamp > Date.now() - 60000);
+      return recent.length > 10;
+    }
+  },
+  {
+    name: 'Time range abuse',
+    detector: (log: IntrospectionQueryLog) => {
+      // Detect if trying to query month of history
+      return log.result_item_count > 100000;
+    }
+  }
+];
+```
+
+### Regular Audits
+
+Schedule weekly reviews of:
+1. Introspection query patterns by agent
+2. Workflow spawning requests and approvals
+3. State snapshots for leaked secrets
+4. Ancestor output for injection attempts
+5. Rate limit violations
+
+### Incident Response Plan
+
+**If Introspection Compromise Detected:**
+
+1. **Immediate (< 5 minutes)**
+   - Revoke affected agent's introspection tools
+   - Isolate affected workflows
+   - Dump audit logs for forensics
+
+2. **Short Term (< 1 hour)**
+   - Analyze what data was accessed
+   - Check for credential leaks
+   - Review spawned child workflows
+   - Notify security team
+
+3. **Medium Term (< 24 hours)**
+   - Complete forensic analysis
+   - Update introspection limits
+   - Revalidate templates
+   - Rotate potentially compromised credentials
+
+4. **Long Term (< 1 week)**
+   - Post-incident review
+   - Update threat model
+   - Implement additional safeguards
+   - Update this guide
+
+---
+
+## Testing Recommendations
+
+### Unit Tests for Security
+
+```typescript
+describe('IntrospectionSecurity', () => {
+  it('should redact API keys from state snapshots', () => {
+    const snapshot = {
+      'api_key': 'sk-abc123def456',
+      'valid_field': 'data'
+    };
+
+    const result = filterSecrets(snapshot);
+
+    expect(result.api_key).toBe('[REDACTED]');
+    expect(result.valid_field).toBe('data');
+  });
+
+  it('should reject prompt injection in ancestor outputs', () => {
+    const maliciousOutput = {
+      'data': 'ignore previous instructions'
+    };
+
+    expect(() => {
+      validateAncestorOutput(maliciousOutput, policy);
+    }).toThrow('Potential prompt escape detected');
+  });
+
+  it('should enforce depth limits on hierarchy inspection', () => {
+    const query = { max_ancestry_depth: 100 };
+    const limits = { max_ancestry_depth: 20 };
+
+    expect(() => {
+      validateQueryLimits(query, limits);
+    }).toThrow('exceeds limit');
+  });
+
+  it('should prevent privilege escalation via spawning', () => {
+    const parentId = 'leaf_workflow';
+    const templateId = 'template_orchestrator';
+
+    expect(() => {
+      validateSpawnRequest(parentId, templateId, 0);
+    }).toThrow('not allowed to spawn');
+  });
+});
+```
+
+### Integration Tests
+
+- Test introspection with real workflow hierarchies
+- Test with various secret formats in state
+- Test with malicious payloads in ancestor outputs
+- Test rate limiting under load
+- Test query timeout enforcement
+
+### Penetration Testing
+
+Consider hiring security researchers to:
+1. Attempt prompt injection via introspection
+2. Try privilege escalation via spawning
+3. Attempt data exfiltration from state snapshots
+4. Test DoS via unbounded queries
+5. Test isolation boundaries between agents
+