From 73453a7191b4f417dcb76ff3f68bbaeddedee210 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 25 Feb 2026 00:02:05 +0900 Subject: [PATCH] =?UTF-8?q?docs(agents):=20update=20hook=20counts=2044?= =?UTF-8?q?=E2=86=9246,=20add=20hashline-edit=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- .issue-comment-2064.md | 61 ++++++++++++ AGENTS.md | 12 +-- src/AGENTS.md | 10 +- src/agents/AGENTS.md | 2 +- src/cli/AGENTS.md | 2 +- src/cli/config-manager/AGENTS.md | 2 +- src/cli/run/AGENTS.md | 2 +- src/config/AGENTS.md | 2 +- src/features/AGENTS.md | 2 +- src/features/background-agent/AGENTS.md | 2 +- src/features/claude-tasks/AGENTS.md | 2 +- src/features/mcp-oauth/AGENTS.md | 2 +- src/features/opencode-skill-loader/AGENTS.md | 2 +- src/features/tmux-subagent/AGENTS.md | 2 +- src/hooks/AGENTS.md | 18 ++-- .../AGENTS.md | 2 +- src/hooks/atlas/AGENTS.md | 2 +- src/hooks/claude-code-hooks/AGENTS.md | 2 +- src/hooks/keyword-detector/AGENTS.md | 2 +- src/hooks/ralph-loop/AGENTS.md | 2 +- src/hooks/rules-injector/AGENTS.md | 2 +- src/hooks/session-recovery/AGENTS.md | 2 +- .../todo-continuation-enforcer/AGENTS.md | 2 +- src/mcp/AGENTS.md | 2 +- src/plugin-handlers/AGENTS.md | 2 +- src/plugin/AGENTS.md | 10 +- src/shared/AGENTS.md | 2 +- src/tools/AGENTS.md | 2 +- src/tools/background-task/AGENTS.md | 2 +- src/tools/call-omo-agent/AGENTS.md | 2 +- src/tools/delegate-task/AGENTS.md | 2 +- src/tools/hashline-edit/AGENTS.md | 92 +++++++++++++++++++ src/tools/lsp/AGENTS.md | 2 +- 33 files changed, 206 insertions(+), 51 deletions(-) create mode 100644 .issue-comment-2064.md create mode 100644 src/tools/hashline-edit/AGENTS.md diff --git a/.issue-comment-2064.md b/.issue-comment-2064.md new file mode 100644 index 00000000..39a6f486 --- /dev/null +++ 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. diff --git a/AGENTS.md b/AGENTS.md index 45d8a26b..c138c4ca 100644 --- 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 diff --git a/src/AGENTS.md b/src/AGENTS.md index 793ab83c..197af269 100644 --- 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 diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index 6e282849..289a0fca 100644 --- 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 diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index 19e6500e..1cdb7fe5 100644 --- 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 diff --git a/src/cli/config-manager/AGENTS.md b/src/cli/config-manager/AGENTS.md index cff4da29..45e3d2d1 100644 --- 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 diff --git a/src/cli/run/AGENTS.md b/src/cli/run/AGENTS.md index 5df64053..4f9fb2ec 100644 --- 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 diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md index 64b75c2e..83a8830a 100644 --- 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 diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 7d01ecda..cec212e5 100644 --- 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 diff --git a/src/features/background-agent/AGENTS.md b/src/features/background-agent/AGENTS.md index 29802126..0b4b18ec 100644 --- 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 diff --git a/src/features/claude-tasks/AGENTS.md b/src/features/claude-tasks/AGENTS.md index 4cb70304..25d00ae0 100644 --- 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 diff --git a/src/features/mcp-oauth/AGENTS.md b/src/features/mcp-oauth/AGENTS.md index 23df309f..97f017c2 100644 --- 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 diff --git a/src/features/opencode-skill-loader/AGENTS.md b/src/features/opencode-skill-loader/AGENTS.md index 968da2e4..5c617673 100644 --- 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 diff --git a/src/features/tmux-subagent/AGENTS.md b/src/features/tmux-subagent/AGENTS.md index 27a7968f..69e8ccfa 100644 --- 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 diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 54dbbc8d..6e22ff9b 100644 --- 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` diff --git a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md index c760d6ba..0234760e 100644 --- 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 diff --git a/src/hooks/atlas/AGENTS.md b/src/hooks/atlas/AGENTS.md index 47a65213..e0c435e2 100644 --- 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 diff --git a/src/hooks/claude-code-hooks/AGENTS.md b/src/hooks/claude-code-hooks/AGENTS.md index cffba532..03b88a73 100644 --- 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 diff --git a/src/hooks/keyword-detector/AGENTS.md b/src/hooks/keyword-detector/AGENTS.md index 7670702b..34f08118 100644 --- 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 diff --git a/src/hooks/ralph-loop/AGENTS.md b/src/hooks/ralph-loop/AGENTS.md index 1162c1f1..7e35f437 100644 --- 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 diff --git a/src/hooks/rules-injector/AGENTS.md b/src/hooks/rules-injector/AGENTS.md index ddaecb62..c43c66b3 100644 --- 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 diff --git a/src/hooks/session-recovery/AGENTS.md b/src/hooks/session-recovery/AGENTS.md index 8c8cb1ba..3959b41c 100644 --- 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 diff --git a/src/hooks/todo-continuation-enforcer/AGENTS.md b/src/hooks/todo-continuation-enforcer/AGENTS.md index 928fabf2..6f0166b6 100644 --- 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 diff --git a/src/mcp/AGENTS.md b/src/mcp/AGENTS.md index f600425d..cb230480 100644 --- 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 diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index 2fcfeeb2..844242bd 100644 --- 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 diff --git a/src/plugin/AGENTS.md b/src/plugin/AGENTS.md index d9697d8e..a3aa2024 100644 --- 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 diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index 1c072797..2cc20f9b 100644 --- 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 diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 6c8d2809..2604ad9e 100644 --- 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 diff --git a/src/tools/background-task/AGENTS.md b/src/tools/background-task/AGENTS.md index 5243b3af..bdf486fe 100644 --- 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 diff --git a/src/tools/call-omo-agent/AGENTS.md b/src/tools/call-omo-agent/AGENTS.md index 1bb73b7c..adbe35fe 100644 --- 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 diff --git a/src/tools/delegate-task/AGENTS.md b/src/tools/delegate-task/AGENTS.md index d94cb0a5..8f533426 100644 --- 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 diff --git a/src/tools/hashline-edit/AGENTS.md b/src/tools/hashline-edit/AGENTS.md new file mode 100644 index 00000000..3054b21d --- /dev/null +++ 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 +``` diff --git a/src/tools/lsp/AGENTS.md b/src/tools/lsp/AGENTS.md index 5fcc7d7e..13968fff 100644 --- 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