AGENTS.md

1# src/plugin/ -- 12 OpenCode Hook Handlers + Hook Composition
2 
3**Generated:** 2026-07-17 / 7d664b96b
4 
5## OVERVIEW
6 
7Core glue layer. Files assemble the 12 OpenCode hook handlers wired into `PluginInterface` here (an additional 2, `experimental.session.compacting` + `experimental.compaction.autocontinue`, are wired in `src/testing/create-plugin-module.ts`). Each handler file maps to one OpenCode hook type.
8 
9## HANDLER FILES
10 
11| File | OpenCode Hook | Purpose |
12|------|---------------|---------|
13| `config.ts` | `config` | 6-phase config loading pipeline (delegates to `plugin-handlers/`) |
14| `tool-registry.ts` | `tool` | 12-38 tools assembled with config gates (team-mode +12, monitor +4, task system +4, hashline +1, interactive_bash +1, look_at +1, goal +3); split across `tool-registry-{core-tools,team-tools,gated-tools}.ts` |
15| `tool-definition.ts` | `tool.definition` | Per-tool definition transform (applies todo-description-override) |
16| `chat-message.ts` | `chat.message` | First-message variant resolution, session setup, keyword detection, goal command dispatch + default goal auto-start |
17| `chat-params.ts` | `chat.params` | Anthropic effort, think mode, runtime fallback model override |
18| `chat-headers.ts` | `chat.headers` | Copilot `x-initiator` header injection |
19| `command-execute-before.ts` | `command.execute.before` | Pre-command guards (stop-continuation, /goal dispatch, start-work, auto-slash-command) |
20| `event.ts` | `event` | Session lifecycle (created/deleted/idle/error/status), openclaw dispatch, runtime fallback, 4 team-session-event handlers (when team_mode.enabled) |
21| `tool-execute-before.ts` | `tool.execute.before` | Pre-tool guards (mcp_ strip, bash sleep block, task subagent resolution, skill /goal + /stop-continuation dispatch) |
22| `tool-execute-after.ts` | `tool.execute.after` | Post-tool hooks (truncation, comment-checker, hashline read tagging, json-error-recovery) |
23| `messages-transform.ts` | `experimental.chat.messages.transform` | Context injection, thinking-block validation, tool-pair validation, keyword detection, category-skill reminder |
24| `system-transform.ts` | `experimental.chat.system.transform` | System-message-level transforms |
25| `session-compacting.ts` | `experimental.session.compacting` | Context + todo preservation across compaction (registered via `create-plugin-module.ts`) |
26| `skill-context.ts` | (helper) | Skill/browser/category context shared with tool creation |
27| `build-team-idle-wake-hint-client.ts` | (helper) | Build the team idle-wake-hint client wired into event handlers |
28 
29## HOOK COMPOSITION (hooks/ subdir)
30 
31| File | Tier | Count |
32|------|------|-------|
33| `create-session-hooks.ts` | Session | 24 |
34| `create-tool-guard-hooks.ts` | Tool Guard | 18 (incl. `team-tool-gating`, null unless team_mode) |
35| `create-transform-hooks.ts` | Transform | 7 slots (2 team-gated, 1 monitor-gated; incl. `contextInjectorMessagesTransform` from `features/context-injector`) |
36| `create-skill-hooks.ts` | Skill | 2 |
37| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 49 slots |
38 
39`createContinuationHooks()` (7) lives in `src/create-hooks.ts` next to `createCoreHooks()` and `createSkillHooks()`.
40 
41## SUPPORT FILES
42 
43| File | Purpose |
44|------|---------|
45| `available-categories.ts` | Build `AvailableCategory[]` for agent prompt injection |
46| `session-agent-resolver.ts` | Resolve which agent owns a session |
47| `session-status-normalizer.ts` | Normalize session status across OpenCode versions |
48| `recent-synthetic-idles.ts` | Dedup rapid synthetic idle events |
49| `unstable-agent-babysitter.ts` | Track unstable agent behavior across sessions |
50| `types.ts` | `PluginContext`, `PluginInterface`, `ToolsRecord`, `TmuxConfig` |
51| `ultrawork-model-override.ts` | Ultrawork mode model override logic |
52| `ultrawork-db-model-override.ts` | DB-level model override for ultrawork |
53| `config-handler.ts` | Runtime config loading and caching |
54| `normalize-tool-arg-schemas.ts` | Coerce tool arg schemas into a normalized shape |
55| `native-skills.ts` | Native-skill loader (`createNativeSkills` / `getPluginInputNativeSkills`) feeding lazy `getLoadedSkills` discovery in skill/delegate tools |
56 
57## TOOL REGISTRATION GATES
58 
59```typescript
60// src/plugin/tool-registry.ts
61const taskToolsRecord = isTaskSystemEnabled(config) ? { task_create, task_get, task_list, task_update } : {}
62const hashlineToolsRecord = config.hashline_edit ? { edit: createHashlineEditTool(ctx) } : {}
63const teamModeToolsRecord = config.team_mode?.enabled ? { team_create, team_delete, team_shutdown_request, team_approve_shutdown, team_reject_shutdown, team_send_message, team_task_create, team_task_list, team_task_update, team_task_get, team_status, team_list } : {}
64const lookAt = isMultimodalLookerEnabled ? { look_at: createLookAt(ctx) } : {}
65const interactiveBashTool = interactiveBashEnabled ? { interactive_bash } : {}
66const goalToolsRecord = pluginConfig.goal?.enabled ? { create_goal, update_goal, get_goal } : {}
67 
68const allTools = {
69  ...createGrepTools(ctx),
70  ...createGlobTools(ctx),
71  ...createSessionManagerTools(ctx),
72  ...backgroundTools,                 // 2 background_*
73  call_omo_agent, task,
74  ...lookAt,
75  skill_mcp, skill,
76  ...interactiveBashTool,
77  ...teamModeToolsRecord,             // +12 conditional
78  ...taskToolsRecord,                 // +4 conditional
79  ...hashlineToolsRecord,             // +1 conditional
80  ...goalToolsRecord,                 // +3 conditional (config.goal.enabled)
81}
82 
83// lsp_* tools are supplied by the built-in MCP server "lsp"
84```
85 
86## KEY PATTERNS
87 
88- Each handler exports a function receiving `(hookRecord, ctx, pluginConfig, managers)` → returns the OpenCode hook function.
89- Handlers iterate over hook records, calling each hook with `(input, output)` in registration order.
90- `safeHook()` wrapper isolates hook errors so one broken hook does not crash the chain.
91- `filterDisabledTools(allTools, disabled_tools)` prunes tools listed in `disabled_tools` config.
92- `experimental.max_tools` cap trims tool count when set (selects the highest-priority tools).
93