docs(agents): update hook counts 44→46, add hashline-edit documentation

- Update root AGENTS.md: hook count 44→46, commit fcb90d92, generated 2026-02-24 - Update src/AGENTS.md: core hooks 35→37, session hooks 21→23 - Update src/hooks/AGENTS.md: 46 hooks total, add modelFallback/noSisyphusGpt/noHephaestusNonGpt/runtimeFallback, jsonErrorRecovery moved to tool-guard (tier 2) - Create src/tools/hashline-edit/AGENTS.md (93 lines): documents three-op model, LINE#ID format, execution pipeline - Refresh timestamps: 2026-02-21→2026-02-24 on 28 files - Update plugin/AGENTS.md hook composition counts 🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
2026-02-25 00:02:05 +09:00
parent fcb90d92a4
commit 73453a7191
33 changed files with 206 additions and 51 deletions
@@ -1,6 +1,6 @@
 # src/ — Plugin Source

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -14,7 +14,7 @@ Root source directory. Entry point `index.ts` orchestrates 4-step initialization
 | `plugin-config.ts` | JSONC parse, multi-level merge (user → project → defaults), Zod validation |
 | `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler |
 | `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry |
-| `create-hooks.ts` | 3-tier hook composition: Core(35) + Continuation(7) + Skill(2) |
+| `create-hooks.ts` | 3-tier hook composition: Core(37) + Continuation(7) + Skill(2) |
 | `plugin-interface.ts` | Assembles 8 OpenCode hook handlers into PluginInterface |

 ## CONFIG LOADING
@@ -32,9 +32,9 @@ loadPluginConfig(directory, ctx)

 ```
 createHooks()
-  ├─→ createCoreHooks()           # 35 hooks
-  │   ├─ createSessionHooks()     # 21: contextWindowMonitor, thinkMode, ralphLoop, sessionRecovery, jsonErrorRecovery, sisyphusGptHephaestusReminder, anthropicEffort...
-  │   ├─ createToolGuardHooks()   # 10: commentChecker, rulesInjector, writeExistingFileGuard, hashlineEditDiffEnhancer...
+  ├─→ createCoreHooks()           # 37 hooks
+  │   ├─ createSessionHooks()     # 23: contextWindowMonitor, thinkMode, ralphLoop, modelFallback, runtimeFallback, noSisyphusGpt, noHephaestusNonGpt, anthropicEffort...
+  │   ├─ createToolGuardHooks()   # 10: commentChecker, rulesInjector, writeExistingFileGuard, jsonErrorRecovery, hashlineReadEnhancer...
  │   └─ createTransformHooks()   # 4: claudeCodeHooks, keywordDetector, contextInjector, thinkingBlockValidator
  ├─→ createContinuationHooks()   # 7: todoContinuationEnforcer, atlas, stopContinuationGuard...
  └─→ createSkillHooks()          # 2: categorySkillReminder, autoSlashCommand
@@ -1,6 +1,6 @@
 # src/agents/ — 11 Agent Definitions

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/cli/config-manager/ — CLI Installation Utilities

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/cli/run/ — Non-Interactive Session Launcher

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/config/ — Zod v4 Schema System

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/ — 19 Feature Modules

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/background-agent/ — Core Orchestration Engine

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/claude-tasks/ — Task Schema + Storage

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/opencode-skill-loader/ — 4-Scope Skill Discovery

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/features/tmux-subagent/ — Tmux Pane Management

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,14 +1,14 @@
-# src/hooks/ — 44 Lifecycle Hooks
+# src/hooks/ — 46 Lifecycle Hooks

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

-44 hooks across 39 directories + 6 standalone files. Three-tier composition: Core(35) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
+46 hooks across 39 directories + 6 standalone files. Three-tier composition: Core(37) + Continuation(7) + Skill(2). All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.

 ## HOOK TIERS

-### Tier 1: Session Hooks (22) — `create-session-hooks.ts`
+### Tier 1: Session Hooks (23) — `create-session-hooks.ts`
 ## STRUCTURE
 ```
 hooks/
