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 · 2026-02-25 00:02:05 +09:00 · 73453a7191
commit 73453a7191
parent fcb90d92a4
33 changed files with 206 additions and 51 deletions
--- a/.issue-comment-2064.md
+++ b/.issue-comment-2064.md
@ -0,0 +1,61 @@
+[sisyphus-bot] 
+
+## Confirmed Bug
+
+We have identified the root cause of this issue. The bug is in the config writing logic during installation.
+
+### Root Cause
+
+**File:** `src/cli/config-manager/write-omo-config.ts` (line 46)
+
+```typescript
+const merged = deepMergeRecord(existing, newConfig)
+```
+
+When a user runs `oh-my-opencode install` (even just to update settings), the installer:
+1. Reads the existing config (with user's custom model settings)
+2. Generates a **new** config based on detected provider availability
+3. Calls `deepMergeRecord(existing, newConfig)` 
+4. Writes the result back
+
+**The problem:** `deepMergeRecord` overwrites values in `existing` with values from `newConfig`. This means your custom `"model": "openai/gpt-5.2-codex"` gets overwritten by the generated default model (e.g., `anthropic/claude-opus-4-6` if Claude is available).
+
+### Why This Happens
+
+Looking at `deepMergeRecord` (line 24-25):
+```typescript
+} else if (sourceValue !== undefined) {
+  result[key] = sourceValue as TTarget[keyof TTarget]
+}
+```
+
+Any defined value in the source (generated config) overwrites the target (user's config).
+
+### Fix Approach
+
+The merge direction should be reversed to respect user overrides:
+```typescript
+const merged = deepMergeRecord(newConfig, existing)
+```
+
+This ensures:
+- User's explicit settings take precedence
+- Only new/undefined keys get populated from generated defaults
+- Custom model choices are preserved
+
+### SEVERITY: HIGH
+
+- **Impact:** User configuration is overwritten without consent
+- **Affected Files:** 
+  - `src/cli/config-manager/write-omo-config.ts`
+  - `src/cli/config-manager/deep-merge-record.ts`
+- **Trigger:** Running `oh-my-opencode install` (even for unrelated updates)
+
+### Workaround (Until Fix)
+
+Backup your config before running install:
+```bash
+cp ~/.config/opencode/oh-my-opencode.jsonc ~/.config/opencode/oh-my-opencode.jsonc.backup
+```
+
+We're working on a fix that will preserve your explicit model configurations.
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,10 +1,10 @@
 # oh-my-opencode — OpenCode Plugin

-**Generated:** 2026-02-21 | **Commit:** 86e3c7d1 | **Branch:** dev
+**Generated:** 2026-02-24 | **Commit:** fcb90d92 | **Branch:** dev

 ## OVERVIEW

-OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 44 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1208 TypeScript files, 143k LOC.
+OpenCode plugin (npm: `oh-my-opencode`) that extends Claude Code (OpenCode fork) with multi-agent orchestration, 46 lifecycle hooks, 26 tools, skill/command/MCP systems, and Claude Code compatibility. 1208 TypeScript files, 143k LOC.

 ## STRUCTURE

@ -14,14 +14,14 @@ oh-my-opencode/
 │   ├── index.ts              # Plugin entry: loadConfig → createManagers → createTools → createHooks → createPluginInterface
 │   ├── plugin-config.ts      # JSONC multi-level config: user → project → defaults (Zod v4)
 │   ├── agents/               # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
-│   ├── hooks/                # 44 hooks across 39 directories + 6 standalone files
+| `hooks/`                # 46 hooks across 39 directories + 6 standalone files
 │   ├── tools/                # 26 tools across 15 directories
 │   ├── features/             # 19 feature modules (background-agent, skill-loader, tmux, MCP-OAuth, etc.)
 │   ├── shared/               # 100+ utility files in 13 categories
 │   ├── config/               # Zod v4 schema system (22+ files)
 │   ├── cli/                  # CLI: install, run, doctor, mcp-oauth (Commander.js)
 │   ├── mcp/                  # 3 built-in remote MCPs (websearch, context7, grep_app)
-│   ├── plugin/               # 8 OpenCode hook handlers + 44 hook composition
+│   ├── plugin/               # 8 OpenCode hook handlers + 46 hook composition
 │   └── plugin-handlers/      # 6-phase config loading pipeline
 ├── packages/                 # Monorepo: comment-checker, opencode-sdk, 10 platform binaries
 └── local-ignore/             # Dev-only test fixtures
@ -34,7 +34,7 @@ OhMyOpenCodePlugin(ctx)
  ├─→ loadPluginConfig()         # JSONC parse → project/user merge → Zod validate → migrate
  ├─→ createManagers()           # TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
  ├─→ createTools()              # SkillContext + AvailableCategories + ToolRegistry (26 tools)
-  ├─→ createHooks()              # 3-tier: Core(35) + Continuation(7) + Skill(2) = 44 hooks
+  ├─→ createHooks()              # 3-tier: Core(37) + Continuation(7) + Skill(2) = 46 hooks
  └─→ createPluginInterface()    # 8 OpenCode hook handlers → PluginInterface
 ```

@ -87,7 +87,7 @@ Fields: agents (14 overridable, 21 fields each), categories (8 built-in + custom

 - **Test pattern**: Bun test (`bun:test`), co-located `*.test.ts`, given/when/then style (nested describe with `#given`/`#when`/`#then` prefixes)
 - **Factory pattern**: `createXXX()` for all tools, hooks, agents
- **Hook tiers**: Session (22) → Tool-Guard (10) → Transform (4) → Continuation (7) → Skill (2)
+- **Hook tiers**: Session (23) → Tool-Guard (10) → Transform (4) → Continuation (7) → Skill (2)
 - **Agent modes**: `primary` (respects UI model) vs `subagent` (own fallback chain) vs `all`
 - **Model resolution**: 3-step: override → category-default → provider-fallback → system-default
 - **Config format**: JSONC with comments, Zod v4 validation, snake_case keys
--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@ -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
--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@ -1,6 +1,6 @@
 # src/agents/ — 11 Agent Definitions

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

 ## OVERVIEW

--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth

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

 ## OVERVIEW

--- a/src/cli/config-manager/AGENTS.md
+++ b/src/cli/config-manager/AGENTS.md
@ -1,6 +1,6 @@
 # src/cli/config-manager/ — CLI Installation Utilities

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

 ## OVERVIEW

--- a/src/cli/run/AGENTS.md
+++ b/src/cli/run/AGENTS.md
@ -1,6 +1,6 @@
 # src/cli/run/ — Non-Interactive Session Launcher

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

 ## OVERVIEW

--- a/src/config/AGENTS.md
+++ b/src/config/AGENTS.md
@ -1,6 +1,6 @@
 # src/config/ — Zod v4 Schema System

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

 ## OVERVIEW

--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@ -1,6 +1,6 @@
 # src/features/ — 19 Feature Modules

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

 ## OVERVIEW

--- a/src/features/background-agent/AGENTS.md
+++ b/src/features/background-agent/AGENTS.md
@ -1,6 +1,6 @@
 # src/features/background-agent/ — Core Orchestration Engine

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

 ## OVERVIEW

--- a/src/features/claude-tasks/AGENTS.md
+++ b/src/features/claude-tasks/AGENTS.md
@ -1,6 +1,6 @@
 # src/features/claude-tasks/ — Task Schema + Storage

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

 ## OVERVIEW

--- a/src/features/mcp-oauth/AGENTS.md
+++ b/src/features/mcp-oauth/AGENTS.md
@ -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

--- a/src/features/opencode-skill-loader/AGENTS.md
+++ b/src/features/opencode-skill-loader/AGENTS.md
@ -1,6 +1,6 @@
 # src/features/opencode-skill-loader/ — 4-Scope Skill Discovery

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

 ## OVERVIEW

--- a/src/features/tmux-subagent/AGENTS.md
+++ b/src/features/tmux-subagent/AGENTS.md
@ -1,6 +1,6 @@
 # src/features/tmux-subagent/ — Tmux Pane Management

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

 ## OVERVIEW

--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@ -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`

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

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

 ## OVERVIEW

--- a/src/hooks/atlas/AGENTS.md
+++ b/src/hooks/atlas/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator

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

 ## OVERVIEW

--- a/src/hooks/claude-code-hooks/AGENTS.md
+++ b/src/hooks/claude-code-hooks/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility

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

 ## OVERVIEW

--- a/src/hooks/keyword-detector/AGENTS.md
+++ b/src/hooks/keyword-detector/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/keyword-detector/ — Mode Keyword Injection

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

 ## OVERVIEW

--- a/src/hooks/ralph-loop/AGENTS.md
+++ b/src/hooks/ralph-loop/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/ralph-loop/ — Self-Referential Dev Loop

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

 ## OVERVIEW

--- a/src/hooks/rules-injector/AGENTS.md
+++ b/src/hooks/rules-injector/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/rules-injector/ — Conditional Rules Injection

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

 ## OVERVIEW

--- a/src/hooks/session-recovery/AGENTS.md
+++ b/src/hooks/session-recovery/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/session-recovery/ — Auto Session Error Recovery

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

 ## OVERVIEW

--- a/src/hooks/todo-continuation-enforcer/AGENTS.md
+++ b/src/hooks/todo-continuation-enforcer/AGENTS.md
@ -1,6 +1,6 @@
 # src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism

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

 ## OVERVIEW

--- a/src/mcp/AGENTS.md
+++ b/src/mcp/AGENTS.md
@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs

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

 ## OVERVIEW

--- a/src/plugin-handlers/AGENTS.md
+++ b/src/plugin-handlers/AGENTS.md
@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline

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

 ## OVERVIEW

--- a/src/plugin/AGENTS.md
+++ b/src/plugin/AGENTS.md
@ -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

--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@ -1,6 +1,6 @@
 # src/shared/ — 101 Utility Files in 13 Categories

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

 ## OVERVIEW

--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@ -1,6 +1,6 @@
 # src/tools/ — 26 Tools Across 15 Directories

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

 ## OVERVIEW

--- a/src/tools/background-task/AGENTS.md
+++ b/src/tools/background-task/AGENTS.md
@ -1,6 +1,6 @@
 # src/tools/background-task/ — Background Task Tool Wrappers

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

 ## OVERVIEW

--- a/src/tools/call-omo-agent/AGENTS.md
+++ b/src/tools/call-omo-agent/AGENTS.md
@ -1,6 +1,6 @@
 # src/tools/call-omo-agent/ — Direct Agent Invocation Tool

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

 ## OVERVIEW

--- a/src/tools/delegate-task/AGENTS.md
+++ b/src/tools/delegate-task/AGENTS.md
@ -1,6 +1,6 @@
 # src/tools/delegate-task/ — Task Delegation Engine

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

 ## OVERVIEW

--- a/src/tools/hashline-edit/AGENTS.md
+++ b/src/tools/hashline-edit/AGENTS.md
@ -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
+```
--- a/src/tools/lsp/AGENTS.md
+++ b/src/tools/lsp/AGENTS.md
@ -1,6 +1,6 @@
 # src/tools/lsp/ — LSP Tool Implementations

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

 ## OVERVIEW