Skip to main content
Hooks are shell commands that run automatically at specific points in the agent’s lifecycle — before or after tool calls, at session start, when a subagent finishes, and more. They provide deterministic control that doesn’t rely on the agent choosing to do something.
This page covers the ollim-bot-specific config location and a practical example. For the complete event list, input schemas, exit codes, and advanced patterns, see the Claude Code hooks reference.

​
Configuration location

Because ollim-bot uses setting_sources=["project"], hooks defined in ~/.ollim-bot/.claude/settings.json apply to the main agent session:
~/.ollim-bot/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I{} sh -c 'cd $(dirname {}) && ruff format {} 2>/dev/null || true'"
          }
        ]
      }
    ]
  }
}
This hook runs ruff format on any file the agent edits, so formatting stays consistent without the agent having to remember.
Changes to settings.json require /restart to take effect.
Hooks can also be scoped narrower:
  • Per-subagent — define a hooks field in a subagent’s .md frontmatter. The hooks activate when that subagent starts and are cleaned up when it finishes.
  • Per-skill — define a hooks field in a skill’s SKILL.md frontmatter. Active only while that skill runs.

​
Built-in hooks

ollim-bot registers its own hooks on the main session via the SDK hooks parameter — separate from the settings.json hooks above. These run for every session automatically.
HookEventMatcherPurpose
state_dir_guardPreToolUseWrite|EditBlocks writes targeting paths inside state/. See state directory write-protection.
routine_validatorPreToolUseWrite|EditValidates routine .md files before they’re written.
auto_commit_hookPostToolUseWrite|EditAuto-commits markdown writes inside the data directory.
tool_error_hookPostToolUseanyMarks a tool label as errored when the tool returns is_error: true.
tool_failure_hookPostToolUseFailureanyMarks a tool label as errored on hard execution failure.
require_report_hookStopanyEnforces the background fork report contract.

​
Routine validator

When the agent writes or edits a file inside ~/.ollim-bot/routines/, the routine_validator hook simulates the resulting content and runs it through validate_routine() before the write lands on disk. Blocks (the write is denied):
  • Missing frontmatter — routine files require YAML between --- markers
  • Missing id — required for scheduler job registration
  • Missing cron — required for scheduling
  • Invalid cron — must have exactly 5 whitespace-separated fields
  • Malformed YAML — unclosed frontmatter or lines that don’t parse
Warns (the write proceeds, but the agent sees a diagnostic):
  • Missing description or background — degrades schedule display and defaults
  • Unscoped Bash, Write, Edit, or MultiEdit in allowed-tools — should be restricted with a path pattern like Bash(ollim-bot cal *)
  • Delegation (Task/Agent) combined with unscoped Write/Edit — subagent output may land in shared files without verification
  • Underscore keys where canonical form is hyphenated (allowed_tools vs allowed-tools)
  • Unknown frontmatter keys
  • Routine longer than 200 lines
The validator runs on both Write and Edit — for Edit, it simulates the string replacement against the current file contents. When it rejects a write, the denial reason is prefixed with routine-validator: so you can find it in the permission surface.
If a routine still produces wrong results after the validator accepts it, invoke the /improve-routine skill to diagnose quality issues the validator can’t catch — like embellished reporting or data source confusion.

​
Full reference

Claude Code hooks reference

Complete event list, input JSON schemas, exit codes, matcher syntax, and advanced hook types (prompt-based, agent-based, HTTP).

​
Next steps

Subagents

Per-subagent hooks in frontmatter — scoped to a single subagent’s lifecycle.

Skills

Per-skill hooks in frontmatter — active only while a skill runs.