@@ -70,11 +70,12 @@ hooks/
 | questionLabelTruncator | tool.execute.before | Truncate long question labels |
 | taskResumeInfo | chat.message | Inject task context on resume |
 | anthropicEffort | chat.params | Adjust reasoning effort level |
-| jsonErrorRecovery | tool.execute.after | Detect JSON parse errors, inject correction reminder |
-| sisyphusGptHephaestusReminder | chat.message | Toast warning when Sisyphus uses GPT model |
-| taskReminder | tool.execute.after | Remind about task tools after 10 turns without usage |
+| modelFallback | chat.params | Provider-level model fallback on errors |
+| noSisyphusGpt | chat.message | Block Sisyphus from using GPT models (toast warning) |
+| noHephaestusNonGpt | chat.message | Block Hephaestus from using non-GPT models |
+| runtimeFallback | event | Auto-switch models on API provider errors |

-### Tier 2: Tool Guard Hooks (9) — `create-tool-guard-hooks.ts`
+### Tier 2: Tool Guard Hooks (10) — `create-tool-guard-hooks.ts`

 | Hook | Event | Purpose |
 |------|-------|---------|
@@ -87,6 +88,7 @@ hooks/
 | tasksTodowriteDisabler | tool.execute.before | Disable TodoWrite when task system active |
 | writeExistingFileGuard | tool.execute.before | Require Read before Write on existing files |
 | hashlineReadEnhancer | tool.execute.after | Enhance Read output with line hashes |
+| jsonErrorRecovery | tool.execute.after | Detect JSON parse errors, inject correction reminder |

 ### Tier 3: Transform Hooks (4) — `create-transform-hooks.ts`

@@ -1,6 +1,6 @@
 # src/hooks/anthropic-context-window-limit-recovery/ — Multi-Strategy Context Recovery

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/keyword-detector/ — Mode Keyword Injection

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/ralph-loop/ — Self-Referential Dev Loop

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/rules-injector/ — Conditional Rules Injection

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/session-recovery/ — Auto Session Error Recovery

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,10 +1,10 @@
 # src/plugin/ — 8 OpenCode Hook Handlers + Hook Composition

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

-Core glue layer. 20 source files assembling the 8 OpenCode hook handlers and composing 44 hooks into the PluginInterface. Every handler file corresponds to one OpenCode hook type.
+Core glue layer. 20 source files assembling the 8 OpenCode hook handlers and composing 46 hooks into the PluginInterface. Every handler file corresponds to one OpenCode hook type.

 ## HANDLER FILES

@@ -25,10 +25,10 @@ Core glue layer. 20 source files assembling the 8 OpenCode hook handlers and com
 |------|------|-------|
 | `create-session-hooks.ts` | Session | 21 |
 | `create-tool-guard-hooks.ts` | Tool Guard | 10 |
-| `create-transform-hooks.ts` | Transform | 4 |
-| `create-continuation-hooks.ts` | Continuation | 7 |
+| `create-session-hooks.ts` | Session | 23 |
+| `create-tool-guard-hooks.ts` | Tool Guard | 10 |
 | `create-skill-hooks.ts` | Skill | 2 |
-| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 35 |
+| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 37 |

 ## SUPPORT FILES

@@ -1,6 +1,6 @@
 # src/shared/ — 101 Utility Files in 13 Categories

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/tools/ — 26 Tools Across 15 Directories

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/tools/background-task/ — Background Task Tool Wrappers

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/tools/call-omo-agent/ — Direct Agent Invocation Tool

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -1,6 +1,6 @@
 # src/tools/delegate-task/ — Task Delegation Engine

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW

