AGENTS.md

1# src/hooks/ -- ~54 Lifecycle Hooks Across 62 Dirs
2 
3**Generated:** 2026-07-17
4 
5## OVERVIEW
6 
754 base registered hooks on default config (61 with team-mode; `monitor-status-injector` adds 1 more with `monitor.enabled` → 62 max), composed from 54 `index.ts` hook dirs (52 wired; `task-reminder/` and `ralph-loop/` unwired) plus 5 standalone hook `.ts` files at the `src/hooks/` top level (bash-file-read-guard, empty-task-response-detector, preemptive-compaction, session-notification, tool-output-truncator). The 62 directories = 54 with `index.ts` + 8 without (`shared/`, `team-session-events/`, `hashline-edit-diff-enhancer/` unwired, and 5 `zauc-mocks-*`/`zauc-sync-mocks`). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) -> HookFunction` factory pattern.
8 
9**Unwired WIP (do not modify casually):** `task-reminder/` (has `index.ts` + `createTaskReminderHook` but NOT exported from barrel, NOT imported by any composer), `ralph-loop/` (exported from barrel but NOT imported by any composer; retained for migration, superseded by `goal/`), and `hashline-edit-diff-enhancer/` (has only `hook.ts`, NOT registered). Treat as orphaned until wired in.
10 
11## TIER COMPOSITION
12 
13| Tier | Composer | Base | With team-mode | Where |
14|------|----------|------|----------------|-------|
15| **Session** | `create-session-hooks.ts` | 24 | 24 | OpenCode session lifecycle + chat.params + chat.message |
16| **Tool Guard** | `create-tool-guard-hooks.ts` | 17 | 18 | Pre/post tool execution (+1: `team-tool-gating`) |
17| **Transform** | `create-transform-hooks.ts` | 4 | 6 | `experimental.chat.messages.transform` (+2: `team-mode-status-injector`, `team-mailbox-injector`; `monitor-status-injector` is a further +1 gated on `monitor.enabled`, not team-mode) |
18| **Continuation** | `create-continuation-hooks.ts` | 7 | 7 | Boulder/atlas/compaction/notification |
19| **Skill** | `create-skill-hooks.ts` | 2 | 2 | Skill awareness (categorySkillReminder, autoSlashCommand) |
20| **Direct event handlers** | `src/plugin/event.ts` | 0 | +4 | `team-session-events/` sub-files: `team-idle-wake-hint`, `team-lead-orphan-handler`, `team-member-error-handler`, `team-member-status-handler` |
21 
22Total exposed hooks: **54 base, 61 with team-mode, 62 with team-mode + monitor** (counts the 4 team-session-events handlers individually).
23 
24Hook name allowlist for `disabled_hooks`: all configurable hook names enumerated in [`src/config/schema/hooks.ts`](../config/schema/hooks.ts) `HookNameSchema`. Team-session-event sub-hooks are not individually listed in the schema -- they activate together with `team_mode.enabled`.
25 
26### Tier 1: Session Hooks (24)
27 
28| Hook | Event | Purpose |
29|------|-------|---------|
30| `preemptiveCompaction` | session.idle | Trigger compaction before limit |
31| `sessionNotification` | session.idle | OS notifications on completion |
32| `thinkMode` | chat.params | Model variant switching for extended thinking |
33| `anthropicContextWindowLimitRecovery` | session.error | Multi-strategy context recovery (truncation, compaction, dedup) |
34| `autoUpdateChecker` | session.created | Check npm for plugin updates |
35| `codegraphBootstrap` | session.created | Bootstrap CodeGraph indexing for the project (pairs with the built-in `codegraph` MCP) |
36| `astGrepSgProvision` | session.created | Provision the ast-grep `sg` binary for the bundled skill |
37| `agentUsageReminder` | chat.message | Remind about available agents |
38| `nonInteractiveEnv` | chat.message | Adjust behavior for `run` command |
39| `interactiveBashSession` | tool.execute | Tmux session lifecycle for interactive_bash tool |
40| `goal` | event | Persistent per-session objective; idle continuation + usage accounting. Replaces `ralphLoop` (see [`goal/AGENTS.md`](goal/AGENTS.md)) |
41| `editErrorRecovery` | tool.execute.after | Retry failed file edits |
42| `delegateTaskRetry` | tool.execute.after | Retry failed task delegations |
43| `startWork` | chat.message | `/start-work` command handler |
44| `prometheusMdOnly` | tool.execute.before | Enforce .md-only writes for Prometheus |
45| `sisyphusJuniorNotepad` | chat.message | Notepad injection for subagents |
46| `questionLabelTruncator` | tool.execute.before | Truncate long Question tool labels |
47| `taskResumeInfo` | chat.message | Inject task context on resume |
48| `modelFallback` | chat.params | Provider-level proactive model fallback |
49| `noSisyphusGpt` | chat.message | Block Sisyphus from non-GPT providers (with warning toast) |
50| `noHephaestusNonGpt` | chat.message | Block Hephaestus from non-GPT models |
51| `hephaestusAgentsMdInjector` | chat.message | Inject walk-up AGENTS.md context for Hephaestus deep-work sessions |
52| `runtimeFallback` | event | Reactive auto-switch on API provider errors |
53| `legacyPluginToast` | chat.message | Show toast when legacy plugin name detected |
54 
55### Tier 2: Tool Guard Hooks (17)
56 
57| Hook | Event | Purpose |
58|------|-------|---------|
59| `commentChecker` | tool.execute.after | Block AI-slop comment patterns (binary: `@code-yeongyu/comment-checker`) |
60| `toolOutputTruncator` | tool.execute.after | Truncate oversized tool output |
61| `directoryAgentsInjector` | tool.execute.before | Inject dir-local AGENTS.md into context |
62| `directoryReadmeInjector` | tool.execute.before | Inject dir-local README.md into context |
63| `emptyTaskResponseDetector` | tool.execute.after | Detect empty task results |
64| `rulesInjector` | tool.execute.before | Conditional rules injection (AGENTS.md, .rules) |
65| `tasksTodowriteDisabler` | tool.execute.before | Disable TodoWrite when Sisyphus task system active |
66| `writeExistingFileGuard` | tool.execute.before | Require Read before Write/Edit on existing files |
67| `bashFileReadGuard` | tool.execute.before | Guard bash commands that read files (cat/head/tail) |
68| `readImageResizer` | tool.execute.after | Resize large images for context efficiency |
69| `todoDescriptionOverride` | tool.execute.before | Override todo item descriptions |
70| `webfetchRedirectGuard` | tool.execute.before | Guard webfetch redirect behavior |
71| `hashlineReadEnhancer` | tool.execute.after | Tag every Read output with `LINE#ID` content hashes |
72| `jsonErrorRecovery` | tool.execute.after | Detect JSON parse errors, inject correction reminder |
73| `fsyncSkipWarning` | tool.execute.after | Warn when fsync is skipped for atomic writes |
74| `notepadWriteGuard` | tool.execute.before | Block `Write` to append-only notepad paths (`.omo/notepads`, `.sisyphus/notepads`) |
75| `planFormatValidator` | tool.execute.before | Validate plan/todo checkbox format on `Write`/`Edit` of boulder plans |
76 
77### Tier 3: Transform Hooks (4 base + 1 monitor-gated)
78 
79| Hook | Event | Purpose |
80|------|-------|---------|
81| `claudeCodeHooks` | messages.transform | Claude Code settings.json compatibility |
82| `keywordDetector` | messages.transform | Detect ultrawork/search/analyze/team modes; inject mode-specific prompt |
83| `contextInjectorMessagesTransform` | messages.transform | Inject AGENTS.md/README.md into context |
84| `toolPairValidator` | messages.transform | Validate tool call/result pairing |
85| `monitorStatusInjector` | messages.transform | Inject running Monitor watch status into context (`monitor.enabled`) |
86 
87### Tier 4: Continuation Hooks (7)
88 
89| Hook | Event | Purpose |
90|------|-------|---------|
91| `stopContinuationGuard` | chat.message | `/stop-continuation` command handler |
92| `compactionContextInjector` | session.compacted | Re-inject context after compaction |
93| `compactionTodoPreserver` | session.compacted | Preserve todos through compaction |
94| `todoContinuationEnforcer` | session.idle | **Boulder** -- force continuation on incomplete todos |
95| `unstableAgentBabysitter` | session.idle | Monitor unstable agent behavior |
96| `backgroundNotificationHook` | event | Background task completion notifications |
97| `atlasHook` | event | Master orchestrator for boulder/background sessions |
98 
99### Tier 5: Skill Hooks (2)
100 
101| Hook | Event | Purpose |
102|------|-------|---------|
103| `categorySkillReminder` | chat.message | Hint to load skills before invoking categories |
104| `autoSlashCommand` | chat.message | Auto-execute matching `/command` from user message |
105 
106### Team-mode Hooks (conditional, only when `team_mode.enabled: true`)
107 
108| Hook | Tier | Registered In | Purpose |
109|------|------|---------------|---------|
110| `team-mode-status-injector` | Transform | [`create-transform-hooks.ts`](../plugin/hooks/create-transform-hooks.ts) | Inject `<team_mode_status>` block into messages |
111| `team-mailbox-injector` | Transform | [`create-transform-hooks.ts`](../plugin/hooks/create-transform-hooks.ts) | Pull pending team mailbox messages into agent context |
112| `team-tool-gating` | Tool Guard | [`create-tool-guard-hooks.ts`](../plugin/hooks/create-tool-guard-hooks.ts) | Restrict `team_*` tools based on member role + permissions |
113| `team-idle-wake-hint` | event handler | [`src/plugin/event.ts`](../plugin/event.ts) | Nudge idle team members back to work |
114| `team-lead-orphan-handler` | event handler | [`src/plugin/event.ts`](../plugin/event.ts) | Detect lead departure → orphan members |
115| `team-member-error-handler` | event handler | [`src/plugin/event.ts`](../plugin/event.ts) | React to member session errors |
116| `team-member-status-handler` | event handler | [`src/plugin/event.ts`](../plugin/event.ts) | Track member status transitions |
117 
118The 4 `team-session-events/` handlers live in `src/hooks/team-session-events/` (separate files: `team-idle-wake-hint.ts`, `team-lead-orphan-handler.ts`, `team-member-error-handler.ts`, `team-member-status-handler.ts`) and are wired into `src/plugin/event.ts` directly, not through a tier composer.
119 
120## STRUCTURE
121 
122```
123hooks/
124├── shared/                                  # Cross-hook helpers (timing, prompt builders, etc.)
125├── team-session-events/                     # 4 team event handlers (wired via src/plugin/event.ts)
126├── (54 index.ts hook directories incl. `task-reminder/` and `ralph-loop/` unwired -- see tier tables above)
127├── zauc-mocks-{bg,cache,hook,ws}, zauc-sync-mocks  # 5 test mocks (NOT hooks; named for sort-order isolation)
128└── (each hook dir)/
129    ├── index.ts        # createXXXHook factory + barrel
130    ├── *.ts            # implementation
131    └── *.test.ts       # bun:test
132```
133 
134## ADDING A NEW HOOK
135 
1361. `mkdir src/hooks/{name}` + `index.ts` exporting `createXXXHook(deps)`
1372. Pick the right tier:
138   - Session lifecycle? → `create-session-hooks.ts`
139   - Pre/post tool? → `create-tool-guard-hooks.ts`
140   - Message transform? → `create-transform-hooks.ts`
141   - Continuation/idle? → `create-continuation-hooks.ts`
142   - Skill awareness? → `create-skill-hooks.ts`
143   - Team-mode-only? → register inside the team-mode conditional block
1443. Add hook name to [`config/schema/hooks.ts`](../config/schema/hooks.ts) `HookNameSchema`
1454. Cover with co-located `*.test.ts` (given/when/then style)
146 
147## NOTES
148 
149- **Tier order matters within a phase:** within Session tier the registration order in `create-session-hooks.ts` determines invocation order -- earlier hooks see un-mutated input, later hooks see accumulated output.
150- **Mock files** (`zauc-mocks-*`, `zauc-sync-mocks`) are NOT hooks. They are placed inside `src/hooks/` purely so `bun:test` discovers them with the hook test fixtures.
151- **`atlasHook` vs `todoContinuationEnforcer`:** atlas handles boulder/ralph/subagent sessions, todoContinuationEnforcer handles the main Sisyphus session. Both fire on `session.idle` but check session type first.
152- **`runtime-fallback` vs `model-fallback`:** runtime-fallback is reactive (after error); model-fallback is proactive (chat.params). They operate independently.
153- **`goal` replaces `ralphLoop` (PR #6184):** `ralphLoop` was removed from `HookNameSchema` and `create-session-hooks.ts`; the `/ralph-loop`, `/ulw-loop`, `/cancel-ralph` builtin commands were removed. The `ralph-loop/` dir + `createRalphLoopHook` factory remain for migration (barrel export kept); `ralph_loop` config is a deprecated passthrough. See [`goal/AGENTS.md`](goal/AGENTS.md).
154