Safety & Monitoring Hooks
Relevant source files
The following files were used as context for generating this wiki page:
Safety and Monitoring Hooks are critical architectural components in Oh-My-OpenCode that enforce operational constraints, maintain agent discipline, and ensure high-quality outputs through automated verification. These hooks act as lifecycle guards that monitor agent behavior, enforce read-only/write-only permissions, and detect state inconsistencies such as "AI slop" or incomplete task responses.
The system utilizes these hooks to implement a "Safety-First" architecture where agents like Sisyphus (the orchestrator) and Prometheus (the planner) are restricted by non-negotiable rules. For example, hooks ensure that the planning agent never performs implementation work and that the orchestrator never delivers a result without verifiable evidence.
Sources: README.md, AGENTS.md, src/hooks/prometheus-md-only/constants.ts
Core Monitoring Framework
The framework provides 34 lifecycle hooks that monitor every stage of an agent's execution. These hooks are designed to prevent common AI failures, such as premature termination, excessive commenting, and unauthorized file modifications.
Agent-Executed QA and Verification
A fundamental safety requirement across all monitoring hooks is the Zero Human Intervention rule. All deliverables must be verified by the agent using automated tools rather than asking the user for manual confirmation.
This diagram illustrates the automated verification flow enforced by safety hooks to ensure tasks are complete without human testing.
Sources: src/agents/prometheus/plan-template.ts, sisyphus-prompt.md
Specialized Safety Hooks
Prometheus Markdown-Only Hook
The prometheus-md-only hook is a specialized safety guard for the Prometheus planning agent. It enforces a strict "Planner, not Implementer" identity by blocking any tool calls that attempt to modify source code or system state outside of the .sisyphus directory.
| Component | Constraint |
|---|---|
| Allowed Extensions | .md only |
| Allowed Paths | .sisyphus/plans/*, .sisyphus/drafts/* |
| Blocked Tools | Write, Edit, write, edit (for non-MD files) |
| System Directive | PROMETHEUS_READ_ONLY |
Sources: src/hooks/prometheus-md-only/constants.ts:7-13, src/agents/prometheus/identity-constraints.ts:86-102
Todo & Continuation Enforcer
This hook monitors the "Todo" or "Task" system. It ensures that if an agent attempts to finish a session while incomplete checkboxes remain in the plan, the system forces a continuation.
- Logic: Detects if
TaskCreateorTodoWritewas called but not all items are markedcompleted. - Safety Trigger: Injects a "MANDATORY WORKFLOW REMINDER" if the agent skips critical planning steps.
Sources: src/agents/sisyphus.ts:50-70, sisyphus-prompt.md, src/hooks/prometheus-md-only/constants.ts:25-45
Monitoring and Validation Logic
Content & Quality Monitoring
The system includes hooks designed to maintain codebase health by monitoring the quality of the generated code.
- Comment Checker: A safety hook that prevents agents from adding "AI slop" or excessive/generic comments to the code.
- LSP Diagnostics: A mandatory monitoring step where agents must run
lsp_diagnosticson changed files before marking a task as complete.
Sequence showing how monitoring hooks utilize LSP diagnostics to validate code quality before allowing task completion.
Sources: sisyphus-prompt.md, README.md, AGENTS.md
Input/Output Validation Hooks
Hooks like the Empty Task Response Detector (referenced in configuration) and Momus Reviewer monitor the validity of agent interactions.
- Momus Reviewer: Acts as a "Blocker-finder" that rejects plans containing missing file references or vague descriptions. It limits feedback to 3 actionable blocking issues to prevent "perfectionism loops."
- Write Protocol: Enforces a "Single Atomic Write" rule to prevent content loss during file operations.
Sources: src/agents/momus.ts:40-65, src/agents/prometheus/identity-constraints.ts:133-145
Implementation Summary
| Hook Feature | Description | File Reference |
|---|---|---|
| Continuation Enforcer | Prevents agents from quitting if todos remain. | sisyphus-prompt.md |
| Read-Only Guard | Blocks Prometheus from writing non-markdown files. | src/hooks/prometheus-md-only/constants.ts |
| Evidence Requirement | Tasks are marked incomplete without tool-based evidence. | sisyphus-prompt.md |
| Atomic Write Guard | Ensures Write tool does not accidentally overwrite parts of a plan. | src/agents/prometheus/identity-constraints.ts |
Sources: src/agents/prometheus/identity-constraints.ts:133, src/hooks/prometheus-md-only/constants.ts:1-20, sisyphus-prompt.md
Conclusion
Safety & Monitoring Hooks provide the "discipline" within the Oh-My-OpenCode ecosystem. By enforcing tool whitelists, validating code through LSP diagnostics, and ensuring a strict separation between planning (Prometheus) and execution (Sisyphus), these hooks allow the system to function autonomously while maintaining human-grade code quality and operational safety.