Design hook-based event systems for ADW observability. Use when implementing real-time event broadcasting, creating hook pipelines, or building agent activity monitoring.
Designs hook-based event systems for real-time agent activity monitoring and observability.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install google-ecosystem@melodic-softwareThis skill is limited to using the following tools:
Design hook-based event systems for capturing and broadcasting agent activities in AI Developer Workflows.
Implementation Note: Full hook event architecture requires Claude Agent SDK with custom tooling. This skill provides design patterns and specifications.
ADW systems capture these event types:
| Event Type | Icon | Source | Payload |
|---|---|---|---|
PreToolUse | 🪝 | Hook | Tool name, inputs, session |
PostToolUse | 🪝 | Hook | Tool name, outputs, duration |
TextBlock | 💬 | Agent | Response text, tokens |
ToolUseBlock | 🛠️ | Agent | Tool invocation record |
ThinkingBlock | 🧠 | Agent | Extended thinking content |
StepStart | ⚙️ | System | Step name, inputs |
StepEnd | ⚙️ | System | Step name, outputs, duration |
Create Pydantic models for events:
class ADWEvent(BaseModel):
type: str # Event type from table
adw_id: str # 8-char correlation ID
step: str # Current step name
timestamp: datetime
payload: dict # Type-specific data
summary: str | None # AI-generated summary
```text
### Step 2: Configure Hook Triggers
Set up Claude Code hooks:
```json
{
"hooks": {
"PreToolUse": [{
"matcher": ".*",
"command": "python hooks/pre_tool.py"
}],
"PostToolUse": [{
"matcher": ".*",
"command": "python hooks/post_tool.py"
}]
}
}
```text
### Step 3: Design Event Pipeline
```text
Agent Execution
│
├── PreToolUse ──► Hook Script ──┬── Log to DB
│ ├── Summarize (Haiku)
▼ └── Broadcast (WebSocket)
Tool Execution
│
├── PostToolUse ──► Hook Script ──┬── Log to DB
│ ├── Summarize (Haiku)
▼ └── Broadcast (WebSocket)
Continue...
```text
### Step 4: Implement Summarization
AI-generated event summaries using Haiku:
```python
async def summarize_event(event: ADWEvent) -> str:
prompt = f"""Summarize in 15 words or less:
Event: {event.type}
Tool: {event.payload.get('tool_name', 'N/A')}
Data: {str(event.payload)[:500]}
"""
return await claude.complete(prompt, model="haiku")
```text
### Step 5: Design Broadcast Pattern
Event distribution to clients:
```python
class EventBroadcaster:
def __init__(self, ws_manager, db_client):
self.ws = ws_manager
self.db = db_client
async def broadcast(self, event: ADWEvent):
# Log to database first
await self.db.log_event(event)
# Broadcast to WebSocket clients
await self.ws.broadcast(event.dict())
```text
## Hook Script Templates
### PreToolUse Hook
```python
#!/usr/bin/env python
import sys, json, asyncio
from adw_modules import broadcast, summarize
async def main():
data = json.load(sys.stdin)
event = {
"type": "PreToolUse",
"adw_id": data.get("adw_id"),
"step": data.get("step"),
"payload": {
"tool_name": data["tool_name"],
"tool_input": data["tool_input"]
}
}
event["summary"] = await summarize(event)
await broadcast(event)
if __name__ == "__main__":
asyncio.run(main())
```text
### PostToolUse Hook
```python
#!/usr/bin/env python
import sys, json, asyncio
from adw_modules import broadcast, summarize
async def main():
data = json.load(sys.stdin)
event = {
"type": "PostToolUse",
"adw_id": data.get("adw_id"),
"step": data.get("step"),
"payload": {
"tool_name": data["tool_name"],
"tool_output": data.get("tool_output", "")[:1000],
"duration_ms": data.get("duration_ms", 0)
}
}
event["summary"] = await summarize(event)
await broadcast(event)
if __name__ == "__main__":
asyncio.run(main())
```text
## Output Format
When designing hook event architecture:
```markdown
## Hook Event Architecture Design
### Event Types
| Type | Trigger | Payload Schema |
| --- | --- | --- |
| [type] | [when triggered] | [fields] |
### Hook Configuration
```json
[hooks.json configuration]
```text
### Event Pipeline
```text
[ASCII diagram of flow]
```text
### Summarization Strategy
[How Haiku generates summaries]
### Broadcasting Pattern
[WebSocket or other broadcast mechanism]
### Database Schema
```sql
[Event logging tables]
```text
### Implementation Checklist
- [ ] [Step 1]
- [ ] [Step 2]
...
```text
## Design Checklist
- [ ] Event types defined with payloads
- [ ] Hook configuration specified
- [ ] Event pipeline documented
- [ ] Summarization prompt designed
- [ ] Broadcast mechanism chosen
- [ ] Database schema defined
- [ ] Error handling considered
- [ ] Performance implications assessed
## Anti-Patterns
| Anti-Pattern | Problem | Solution |
| --- | --- | --- |
| Sync broadcasting | Blocks agent execution | Async dispatch |
| No correlation ID | Can't trace workflows | Use adw_id |
| Raw payload logging | Token waste | Truncate large data |
| Missing summaries | Hard to scan | Always summarize |
| No error handling | Silent failures | Log and recover |
## Cross-References
- @hook-event-patterns.md - Event type details
- @websocket-architecture.md - Broadcasting patterns
- @production-patterns.md - Database logging
- @adw-framework.md - ADW overview
## Version History
- **v1.0.0** (2026-01-01): Initial release (Lesson 14)
---
## Last Updated
**Date:** 2026-01-01
**Model:** claude-opus-4-5-20251101
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.