Files

T

justsisyphus f1393d3e85 docs: regenerate hierarchical AGENTS.md with deep investigation

- Root: 181 lines with agent models, complexity hotspots, CI pipeline
- Hooks: 31 lifecycle hooks, execution order, patterns
- Tools: 20+ tools, LSP/AST-Grep specifics, registration
- Features: Background agents, Claude Code compat, skill MCP
- Agents: 10 agents with models, tool restrictions
- Shared: 43 utilities with usage patterns
- CLI: Commander.js entry, doctor checks, TUI framework

Generated via /init-deep with 12 parallel explore agents

2026-01-17 22:01:56 +09:00

3.4 KiB

Raw Blame History

HOOKS KNOWLEDGE BASE

OVERVIEW

31 lifecycle hooks intercepting/modifying agent behavior. Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, onSummarize.

STRUCTURE

hooks/
├── sisyphus-orchestrator/      # Main orchestration & delegation (771 lines)
├── anthropic-context-window-limit-recovery/  # Auto-summarize at token limit
├── todo-continuation-enforcer.ts # Force TODO completion
├── ralph-loop/                 # Self-referential dev loop until done
├── claude-code-hooks/          # settings.json hook compat layer (13 files)
├── comment-checker/            # Prevents AI slop/excessive comments
├── auto-slash-command/         # Detects /command patterns
├── rules-injector/             # Conditional rules from .claude/rules/
├── directory-agents-injector/  # Auto-injects AGENTS.md files
├── directory-readme-injector/  # Auto-injects README.md files
├── preemptive-compaction/      # Triggers summary at 85% context
├── edit-error-recovery/        # Recovers from tool failures
├── thinking-block-validator/   # Ensures valid <thinking> format
├── context-window-monitor.ts   # Reminds agents of remaining headroom
├── session-recovery/           # Auto-recovers from crashes
├── think-mode/                 # Dynamic thinking budget
├── keyword-detector/           # ultrawork/search/analyze modes
├── background-notification/    # OS notification on task completion
└── tool-output-truncator.ts    # Prevents context bloat

HOOK EVENTS

Event	Timing	Can Block	Use Case
PreToolUse	Before tool	Yes	Validate/modify inputs, inject context
PostToolUse	After tool	No	Append warnings, truncate output
UserPromptSubmit	On prompt	Yes	Keyword detection, mode switching
Stop	Session idle	No	Auto-continue (todo-continuation, ralph-loop)
onSummarize	Compaction	No	Preserve critical state

EXECUTION ORDER

chat.message: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork → ralphLoop

tool.execute.before: claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector

tool.execute.after: editErrorRecovery → delegateTaskRetry → commentChecker → toolOutputTruncator → emptyTaskResponseDetector → claudeCodeHooks

HOW TO ADD

Create src/hooks/name/ with index.ts exporting createMyHook(ctx)
Implement event handlers: "tool.execute.before", "tool.execute.after", etc.
Add hook name to HookNameSchema in src/config/schema.ts

const myHook = isHookEnabled("my-hook") ? createMyHook(ctx) : null
// Add to event handlers

PATTERNS

Session-scoped state: Map<sessionID, Set<string>> for tracking per-session
Conditional execution: Check input.tool before processing
Output modification: output.output += "\n${REMINDER}" to append context
Async state: Use promises for CLI path resolution, cache results

ANTI-PATTERNS

Blocking non-critical: Use PostToolUse warnings instead of PreToolUse blocks
Heavy computation: Keep PreToolUse light - slows every tool call
Redundant injection: Track injected files to prevent duplicates
Verbose output: Keep hook messages technical, brief

3.4 KiB Raw Blame History