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

HOOKS KNOWLEDGE BASE

OVERVIEW

22+ lifecycle hooks intercepting/modifying agent behavior. Context injection, error recovery, output control, notifications.

STRUCTURE

hooks/
├── anthropic-context-window-limit-recovery/  # Auto-compact at token limit (556 lines)
├── auto-slash-command/         # Detect and execute /command patterns
├── auto-update-checker/        # Version notifications, startup toast
├── background-notification/    # OS notify on task complete
├── claude-code-hooks/          # settings.json PreToolUse/PostToolUse/etc (408 lines)
├── comment-checker/            # Prevent excessive AI comments
│   ├── filters/                # docstring, directive, bdd, shebang
│   └── output/                 # XML builder, formatter
├── compaction-context-injector/ # Preserve context during compaction
├── directory-agents-injector/  # Auto-inject AGENTS.md
├── directory-readme-injector/  # Auto-inject README.md
├── edit-error-recovery/        # Recover from edit failures
├── empty-message-sanitizer/    # Sanitize empty messages
├── interactive-bash-session/   # Tmux session management
├── keyword-detector/           # ultrawork/search keyword activation
├── non-interactive-env/        # CI/headless handling
├── preemptive-compaction/      # Pre-emptive at 85% usage
├── prometheus-md-only/         # Restrict prometheus to read-only
├── ralph-loop/                 # Self-referential dev loop
├── rules-injector/             # Conditional rules from .claude/rules/
├── session-recovery/           # Recover from errors (432 lines)
├── sisyphus-orchestrator/      # Main orchestration hook (660 lines)
├── start-work/                 # Initialize Sisyphus work session
├── task-resume-info/           # Track task resume state
├── think-mode/                 # Auto-detect thinking triggers
├── thinking-block-validator/   # Validate thinking block format
├── agent-usage-reminder/       # Remind to use specialists
├── context-window-monitor.ts   # Monitor usage (standalone)
├── session-notification.ts     # OS notify on idle
├── todo-continuation-enforcer.ts # Force TODO completion (413 lines)
└── tool-output-truncator.ts    # Truncate verbose outputs

HOOK EVENTS

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

HOW TO ADD

1. Create src/hooks/my-hook/
2. Files: index.ts (createMyHook), constants.ts, types.ts (optional)
3. Return: { PreToolUse?, PostToolUse?, UserPromptSubmit?, Stop?, onSummarize? }
4. Export from src/hooks/index.ts

PATTERNS

• Storage: JSON file for persistent state across sessions
• Once-per-session: Track injected paths in Set
• Message injection: Return { messages: [...] }
• Blocking: Return { blocked: true, message: "..." } from PreToolUse

ANTI-PATTERNS

• Heavy computation in PreToolUse (slows every tool call)
• Blocking without actionable message
• Duplicate injection (track what's injected)
• Missing try/catch (don't crash session)