# Hooks Reference

> Complete reference of all supported ACS/AOS hooks with methods and use cases

- **Category**: guardrails-acs

- **Canonical URL**: https://designpattern.fyi/guardrails-acs/hooks-reference/

---

## Description
Complete reference of all supported ACS/AOS hooks with methods and use cases








## Additional Notes

# Appendix A — Full Supported Hooks Reference

| # | Hook | Fires when | AOS method | Typical Guardian Agent use |
|---|---|---|---|---|
| 1 | Agent Trigger | An external trigger (schedule, inbound message, webhook) activates the agent, before it starts reasoning | `steps/agentTrigger` | Block or rewrite spoofed/malicious triggers before the agent ever runs |
| 2 | Tool Call Request | The agent has decided to call a tool, before execution | `steps/toolCallRequest` | Deny high-risk calls or rewrite parameters |
| 3 | Tool Call Result | A tool call has completed, before the agent consumes the result | `steps/toolCallResult` | Strip sensitive data or block a poisoned/unexpected result |
| 4 | User Message | An inbound user prompt, before the agent processes it | `steps/message` (role=`user`) | Filter injection attempts, jailbreaks, or out-of-scope requests |
| 5 | Memory Context Retrieval | Prior memory is pulled into context, before attachment | `steps/memoryContextRetrieval` | Prevent stale or poisoned memory from re-entering context |
| 6 | Knowledge Retrieval | Data is pulled from a knowledge source (RAG, files), before reaching the LLM | `steps/knowledgeRetrieval` | Block or redact retrieved content that could indirectly inject the model |
| 7 | Memory Store | The agent is about to write to its memory store | `steps/memoryStore` | Prevent persistence of attacker-supplied instructions or sensitive data |
| 8 | Agent Response | The outbound response, before it reaches the user | `steps/message` (role=`agent`) | Redact, block, or rewrite the final output |
| 9 | MCP Outbound | The agent sends a message to a remote MCP server | `protocols/MCP` | Restrict outbound MCP traffic to an approved server list |
| 10 | MCP Inbound | The agent receives a message from a remote MCP server | `protocols/MCP` | Screen inbound MCP payloads before processing |
| 11–15 | A2A hooks (send/stream message, cancel task, get task, get/set notification config, resubscribe) | Task delegation, cancellation, and status exchange with peer agents | A2A protocol methods | Authenticate and authorize inter-agent task handoffs; contain a compromised peer agent |

---

## 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
```json
{
  "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