docs(agents): regenerate all AGENTS.md with deep codebase analysis
This commit is contained in:
YeonGyu-Kim
+49
-58
@@ -2,48 +2,40 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
163 lifecycle hooks intercepting/modifying agent behavior across 5 events.
|
||||
|
||||
**Event Types**:
|
||||
- `UserPromptSubmit` (`chat.message`) - Can block
|
||||
- `PreToolUse` (`tool.execute.before`) - Can block
|
||||
- `PostToolUse` (`tool.execute.after`) - Cannot block
|
||||
- `Stop` (`event: session.stop`) - Cannot block
|
||||
- `onSummarize` (Compaction) - Cannot block
|
||||
41 lifecycle hooks intercepting/modifying agent behavior across 7 event types. Three-tier registration: Core (32) → Continuation (7) → Skill (2).
|
||||
|
||||
## STRUCTURE
|
||||
```
|
||||
hooks/
|
||||
├── agent-usage-reminder/ # Specialized agent hints (212 lines)
|
||||
├── agent-usage-reminder/ # Specialized agent hints (109 lines)
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines)
|
||||
├── anthropic-effort/ # Anthropic effort level management (272 lines)
|
||||
├── anthropic-effort/ # Effort=max for Opus max variant (56 lines)
|
||||
├── atlas/ # Main orchestration hook (1976 lines)
|
||||
├── auto-slash-command/ # Detects /command patterns (1134 lines)
|
||||
├── auto-update-checker/ # Plugin update check (1140 lines)
|
||||
├── background-notification/ # OS notifications (33 lines)
|
||||
├── category-skill-reminder/ # Reminds of category skills (597 lines)
|
||||
├── claude-code-hooks/ # settings.json compat - see AGENTS.md (2110 lines)
|
||||
├── category-skill-reminder/ # Category+skill delegation reminders (597 lines)
|
||||
├── claude-code-hooks/ # settings.json compat (2110 lines) - see AGENTS.md
|
||||
├── comment-checker/ # Prevents AI slop comments (710 lines)
|
||||
├── compaction-context-injector/ # Injects context on compaction (128 lines)
|
||||
├── compaction-todo-preserver/ # Preserves todos during compaction (203 lines)
|
||||
├── context-window-monitor.ts # Reminds of headroom (99 lines)
|
||||
├── context-window-monitor.ts # Reminds of headroom at 70% (99 lines)
|
||||
├── delegate-task-retry/ # Retries failed delegations (266 lines)
|
||||
├── directory-agents-injector/ # Auto-injects AGENTS.md (195 lines)
|
||||
├── directory-readme-injector/ # Auto-injects README.md (190 lines)
|
||||
├── edit-error-recovery/ # Recovers from edit failures (188 lines)
|
||||
├── empty-task-response-detector.ts # Detects empty responses (27 lines)
|
||||
├── index.ts # Hook aggregation + registration (46 lines)
|
||||
├── interactive-bash-session/ # Tmux session management (695 lines)
|
||||
├── keyword-detector/ # ultrawork/search/analyze modes (1665 lines)
|
||||
├── non-interactive-env/ # Non-TTY environment handling (483 lines)
|
||||
├── preemptive-compaction.ts # Preemptive context compaction (108 lines)
|
||||
├── non-interactive-env/ # Non-TTY handling (483 lines)
|
||||
├── preemptive-compaction.ts # Auto-compact at 78% usage (108 lines)
|
||||
├── prometheus-md-only/ # Planner read-only mode (955 lines)
|
||||
├── question-label-truncator/ # Auto-truncates question labels (199 lines)
|
||||
├── question-label-truncator/ # Truncates labels to 30 chars (199 lines)
|
||||
├── ralph-loop/ # Self-referential dev loop (1687 lines)
|
||||
├── rules-injector/ # Conditional rules injection (1604 lines)
|
||||
├── session-notification.ts # Session event notifications (108 lines)
|
||||
├── rules-injector/ # Conditional .sisyphus/rules injection (1604 lines)
|
||||
├── session-notification.ts # OS idle notifications (108 lines)
|
||||
├── session-recovery/ # Auto-recovers from crashes (1279 lines)
|
||||
├── sisyphus-junior-notepad/ # Sisyphus Junior notepad (76 lines)
|
||||
├── sisyphus-junior-notepad/ # Junior notepad directive (76 lines)
|
||||
├── start-work/ # Sisyphus work session starter (648 lines)
|
||||
├── stop-continuation-guard/ # Guards stop continuation (214 lines)
|
||||
├── subagent-question-blocker/ # Blocks subagent questions (112 lines)
|
||||
@@ -51,54 +43,53 @@ hooks/
|
||||
├── task-resume-info/ # Resume info for cancelled tasks (39 lines)
|
||||
├── tasks-todowrite-disabler/ # Disables TodoWrite when tasks active (202 lines)
|
||||
├── think-mode/ # Dynamic thinking budget (1365 lines)
|
||||
├── thinking-block-validator/ # Ensures valid <thinking> blocks (169 lines)
|
||||
├── todo-continuation-enforcer/ # Force TODO completion (2061 lines)
|
||||
├── thinking-block-validator/ # Validates thinking blocks (169 lines)
|
||||
├── todo-continuation-enforcer/ # Force TODO completion — boulder mechanism (2061 lines)
|
||||
├── tool-output-truncator.ts # Prevents context bloat (62 lines)
|
||||
├── unstable-agent-babysitter/ # Monitors unstable agent behavior (451 lines)
|
||||
└── write-existing-file-guard/ # Guards against overwriting files (356 lines)
|
||||
├── unstable-agent-babysitter/ # Monitors unstable behavior (451 lines)
|
||||
└── write-existing-file-guard/ # Guards against file overwrite (356 lines)
|
||||
```
|
||||
|
||||
## HOOK EVENTS
|
||||
| Event | Timing | Can Block | Use Case |
|
||||
|-------|--------|-----------|----------|
|
||||
| UserPromptSubmit | `chat.message` | Yes | Keyword detection, slash commands |
|
||||
| PreToolUse | `tool.execute.before` | Yes | Validate/modify inputs, inject context |
|
||||
| PostToolUse | `tool.execute.after` | No | Truncate output, error recovery |
|
||||
| Stop | `event` (session.stop) | No | Auto-continue, notifications |
|
||||
| onSummarize | Compaction | No | Preserve state, inject summary context |
|
||||
## EVENT TYPES
|
||||
|
||||
| Event | Hook Method | Can Block | Count |
|
||||
|-------|-------------|-----------|-------|
|
||||
| UserPromptSubmit | `chat.message` | Yes | 4 |
|
||||
| ChatParams | `chat.params` | No | 2 |
|
||||
| PreToolUse | `tool.execute.before` | Yes | 13 |
|
||||
| PostToolUse | `tool.execute.after` | No | 18 |
|
||||
| SessionEvent | `event` | No | 17 |
|
||||
| MessagesTransform | `experimental.chat.messages.transform` | No | 1 |
|
||||
| Compaction | `onSummarize` | No | 1 |
|
||||
|
||||
## BLOCKING HOOKS (8)
|
||||
|
||||
| Hook | Event | Blocks When |
|
||||
|------|-------|-------------|
|
||||
| auto-slash-command | chat.message | Command execution fails |
|
||||
| keyword-detector | chat.message | Keyword injection fails |
|
||||
| non-interactive-env | tool.execute.before | Interactive command in non-TTY |
|
||||
| prometheus-md-only | tool.execute.before | Write outside .sisyphus/*.md |
|
||||
| subagent-question-blocker | tool.execute.before | Question tool in subagent |
|
||||
| tasks-todowrite-disabler | tool.execute.before | TodoWrite with task system |
|
||||
| write-existing-file-guard | tool.execute.before | Write to existing file |
|
||||
| claude-code-hooks | tool.execute.before | Exit code 2 from settings.json hook |
|
||||
|
||||
## EXECUTION ORDER
|
||||
- **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
|
||||
- **PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → atlasHook
|
||||
- **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder
|
||||
|
||||
**UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
|
||||
**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → atlasHook
|
||||
**PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder
|
||||
|
||||
## HOW TO ADD
|
||||
|
||||
1. Create `src/hooks/name/` with `index.ts` exporting `createMyHook(ctx)`
|
||||
2. Add hook name to `HookNameSchema` in `src/config/schema.ts`
|
||||
3. Register in `src/index.ts` and add to relevant lifecycle methods
|
||||
|
||||
## HOOK PATTERNS
|
||||
|
||||
**Simple Single-Event**:
|
||||
```typescript
|
||||
export function createToolOutputTruncatorHook(ctx) {
|
||||
return { "tool.execute.after": async (input, output) => { ... } }
|
||||
}
|
||||
```
|
||||
|
||||
**Multi-Event with State**:
|
||||
```typescript
|
||||
export function createThinkModeHook() {
|
||||
const state = new Map<string, ThinkModeState>()
|
||||
return {
|
||||
"chat.params": async (output, sessionID) => { ... },
|
||||
"event": async ({ event }) => { /* cleanup */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
2. Add hook name to `HookNameSchema` in `src/config/schema/hooks.ts`
|
||||
3. Register in appropriate `src/plugin/hooks/create-*-hooks.ts`
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool — keep light
|
||||
- **Blocking non-critical**: Use PostToolUse warnings instead
|
||||
- **Heavy computation**: Keep PreToolUse light to avoid latency
|
||||
- **Redundant injection**: Track injected files to avoid context bloat
|
||||
- **Direct state mutation**: Use `output.output +=` instead of replacing
|
||||
|
||||
@@ -28,24 +28,23 @@ claude-code-hooks/
|
||||
```
|
||||
|
||||
## HOOK LIFECYCLE
|
||||
|
||||
| Event | Timing | Can Block | Context Provided |
|
||||
|-------|--------|-----------|------------------|
|
||||
| PreToolUse | Before tool exec | Yes | sessionId, toolName, toolInput, cwd |
|
||||
| PostToolUse | After tool exec | Warn | + toolOutput, transcriptPath |
|
||||
| UserPromptSubmit | On message send | Yes | sessionId, prompt, parts, cwd |
|
||||
| Stop | Session idle/end | Inject | sessionId, parentSessionId, cwd |
|
||||
| PreToolUse | Before exec | Yes (exit 2) | sessionId, toolName, toolInput, cwd |
|
||||
| PostToolUse | After exec | Warn (exit 1) | + toolOutput, transcriptPath |
|
||||
| UserPromptSubmit | On message | Yes (exit 2) | sessionId, prompt, parts, cwd |
|
||||
| Stop | Session end | Inject | sessionId, parentSessionId, cwd |
|
||||
| PreCompact | Before summarize | No | sessionId, cwd |
|
||||
|
||||
## HOOK EXECUTION
|
||||
- **Matchers**: Hooks filter by tool name or event type via regex/glob
|
||||
- **Commands**: Executed via subprocess with env vars (`$SESSION_ID`, `$TOOL_NAME`)
|
||||
- **Exit Codes**:
|
||||
- `0`: Pass (Success)
|
||||
- `1`: Warn (Continue with system message)
|
||||
- `2`: Block (Abort operation/prompt)
|
||||
## EXIT CODES
|
||||
|
||||
- `0`: Pass (continue)
|
||||
- `1`: Warn (continue + system message)
|
||||
- `2`: Block (abort operation)
|
||||
|
||||
## ANTI-PATTERNS
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool; keep logic light to avoid latency
|
||||
- **Blocking non-critical**: Prefer PostToolUse warnings for non-fatal issues
|
||||
- **Direct state mutation**: Use `updatedInput` in PreToolUse instead of side effects
|
||||
- **Ignoring Exit Codes**: Ensure scripts return `2` to properly block sensitive tools
|
||||
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool — keep scripts fast
|
||||
- **Blocking non-critical**: Prefer PostToolUse warnings
|
||||
- **Ignoring exit codes**: Return `2` to block sensitive tools
|
||||
|
||||
Reference in New Issue
Block a user