@@ -0,0 +1,92 @@
+# src/tools/hashline-edit/ — Hash-Anchored File Edit Tool
+
+**Generated:** 2026-02-24
+
+## OVERVIEW
+
+24 files. Implements the `hashline_edit` tool — hash-anchored file editing where every line reference includes a content hash (`LINE#ID`). Validates hashes before applying edits, rejecting stale references.
+
+## THREE-OP MODEL
+
+All edits use exactly 3 operations:
+
+| Op | pos | end | lines | Effect |
+|----|-----|-----|-------|--------|
+| `replace` | required | optional | required | Replace single line or range pos..end |
+| `append` | optional | optional | required | Insert after anchor (or EOF if no anchor) |
+| `prepend` | optional | optional | required | Insert before anchor (or BOF if no anchor) |
+
+`lines: null` or `lines: []` with `replace` = delete. `delete: true` at tool level = delete file.
+
+## EXECUTION PIPELINE
+
+```
+hashline-edit-executor.ts
+  → normalize-edits.ts       # Parse RawHashlineEdit → HashlineEdit (validate op schema)
+  → validation.ts            # Validate LINE#ID references (hash match, line exists)
+  → edit-ordering.ts         # Sort bottom-up (by line number, descending)
+  → edit-deduplication.ts    # Remove duplicate ops
+  → edit-operations.ts       # Apply each op using edit-operation-primitives.ts
+  → autocorrect-replacement-lines.ts  # Auto-fix indentation/formatting
+  → hashline-edit-diff.ts    # Build diff output using diff-utils.ts
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `tools.ts` | `createHashlineEditTool()` factory — tool schema + entry point |
+| `hashline-edit-executor.ts` | Main execution: normalize → validate → order → apply → diff |
+| `normalize-edits.ts` | Parse `RawHashlineEdit[]` (allows string `op` variants) → typed `HashlineEdit[]` |
+| `validation.ts` | Validate LINE#ID: parse hash, verify line content matches stored hash |
+| `hash-computation.ts` | `computeLineHash(line)` → 2-char CID from set `ZPMQVRWSNKTXJBYH` |
+| `edit-operations.ts` | Apply replace/append/prepend to file lines array |
+| `edit-operation-primitives.ts` | Low-level line array mutation primitives |
+| `edit-ordering.ts` | Sort edits bottom-up to preserve line numbers during multi-edit |
+| `edit-deduplication.ts` | Deduplicate overlapping/identical operations |
+| `edit-text-normalization.ts` | Normalize line content (CRLF, BOM, trailing whitespace) |
+| `file-text-canonicalization.ts` | Canonicalize full file content before hashing |
+| `autocorrect-replacement-lines.ts` | Auto-restore indentation from original lines |
+| `hashline-edit-diff.ts` | Generate unified diff for error/success messages |
+| `diff-utils.ts` | Thin wrapper around `diff` npm library |
+| `hashline-chunk-formatter.ts` | Format line chunks with `LINE#ID` tags |
+| `tool-description.ts` | `HASHLINE_EDIT_DESCRIPTION` constant |
+| `types.ts` | `HashlineEdit`, `ReplaceEdit`, `AppendEdit`, `PrependEdit` |
+| `constants.ts` | Hash alphabet, separator character (`#`), pipe separator (`|`) |
+
+## LINE#ID FORMAT
+
+```
+{line_number}#{hash_id}
+```
+
+- `hash_id`: two chars from `ZPMQVRWSNKTXJBYH` (CID letters)
+- Example: `42#VK` means line 42 with hash `VK`
+- Validation: recompute hash of current line content → must match stored hash
+- Content separator: `|` (pipe) between hash tag and content in read output
+
+## AUTOCORRECT BEHAVIORS (built-in)
+
+- Merged lines auto-expanded back to original count
+- Indentation restored from original lines
+- BOM and CRLF line endings preserved
+- `>>>` prefix and diff markers in `lines` text auto-stripped
+
+## ERROR CASES
+
+- Hash mismatch → edit rejected, diff shown with current state
+- Overlapping ranges → detected and rejected
+- Missing `pos` for `replace` → schema error
+- `lines: null` with `append`/`prepend` → schema error
+
+## HOW LINE HASHES WORK
+
+```typescript
+// Reading: every line gets tagged
+"42#VK| function hello() {"
+
+// Editing: reference by tag
+{ op: "replace", pos: "42#VK", lines: "function hello(name: string) {" }
+
+// If file changed since read: hash won't match → rejected before corruption
+```
@@ -1,6 +1,6 @@
 # src/tools/lsp/ — LSP Tool Implementations

-**Generated:** 2026-02-21
+**Generated:** 2026-02-24

 ## OVERVIEW