chore(docs): regenerate AGENTS.md knowledge base (#1118)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com> Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
justsisyphus
+45
-29
@@ -1,16 +1,14 @@
|
||||
# HOOKS KNOWLEDGE BASE
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
31 lifecycle hooks intercepting/modifying agent behavior. Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, onSummarize.
|
||||
32 lifecycle hooks intercepting/modifying agent behavior. Events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, onSummarize.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
hooks/
|
||||
├── atlas/ # Main orchestration (773 lines)
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-summarize
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion (489 lines)
|
||||
├── atlas/ # Main orchestration (752 lines)
|
||||
├── anthropic-context-window-limit-recovery/ # Auto-summarize
|
||||
├── todo-continuation-enforcer.ts # Force TODO completion
|
||||
├── ralph-loop/ # Self-referential dev loop
|
||||
├── claude-code-hooks/ # settings.json compat layer - see AGENTS.md
|
||||
├── comment-checker/ # Prevents AI slop
|
||||
@@ -35,45 +33,63 @@ hooks/
|
||||
├── non-interactive-env/ # Non-TTY environment handling
|
||||
├── start-work/ # Sisyphus work session starter
|
||||
├── task-resume-info/ # Resume info for cancelled tasks
|
||||
├── question-label-truncator/ # Auto-truncates question labels >30 chars
|
||||
├── question-label-truncator/ # Auto-truncates question labels
|
||||
├── category-skill-reminder/ # Reminds of category skills
|
||||
├── empty-task-response-detector.ts # Detects empty responses
|
||||
├── sisyphus-junior-notepad/ # Sisyphus Junior notepad
|
||||
└── index.ts # Hook aggregation + registration
|
||||
```
|
||||
|
||||
## HOOK EVENTS
|
||||
|
||||
| Event | Timing | Can Block | Use Case |
|
||||
|-------|--------|-----------|----------|
|
||||
| PreToolUse | Before tool | Yes | Validate/modify inputs |
|
||||
| PostToolUse | After tool | No | Append warnings, truncate |
|
||||
| UserPromptSubmit | On prompt | Yes | Keyword detection |
|
||||
| Stop | Session idle | No | Auto-continue |
|
||||
| onSummarize | Compaction | No | Preserve state |
|
||||
| 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 |
|
||||
|
||||
## EXECUTION ORDER
|
||||
- **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
|
||||
- **PreToolUse**: questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → atlasHook
|
||||
- **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo
|
||||
|
||||
**chat.message**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork → ralphLoop
|
||||
## CRITICAL DEPENDENCIES
|
||||
|
||||
**tool.execute.before**: claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → rulesInjector
|
||||
|
||||
**tool.execute.after**: editErrorRecovery → delegateTaskRetry → commentChecker → toolOutputTruncator → claudeCodeHooks
|
||||
| Hook | Depends On | State Sharing |
|
||||
|------|------------|---------------|
|
||||
| todo-continuation-enforcer | session-recovery callbacks | `isRecovering` flag |
|
||||
| atlas | backgroundManager | Running task checks |
|
||||
| start-work | boulder state file | `.sisyphus/boulder.json` |
|
||||
| directory-*-injector | per-session caches | `sessionCaches` Map |
|
||||
|
||||
## 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`:
|
||||
```typescript
|
||||
const myHook = isHookEnabled("my-hook") ? createMyHook(ctx) : null
|
||||
```
|
||||
3. Register in `src/index.ts` and add to relevant lifecycle methods
|
||||
|
||||
## PATTERNS
|
||||
## HOOK PATTERNS
|
||||
|
||||
- **Session-scoped state**: `Map<sessionID, Set<string>>`
|
||||
- **Conditional execution**: Check `input.tool` before processing
|
||||
- **Output modification**: `output.output += "\n${REMINDER}"`
|
||||
**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 */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- **Blocking non-critical**: Use PostToolUse warnings instead
|
||||
- **Heavy computation**: Keep PreToolUse light
|
||||
- **Redundant injection**: Track injected files
|
||||
- **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
|
||||
|
||||
@@ -1,51 +1,48 @@
|
||||
# CLAUDE CODE HOOKS COMPATIBILITY
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Full Claude Code settings.json hook compatibility. 5 lifecycle events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact.
|
||||
Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in Claude Code configuration.
|
||||
|
||||
## STRUCTURE
|
||||
|
||||
```
|
||||
claude-code-hooks/
|
||||
├── index.ts # Main factory (401 lines)
|
||||
├── config.ts # Loads ~/.claude/settings.json
|
||||
├── config-loader.ts # Extended config
|
||||
├── config-loader.ts # Extended config (disabledHooks)
|
||||
├── pre-tool-use.ts # PreToolUse executor
|
||||
├── post-tool-use.ts # PostToolUse executor
|
||||
├── user-prompt-submit.ts # UserPromptSubmit executor
|
||||
├── stop.ts # Stop hook executor
|
||||
├── stop.ts # Stop hook executor (with active state tracking)
|
||||
├── pre-compact.ts # PreCompact executor
|
||||
├── transcript.ts # Tool use recording
|
||||
├── tool-input-cache.ts # Pre→post caching
|
||||
├── types.ts # Hook types
|
||||
└── todo.ts # Todo JSON fix
|
||||
├── tool-input-cache.ts # Pre→post input caching
|
||||
└── types.ts # Hook & IO type definitions
|
||||
```
|
||||
|
||||
## HOOK LIFECYCLE
|
||||
|
||||
| Event | When | Can Block | Context |
|
||||
|-------|------|-----------|---------|
|
||||
| PreToolUse | Before tool | Yes | sessionId, toolName, toolInput |
|
||||
| PostToolUse | After tool | Warn | + toolOutput, transcriptPath |
|
||||
| UserPromptSubmit | On message | Yes | sessionId, prompt, parts |
|
||||
| Stop | Session idle | inject | sessionId, parentSessionId |
|
||||
| PreCompact | Before summarize | No | sessionId |
|
||||
| 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 |
|
||||
| PreCompact | Before summarize | No | sessionId, cwd |
|
||||
|
||||
## CONFIG SOURCES
|
||||
|
||||
Priority (highest first):
|
||||
1. `.claude/settings.json` (project)
|
||||
2. `~/.claude/settings.json` (user)
|
||||
1. `.claude/settings.json` (Project-local)
|
||||
2. `~/.claude/settings.json` (Global user)
|
||||
|
||||
## HOOK EXECUTION
|
||||
|
||||
1. Hooks loaded from settings.json
|
||||
2. Matchers filter by tool name
|
||||
3. Commands via subprocess with `$SESSION_ID`, `$TOOL_NAME`
|
||||
4. Exit codes: 0=pass, 1=warn, 2=block
|
||||
- **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)
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- **Heavy PreToolUse**: Runs before EVERY tool call
|
||||
- **Blocking non-critical**: Use PostToolUse warnings
|
||||
- **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.
|
||||
|
||||
Reference in New Issue
Block a user