oh-my-opencode/src/hooks/AGENTS.md

HOOKS KNOWLEDGE BASE

OVERVIEW

Lifecycle hooks that intercept/modify agent behavior. Inject context, enforce rules, recover from errors, notify on events.

STRUCTURE

hooks/
├── agent-usage-reminder/       # Remind to use specialized agents
├── anthropic-auto-compact/     # Auto-compact Claude at token limit
├── auto-update-checker/        # Version update notifications
├── background-notification/    # OS notify on background task complete
├── claude-code-hooks/          # Claude Code settings.json integration
├── comment-checker/            # Prevent excessive AI comments
│   ├── filters/                # Filtering rules (docstring, directive, bdd, etc.)
│   └── output/                 # Output formatting
├── compaction-context-injector/ # Inject context during compaction
├── directory-agents-injector/  # Auto-inject AGENTS.md files
├── directory-readme-injector/  # Auto-inject README.md files
├── empty-message-sanitizer/    # Sanitize empty messages
├── interactive-bash-session/   # Tmux session management
├── keyword-detector/           # Detect ultrawork/search keywords
├── non-interactive-env/        # CI/headless environment handling
├── preemptive-compaction/      # Pre-emptive session compaction
├── rules-injector/             # Conditional rules from .claude/rules/
├── session-recovery/           # Recover from session errors
├── think-mode/                 # Auto-detect thinking triggers
├── context-window-monitor.ts   # Monitor context usage (standalone)
├── empty-task-response-detector.ts
├── session-notification.ts     # OS notify on idle (standalone)
├── todo-continuation-enforcer.ts # Force TODO completion (standalone)
└── tool-output-truncator.ts    # Truncate verbose outputs (standalone)

HOOK CATEGORIES

Category	Hooks	Purpose
Context Injection	directory-agents-injector, directory-readme-injector, rules-injector, compaction-context-injector	Auto-inject relevant context
Session Management	session-recovery, anthropic-auto-compact, preemptive-compaction, empty-message-sanitizer	Handle session lifecycle
Output Control	comment-checker, tool-output-truncator	Control agent output quality
Notifications	session-notification, background-notification, auto-update-checker	OS/user notifications
Behavior Enforcement	todo-continuation-enforcer, keyword-detector, think-mode, agent-usage-reminder	Enforce agent behavior
Environment	non-interactive-env, interactive-bash-session, context-window-monitor	Adapt to runtime environment
Compatibility	claude-code-hooks	Claude Code settings.json support

HOW TO ADD A HOOK

1. Create directory: src/hooks/my-hook/
2. Create files:
   • index.ts: Export createMyHook(input: PluginInput)
   • constants.ts: Hook name constant
   • types.ts: TypeScript interfaces (optional)
   • storage.ts: Persistent state (optional)
3. Return event handlers: { PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }
4. Export from src/hooks/index.ts
5. Register in main plugin

HOOK EVENTS

Event	Timing	Can Block	Use Case
PreToolUse	Before tool exec	Yes	Validate, modify input
PostToolUse	After tool exec	No	Add context, warnings
UserPromptSubmit	On user prompt	Yes	Inject messages, block
Stop	Session idle	No	Inject follow-ups
onSummarize	During compaction	No	Preserve critical context

COMMON PATTERNS

• Storage: Use storage.ts with JSON file for persistent state across sessions
• Once-per-session: Track injected paths in Set to avoid duplicate injection
• Message injection: Return { messages: [...] } from event handlers
• Blocking: Return { blocked: true, message: "reason" } from PreToolUse

ANTI-PATTERNS (HOOKS)

• Heavy computation in PreToolUse: Slows every tool call
• Blocking without clear reason: Always provide actionable message
• Duplicate injection: Track what's already injected per session
• Ignoring errors: Always try/catch, log failures, don't crash session