oh-my-opencode-slim/src/hooks/codemap.md

src/hooks/

This directory exposes the public hook entry points that feature code imports to tap into behavior such as workflow reminders, error recovery, rate-limit fallback, and delegation guidance.

Responsibility

Acts as a single entry point that re-exports the factory functions and types for every hook implementation underneath src/hooks/, so other modules can import from a flat namespace without needing to know subpaths.

Design

• Aggregator/re-export pattern: index.ts consolidates all hook factories and types for the entire hooks subsystem.
• Factory-based design: Each hook is a factory function that returns a hook object with specific hook points (e.g., 'tool.execute.after', 'experimental.chat.messages.transform', 'chat.headers').
• Modular architecture: Each hook lives in its own subdirectory with internal components (hook implementation, patterns, guidance, etc.).
• Event-driven hooks: Hooks respond to OpenCode plugin events and modify output before it reaches the LLM or UI.

Flow

1. Import: Feature modules import factories from src/hooks/index.ts (e.g., createPhaseReminderHook, createJsonErrorRecoveryHook).
2. Configure: Call factory with any required context (e.g., PluginInput for client access).
3. Register: Hook objects are registered with OpenCode's plugin system via the feature layer.
4. Execute: At runtime, OpenCode invokes hook functions at specific points (tool execution, message transformation, event handling).
5. Modify: Hooks inspect input/output and apply side-effects (inject text, modify headers, append guidance).

Integration

Hook Points

Hook Point	Purpose	Hooks
'tool.execute.after'	Modify tool output after execution	post-read-nudge, delegate-task-retry, json-error-recovery
'experimental.chat.messages.transform'	Transform messages before API call	phase-reminder
'chat.headers'	Add custom headers to API requests	chat-headers
Event handlers	React to OpenCode events	foreground-fallback

Hook Implementations

phase-reminder

• Location: src/hooks/phase-reminder/index.ts
• Purpose: Injects workflow reminder before each user message for the orchestrator agent to combat instruction-following degradation.
• Hook Point: 'experimental.chat.messages.transform'
• Behavior: Prepend reminder text to the last user message if agent is 'orchestrator' and message doesn't contain internal initiator marker.
• Research: Based on "LLMs Get Lost In Multi-Turn Conversation" (arXiv:2505.06120) showing ~40% compliance drop after 2-3 turns without reminders.

post-read-nudge

• Location: src/hooks/post-read-nudge/index.ts
• Purpose: Appends delegation reminder after file reads to catch the "read files → implement myself" anti-pattern.
• Hook Point: 'tool.execute.after'
• Behavior: Appends nudge text to output when tool is 'Read' or 'read'.

chat-headers

• Location: src/hooks/chat-headers.ts
• Purpose: Adds x-initiator: agent header for GitHub Copilot provider when internal initiator marker is detected.
• Hook Point: 'chat.headers'
• Behavior: Checks for internal marker via API call, only applies to Copilot provider and non-Copilot npm model.
• Caching: Uses in-memory cache (max 1000 entries) to reduce API calls.

delegate-task-retry

• Location: src/hooks/delegate-task-retry/
• Purpose: Detects delegate task errors and provides actionable retry guidance.
• Components:
  • hook.ts: Main hook that detects errors and appends guidance.
  • patterns.ts: Defines error patterns and detection logic.
  • guidance.ts: Builds retry guidance messages with available options.
• Hook Point: 'tool.execute.after'
• Behavior: Detects errors like missing run_in_background, invalid category/agent, unknown skills, and appends structured guidance.
• Patterns: 8 error types with specific fix hints and available options extraction.

foreground-fallback

• Location: src/hooks/foreground-fallback/index.ts
• Purpose: Runtime model fallback for foreground (interactive) agent sessions experiencing rate limits.
• Hook Point: Event-driven (not a standard hook point)
• Behavior:
  • Monitors message.updated, session.error, session.status, and subagent.session.created events.
  • Detects rate-limit signals via regex patterns.
  • Aborts rate-limited prompt via client.session.abort().
  • Re-queues last user message via client.session.promptAsync() with fallback model.
  • Tracks tried models per session to avoid infinite loops.
  • Deduplicates triggers within 5-second window.
• Fallback Chains: Configurable per agent (e.g., { orchestrator: ['anthropic/claude-opus-4-5', 'openai/gpt-4o'] }).
• Cleanup: Removes session state on session.deleted events.

json-error-recovery

• Location: src/hooks/json-error-recovery/
• Purpose: Detects JSON parse errors and provides immediate recovery guidance.
• Components:
  • hook.ts: Main hook that detects JSON errors and appends guidance.
  • index.ts: Re-exports hook and constants.
• Hook Point: 'tool.execute.after'
• Behavior: Appends structured reminder when JSON parse errors are detected in tool output (excluding bash, read, glob, webfetch, etc.).
• Patterns: 8 regex patterns covering common JSON syntax errors.

Dependencies

• OpenCode SDK: @opencode-ai/plugin (PluginInput type, client access)
• OpenCode SDK: @opencode-ai/sdk (Model, UserMessage types)
• Internal Utils: hasInternalInitiatorMarker, SLIM_INTERNAL_INITIATOR_MARKER
• Internal Logger: utils/logger

Consumers

• Feature modules in src/ import hook factories from src/hooks/index.ts.
• Plugin initialization in src/index.ts registers hooks with OpenCode's plugin system.
• No direct relations to deeper hook files from consumers (implementation details hidden).