Hook Configuration

​

What Are Hooks?

• Before/after tool execution
• On session events (created, deleted, idle, error)
• On message transformations
• On continuation/compaction

​

Hook Tiers

​

Tier 1: Session Hooks (23)

• context-window-monitor — Track context usage
• session-recovery — Auto-recover from crashes
• session-notification — OS notifications for session events
• think-mode — Extended thinking mode detection
• model-fallback — Legacy model fallback (use runtime-fallback instead)
• anthropic-context-window-limit-recovery — Auto-compact on context limit
• preemptive-compaction — Proactive context compression
• background-notification — Notifications for background tasks
• auto-update-checker — Check for plugin updates
• startup-toast — Show startup notification
• keyword-detector — Detect special keywords
• agent-usage-reminder — Remind about available agents
• non-interactive-env — Detect non-interactive environments
• interactive-bash-session — Manage bash sessions
• ralph-loop — Ralph loop prevention
• no-sisyphus-gpt — Auto-switch Sisyphus from GPT to Hephaestus
• no-hephaestus-non-gpt — Block non-GPT models for Hephaestus
• start-work — Start work command integration
• atlas — Atlas agent integration
• unstable-agent-babysitter — Monitor unstable agents
• task-resume-info — Task resumption information
• runtime-fallback — Auto-switch models on API errors
• anthropic-effort — Anthropic effort level adjustment

​

Tier 2: Tool Guard Hooks (10)

• comment-checker — Detect AI-generated comment patterns
• tool-output-truncator — Truncate long tool outputs
• question-label-truncator — Truncate question labels
• directory-agents-injector — Inject AGENTS.md content (deprecated on OpenCode 1.1.37+)
• directory-readme-injector — Inject README.md content
• rules-injector — Inject project rules
• write-existing-file-guard — Prevent accidental overwrites
• edit-error-recovery — Recover from edit errors
• json-error-recovery — Recover from JSON parse errors
• hashline-read-enhancer — Annotate Read output with hash anchors

​

Tier 3: Transform Hooks (4)

• thinking-block-validator — Validate thinking blocks
• claude-code-hooks — Claude Code compatibility
• compaction-context-injector — Inject context during compaction
• read-image-resizer — Resize images for multimodal models

​

Continuation Hooks (7)

• todo-continuation-enforcer — Enforce todo completion
• empty-task-response-detector — Detect empty task responses
• delegate-task-retry — Retry failed task delegations
• prometheus-md-only — Markdown-only mode for Prometheus
• sisyphus-junior-notepad — Notepad for Sisyphus Junior
• stop-continuation-guard — Prevent infinite continuations
• tasks-todowrite-disabler — Disable todowrite for task system
• compaction-todo-preserver — Preserve todos during compaction

​

Skill Hooks (2)

• category-skill-reminder — Remind about category-specific skills
• auto-slash-command — Auto-detect slash commands

​

Disabling Hooks

{
  "disabled_hooks": [
    "comment-checker",
    "agent-usage-reminder",
    "startup-toast"
  ]
}

​

Hook-Specific Configuration

​

Comment Checker

{
  "comment_checker": {
    "custom_prompt": "Check these comments for AI patterns: {{comments}}"
  }
}

{
  "disabled_hooks": ["comment-checker"]
}

​

Startup Toast

{
  "disabled_hooks": ["startup-toast"]
}

{
  "auto_update": false,
  "disabled_hooks": ["auto-update-checker"]
}

​

Directory Agents Injector

{
  "disabled_hooks": ["directory-agents-injector"]
}

​

Hashline Read Enhancer

• hashline-read-enhancer — Annotates Read output with LINE#ID anchors
• hashline-edit-diff-enhancer — Shows diffs for hashline edits

{
  "hashline_edit": false
}

{
  "disabled_hooks": [
    "hashline-read-enhancer"
  ]
}

​

Tool Output Truncator

{
  "disabled_hooks": ["tool-output-truncator"]
}

{
  "experimental": {
    "truncate_all_tool_outputs": true
  }
}

​

Runtime Fallback

{
  "runtime_fallback": false
}

{
  "disabled_hooks": ["runtime-fallback"]
}

​

Ralph Loop

{
  "ralph_loop": {
    "enabled": true,
    "max_iterations": 10,
    "detection_window": 5
  }
}

{
  "disabled_hooks": ["ralph-loop"]
}

​

All Available Hooks

{
  "disabled_hooks": [
    // Session hooks (23)
    "todo-continuation-enforcer",
    "context-window-monitor",
    "session-recovery",
    "session-notification",
    "think-mode",
    "model-fallback",
    "anthropic-context-window-limit-recovery",
    "preemptive-compaction",
    "background-notification",
    "auto-update-checker",
    "startup-toast",
    "keyword-detector",
    "agent-usage-reminder",
    "non-interactive-env",
    "interactive-bash-session",
    "ralph-loop",
    "no-sisyphus-gpt",
    "no-hephaestus-non-gpt",
    "start-work",
    "atlas",
    "unstable-agent-babysitter",
    "task-resume-info",
    "runtime-fallback",
    "anthropic-effort",

    // Tool guard hooks (10)
    "comment-checker",
    "tool-output-truncator",
    "question-label-truncator",
    "directory-agents-injector",
    "directory-readme-injector",
    "rules-injector",
    "write-existing-file-guard",
    "edit-error-recovery",
    "json-error-recovery",
    "hashline-read-enhancer",

    // Transform hooks (4)
    "thinking-block-validator",
    "claude-code-hooks",
    "compaction-context-injector",
    "read-image-resizer",

    // Continuation hooks (7)
    "empty-task-response-detector",
    "delegate-task-retry",
    "prometheus-md-only",
    "sisyphus-junior-notepad",
    "stop-continuation-guard",
    "tasks-todowrite-disabler",
    "compaction-todo-preserver",

    // Skill hooks (2)
    "category-skill-reminder",
    "auto-slash-command"
  ]
}

​

Hook Migration

​

Safe Hook Creation

{
  "experimental": {
    "safe_hook_creation": true  // Default
  }
}

{
  "experimental": {
    "safe_hook_creation": false
  }
}

​

Common Configurations

​

Minimal Hooks

{
  "disabled_hooks": [
    "comment-checker",
    "agent-usage-reminder",
    "startup-toast",
    "auto-update-checker",
    "background-notification",
    "session-notification",
    "directory-readme-injector",
    "question-label-truncator"
  ]
}

​

Performance-Optimized

{
  "disabled_hooks": [
    "comment-checker",
    "context-window-monitor",
    "directory-agents-injector",
    "directory-readme-injector",
    "rules-injector"
  ],
  "experimental": {
    "aggressive_truncation": true
  }
}

​

Silent Mode

{
  "disabled_hooks": [
    "startup-toast",
    "background-notification",
    "session-notification",
    "auto-update-checker"
  ]
}

​

Next Steps