Appendix A — Full Supported Hooks Reference

Verdict Object Structure

Every hook returns a verdict object carrying the same response shape across all hooks, which is what makes a single Guardian Agent implementation able to enforce policy consistently across the entire agent lifecycle.

Verdict Fields

{
  "verdict": "allow | deny | modify",
  "reason": "Human-readable explanation of the decision",
  "modifiedRequest": {
    // Replacement content (only for modify verdict)
  }
}

Verdict Types

Allow

• Effect: The action proceeds unchanged
• Use when: The action passes all policy checks
• Required fields: verdict: "allow", reason

Deny

• Effect: The action is blocked entirely
• Use when: The action violates policy and cannot be safely modified
• Required fields: verdict: "deny", reason
• Agent behavior: Agent should handle the denial gracefully (e.g., return safe refusal template)

Modify

• Effect: The action proceeds, but with Guardian-Agent-supplied replacement content
• Use when: The action can be made safe by modifying parameters or content
• Required fields: verdict: "modify", reason, modifiedRequest
• Agent behavior: Agent should use the modified content instead of the original

Hook Categories

Lifecycle Hooks (1, 8)

These hooks cover the beginning and end of the agent lifecycle:

• Agent Trigger (#1) — Controls when and how an agent can be activated
• Agent Response (#8) — Controls what the agent is allowed to output

Common use cases:

• Prevent unauthorized agent activation
• Filter malicious outbound content
• Enforce response formatting and content policies

Tool Hooks (2, 3)

These hooks control tool usage, which is often the highest-risk agent capability:

• Tool Call Request (#2) — Controls what tools the agent can call and with what parameters
• Tool Call Result (#3) — Controls what tool results the agent can consume

Common use cases:

• Prevent unauthorized tool usage
• Parameter validation and sanitization
• Result filtering and redaction
• Cost control and rate limiting

Memory Hooks (5, 7)

These hooks control agent memory, a common attack vector:

• Memory Context Retrieval (#5) — Controls what memory the agent can access
• Memory Store (#7) — Controls what the agent can write to memory

Common use cases:

• Prevent memory poisoning attacks
• Control access to sensitive memory
• Prevent persistence of malicious instructions
• Implement memory retention policies

Knowledge Hooks (6)

These hooks control knowledge retrieval, another potential attack vector:

• Knowledge Retrieval (#6) — Controls what knowledge sources the agent can access and what content it can retrieve

Common use cases:

• Prevent access to unauthorized knowledge sources
• Filter retrieved content for injection attacks
• Implement knowledge source governance
• Control RAG system access

Protocol Hooks (9, 10, 11-15)

These hooks control protocol-level interactions:

• MCP Outbound (#9) — Controls connections to Model Context Protocol servers
• MCP Inbound (#10) — Controls inbound MCP traffic
• A2A hooks (#11-15) — Control inter-agent communication

Common use cases:

• Implement allow-lists for MCP servers
• Authenticate and authorize A2A communication
• Prevent supply chain attacks through protocol connections
• Control inter-agent task delegation

Hook Implementation Priority

Based on risk and implementation complexity, consider this priority order:

High Priority (Implement First)

1. User Message (#4) — Basic input filtering, quick wins
2. Agent Response (#8) — Basic output filtering, quick wins
3. Tool Call Request (#2) — High-impact control point

Medium Priority (Implement Second)

4. Tool Call Result (#3) — Important for data protection
5. Memory Store (#7) — Important for preventing memory poisoning
6. Memory Context Retrieval (#5) — Important for memory security

Lower Priority (Implement Later)

7. Knowledge Retrieval (#6) — Important if using RAG systems
8. Agent Trigger (#1) — Important for automated/triggered agents
9. MCP Outbound (#9) — Important if using MCP servers
10. MCP Inbound (#10) — Important if using MCP servers
11. A2A hooks (#11-15) — Important for multi-agent systems

Hook Context Requirements

Each hook requires specific context to be effective:

Minimal Context

All hooks should provide:

• Session ID — For traceability and audit
• Agent ID — For agent identification
• Timestamp — For temporal analysis
• Hook ID — For hook identification

Hook-Specific Context

Agent Trigger (#1)

• Trigger type (schedule, webhook, message)
• Trigger source
• Trigger parameters

Tool Call Request (#2)

• Tool name and identifier
• Tool parameters
• Agent reasoning for the call
• Request timestamp

Tool Call Result (#3)

• Tool name and identifier
• Tool result data
• Execution metadata (duration, status)
• Result timestamp

User Message (#4)

• Message content
• User identifier
• Message metadata (channel, format)
• Input timestamp

Memory Context Retrieval (#5)

• Memory keys being retrieved
• Retrieval context
• Memory store identifier

Knowledge Retrieval (#6)

• Knowledge source identifier
• Query parameters
• Retrieved content preview
• Knowledge source metadata

Memory Store (#7)

• Memory key being written
• Content being written
• Write context and metadata
• Memory store identifier

Agent Response (#8)

• Response content
• Intended recipient
• Response metadata (format, channel)
• Output timestamp

MCP Hooks (9, 10)

• MCP server identifier
• Message content
• Protocol version
• Connection metadata

A2A Hooks (11-15)

• Source agent identifier
• Target agent identifier
• Message or task content
• Protocol metadata

Error Handling

Hook Evaluation Failures

When Guardian Agent evaluation fails:

• Default to deny — Fail-safe behavior for security-critical systems
• Log the failure — Record the error for debugging and analysis
• Alert operators — Notify security teams of evaluation failures
• Implement fallback — Consider fallback policies for critical systems

Verdict Processing Failures

When an agent fails to handle a verdict:

• Log the failure — Record the error for analysis
• Implement retry logic — Retry with exponential backoff
• Circuit breaker — Disable the agent if failures persist
• Alert operators — Notify teams of persistent issues

Performance Considerations

Latency Budget

Hook evaluation must be fast to avoid impacting agent responsiveness:

• Target latency: < 100ms for most hooks
• Critical hooks: < 50ms for high-frequency hooks (user message, tool call)
• Complex evaluations: Consider async processing for non-critical hooks

Caching Strategies

Improve performance through intelligent caching:

• Policy caching — Cache compiled policies to avoid re-parsing
• Context caching — Cache frequently accessed context data
• Result caching — Cache evaluation results for identical inputs
• Distributed caching — Use Redis or similar for multi-instance deployments

Throughput Optimization

Handle high-volume agent interactions:

• Connection pooling — Reuse connections to Guardian Agent
• Batch processing — Process multiple hooks in parallel where possible
• Load balancing — Distribute load across multiple Guardian Agent instances
• Rate limiting — Implement backpressure handling for overload situations

Key Takeaways

1. 15 standard hooks — Cover the entire agent lifecycle from trigger to response
2. Consistent verdict structure — Same response shape across all hooks enables unified Guardian Agent
3. Three verdict types — Allow, deny, and modify provide flexible control
4. Hook categories — Lifecycle, tool, memory, knowledge, and protocol hooks
5. Prioritized implementation — Start with high-impact, low-complexity hooks
6. Context requirements — Each hook needs specific context for effective evaluation
7. Performance matters — Hook evaluation must be fast to avoid impacting agent responsiveness

Next Steps

• Risk Control Mapping — condensed quick-reference for ASI to ACS mapping