release: v0.3.3

* feat(agents): enhance librarian and explore prompts with parallel execution and evidence-based citations

Librarian agent enhancements:
- Add mandatory 5+ parallel tool execution requirement
- Add WebSearch integration for latest information
- Add repository cloning to /tmp for deep source analysis
- Require GitHub permalinks for all code citations
- Add evidence-based reasoning with specific code references
- Enhanced gh CLI usage with permalink construction

Explore agent enhancements:
- Add mandatory 3+ parallel tool execution requirement
- Extensive Git CLI integration for repository analysis
- Add git log, git blame, git diff commands for exploration
- Add parallel execution examples and best practices

* feat(agents): add LSP and AST-grep tools to librarian and explore prompts

Librarian agent:
- Added LSP tools section (lsp_hover, lsp_goto_definition, lsp_find_references, etc.)
- Added AST-grep section with pattern examples for structural code search
- Updated parallel execution examples to include LSP and AST-grep tools
- Added guidance on when to use AST-grep vs Grep vs LSP

Explore agent:
- Added LSP tools section for semantic code analysis
- Added AST-grep section with examples for TypeScript/React patterns
- Updated parallel execution examples to include 6 tools
- Added tool selection guidance for LSP and AST-grep

* fix(agents): remove explore agent references from librarian prompt

Subagents cannot call other agents, so replaced all Explore agent
references with direct tool usage (Glob, Grep, ast_grep_search).

---------

Co-authored-by: Claude <noreply@anthropic.com>

AGENTS.md

@@ -65,7 +65,7 @@ oh-my-opencode/
 
 | Agent | Model | Purpose |
 |-------|-------|---------|
-| oracle | GPT-5.1 | Code review, strategic planning |
+| oracle | GPT-5.2 | Code review, strategic planning |
 | librarian | Claude Haiku | Documentation, example lookup |
 | explore | Grok | File/codebase exploration |
 | frontend-ui-ux-engineer | Gemini | UI generation |
@@ -84,9 +84,31 @@ bun run build
 bun run rebuild
 ```
 
+## DEPLOYMENT
+
+**배포는 GitHub Actions workflow_dispatch로만 진행**
+
+1. package.json 버전은 수정하지 않음 (워크플로우에서 자동 bump)
+2. 변경사항 커밋 & 푸시
+3. GitHub Actions에서 `publish` 워크플로우 수동 실행
+   - `bump`: major | minor | patch 선택
+   - `version`: (선택) 특정 버전 지정 가능
+
+```bash
+# 워크플로우 실행 (CLI)
+gh workflow run publish -f bump=patch
+
+# 워크플로우 상태 확인
+gh run list --workflow=publish
+```
+
+**주의사항**:
+- `bun publish` 직접 실행 금지 (OIDC provenance 문제)
+- 로컬에서 버전 bump 하지 말 것
+
 ## NOTES
 
 - **No tests**: Test framework not configured
-- **No CI/CD**: GitHub workflows not present
+- **CI/CD**: GitHub Actions publish workflow 사용
 - **Version requirement**: OpenCode >= 1.0.132 (earlier versions have config bugs)
 - **Multi-language docs**: README.md, README.en.md, README.ko.md

README.ko.md

@@ -3,18 +3,21 @@
 ## 목차
 
 - [Oh My OpenCode](#oh-my-opencode)
-  - [설치](#설치)
   - [세 줄 요약](#세-줄-요약)
-  - [Why OpenCode \& Why Oh My OpenCode](#why-opencode--why-oh-my-opencode)
+  - [설치](#설치)
+  - [LLM Agent를 위한 안내](#llm-agent를-위한-안내)
+  - [Why OpenCode & Why Oh My OpenCode](#why-opencode--why-oh-my-opencode)
   - [기능](#기능)
     - [Hooks](#hooks)
     - [Agents](#agents)
     - [Tools](#tools)
       - [내장 LSP Tools](#내장-lsp-tools)
       - [내장 AST-Grep Tools](#내장-ast-grep-tools)
-      - [Safe Grep](#safe-grep)
+      - [Grep](#grep)
       - [내장 MCPs](#내장-mcps)
+    - [Claude Code 호환성](#claude-code-호환성)
     - [기타 편의 기능](#기타-편의-기능)
+  - [설정](#설정)
   - [작성자의 노트](#작성자의-노트)
   - [주의](#주의)
 
@@ -33,6 +36,17 @@ OpenCode 가 낭만이 사라진것같은 오늘날의 시대에, 당신에게
 당신이 코딩을 좋아하고 컴퓨터를 좋아한다면, OpenCode 는 윈도우만 사용하다가 리눅스를 처음 접하게 된 그런 느낌일겁니다.
 그렇지 않은 당신도 약간의 시간을 투자해서 당신의 실력과 생산성을 몇배로 부스트하세요.
 
+## 세 줄 요약
+
+- **모델 설정이 필요합니다**
+  - 이 플러그인은 [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, Anthropic 의 모델을 사용합니다.
+    - Anthropic 모델들을 사용하기 위해 [OpenCode 의 내장 Claude Code Max Plan 로그인 기능](https://opencode.ai/docs/providers/#anthropic)을 사용하세요. (Anthropic 플랜은 유료입니다)
+    - OpenAI 모델들을 사용하기 위해 이 [OpenCode-OpenAI-Codex-Auth 플러그인](https://github.com/numman-ali/opencode-openai-codex-auth)을 추천합니다. (OpenAI 플랜은 유료입니다)
+    - Gemini, GPT 를 위해 [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) 또는 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)를 추천합니다. (Gemini 는 구독하지 않아도 사용 할 수 있습니다)
+- **사실 밑의 내용은 읽지 않아도 됩니다. 그냥 설치하시면 됩니다. 모델 설정하고나면 추가로 공부하거나 알 필요가 없고, 설치하고 나면 그냥 더 좋아집니다.**
+- **이 문서도 그냥 Claude Code, OpenCode, Cursor에 붙여넣고, 설치하고, 사용자의 개입이 필요할 때 알려달라고 프롬프팅하세요. 그럼 그냥 깔립니다.**
+  - 당신이 LLM Agent 라면, 필요한 플러그인과 의존성을 설치하고, tmux 를 통해 opencode auth login 을 실행하여 사용자의 구성을 도와주세요.
+
 ## 설치
 
 `~/.config/opencode/opencode.json`에 추가:
@@ -45,16 +59,68 @@ OpenCode 가 낭만이 사라진것같은 오늘날의 시대에, 당신에게
 }
 ```
 
-## 세 줄 요약
+## LLM Agent를 위한 안내
 
-- **모델 설정이 필요합니다**
-  - 이 플러그인은 [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, Anthropic 의 모델을 사용합니다.
-    - Anthropic 모델들을 사용하기 위해 [OpenCode 의 내장 Claude Code Max Plan 로그인 기능](https://opencode.ai/docs/providers/#anthropic)을 사용하세요. (Anthropic 플랜은 유료입니다)
-    - OpenAI 모델들을 사용하기 위해 이 [OpenCode-OpenAI-Codex-Auth 플러그인](https://github.com/numman-ali/opencode-openai-codex-auth)을 추천합니다. (OpenAI 플랜은 유료입니다)
-    - Gemini, GPT 를 위해 [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) 또는 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)를 추천합니다. (Gemini 는 구독하지 않아도 사용 할 수 있습니다)
-- **사실 밑의 내용은 읽지 않아도 됩니다. 그냥 설치하시면 됩니다. 모델 설정하고나면 추가로 공부하거나 알 필요가 없고, 설치하고 나면 그냥 더 좋아집니다.**
-- **이 문서도 그냥 Claude Code, OpenCode, Cursor에 붙여넣고, 설치하고, 사용자의 개입이 필요할 때 알려달라고 프롬프팅하세요. 그럼 그냥 깔립니다.**
-  - 당신이 LLM Agent 라면, 필요한 플러그인과 의존성을 설치하고, tmux 를 통해 opencode auth login 을 실행하여 사용자의 구성을 도와주세요.
+<details>
+<summary>LLM Agent를 위한 안내 (클릭하여 펼치기)</summary>
+
+당신이 사용자의 oh-my-opencode 설정을 돕는 LLM Agent라면, 다음 단계를 따르세요:
+
+### 1단계: OpenCode 설치 확인
+
+```bash
+if command -v opencode &> /dev/null; then
+    echo "OpenCode $(opencode --version) 설치됨"
+else
+    echo "OpenCode가 설치되어 있지 않습니다. 먼저 설치해주세요."
+    echo "참고: https://opencode.ai/docs"
+fi
+```
+
+OpenCode가 설치되어 있지 않다면, [OpenCode 설치 가이드](https://opencode.ai/docs)를 안내하세요.
+
+### 2단계: oh-my-opencode 플러그인 설정
+
+```bash
+mkdir -p ~/.config/opencode
+
+if [ -f ~/.config/opencode/opencode.json ]; then
+    # 기존 설정 파일이 있는 경우: jq 또는 python으로 plugin 추가
+    if command -v jq &> /dev/null; then
+        jq '.plugin = ((.plugin // []) + ["oh-my-opencode"] | unique)' \
+            ~/.config/opencode/opencode.json > /tmp/oc.json && \
+            mv /tmp/oc.json ~/.config/opencode/opencode.json
+    else
+        echo "~/.config/opencode/opencode.json의 plugin 배열에 \"oh-my-opencode\"를 추가하세요"
+    fi
+else
+    # 새 설정 파일 생성
+    echo '{"plugin":["oh-my-opencode"]}' > ~/.config/opencode/opencode.json
+fi
+```
+
+### 3단계: 설정 확인
+
+```bash
+opencode --version  # 1.0.132 이상이어야 함
+cat ~/.config/opencode/opencode.json  # plugin 배열에 "oh-my-opencode"가 있어야 함
+```
+
+### 4단계: 인증정보 설정
+
+plugin 에 oh my opencode 를 추가했다면, tmux 를 사용하여 다음의 내용을 진행주세요.
+
+1. tmux 를 사용하여 셸 열기
+2. opencode auth login > Provider Anthropic > Login method Claude Pro/Max > 사용자에게 oauth 화면에서 인증하라고 안내
+3. 사용자에게 macOS 일 경우 VibeProxy, 아닐 경우 CLIProxyAPI 를 사용하여 OpenAI / Google 인증을 완료하라고 안내
+
+### ⚠️ 주의
+
+**사용자가 명시적으로 요청하지 않는 한, `oh-my-opencode.json` 설정 파일을 생성하거나 수정하지 마세요.**
+
+플러그인은 설정 파일 없이도 기본값으로 완벽하게 동작합니다. 설정 파일은 사용자가 커스터마이징을 원할 때만 필요합니다.
+
+</details>
 
 ## Why OpenCode & Why Oh My OpenCode
 
@@ -83,20 +149,53 @@ OpenCode 는 아주 확장가능하고 아주 커스터마이저블합니다.
 - **Context Window Monitor**: [컨텍스트 윈도우 불안 관리](https://agentic-patterns.com/patterns/context-window-anxiety-management/) 패턴을 구현합니다.
   - 사용량이 70%를 넘으면 에이전트에게 아직 토큰이 충분하다고 상기시켜, 급하게 불완전한 작업을 하는 것을 완화합니다.
 - **Session Notification**: 에이전트가 작업을 마치면 OS 네이티브 알림을 보냅니다 (macOS, Linux, Windows).
+- **Session Recovery**: API 에러로부터 자동으로 복구하여 세션 안정성을 보장합니다. 네 가지 시나리오를 처리합니다:
+  - **Tool Result Missing**: `tool_use` 블록이 있지만 `tool_result`가 없을 때 (ESC 인터럽트) → "cancelled" tool result 주입
+  - **Thinking Block Order**: thinking 블록이 첫 번째여야 하는데 아닐 때 → 빈 thinking 블록 추가
+  - **Thinking Disabled Violation**: thinking 이 비활성화인데 thinking 블록이 있을 때 → thinking 블록 제거
+  - **Empty Content Message**: 메시지가 thinking/meta 블록만 있고 실제 내용이 없을 때 → 파일시스템을 통해 "(interrupted)" 텍스트 주입
 - **Comment Checker**: 코드 수정 후 불필요한 주석을 감지하여 보고합니다. BDD 패턴, 지시어, 독스트링 등 유효한 주석은 똑똑하게 제외하고, AI가 남긴 흔적을 제거하여 코드를 깨끗하게 유지합니다.
+- **Directory AGENTS.md Injector**: 파일을 읽을 때 `AGENTS.md` 내용을 자동으로 주입합니다. 파일 디렉토리부터 프로젝트 루트까지 탐색하며, 경로 상의 **모든** `AGENTS.md` 파일을 수집합니다. 중첩된 디렉토리별 지침을 지원합니다:
+  ```
+  project/
+  ├── AGENTS.md              # 프로젝트 전체 컨텍스트
+  ├── src/
+  │   ├── AGENTS.md          # src 전용 컨텍스트
+  │   └── components/
+  │       ├── AGENTS.md      # 컴포넌트 전용 컨텍스트
+  │       └── Button.tsx     # 이 파일을 읽으면 위 3개 AGENTS.md 모두 주입
+  ```
+  `Button.tsx`를 읽으면 순서대로 주입됩니다: `project/AGENTS.md` → `src/AGENTS.md` → `components/AGENTS.md`. 각 디렉토리의 컨텍스트는 세션당 한 번만 주입됩니다. Claude Code의 CLAUDE.md 기능에서 영감을 받았습니다.
+- **Directory README.md Injector**: 파일을 읽을 때 `README.md` 내용을 자동으로 주입합니다. AGENTS.md Injector와 동일하게 동작하며, 파일 디렉토리부터 프로젝트 루트까지 탐색합니다. LLM 에이전트에게 프로젝트 문서 컨텍스트를 제공합니다. 각 디렉토리의 README는 세션당 한 번만 주입됩니다.
+- **Think Mode**: 확장된 사고(Extended Thinking)가 필요한 상황을 자동으로 감지하고 모드를 전환합니다. 사용자가 깊은 사고를 요청하는 표현(예: "think deeply", "ultrathink")을 감지하면, 추론 능력을 극대화하도록 모델 설정을 동적으로 조정합니다.
+- **Anthropic Auto Compact**: Anthropic 모델 사용 시 컨텍스트 한계에 도달하면 대화 기록을 자동으로 압축하여 효율적으로 관리합니다.
+- **Empty Task Response Detector**: 서브 에이전트가 수행한 작업이 비어있거나 무의미한 응답을 반환하는 경우를 감지하여, 오류 없이 우아하게 처리합니다.
+- **Grep Output Truncator**: Grep 검색 결과가 너무 길어 컨텍스트를 장악해버리는 것을 방지하기 위해, 과도한 출력을 자동으로 자릅니다.
 
 ### Agents
 
-- **oracle** (`openai/gpt-5.1`): 아키텍처, 코드 리뷰, 전략 수립을 위한 전문가 조언자. GPT-5.1의 뛰어난 논리적 추론과 깊은 분석 능력을 활용합니다. AmpCode 에서 영감을 받았습니다.
+- **oracle** (`openai/gpt-5.2`): 아키텍처, 코드 리뷰, 전략 수립을 위한 전문가 조언자. GPT-5.2의 뛰어난 논리적 추론과 깊은 분석 능력을 활용합니다. AmpCode 에서 영감을 받았습니다.
 - **librarian** (`anthropic/claude-haiku-4-5`): 멀티 레포 분석, 문서 조회, 구현 예제 담당. Haiku의 빠른 속도, 적절한 지능, 훌륭한 도구 호출 능력, 저렴한 비용을 활용합니다. AmpCode 에서 영감을 받았습니다.
 - **explore** (`opencode/grok-code`): 빠른 코드베이스 탐색, 파일 패턴 매칭. Claude Code는 Haiku를 쓰지만, 우리는 Grok을 씁니다. 현재 무료이고, 극도로 빠르며, 파일 탐색 작업에 충분한 지능을 갖췄기 때문입니다. Claude Code 에서 영감을 받았습니다.
 - **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): 개발자로 전향한 디자이너라는 설정을 갖고 있습니다. 멋진 UI를 만듭니다. 아름답고 창의적인 UI 코드를 생성하는 데 탁월한 Gemini를 사용합니다.
 - **document-writer** (`google/gemini-3-pro-preview`): 기술 문서 전문가라는 설정을 갖고 있습니다. Gemini 는 문학가입니다. 글을 기가막히게 씁니다.
 
+각 에이전트는 메인 에이전트가 알아서 호출하지만, 명시적으로 요청할 수도 있습니다:
+
+```
+@oracle 한테 이 부분 설계 고민하고서 아키텍쳐 제안을 부탁해줘
+@librarian 한테 이 부분 어떻게 구현돼있길래 자꾸 안에서 동작이 바뀌는지 알려달라고 해줘
+@explore 한테 이 기능 정책 알려달라고 해줘
+```
+
+에이전트의 모델, 프롬프트, 권한은 `oh-my-opencode.json`에서 커스텀할 수 있습니다. 자세한 내용은 [설정](#설정)을 참고하세요.
+
 ### Tools
 
 #### 내장 LSP Tools
 
+당신이 에디터에서 사용하는 그 기능을 다른 에이전트들은 사용하지 못합니다. Oh My OpenCode 는 당신만의 그 도구를 LLM Agent 에게 쥐어줍니다. 리팩토링하고, 탐색하고, 분석하는 모든 작업을 OpenCode 의 설정값을 그대로 사용하여 지원합니다.
+
 [OpenCode 는 LSP 를 제공하지만](https://opencode.ai/docs/lsp/), 오로지 분석용으로만 제공합니다. 탐색과 리팩토링을 위한 도구는 OpenCode 와 동일한 스펙과 설정으로 Oh My OpenCode 가 제공합니다.
 
 - **lsp_hover**: 위치의 타입 정보, 문서, 시그니처 가져오기
@@ -115,18 +214,177 @@ OpenCode 는 아주 확장가능하고 아주 커스터마이저블합니다.
 - **ast_grep_search**: AST 인식 코드 패턴 검색 (25개 언어)
 - **ast_grep_replace**: AST 인식 코드 교체
 
-#### Safe Grep
-- **safe_grep**: 안전 제한이 있는 콘텐츠 검색 (5분 타임아웃, 10MB 출력 제한).
+#### Grep
+- **grep**: 안전 제한이 있는 콘텐츠 검색 (5분 타임아웃, 10MB 출력 제한). OpenCode의 내장 `grep` 도구를 대체합니다.
   - 기본 grep 도구는 시간제한이 걸려있지 않습니다. 대형 코드베이스에서 광범위한 패턴을 검색하면 CPU가 폭발하고 무한히 멈출 수 있습니다.
-  - safe_grep 은 timeout 과 더 엄격한 출력 제한을 적용합니다.
-  - **주의**: 기본 grep 도구는 Agent 를 햇갈리게 하지 않기 위해 비활성화됩니다. 그러나 SafeGrep 은 Grep 이 제공하는 모든 기능을 제공합니다.
+  - 이 도구는 엄격한 제한을 적용하며, 내장 `grep`을 완전히 대체합니다.
+
+#### Glob
+
+- **glob**: 타임아웃 보호가 있는 파일 패턴 매칭 (60초). OpenCode 내장 `glob` 도구를 대체합니다.
+  - 기본 `glob`은 타임아웃이 없습니다. ripgrep이 멈추면 무한정 대기합니다.
+  - 이 도구는 타임아웃을 강제하고 만료 시 프로세스를 종료합니다.
 
 #### 내장 MCPs
 
 - **websearch_exa**: Exa AI 웹 검색. 실시간 웹 검색과 콘텐츠 스크래핑을 수행합니다. 관련 웹사이트에서 LLM에 최적화된 컨텍스트를 반환합니다.
+- **context7**: 라이브러리 문서 조회. 정확한 코딩을 위해 최신 라이브러리 문서를 가져옵니다.
+
+필요 없다면 `oh-my-opencode.json`에서 비활성화할 수 있습니다:
+
+```json
+{
+  "disabled_mcps": ["websearch_exa"]
+}
+```
+
+### Claude Code 호환성
+
+Oh My OpenCode는 Claude Code 설정과 완벽하게 호환됩니다. Claude Code를 사용하셨다면, 기존 설정을 그대로 사용할 수 있습니다.
+
+#### Hooks 통합
+
+Claude Code의 `settings.json` 훅 시스템을 통해 커스텀 스크립트를 실행합니다. Oh My OpenCode는 다음 위치의 훅을 읽고 실행합니다:
+
+- `~/.claude/settings.json` (사용자)
+- `./.claude/settings.json` (프로젝트)
+- `./.claude/settings.local.json` (로컬, git-ignored)
+
+지원되는 훅 이벤트:
+- **PreToolUse**: 도구 실행 전에 실행. 차단하거나 도구 입력을 수정할 수 있습니다.
+- **PostToolUse**: 도구 실행 후에 실행. 경고나 컨텍스트를 추가할 수 있습니다.
+- **UserPromptSubmit**: 사용자가 프롬프트를 제출할 때 실행. 차단하거나 메시지를 주입할 수 있습니다.
+- **Stop**: 세션이 유휴 상태가 될 때 실행. 후속 프롬프트를 주입할 수 있습니다.
+
+`settings.json` 예시:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
+      }
+    ]
+  }
+}
+```
+
+#### 설정 로더
+
+**Command Loader**: 4개 디렉토리에서 마크다운 기반 슬래시 명령어를 로드합니다:
+- `~/.claude/commands/` (사용자)
+- `./.claude/commands/` (프로젝트)
+- `~/.config/opencode/command/` (opencode 전역)
+- `./.opencode/command/` (opencode 프로젝트)
+
+**Skill Loader**: `SKILL.md`가 있는 디렉토리 기반 스킬을 로드합니다:
+- `~/.claude/skills/` (사용자)
+- `./.claude/skills/` (프로젝트)
+
+**Agent Loader**: 마크다운 파일에서 커스텀 에이전트 정의를 로드합니다:
+- `~/.claude/agents/*.md` (사용자)
+- `./.claude/agents/*.md` (프로젝트)
+
+**MCP Loader**: `.mcp.json` 파일에서 MCP 서버 설정을 로드합니다:
+- `~/.claude/.mcp.json` (사용자)
+- `./.mcp.json` (프로젝트)
+- `./.claude/.mcp.json` (로컬)
+- 환경변수 확장 지원 (`${VAR}` 문법)
+
+#### 데이터 저장소
+
+**Todo 관리**: 세션 todo가 `~/.claude/todos/`에 Claude Code 호환 형식으로 저장됩니다.
+
+**Transcript**: 세션 활동이 `~/.claude/transcripts/`에 JSONL 형식으로 기록되어 재생 및 분석이 가능합니다.
+
+> **`claude-code-*` 네이밍에 대해**: `src/features/claude-code-*/` 아래의 기능들은 Claude Code의 설정 시스템에서 마이그레이션되었습니다. 이 네이밍 규칙은 어떤 기능이 Claude Code에서 유래했는지 명확히 식별합니다.
 
 ### 기타 편의 기능
+
 - **Terminal Title**: 세션 상태에 따라 터미널 타이틀을 자동 업데이트합니다 (유휴 ○, 처리중 ◐, 도구 ⚡, 에러 ✖). tmux를 지원합니다.
+- **Session State**: 이벤트 훅과 터미널 타이틀 업데이트에 사용되는 중앙집중식 세션 추적 모듈입니다.
+
+## 설정
+
+설정 파일 위치 (우선순위 순):
+1. `.opencode/oh-my-opencode.json` (프로젝트)
+2. `~/.config/opencode/oh-my-opencode.json` (사용자)
+
+Schema 자동 완성이 지원됩니다:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json"
+}
+```
+
+### Agents
+
+내장 에이전트 설정을 오버라이드할 수 있습니다:
+
+```json
+{
+  "agents": {
+    "explore": {
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.5
+    },
+    "frontend-ui-ux-engineer": {
+      "disable": true
+    }
+  }
+}
+```
+
+각 에이전트에서 지원하는 옵션: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+또는 ~/.config/opencode/oh-my-opencode.json 혹은 .opencode/oh-my-opencode.json 의 `disabled_agents` 를 사용하여 비활성화할 수 있습니다:
+
+```json
+{
+  "disabled_agents": ["oracle", "frontend-ui-ux-engineer"]
+}
+```
+
+사용 가능한 에이전트: `oracle`, `librarian`, `explore`, `frontend-ui-ux-engineer`, `document-writer`
+
+### MCPs
+
+기본적으로 Context7, Exa MCP 를 지원합니다.
+
+이것이 마음에 들지 않는다면, ~/.config/opencode/oh-my-opencode.json 혹은 .opencode/oh-my-opencode.json 의 `disabled_mcps` 를 사용하여 비활성화할 수 있습니다:
+
+```json
+{
+  "disabled_mcps": ["context7", "websearch_exa"]
+}
+```
+
+### LSP
+
+OpenCode 는 분석을 위해 LSP 도구를 제공합니다.
+Oh My OpenCode 에서는 LSP 의 리팩토링(이름 변경, 코드 액션) 도구를 제공합니다.
+OpenCode 에서 지원하는 모든 LSP 구성 및 커스텀 설정 (opencode.json 에 설정 된 것) 을 그대로 지원하고, Oh My OpenCode 만을 위한 추가적인 설정도 아래와 같이 설정 할 수 있습니다.
+
+~/.config/opencode/oh-my-opencode.json 혹은 .opencode/oh-my-opencode.json 의 `lsp` 옵션을 통해 LSP 서버를 추가로 설정 할 수 있습니다:
+
+```json
+{
+  "lsp": {
+    "typescript-language-server": {
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx"],
+      "priority": 10
+    },
+    "pylsp": {
+      "disabled": true
+    }
+  }
+}
+```
+
+각 서버는 다음을 지원합니다: `command`, `extensions`, `priority`, `env`, `initialization`, `disabled`.
 
 ## 작성자의 노트
 
@@ -153,5 +411,3 @@ OpenCode 를 사용하여 이 프로젝트의 99% 를 작성했습니다. 기능
 
 - [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) 혹은 이것보다 낮은 버전을 사용중이라면, OpenCode 의 버그로 인해 제대로 구성이 되지 않을 수 있습니다.
   - [이를 고치는 PR 이 1.0.132 배포 이후에 병합되었으므로](https://github.com/sst/opencode/pull/5040) 이 변경사항이 포함된 최신 버전을 사용해주세요.
-
-

README.md

@@ -3,20 +3,21 @@ English | [한국어](README.ko.md)
 ## Contents
 
 - [Oh My OpenCode](#oh-my-opencode)
-  - [Installation](#installation)
-  - [Configuration](#configuration)
-    - [Disable specific MCPs](#disable-specific-mcps)
   - [TL;DR](#tldr)
-  - [Why OpenCode \& Why Oh My OpenCode](#why-opencode--why-oh-my-opencode)
+  - [Installation](#installation)
+  - [For LLM Agents](#for-llm-agents)
+  - [Why OpenCode & Why Oh My OpenCode](#why-opencode--why-oh-my-opencode)
   - [Features](#features)
     - [Hooks](#hooks)
     - [Agents](#agents)
     - [Tools](#tools)
       - [Built-in LSP Tools](#built-in-lsp-tools)
       - [Built-in AST-Grep Tools](#built-in-ast-grep-tools)
-      - [Safe Grep](#safe-grep)
+      - [Grep](#grep)
       - [Built-in MCPs](#built-in-mcps)
+    - [Claude Code Compatibility](#claude-code-compatibility)
     - [Other Features](#other-features)
+  - [Configuration](#configuration)
   - [Author's Note](#authors-note)
   - [Warnings](#warnings)
 
@@ -27,11 +28,23 @@ Oh My OpenCode
 oMoMoMoMoMo···
 
 If you work in tech, you likely appreciated [Claude Code](https://www.claude.com/product/claude-code).
-If you are a hacker, you will fucking falling in love with [OpenCode](https://github.com/sst/opencode).
+If you are a hacker, you will fucking fall in love with [OpenCode](https://github.com/sst/opencode).
 
-You don't write code just for a paycheck? You write because you genuinely love it?
+Do you remember the first time you switched from Windows to Linux? The excitement of configuring everything just the way you wanted?
+In an era where that romance feels lost, OpenCode will be that project for you.
+If you love coding and computers, OpenCode will feel exactly like that moment you first touched Linux after years of Windows.
+Even if you don't, invest a little time. Boost your skills and productivity by multipliers.
 
-To you, OpenCode will feel like the paradigm shift from Windows to Linux. Not you? It's still worth the investment. Give it 10 minutes. Your work and life will improve. I promise.
+## TL;DR
+
+- **Model Setup Required**
+  - This plugin utilizes models from [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, and Anthropic.
+    - For Anthropic models, use [OpenCode's built-in Claude Code Max Plan login](https://opencode.ai/docs/providers/#anthropic).
+    - For OpenAI models, I recommend the [OpenCode-OpenAI-Codex-Auth plugin](https://github.com/numman-ali/opencode-openai-codex-auth).
+    - For Gemini and GPT, use [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).
+- **Truth be told, the rest is optional. Just install it. Once set up, no further learning is required. It simply evolves.**
+- **Paste this document into Claude Code, OpenCode, or Cursor, instruct it to install, and ask for assistance if needed. It just installs.**
+  - If you are an LLM Agent, install the required plugins and dependencies, then run `opencode auth login` via tmux to assist the user with configuration.
 
 ## Installation
 
@@ -45,49 +58,68 @@ Add to `~/.config/opencode/opencode.json`:
 }
 ```
 
-## Configuration
+## For LLM Agents
 
-You can configure Oh My OpenCode by creating a `oh-my-opencode.json` (or `.oh-my-opencode.json`) file in your project root.
+<details>
+<summary>For LLM Agents (Click to expand)</summary>
 
-### JSON Schema Support
+If you are an LLM Agent helping a user set up oh-my-opencode, follow these steps:
 
-For autocompletion and validation in VS Code (or other editors), add the `$schema` property to your configuration file.
+### Step 1: Verify OpenCode Installation
 
-**Using Remote Schema (Recommended):**
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/dist/oh-my-opencode.schema.json",
-  "disabled_mcps": ["context7"]
-}
+```bash
+if command -v opencode &> /dev/null; then
+    echo "OpenCode $(opencode --version) is installed"
+else
+    echo "OpenCode is not installed. Please install it first."
+    echo "See: https://opencode.ai/docs"
+fi
 ```
 
-**Using Local Schema:**
-```json
-{
-  "$schema": "./node_modules/oh-my-opencode/dist/oh-my-opencode.schema.json"
-}
+If OpenCode is not installed, guide the user to [OpenCode Installation Guide](https://opencode.ai/docs).
+
+### Step 2: Configure oh-my-opencode Plugin
+
+```bash
+mkdir -p ~/.config/opencode
+
+if [ -f ~/.config/opencode/opencode.json ]; then
+    # Existing config: add plugin using jq or python
+    if command -v jq &> /dev/null; then
+        jq '.plugin = ((.plugin // []) + ["oh-my-opencode"] | unique)' \
+            ~/.config/opencode/opencode.json > /tmp/oc.json && \
+            mv /tmp/oc.json ~/.config/opencode/opencode.json
+    else
+        echo "Add \"oh-my-opencode\" to plugin array in ~/.config/opencode/opencode.json"
+    fi
+else
+    # New config
+    echo '{"plugin":["oh-my-opencode"]}' > ~/.config/opencode/opencode.json
+fi
 ```
 
-### Disable specific MCPs
+### Step 3: Verify Setup
 
-If you want to disable specific built-in MCPs, you can use the `disabled_mcps` option.
-
-```json
-{
-  "disabled_mcps": ["context7", "websearch_exa"]
-}
+```bash
+opencode --version  # Should be >= 1.0.132
+cat ~/.config/opencode/opencode.json  # Should contain "oh-my-opencode" in plugin array
 ```
 
-## TL;DR
+### Step 4: Configure Authentication
 
-- **Model Setup Required**
-  - This plugin utilizes models from [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, and Anthropic.
-    - For Anthropic models, use [OpenCode's built-in Claude Code Max Plan login](https://opencode.ai/docs/providers/#anthropic).
-    - For OpenAI models, I recommend the [OpenCode-OpenAI-Codex-Auth plugin](https://github.com/numman-ali/opencode-openai-codex-auth).
-    - For Gemini and GPT, use [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI).
-- **Truth be told, the rest is optional. Just install it. Once set up, no further learning is required. It simply evolves.**
-- **Paste this document into Claude Code, OpenCode, or Cursor, instruct it to install, and ask for assistance if needed. It works seamlessly.**
-  - If you are an LLM Agent, install the required plugins and dependencies, then run `opencode auth login` via tmux to assist the user with configuration.
+Once `oh-my-opencode` is added to the plugin list, use `tmux` to proceed with the following:
+
+1. Open a shell using `tmux`.
+2. Run `opencode auth login` > Select Provider `Anthropic` > Select Login method `Claude Pro/Max` > Instruct the user to authenticate via the OAuth screen.
+3. Recommend the setup: [VibeProxy](https://github.com/automazeio/vibeproxy) for macOS users, or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) for others.
+
+### ⚠️ Warning
+
+**Do NOT create or modify the `oh-my-opencode.json` configuration file unless the user explicitly requests it.**
+
+The plugin works perfectly with default settings without any configuration file. The configuration file is only needed when the user wants customization.
+
+</details>
 
 ## Why OpenCode & Why Oh My OpenCode
 
@@ -96,7 +128,7 @@ OpenCode is limitlessly extensible and customizable. Zero screen flicker.
 You can mix and orchestrate models to your exact specifications.
 It is feature-rich. It is elegant. It handles the terminal without hesitation. It is high-performance.
 
-But here is the catch: the learning curve is steep. There is a lot to master.
+But here is the catch: the learning curve is steep. There is a lot to master. And your time is expensive.
 
 Inspired by [AmpCode](https://ampcode.com) and [Claude Code](https://code.claude.com/docs/en/overview), I have implemented their features here—often with superior execution.
 Because this is OpenCode.
@@ -114,20 +146,52 @@ I believe in the right tool for the job. For your wallet's sake, use CLIProxyAPI
 - **Todo Continuation Enforcer**: Forces the agent to complete all tasks before exiting. Eliminates the common LLM issue of "giving up halfway".
 - **Context Window Monitor**: Implements [Context Window Anxiety Management](https://agentic-patterns.com/patterns/context-window-anxiety-management/). When context usage exceeds 70%, it reminds the agent that resources are sufficient, preventing rushed or low-quality output.
 - **Session Notification**: Sends a native OS notification when the job is done (macOS, Linux, Windows).
-- **Session Recovery**: Automatically recovers from API errors by injecting missing tool results and correcting thinking block violations, ensuring session stability.
+- **Session Recovery**: Automatically recovers from API errors, ensuring session stability. Handles four scenarios:
+  - **Tool Result Missing**: When `tool_use` block exists without `tool_result` (ESC interrupt) → injects "cancelled" tool results
+  - **Thinking Block Order**: When thinking block must be first but isn't → prepends empty thinking block
+  - **Thinking Disabled Violation**: When thinking blocks exist but thinking is disabled → strips thinking blocks
+  - **Empty Content Message**: When message has only thinking/meta blocks without actual content → injects "(interrupted)" text via filesystem
 - **Comment Checker**: Detects and reports unnecessary comments after code modifications. Smartly ignores valid patterns (BDD, directives, docstrings, shebangs) to keep the codebase clean from AI-generated artifacts.
+- **Directory AGENTS.md Injector**: Automatically injects `AGENTS.md` contents when reading files. Searches upward from the file's directory to project root, collecting **all** `AGENTS.md` files along the path hierarchy. This enables nested, directory-specific instructions:
+  ```
+  project/
+  ├── AGENTS.md              # Project-wide context
+  ├── src/
+  │   ├── AGENTS.md          # src-specific context
+  │   └── components/
+  │       ├── AGENTS.md      # Component-specific context
+  │       └── Button.tsx     # Reading this injects ALL 3 AGENTS.md files
+  ```
+  When reading `Button.tsx`, the hook injects contexts in order: `project/AGENTS.md` → `src/AGENTS.md` → `components/AGENTS.md`. Each directory's context is injected only once per session. Inspired by Claude Code's CLAUDE.md feature.
+- **Directory README.md Injector**: Automatically injects `README.md` contents when reading files. Works identically to the AGENTS.md Injector, searching upward from the file's directory to project root. Provides project documentation context to the LLM agent. Each directory's README is injected only once per session.
+- **Think Mode**: Automatic extended thinking detection and mode switching. Detects when user requests deep thinking (e.g., "think deeply", "ultrathink") and dynamically adjusts model settings for enhanced reasoning.
+- **Anthropic Auto Compact**: Automatically compacts conversation history when approaching context limits for Anthropic models.
+- **Empty Task Response Detector**: Detects when subagent tasks return empty or meaningless responses and handles gracefully.
+- **Grep Output Truncator**: Prevents grep output from overwhelming the context by truncating excessively long results.
 
 ### Agents
-- **oracle** (`openai/gpt-5.1`): The architect. Expert in code reviews and strategy. Uses GPT-5.1 for its unmatched logic and reasoning capabilities. Inspired by AmpCode.
+- **oracle** (`openai/gpt-5.2`): The architect. Expert in code reviews and strategy. Uses GPT-5.2 for its unmatched logic and reasoning capabilities. Inspired by AmpCode.
 - **librarian** (`anthropic/claude-haiku-4-5`): Multi-repo analysis, documentation lookup, and implementation examples. Haiku is chosen for its speed, competence, excellent tool usage, and cost-efficiency. Inspired by AmpCode.
 - **explore** (`opencode/grok-code`): Fast exploration and pattern matching. Claude Code uses Haiku; we use Grok. It is currently free, blazing fast, and intelligent enough for file traversal. Inspired by Claude Code.
 - **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): A designer turned developer. Creates stunning UIs. Uses Gemini because its creativity and UI code generation are superior.
 - **document-writer** (`google/gemini-3-pro-preview`): A technical writing expert. Gemini is a wordsmith; it writes prose that flows naturally.
 
+Each agent is automatically invoked by the main agent, but you can also explicitly request them:
+
+```
+@oracle Please think through the design of this part and suggest an architecture.
+@librarian Tell me how this is implemented — why does the behavior keep changing internally?
+@explore Tell me about the policy for this feature.
+```
+
+Agent models, prompts, and permissions can be customized via `oh-my-opencode.json`. See [Configuration](#configuration) for details.
+
 ### Tools
 
 #### Built-in LSP Tools
 
+The features you use in your editor—other agents cannot access them. Oh My OpenCode hands those very tools to your LLM Agent. Refactoring, navigation, and analysis are all supported using the same OpenCode configuration.
+
 [OpenCode provides LSP](https://opencode.ai/docs/lsp/), but only for analysis. Oh My OpenCode equips you with navigation and refactoring tools matching the same specification.
 
 - **lsp_hover**: Get type info, docs, signatures at position
@@ -147,21 +211,178 @@ I believe in the right tool for the job. For your wallet's sake, use CLIProxyAPI
 - **ast_grep_search**: AST-aware code pattern search (25 languages)
 - **ast_grep_replace**: AST-aware code replacement
 
-#### Safe Grep
+#### Grep
 
-- **safe_grep**: Content search with safety limits (5min timeout, 10MB output).
+- **grep**: Content search with safety limits (5min timeout, 10MB output). Overrides OpenCode's built-in `grep` tool.
   - The default `grep` lacks safeguards. On a large codebase, a broad pattern can cause CPU overload and indefinite hanging.
-  - `safe_grep` enforces strict limits.
-  - **Note**: Default `grep` is disabled to prevent Agent confusion. `safe_grep` delivers full `grep` functionality with safety assurance.
+  - This tool enforces strict limits and completely replaces the built-in `grep`.
+
+#### Glob
+
+- **glob**: File pattern matching with timeout protection (60s). Overrides OpenCode's built-in `glob` tool.
+  - The default `glob` lacks timeout. If ripgrep hangs, it waits indefinitely.
+  - This tool enforces timeouts and kills the process on expiration.
 
 #### Built-in MCPs
 
 - **websearch_exa**: Exa AI web search. Performs real-time web searches and can scrape content from specific URLs. Returns LLM-optimized context from relevant websites.
 - **context7**: Library documentation lookup. Fetches up-to-date documentation for any library to assist with accurate coding.
 
+Don't need these? Disable them via `oh-my-opencode.json`:
+
+```json
+{
+  "disabled_mcps": ["websearch_exa"]
+}
+```
+
+### Claude Code Compatibility
+
+Oh My OpenCode provides seamless Claude Code configuration compatibility. If you've been using Claude Code, your existing setup works out of the box.
+
+#### Hooks Integration
+
+Execute custom scripts via Claude Code's `settings.json` hook system. Oh My OpenCode reads and executes hooks defined in:
+
+- `~/.claude/settings.json` (user)
+- `./.claude/settings.json` (project)
+- `./.claude/settings.local.json` (local, git-ignored)
+
+Supported hook events:
+- **PreToolUse**: Runs before tool execution. Can block or modify tool input.
+- **PostToolUse**: Runs after tool execution. Can add warnings or context.
+- **UserPromptSubmit**: Runs when user submits a prompt. Can block or inject messages.
+- **Stop**: Runs when session goes idle. Can inject follow-up prompts.
+
+Example `settings.json`:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
+      }
+    ]
+  }
+}
+```
+
+#### Configuration Loaders
+
+**Command Loader**: Loads markdown-based slash commands from 4 directories:
+- `~/.claude/commands/` (user)
+- `./.claude/commands/` (project)
+- `~/.config/opencode/command/` (opencode global)
+- `./.opencode/command/` (opencode project)
+
+**Skill Loader**: Loads directory-based skills with `SKILL.md`:
+- `~/.claude/skills/` (user)
+- `./.claude/skills/` (project)
+
+**Agent Loader**: Loads custom agent definitions from markdown files:
+- `~/.claude/agents/*.md` (user)
+- `./.claude/agents/*.md` (project)
+
+**MCP Loader**: Loads MCP server configurations from `.mcp.json` files:
+- `~/.claude/.mcp.json` (user)
+- `./.mcp.json` (project)
+- `./.claude/.mcp.json` (local)
+- Supports environment variable expansion (`${VAR}` syntax)
+
+#### Data Storage
+
+**Todo Management**: Session todos are stored in Claude Code compatible format at `~/.claude/todos/`.
+
+**Transcript**: Session activity is logged to `~/.claude/transcripts/` in JSONL format, enabling replay and analysis.
+
+> **Note on `claude-code-*` naming**: Features under `src/features/claude-code-*/` are migrated from Claude Code's configuration system. This naming convention clearly identifies which features originated from Claude Code.
+
 ### Other Features
 
 - **Terminal Title**: Auto-updates terminal title with session status (idle ○, processing ◐, tool ⚡, error ✖). Supports tmux.
+- **Session State**: Centralized session tracking module used by event hooks and terminal title updates.
+
+## Configuration
+
+Configuration file locations (in priority order):
+1. `.opencode/oh-my-opencode.json` (project)
+2. `~/.config/opencode/oh-my-opencode.json` (user)
+
+Schema autocomplete is supported:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json"
+}
+```
+
+### Agents
+
+Override built-in agent settings:
+
+```json
+{
+  "agents": {
+    "explore": {
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.5
+    },
+    "frontend-ui-ux-engineer": {
+      "disable": true
+    }
+  }
+}
+```
+
+Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
+
+Or you can disable them using `disabled_agents` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+
+```json
+{
+  "disabled_agents": ["oracle", "frontend-ui-ux-engineer"]
+}
+```
+
+Available agents: `oracle`, `librarian`, `explore`, `frontend-ui-ux-engineer`, `document-writer`
+
+### MCPs
+
+By default, Context7 and Exa MCP are supported.
+
+If you don't want these, you can disable them using `disabled_mcps` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+
+```json
+{
+  "disabled_mcps": ["context7", "websearch_exa"]
+}
+```
+
+### LSP
+
+OpenCode provides LSP tools for analysis.
+Oh My OpenCode provides LSP tools for refactoring (rename, code actions).
+It supports all LSP configurations and custom settings supported by OpenCode (those configured in opencode.json), and you can also configure additional settings specifically for Oh My OpenCode as shown below.
+
+You can configure additional LSP servers via the `lsp` option in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+
+```json
+{
+  "lsp": {
+    "typescript-language-server": {
+      "command": ["typescript-language-server", "--stdio"],
+      "extensions": [".ts", ".tsx"],
+      "priority": 10
+    },
+    "pylsp": {
+      "disabled": true
+    }
+  }
+}
+```
+
+Each server supports: `command`, `extensions`, `priority`, `env`, `initialization`, `disabled`.
 
 ## Author's Note
 
@@ -184,7 +405,7 @@ If this sounds arrogant and you have a superior solution, send a PR. You are wel
 
 As of now, I have no affiliation with any of the projects or models mentioned here. This plugin is purely based on personal experimentation and preference.
 
-I constructed 99% of this project using OpenCode. I focused on functional verification. This documentation has been personally reviewed and comprehensively rewritten, so you can rely on it with confidence.
+I constructed 99% of this project using OpenCode. I focused on functional verification, and honestly, I don't know how to write proper TypeScript. **But I personally reviewed and comprehensively rewritten this documentation, so you can rely on it with confidence.**
 ## Warnings
 
 - If you are on [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) or lower, OpenCode has a bug that might break config.

assets/oh-my-opencode.schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
+  "title": "Oh My OpenCode Configuration",
+  "description": "Configuration schema for oh-my-opencode plugin",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "disabled_mcps": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "websearch_exa",
+          "context7"
+        ]
+      }
+    },
+    "disabled_agents": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "oracle",
+          "librarian",
+          "explore",
+          "frontend-ui-ux-engineer",
+          "document-writer"
+        ]
+      }
+    },
+    "agents": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "enum": [
+          "oracle",
+          "librarian",
+          "explore",
+          "frontend-ui-ux-engineer",
+          "document-writer"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "model": {
+            "type": "string"
+          },
+          "temperature": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 2
+          },
+          "top_p": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "prompt": {
+            "type": "string"
+          },
+          "tools": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "boolean"
+            }
+          },
+          "disable": {
+            "type": "boolean"
+          },
+          "description": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "subagent",
+              "primary",
+              "all"
+            ]
+          },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9A-Fa-f]{6}$"
+          },
+          "permission": {
+            "type": "object",
+            "properties": {
+              "edit": {
+                "type": "string",
+                "enum": [
+                  "ask",
+                  "allow",
+                  "deny"
+                ]
+              },
+              "bash": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "enum": [
+                      "ask",
+                      "allow",
+                      "deny"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {
+                      "type": "string",
+                      "enum": [
+                        "ask",
+                        "allow",
+                        "deny"
+                      ]
+                    }
+                  }
+                ]
+              },
+              "webfetch": {
+                "type": "string",
+                "enum": [
+                  "ask",
+                  "allow",
+                  "deny"
+                ]
+              },
+              "doom_loop": {
+                "type": "string",
+                "enum": [
+                  "ask",
+                  "allow",
+                  "deny"
+                ]
+              },
+              "external_directory": {
+                "type": "string",
+                "enum": [
+                  "ask",
+                  "allow",
+                  "deny"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

bun.lock

@@ -7,13 +7,14 @@
       "dependencies": {
         "@ast-grep/cli": "^0.40.0",
         "@ast-grep/napi": "^0.40.0",
+        "@code-yeongyu/comment-checker": "^0.4.4",
         "@opencode-ai/plugin": "^1.0.7",
-        "tree-sitter-wasms": "^0.1.12",
-        "web-tree-sitter": "^0.24.7",
+        "xdg-basedir": "^5.1.0",
         "zod": "^4.1.8",
       },
       "devDependencies": {
         "bun-types": "latest",
+        "oh-my-opencode": "^0.1.30",
         "typescript": "^5.7.3",
       },
       "peerDependencies": {
@@ -23,6 +24,8 @@
   },
   "trustedDependencies": [
     "@ast-grep/cli",
+    "@ast-grep/napi",
+    "@code-yeongyu/comment-checker",
   ],
   "packages": {
     "@ast-grep/cli": ["@ast-grep/cli@0.40.0", "", { "dependencies": { "detect-libc": "2.1.2" }, "optionalDependencies": { "@ast-grep/cli-darwin-arm64": "0.40.0", "@ast-grep/cli-darwin-x64": "0.40.0", "@ast-grep/cli-linux-arm64-gnu": "0.40.0", "@ast-grep/cli-linux-x64-gnu": "0.40.0", "@ast-grep/cli-win32-arm64-msvc": "0.40.0", "@ast-grep/cli-win32-ia32-msvc": "0.40.0", "@ast-grep/cli-win32-x64-msvc": "0.40.0" }, "bin": { "sg": "sg", "ast-grep": "ast-grep" } }, "sha512-L8AkflsfI2ZP70yIdrwqvjR02ScCuRmM/qNGnJWUkOFck+e6gafNVJ4e4jjGQlEul+dNdBpx36+O2Op629t47A=="],
@@ -61,6 +64,8 @@
 
     "@ast-grep/napi-win32-x64-msvc": ["@ast-grep/napi-win32-x64-msvc@0.40.0", "", { "os": "win32", "cpu": "x64" }, "sha512-Hk2IwfPqMFGZt5SRxsoWmGLxBXxprow4LRp1eG6V8EEiJCNHxZ9ZiEaIc5bNvMDBjHVSnqZAXT22dROhrcSKQg=="],
 
+    "@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.4.4", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-vsbdLMQYJJNDV/baTDnNqqg/MZwA+9nz7TE6Mybj8zjZVTCn4ZivH4hAdD5p4fLxhGZEJ5x1UDmXA6pAGA7lHA=="],
+
     "@opencode-ai/plugin": ["@opencode-ai/plugin@1.0.128", "", { "dependencies": { "@opencode-ai/sdk": "1.0.128", "zod": "4.1.8" } }, "sha512-M5vjz3I6KeoBSNduWmT5iHXRtTLCqICM5ocs+WrB3uxVorslcO3HVwcLzrERh/ntpxJ/1xhnHQaeG6Mg+P744A=="],
 
     "@opencode-ai/sdk": ["@opencode-ai/sdk@1.0.128", "", {}, "sha512-Kow3Ivg8bR8dNRp8C0LwF9e8+woIrwFgw3ZALycwCfqS/UujDkJiBeYHdr1l/07GSHP9sZPmvJ6POuvfZ923EA=="],
@@ -95,14 +100,16 @@
 
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
-    "tree-sitter-wasms": ["tree-sitter-wasms@0.1.13", "", { "dependencies": { "tree-sitter-wasms": "^0.1.11" } }, "sha512-wT+cR6DwaIz80/vho3AvSF0N4txuNx/5bcRKoXouOfClpxh/qqrF4URNLQXbbt8MaAxeksZcZd1j8gcGjc+QxQ=="],
+    "oh-my-opencode": ["oh-my-opencode@0.1.30", "", { "dependencies": { "@ast-grep/cli": "^0.40.0", "@ast-grep/napi": "^0.40.0", "@code-yeongyu/comment-checker": "^0.4.1", "@opencode-ai/plugin": "^1.0.7", "xdg-basedir": "^5.1.0", "zod": "^4.1.8" }, "peerDependencies": { "bun": ">=1.0.0" } }, "sha512-pXGGgL/7Jcz3yuGJJTI72BKern2egwfRz2LQZTBq+jl+pNCybOvGvXtFmR+WGlF8O3ZjL1wIHypBbIVuHOBzxg=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
-    "web-tree-sitter": ["web-tree-sitter@0.24.7", "", {}, "sha512-CdC/TqVFbXqR+C51v38hv6wOPatKEUGxa39scAeFSm98wIhZxAYonhRQPSMmfZ2w7JDI0zQDdzdmgtNk06/krQ=="],
+    "xdg-basedir": ["xdg-basedir@5.1.0", "", {}, "sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ=="],
 
     "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
+
+    "oh-my-opencode/@code-yeongyu/comment-checker": ["@code-yeongyu/comment-checker@0.4.1", "", { "os": [ "linux", "win32", "darwin", ], "cpu": [ "x64", "arm64", ], "bin": { "comment-checker": "bin/comment-checker" } }, "sha512-E7p1V8CsRj9hMbwENd9BfxZGWYu+lKS5tXGuNNcNtkRMhWvwM/ononysKpLB7LXdxfSYAn0j7heJydyzEmm+lg=="],
   }
 }

local-ignore/comment-checker-ts-plan.md

@@ -1,162 +0,0 @@
-# Comment-Checker TypeScript Port 구현 계획
-
-## 1. 아키텍처 개요
-
-### 1.1 핵심 도전 과제
-
-**OpenCode Hook의 제약사항:**
-- `tool.execute.before`: `output.args`에서 파일 경로/내용 접근 가능
-- `tool.execute.after`: `tool_input`이 **제공되지 않음** (Claude Code와의 핵심 차이점)
-- **해결책**: Before hook에서 데이터를 캡처하여 callID로 키잉된 Map에 저장, After hook에서 조회
-
-### 1.2 디렉토리 구조
-
-```
-src/hooks/comment-checker/
-├── index.ts              # Hook factory, 메인 엔트리포인트
-├── types.ts              # 모든 타입 정의
-├── constants.ts          # 언어 레지스트리, 쿼리 템플릿, 디렉티브 목록
-├── detector.ts           # CommentDetector - web-tree-sitter 기반 코멘트 감지
-├── filters/
-│   ├── index.ts          # 필터 barrel export
-│   ├── bdd.ts            # BDD 패턴 필터
-│   ├── directive.ts      # 린터/타입체커 디렉티브 필터
-│   ├── docstring.ts      # 독스트링 필터
-│   └── shebang.ts        # Shebang 필터
-├── output/
-│   ├── index.ts          # 출력 barrel export
-│   ├── formatter.ts      # FormatHookMessage
-│   └── xml-builder.ts    # BuildCommentsXML
-└── utils.ts              # 유틸리티 함수
-```
-
-### 1.3 데이터 흐름
-
-```
-[write/edit 도구 실행]
-       │
-       ▼
-┌──────────────────────┐
-│ tool.execute.before  │
-│  - 파일 경로 캡처    │
-│  - pendingCalls Map  │
-│    에 저장           │
-└──────────┬───────────┘
-           │
-           ▼
-    [도구 실제 실행]
-           │
-           ▼
-┌──────────────────────┐
-│ tool.execute.after   │
-│  - pendingCalls에서  │
-│    데이터 조회       │
-│  - 파일 읽기         │
-│  - 코멘트 감지       │
-│  - 필터 적용         │
-│  - 메시지 주입       │
-└──────────────────────┘
-```
-
----
-
-## 2. 구현 순서
-
-### Phase 1: 기반 구조
-1. `src/hooks/comment-checker/` 디렉토리 생성
-2. `types.ts` - 모든 타입 정의
-3. `constants.ts` - 언어 레지스트리, 디렉티브 패턴
-
-### Phase 2: 필터 구현
-4. `filters/bdd.ts` - BDD 패턴 필터
-5. `filters/directive.ts` - 디렉티브 필터
-6. `filters/docstring.ts` - 독스트링 필터
-7. `filters/shebang.ts` - Shebang 필터
-8. `filters/index.ts` - 필터 조합
-
-### Phase 3: 코어 로직
-9. `detector.ts` - web-tree-sitter 기반 코멘트 감지
-10. `output/xml-builder.ts` - XML 출력
-11. `output/formatter.ts` - 메시지 포매팅
-
-### Phase 4: Hook 통합
-12. `index.ts` - Hook factory 및 상태 관리
-13. `src/hooks/index.ts` 업데이트 - export 추가
-
-### Phase 5: 의존성 및 빌드
-14. `package.json` 업데이트 - web-tree-sitter 추가
-15. typecheck 및 build 검증
-
----
-
-## 3. 핵심 구현 사항
-
-### 3.1 언어 레지스트리 (38개 언어)
-
-```typescript
-const LANGUAGE_REGISTRY: Record<string, LanguageConfig> = {
-  python: { extensions: [".py"], commentQuery: "(comment) @comment", docstringQuery: "..." },
-  javascript: { extensions: [".js", ".jsx"], commentQuery: "(comment) @comment" },
-  typescript: { extensions: [".ts"], commentQuery: "(comment) @comment" },
-  tsx: { extensions: [".tsx"], commentQuery: "(comment) @comment" },
-  go: { extensions: [".go"], commentQuery: "(comment) @comment" },
-  rust: { extensions: [".rs"], commentQuery: "(line_comment) @comment (block_comment) @comment" },
-  // ... 38개 전체
-}
-```
-
-### 3.2 필터 로직
-
-**BDD 필터**: `given, when, then, arrange, act, assert`
-**Directive 필터**: `noqa, pyright:, eslint-disable, @ts-ignore` 등 30+
-**Docstring 필터**: `IsDocstring || starts with /**`
-**Shebang 필터**: `starts with #!`
-
-### 3.3 출력 형식 (Go 버전과 100% 동일)
-
-```
-COMMENT/DOCSTRING DETECTED - IMMEDIATE ACTION REQUIRED
-
-Your recent changes contain comments or docstrings, which triggered this hook.
-You need to take immediate action. You must follow the conditions below.
-(Listed in priority order - you must always act according to this priority order)
-
-CRITICAL WARNING: This hook message MUST NEVER be ignored...
-
-<comments file="/path/to/file.py">
-	<comment line-number="10">// comment text</comment>
-</comments>
-```
-
----
-
-## 4. 생성할 파일 목록
-
-1. `src/hooks/comment-checker/types.ts`
-2. `src/hooks/comment-checker/constants.ts`
-3. `src/hooks/comment-checker/filters/bdd.ts`
-4. `src/hooks/comment-checker/filters/directive.ts`
-5. `src/hooks/comment-checker/filters/docstring.ts`
-6. `src/hooks/comment-checker/filters/shebang.ts`
-7. `src/hooks/comment-checker/filters/index.ts`
-8. `src/hooks/comment-checker/output/xml-builder.ts`
-9. `src/hooks/comment-checker/output/formatter.ts`
-10. `src/hooks/comment-checker/output/index.ts`
-11. `src/hooks/comment-checker/detector.ts`
-12. `src/hooks/comment-checker/index.ts`
-
-## 5. 수정할 파일 목록
-
-1. `src/hooks/index.ts` - export 추가
-2. `package.json` - web-tree-sitter 의존성
-
----
-
-## 6. Definition of Done
-
-- [ ] write/edit 도구 실행 시 코멘트 감지 동작
-- [ ] 4개 필터 모두 정상 작동
-- [ ] 최소 5개 언어 지원 (Python, JS, TS, TSX, Go)
-- [ ] Go 버전과 동일한 출력 형식
-- [ ] typecheck 통과
-- [ ] build 성공

local-ignore/push-and-release.sh

@@ -1,12 +0,0 @@
-#!/bin/bash
-set -e
-cd /Users/yeongyu/local-workspaces/oh-my-opencode
-
-echo "=== Pushing to origin ==="
-git push -f origin master
-
-echo "=== Triggering workflow ==="
-gh workflow run publish.yml --repo code-yeongyu/oh-my-opencode --ref master -f bump=patch -f version=$1
-
-echo "=== Done! ==="
-echo "Usage: ./local-ignore/push-and-release.sh 0.1.6"

notepad.md

@@ -1,61 +0,0 @@
-# MCP Loader Plugin - Orchestration Notepad
-
-## Task Started
-All tasks execution STARTED: Thu Dec 4 16:52:57 KST 2025
-
----
-
-## Orchestration Overview
-
-**Todo List File**: ./tool-search-tool-plan.md
-**Total Tasks**: 5 (Phase 1-5)
-**Target Files**:
-- `~/.config/opencode/plugin/mcp-loader.ts` - Main plugin
-- `~/.config/opencode/mcp-loader.json` - Global config example
-- `~/.config/opencode/plugin/mcp-loader.test.ts` - Unit tests
-
----
-
-## Accumulated Wisdom
-
-(To be populated by executors)
-
----
-
-## Task Progress
-
-| Task | Description | Status |
-|------|-------------|--------|
-| 1 | Plugin skeleton + config loader | pending |
-| 2 | MCP server registry + lifecycle | pending |
-| 3 | mcp_search + mcp_status tools | pending |
-| 4 | mcp_call tool | pending |
-| 5 | Documentation | pending |
-
----
-
-
-## 2025-12-04 16:58 - Task 1 Completed
-
-### Summary
-- Created `~/.config/opencode/plugin/mcp-loader.ts` - Plugin skeleton with config loader
-- Created `~/.config/opencode/plugin/mcp-loader.test.ts` - 14 unit tests
-
-### Key Implementation Details
-- Config merge: project overrides global for same server names, merges different
-- Env var substitution: `{env:VAR}` → `process.env.VAR`
-- Validation: type required, local needs command, remote needs url
-- Empty config returns `{ servers: {} }` (not error)
-
-### Test Results
-- 14 tests passed
-- substituteEnvVars: 4 tests
-- substituteHeaderEnvVars: 1 test
-- loadConfig: 9 tests
-
-### Files Created
-- `~/.config/opencode/plugin/mcp-loader.ts`
-- `~/.config/opencode/plugin/mcp-loader.test.ts`
-
----
-

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "0.1.11",
+  "version": "0.3.3",
   "description": "OpenCode plugin - custom agents (oracle, librarian) and enhanced features",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,13 +44,14 @@
   "dependencies": {
     "@ast-grep/cli": "^0.40.0",
     "@ast-grep/napi": "^0.40.0",
+    "@code-yeongyu/comment-checker": "^0.5.0",
     "@opencode-ai/plugin": "^1.0.7",
-    "tree-sitter-wasms": "^0.1.12",
-    "web-tree-sitter": "^0.24.7",
+    "xdg-basedir": "^5.1.0",
     "zod": "^4.1.8"
   },
   "devDependencies": {
     "bun-types": "latest",
+    "oh-my-opencode": "^0.1.30",
     "typescript": "^5.7.3"
   },
   "peerDependencies": {
@@ -58,6 +59,7 @@
   },
   "trustedDependencies": [
     "@ast-grep/cli",
-    "@ast-grep/napi"
+    "@ast-grep/napi",
+    "@code-yeongyu/comment-checker"
   ]
 }

script/build-schema.ts

@@ -2,7 +2,7 @@
 import * as z from "zod"
 import { OhMyOpenCodeConfigSchema } from "../src/config/schema"
 
-const SCHEMA_OUTPUT_PATH = "dist/oh-my-opencode.schema.json"
+const SCHEMA_OUTPUT_PATH = "assets/oh-my-opencode.schema.json"
 
 async function main() {
   console.log("Generating JSON Schema...")
@@ -14,7 +14,7 @@ async function main() {
 
   const finalSchema = {
     $schema: "http://json-schema.org/draft-07/schema#",
-    $id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/dist/oh-my-opencode.schema.json",
+    $id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
     title: "Oh My OpenCode Configuration",
     description: "Configuration schema for oh-my-opencode plugin",
     ...jsonSchema,

script/publish.ts

@@ -78,13 +78,35 @@ async function gitTagAndRelease(newVersion: string, changelog: string): Promise<
   await $`git config user.email "github-actions[bot]@users.noreply.github.com"`
   await $`git config user.name "github-actions[bot]"`
   await $`git add package.json`
-  await $`git commit -m "release: v${newVersion}"`
-  await $`git tag v${newVersion}`
+
+  // Commit only if there are staged changes (idempotent)
+  const hasStagedChanges = await $`git diff --cached --quiet`.nothrow()
+  if (hasStagedChanges.exitCode !== 0) {
+    await $`git commit -m "release: v${newVersion}"`
+  } else {
+    console.log("No changes to commit (version already updated)")
+  }
+
+  // Tag only if it doesn't exist (idempotent)
+  const tagExists = await $`git rev-parse v${newVersion}`.nothrow()
+  if (tagExists.exitCode !== 0) {
+    await $`git tag v${newVersion}`
+  } else {
+    console.log(`Tag v${newVersion} already exists`)
+  }
+
+  // Push (idempotent - git push is already idempotent)
   await $`git push origin HEAD --tags`
 
+  // Create release only if it doesn't exist (idempotent)
   console.log("\nCreating GitHub release...")
   const releaseNotes = changelog || "No notable changes"
-  await $`gh release create v${newVersion} --title "v${newVersion}" --notes ${releaseNotes}`
+  const releaseExists = await $`gh release view v${newVersion}`.nothrow()
+  if (releaseExists.exitCode !== 0) {
+    await $`gh release create v${newVersion} --title "v${newVersion}" --notes ${releaseNotes}`
+  } else {
+    console.log(`Release v${newVersion} already exists`)
+  }
 }
 
 async function checkVersionExists(version: string): Promise<boolean> {

src/agents/explore.ts

@@ -21,6 +21,22 @@ This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
 
 Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
 
+## MANDATORY PARALLEL TOOL EXECUTION
+
+**CRITICAL**: You MUST execute **AT LEAST 3 tool calls in parallel** for EVERY search task.
+
+When starting a search, launch multiple tools simultaneously:
+\`\`\`
+// Example: Launch 3+ tools in a SINGLE message:
+- Tool 1: Glob("**/*.ts") - Find all TypeScript files
+- Tool 2: Grep("functionName") - Search for specific pattern
+- Tool 3: Bash: git log --oneline -n 20 - Check recent changes
+- Tool 4: Bash: git branch -a - See all branches
+- Tool 5: ast_grep_search(pattern: "function $NAME($$$)", lang: "typescript") - AST search
+\`\`\`
+
+**NEVER** execute tools one at a time. Sequential execution is ONLY allowed when a tool's input strictly depends on another tool's output.
+
 ## Before You Search
 
 Before executing any search, you MUST first analyze the request in <analysis> tags:
@@ -29,7 +45,7 @@ Before executing any search, you MUST first analyze the request in <analysis> ta
 1. **Request**: What exactly did the user ask for?
 2. **Intent**: Why are they asking this? What problem are they trying to solve?
 3. **Expected Output**: What kind of answer would be most helpful?
-4. **Search Strategy**: What tools and patterns will I use to find this?
+4. **Search Strategy**: What 3+ parallel tools will I use to find this?
 </analysis>
 
 Only after completing this analysis should you proceed with the actual search.
@@ -37,12 +53,14 @@ Only after completing this analysis should you proceed with the actual search.
 ## Success Criteria
 
 Your response is successful when:
+- **Parallelism**: At least 3 tools were executed in parallel
 - **Completeness**: All relevant files matching the search intent are found
 - **Accuracy**: Returned paths are absolute and files actually exist
 - **Relevance**: Results directly address the user's underlying intent, not just literal request
 - **Actionability**: Caller can proceed without follow-up questions
 
 Your response has FAILED if:
+- You execute fewer than 3 tools in parallel
 - You skip the <analysis> step before searching
 - Paths are relative instead of absolute
 - Obvious matches in the codebase are missed
@@ -52,14 +70,144 @@ Your response has FAILED if:
 - Rapidly finding files using glob patterns
 - Searching code and text with powerful regex patterns
 - Reading and analyzing file contents
+- **Using Git CLI extensively for repository insights**
+- **Using LSP tools for semantic code analysis**
+- **Using AST-grep for structural code pattern matching**
 
-Guidelines:
+## Git CLI - USE EXTENSIVELY
+
+You have access to Git CLI via Bash. Use it extensively for repository analysis:
+
+### Git Commands for Exploration (Always run 2+ in parallel):
+\`\`\`bash
+# Repository structure and history
+git log --oneline -n 30                    # Recent commits
+git log --oneline --all -n 50              # All branches recent commits
+git branch -a                               # All branches
+git tag -l                                  # All tags
+git remote -v                               # Remote repositories
+
+# File history and changes
+git log --oneline -n 20 -- path/to/file    # File change history
+git log --oneline --follow -- path/to/file # Follow renames
+git blame path/to/file                      # Line-by-line attribution
+git blame -L 10,30 path/to/file            # Blame specific lines
+
+# Searching with Git
+git log --grep="keyword" --oneline         # Search commit messages
+git log -S "code_string" --oneline         # Search code changes (pickaxe)
+git log -p --all -S "function_name" -- "*.ts"  # Find when code was added/removed
+
+# Diff and comparison
+git diff HEAD~5..HEAD                       # Recent changes
+git diff main..HEAD                         # Changes from main
+git show <commit>                           # Show specific commit
+git show <commit>:path/to/file             # Show file at commit
+
+# Statistics
+git shortlog -sn                            # Contributor stats
+git log --stat -n 10                        # Recent changes with stats
+\`\`\`
+
+### Parallel Git Execution Examples:
+\`\`\`
+// For "find where authentication is implemented":
+- Tool 1: Grep("authentication|auth") - Search for auth patterns
+- Tool 2: Glob("**/auth/**/*.ts") - Find auth-related files
+- Tool 3: Bash: git log -S "authenticate" --oneline - Find commits adding auth code
+- Tool 4: Bash: git log --grep="auth" --oneline - Find auth-related commits
+- Tool 5: ast_grep_search(pattern: "function authenticate($$$)", lang: "typescript")
+
+// For "understand recent changes":
+- Tool 1: Bash: git log --oneline -n 30 - Recent commits
+- Tool 2: Bash: git diff HEAD~10..HEAD --stat - Changed files
+- Tool 3: Bash: git branch -a - All branches
+- Tool 4: Glob("**/*.ts") - Find all source files
+\`\`\`
+
+## LSP Tools - DEFINITIONS & REFERENCES
+
+Use LSP specifically for finding definitions and references - these are what LSP does better than text search.
+
+**Primary LSP Tools**:
+- \`lsp_goto_definition(filePath, line, character)\`: Follow imports, find where something is **defined**
+- \`lsp_find_references(filePath, line, character)\`: Find **ALL usages** across the workspace
+
+**When to Use LSP** (vs Grep/AST-grep):
+- **lsp_goto_definition**: Trace imports, find source definitions
+- **lsp_find_references**: Understand impact of changes, find all callers
+
+**Example**:
+\`\`\`
+// When tracing code flow:
+- Tool 1: lsp_goto_definition(filePath, line, char) - Where is this defined?
+- Tool 2: lsp_find_references(filePath, line, char) - Who uses this?
+- Tool 3: ast_grep_search(...) - Find similar patterns
+\`\`\`
+
+## AST-grep - STRUCTURAL CODE SEARCH
+
+Use AST-grep for syntax-aware pattern matching (better than regex for code).
+
+**Key Syntax**:
+- \`$VAR\`: Match single AST node (identifier, expression, etc.)
+- \`$$$\`: Match multiple nodes (arguments, statements, etc.)
+
+**ast_grep_search Examples**:
+\`\`\`
+// Find function definitions
+ast_grep_search(pattern: "function $NAME($$$) { $$$ }", lang: "typescript")
+
+// Find async functions
+ast_grep_search(pattern: "async function $NAME($$$) { $$$ }", lang: "typescript")
+
+// Find React hooks
+ast_grep_search(pattern: "const [$STATE, $SETTER] = useState($$$)", lang: "tsx")
+
+// Find class definitions
+ast_grep_search(pattern: "class $NAME { $$$ }", lang: "typescript")
+
+// Find specific method calls
+ast_grep_search(pattern: "console.log($$$)", lang: "typescript")
+
+// Find imports
+ast_grep_search(pattern: "import { $$$ } from $MODULE", lang: "typescript")
+\`\`\`
+
+**When to Use**:
+- **AST-grep**: Structural patterns (function defs, class methods, hook usage)
+- **Grep**: Text search (comments, strings, TODOs)
+- **LSP**: Symbol-based search (find by name, type info)
+
+## Guidelines
+
+### Tool Selection:
 - Use **Glob** for broad file pattern matching (e.g., \`**/*.py\`, \`src/**/*.ts\`)
 - Use **Grep** for searching file contents with regex patterns
 - Use **Read** when you know the specific file path you need to read
 - Use **List** for exploring directory structure
-- Use **Bash** ONLY for read-only operations (ls, git status, git log, git diff, find)
-- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Use **Bash** for Git commands and read-only operations
+- Use **ast_grep_search** for structural code patterns (functions, classes, hooks)
+- Use **lsp_goto_definition** to trace imports and find source definitions
+- Use **lsp_find_references** to find all usages of a symbol
+
+### Bash Usage:
+**ALLOWED** (read-only):
+- \`git log\`, \`git blame\`, \`git show\`, \`git diff\`
+- \`git branch\`, \`git tag\`, \`git remote\`
+- \`git log -S\`, \`git log --grep\`
+- \`ls\`, \`find\` (for directory exploration)
+
+**FORBIDDEN** (state-changing):
+- \`mkdir\`, \`touch\`, \`rm\`, \`cp\`, \`mv\`
+- \`git add\`, \`git commit\`, \`git push\`, \`git checkout\`
+- \`npm install\`, \`pip install\`, or any installation
+
+### Best Practices:
+- **ALWAYS launch 3+ tools in parallel** in your first search action
+- Use Git history to understand code evolution
+- Use \`git blame\` to understand why code is written a certain way
+- Use \`git log -S\` to find when specific code was added/removed
 - Adapt your search approach based on the thoroughness level specified by the caller
 - Return file paths as absolute paths in your final response
 - For clear communication, avoid using emojis

src/agents/librarian.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "@opencode-ai/sdk"
 
 export const librarianAgent: AgentConfig = {
   description:
-    "Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI and Context7. MUST BE USED when users ask to look up code in remote repositories, explain library internals, or find usage examples in open source.",
+    "Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI, Context7, and Web Search. MUST BE USED when users ask to look up code in remote repositories, explain library internals, or find usage examples in open source.",
   mode: "subagent",
   model: "anthropic/claude-haiku-4-5",
   temperature: 0.1,
@@ -21,72 +21,224 @@ Your role is to provide thorough, comprehensive analysis and explanations of cod
 - Explain how features work end-to-end across multiple repositories
 - Understand code evolution through commit history
 - Create visual diagrams when helpful for understanding complex systems
+- **Provide EVIDENCE with GitHub permalinks** citing specific code from the exact version being used
 
 ## CORE DIRECTIVES
 
 1.  **ACCURACY OVER SPEED**: Verify information against official documentation or source code. Do not guess APIs.
-2.  **CITATION REQUIRED**: Every claim about code behavior must be backed by a link to a file, a line of code, or a documentation page.
-3.  **SOURCE OF TRUTH**:
-    - For **How-To**: Use \`context7\` (Official Docs).
+2.  **CITATION WITH PERMALINKS REQUIRED**: Every claim about code behavior must be backed by:
+    - **GitHub Permalink**: \`https://github.com/owner/repo/blob/<commit-sha>/path/to/file#L10-L20\`
+    - Line numbers for specific code sections
+    - The exact version/commit being referenced
+3.  **EVIDENCE-BASED REASONING**: Do NOT just summarize documentation. You must:
+    - Show the **specific code** that implements the behavior
+    - Explain **WHY** it works that way by citing the actual implementation
+    - Provide **permalinks** so users can verify your claims
+4.  **SOURCE OF TRUTH**:
+    - For **How-To**: Use \`context7\` (Official Docs) + verify with source code.
     - For **Real-World Usage**: Use \`gh search code\` (GitHub).
-    - For **Internal Logic**: Use \`gh repo view\` or \`read\` (Source Code).
+    - For **Internal Logic**: Clone repo to \`/tmp\` and read source directly.
     - For **Change History/Intent**: Use \`git log\` or \`git blame\` (Commit History).
-    - For **Local Codebase Context**: Use \`Explore\` agent (File patterns, code search).
+    - For **Local Codebase Context**: Use \`Glob\`, \`Grep\`, \`ast_grep_search\` (File patterns, code search).
+    - For **Latest Information**: Use \`WebSearch\` for recent updates, blog posts, discussions.
+
+## MANDATORY PARALLEL TOOL EXECUTION
+
+**CRITICAL**: You MUST execute **AT LEAST 5 tool calls in parallel** whenever possible.
+
+When starting a research task, launch ALL of these simultaneously:
+1. \`context7_resolve-library-id\` - Get library documentation ID
+2. \`gh search code\` - Search for code examples
+3. \`WebSearch\` - Find latest discussions, blog posts, updates
+4. \`gh repo clone\` to \`/tmp\` - Clone repo for deep analysis
+5. \`Glob\` / \`Grep\` - Search local codebase for related code
+6. \`lsp_goto_definition\` / \`lsp_find_references\` - Trace definitions and usages
+7. \`ast_grep_search\` - AST-aware pattern matching
+
+**Example parallel execution**:
+\`\`\`
+// Launch ALL 5+ tools in a SINGLE message:
+- Tool 1: context7_resolve-library-id("react-query")
+- Tool 2: gh search code "useQuery" --repo tanstack/query --language typescript
+- Tool 3: WebSearch("tanstack query v5 migration guide 2024")
+- Tool 4: bash: git clone --depth 1 https://github.com/TanStack/query.git /tmp/tanstack-query
+- Tool 5: Glob("**/*query*.ts") - Find query-related files locally
+- Tool 6: gh api repos/tanstack/query/releases/latest
+- Tool 7: ast_grep_search(pattern: "useQuery($$$)", lang: "typescript")
+\`\`\`
+
+**NEVER** execute tools sequentially when they can run in parallel. Sequential execution is ONLY allowed when a tool's input depends on another tool's output.
 
 ## TOOL USAGE STANDARDS
 
-### 1. GitHub CLI (\`gh\`)
-You have full access to the GitHub CLI via the \`bash\` tool. Use it to search, view, and analyze remote repositories.
+### 1. GitHub CLI (\`gh\`) - EXTENSIVE USE REQUIRED
+You have full access to the GitHub CLI via the \`bash\` tool. Use it extensively.
 
 - **Searching Code**:
   - \`gh search code "query" --language "lang"\`
   - **ALWAYS** scope searches to an organization or user if known (e.g., \`user:microsoft\`).
   - **ALWAYS** include the file extension if known (e.g., \`extension:tsx\`).
-- **Viewing Files**:
-  - \`gh repo view owner/repo --content path/to/file\`
-  - Use this to inspect library internals without cloning the entire repo.
-- **Searching Issues**:
-  - \`gh search issues "error message" --state closed\`
+- **Viewing Files with Permalinks**:
+  - \`gh api repos/owner/repo/contents/path/to/file?ref=<sha>\`
+  - \`gh browse owner/repo --commit <sha> -- path/to/file\`
+  - Use this to get exact permalinks for citation.
+- **Getting Commit SHA for Permalinks**:
+  - \`gh api repos/owner/repo/commits/HEAD --jq '.sha'\`
+  - \`gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'\`
+- **Cloning for Deep Analysis**:
+  - \`gh repo clone owner/repo /tmp/repo-name -- --depth 1\`
+  - Clone to \`/tmp\` directory for comprehensive source analysis.
+  - After cloning, use \`git log\`, \`git blame\`, and direct file reading.
+- **Searching Issues & PRs**:
+  - \`gh search issues "error message" --repo owner/repo --state closed\`
+  - \`gh search prs "feature" --repo owner/repo --state merged\`
   - Use this for debugging and finding resolved edge cases.
+- **Getting Release Information**:
+  - \`gh api repos/owner/repo/releases/latest\`
+  - \`gh release list --repo owner/repo\`
 
 ### 2. Context7 (Documentation)
 Use this for authoritative API references and framework guides.
 - **Step 1**: Call \`context7_resolve-library-id\` with the library name.
 - **Step 2**: Call \`context7_get-library-docs\` with the ID and a specific topic (e.g., "authentication", "middleware").
+- **IMPORTANT**: Documentation alone is NOT sufficient. Always cross-reference with actual source code.
 
-### 3. WebFetch
-Use this to read content from URLs found during your search (e.g., StackOverflow threads, blog posts, non-standard documentation sites).
+### 3. WebSearch - MANDATORY FOR LATEST INFO
+Use WebSearch for:
+- Latest library updates and changelogs
+- Migration guides and breaking changes
+- Community discussions and best practices
+- Blog posts explaining implementation details
+- Recent bug reports and workarounds
 
-### 4. Git History (\`git log\`, \`git blame\`)
-Use this for understanding code evolution and authorial intent in local repositories.
+**Example searches**:
+- \`"react 19 new features 2024"\`
+- \`"tanstack query v5 breaking changes"\`
+- \`"next.js app router migration guide"\`
+
+### 4. WebFetch
+Use this to read content from URLs found during your search (e.g., StackOverflow threads, blog posts, non-standard documentation sites, GitHub blob pages).
+
+### 5. Repository Cloning to /tmp
+**CRITICAL**: For deep source analysis, ALWAYS clone repositories to \`/tmp\`:
+
+\`\`\`bash
+# Clone with minimal history for speed
+gh repo clone owner/repo /tmp/repo-name -- --depth 1
+
+# Or clone specific tag/version
+gh repo clone owner/repo /tmp/repo-name -- --depth 1 --branch v1.0.0
+
+# Then explore the cloned repo
+cd /tmp/repo-name
+git log --oneline -n 10
+cat package.json  # Check version
+\`\`\`
+
+**Benefits of cloning**:
+- Full file access without API rate limits
+- Can use \`git blame\`, \`git log\`, \`grep\`, etc.
+- Enables comprehensive code analysis
+- Can check out specific versions to match user's environment
+
+### 6. Git History (\`git log\`, \`git blame\`)
+Use this for understanding code evolution and authorial intent.
 
 - **Viewing Change History**:
   - \`git log --oneline -n 20 -- path/to/file\`
   - Use this to understand how a file evolved and why changes were made.
 - **Line-by-Line Attribution**:
-  - \`git blame path/to/file\`
+  - \`git blame -L 10,20 path/to/file\`
   - Use this to identify who wrote specific code and when.
 - **Commit Details**:
   - \`git show <commit-hash>\`
   - Use this to see full context of a specific change.
+- **Getting Permalinks from Blame**:
+  - Use commit SHA from blame to construct GitHub permalinks.
 
-### 5. Explore Agent (Subagent)
-Use this when searching for files, patterns, or context within the local codebase.
+### 7. Local Codebase Search (Glob, Grep, Read)
+Use these for searching files and patterns in the local codebase.
 
-**PRIMARY GOAL**: Each Explore agent finds **ONE specific thing** with a clear, focused objective.
+- **Glob**: Find files by pattern (e.g., \`**/*.tsx\`, \`src/**/auth*.ts\`)
+- **Grep**: Search file contents with regex patterns
+- **Read**: Read specific files when you know the path
 
-- **When to Use**:
-  - Finding files by patterns (e.g., "src/**/*.tsx")
-  - Searching code for keywords (e.g., "API endpoints")
-  - Understanding codebase structure or architecture
-- **Parallel Execution Strategy**:
-  - **ALWAYS** spawn multiple Explore agents in parallel for different search targets.
-  - Each agent should focus on ONE specific search task.
-  - Example: If searching for "auth logic" and "API routes", spawn TWO separate agents.
-- **Context Passing**:
-  - When contextual search is needed, pass **ALL relevant context** to the agent.
-  - Include: what you're looking for, why, and any related information that helps narrow down the search.
-  - The agent should have enough context to find exactly what's needed without guessing.
+**Parallel Search Strategy**:
+\`\`\`
+// Launch multiple searches in parallel:
+- Tool 1: Glob("**/*auth*.ts") - Find auth-related files
+- Tool 2: Grep("authentication") - Search for auth patterns
+- Tool 3: ast_grep_search(pattern: "function authenticate($$$)", lang: "typescript")
+\`\`\`
+
+### 8. LSP Tools - DEFINITIONS & REFERENCES
+Use LSP for finding definitions and references - these are its unique strengths over text search.
+
+**Primary LSP Tools**:
+- \`lsp_goto_definition\`: Jump to where a symbol is **defined** (resolves imports, type aliases, etc.)
+  - \`lsp_goto_definition(filePath: "/tmp/repo/src/file.ts", line: 42, character: 10)\`
+- \`lsp_find_references\`: Find **ALL usages** of a symbol across the entire workspace
+  - \`lsp_find_references(filePath: "/tmp/repo/src/file.ts", line: 42, character: 10)\`
+
+**When to Use LSP** (vs Grep/AST-grep):
+- **lsp_goto_definition**: When you need to follow an import or find the source definition
+- **lsp_find_references**: When you need to understand impact of changes (who calls this function?)
+
+**Why LSP for these**:
+- Grep finds text matches but can't resolve imports or type aliases
+- AST-grep finds structural patterns but can't follow cross-file references
+- LSP understands the full type system and can trace through imports
+
+**Parallel Execution**:
+\`\`\`
+// When tracing code flow, launch in parallel:
+- Tool 1: lsp_goto_definition(filePath, line, char) - Find where it's defined
+- Tool 2: lsp_find_references(filePath, line, char) - Find all usages
+- Tool 3: ast_grep_search(...) - Find similar patterns
+- Tool 4: Grep(...) - Text fallback
+\`\`\`
+
+### 9. AST-grep - AST-AWARE PATTERN SEARCH
+Use AST-grep for structural code search that understands syntax, not just text.
+
+**Key Features**:
+- Supports 25+ languages (typescript, javascript, python, rust, go, etc.)
+- Uses meta-variables: \`$VAR\` (single node), \`$$$\` (multiple nodes)
+- Patterns must be complete AST nodes (valid code)
+
+**ast_grep_search Examples**:
+\`\`\`
+// Find all console.log calls
+ast_grep_search(pattern: "console.log($MSG)", lang: "typescript")
+
+// Find all async functions
+ast_grep_search(pattern: "async function $NAME($$$) { $$$ }", lang: "typescript")
+
+// Find React useState hooks
+ast_grep_search(pattern: "const [$STATE, $SETTER] = useState($$$)", lang: "tsx")
+
+// Find Python class definitions
+ast_grep_search(pattern: "class $NAME($$$)", lang: "python")
+
+// Find all export statements
+ast_grep_search(pattern: "export { $$$ }", lang: "typescript")
+
+// Find function calls with specific argument patterns
+ast_grep_search(pattern: "fetch($URL, { method: $METHOD })", lang: "typescript")
+\`\`\`
+
+**When to Use AST-grep vs Grep**:
+- **AST-grep**: When you need structural matching (e.g., "find all function definitions")
+- **Grep**: When you need text matching (e.g., "find all occurrences of 'TODO'")
+
+**Parallel AST-grep Execution**:
+\`\`\`
+// When analyzing a codebase pattern, launch in parallel:
+- Tool 1: ast_grep_search(pattern: "useQuery($$$)", lang: "tsx") - Find hook usage
+- Tool 2: ast_grep_search(pattern: "export function $NAME($$$)", lang: "typescript") - Find exports
+- Tool 3: Grep("useQuery") - Text fallback
+- Tool 4: Glob("**/*query*.ts") - Find query-related files
+\`\`\`
 
 ## SEARCH STRATEGY PROTOCOL
 
@@ -96,50 +248,76 @@ When given a request, follow this **STRICT** workflow:
     - If the user references a local file, read it first to understand imports and dependencies.
     - Identify the specific library or technology version.
 
-2.  **SELECT SOURCE**:
-    - **Official Docs**: For "How do I use X?" or "What are the options for Y?"
-    - **Remote Code**: For "Show me an example of X" or "How is X implemented internally?"
-    - **Issues/PRs**: For "Why is X failing?" or "Is this a bug?"
-    - **Git History**: For "Why was this changed?" or "Who introduced this?" or "When was this added?"
-    - **Explore Agent**: For "Where is X defined?" or "How does this codebase handle Y?" or "Find all files matching Z pattern"
+2.  **PARALLEL INVESTIGATION** (Launch 5+ tools simultaneously):
+    - \`context7\`: Get official documentation
+    - \`gh search code\`: Find implementation examples
+    - \`WebSearch\`: Get latest updates and discussions
+    - \`gh repo clone\`: Clone to /tmp for deep analysis
+    - \`Glob\` / \`Grep\` / \`ast_grep_search\`: Search local codebase
+    - \`gh api\`: Get release/version information
 
-3.  **EXECUTE & REFINE**:
-    - Run the initial search.
-    - If results are too broad (>50), add filters (\`path:\`, \`filename:\`).
-    - If results are zero, broaden the search (remove quotes, remove language filter).
+3.  **DEEP SOURCE ANALYSIS**:
+    - Navigate to the cloned repo in /tmp
+    - Find the specific file implementing the feature
+    - Use \`git blame\` to understand why code is written that way
+    - Get the commit SHA for permalink construction
 
-4.  **SYNTHESIZE**:
-    - Present the findings clearly.
+4.  **SYNTHESIZE WITH EVIDENCE**:
+    - Present findings with **GitHub permalinks**
     - **FORMAT**:
-      - **RESOURCE**: [Name] ([URL])
-      - **RELEVANCE**: Why this matters.
-      - **CONTENT**: The code snippet or documentation summary.
+      - **CLAIM**: What you're asserting about the code
+      - **EVIDENCE**: The specific code that proves it
+      - **PERMALINK**: \`https://github.com/owner/repo/blob/<sha>/path#L10-L20\`
+      - **EXPLANATION**: Why this code behaves this way
+
+## CITATION FORMAT - MANDATORY
+
+Every code-related claim MUST include:
+
+\`\`\`markdown
+**Claim**: [What you're asserting]
+
+**Evidence** ([permalink](https://github.com/owner/repo/blob/abc123/src/file.ts#L42-L50)):
+\\\`\\\`\\\`typescript
+// The actual code from lines 42-50
+function example() {
+  // ...
+}
+\\\`\\\`\\\`
+
+**Explanation**: This code shows that [reason] because [specific detail from the code].
+\`\`\`
 
 ## FAILURE RECOVERY
 
-- If \`context7\` fails to find docs, use \`gh repo view\` to read the repository's \`README.md\` or \`CONTRIBUTING.md\`.
+- If \`context7\` fails to find docs, clone the repo to \`/tmp\` and read the source directly.
 - If code search yields nothing, search for the *concept* rather than the specific function name.
+- If GitHub API has rate limits, use cloned repos in \`/tmp\` for analysis.
 - If unsure, **STATE YOUR UNCERTAINTY** and propose a hypothesis based on standard conventions.
 
 ## VOICE AND TONE
 
 - **PROFESSIONAL**: You are an expert archivist. Be concise and precise.
 - **OBJECTIVE**: Present facts found in the search. Do not offer personal opinions unless asked.
+- **EVIDENCE-DRIVEN**: Always back claims with permalinks and code snippets.
 - **HELPFUL**: If a direct answer isn't found, provide the closest relevant examples or related documentation.
 
 ## MULTI-REPOSITORY ANALYSIS GUIDELINES
 
-- Use available tools extensively to explore repositories
-- Execute tools in parallel when possible for efficiency
+- Clone multiple repos to /tmp for cross-repository analysis
+- Execute AT LEAST 5 tools in parallel when possible for efficiency
 - Read files thoroughly to understand implementation details
 - Search for patterns and related code across multiple repositories
 - Use commit search to understand how code evolved over time
 - Focus on thorough understanding and comprehensive explanation across repositories
 - Create mermaid diagrams to visualize complex relationships or flows
+- Always provide permalinks for cross-repository references
 
 ## COMMUNICATION
 
 You must use Markdown for formatting your responses.
 
-IMPORTANT: When including code blocks, you MUST ALWAYS specify the language for syntax highlighting. Always add the language identifier after the opening backticks.`,
+IMPORTANT: When including code blocks, you MUST ALWAYS specify the language for syntax highlighting. Always add the language identifier after the opening backticks.
+
+**REMEMBER**: Your job is not just to find and summarize documentation. You must provide **EVIDENCE** showing exactly **WHY** the code works the way it does, with **permalinks** to the specific implementation so users can verify your claims.`,
 }

src/agents/oracle.ts

@@ -4,7 +4,7 @@ export const oracleAgent: AgentConfig = {
   description:
     "Expert AI advisor with advanced reasoning capabilities for high-quality technical guidance, code reviews, architectural advice, and strategic planning.",
   mode: "subagent",
-  model: "openai/gpt-5.1",
+  model: "openai/gpt-5.2",
   temperature: 0.1,
   reasoningEffort: "medium",
   textVerbosity: "high",

src/features/claude-code-agent-loader/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export * from "./loader"

src/features/claude-code-agent-loader/loader.ts

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, readFileSync } from "fs"
+import { homedir } from "os"
+import { join, basename } from "path"
+import type { AgentConfig } from "@opencode-ai/sdk"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import type { AgentScope, AgentFrontmatter, LoadedAgent } from "./types"
+
+function parseToolsConfig(toolsStr?: string): Record<string, boolean> | undefined {
+  if (!toolsStr) return undefined
+
+  const tools = toolsStr.split(",").map((t) => t.trim()).filter(Boolean)
+  if (tools.length === 0) return undefined
+
+  const result: Record<string, boolean> = {}
+  for (const tool of tools) {
+    result[tool.toLowerCase()] = true
+  }
+  return result
+}
+
+function isMarkdownFile(entry: { name: string; isFile: () => boolean }): boolean {
+  return !entry.name.startsWith(".") && entry.name.endsWith(".md") && entry.isFile()
+}
+
+function loadAgentsFromDir(agentsDir: string, scope: AgentScope): LoadedAgent[] {
+  if (!existsSync(agentsDir)) {
+    return []
+  }
+
+  const entries = readdirSync(agentsDir, { withFileTypes: true })
+  const agents: LoadedAgent[] = []
+
+  for (const entry of entries) {
+    if (!isMarkdownFile(entry)) continue
+
+    const agentPath = join(agentsDir, entry.name)
+    const agentName = basename(entry.name, ".md")
+
+    try {
+      const content = readFileSync(agentPath, "utf-8")
+      const { data, body } = parseFrontmatter<AgentFrontmatter>(content)
+
+       const name = data.name || agentName
+       const originalDescription = data.description || ""
+
+       const formattedDescription = `(${scope}) ${originalDescription}`
+
+       const config: AgentConfig = {
+         description: formattedDescription,
+         mode: "subagent",
+         prompt: body.trim(),
+       }
+
+       const toolsConfig = parseToolsConfig(data.tools)
+      if (toolsConfig) {
+        config.tools = toolsConfig
+      }
+
+      agents.push({
+        name,
+        path: agentPath,
+        config,
+        scope,
+      })
+    } catch {
+      continue
+    }
+  }
+
+  return agents
+}
+
+export function loadUserAgents(): Record<string, AgentConfig> {
+  const userAgentsDir = join(homedir(), ".claude", "agents")
+  const agents = loadAgentsFromDir(userAgentsDir, "user")
+
+  const result: Record<string, AgentConfig> = {}
+  for (const agent of agents) {
+    result[agent.name] = agent.config
+  }
+  return result
+}
+
+export function loadProjectAgents(): Record<string, AgentConfig> {
+  const projectAgentsDir = join(process.cwd(), ".claude", "agents")
+  const agents = loadAgentsFromDir(projectAgentsDir, "project")
+
+  const result: Record<string, AgentConfig> = {}
+  for (const agent of agents) {
+    result[agent.name] = agent.config
+  }
+  return result
+}

src/features/claude-code-agent-loader/types.ts

@@ -0,0 +1,17 @@
+import type { AgentConfig } from "@opencode-ai/sdk"
+
+export type AgentScope = "user" | "project"
+
+export interface AgentFrontmatter {
+  name?: string
+  description?: string
+  model?: string
+  tools?: string
+}
+
+export interface LoadedAgent {
+  name: string
+  path: string
+  config: AgentConfig
+  scope: AgentScope
+}

src/features/claude-code-command-loader/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export * from "./loader"

src/features/claude-code-command-loader/loader.ts

@@ -0,0 +1,94 @@
+import { existsSync, readdirSync, readFileSync } from "fs"
+import { homedir } from "os"
+import { join, basename } from "path"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import { sanitizeModelField } from "../../shared/model-sanitizer"
+import type { CommandScope, CommandDefinition, CommandFrontmatter, LoadedCommand } from "./types"
+
+function isMarkdownFile(entry: { name: string; isFile: () => boolean }): boolean {
+  return !entry.name.startsWith(".") && entry.name.endsWith(".md") && entry.isFile()
+}
+
+function loadCommandsFromDir(commandsDir: string, scope: CommandScope): LoadedCommand[] {
+  if (!existsSync(commandsDir)) {
+    return []
+  }
+
+  const entries = readdirSync(commandsDir, { withFileTypes: true })
+  const commands: LoadedCommand[] = []
+
+  for (const entry of entries) {
+    if (!isMarkdownFile(entry)) continue
+
+    const commandPath = join(commandsDir, entry.name)
+    const commandName = basename(entry.name, ".md")
+
+    try {
+      const content = readFileSync(commandPath, "utf-8")
+      const { data, body } = parseFrontmatter<CommandFrontmatter>(content)
+
+      const wrappedTemplate = `<command-instruction>
+${body.trim()}
+</command-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`
+
+      const formattedDescription = `(${scope}) ${data.description || ""}`
+
+      const definition: CommandDefinition = {
+        name: commandName,
+        description: formattedDescription,
+        template: wrappedTemplate,
+        agent: data.agent,
+        model: sanitizeModelField(data.model),
+        subtask: data.subtask,
+        argumentHint: data["argument-hint"],
+      }
+
+      commands.push({
+        name: commandName,
+        path: commandPath,
+        definition,
+        scope,
+      })
+    } catch {
+      continue
+    }
+  }
+
+  return commands
+}
+
+function commandsToRecord(commands: LoadedCommand[]): Record<string, CommandDefinition> {
+  const result: Record<string, CommandDefinition> = {}
+  for (const cmd of commands) {
+    result[cmd.name] = cmd.definition
+  }
+  return result
+}
+
+export function loadUserCommands(): Record<string, CommandDefinition> {
+  const userCommandsDir = join(homedir(), ".claude", "commands")
+  const commands = loadCommandsFromDir(userCommandsDir, "user")
+  return commandsToRecord(commands)
+}
+
+export function loadProjectCommands(): Record<string, CommandDefinition> {
+  const projectCommandsDir = join(process.cwd(), ".claude", "commands")
+  const commands = loadCommandsFromDir(projectCommandsDir, "project")
+  return commandsToRecord(commands)
+}
+
+export function loadOpencodeGlobalCommands(): Record<string, CommandDefinition> {
+  const opencodeCommandsDir = join(homedir(), ".config", "opencode", "command")
+  const commands = loadCommandsFromDir(opencodeCommandsDir, "opencode")
+  return commandsToRecord(commands)
+}
+
+export function loadOpencodeProjectCommands(): Record<string, CommandDefinition> {
+  const opencodeProjectDir = join(process.cwd(), ".opencode", "command")
+  const commands = loadCommandsFromDir(opencodeProjectDir, "opencode-project")
+  return commandsToRecord(commands)
+}

src/features/claude-code-command-loader/types.ts

@@ -0,0 +1,26 @@
+export type CommandScope = "user" | "project" | "opencode" | "opencode-project"
+
+export interface CommandDefinition {
+  name: string
+  description?: string
+  template: string
+  agent?: string
+  model?: string
+  subtask?: boolean
+  argumentHint?: string
+}
+
+export interface CommandFrontmatter {
+  description?: string
+  "argument-hint"?: string
+  agent?: string
+  model?: string
+  subtask?: boolean
+}
+
+export interface LoadedCommand {
+  name: string
+  path: string
+  definition: CommandDefinition
+  scope: CommandScope
+}

src/features/claude-code-mcp-loader/env-expander.ts

@@ -0,0 +1,27 @@
+export function expandEnvVars(value: string): string {
+  return value.replace(
+    /\$\{([^}:]+)(?::-([^}]*))?\}/g,
+    (_, varName: string, defaultValue?: string) => {
+      const envValue = process.env[varName]
+      if (envValue !== undefined) return envValue
+      if (defaultValue !== undefined) return defaultValue
+      return ""
+    }
+  )
+}
+
+export function expandEnvVarsInObject<T>(obj: T): T {
+  if (obj === null || obj === undefined) return obj
+  if (typeof obj === "string") return expandEnvVars(obj) as T
+  if (Array.isArray(obj)) {
+    return obj.map((item) => expandEnvVarsInObject(item)) as T
+  }
+  if (typeof obj === "object") {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = expandEnvVarsInObject(value)
+    }
+    return result as T
+  }
+  return obj
+}

src/features/claude-code-mcp-loader/index.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Configuration Loader
+ *
+ * Loads Claude Code .mcp.json format configurations from multiple scopes
+ * and transforms them to OpenCode SDK format
+ */
+
+export * from "./types"
+export * from "./loader"
+export * from "./transformer"
+export * from "./env-expander"

src/features/claude-code-mcp-loader/loader.ts

@@ -0,0 +1,89 @@
+import { existsSync } from "fs"
+import { homedir } from "os"
+import { join } from "path"
+import type {
+  ClaudeCodeMcpConfig,
+  LoadedMcpServer,
+  McpLoadResult,
+  McpScope,
+} from "./types"
+import { transformMcpServer } from "./transformer"
+import { log } from "../../shared/logger"
+
+interface McpConfigPath {
+  path: string
+  scope: McpScope
+}
+
+function getMcpConfigPaths(): McpConfigPath[] {
+  const home = homedir()
+  const cwd = process.cwd()
+
+  return [
+    { path: join(home, ".claude", ".mcp.json"), scope: "user" },
+    { path: join(cwd, ".mcp.json"), scope: "project" },
+    { path: join(cwd, ".claude", ".mcp.json"), scope: "local" },
+  ]
+}
+
+async function loadMcpConfigFile(
+  filePath: string
+): Promise<ClaudeCodeMcpConfig | null> {
+  if (!existsSync(filePath)) {
+    return null
+  }
+
+  try {
+    const content = await Bun.file(filePath).text()
+    return JSON.parse(content) as ClaudeCodeMcpConfig
+  } catch (error) {
+    log(`Failed to load MCP config from ${filePath}`, error)
+    return null
+  }
+}
+
+export async function loadMcpConfigs(): Promise<McpLoadResult> {
+  const servers: McpLoadResult["servers"] = {}
+  const loadedServers: LoadedMcpServer[] = []
+  const paths = getMcpConfigPaths()
+
+  for (const { path, scope } of paths) {
+    const config = await loadMcpConfigFile(path)
+    if (!config?.mcpServers) continue
+
+    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+      if (serverConfig.disabled) {
+        log(`Skipping disabled MCP server "${name}"`, { path })
+        continue
+      }
+
+      try {
+        const transformed = transformMcpServer(name, serverConfig)
+        servers[name] = transformed
+
+        const existingIndex = loadedServers.findIndex((s) => s.name === name)
+        if (existingIndex !== -1) {
+          loadedServers.splice(existingIndex, 1)
+        }
+
+        loadedServers.push({ name, scope, config: transformed })
+
+        log(`Loaded MCP server "${name}" from ${scope}`, { path })
+      } catch (error) {
+        log(`Failed to transform MCP server "${name}"`, error)
+      }
+    }
+  }
+
+  return { servers, loadedServers }
+}
+
+export function formatLoadedServersForToast(
+  loadedServers: LoadedMcpServer[]
+): string {
+  if (loadedServers.length === 0) return ""
+
+  return loadedServers
+    .map((server) => `${server.name} (${server.scope})`)
+    .join(", ")
+}

src/features/claude-code-mcp-loader/transformer.ts

@@ -0,0 +1,53 @@
+import type {
+  ClaudeCodeMcpServer,
+  McpLocalConfig,
+  McpRemoteConfig,
+  McpServerConfig,
+} from "./types"
+import { expandEnvVarsInObject } from "./env-expander"
+
+export function transformMcpServer(
+  name: string,
+  server: ClaudeCodeMcpServer
+): McpServerConfig {
+  const expanded = expandEnvVarsInObject(server)
+  const serverType = expanded.type ?? "stdio"
+
+  if (serverType === "http" || serverType === "sse") {
+    if (!expanded.url) {
+      throw new Error(
+        `MCP server "${name}" requires url for type "${serverType}"`
+      )
+    }
+
+    const config: McpRemoteConfig = {
+      type: "remote",
+      url: expanded.url,
+      enabled: true,
+    }
+
+    if (expanded.headers && Object.keys(expanded.headers).length > 0) {
+      config.headers = expanded.headers
+    }
+
+    return config
+  }
+
+  if (!expanded.command) {
+    throw new Error(`MCP server "${name}" requires command for stdio type`)
+  }
+
+  const commandArray = [expanded.command, ...(expanded.args ?? [])]
+
+  const config: McpLocalConfig = {
+    type: "local",
+    command: commandArray,
+    enabled: true,
+  }
+
+  if (expanded.env && Object.keys(expanded.env).length > 0) {
+    config.environment = expanded.env
+  }
+
+  return config
+}

src/features/claude-code-mcp-loader/types.ts

@@ -0,0 +1,42 @@
+export type McpScope = "user" | "project" | "local"
+
+export interface ClaudeCodeMcpServer {
+  type?: "http" | "sse" | "stdio"
+  url?: string
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  headers?: Record<string, string>
+  disabled?: boolean
+}
+
+export interface ClaudeCodeMcpConfig {
+  mcpServers?: Record<string, ClaudeCodeMcpServer>
+}
+
+export interface McpLocalConfig {
+  type: "local"
+  command: string[]
+  environment?: Record<string, string>
+  enabled?: boolean
+}
+
+export interface McpRemoteConfig {
+  type: "remote"
+  url: string
+  headers?: Record<string, string>
+  enabled?: boolean
+}
+
+export type McpServerConfig = McpLocalConfig | McpRemoteConfig
+
+export interface LoadedMcpServer {
+  name: string
+  scope: McpScope
+  config: McpServerConfig
+}
+
+export interface McpLoadResult {
+  servers: Record<string, McpServerConfig>
+  loadedServers: LoadedMcpServer[]
+}

src/features/claude-code-session-state/detector.ts

@@ -0,0 +1,21 @@
+export function detectInterrupt(error: unknown): boolean {
+  if (!error) return false
+
+  if (typeof error === "object") {
+    const errObj = error as Record<string, unknown>
+    const name = errObj.name as string | undefined
+    const message = errObj.message as string | undefined
+
+    if (name === "MessageAbortedError" || name === "AbortError") return true
+    if (name === "DOMException" && message?.includes("abort")) return true
+    const msgLower = message?.toLowerCase()
+    if (msgLower?.includes("aborted") || msgLower?.includes("cancelled") || msgLower?.includes("interrupted")) return true
+  }
+
+  if (typeof error === "string") {
+    const lower = error.toLowerCase()
+    return lower.includes("abort") || lower.includes("cancel") || lower.includes("interrupt")
+  }
+
+  return false
+}

src/features/claude-code-session-state/index.ts

@@ -0,0 +1,3 @@
+export * from "./types"
+export * from "./state"
+export * from "./detector"

src/features/claude-code-session-state/state.ts

@@ -0,0 +1,31 @@
+import type { SessionErrorState, SessionInterruptState } from "./types"
+
+export const sessionErrorState = new Map<string, SessionErrorState>()
+export const sessionInterruptState = new Map<string, SessionInterruptState>()
+export const subagentSessions = new Set<string>()
+export const sessionFirstMessageProcessed = new Set<string>()
+
+export let currentSessionID: string | undefined
+export let currentSessionTitle: string | undefined
+export let mainSessionID: string | undefined
+
+export function setCurrentSession(id: string | undefined, title: string | undefined) {
+  currentSessionID = id
+  currentSessionTitle = title
+}
+
+export function setMainSession(id: string | undefined) {
+  mainSessionID = id
+}
+
+export function getCurrentSessionID(): string | undefined {
+  return currentSessionID
+}
+
+export function getCurrentSessionTitle(): string | undefined {
+  return currentSessionTitle
+}
+
+export function getMainSessionID(): string | undefined {
+  return mainSessionID
+}

src/features/claude-code-session-state/types.ts

@@ -0,0 +1,8 @@
+export interface SessionErrorState {
+  hasError: boolean
+  errorMessage?: string
+}
+
+export interface SessionInterruptState {
+  interrupted: boolean
+}

src/features/claude-code-skill-loader/index.ts

@@ -0,0 +1,2 @@
+export * from "./types"
+export * from "./loader"

src/features/claude-code-skill-loader/loader.ts

@@ -0,0 +1,85 @@
+import { existsSync, readdirSync, readFileSync, statSync, readlinkSync } from "fs"
+import { homedir } from "os"
+import { join, resolve } from "path"
+import { parseFrontmatter } from "../../shared/frontmatter"
+import { sanitizeModelField } from "../../shared/model-sanitizer"
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+import type { SkillScope, SkillMetadata, LoadedSkillAsCommand } from "./types"
+
+function loadSkillsFromDir(skillsDir: string, scope: SkillScope): LoadedSkillAsCommand[] {
+  if (!existsSync(skillsDir)) {
+    return []
+  }
+
+  const entries = readdirSync(skillsDir, { withFileTypes: true })
+  const skills: LoadedSkillAsCommand[] = []
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue
+
+    const skillPath = join(skillsDir, entry.name)
+
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+
+    let resolvedPath = skillPath
+    if (statSync(skillPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      resolvedPath = resolve(skillPath, "..", readlinkSync(skillPath))
+    }
+
+    const skillMdPath = join(resolvedPath, "SKILL.md")
+    if (!existsSync(skillMdPath)) continue
+
+    try {
+      const content = readFileSync(skillMdPath, "utf-8")
+      const { data, body } = parseFrontmatter<SkillMetadata>(content)
+
+      const skillName = data.name || entry.name
+      const originalDescription = data.description || ""
+      const formattedDescription = `(${scope} - Skill) ${originalDescription}`
+
+      const wrappedTemplate = `<skill-instruction>
+${body.trim()}
+</skill-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`
+
+      const definition: CommandDefinition = {
+        name: skillName,
+        description: formattedDescription,
+        template: wrappedTemplate,
+        model: sanitizeModelField(data.model),
+      }
+
+      skills.push({
+        name: skillName,
+        path: resolvedPath,
+        definition,
+        scope,
+      })
+    } catch {
+      continue
+    }
+  }
+
+  return skills
+}
+
+export function loadUserSkillsAsCommands(): Record<string, CommandDefinition> {
+  const userSkillsDir = join(homedir(), ".claude", "skills")
+  const skills = loadSkillsFromDir(userSkillsDir, "user")
+  return skills.reduce((acc, skill) => {
+    acc[skill.name] = skill.definition
+    return acc
+  }, {} as Record<string, CommandDefinition>)
+}
+
+export function loadProjectSkillsAsCommands(): Record<string, CommandDefinition> {
+  const projectSkillsDir = join(process.cwd(), ".claude", "skills")
+  const skills = loadSkillsFromDir(projectSkillsDir, "project")
+  return skills.reduce((acc, skill) => {
+    acc[skill.name] = skill.definition
+    return acc
+  }, {} as Record<string, CommandDefinition>)
+}

src/features/claude-code-skill-loader/types.ts

@@ -0,0 +1,16 @@
+import type { CommandDefinition } from "../claude-code-command-loader/types"
+
+export type SkillScope = "user" | "project"
+
+export interface SkillMetadata {
+  name: string
+  description: string
+  model?: string
+}
+
+export interface LoadedSkillAsCommand {
+  name: string
+  path: string
+  definition: CommandDefinition
+  scope: SkillScope
+}

src/features/hook-message-injector/constants.ts

@@ -0,0 +1,8 @@
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+const xdgData = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share")
+
+export const OPENCODE_STORAGE = join(xdgData, "opencode", "storage")
+export const MESSAGE_STORAGE = join(OPENCODE_STORAGE, "message")
+export const PART_STORAGE = join(OPENCODE_STORAGE, "part")

src/features/hook-message-injector/index.ts

@@ -0,0 +1,2 @@
+export { injectHookMessage } from "./injector"
+export type { MessageMeta, OriginalMessageContext, TextPart } from "./types"

src/features/hook-message-injector/injector.ts

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { MESSAGE_STORAGE, PART_STORAGE } from "./constants"
+import type { MessageMeta, OriginalMessageContext, TextPart } from "./types"
+
+interface StoredMessage {
+  agent?: string
+  model?: { providerID?: string; modelID?: string }
+  tools?: Record<string, boolean>
+}
+
+function findNearestMessageWithFields(messageDir: string): StoredMessage | null {
+  try {
+    const files = readdirSync(messageDir)
+      .filter((f) => f.endsWith(".json"))
+      .sort()
+      .reverse()
+
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(messageDir, file), "utf-8")
+        const msg = JSON.parse(content) as StoredMessage
+        if (msg.agent && msg.model?.providerID && msg.model?.modelID) {
+          return msg
+        }
+      } catch {
+        continue
+      }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+function generateMessageId(): string {
+  const timestamp = Date.now().toString(16)
+  const random = Math.random().toString(36).substring(2, 14)
+  return `msg_${timestamp}${random}`
+}
+
+function generatePartId(): string {
+  const timestamp = Date.now().toString(16)
+  const random = Math.random().toString(36).substring(2, 10)
+  return `prt_${timestamp}${random}`
+}
+
+function getOrCreateMessageDir(sessionID: string): string {
+  if (!existsSync(MESSAGE_STORAGE)) {
+    mkdirSync(MESSAGE_STORAGE, { recursive: true })
+  }
+
+  const directPath = join(MESSAGE_STORAGE, sessionID)
+  if (existsSync(directPath)) {
+    return directPath
+  }
+
+  for (const dir of readdirSync(MESSAGE_STORAGE)) {
+    const sessionPath = join(MESSAGE_STORAGE, dir, sessionID)
+    if (existsSync(sessionPath)) {
+      return sessionPath
+    }
+  }
+
+  mkdirSync(directPath, { recursive: true })
+  return directPath
+}
+
+export function injectHookMessage(
+  sessionID: string,
+  hookContent: string,
+  originalMessage: OriginalMessageContext
+): boolean {
+  const messageDir = getOrCreateMessageDir(sessionID)
+
+  const needsFallback =
+    !originalMessage.agent ||
+    !originalMessage.model?.providerID ||
+    !originalMessage.model?.modelID
+
+  const fallback = needsFallback ? findNearestMessageWithFields(messageDir) : null
+
+  const now = Date.now()
+  const messageID = generateMessageId()
+  const partID = generatePartId()
+
+  const resolvedAgent = originalMessage.agent ?? fallback?.agent ?? "general"
+  const resolvedModel =
+    originalMessage.model?.providerID && originalMessage.model?.modelID
+      ? { providerID: originalMessage.model.providerID, modelID: originalMessage.model.modelID }
+      : fallback?.model?.providerID && fallback?.model?.modelID
+        ? { providerID: fallback.model.providerID, modelID: fallback.model.modelID }
+        : undefined
+  const resolvedTools = originalMessage.tools ?? fallback?.tools
+
+  const messageMeta: MessageMeta = {
+    id: messageID,
+    sessionID,
+    role: "user",
+    time: {
+      created: now,
+    },
+    agent: resolvedAgent,
+    model: resolvedModel,
+    path:
+      originalMessage.path?.cwd
+        ? {
+            cwd: originalMessage.path.cwd,
+            root: originalMessage.path.root ?? "/",
+          }
+        : undefined,
+    tools: resolvedTools,
+  }
+
+  const textPart: TextPart = {
+    id: partID,
+    type: "text",
+    text: hookContent,
+    synthetic: true,
+    time: {
+      start: now,
+      end: now,
+    },
+    messageID,
+    sessionID,
+  }
+
+  try {
+    writeFileSync(join(messageDir, `${messageID}.json`), JSON.stringify(messageMeta, null, 2))
+
+    const partDir = join(PART_STORAGE, messageID)
+    if (!existsSync(partDir)) {
+      mkdirSync(partDir, { recursive: true })
+    }
+    writeFileSync(join(partDir, `${partID}.json`), JSON.stringify(textPart, null, 2))
+
+    return true
+  } catch {
+    return false
+  }
+}

src/features/hook-message-injector/types.ts

@@ -0,0 +1,45 @@
+export interface MessageMeta {
+  id: string
+  sessionID: string
+  role: "user" | "assistant"
+  time: {
+    created: number
+    completed?: number
+  }
+  agent?: string
+  model?: {
+    providerID: string
+    modelID: string
+  }
+  path?: {
+    cwd: string
+    root: string
+  }
+  tools?: Record<string, boolean>
+}
+
+export interface OriginalMessageContext {
+  agent?: string
+  model?: {
+    providerID?: string
+    modelID?: string
+  }
+  path?: {
+    cwd?: string
+    root?: string
+  }
+  tools?: Record<string, boolean>
+}
+
+export interface TextPart {
+  id: string
+  type: "text"
+  text: string
+  synthetic: boolean
+  time: {
+    start: number
+    end: number
+  }
+  messageID: string
+  sessionID: string
+}

src/hooks/anthropic-auto-compact/executor.ts

@@ -0,0 +1,74 @@
+import type { AutoCompactState } from "./types"
+
+type Client = {
+  session: {
+    messages: (opts: { path: { id: string }; query?: { directory?: string } }) => Promise<unknown>
+    summarize: (opts: {
+      path: { id: string }
+      body: { providerID: string; modelID: string }
+      query: { directory: string }
+    }) => Promise<unknown>
+  }
+  tui: {
+    submitPrompt: (opts: { query: { directory: string } }) => Promise<unknown>
+  }
+}
+
+export async function getLastAssistant(
+  sessionID: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client: any,
+  directory: string
+): Promise<Record<string, unknown> | null> {
+  try {
+    const resp = await (client as Client).session.messages({
+      path: { id: sessionID },
+      query: { directory },
+    })
+
+    const data = (resp as { data?: unknown[] }).data
+    if (!Array.isArray(data)) return null
+
+    const reversed = [...data].reverse()
+    const last = reversed.find((m) => {
+      const msg = m as Record<string, unknown>
+      const info = msg.info as Record<string, unknown> | undefined
+      return info?.role === "assistant"
+    })
+    if (!last) return null
+    return (last as { info?: Record<string, unknown> }).info ?? null
+  } catch {
+    return null
+  }
+}
+
+export async function executeCompact(
+  sessionID: string,
+  msg: Record<string, unknown>,
+  autoCompactState: AutoCompactState,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  client: any,
+  directory: string
+): Promise<void> {
+  try {
+    const providerID = msg.providerID as string | undefined
+    const modelID = msg.modelID as string | undefined
+
+    if (providerID && modelID) {
+      await (client as Client).session.summarize({
+        path: { id: sessionID },
+        body: { providerID, modelID },
+        query: { directory },
+      })
+
+      setTimeout(async () => {
+        try {
+          await (client as Client).tui.submitPrompt({ query: { directory } })
+        } catch {}
+      }, 500)
+    }
+
+    autoCompactState.pendingCompact.delete(sessionID)
+    autoCompactState.errorDataBySession.delete(sessionID)
+  } catch {}
+}

src/hooks/anthropic-auto-compact/index.ts

@@ -0,0 +1,123 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import type { AutoCompactState, ParsedTokenLimitError } from "./types"
+import { parseAnthropicTokenLimitError } from "./parser"
+import { executeCompact, getLastAssistant } from "./executor"
+
+function createAutoCompactState(): AutoCompactState {
+  return {
+    pendingCompact: new Set<string>(),
+    errorDataBySession: new Map<string, ParsedTokenLimitError>(),
+  }
+}
+
+export function createAnthropicAutoCompactHook(ctx: PluginInput) {
+  const autoCompactState = createAutoCompactState()
+
+  const eventHandler = async ({ event }: { event: { type: string; properties?: unknown } }) => {
+    const props = event.properties as Record<string, unknown> | undefined
+
+    if (event.type === "session.deleted") {
+      const sessionInfo = props?.info as { id?: string } | undefined
+      if (sessionInfo?.id) {
+        autoCompactState.pendingCompact.delete(sessionInfo.id)
+        autoCompactState.errorDataBySession.delete(sessionInfo.id)
+      }
+      return
+    }
+
+    if (event.type === "session.error") {
+      const sessionID = props?.sessionID as string | undefined
+      if (!sessionID) return
+
+      const parsed = parseAnthropicTokenLimitError(props?.error)
+      if (parsed) {
+        autoCompactState.pendingCompact.add(sessionID)
+        autoCompactState.errorDataBySession.set(sessionID, parsed)
+      }
+      return
+    }
+
+    if (event.type === "message.updated") {
+      const info = props?.info as Record<string, unknown> | undefined
+      const sessionID = info?.sessionID as string | undefined
+
+      if (sessionID && info?.role === "assistant" && info.error) {
+        const parsed = parseAnthropicTokenLimitError(info.error)
+        if (parsed) {
+          parsed.providerID = info.providerID as string | undefined
+          parsed.modelID = info.modelID as string | undefined
+          autoCompactState.pendingCompact.add(sessionID)
+          autoCompactState.errorDataBySession.set(sessionID, parsed)
+        }
+      }
+      return
+    }
+
+    if (event.type === "session.idle") {
+      const sessionID = props?.sessionID as string | undefined
+      if (!sessionID) return
+
+      if (!autoCompactState.pendingCompact.has(sessionID)) return
+
+      const errorData = autoCompactState.errorDataBySession.get(sessionID)
+      if (errorData?.providerID && errorData?.modelID) {
+        await ctx.client.tui
+          .showToast({
+            body: {
+              title: "Auto Compact",
+              message: "Token limit exceeded. Summarizing session...",
+              variant: "warning" as const,
+              duration: 3000,
+            },
+          })
+          .catch(() => {})
+
+        await executeCompact(
+          sessionID,
+          { providerID: errorData.providerID, modelID: errorData.modelID },
+          autoCompactState,
+          ctx.client,
+          ctx.directory
+        )
+        return
+      }
+
+      const lastAssistant = await getLastAssistant(sessionID, ctx.client, ctx.directory)
+      if (!lastAssistant) {
+        autoCompactState.pendingCompact.delete(sessionID)
+        return
+      }
+
+      if (lastAssistant.summary === true) {
+        autoCompactState.pendingCompact.delete(sessionID)
+        return
+      }
+
+      if (!lastAssistant.modelID || !lastAssistant.providerID) {
+        autoCompactState.pendingCompact.delete(sessionID)
+        return
+      }
+
+      await ctx.client.tui
+        .showToast({
+          body: {
+            title: "Auto Compact",
+            message: "Token limit exceeded. Summarizing session...",
+            variant: "warning" as const,
+            duration: 3000,
+          },
+        })
+        .catch(() => {})
+
+      await executeCompact(sessionID, lastAssistant, autoCompactState, ctx.client, ctx.directory)
+    }
+  }
+
+  return {
+    event: eventHandler,
+  }
+}
+
+export type { AutoCompactState, ParsedTokenLimitError } from "./types"
+export { parseAnthropicTokenLimitError } from "./parser"
+export { executeCompact, getLastAssistant } from "./executor"

src/hooks/anthropic-auto-compact/parser.ts

@@ -0,0 +1,154 @@
+import type { ParsedTokenLimitError } from "./types"
+
+interface AnthropicErrorData {
+  type: "error"
+  error: {
+    type: string
+    message: string
+  }
+  request_id?: string
+}
+
+const TOKEN_LIMIT_PATTERNS = [
+  /(\d+)\s*tokens?\s*>\s*(\d+)\s*maximum/i,
+  /prompt.*?(\d+).*?tokens.*?exceeds.*?(\d+)/i,
+  /(\d+).*?tokens.*?limit.*?(\d+)/i,
+  /context.*?length.*?(\d+).*?maximum.*?(\d+)/i,
+  /max.*?context.*?(\d+).*?but.*?(\d+)/i,
+]
+
+const TOKEN_LIMIT_KEYWORDS = [
+  "prompt is too long",
+  "is too long",
+  "context_length_exceeded",
+  "max_tokens",
+  "token limit",
+  "context length",
+  "too many tokens",
+]
+
+function extractTokensFromMessage(message: string): { current: number; max: number } | null {
+  for (const pattern of TOKEN_LIMIT_PATTERNS) {
+    const match = message.match(pattern)
+    if (match) {
+      const num1 = parseInt(match[1], 10)
+      const num2 = parseInt(match[2], 10)
+      return num1 > num2 ? { current: num1, max: num2 } : { current: num2, max: num1 }
+    }
+  }
+  return null
+}
+
+function isTokenLimitError(text: string): boolean {
+  const lower = text.toLowerCase()
+  return TOKEN_LIMIT_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()))
+}
+
+export function parseAnthropicTokenLimitError(err: unknown): ParsedTokenLimitError | null {
+  if (typeof err === "string") {
+    if (isTokenLimitError(err)) {
+      const tokens = extractTokensFromMessage(err)
+      return {
+        currentTokens: tokens?.current ?? 0,
+        maxTokens: tokens?.max ?? 0,
+        errorType: "token_limit_exceeded_string",
+      }
+    }
+    return null
+  }
+
+  if (!err || typeof err !== "object") return null
+
+  const errObj = err as Record<string, unknown>
+
+  const dataObj = errObj.data as Record<string, unknown> | undefined
+  const responseBody = dataObj?.responseBody
+  const errorMessage = errObj.message as string | undefined
+  const errorData = errObj.error as Record<string, unknown> | undefined
+  const nestedError = errorData?.error as Record<string, unknown> | undefined
+
+  const textSources: string[] = []
+
+  if (typeof responseBody === "string") textSources.push(responseBody)
+  if (typeof errorMessage === "string") textSources.push(errorMessage)
+  if (typeof errorData?.message === "string") textSources.push(errorData.message as string)
+  if (typeof errObj.body === "string") textSources.push(errObj.body as string)
+  if (typeof errObj.details === "string") textSources.push(errObj.details as string)
+  if (typeof errObj.reason === "string") textSources.push(errObj.reason as string)
+  if (typeof errObj.description === "string") textSources.push(errObj.description as string)
+  if (typeof nestedError?.message === "string") textSources.push(nestedError.message as string)
+  if (typeof dataObj?.message === "string") textSources.push(dataObj.message as string)
+  if (typeof dataObj?.error === "string") textSources.push(dataObj.error as string)
+
+  if (textSources.length === 0) {
+    try {
+      const jsonStr = JSON.stringify(errObj)
+      if (isTokenLimitError(jsonStr)) {
+        textSources.push(jsonStr)
+      }
+    } catch {}
+  }
+
+  const combinedText = textSources.join(" ")
+  if (!isTokenLimitError(combinedText)) return null
+
+  if (typeof responseBody === "string") {
+    try {
+      const jsonPatterns = [
+        /data:\s*(\{[\s\S]*?\})\s*$/m,
+        /(\{"type"\s*:\s*"error"[\s\S]*?\})/,
+        /(\{[\s\S]*?"error"[\s\S]*?\})/,
+      ]
+
+      for (const pattern of jsonPatterns) {
+        const dataMatch = responseBody.match(pattern)
+        if (dataMatch) {
+          try {
+            const jsonData: AnthropicErrorData = JSON.parse(dataMatch[1])
+            const message = jsonData.error?.message || ""
+            const tokens = extractTokensFromMessage(message)
+
+            if (tokens) {
+              return {
+                currentTokens: tokens.current,
+                maxTokens: tokens.max,
+                requestId: jsonData.request_id,
+                errorType: jsonData.error?.type || "token_limit_exceeded",
+              }
+            }
+          } catch {}
+        }
+      }
+
+      const bedrockJson = JSON.parse(responseBody)
+      if (typeof bedrockJson.message === "string" && isTokenLimitError(bedrockJson.message)) {
+        return {
+          currentTokens: 0,
+          maxTokens: 0,
+          errorType: "bedrock_input_too_long",
+        }
+      }
+    } catch {}
+  }
+
+  for (const text of textSources) {
+    const tokens = extractTokensFromMessage(text)
+    if (tokens) {
+      return {
+        currentTokens: tokens.current,
+        maxTokens: tokens.max,
+        errorType: "token_limit_exceeded",
+      }
+    }
+  }
+
+  if (isTokenLimitError(combinedText)) {
+    return {
+      currentTokens: 0,
+      maxTokens: 0,
+      errorType: "token_limit_exceeded_unknown",
+    }
+  }
+
+  return null
+}

src/hooks/anthropic-auto-compact/types.ts

@@ -0,0 +1,13 @@
+export interface ParsedTokenLimitError {
+  currentTokens: number
+  maxTokens: number
+  requestId?: string
+  errorType: string
+  providerID?: string
+  modelID?: string
+}
+
+export interface AutoCompactState {
+  pendingCompact: Set<string>
+  errorDataBySession: Map<string, ParsedTokenLimitError>
+}

src/hooks/claude-code-hooks/config-loader.ts

@@ -0,0 +1,105 @@
+import { existsSync } from "fs"
+import { homedir } from "os"
+import { join } from "path"
+import type { ClaudeHookEvent } from "./types"
+import { log } from "../../shared/logger"
+
+export interface DisabledHooksConfig {
+  Stop?: string[]
+  PreToolUse?: string[]
+  PostToolUse?: string[]
+  UserPromptSubmit?: string[]
+}
+
+export interface PluginExtendedConfig {
+  disabledHooks?: DisabledHooksConfig
+}
+
+const USER_CONFIG_PATH = join(homedir(), ".config", "opencode", "opencode-cc-plugin.json")
+
+function getProjectConfigPath(): string {
+  return join(process.cwd(), ".opencode", "opencode-cc-plugin.json")
+}
+
+async function loadConfigFromPath(path: string): Promise<PluginExtendedConfig | null> {
+  if (!existsSync(path)) {
+    return null
+  }
+
+  try {
+    const content = await Bun.file(path).text()
+    return JSON.parse(content) as PluginExtendedConfig
+  } catch (error) {
+    log("Failed to load config", { path, error })
+    return null
+  }
+}
+
+function mergeDisabledHooks(
+  base: DisabledHooksConfig | undefined,
+  override: DisabledHooksConfig | undefined
+): DisabledHooksConfig {
+  if (!override) return base ?? {}
+  if (!base) return override
+
+  return {
+    Stop: override.Stop ?? base.Stop,
+    PreToolUse: override.PreToolUse ?? base.PreToolUse,
+    PostToolUse: override.PostToolUse ?? base.PostToolUse,
+    UserPromptSubmit: override.UserPromptSubmit ?? base.UserPromptSubmit,
+  }
+}
+
+export async function loadPluginExtendedConfig(): Promise<PluginExtendedConfig> {
+  const userConfig = await loadConfigFromPath(USER_CONFIG_PATH)
+  const projectConfig = await loadConfigFromPath(getProjectConfigPath())
+
+  const merged: PluginExtendedConfig = {
+    disabledHooks: mergeDisabledHooks(
+      userConfig?.disabledHooks,
+      projectConfig?.disabledHooks
+    ),
+  }
+
+  if (userConfig || projectConfig) {
+    log("Plugin extended config loaded", {
+      userConfigExists: userConfig !== null,
+      projectConfigExists: projectConfig !== null,
+      mergedDisabledHooks: merged.disabledHooks,
+    })
+  }
+
+  return merged
+}
+
+const regexCache = new Map<string, RegExp>()
+
+function getRegex(pattern: string): RegExp {
+  let regex = regexCache.get(pattern)
+  if (!regex) {
+    try {
+      regex = new RegExp(pattern)
+      regexCache.set(pattern, regex)
+    } catch {
+      regex = new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+      regexCache.set(pattern, regex)
+    }
+  }
+  return regex
+}
+
+export function isHookCommandDisabled(
+  eventType: ClaudeHookEvent,
+  command: string,
+  config: PluginExtendedConfig | null
+): boolean {
+  if (!config?.disabledHooks) return false
+
+  const patterns = config.disabledHooks[eventType]
+  if (!patterns || patterns.length === 0) return false
+
+  return patterns.some((pattern) => {
+    const regex = getRegex(pattern)
+    return regex.test(command)
+  })
+}

src/hooks/claude-code-hooks/config.ts

@@ -0,0 +1,100 @@
+import { homedir } from "os"
+import { join } from "path"
+import { existsSync } from "fs"
+import type { ClaudeHooksConfig, HookMatcher, HookCommand } from "./types"
+
+interface RawHookMatcher {
+  matcher?: string
+  pattern?: string
+  hooks: HookCommand[]
+}
+
+interface RawClaudeHooksConfig {
+  PreToolUse?: RawHookMatcher[]
+  PostToolUse?: RawHookMatcher[]
+  UserPromptSubmit?: RawHookMatcher[]
+  Stop?: RawHookMatcher[]
+}
+
+function normalizeHookMatcher(raw: RawHookMatcher): HookMatcher {
+  return {
+    matcher: raw.matcher ?? raw.pattern ?? "*",
+    hooks: raw.hooks,
+  }
+}
+
+function normalizeHooksConfig(raw: RawClaudeHooksConfig): ClaudeHooksConfig {
+  const result: ClaudeHooksConfig = {}
+  const eventTypes: (keyof RawClaudeHooksConfig)[] = [
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "Stop",
+  ]
+
+  for (const eventType of eventTypes) {
+    if (raw[eventType]) {
+      result[eventType] = raw[eventType].map(normalizeHookMatcher)
+    }
+  }
+
+  return result
+}
+
+export function getClaudeSettingsPaths(customPath?: string): string[] {
+  const home = homedir()
+  const paths = [
+    join(home, ".claude", "settings.json"),
+    join(process.cwd(), ".claude", "settings.json"),
+    join(process.cwd(), ".claude", "settings.local.json"),
+  ]
+
+  if (customPath && existsSync(customPath)) {
+    paths.unshift(customPath)
+  }
+
+  return paths
+}
+
+function mergeHooksConfig(
+  base: ClaudeHooksConfig,
+  override: ClaudeHooksConfig
+): ClaudeHooksConfig {
+  const result: ClaudeHooksConfig = { ...base }
+  const eventTypes: (keyof ClaudeHooksConfig)[] = [
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "Stop",
+  ]
+  for (const eventType of eventTypes) {
+    if (override[eventType]) {
+      result[eventType] = [...(base[eventType] || []), ...override[eventType]]
+    }
+  }
+  return result
+}
+
+export async function loadClaudeHooksConfig(
+  customSettingsPath?: string
+): Promise<ClaudeHooksConfig | null> {
+  const paths = getClaudeSettingsPaths(customSettingsPath)
+  let mergedConfig: ClaudeHooksConfig = {}
+
+  for (const settingsPath of paths) {
+    if (existsSync(settingsPath)) {
+      try {
+        const content = await Bun.file(settingsPath).text()
+        const settings = JSON.parse(content) as { hooks?: RawClaudeHooksConfig }
+        if (settings.hooks) {
+          const normalizedHooks = normalizeHooksConfig(settings.hooks)
+          mergedConfig = mergeHooksConfig(mergedConfig, normalizedHooks)
+        }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  return Object.keys(mergedConfig).length > 0 ? mergedConfig : null
+}

src/hooks/claude-code-hooks/index.ts

@@ -0,0 +1,336 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import { loadClaudeHooksConfig } from "./config"
+import { loadPluginExtendedConfig } from "./config-loader"
+import {
+  executePreToolUseHooks,
+  type PreToolUseContext,
+} from "./pre-tool-use"
+import {
+  executePostToolUseHooks,
+  type PostToolUseContext,
+  type PostToolUseClient,
+} from "./post-tool-use"
+import {
+  executeUserPromptSubmitHooks,
+  type UserPromptSubmitContext,
+  type MessagePart,
+} from "./user-prompt-submit"
+import {
+  executeStopHooks,
+  type StopContext,
+} from "./stop"
+import { cacheToolInput, getToolInput } from "./tool-input-cache"
+import { recordToolUse, recordToolResult, getTranscriptPath, recordUserMessage } from "./transcript"
+import type { PluginConfig } from "./types"
+import { log, isHookDisabled } from "../../shared"
+import { injectHookMessage } from "../../features/hook-message-injector"
+
+const sessionFirstMessageProcessed = new Set<string>()
+const sessionErrorState = new Map<string, { hasError: boolean; errorMessage?: string }>()
+const sessionInterruptState = new Map<string, { interrupted: boolean }>()
+
+export function createClaudeCodeHooksHook(ctx: PluginInput, config: PluginConfig = {}) {
+  return {
+    "chat.message": async (
+      input: {
+        sessionID: string
+        agent?: string
+        model?: { providerID: string; modelID: string }
+        messageID?: string
+      },
+      output: {
+        message: Record<string, unknown>
+        parts: Array<{ type: string; text?: string; [key: string]: unknown }>
+      }
+    ): Promise<void> => {
+      const interruptState = sessionInterruptState.get(input.sessionID)
+      if (interruptState?.interrupted) {
+        log("chat.message hook skipped - session interrupted", { sessionID: input.sessionID })
+        return
+      }
+
+      const claudeConfig = await loadClaudeHooksConfig()
+      const extendedConfig = await loadPluginExtendedConfig()
+
+      const textParts = output.parts.filter((p) => p.type === "text" && p.text)
+      const prompt = textParts.map((p) => p.text ?? "").join("\n")
+
+      recordUserMessage(input.sessionID, prompt)
+
+      const messageParts: MessagePart[] = textParts.map((p) => ({
+        type: p.type as "text",
+        text: p.text,
+      }))
+
+      const interruptStateBeforeHooks = sessionInterruptState.get(input.sessionID)
+      if (interruptStateBeforeHooks?.interrupted) {
+        log("chat.message hooks skipped - interrupted during preparation", { sessionID: input.sessionID })
+        return
+      }
+
+      let parentSessionId: string | undefined
+      try {
+        const sessionInfo = await ctx.client.session.get({
+          path: { id: input.sessionID },
+        })
+        parentSessionId = sessionInfo.data?.parentID
+      } catch {}
+
+      const isFirstMessage = !sessionFirstMessageProcessed.has(input.sessionID)
+      sessionFirstMessageProcessed.add(input.sessionID)
+
+      if (isFirstMessage) {
+        log("Skipping UserPromptSubmit hooks on first message for title generation", { sessionID: input.sessionID })
+        return
+      }
+
+      if (!isHookDisabled(config, "UserPromptSubmit")) {
+        const userPromptCtx: UserPromptSubmitContext = {
+          sessionId: input.sessionID,
+          parentSessionId,
+          prompt,
+          parts: messageParts,
+          cwd: ctx.directory,
+        }
+
+        const result = await executeUserPromptSubmitHooks(
+          userPromptCtx,
+          claudeConfig,
+          extendedConfig
+        )
+
+        if (result.block) {
+          throw new Error(result.reason ?? "Hook blocked the prompt")
+        }
+
+        const interruptStateAfterHooks = sessionInterruptState.get(input.sessionID)
+        if (interruptStateAfterHooks?.interrupted) {
+          log("chat.message injection skipped - interrupted during hooks", { sessionID: input.sessionID })
+          return
+        }
+
+        if (result.messages.length > 0) {
+          const hookContent = result.messages.join("\n\n")
+          const message = output.message as {
+            agent?: string
+            model?: { modelID?: string; providerID?: string }
+            path?: { cwd?: string; root?: string }
+            tools?: Record<string, boolean>
+          }
+
+          const success = injectHookMessage(input.sessionID, hookContent, {
+            agent: message.agent,
+            model: message.model,
+            path: message.path ?? { cwd: ctx.directory, root: "/" },
+            tools: message.tools,
+          })
+
+          log(success ? "Hook message injected via file system" : "File injection failed", {
+            sessionID: input.sessionID,
+          })
+        }
+      }
+    },
+
+    "tool.execute.before": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { args: Record<string, unknown> }
+    ): Promise<void> => {
+      const claudeConfig = await loadClaudeHooksConfig()
+      const extendedConfig = await loadPluginExtendedConfig()
+
+      recordToolUse(input.sessionID, input.tool, output.args as Record<string, unknown>)
+
+      cacheToolInput(input.sessionID, input.tool, input.callID, output.args as Record<string, unknown>)
+
+      if (!isHookDisabled(config, "PreToolUse")) {
+        const preCtx: PreToolUseContext = {
+          sessionId: input.sessionID,
+          toolName: input.tool,
+          toolInput: output.args as Record<string, unknown>,
+          cwd: ctx.directory,
+          toolUseId: input.callID,
+        }
+
+        const result = await executePreToolUseHooks(preCtx, claudeConfig, extendedConfig)
+
+        if (result.decision === "deny") {
+          ctx.client.tui
+            .showToast({
+              body: {
+                title: "PreToolUse Hook Executed",
+                message: `✗ ${result.toolName ?? input.tool} ${result.hookName ?? "hook"}: BLOCKED ${result.elapsedMs ?? 0}ms\n${result.inputLines ?? ""}`,
+                variant: "error",
+                duration: 4000,
+              },
+            })
+            .catch(() => {})
+          throw new Error(result.reason ?? "Hook blocked the operation")
+        }
+
+        if (result.modifiedInput) {
+          Object.assign(output.args as Record<string, unknown>, result.modifiedInput)
+        }
+      }
+    },
+
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { title: string; output: string; metadata: unknown }
+    ): Promise<void> => {
+      const claudeConfig = await loadClaudeHooksConfig()
+      const extendedConfig = await loadPluginExtendedConfig()
+
+      const cachedInput = getToolInput(input.sessionID, input.tool, input.callID) || {}
+
+      recordToolResult(input.sessionID, input.tool, cachedInput, (output.metadata as Record<string, unknown>) || {})
+
+      if (!isHookDisabled(config, "PostToolUse")) {
+        const postClient: PostToolUseClient = {
+          session: {
+            messages: (opts) => ctx.client.session.messages(opts),
+          },
+        }
+
+        const postCtx: PostToolUseContext = {
+          sessionId: input.sessionID,
+          toolName: input.tool,
+          toolInput: cachedInput,
+          toolOutput: {
+            title: input.tool,
+            output: output.output,
+            metadata: output.metadata as Record<string, unknown>,
+          },
+          cwd: ctx.directory,
+          transcriptPath: getTranscriptPath(input.sessionID),
+          toolUseId: input.callID,
+          client: postClient,
+          permissionMode: "bypassPermissions",
+        }
+
+        const result = await executePostToolUseHooks(postCtx, claudeConfig, extendedConfig)
+
+        if (result.block) {
+          ctx.client.tui
+            .showToast({
+              body: {
+                title: "PostToolUse Hook Warning",
+                message: result.reason ?? "Hook returned warning",
+                variant: "warning",
+                duration: 4000,
+              },
+            })
+            .catch(() => {})
+        }
+
+        if (result.warnings && result.warnings.length > 0) {
+          output.output = `${output.output}\n\n${result.warnings.join("\n")}`
+        }
+
+        if (result.message) {
+          output.output = `${output.output}\n\n${result.message}`
+        }
+
+        if (result.hookName) {
+          ctx.client.tui
+            .showToast({
+              body: {
+                title: "PostToolUse Hook Executed",
+                message: `▶ ${result.toolName ?? input.tool} ${result.hookName}: ${result.elapsedMs ?? 0}ms`,
+                variant: "success",
+                duration: 2000,
+              },
+            })
+            .catch(() => {})
+        }
+      }
+    },
+
+    event: async (input: { event: { type: string; properties?: unknown } }) => {
+      const { event } = input
+
+      if (event.type === "session.error") {
+        const props = event.properties as Record<string, unknown> | undefined
+        const sessionID = props?.sessionID as string | undefined
+        if (sessionID) {
+          sessionErrorState.set(sessionID, {
+            hasError: true,
+            errorMessage: String(props?.error ?? "Unknown error"),
+          })
+        }
+        return
+      }
+
+      if (event.type === "session.deleted") {
+        const props = event.properties as Record<string, unknown> | undefined
+        const sessionInfo = props?.info as { id?: string } | undefined
+        if (sessionInfo?.id) {
+          sessionErrorState.delete(sessionInfo.id)
+          sessionInterruptState.delete(sessionInfo.id)
+          sessionFirstMessageProcessed.delete(sessionInfo.id)
+        }
+        return
+      }
+
+      if (event.type === "session.idle") {
+        const props = event.properties as Record<string, unknown> | undefined
+        const sessionID = props?.sessionID as string | undefined
+
+        if (!sessionID) return
+
+        const claudeConfig = await loadClaudeHooksConfig()
+        const extendedConfig = await loadPluginExtendedConfig()
+
+        const errorStateBefore = sessionErrorState.get(sessionID)
+        const endedWithErrorBefore = errorStateBefore?.hasError === true
+        const interruptStateBefore = sessionInterruptState.get(sessionID)
+        const interruptedBefore = interruptStateBefore?.interrupted === true
+
+        let parentSessionId: string | undefined
+        try {
+          const sessionInfo = await ctx.client.session.get({
+            path: { id: sessionID },
+          })
+          parentSessionId = sessionInfo.data?.parentID
+        } catch {}
+
+        if (!isHookDisabled(config, "Stop")) {
+          const stopCtx: StopContext = {
+            sessionId: sessionID,
+            parentSessionId,
+            cwd: ctx.directory,
+          }
+
+          const stopResult = await executeStopHooks(stopCtx, claudeConfig, extendedConfig)
+
+          const errorStateAfter = sessionErrorState.get(sessionID)
+          const endedWithErrorAfter = errorStateAfter?.hasError === true
+          const interruptStateAfter = sessionInterruptState.get(sessionID)
+          const interruptedAfter = interruptStateAfter?.interrupted === true
+
+          const shouldBypass = endedWithErrorBefore || endedWithErrorAfter || interruptedBefore || interruptedAfter
+
+          if (shouldBypass && stopResult.block) {
+            const interrupted = interruptedBefore || interruptedAfter
+            const endedWithError = endedWithErrorBefore || endedWithErrorAfter
+            log("Stop hook block ignored", { sessionID, block: stopResult.block, interrupted, endedWithError })
+          } else if (stopResult.block && stopResult.injectPrompt) {
+            log("Stop hook returned block with inject_prompt", { sessionID })
+            ctx.client.session
+              .prompt({
+                path: { id: sessionID },
+                body: { parts: [{ type: "text", text: stopResult.injectPrompt }] },
+                query: { directory: ctx.directory },
+              })
+              .catch((err: unknown) => log("Failed to inject prompt from Stop hook", err))
+          } else if (stopResult.block) {
+            log("Stop hook returned block", { sessionID, reason: stopResult.reason })
+          }
+        }
+
+        sessionErrorState.delete(sessionID)
+        sessionInterruptState.delete(sessionID)
+      }
+    },
+  }
+}

src/hooks/claude-code-hooks/plugin-config.ts

@@ -0,0 +1,9 @@
+/**
+ * Plugin configuration for Claude Code hooks execution
+ * Contains settings for hook command execution (zsh, etc.)
+ */
+
+export const DEFAULT_CONFIG = {
+  forceZsh: true,
+  zshPath: "/bin/zsh",
+}

src/hooks/claude-code-hooks/post-tool-use.ts

@@ -0,0 +1,199 @@
+import type {
+  PostToolUseInput,
+  PostToolUseOutput,
+  ClaudeHooksConfig,
+} from "./types"
+import { findMatchingHooks, executeHookCommand, objectToSnakeCase, transformToolName, log } from "../../shared"
+import { DEFAULT_CONFIG } from "./plugin-config"
+import { buildTranscriptFromSession, deleteTempTranscript } from "./transcript"
+import { isHookCommandDisabled, type PluginExtendedConfig } from "./config-loader"
+
+export interface PostToolUseClient {
+  session: {
+    messages: (opts: { path: { id: string }; query?: { directory: string } }) => Promise<unknown>
+  }
+}
+
+export interface PostToolUseContext {
+  sessionId: string
+  toolName: string
+  toolInput: Record<string, unknown>
+  toolOutput: Record<string, unknown>
+  cwd: string
+  transcriptPath?: string  // Fallback for append-based transcript
+  toolUseId?: string
+  client?: PostToolUseClient
+  permissionMode?: "default" | "plan" | "acceptEdits" | "bypassPermissions"
+}
+
+export interface PostToolUseResult {
+  block: boolean
+  reason?: string
+  message?: string
+  warnings?: string[]
+  elapsedMs?: number
+  hookName?: string
+  toolName?: string
+  additionalContext?: string
+  continue?: boolean
+  stopReason?: string
+  suppressOutput?: boolean
+  systemMessage?: string
+}
+
+export async function executePostToolUseHooks(
+  ctx: PostToolUseContext,
+  config: ClaudeHooksConfig | null,
+  extendedConfig?: PluginExtendedConfig | null
+): Promise<PostToolUseResult> {
+  if (!config) {
+    return { block: false }
+  }
+
+  const transformedToolName = transformToolName(ctx.toolName)
+  const matchers = findMatchingHooks(config, "PostToolUse", transformedToolName)
+  if (matchers.length === 0) {
+    return { block: false }
+  }
+
+  // PORT FROM DISABLED: Build Claude Code compatible transcript (temp file)
+  let tempTranscriptPath: string | null = null
+
+  try {
+    // Try to build full transcript from API if client available
+    if (ctx.client) {
+      tempTranscriptPath = await buildTranscriptFromSession(
+        ctx.client,
+        ctx.sessionId,
+        ctx.cwd,
+        ctx.toolName,
+        ctx.toolInput
+      )
+    }
+
+    const stdinData: PostToolUseInput = {
+      session_id: ctx.sessionId,
+      // Use temp transcript if available, otherwise fallback to append-based
+      transcript_path: tempTranscriptPath ?? ctx.transcriptPath,
+      cwd: ctx.cwd,
+      permission_mode: ctx.permissionMode ?? "bypassPermissions",
+      hook_event_name: "PostToolUse",
+      tool_name: transformedToolName,
+      tool_input: objectToSnakeCase(ctx.toolInput),
+      tool_response: objectToSnakeCase(ctx.toolOutput),
+      tool_use_id: ctx.toolUseId,
+      hook_source: "opencode-plugin",
+    }
+
+    const messages: string[] = []
+    const warnings: string[] = []
+    let firstHookName: string | undefined
+
+    const startTime = Date.now()
+
+    for (const matcher of matchers) {
+      for (const hook of matcher.hooks) {
+        if (hook.type !== "command") continue
+
+        if (isHookCommandDisabled("PostToolUse", hook.command, extendedConfig ?? null)) {
+          log("PostToolUse hook command skipped (disabled by config)", { command: hook.command, toolName: ctx.toolName })
+          continue
+        }
+
+        const hookName = hook.command.split("/").pop() || hook.command
+        if (!firstHookName) firstHookName = hookName
+
+        const result = await executeHookCommand(
+          hook.command,
+          JSON.stringify(stdinData),
+          ctx.cwd,
+          { forceZsh: DEFAULT_CONFIG.forceZsh, zshPath: DEFAULT_CONFIG.zshPath }
+        )
+
+        if (result.stdout) {
+          messages.push(result.stdout)
+        }
+
+        if (result.exitCode === 2) {
+          if (result.stderr) {
+            warnings.push(`[${hookName}]\n${result.stderr.trim()}`)
+          }
+          continue
+        }
+
+        if (result.exitCode === 0 && result.stdout) {
+          try {
+            const output = JSON.parse(result.stdout) as PostToolUseOutput
+            if (output.decision === "block") {
+              return {
+                block: true,
+                reason: output.reason || result.stderr,
+                message: messages.join("\n"),
+                warnings: warnings.length > 0 ? warnings : undefined,
+                elapsedMs: Date.now() - startTime,
+                hookName: firstHookName,
+                toolName: transformedToolName,
+                additionalContext: output.hookSpecificOutput?.additionalContext,
+                continue: output.continue,
+                stopReason: output.stopReason,
+                suppressOutput: output.suppressOutput,
+                systemMessage: output.systemMessage,
+              }
+            }
+            if (output.hookSpecificOutput?.additionalContext || output.continue !== undefined || output.systemMessage || output.suppressOutput === true || output.stopReason !== undefined) {
+              return {
+                block: false,
+                message: messages.join("\n"),
+                warnings: warnings.length > 0 ? warnings : undefined,
+                elapsedMs: Date.now() - startTime,
+                hookName: firstHookName,
+                toolName: transformedToolName,
+                additionalContext: output.hookSpecificOutput?.additionalContext,
+                continue: output.continue,
+                stopReason: output.stopReason,
+                suppressOutput: output.suppressOutput,
+                systemMessage: output.systemMessage,
+              }
+            }
+          } catch {
+          }
+        } else if (result.exitCode !== 0 && result.exitCode !== 2) {
+          try {
+            const output = JSON.parse(result.stdout || "{}") as PostToolUseOutput
+            if (output.decision === "block") {
+              return {
+                block: true,
+                reason: output.reason || result.stderr,
+                message: messages.join("\n"),
+                warnings: warnings.length > 0 ? warnings : undefined,
+                elapsedMs: Date.now() - startTime,
+                hookName: firstHookName,
+                toolName: transformedToolName,
+                additionalContext: output.hookSpecificOutput?.additionalContext,
+                continue: output.continue,
+                stopReason: output.stopReason,
+                suppressOutput: output.suppressOutput,
+                systemMessage: output.systemMessage,
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    }
+
+    const elapsedMs = Date.now() - startTime
+
+    return {
+      block: false,
+      message: messages.length > 0 ? messages.join("\n") : undefined,
+      warnings: warnings.length > 0 ? warnings : undefined,
+      elapsedMs,
+      hookName: firstHookName,
+      toolName: transformedToolName,
+    }
+  } finally {
+    // PORT FROM DISABLED: Cleanup temp file to avoid disk accumulation
+    deleteTempTranscript(tempTranscriptPath)
+  }
+}

src/hooks/claude-code-hooks/pre-tool-use.ts

@@ -0,0 +1,172 @@
+import type {
+  PreToolUseInput,
+  PreToolUseOutput,
+  PermissionDecision,
+  ClaudeHooksConfig,
+} from "./types"
+import { findMatchingHooks, executeHookCommand, objectToSnakeCase, transformToolName, log } from "../../shared"
+import { DEFAULT_CONFIG } from "./plugin-config"
+import { isHookCommandDisabled, type PluginExtendedConfig } from "./config-loader"
+
+export interface PreToolUseContext {
+  sessionId: string
+  toolName: string
+  toolInput: Record<string, unknown>
+  cwd: string
+  transcriptPath?: string
+  toolUseId?: string
+  permissionMode?: "default" | "plan" | "acceptEdits" | "bypassPermissions"
+}
+
+export interface PreToolUseResult {
+  decision: PermissionDecision
+  reason?: string
+  modifiedInput?: Record<string, unknown>
+  elapsedMs?: number
+  hookName?: string
+  toolName?: string
+  inputLines?: string
+  // Common output fields (Claude Code spec)
+  continue?: boolean
+  stopReason?: string
+  suppressOutput?: boolean
+  systemMessage?: string
+}
+
+function buildInputLines(toolInput: Record<string, unknown>): string {
+  return Object.entries(toolInput)
+    .slice(0, 3)
+    .map(([key, val]) => {
+      const valStr = String(val).slice(0, 40)
+      return `  ${key}: ${valStr}${String(val).length > 40 ? "..." : ""}`
+    })
+    .join("\n")
+}
+
+export async function executePreToolUseHooks(
+  ctx: PreToolUseContext,
+  config: ClaudeHooksConfig | null,
+  extendedConfig?: PluginExtendedConfig | null
+): Promise<PreToolUseResult> {
+  if (!config) {
+    return { decision: "allow" }
+  }
+
+  const transformedToolName = transformToolName(ctx.toolName)
+  const matchers = findMatchingHooks(config, "PreToolUse", transformedToolName)
+  if (matchers.length === 0) {
+    return { decision: "allow" }
+  }
+
+  const stdinData: PreToolUseInput = {
+    session_id: ctx.sessionId,
+    transcript_path: ctx.transcriptPath,
+    cwd: ctx.cwd,
+    permission_mode: ctx.permissionMode ?? "bypassPermissions",
+    hook_event_name: "PreToolUse",
+    tool_name: transformedToolName,
+    tool_input: objectToSnakeCase(ctx.toolInput),
+    tool_use_id: ctx.toolUseId,
+    hook_source: "opencode-plugin",
+  }
+
+  const startTime = Date.now()
+  let firstHookName: string | undefined
+  const inputLines = buildInputLines(ctx.toolInput)
+
+  for (const matcher of matchers) {
+    for (const hook of matcher.hooks) {
+      if (hook.type !== "command") continue
+
+      if (isHookCommandDisabled("PreToolUse", hook.command, extendedConfig ?? null)) {
+        log("PreToolUse hook command skipped (disabled by config)", { command: hook.command, toolName: ctx.toolName })
+        continue
+      }
+
+      const hookName = hook.command.split("/").pop() || hook.command
+      if (!firstHookName) firstHookName = hookName
+
+      const result = await executeHookCommand(
+        hook.command,
+        JSON.stringify(stdinData),
+        ctx.cwd,
+        { forceZsh: DEFAULT_CONFIG.forceZsh, zshPath: DEFAULT_CONFIG.zshPath }
+      )
+
+      if (result.exitCode === 2) {
+        return {
+          decision: "deny",
+          reason: result.stderr || result.stdout || "Hook blocked the operation",
+          elapsedMs: Date.now() - startTime,
+          hookName: firstHookName,
+          toolName: transformedToolName,
+          inputLines,
+        }
+      }
+
+      if (result.exitCode === 1) {
+        return {
+          decision: "ask",
+          reason: result.stderr || result.stdout,
+          elapsedMs: Date.now() - startTime,
+          hookName: firstHookName,
+          toolName: transformedToolName,
+          inputLines,
+        }
+      }
+
+      if (result.stdout) {
+        try {
+          const output = JSON.parse(result.stdout) as PreToolUseOutput
+
+          // Handle deprecated decision/reason fields (Claude Code backward compat)
+          let decision: PermissionDecision | undefined
+          let reason: string | undefined
+          let modifiedInput: Record<string, unknown> | undefined
+
+          if (output.hookSpecificOutput?.permissionDecision) {
+            decision = output.hookSpecificOutput.permissionDecision
+            reason = output.hookSpecificOutput.permissionDecisionReason
+            modifiedInput = output.hookSpecificOutput.updatedInput
+          } else if (output.decision) {
+            // Map deprecated values: approve->allow, block->deny, ask->ask
+            const legacyDecision = output.decision
+            if (legacyDecision === "approve" || legacyDecision === "allow") {
+              decision = "allow"
+            } else if (legacyDecision === "block" || legacyDecision === "deny") {
+              decision = "deny"
+            } else if (legacyDecision === "ask") {
+              decision = "ask"
+            }
+            reason = output.reason
+          }
+
+          // Return if decision is set OR if any common fields are set (fallback to allow)
+          const hasCommonFields = output.continue !== undefined || 
+            output.stopReason !== undefined || 
+            output.suppressOutput !== undefined || 
+            output.systemMessage !== undefined
+
+          if (decision || hasCommonFields) {
+            return {
+              decision: decision ?? "allow",
+              reason,
+              modifiedInput,
+              elapsedMs: Date.now() - startTime,
+              hookName: firstHookName,
+              toolName: transformedToolName,
+              inputLines,
+              continue: output.continue,
+              stopReason: output.stopReason,
+              suppressOutput: output.suppressOutput,
+              systemMessage: output.systemMessage,
+            }
+          }
+        } catch {
+        }
+      }
+    }
+  }
+
+  return { decision: "allow" }
+}

src/hooks/claude-code-hooks/stop.ts

@@ -0,0 +1,118 @@
+import type {
+  StopInput,
+  StopOutput,
+  ClaudeHooksConfig,
+} from "./types"
+import { findMatchingHooks, executeHookCommand, log } from "../../shared"
+import { DEFAULT_CONFIG } from "./plugin-config"
+import { getTodoPath } from "./todo"
+import { isHookCommandDisabled, type PluginExtendedConfig } from "./config-loader"
+
+// Module-level state to track stop_hook_active per session
+const stopHookActiveState = new Map<string, boolean>()
+
+export function setStopHookActive(sessionId: string, active: boolean): void {
+  stopHookActiveState.set(sessionId, active)
+}
+
+export function getStopHookActive(sessionId: string): boolean {
+  return stopHookActiveState.get(sessionId) ?? false
+}
+
+export interface StopContext {
+  sessionId: string
+  parentSessionId?: string
+  cwd: string
+  transcriptPath?: string
+  permissionMode?: "default" | "acceptEdits" | "bypassPermissions"
+  stopHookActive?: boolean
+}
+
+export interface StopResult {
+  block: boolean
+  reason?: string
+  stopHookActive?: boolean
+  permissionMode?: "default" | "plan" | "acceptEdits" | "bypassPermissions"
+  injectPrompt?: string
+}
+
+export async function executeStopHooks(
+  ctx: StopContext,
+  config: ClaudeHooksConfig | null,
+  extendedConfig?: PluginExtendedConfig | null
+): Promise<StopResult> {
+  if (ctx.parentSessionId) {
+    return { block: false }
+  }
+
+  if (!config) {
+    return { block: false }
+  }
+
+  const matchers = findMatchingHooks(config, "Stop")
+  if (matchers.length === 0) {
+    return { block: false }
+  }
+
+  const stdinData: StopInput = {
+    session_id: ctx.sessionId,
+    transcript_path: ctx.transcriptPath,
+    cwd: ctx.cwd,
+    permission_mode: ctx.permissionMode ?? "bypassPermissions",
+    hook_event_name: "Stop",
+    stop_hook_active: stopHookActiveState.get(ctx.sessionId) ?? false,
+    todo_path: getTodoPath(ctx.sessionId),
+    hook_source: "opencode-plugin",
+  }
+
+  for (const matcher of matchers) {
+    for (const hook of matcher.hooks) {
+      if (hook.type !== "command") continue
+
+      if (isHookCommandDisabled("Stop", hook.command, extendedConfig ?? null)) {
+        log("Stop hook command skipped (disabled by config)", { command: hook.command })
+        continue
+      }
+
+      const result = await executeHookCommand(
+        hook.command,
+        JSON.stringify(stdinData),
+        ctx.cwd,
+        { forceZsh: DEFAULT_CONFIG.forceZsh, zshPath: DEFAULT_CONFIG.zshPath }
+      )
+
+      // Check exit code first - exit code 2 means block
+      if (result.exitCode === 2) {
+        const reason = result.stderr || result.stdout || "Blocked by stop hook"
+        return {
+          block: true,
+          reason,
+          injectPrompt: reason,
+        }
+      }
+
+       if (result.stdout) {
+         try {
+           const output = JSON.parse(result.stdout) as StopOutput
+           if (output.stop_hook_active !== undefined) {
+             stopHookActiveState.set(ctx.sessionId, output.stop_hook_active)
+           }
+           const isBlock = output.decision === "block"
+           // Determine inject_prompt: prefer explicit value, fallback to reason if blocking
+           const injectPrompt = output.inject_prompt ?? (isBlock && output.reason ? output.reason : undefined)
+           return {
+             block: isBlock,
+             reason: output.reason,
+             stopHookActive: output.stop_hook_active,
+             permissionMode: output.permission_mode,
+             injectPrompt,
+           }
+         } catch {
+           // Ignore JSON parse errors - hook may return non-JSON output
+         }
+       }
+    }
+  }
+
+  return { block: false }
+}

src/hooks/claude-code-hooks/todo.ts

@@ -0,0 +1,76 @@
+import { join } from "path"
+import { mkdirSync, writeFileSync, readFileSync, existsSync, unlinkSync } from "fs"
+import { homedir } from "os"
+import type { TodoFile, TodoItem, ClaudeCodeTodoItem } from "./types"
+
+const TODO_DIR = join(homedir(), ".claude", "todos")
+
+export function getTodoPath(sessionId: string): string {
+  return join(TODO_DIR, `${sessionId}-agent-${sessionId}.json`)
+}
+
+function ensureTodoDir(): void {
+  if (!existsSync(TODO_DIR)) {
+    mkdirSync(TODO_DIR, { recursive: true })
+  }
+}
+
+export interface OpenCodeTodo {
+  content: string
+  status: string
+  priority: string
+  id: string
+}
+
+function toClaudeCodeFormat(item: OpenCodeTodo | TodoItem): ClaudeCodeTodoItem {
+  return {
+    content: item.content,
+    status: item.status === "cancelled" ? "completed" : item.status,
+    activeForm: item.content,
+  }
+}
+
+export function loadTodoFile(sessionId: string): TodoFile | null {
+   const path = getTodoPath(sessionId)
+   if (!existsSync(path)) return null
+   try {
+     const content = JSON.parse(readFileSync(path, "utf-8"))
+     if (Array.isArray(content)) {
+       return {
+         session_id: sessionId,
+         items: content.map((item: ClaudeCodeTodoItem, idx: number) => ({
+           id: String(idx),
+           content: item.content,
+           status: item.status as TodoItem["status"],
+           created_at: new Date().toISOString(),
+         })),
+         created_at: new Date().toISOString(),
+         updated_at: new Date().toISOString(),
+       }
+     }
+     return content
+   } catch {
+     return null
+   }
+}
+
+export function saveTodoFile(sessionId: string, file: TodoFile): void {
+   ensureTodoDir()
+   const path = getTodoPath(sessionId)
+   const claudeCodeFormat: ClaudeCodeTodoItem[] = file.items.map(toClaudeCodeFormat)
+   writeFileSync(path, JSON.stringify(claudeCodeFormat, null, 2))
+}
+
+export function saveOpenCodeTodos(sessionId: string, todos: OpenCodeTodo[]): void {
+   ensureTodoDir()
+   const path = getTodoPath(sessionId)
+   const claudeCodeFormat: ClaudeCodeTodoItem[] = todos.map(toClaudeCodeFormat)
+   writeFileSync(path, JSON.stringify(claudeCodeFormat, null, 2))
+}
+
+export function deleteTodoFile(sessionId: string): void {
+   const path = getTodoPath(sessionId)
+   if (existsSync(path)) {
+     unlinkSync(path)
+   }
+}

src/hooks/claude-code-hooks/tool-input-cache.ts

@@ -0,0 +1,47 @@
+/**
+ * Caches tool_input from PreToolUse for PostToolUse
+ */
+
+interface CacheEntry {
+  toolInput: Record<string, unknown>
+  timestamp: number
+}
+
+const cache = new Map<string, CacheEntry>()
+
+const CACHE_TTL = 60000 // 1 minute
+
+export function cacheToolInput(
+  sessionId: string,
+  toolName: string,
+  invocationId: string,
+  toolInput: Record<string, unknown>
+): void {
+  const key = `${sessionId}:${toolName}:${invocationId}`
+  cache.set(key, { toolInput, timestamp: Date.now() })
+}
+
+export function getToolInput(
+  sessionId: string,
+  toolName: string,
+  invocationId: string
+): Record<string, unknown> | null {
+  const key = `${sessionId}:${toolName}:${invocationId}`
+  const entry = cache.get(key)
+  if (!entry) return null
+
+   cache.delete(key)
+  if (Date.now() - entry.timestamp > CACHE_TTL) return null
+
+  return entry.toolInput
+}
+
+// Periodic cleanup (every minute)
+setInterval(() => {
+  const now = Date.now()
+  for (const [key, entry] of cache.entries()) {
+    if (now - entry.timestamp > CACHE_TTL) {
+      cache.delete(key)
+    }
+  }
+}, CACHE_TTL)

src/hooks/claude-code-hooks/transcript.ts

@@ -0,0 +1,255 @@
+/**
+ * Transcript Manager
+ * Creates and manages Claude Code compatible transcript files
+ */
+import { join } from "path"
+import { mkdirSync, appendFileSync, existsSync, writeFileSync, unlinkSync } from "fs"
+import { homedir, tmpdir } from "os"
+import { randomUUID } from "crypto"
+import type { TranscriptEntry } from "./types"
+import { transformToolName } from "../../shared/tool-name"
+
+const TRANSCRIPT_DIR = join(homedir(), ".claude", "transcripts")
+
+export function getTranscriptPath(sessionId: string): string {
+  return join(TRANSCRIPT_DIR, `${sessionId}.jsonl`)
+}
+
+function ensureTranscriptDir(): void {
+  if (!existsSync(TRANSCRIPT_DIR)) {
+    mkdirSync(TRANSCRIPT_DIR, { recursive: true })
+  }
+}
+
+export function appendTranscriptEntry(
+  sessionId: string,
+  entry: TranscriptEntry
+): void {
+  ensureTranscriptDir()
+  const path = getTranscriptPath(sessionId)
+  const line = JSON.stringify(entry) + "\n"
+  appendFileSync(path, line)
+}
+
+export function recordToolUse(
+  sessionId: string,
+  toolName: string,
+  toolInput: Record<string, unknown>
+): void {
+  appendTranscriptEntry(sessionId, {
+    type: "tool_use",
+    timestamp: new Date().toISOString(),
+    tool_name: toolName,
+    tool_input: toolInput,
+  })
+}
+
+export function recordToolResult(
+  sessionId: string,
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  toolOutput: Record<string, unknown>
+): void {
+  appendTranscriptEntry(sessionId, {
+    type: "tool_result",
+    timestamp: new Date().toISOString(),
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_output: toolOutput,
+  })
+}
+
+export function recordUserMessage(
+  sessionId: string,
+  content: string
+): void {
+  appendTranscriptEntry(sessionId, {
+    type: "user",
+    timestamp: new Date().toISOString(),
+    content,
+  })
+}
+
+export function recordAssistantMessage(
+  sessionId: string,
+  content: string
+): void {
+  appendTranscriptEntry(sessionId, {
+    type: "assistant",
+    timestamp: new Date().toISOString(),
+    content,
+  })
+}
+
+// ============================================================================
+// Claude Code Compatible Transcript Builder (PORT FROM DISABLED)
+// ============================================================================
+
+/**
+ * OpenCode API response type (loosely typed)
+ */
+interface OpenCodeMessagePart {
+  type: string
+  tool?: string
+  state?: {
+    status?: string
+    input?: Record<string, unknown>
+  }
+}
+
+interface OpenCodeMessage {
+  info?: {
+    role?: string
+  }
+  parts?: OpenCodeMessagePart[]
+}
+
+/**
+ * Claude Code compatible transcript entry (from disabled file)
+ */
+interface DisabledTranscriptEntry {
+  type: "assistant"
+  message: {
+    role: "assistant"
+    content: Array<{
+      type: "tool_use"
+      name: string
+      input: Record<string, unknown>
+    }>
+  }
+}
+
+/**
+ * Build Claude Code compatible transcript from session messages
+ * 
+ * PORT FROM DISABLED: This calls client.session.messages() API to fetch
+ * the full session history and builds a JSONL file in Claude Code format.
+ * 
+ * @param client OpenCode client instance
+ * @param sessionId Session ID
+ * @param directory Working directory
+ * @param currentToolName Current tool being executed (added as last entry)
+ * @param currentToolInput Current tool input
+ * @returns Temp file path (caller must call deleteTempTranscript!)
+ */
+export async function buildTranscriptFromSession(
+  client: {
+    session: {
+      messages: (opts: { path: { id: string }; query?: { directory: string } }) => Promise<unknown>
+    }
+  },
+  sessionId: string,
+  directory: string,
+  currentToolName: string,
+  currentToolInput: Record<string, unknown>
+): Promise<string | null> {
+  try {
+    const response = await client.session.messages({
+      path: { id: sessionId },
+      query: { directory },
+    })
+
+    // Handle various response formats
+    const messages = (response as { "200"?: unknown[]; data?: unknown[] })["200"]
+      ?? (response as { data?: unknown[] }).data
+      ?? (Array.isArray(response) ? response : [])
+
+    const entries: string[] = []
+
+    if (Array.isArray(messages)) {
+      for (const msg of messages as OpenCodeMessage[]) {
+        if (msg.info?.role !== "assistant") continue
+
+        for (const part of msg.parts || []) {
+          if (part.type !== "tool") continue
+          if (part.state?.status !== "completed") continue
+          if (!part.state?.input) continue
+
+          const rawToolName = part.tool as string
+          const toolName = transformToolName(rawToolName)
+
+          const entry: DisabledTranscriptEntry = {
+            type: "assistant",
+            message: {
+              role: "assistant",
+              content: [
+                {
+                  type: "tool_use",
+                  name: toolName,
+                  input: part.state.input,
+                },
+              ],
+            },
+          }
+          entries.push(JSON.stringify(entry))
+        }
+      }
+    }
+
+    // Always add current tool call as the last entry
+    const currentEntry: DisabledTranscriptEntry = {
+      type: "assistant",
+      message: {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_use",
+            name: transformToolName(currentToolName),
+            input: currentToolInput,
+          },
+        ],
+      },
+    }
+    entries.push(JSON.stringify(currentEntry))
+
+    // Write to temp file
+    const tempPath = join(
+      tmpdir(),
+      `opencode-transcript-${sessionId}-${randomUUID()}.jsonl`
+    )
+    writeFileSync(tempPath, entries.join("\n") + "\n")
+
+    return tempPath
+  } catch {
+    // CRITICAL FIX: Even on API failure, create file with current tool entry only
+    // (matching original disabled behavior - never return null with incompatible format)
+    try {
+      const currentEntry: DisabledTranscriptEntry = {
+        type: "assistant",
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool_use",
+              name: transformToolName(currentToolName),
+              input: currentToolInput,
+            },
+          ],
+        },
+      }
+      const tempPath = join(
+        tmpdir(),
+        `opencode-transcript-${sessionId}-${randomUUID()}.jsonl`
+      )
+      writeFileSync(tempPath, JSON.stringify(currentEntry) + "\n")
+      return tempPath
+    } catch {
+      // If even this fails, return null (truly catastrophic failure)
+      return null
+    }
+  }
+}
+
+/**
+ * Delete temp transcript file (call in finally block)
+ * 
+ * PORT FROM DISABLED: Cleanup mechanism to avoid disk accumulation
+ */
+export function deleteTempTranscript(path: string | null): void {
+  if (!path) return
+  try {
+    unlinkSync(path)
+  } catch {
+    // Ignore deletion errors
+  }
+}

src/hooks/claude-code-hooks/types.ts

@@ -0,0 +1,184 @@
+/**
+ * Claude Code Hooks Type Definitions
+ * Maps Claude Code hook concepts to OpenCode plugin events
+ */
+
+export type ClaudeHookEvent =
+  | "PreToolUse"
+  | "PostToolUse"
+  | "UserPromptSubmit"
+  | "Stop"
+
+export interface HookMatcher {
+  matcher: string
+  hooks: HookCommand[]
+}
+
+export interface HookCommand {
+  type: "command"
+  command: string
+}
+
+export interface ClaudeHooksConfig {
+  PreToolUse?: HookMatcher[]
+  PostToolUse?: HookMatcher[]
+  UserPromptSubmit?: HookMatcher[]
+  Stop?: HookMatcher[]
+}
+
+export interface PreToolUseInput {
+  session_id: string
+  transcript_path?: string
+  cwd: string
+  permission_mode?: PermissionMode
+  hook_event_name: "PreToolUse"
+  tool_name: string
+  tool_input: Record<string, unknown>
+  tool_use_id?: string
+  hook_source?: HookSource
+}
+
+export interface PostToolUseInput {
+  session_id: string
+  transcript_path?: string
+  cwd: string
+  permission_mode?: PermissionMode
+  hook_event_name: "PostToolUse"
+  tool_name: string
+  tool_input: Record<string, unknown>
+  tool_response: {
+    title?: string
+    output?: string
+    [key: string]: unknown
+  }
+  tool_use_id?: string
+  hook_source?: HookSource
+}
+
+export interface UserPromptSubmitInput {
+  session_id: string
+  cwd: string
+  permission_mode?: PermissionMode
+  hook_event_name: "UserPromptSubmit"
+  prompt: string
+  session?: {
+    id: string
+  }
+  hook_source?: HookSource
+}
+
+export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypassPermissions"
+
+export type HookSource = "opencode-plugin"
+
+export interface StopInput {
+  session_id: string
+  transcript_path?: string
+  cwd: string
+  permission_mode?: PermissionMode
+  hook_event_name: "Stop"
+  stop_hook_active: boolean
+  todo_path?: string
+  hook_source?: HookSource
+}
+
+export type PermissionDecision = "allow" | "deny" | "ask"
+
+/**
+ * Common JSON fields for all hook outputs (Claude Code spec)
+ */
+export interface HookCommonOutput {
+  /** If false, Claude stops entirely */
+  continue?: boolean
+  /** Message shown to user when continue=false */
+  stopReason?: string
+  /** Suppress output from transcript */
+  suppressOutput?: boolean
+  /** Warning/message displayed to user */
+  systemMessage?: string
+}
+
+export interface PreToolUseOutput extends HookCommonOutput {
+  /** Deprecated: use hookSpecificOutput.permissionDecision instead */
+  decision?: "allow" | "deny" | "approve" | "block" | "ask"
+  /** Deprecated: use hookSpecificOutput.permissionDecisionReason instead */
+  reason?: string
+  hookSpecificOutput?: {
+    hookEventName: "PreToolUse"
+    permissionDecision: PermissionDecision
+    permissionDecisionReason?: string
+    updatedInput?: Record<string, unknown>
+  }
+}
+
+export interface PostToolUseOutput extends HookCommonOutput {
+  decision?: "block"
+  reason?: string
+  hookSpecificOutput?: {
+    hookEventName: "PostToolUse"
+    /** Additional context to provide to Claude */
+    additionalContext?: string
+  }
+}
+
+export interface HookResult {
+  exitCode: number
+  stdout?: string
+  stderr?: string
+}
+
+export interface TranscriptEntry {
+  type: "tool_use" | "tool_result" | "user" | "assistant"
+  timestamp: string
+  tool_name?: string
+  tool_input?: Record<string, unknown>
+  tool_output?: Record<string, unknown>
+  content?: string
+}
+
+export interface TodoItem {
+  id: string
+  content: string
+  status: "pending" | "in_progress" | "completed" | "cancelled"
+  priority?: "low" | "medium" | "high"
+  created_at: string
+  updated_at?: string
+}
+
+export interface ClaudeCodeTodoItem {
+  content: string
+  status: string // "pending" | "in_progress" | "completed"
+  activeForm: string
+}
+
+export interface TodoFile {
+  session_id: string
+  items: TodoItem[]
+  created_at: string
+  updated_at: string
+}
+
+export interface StopOutput {
+  decision?: "block" | "continue"
+  reason?: string
+  stop_hook_active?: boolean
+  permission_mode?: PermissionMode
+  inject_prompt?: string
+}
+
+export type ClaudeCodeContent =
+  | { type: "text"; text: string }
+  | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
+  | { type: "tool_result"; tool_use_id: string; content: string }
+
+export interface ClaudeCodeMessage {
+  type: "user" | "assistant"
+  message: {
+    role: "user" | "assistant"
+    content: ClaudeCodeContent[]
+  }
+}
+
+export interface PluginConfig {
+  disabledHooks?: boolean | ClaudeHookEvent[]
+}

src/hooks/claude-code-hooks/user-prompt-submit.ts

@@ -0,0 +1,117 @@
+import type {
+  UserPromptSubmitInput,
+  PostToolUseOutput,
+  ClaudeHooksConfig,
+} from "./types"
+import { findMatchingHooks, executeHookCommand, log } from "../../shared"
+import { DEFAULT_CONFIG } from "./plugin-config"
+import { isHookCommandDisabled, type PluginExtendedConfig } from "./config-loader"
+
+const USER_PROMPT_SUBMIT_TAG_OPEN = "<user-prompt-submit-hook>"
+const USER_PROMPT_SUBMIT_TAG_CLOSE = "</user-prompt-submit-hook>"
+
+export interface MessagePart {
+  type: "text" | "tool_use" | "tool_result"
+  text?: string
+  [key: string]: unknown
+}
+
+export interface UserPromptSubmitContext {
+  sessionId: string
+  parentSessionId?: string
+  prompt: string
+  parts: MessagePart[]
+  cwd: string
+  permissionMode?: "default" | "acceptEdits" | "bypassPermissions"
+}
+
+export interface UserPromptSubmitResult {
+  block: boolean
+  reason?: string
+  modifiedParts: MessagePart[]
+  messages: string[]
+}
+
+export async function executeUserPromptSubmitHooks(
+  ctx: UserPromptSubmitContext,
+  config: ClaudeHooksConfig | null,
+  extendedConfig?: PluginExtendedConfig | null
+): Promise<UserPromptSubmitResult> {
+  const modifiedParts = ctx.parts
+  const messages: string[] = []
+
+  if (ctx.parentSessionId) {
+    return { block: false, modifiedParts, messages }
+  }
+
+  if (
+    ctx.prompt.includes(USER_PROMPT_SUBMIT_TAG_OPEN) &&
+    ctx.prompt.includes(USER_PROMPT_SUBMIT_TAG_CLOSE)
+  ) {
+    return { block: false, modifiedParts, messages }
+  }
+
+  if (!config) {
+    return { block: false, modifiedParts, messages }
+  }
+
+  const matchers = findMatchingHooks(config, "UserPromptSubmit")
+  if (matchers.length === 0) {
+    return { block: false, modifiedParts, messages }
+  }
+
+  const stdinData: UserPromptSubmitInput = {
+    session_id: ctx.sessionId,
+    cwd: ctx.cwd,
+    permission_mode: ctx.permissionMode ?? "bypassPermissions",
+    hook_event_name: "UserPromptSubmit",
+    prompt: ctx.prompt,
+    session: { id: ctx.sessionId },
+    hook_source: "opencode-plugin",
+  }
+
+  for (const matcher of matchers) {
+    for (const hook of matcher.hooks) {
+      if (hook.type !== "command") continue
+
+      if (isHookCommandDisabled("UserPromptSubmit", hook.command, extendedConfig ?? null)) {
+        log("UserPromptSubmit hook command skipped (disabled by config)", { command: hook.command })
+        continue
+      }
+
+      const result = await executeHookCommand(
+        hook.command,
+        JSON.stringify(stdinData),
+        ctx.cwd,
+        { forceZsh: DEFAULT_CONFIG.forceZsh, zshPath: DEFAULT_CONFIG.zshPath }
+      )
+
+      if (result.stdout) {
+        const output = result.stdout.trim()
+        if (output.startsWith(USER_PROMPT_SUBMIT_TAG_OPEN)) {
+          messages.push(output)
+        } else {
+          messages.push(`${USER_PROMPT_SUBMIT_TAG_OPEN}\n${output}\n${USER_PROMPT_SUBMIT_TAG_CLOSE}`)
+        }
+      }
+
+      if (result.exitCode !== 0) {
+        try {
+          const output = JSON.parse(result.stdout || "{}") as PostToolUseOutput
+          if (output.decision === "block") {
+            return {
+              block: true,
+              reason: output.reason || result.stderr,
+              modifiedParts,
+              messages,
+            }
+          }
+         } catch {
+          // Ignore JSON parse errors
+         }
+      }
+    }
+  }
+
+  return { block: false, modifiedParts, messages }
+}

src/hooks/comment-checker/cli.ts

@@ -0,0 +1,210 @@
+import { spawn } from "bun"
+import { createRequire } from "module"
+import { dirname, join } from "path"
+import { existsSync } from "fs"
+import * as fs from "fs"
+import { getCachedBinaryPath, ensureCommentCheckerBinary } from "./downloader"
+
+const DEBUG = process.env.COMMENT_CHECKER_DEBUG === "1"
+const DEBUG_FILE = "/tmp/comment-checker-debug.log"
+
+function debugLog(...args: unknown[]) {
+  if (DEBUG) {
+    const msg = `[${new Date().toISOString()}] [comment-checker:cli] ${args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')}\n`
+    fs.appendFileSync(DEBUG_FILE, msg)
+  }
+}
+
+function getBinaryName(): string {
+  return process.platform === "win32" ? "comment-checker.exe" : "comment-checker"
+}
+
+function findCommentCheckerPathSync(): string | null {
+  const binaryName = getBinaryName()
+
+  try {
+    const require = createRequire(import.meta.url)
+    const cliPkgPath = require.resolve("@code-yeongyu/comment-checker/package.json")
+    const cliDir = dirname(cliPkgPath)
+    const binaryPath = join(cliDir, "bin", binaryName)
+
+    if (existsSync(binaryPath)) {
+      debugLog("found binary in main package:", binaryPath)
+      return binaryPath
+    }
+  } catch {
+    debugLog("main package not installed")
+  }
+
+  const cachedPath = getCachedBinaryPath()
+  if (cachedPath) {
+    debugLog("found binary in cache:", cachedPath)
+    return cachedPath
+  }
+
+  debugLog("no binary found in known locations")
+  return null
+}
+
+// Cached resolved path
+let resolvedCliPath: string | null = null
+let initPromise: Promise<string | null> | null = null
+
+/**
+ * Asynchronously get comment-checker binary path.
+ * Will trigger lazy download if binary not found.
+ */
+export async function getCommentCheckerPath(): Promise<string | null> {
+  // Return cached path if already resolved
+  if (resolvedCliPath !== null) {
+    return resolvedCliPath
+  }
+
+  // Return existing promise if initialization is in progress
+  if (initPromise) {
+    return initPromise
+  }
+
+  initPromise = (async () => {
+    // First try sync path resolution
+    const syncPath = findCommentCheckerPathSync()
+    if (syncPath && existsSync(syncPath)) {
+      resolvedCliPath = syncPath
+      debugLog("using sync-resolved path:", syncPath)
+      return syncPath
+    }
+
+    // Lazy download if not found
+    debugLog("triggering lazy download...")
+    const downloadedPath = await ensureCommentCheckerBinary()
+    if (downloadedPath) {
+      resolvedCliPath = downloadedPath
+      debugLog("using downloaded path:", downloadedPath)
+      return downloadedPath
+    }
+
+    debugLog("no binary available")
+    return null
+  })()
+
+  return initPromise
+}
+
+/**
+ * Synchronously get comment-checker path (no download).
+ * Returns cached path or searches known locations.
+ */
+export function getCommentCheckerPathSync(): string | null {
+  return resolvedCliPath ?? findCommentCheckerPathSync()
+}
+
+/**
+ * Start background initialization.
+ * Call this early to trigger download while other init happens.
+ */
+export function startBackgroundInit(): void {
+  if (!initPromise) {
+    initPromise = getCommentCheckerPath()
+    initPromise.then(path => {
+      debugLog("background init complete:", path || "no binary")
+    }).catch(err => {
+      debugLog("background init error:", err)
+    })
+  }
+}
+
+// Legacy export for backwards compatibility (sync, no download)
+export const COMMENT_CHECKER_CLI_PATH = findCommentCheckerPathSync()
+
+export interface HookInput {
+  session_id: string
+  tool_name: string
+  transcript_path: string
+  cwd: string
+  hook_event_name: string
+  tool_input: {
+    file_path?: string
+    content?: string
+    old_string?: string
+    new_string?: string
+    edits?: Array<{ old_string: string; new_string: string }>
+  }
+  tool_response?: unknown
+}
+
+export interface CheckResult {
+  hasComments: boolean
+  message: string
+}
+
+/**
+ * Run comment-checker CLI with given input.
+ * @param input Hook input to check
+ * @param cliPath Optional explicit path to CLI binary
+ */
+export async function runCommentChecker(input: HookInput, cliPath?: string): Promise<CheckResult> {
+  const binaryPath = cliPath ?? resolvedCliPath ?? COMMENT_CHECKER_CLI_PATH
+  
+  if (!binaryPath) {
+    debugLog("comment-checker binary not found")
+    return { hasComments: false, message: "" }
+  }
+
+  if (!existsSync(binaryPath)) {
+    debugLog("comment-checker binary does not exist:", binaryPath)
+    return { hasComments: false, message: "" }
+  }
+
+  const jsonInput = JSON.stringify(input)
+  debugLog("running comment-checker with input:", jsonInput.substring(0, 200))
+
+  try {
+    const proc = spawn([binaryPath], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+
+    // Write JSON to stdin
+    proc.stdin.write(jsonInput)
+    proc.stdin.end()
+
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    const exitCode = await proc.exited
+
+    debugLog("exit code:", exitCode, "stdout length:", stdout.length, "stderr length:", stderr.length)
+
+    if (exitCode === 0) {
+      return { hasComments: false, message: "" }
+    }
+
+    if (exitCode === 2) {
+      // Comments detected - message is in stderr
+      return { hasComments: true, message: stderr }
+    }
+
+    // Error case
+    debugLog("unexpected exit code:", exitCode, "stderr:", stderr)
+    return { hasComments: false, message: "" }
+  } catch (err) {
+    debugLog("failed to run comment-checker:", err)
+    return { hasComments: false, message: "" }
+  }
+}
+
+/**
+ * Check if CLI is available (sync check, no download).
+ */
+export function isCliAvailable(): boolean {
+  const path = getCommentCheckerPathSync()
+  return path !== null && existsSync(path)
+}
+
+/**
+ * Check if CLI will be available (async, may trigger download).
+ */
+export async function ensureCliAvailable(): Promise<boolean> {
+  const path = await getCommentCheckerPath()
+  return path !== null && existsSync(path)
+}

src/hooks/comment-checker/constants.ts

@@ -1,117 +1,3 @@
-import type { LanguageConfig } from "./types"
-
-export const EXTENSION_TO_LANGUAGE: Record<string, string> = {
-  py: "python",
-  js: "javascript",
-  jsx: "javascript",
-  ts: "typescript",
-  tsx: "tsx",
-  go: "golang",
-  java: "java",
-  kt: "kotlin",
-  scala: "scala",
-  c: "c",
-  h: "c",
-  cpp: "cpp",
-  cc: "cpp",
-  cxx: "cpp",
-  hpp: "cpp",
-  rs: "rust",
-  rb: "ruby",
-  sh: "bash",
-  bash: "bash",
-  cs: "csharp",
-  swift: "swift",
-  ex: "elixir",
-  exs: "elixir",
-  lua: "lua",
-  php: "php",
-  ml: "ocaml",
-  mli: "ocaml",
-  sql: "sql",
-  html: "html",
-  htm: "html",
-  css: "css",
-  yaml: "yaml",
-  yml: "yaml",
-  toml: "toml",
-  hcl: "hcl",
-  tf: "hcl",
-  dockerfile: "dockerfile",
-  proto: "protobuf",
-  svelte: "svelte",
-  elm: "elm",
-  groovy: "groovy",
-  cue: "cue",
-}
-
-export const QUERY_TEMPLATES: Record<string, string> = {
-  python: "(comment) @comment",
-  javascript: "(comment) @comment",
-  typescript: "(comment) @comment",
-  tsx: "(comment) @comment",
-  golang: "(comment) @comment",
-  rust: `
-    (line_comment) @comment
-    (block_comment) @comment
-  `,
-  kotlin: `
-    (line_comment) @comment
-    (multiline_comment) @comment
-  `,
-  java: `
-    (line_comment) @comment
-    (block_comment) @comment
-  `,
-  c: "(comment) @comment",
-  cpp: "(comment) @comment",
-  csharp: "(comment) @comment",
-  ruby: "(comment) @comment",
-  bash: "(comment) @comment",
-  swift: "(comment) @comment",
-  elixir: "(comment) @comment",
-  lua: "(comment) @comment",
-  php: "(comment) @comment",
-  ocaml: "(comment) @comment",
-  sql: "(comment) @comment",
-  html: "(comment) @comment",
-  css: "(comment) @comment",
-  yaml: "(comment) @comment",
-  toml: "(comment) @comment",
-  hcl: "(comment) @comment",
-  dockerfile: "(comment) @comment",
-  protobuf: "(comment) @comment",
-  svelte: "(comment) @comment",
-  elm: "(comment) @comment",
-  groovy: "(comment) @comment",
-  cue: "(comment) @comment",
-  scala: "(comment) @comment",
-}
-
-export const DOCSTRING_QUERIES: Record<string, string> = {
-  python: `
-    (module . (expression_statement (string) @docstring))
-    (class_definition body: (block . (expression_statement (string) @docstring)))
-    (function_definition body: (block . (expression_statement (string) @docstring)))
-  `,
-  javascript: `
-    (comment) @jsdoc
-    (#match? @jsdoc "^/\\\\*\\\\*")
-  `,
-  typescript: `
-    (comment) @jsdoc
-    (#match? @jsdoc "^/\\\\*\\\\*")
-  `,
-  tsx: `
-    (comment) @jsdoc
-    (#match? @jsdoc "^/\\\\*\\\\*")
-  `,
-  java: `
-    (comment) @javadoc
-    (#match? @javadoc "^/\\\\*\\\\*")
-  `,
-}
-
 export const BDD_KEYWORDS = new Set([
   "given",
   "when",
@@ -186,19 +72,12 @@ PRIORITY-BASED ACTION GUIDELINES:
 \t-> Make the code itself clearer so it can be understood without comments/docstrings.
 \t-> For verbose docstrings: refactor code to be self-documenting instead of adding lengthy explanations.
 
+CODE SMELL WARNING: Using comments as visual separators (e.g., "// =========", "# ---", "// *** Section ***")
+is a code smell. If you need separators, your file is too long or poorly organized.
+Refactor into smaller modules or use proper code organization instead of comment-based section dividers.
+
 MANDATORY REQUIREMENT: You must acknowledge this hook message and take one of the above actions.
 Review in the above priority order and take the corresponding action EVERY TIME this appears.
 
 Detected comments/docstrings:
 `
-
-export function getLanguageByExtension(filePath: string): string | null {
-  const lastDot = filePath.lastIndexOf(".")
-  if (lastDot === -1) {
-    const baseName = filePath.split("/").pop()?.toLowerCase()
-    if (baseName === "dockerfile") return "dockerfile"
-    return null
-  }
-  const ext = filePath.slice(lastDot + 1).toLowerCase()
-  return EXTENSION_TO_LANGUAGE[ext] ?? null
-}

src/hooks/comment-checker/detector.ts

@@ -1,314 +0,0 @@
-import type { CommentInfo, CommentType } from "./types"
-import { getLanguageByExtension, QUERY_TEMPLATES, DOCSTRING_QUERIES } from "./constants"
-import * as fs from "fs"
-
-// =============================================================================
-// Debug logging
-// =============================================================================
-
-const DEBUG = process.env.COMMENT_CHECKER_DEBUG === "1"
-const DEBUG_FILE = "/tmp/comment-checker-debug.log"
-
-function debugLog(...args: unknown[]) {
-  if (DEBUG) {
-    const msg = `[${new Date().toISOString()}] [comment-checker:detector] ${args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')}\n`
-    fs.appendFileSync(DEBUG_FILE, msg)
-  }
-}
-
-// =============================================================================
-// Parser Manager (LSP-style background initialization)
-// =============================================================================
-
-interface ManagedLanguage {
-  language: unknown
-  initPromise?: Promise<unknown>
-  isInitializing: boolean
-  lastUsedAt: number
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let parserClass: any = null
-let parserInitPromise: Promise<void> | null = null
-const languageCache = new Map<string, ManagedLanguage>()
-
-const LANGUAGE_NAME_MAP: Record<string, string> = {
-  golang: "go",
-  csharp: "c_sharp",
-  cpp: "cpp",
-}
-
-const COMMON_LANGUAGES = [
-  "python",
-  "typescript",
-  "javascript",
-  "tsx",
-  "go",
-  "rust",
-  "java",
-]
-
-async function initParserClass(): Promise<void> {
-  if (parserClass) return
-  
-  if (parserInitPromise) {
-    await parserInitPromise
-    return
-  }
-  
-  parserInitPromise = (async () => {
-    debugLog("importing web-tree-sitter...")
-    parserClass = (await import("web-tree-sitter")).default
-    const treeSitterWasmPath = require.resolve("web-tree-sitter/tree-sitter.wasm")
-    debugLog("wasm path:", treeSitterWasmPath)
-    await parserClass.init({
-      locateFile: () => treeSitterWasmPath,
-    })
-    debugLog("Parser class initialized")
-  })()
-  
-  await parserInitPromise
-}
-
-async function getParser() {
-  await initParserClass()
-  return new parserClass()
-}
-
-async function loadLanguageWasm(langName: string): Promise<unknown | null> {
-  const mappedLang = LANGUAGE_NAME_MAP[langName] || langName
-  
-  try {
-    const wasmModule = await import(`tree-sitter-wasms/out/tree-sitter-${langName}.wasm`)
-    return wasmModule.default
-  } catch {
-    if (mappedLang !== langName) {
-      try {
-        const wasmModule = await import(`tree-sitter-wasms/out/tree-sitter-${mappedLang}.wasm`)
-        return wasmModule.default
-      } catch {
-        return null
-      }
-    }
-    return null
-  }
-}
-
-async function getLanguage(langName: string): Promise<unknown | null> {
-  const cached = languageCache.get(langName)
-  
-  if (cached) {
-    if (cached.initPromise) {
-      await cached.initPromise
-    }
-    cached.lastUsedAt = Date.now()
-    debugLog("using cached language:", langName)
-    return cached.language
-  }
-  
-  debugLog("loading language wasm:", langName)
-  
-  const initPromise = (async () => {
-    await initParserClass()
-    const wasmPath = await loadLanguageWasm(langName)
-    if (!wasmPath) {
-      debugLog("failed to load language wasm:", langName)
-      return null
-    }
-    return await parserClass!.Language.load(wasmPath)
-  })()
-  
-  languageCache.set(langName, {
-    language: null as unknown,
-    initPromise,
-    isInitializing: true,
-    lastUsedAt: Date.now(),
-  })
-  
-  const language = await initPromise
-  const managed = languageCache.get(langName)
-  if (managed) {
-    managed.language = language
-    managed.initPromise = undefined
-    managed.isInitializing = false
-  }
-  
-  debugLog("language loaded and cached:", langName)
-  return language
-}
-
-function warmupLanguage(langName: string): void {
-  if (languageCache.has(langName)) return
-  
-  debugLog("warming up language (background):", langName)
-  
-  const initPromise = (async () => {
-    await initParserClass()
-    const wasmPath = await loadLanguageWasm(langName)
-    if (!wasmPath) return null
-    return await parserClass!.Language.load(wasmPath)
-  })()
-  
-  languageCache.set(langName, {
-    language: null as unknown,
-    initPromise,
-    isInitializing: true,
-    lastUsedAt: Date.now(),
-  })
-  
-  initPromise.then((language) => {
-    const managed = languageCache.get(langName)
-    if (managed) {
-      managed.language = language
-      managed.initPromise = undefined
-      managed.isInitializing = false
-      debugLog("warmup complete:", langName)
-    }
-  }).catch((err) => {
-    debugLog("warmup failed:", langName, err)
-    languageCache.delete(langName)
-  })
-}
-
-export function warmupCommonLanguages(): void {
-  debugLog("starting background warmup for common languages...")
-  initParserClass().then(() => {
-    for (const lang of COMMON_LANGUAGES) {
-      warmupLanguage(lang)
-    }
-  }).catch((err) => {
-    debugLog("warmup initialization failed:", err)
-  })
-}
-
-// =============================================================================
-// Public API
-// =============================================================================
-
-export function isSupportedFile(filePath: string): boolean {
-  return getLanguageByExtension(filePath) !== null
-}
-
-function determineCommentType(text: string, nodeType: string): CommentType {
-  const stripped = text.trim()
-
-  if (nodeType === "line_comment") {
-    return "line"
-  }
-  if (nodeType === "block_comment" || nodeType === "multiline_comment") {
-    return "block"
-  }
-
-  if (stripped.startsWith('"""') || stripped.startsWith("'''")) {
-    return "docstring"
-  }
-
-  if (stripped.startsWith("//") || stripped.startsWith("#")) {
-    return "line"
-  }
-
-  if (stripped.startsWith("/*") || stripped.startsWith("<!--") || stripped.startsWith("--")) {
-    return "block"
-  }
-
-  return "line"
-}
-
-export async function detectComments(
-  filePath: string,
-  content: string,
-  includeDocstrings = true
-): Promise<CommentInfo[]> {
-  debugLog("detectComments called:", { filePath, contentLength: content.length })
-  
-  const langName = getLanguageByExtension(filePath)
-  if (!langName) {
-    debugLog("unsupported language for:", filePath)
-    return []
-  }
-
-  const queryPattern = QUERY_TEMPLATES[langName]
-  if (!queryPattern) {
-    debugLog("no query pattern for:", langName)
-    return []
-  }
-
-  try {
-    const parser = await getParser()
-    const language = await getLanguage(langName)
-    
-    if (!language) {
-      debugLog("language not available:", langName)
-      return []
-    }
-
-    parser.setLanguage(language)
-    const tree = parser.parse(content)
-    const comments: CommentInfo[] = []
-
-    const query = (language as { query: (pattern: string) => { matches: (node: unknown) => Array<{ captures: Array<{ node: { text: string; type: string; startPosition: { row: number } } }> }> } }).query(queryPattern)
-    const matches = query.matches(tree.rootNode)
-
-    for (const match of matches) {
-      for (const capture of match.captures) {
-        const node = capture.node
-        const text = node.text
-        const lineNumber = node.startPosition.row + 1
-
-        const commentType = determineCommentType(text, node.type)
-        const isDocstring = commentType === "docstring"
-
-        if (isDocstring && !includeDocstrings) {
-          continue
-        }
-
-        comments.push({
-          text,
-          lineNumber,
-          filePath,
-          commentType,
-          isDocstring,
-        })
-      }
-    }
-
-    if (includeDocstrings) {
-      const docQuery = DOCSTRING_QUERIES[langName]
-      if (docQuery) {
-        try {
-          const docQueryObj = (language as { query: (pattern: string) => { matches: (node: unknown) => Array<{ captures: Array<{ node: { text: string; startPosition: { row: number } } }> }> } }).query(docQuery)
-          const docMatches = docQueryObj.matches(tree.rootNode)
-
-          for (const match of docMatches) {
-            for (const capture of match.captures) {
-              const node = capture.node
-              const text = node.text
-              const lineNumber = node.startPosition.row + 1
-
-              const alreadyAdded = comments.some(
-                (c) => c.lineNumber === lineNumber && c.text === text
-              )
-              if (!alreadyAdded) {
-                comments.push({
-                  text,
-                  lineNumber,
-                  filePath,
-                  commentType: "docstring",
-                  isDocstring: true,
-                })
-              }
-            }
-          }
-        } catch {}
-      }
-    }
-
-    comments.sort((a, b) => a.lineNumber - b.lineNumber)
-
-    debugLog("detected comments:", comments.length)
-    return comments
-  } catch (err) {
-    debugLog("detectComments failed:", err)
-    return []
-  }
-}

src/hooks/comment-checker/downloader.ts

@@ -0,0 +1,210 @@
+import { spawn } from "bun"
+import { existsSync, mkdirSync, chmodSync, unlinkSync, appendFileSync } from "fs"
+import { join } from "path"
+import { homedir } from "os"
+import { createRequire } from "module"
+
+const DEBUG = process.env.COMMENT_CHECKER_DEBUG === "1"
+const DEBUG_FILE = "/tmp/comment-checker-debug.log"
+
+function debugLog(...args: unknown[]) {
+  if (DEBUG) {
+    const msg = `[${new Date().toISOString()}] [comment-checker:downloader] ${args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')}\n`
+    appendFileSync(DEBUG_FILE, msg)
+  }
+}
+
+const REPO = "code-yeongyu/go-claude-code-comment-checker"
+
+interface PlatformInfo {
+  os: string
+  arch: string
+  ext: "tar.gz" | "zip"
+}
+
+const PLATFORM_MAP: Record<string, PlatformInfo> = {
+  "darwin-arm64": { os: "darwin", arch: "arm64", ext: "tar.gz" },
+  "darwin-x64": { os: "darwin", arch: "amd64", ext: "tar.gz" },
+  "linux-arm64": { os: "linux", arch: "arm64", ext: "tar.gz" },
+  "linux-x64": { os: "linux", arch: "amd64", ext: "tar.gz" },
+  "win32-x64": { os: "windows", arch: "amd64", ext: "zip" },
+}
+
+/**
+ * Get the cache directory for oh-my-opencode binaries.
+ * Follows XDG Base Directory Specification.
+ */
+export function getCacheDir(): string {
+  const xdgCache = process.env.XDG_CACHE_HOME
+  const base = xdgCache || join(homedir(), ".cache")
+  return join(base, "oh-my-opencode", "bin")
+}
+
+/**
+ * Get the binary name based on platform.
+ */
+export function getBinaryName(): string {
+  return process.platform === "win32" ? "comment-checker.exe" : "comment-checker"
+}
+
+/**
+ * Get the cached binary path if it exists.
+ */
+export function getCachedBinaryPath(): string | null {
+  const binaryPath = join(getCacheDir(), getBinaryName())
+  return existsSync(binaryPath) ? binaryPath : null
+}
+
+/**
+ * Get the version from the installed @code-yeongyu/comment-checker package.
+ */
+function getPackageVersion(): string {
+  try {
+    const require = createRequire(import.meta.url)
+    const pkg = require("@code-yeongyu/comment-checker/package.json")
+    return pkg.version
+  } catch {
+    // Fallback to hardcoded version if package not found
+    return "0.4.1"
+  }
+}
+
+/**
+ * Extract tar.gz archive using system tar command.
+ */
+async function extractTarGz(archivePath: string, destDir: string): Promise<void> {
+  debugLog("Extracting tar.gz:", archivePath, "to", destDir)
+  
+  const proc = spawn(["tar", "-xzf", archivePath, "-C", destDir], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  
+  const exitCode = await proc.exited
+  
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    throw new Error(`tar extraction failed (exit ${exitCode}): ${stderr}`)
+  }
+}
+
+/**
+ * Extract zip archive using system commands.
+ */
+async function extractZip(archivePath: string, destDir: string): Promise<void> {
+  debugLog("Extracting zip:", archivePath, "to", destDir)
+  
+  const proc = process.platform === "win32"
+    ? spawn(["powershell", "-command", `Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force`], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+    : spawn(["unzip", "-o", archivePath, "-d", destDir], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+  
+  const exitCode = await proc.exited
+  
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    throw new Error(`zip extraction failed (exit ${exitCode}): ${stderr}`)
+  }
+}
+
+/**
+ * Download the comment-checker binary from GitHub Releases.
+ * Returns the path to the downloaded binary, or null on failure.
+ */
+export async function downloadCommentChecker(): Promise<string | null> {
+  const platformKey = `${process.platform}-${process.arch}`
+  const platformInfo = PLATFORM_MAP[platformKey]
+  
+  if (!platformInfo) {
+    debugLog(`Unsupported platform: ${platformKey}`)
+    return null
+  }
+  
+  const cacheDir = getCacheDir()
+  const binaryName = getBinaryName()
+  const binaryPath = join(cacheDir, binaryName)
+  
+  // Already exists in cache
+  if (existsSync(binaryPath)) {
+    debugLog("Binary already cached at:", binaryPath)
+    return binaryPath
+  }
+  
+  const version = getPackageVersion()
+  const { os, arch, ext } = platformInfo
+  const assetName = `comment-checker_v${version}_${os}_${arch}.${ext}`
+  const downloadUrl = `https://github.com/${REPO}/releases/download/v${version}/${assetName}`
+  
+  debugLog(`Downloading from: ${downloadUrl}`)
+  console.log(`[oh-my-opencode] Downloading comment-checker binary...`)
+  
+  try {
+    // Ensure cache directory exists
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true })
+    }
+    
+    // Download with fetch() - Bun handles redirects automatically
+    const response = await fetch(downloadUrl, { redirect: "follow" })
+    
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+    }
+    
+    const archivePath = join(cacheDir, assetName)
+    const arrayBuffer = await response.arrayBuffer()
+    await Bun.write(archivePath, arrayBuffer)
+    
+    debugLog(`Downloaded archive to: ${archivePath}`)
+    
+    // Extract based on file type
+    if (ext === "tar.gz") {
+      await extractTarGz(archivePath, cacheDir)
+    } else {
+      await extractZip(archivePath, cacheDir)
+    }
+    
+    // Clean up archive
+    if (existsSync(archivePath)) {
+      unlinkSync(archivePath)
+    }
+    
+    // Set execute permission on Unix
+    if (process.platform !== "win32" && existsSync(binaryPath)) {
+      chmodSync(binaryPath, 0o755)
+    }
+    
+    debugLog(`Successfully downloaded binary to: ${binaryPath}`)
+    console.log(`[oh-my-opencode] comment-checker binary ready.`)
+    
+    return binaryPath
+    
+  } catch (err) {
+    debugLog(`Failed to download: ${err}`)
+    console.error(`[oh-my-opencode] Failed to download comment-checker: ${err instanceof Error ? err.message : err}`)
+    console.error(`[oh-my-opencode] Comment checking disabled.`)
+    return null
+  }
+}
+
+/**
+ * Ensure the comment-checker binary is available.
+ * First checks cache, then downloads if needed.
+ * Returns the binary path or null if unavailable.
+ */
+export async function ensureCommentCheckerBinary(): Promise<string | null> {
+  // Check cache first
+  const cachedPath = getCachedBinaryPath()
+  if (cachedPath) {
+    debugLog("Using cached binary:", cachedPath)
+    return cachedPath
+  }
+  
+  // Download if not cached
+  return downloadCommentChecker()
+}

src/hooks/comment-checker/index.ts

@@ -1,9 +1,8 @@
-import type { PendingCall, FileComments } from "./types"
-import { detectComments, isSupportedFile, warmupCommonLanguages } from "./detector"
-import { applyFilters } from "./filters"
-import { formatHookMessage } from "./output"
+import type { PendingCall } from "./types"
+import { runCommentChecker, getCommentCheckerPath, startBackgroundInit, type HookInput } from "./cli"
 
 import * as fs from "fs"
+import { existsSync } from "fs"
 
 const DEBUG = process.env.COMMENT_CHECKER_DEBUG === "1"
 const DEBUG_FILE = "/tmp/comment-checker-debug.log"
@@ -18,6 +17,8 @@ function debugLog(...args: unknown[]) {
 const pendingCalls = new Map<string, PendingCall>()
 const PENDING_CALL_TTL = 60_000
 
+let cliPathPromise: Promise<string | null> | null = null
+
 function cleanupOldPendingCalls(): void {
   const now = Date.now()
   for (const [callID, call] of pendingCalls) {
@@ -32,8 +33,14 @@ setInterval(cleanupOldPendingCalls, 10_000)
 export function createCommentCheckerHooks() {
   debugLog("createCommentCheckerHooks called")
   
-  // Background warmup - LSP style (non-blocking)
-  warmupCommonLanguages()
+  // Start background CLI initialization (may trigger lazy download)
+  startBackgroundInit()
+  cliPathPromise = getCommentCheckerPath()
+  cliPathPromise.then(path => {
+    debugLog("CLI path resolved:", path || "disabled (no binary)")
+  }).catch(err => {
+    debugLog("CLI path resolution error:", err)
+  })
   
   return {
     "tool.execute.before": async (
@@ -50,6 +57,9 @@ export function createCommentCheckerHooks() {
 
       const filePath = (output.args.filePath ?? output.args.file_path ?? output.args.path) as string | undefined
       const content = output.args.content as string | undefined
+      const oldString = output.args.oldString ?? output.args.old_string as string | undefined
+      const newString = output.args.newString ?? output.args.new_string as string | undefined
+      const edits = output.args.edits as Array<{ old_string: string; new_string: string }> | undefined
 
       debugLog("extracted filePath:", filePath)
 
@@ -58,15 +68,13 @@ export function createCommentCheckerHooks() {
         return
       }
 
-      if (!isSupportedFile(filePath)) {
-        debugLog("unsupported file:", filePath)
-        return
-      }
-
       debugLog("registering pendingCall:", { callID: input.callID, filePath, tool: toolLower })
       pendingCalls.set(input.callID, {
         filePath,
         content,
+        oldString: oldString as string | undefined,
+        newString: newString as string | undefined,
+        edits,
         tool: toolLower as "write" | "edit" | "multiedit",
         sessionID: input.sessionID,
         timestamp: Date.now(),
@@ -89,7 +97,6 @@ export function createCommentCheckerHooks() {
       debugLog("processing pendingCall:", pendingCall)
 
       // Only skip if the output indicates a tool execution failure
-      // (not LSP warnings/errors or other incidental "error" strings)
       const outputLower = output.output.toLowerCase()
       const isToolFailure = 
         outputLower.includes("error:") || 
@@ -103,40 +110,18 @@ export function createCommentCheckerHooks() {
       }
 
       try {
-        let content: string
-
-        if (pendingCall.content) {
-          content = pendingCall.content
-          debugLog("using content from args")
-        } else {
-          debugLog("reading file:", pendingCall.filePath)
-          const file = Bun.file(pendingCall.filePath)
-          content = await file.text()
-          debugLog("file content length:", content.length)
-        }
-
-        debugLog("calling detectComments...")
-        const rawComments = await detectComments(pendingCall.filePath, content)
-        debugLog("raw comments:", rawComments.length)
+        // Wait for CLI path resolution
+        const cliPath = await cliPathPromise
         
-        const filteredComments = applyFilters(rawComments)
-        debugLog("filtered comments:", filteredComments.length)
-
-        if (filteredComments.length === 0) {
-          debugLog("no comments after filtering")
+        if (!cliPath || !existsSync(cliPath)) {
+          // CLI not available - silently skip comment checking
+          debugLog("CLI not available, skipping comment check")
           return
         }
-
-        const fileComments: FileComments[] = [
-          {
-            filePath: pendingCall.filePath,
-            comments: filteredComments,
-          },
-        ]
-
-        const message = formatHookMessage(fileComments)
-        debugLog("appending message to output")
-        output.output += `\n\n${message}`
+        
+        // CLI mode only
+        debugLog("using CLI:", cliPath)
+        await processWithCli(input, pendingCall, output, cliPath)
       } catch (err) {
         debugLog("tool.execute.after failed:", err)
       }
@@ -144,4 +129,35 @@ export function createCommentCheckerHooks() {
   }
 }
 
-
+async function processWithCli(
+  input: { tool: string; sessionID: string; callID: string },
+  pendingCall: PendingCall,
+  output: { output: string },
+  cliPath: string
+): Promise<void> {
+  debugLog("using CLI mode with path:", cliPath)
+  
+  const hookInput: HookInput = {
+    session_id: pendingCall.sessionID,
+    tool_name: pendingCall.tool.charAt(0).toUpperCase() + pendingCall.tool.slice(1),
+    transcript_path: "",
+    cwd: process.cwd(),
+    hook_event_name: "PostToolUse",
+    tool_input: {
+      file_path: pendingCall.filePath,
+      content: pendingCall.content,
+      old_string: pendingCall.oldString,
+      new_string: pendingCall.newString,
+      edits: pendingCall.edits,
+    },
+  }
+  
+  const result = await runCommentChecker(hookInput, cliPath)
+  
+  if (result.hasComments && result.message) {
+    debugLog("CLI detected comments, appending message")
+    output.output += `\n\n${result.message}`
+  } else {
+    debugLog("CLI: no comments detected")
+  }
+}

src/hooks/comment-checker/types.ts

@@ -9,15 +9,12 @@ export interface CommentInfo {
   metadata?: Record<string, string>
 }
 
-export interface LanguageConfig {
-  extensions: string[]
-  commentQuery: string
-  docstringQuery?: string
-}
-
 export interface PendingCall {
   filePath: string
   content?: string
+  oldString?: string
+  newString?: string
+  edits?: Array<{ old_string: string; new_string: string }>
   tool: "write" | "edit" | "multiedit"
   sessionID: string
   timestamp: number

src/hooks/context-window-monitor.ts

@@ -7,16 +7,8 @@ const CONTEXT_WARNING_THRESHOLD = 0.70
 const CONTEXT_REMINDER = `[SYSTEM REMINDER - 1M Context Window]
 
 You are using Anthropic Claude with 1M context window.
-Current usage has exceeded 75%.
-
-RECOMMENDATIONS:
-- Consider compacting the session if available
-- Break complex tasks into smaller, focused sessions
-- Be concise in your responses
-- Avoid redundant file reads
-
-You have access to 1M tokens - use them wisely. Do NOT rush or skip tasks.
-Complete your work thoroughly despite the context usage warning.`
+You have plenty of context remaining - do NOT rush or skip tasks.
+Complete your work thoroughly and methodically.`
 
 interface AssistantMessageInfo {
   role: "assistant"

src/hooks/directory-agents-injector/constants.ts

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+import { xdgData } from "xdg-basedir";
+
+export const OPENCODE_STORAGE = join(xdgData ?? "", "opencode", "storage");
+export const AGENTS_INJECTOR_STORAGE = join(
+  OPENCODE_STORAGE,
+  "directory-agents",
+);
+export const AGENTS_FILENAME = "AGENTS.md";

src/hooks/directory-agents-injector/index.ts

@@ -0,0 +1,126 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  loadInjectedPaths,
+  saveInjectedPaths,
+  clearInjectedPaths,
+} from "./storage";
+import { AGENTS_FILENAME } from "./constants";
+
+interface ToolExecuteInput {
+  tool: string;
+  sessionID: string;
+  callID: string;
+}
+
+interface ToolExecuteOutput {
+  title: string;
+  output: string;
+  metadata: unknown;
+}
+
+interface EventInput {
+  event: {
+    type: string;
+    properties?: unknown;
+  };
+}
+
+export function createDirectoryAgentsInjectorHook(ctx: PluginInput) {
+  const sessionCaches = new Map<string, Set<string>>();
+
+  function getSessionCache(sessionID: string): Set<string> {
+    if (!sessionCaches.has(sessionID)) {
+      sessionCaches.set(sessionID, loadInjectedPaths(sessionID));
+    }
+    return sessionCaches.get(sessionID)!;
+  }
+
+  function resolveFilePath(title: string): string | null {
+    if (!title) return null;
+    if (title.startsWith("/")) return title;
+    return resolve(ctx.directory, title);
+  }
+
+  function findAgentsMdUp(startDir: string): string[] {
+    const found: string[] = [];
+    let current = startDir;
+
+    while (true) {
+      const agentsPath = join(current, AGENTS_FILENAME);
+      if (existsSync(agentsPath)) {
+        found.push(agentsPath);
+      }
+
+      if (current === ctx.directory) break;
+      const parent = dirname(current);
+      if (parent === current) break;
+      if (!parent.startsWith(ctx.directory)) break;
+      current = parent;
+    }
+
+    return found.reverse();
+  }
+
+  const toolExecuteAfter = async (
+    input: ToolExecuteInput,
+    output: ToolExecuteOutput,
+  ) => {
+    if (input.tool.toLowerCase() !== "read") return;
+
+    const filePath = resolveFilePath(output.title);
+    if (!filePath) return;
+
+    const dir = dirname(filePath);
+    const cache = getSessionCache(input.sessionID);
+    const agentsPaths = findAgentsMdUp(dir);
+
+    const toInject: { path: string; content: string }[] = [];
+
+    for (const agentsPath of agentsPaths) {
+      const agentsDir = dirname(agentsPath);
+      if (cache.has(agentsDir)) continue;
+
+      try {
+        const content = readFileSync(agentsPath, "utf-8");
+        toInject.push({ path: agentsPath, content });
+        cache.add(agentsDir);
+      } catch {}
+    }
+
+    if (toInject.length === 0) return;
+
+    for (const { path, content } of toInject) {
+      output.output += `\n\n[Directory Context: ${path}]\n${content}`;
+    }
+
+    saveInjectedPaths(input.sessionID, cache);
+  };
+
+  const eventHandler = async ({ event }: EventInput) => {
+    const props = event.properties as Record<string, unknown> | undefined;
+
+    if (event.type === "session.deleted") {
+      const sessionInfo = props?.info as { id?: string } | undefined;
+      if (sessionInfo?.id) {
+        sessionCaches.delete(sessionInfo.id);
+        clearInjectedPaths(sessionInfo.id);
+      }
+    }
+
+    if (event.type === "session.compacted") {
+      const sessionID = (props?.sessionID ??
+        (props?.info as { id?: string } | undefined)?.id) as string | undefined;
+      if (sessionID) {
+        sessionCaches.delete(sessionID);
+        clearInjectedPaths(sessionID);
+      }
+    }
+  };
+
+  return {
+    "tool.execute.after": toolExecuteAfter,
+    event: eventHandler,
+  };
+}

src/hooks/directory-agents-injector/storage.ts

@@ -0,0 +1,48 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { AGENTS_INJECTOR_STORAGE } from "./constants";
+import type { InjectedPathsData } from "./types";
+
+function getStoragePath(sessionID: string): string {
+  return join(AGENTS_INJECTOR_STORAGE, `${sessionID}.json`);
+}
+
+export function loadInjectedPaths(sessionID: string): Set<string> {
+  const filePath = getStoragePath(sessionID);
+  if (!existsSync(filePath)) return new Set();
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const data: InjectedPathsData = JSON.parse(content);
+    return new Set(data.injectedPaths);
+  } catch {
+    return new Set();
+  }
+}
+
+export function saveInjectedPaths(sessionID: string, paths: Set<string>): void {
+  if (!existsSync(AGENTS_INJECTOR_STORAGE)) {
+    mkdirSync(AGENTS_INJECTOR_STORAGE, { recursive: true });
+  }
+
+  const data: InjectedPathsData = {
+    sessionID,
+    injectedPaths: [...paths],
+    updatedAt: Date.now(),
+  };
+
+  writeFileSync(getStoragePath(sessionID), JSON.stringify(data, null, 2));
+}
+
+export function clearInjectedPaths(sessionID: string): void {
+  const filePath = getStoragePath(sessionID);
+  if (existsSync(filePath)) {
+    unlinkSync(filePath);
+  }
+}

src/hooks/directory-agents-injector/types.ts

@@ -0,0 +1,5 @@
+export interface InjectedPathsData {
+  sessionID: string;
+  injectedPaths: string[];
+  updatedAt: number;
+}

src/hooks/directory-readme-injector/constants.ts

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+import { xdgData } from "xdg-basedir";
+
+export const OPENCODE_STORAGE = join(xdgData ?? "", "opencode", "storage");
+export const README_INJECTOR_STORAGE = join(
+  OPENCODE_STORAGE,
+  "directory-readme",
+);
+export const README_FILENAME = "README.md";

src/hooks/directory-readme-injector/index.ts

@@ -0,0 +1,126 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  loadInjectedPaths,
+  saveInjectedPaths,
+  clearInjectedPaths,
+} from "./storage";
+import { README_FILENAME } from "./constants";
+
+interface ToolExecuteInput {
+  tool: string;
+  sessionID: string;
+  callID: string;
+}
+
+interface ToolExecuteOutput {
+  title: string;
+  output: string;
+  metadata: unknown;
+}
+
+interface EventInput {
+  event: {
+    type: string;
+    properties?: unknown;
+  };
+}
+
+export function createDirectoryReadmeInjectorHook(ctx: PluginInput) {
+  const sessionCaches = new Map<string, Set<string>>();
+
+  function getSessionCache(sessionID: string): Set<string> {
+    if (!sessionCaches.has(sessionID)) {
+      sessionCaches.set(sessionID, loadInjectedPaths(sessionID));
+    }
+    return sessionCaches.get(sessionID)!;
+  }
+
+  function resolveFilePath(title: string): string | null {
+    if (!title) return null;
+    if (title.startsWith("/")) return title;
+    return resolve(ctx.directory, title);
+  }
+
+  function findReadmeMdUp(startDir: string): string[] {
+    const found: string[] = [];
+    let current = startDir;
+
+    while (true) {
+      const readmePath = join(current, README_FILENAME);
+      if (existsSync(readmePath)) {
+        found.push(readmePath);
+      }
+
+      if (current === ctx.directory) break;
+      const parent = dirname(current);
+      if (parent === current) break;
+      if (!parent.startsWith(ctx.directory)) break;
+      current = parent;
+    }
+
+    return found.reverse();
+  }
+
+  const toolExecuteAfter = async (
+    input: ToolExecuteInput,
+    output: ToolExecuteOutput,
+  ) => {
+    if (input.tool.toLowerCase() !== "read") return;
+
+    const filePath = resolveFilePath(output.title);
+    if (!filePath) return;
+
+    const dir = dirname(filePath);
+    const cache = getSessionCache(input.sessionID);
+    const readmePaths = findReadmeMdUp(dir);
+
+    const toInject: { path: string; content: string }[] = [];
+
+    for (const readmePath of readmePaths) {
+      const readmeDir = dirname(readmePath);
+      if (cache.has(readmeDir)) continue;
+
+      try {
+        const content = readFileSync(readmePath, "utf-8");
+        toInject.push({ path: readmePath, content });
+        cache.add(readmeDir);
+      } catch {}
+    }
+
+    if (toInject.length === 0) return;
+
+    for (const { path, content } of toInject) {
+      output.output += `\n\n[Project README: ${path}]\n${content}`;
+    }
+
+    saveInjectedPaths(input.sessionID, cache);
+  };
+
+  const eventHandler = async ({ event }: EventInput) => {
+    const props = event.properties as Record<string, unknown> | undefined;
+
+    if (event.type === "session.deleted") {
+      const sessionInfo = props?.info as { id?: string } | undefined;
+      if (sessionInfo?.id) {
+        sessionCaches.delete(sessionInfo.id);
+        clearInjectedPaths(sessionInfo.id);
+      }
+    }
+
+    if (event.type === "session.compacted") {
+      const sessionID = (props?.sessionID ??
+        (props?.info as { id?: string } | undefined)?.id) as string | undefined;
+      if (sessionID) {
+        sessionCaches.delete(sessionID);
+        clearInjectedPaths(sessionID);
+      }
+    }
+  };
+
+  return {
+    "tool.execute.after": toolExecuteAfter,
+    event: eventHandler,
+  };
+}

src/hooks/directory-readme-injector/storage.ts

@@ -0,0 +1,48 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { README_INJECTOR_STORAGE } from "./constants";
+import type { InjectedPathsData } from "./types";
+
+function getStoragePath(sessionID: string): string {
+  return join(README_INJECTOR_STORAGE, `${sessionID}.json`);
+}
+
+export function loadInjectedPaths(sessionID: string): Set<string> {
+  const filePath = getStoragePath(sessionID);
+  if (!existsSync(filePath)) return new Set();
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const data: InjectedPathsData = JSON.parse(content);
+    return new Set(data.injectedPaths);
+  } catch {
+    return new Set();
+  }
+}
+
+export function saveInjectedPaths(sessionID: string, paths: Set<string>): void {
+  if (!existsSync(README_INJECTOR_STORAGE)) {
+    mkdirSync(README_INJECTOR_STORAGE, { recursive: true });
+  }
+
+  const data: InjectedPathsData = {
+    sessionID,
+    injectedPaths: [...paths],
+    updatedAt: Date.now(),
+  };
+
+  writeFileSync(getStoragePath(sessionID), JSON.stringify(data, null, 2));
+}
+
+export function clearInjectedPaths(sessionID: string): void {
+  const filePath = getStoragePath(sessionID);
+  if (existsSync(filePath)) {
+    unlinkSync(filePath);
+  }
+}

src/hooks/directory-readme-injector/types.ts

@@ -0,0 +1,5 @@
+export interface InjectedPathsData {
+  sessionID: string;
+  injectedPaths: string[];
+  updatedAt: number;
+}

src/hooks/empty-task-response-detector.ts

@@ -0,0 +1,27 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+const EMPTY_RESPONSE_WARNING = `[Task Empty Response Warning]
+
+Task invocation completed but returned no response. This indicates the agent either:
+- Failed to execute properly
+- Did not terminate correctly
+- Returned an empty result
+
+Note: The call has already completed - you are NOT waiting for a response. Proceed accordingly.`
+
+export function createEmptyTaskResponseDetectorHook(_ctx: PluginInput) {
+  return {
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string },
+      output: { title: string; output: string; metadata: unknown }
+    ) => {
+      if (input.tool !== "Task") return
+
+      const responseText = output.output?.trim() ?? ""
+
+      if (responseText === "") {
+        output.output = EMPTY_RESPONSE_WARNING
+      }
+    },
+  }
+}

src/hooks/grep-blocker.ts

@@ -1,18 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin"
-
-const BLOCKED_MESSAGE =
-  "Error: [BLOCKED] grep has no timeout and can freeze the system. " +
-  "It is permanently disabled. Use 'safe_grep' instead."
-
-export function createGrepBlocker(_ctx: PluginInput) {
-  return {
-    "tool.execute.before": async (
-      input: { tool: string; sessionID: string; callID: string },
-      _output: { args: unknown }
-    ) => {
-      if (input.tool === "grep") {
-        throw new Error(BLOCKED_MESSAGE)
-      }
-    },
-  }
-}

src/hooks/grep-output-truncator.ts

@@ -0,0 +1,131 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+const ANTHROPIC_ACTUAL_LIMIT = 200_000
+const CHARS_PER_TOKEN_ESTIMATE = 4
+const TARGET_MAX_TOKENS = 50_000
+
+interface AssistantMessageInfo {
+  role: "assistant"
+  tokens: {
+    input: number
+    output: number
+    reasoning: number
+    cache: { read: number; write: number }
+  }
+}
+
+interface MessageWrapper {
+  info: { role: string } & Partial<AssistantMessageInfo>
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE)
+}
+
+function truncateToTokenLimit(output: string, maxTokens: number): { result: string; truncated: boolean } {
+  const currentTokens = estimateTokens(output)
+
+  if (currentTokens <= maxTokens) {
+    return { result: output, truncated: false }
+  }
+
+  const lines = output.split("\n")
+
+  if (lines.length <= 3) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN_ESTIMATE
+    return {
+      result: output.slice(0, maxChars) + "\n\n[Output truncated due to context window limit]",
+      truncated: true,
+    }
+  }
+
+  const headerLines = lines.slice(0, 3)
+  const contentLines = lines.slice(3)
+
+  const headerText = headerLines.join("\n")
+  const headerTokens = estimateTokens(headerText)
+  const availableTokens = maxTokens - headerTokens - 50
+
+  if (availableTokens <= 0) {
+    return {
+      result: headerText + "\n\n[Content truncated due to context window limit]",
+      truncated: true,
+    }
+  }
+
+  let resultLines: string[] = []
+  let currentTokenCount = 0
+
+  for (const line of contentLines) {
+    const lineTokens = estimateTokens(line + "\n")
+    if (currentTokenCount + lineTokens > availableTokens) {
+      break
+    }
+    resultLines.push(line)
+    currentTokenCount += lineTokens
+  }
+
+  const truncatedContent = [...headerLines, ...resultLines].join("\n")
+  const removedCount = contentLines.length - resultLines.length
+
+  return {
+    result: truncatedContent + `\n\n[${removedCount} more lines truncated due to context window limit]`,
+    truncated: true,
+  }
+}
+
+export function createGrepOutputTruncatorHook(ctx: PluginInput) {
+  const GREP_TOOLS = ["safe_grep", "Grep"]
+
+  const toolExecuteAfter = async (
+    input: { tool: string; sessionID: string; callID: string },
+    output: { title: string; output: string; metadata: unknown }
+  ) => {
+    if (!GREP_TOOLS.includes(input.tool)) return
+
+    const { sessionID } = input
+
+    try {
+      const response = await ctx.client.session.messages({
+        path: { id: sessionID },
+      })
+
+      const messages = (response.data ?? response) as MessageWrapper[]
+
+      const assistantMessages = messages
+        .filter((m) => m.info.role === "assistant")
+        .map((m) => m.info as AssistantMessageInfo)
+
+      if (assistantMessages.length === 0) return
+
+      const totalInputTokens = assistantMessages.reduce((sum, m) => {
+        const inputTokens = m.tokens?.input ?? 0
+        const cacheReadTokens = m.tokens?.cache?.read ?? 0
+        return sum + inputTokens + cacheReadTokens
+      }, 0)
+
+      const remainingTokens = ANTHROPIC_ACTUAL_LIMIT - totalInputTokens
+
+      const maxOutputTokens = Math.min(
+        remainingTokens * 0.5,
+        TARGET_MAX_TOKENS
+      )
+
+      if (maxOutputTokens <= 0) {
+        output.output = "[Output suppressed - context window exhausted]"
+        return
+      }
+
+      const { result, truncated } = truncateToTokenLimit(output.output, maxOutputTokens)
+      if (truncated) {
+        output.output = result
+      }
+    } catch {
+      // Graceful degradation
+    }
+  }
+
+  return {
+    "tool.execute.after": toolExecuteAfter,
+  }
+}

src/hooks/index.ts

@@ -1,5 +1,12 @@
-export { createTodoContinuationEnforcer } from "./todo-continuation-enforcer"
-export { createContextWindowMonitorHook } from "./context-window-monitor"
-export { createSessionNotification } from "./session-notification"
-export { createSessionRecoveryHook } from "./session-recovery"
-export { createCommentCheckerHooks } from "./comment-checker"
+export { createTodoContinuationEnforcer } from "./todo-continuation-enforcer";
+export { createContextWindowMonitorHook } from "./context-window-monitor";
+export { createSessionNotification } from "./session-notification";
+export { createSessionRecoveryHook } from "./session-recovery";
+export { createCommentCheckerHooks } from "./comment-checker";
+export { createGrepOutputTruncatorHook } from "./grep-output-truncator";
+export { createDirectoryAgentsInjectorHook } from "./directory-agents-injector";
+export { createDirectoryReadmeInjectorHook } from "./directory-readme-injector";
+export { createEmptyTaskResponseDetectorHook } from "./empty-task-response-detector";
+export { createAnthropicAutoCompactHook } from "./anthropic-auto-compact";
+export { createThinkModeHook } from "./think-mode";
+export { createClaudeCodeHooksHook } from "./claude-code-hooks";

src/hooks/session-recovery/constants.ts

@@ -0,0 +1,10 @@
+import { join } from "node:path"
+import { xdgData } from "xdg-basedir"
+
+export const OPENCODE_STORAGE = join(xdgData ?? "", "opencode", "storage")
+export const MESSAGE_STORAGE = join(OPENCODE_STORAGE, "message")
+export const PART_STORAGE = join(OPENCODE_STORAGE, "part")
+
+export const THINKING_TYPES = new Set(["thinking", "redacted_thinking", "reasoning"])
+export const META_TYPES = new Set(["step-start", "step-finish"])
+export const CONTENT_TYPES = new Set(["text", "tool", "tool_use", "tool_result"])

src/hooks/session-recovery/index.ts

@@ -1,26 +1,24 @@
-/**
- * Session Recovery - Message State Error Recovery
- *
- * Handles FOUR specific scenarios:
- * 1. tool_use block exists without tool_result
- *    - Recovery: inject tool_result with "cancelled" content
- *
- * 2. Thinking block order violation (first block must be thinking)
- *    - Recovery: prepend empty thinking block
- *
- * 3. Thinking disabled but message contains thinking blocks
- *    - Recovery: strip thinking/redacted_thinking blocks
- *
- * 4. Empty content message (non-empty content required)
- *    - Recovery: delete the empty message via revert
- */
-
 import type { PluginInput } from "@opencode-ai/plugin"
 import type { createOpencodeClient } from "@opencode-ai/sdk"
+import {
+  findEmptyMessages,
+  findEmptyMessageByIndex,
+  findMessagesWithOrphanThinking,
+  findMessagesWithThinkingBlocks,
+  injectTextPart,
+  prependThinkingPart,
+  stripThinkingParts,
+} from "./storage"
+import type { MessageData } from "./types"
 
 type Client = ReturnType<typeof createOpencodeClient>
 
-type RecoveryErrorType = "tool_result_missing" | "thinking_block_order" | "thinking_disabled_violation" | "empty_content_message" | null
+type RecoveryErrorType =
+  | "tool_result_missing"
+  | "thinking_block_order"
+  | "thinking_disabled_violation"
+  | "empty_content_message"
+  | null
 
 interface MessageInfo {
   id?: string
@@ -37,11 +35,6 @@ interface ToolUsePart {
   input: Record<string, unknown>
 }
 
-interface ThinkingPart {
-  type: "thinking"
-  thinking: string
-}
-
 interface MessagePart {
   type: string
   id?: string
@@ -51,16 +44,21 @@ interface MessagePart {
   input?: Record<string, unknown>
 }
 
-interface MessageData {
-  info?: MessageInfo
-  parts?: MessagePart[]
-}
-
 function getErrorMessage(error: unknown): string {
   if (!error) return ""
   if (typeof error === "string") return error.toLowerCase()
-  const errorObj = error as { data?: { message?: string }; message?: string }
-  return (errorObj.data?.message || errorObj.message || "").toLowerCase()
+  const errorObj = error as {
+    data?: { message?: string }
+    message?: string
+    error?: { message?: string }
+  }
+  return (errorObj.data?.message || errorObj.error?.message || errorObj.message || "").toLowerCase()
+}
+
+function extractMessageIndex(error: unknown): number | null {
+  const message = getErrorMessage(error)
+  const match = message.match(/messages\.(\d+)/)
+  return match ? parseInt(match[1], 10) : null
 }
 
 function detectErrorType(error: unknown): RecoveryErrorType {
@@ -70,7 +68,10 @@ function detectErrorType(error: unknown): RecoveryErrorType {
     return "tool_result_missing"
   }
 
-  if (message.includes("thinking") && message.includes("first block")) {
+  if (
+    message.includes("thinking") &&
+    (message.includes("first block") || message.includes("must start with") || message.includes("preceeding"))
+  ) {
     return "thinking_block_order"
   }
 
@@ -110,7 +111,7 @@ async function recoverToolResultMissing(
   try {
     await client.session.prompt({
       path: { id: sessionID },
-      // @ts-expect-error - SDK types may not include tool_result parts, but runtime accepts it
+      // @ts-expect-error - SDK types may not include tool_result parts
       body: { parts: toolResultParts },
     })
 
@@ -121,182 +122,87 @@ async function recoverToolResultMissing(
 }
 
 async function recoverThinkingBlockOrder(
-  client: Client,
+  _client: Client,
   sessionID: string,
-  failedAssistantMsg: MessageData,
-  directory: string
+  _failedAssistantMsg: MessageData,
+  _directory: string
 ): Promise<boolean> {
-  const messageID = failedAssistantMsg.info?.id
-  if (!messageID) {
+  const orphanMessages = findMessagesWithOrphanThinking(sessionID)
+
+  if (orphanMessages.length === 0) {
     return false
   }
 
-  const existingParts = failedAssistantMsg.parts || []
-  const patchedParts: MessagePart[] = [{ type: "thinking", thinking: "" } as ThinkingPart, ...existingParts]
-
-  try {
-    // @ts-expect-error - Experimental API
-    await client.message?.update?.({
-      path: { id: messageID },
-      body: { parts: patchedParts },
-    })
-
-    return true
-  } catch {
-    // message.update not available
-  }
-
-  try {
-    // @ts-expect-error - Experimental API
-    await client.session.patch?.({
-      path: { id: sessionID },
-      body: {
-        messageID,
-        parts: patchedParts,
-      },
-    })
-
-    return true
-  } catch {
-    // session.patch not available
-  }
-
-  return await fallbackRevertStrategy(client, sessionID, failedAssistantMsg, directory)
-}
-
-async function recoverThinkingDisabledViolation(
-  client: Client,
-  sessionID: string,
-  failedAssistantMsg: MessageData
-): Promise<boolean> {
-  const messageID = failedAssistantMsg.info?.id
-  if (!messageID) {
-    return false
-  }
-
-  const existingParts = failedAssistantMsg.parts || []
-  const strippedParts = existingParts.filter((p) => p.type !== "thinking" && p.type !== "redacted_thinking")
-
-  if (strippedParts.length === 0) {
-    return false
-  }
-
-  try {
-    // @ts-expect-error - Experimental API
-    await client.message?.update?.({
-      path: { id: messageID },
-      body: { parts: strippedParts },
-    })
-
-    return true
-  } catch {
-    // message.update not available
-  }
-
-  try {
-    // @ts-expect-error - Experimental API
-    await client.session.patch?.({
-      path: { id: sessionID },
-      body: {
-        messageID,
-        parts: strippedParts,
-      },
-    })
-
-    return true
-  } catch {
-    // session.patch not available
-  }
-
-  return false
-}
-
-async function recoverEmptyContentMessage(
-  client: Client,
-  sessionID: string,
-  failedAssistantMsg: MessageData,
-  directory: string
-): Promise<boolean> {
-  const messageID = failedAssistantMsg.info?.id
-  const parentMsgID = failedAssistantMsg.info?.parentID
-
-  if (!messageID) {
-    return false
-  }
-
-  // Revert to parent message (delete the empty message)
-  const revertTargetID = parentMsgID || messageID
-
-  try {
-    await client.session.revert({
-      path: { id: sessionID },
-      body: { messageID: revertTargetID },
-      query: { directory },
-    })
-
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function fallbackRevertStrategy(
-  client: Client,
-  sessionID: string,
-  failedAssistantMsg: MessageData,
-  directory: string
-): Promise<boolean> {
-  const parentMsgID = failedAssistantMsg.info?.parentID
-
-  const messagesResp = await client.session.messages({
-    path: { id: sessionID },
-    query: { directory },
-  })
-  const msgs = (messagesResp as { data?: MessageData[] }).data
-  if (!msgs || msgs.length === 0) {
-    return false
-  }
-
-  let targetUserMsg: MessageData | null = null
-  if (parentMsgID) {
-    targetUserMsg = msgs.find((m) => m.info?.id === parentMsgID) ?? null
-  }
-  if (!targetUserMsg) {
-    for (let i = msgs.length - 1; i >= 0; i--) {
-      if (msgs[i].info?.role === "user") {
-        targetUserMsg = msgs[i]
-        break
-      }
+  let anySuccess = false
+  for (const messageID of orphanMessages) {
+    if (prependThinkingPart(sessionID, messageID)) {
+      anySuccess = true
     }
   }
 
-  if (!targetUserMsg?.parts?.length) {
-    return false
-  }
-
-  await client.session.revert({
-    path: { id: sessionID },
-    body: { messageID: targetUserMsg.info?.id ?? "" },
-    query: { directory },
-  })
-
-  const textParts = targetUserMsg.parts
-    .filter((p) => p.type === "text" && p.text)
-    .map((p) => ({ type: "text" as const, text: p.text ?? "" }))
-
-  if (textParts.length === 0) {
-    return false
-  }
-
-  await client.session.prompt({
-    path: { id: sessionID },
-    body: { parts: textParts },
-    query: { directory },
-  })
-
-  return true
+  return anySuccess
 }
 
+async function recoverThinkingDisabledViolation(
+  _client: Client,
+  sessionID: string,
+  _failedAssistantMsg: MessageData
+): Promise<boolean> {
+  const messagesWithThinking = findMessagesWithThinkingBlocks(sessionID)
+
+  if (messagesWithThinking.length === 0) {
+    return false
+  }
+
+  let anySuccess = false
+  for (const messageID of messagesWithThinking) {
+    if (stripThinkingParts(messageID)) {
+      anySuccess = true
+    }
+  }
+
+  return anySuccess
+}
+
+async function recoverEmptyContentMessage(
+  _client: Client,
+  sessionID: string,
+  failedAssistantMsg: MessageData,
+  _directory: string,
+  error: unknown
+): Promise<boolean> {
+  const targetIndex = extractMessageIndex(error)
+  const failedID = failedAssistantMsg.info?.id
+
+  if (targetIndex !== null) {
+    const targetMessageID = findEmptyMessageByIndex(sessionID, targetIndex)
+    if (targetMessageID) {
+      return injectTextPart(sessionID, targetMessageID, "(interrupted)")
+    }
+  }
+
+  if (failedID) {
+    if (injectTextPart(sessionID, failedID, "(interrupted)")) {
+      return true
+    }
+  }
+
+  const emptyMessageIDs = findEmptyMessages(sessionID)
+  let anySuccess = false
+  for (const messageID of emptyMessageIDs) {
+    if (injectTextPart(sessionID, messageID, "(interrupted)")) {
+      anySuccess = true
+    }
+  }
+
+  return anySuccess
+}
+
+// NOTE: fallbackRevertStrategy was removed (2025-12-08)
+// Reason: Function was defined but never called - no error recovery paths used it.
+// All error types have dedicated recovery functions (recoverToolResultMissing,
+// recoverThinkingBlockOrder, recoverThinkingDisabledViolation, recoverEmptyContentMessage).
+
 export function createSessionRecoveryHook(ctx: PluginInput) {
   const processingErrors = new Set<string>()
   let onAbortCallback: ((sessionID: string) => void) | null = null
@@ -350,16 +256,14 @@ export function createSessionRecoveryHook(ctx: PluginInput) {
         tool_result_missing: "Injecting cancelled tool results...",
         thinking_block_order: "Fixing message structure...",
         thinking_disabled_violation: "Stripping thinking blocks...",
-        empty_content_message: "Deleting empty message...",
+        empty_content_message: "Fixing empty message...",
       }
-      const toastTitle = toastTitles[errorType]
-      const toastMessage = toastMessages[errorType]
 
       await ctx.client.tui
         .showToast({
           body: {
-            title: toastTitle,
-            message: toastMessage,
+            title: toastTitles[errorType],
+            message: toastMessages[errorType],
             variant: "warning",
             duration: 3000,
           },
@@ -375,15 +279,16 @@ export function createSessionRecoveryHook(ctx: PluginInput) {
       } else if (errorType === "thinking_disabled_violation") {
         success = await recoverThinkingDisabledViolation(ctx.client, sessionID, failedMsg)
       } else if (errorType === "empty_content_message") {
-        success = await recoverEmptyContentMessage(ctx.client, sessionID, failedMsg, ctx.directory)
+        success = await recoverEmptyContentMessage(ctx.client, sessionID, failedMsg, ctx.directory, info.error)
       }
 
-      return success
-    } catch {
-      return false
-    } finally {
-      processingErrors.delete(assistantMsgID)
-    }
+    return success
+  } catch (err) {
+    console.error("[session-recovery] Recovery failed:", err)
+    return false
+  } finally {
+    processingErrors.delete(assistantMsgID)
+  }
   }
 
   return {

src/hooks/session-recovery/storage.ts

@@ -0,0 +1,248 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { MESSAGE_STORAGE, PART_STORAGE, THINKING_TYPES, META_TYPES } from "./constants"
+import type { StoredMessageMeta, StoredPart, StoredTextPart } from "./types"
+
+export function generatePartId(): string {
+  const timestamp = Date.now().toString(16)
+  const random = Math.random().toString(36).substring(2, 10)
+  return `prt_${timestamp}${random}`
+}
+
+export function getMessageDir(sessionID: string): string {
+  if (!existsSync(MESSAGE_STORAGE)) return ""
+
+  const directPath = join(MESSAGE_STORAGE, sessionID)
+  if (existsSync(directPath)) {
+    return directPath
+  }
+
+  for (const dir of readdirSync(MESSAGE_STORAGE)) {
+    const sessionPath = join(MESSAGE_STORAGE, dir, sessionID)
+    if (existsSync(sessionPath)) {
+      return sessionPath
+    }
+  }
+
+  return ""
+}
+
+export function readMessages(sessionID: string): StoredMessageMeta[] {
+  const messageDir = getMessageDir(sessionID)
+  if (!messageDir || !existsSync(messageDir)) return []
+
+  const messages: StoredMessageMeta[] = []
+  for (const file of readdirSync(messageDir)) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const content = readFileSync(join(messageDir, file), "utf-8")
+      messages.push(JSON.parse(content))
+    } catch {
+      continue
+    }
+  }
+
+  return messages.sort((a, b) => {
+    const aTime = a.time?.created ?? 0
+    const bTime = b.time?.created ?? 0
+    if (aTime !== bTime) return aTime - bTime
+    return a.id.localeCompare(b.id)
+  })
+}
+
+export function readParts(messageID: string): StoredPart[] {
+  const partDir = join(PART_STORAGE, messageID)
+  if (!existsSync(partDir)) return []
+
+  const parts: StoredPart[] = []
+  for (const file of readdirSync(partDir)) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const content = readFileSync(join(partDir, file), "utf-8")
+      parts.push(JSON.parse(content))
+    } catch {
+      continue
+    }
+  }
+
+  return parts
+}
+
+export function hasContent(part: StoredPart): boolean {
+  if (THINKING_TYPES.has(part.type)) return false
+  if (META_TYPES.has(part.type)) return false
+
+  if (part.type === "text") {
+    const textPart = part as StoredTextPart
+    return !!(textPart.text?.trim())
+  }
+
+  if (part.type === "tool" || part.type === "tool_use") {
+    return true
+  }
+
+  if (part.type === "tool_result") {
+    return true
+  }
+
+  return false
+}
+
+export function messageHasContent(messageID: string): boolean {
+  const parts = readParts(messageID)
+  return parts.some(hasContent)
+}
+
+export function injectTextPart(sessionID: string, messageID: string, text: string): boolean {
+  const partDir = join(PART_STORAGE, messageID)
+
+  if (!existsSync(partDir)) {
+    mkdirSync(partDir, { recursive: true })
+  }
+
+  const partId = generatePartId()
+  const part: StoredTextPart = {
+    id: partId,
+    sessionID,
+    messageID,
+    type: "text",
+    text,
+    synthetic: true,
+  }
+
+  try {
+    writeFileSync(join(partDir, `${partId}.json`), JSON.stringify(part, null, 2))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function findEmptyMessages(sessionID: string): string[] {
+  const messages = readMessages(sessionID)
+  const emptyIds: string[] = []
+
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue
+
+    if (!messageHasContent(msg.id)) {
+      emptyIds.push(msg.id)
+    }
+  }
+
+  return emptyIds
+}
+
+export function findEmptyMessageByIndex(sessionID: string, targetIndex: number): string | null {
+  const messages = readMessages(sessionID)
+  
+  if (targetIndex < 0 || targetIndex >= messages.length) return null
+
+  const targetMsg = messages[targetIndex]
+  if (targetMsg.role !== "assistant") return null
+  if (messageHasContent(targetMsg.id)) return null
+
+  return targetMsg.id
+}
+
+export function findFirstEmptyMessage(sessionID: string): string | null {
+  const emptyIds = findEmptyMessages(sessionID)
+  return emptyIds.length > 0 ? emptyIds[0] : null
+}
+
+export function findMessagesWithThinkingBlocks(sessionID: string): string[] {
+  const messages = readMessages(sessionID)
+  const result: string[] = []
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i]
+    if (msg.role !== "assistant") continue
+
+    const isLastMessage = i === messages.length - 1
+    if (isLastMessage) continue
+
+    const parts = readParts(msg.id)
+    const hasThinking = parts.some((p) => THINKING_TYPES.has(p.type))
+    if (hasThinking) {
+      result.push(msg.id)
+    }
+  }
+
+  return result
+}
+
+export function findMessagesWithOrphanThinking(sessionID: string): string[] {
+  const messages = readMessages(sessionID)
+  const result: string[] = []
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i]
+    if (msg.role !== "assistant") continue
+
+    const isLastMessage = i === messages.length - 1
+    if (isLastMessage) continue
+
+    const parts = readParts(msg.id)
+    if (parts.length === 0) continue
+
+    const sortedParts = [...parts].sort((a, b) => a.id.localeCompare(b.id))
+    const firstPart = sortedParts[0]
+
+    const hasThinking = parts.some((p) => THINKING_TYPES.has(p.type))
+    const firstIsThinking = THINKING_TYPES.has(firstPart.type)
+
+    if (hasThinking && !firstIsThinking) {
+      result.push(msg.id)
+    }
+  }
+
+  return result
+}
+
+export function prependThinkingPart(sessionID: string, messageID: string): boolean {
+  const partDir = join(PART_STORAGE, messageID)
+
+  if (!existsSync(partDir)) {
+    mkdirSync(partDir, { recursive: true })
+  }
+
+  const partId = `prt_0000000000_thinking`
+  const part = {
+    id: partId,
+    sessionID,
+    messageID,
+    type: "thinking",
+    thinking: "",
+    synthetic: true,
+  }
+
+  try {
+    writeFileSync(join(partDir, `${partId}.json`), JSON.stringify(part, null, 2))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function stripThinkingParts(messageID: string): boolean {
+  const partDir = join(PART_STORAGE, messageID)
+  if (!existsSync(partDir)) return false
+
+  let anyRemoved = false
+  for (const file of readdirSync(partDir)) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const filePath = join(partDir, file)
+      const content = readFileSync(filePath, "utf-8")
+      const part = JSON.parse(content) as StoredPart
+      if (THINKING_TYPES.has(part.type)) {
+        unlinkSync(filePath)
+        anyRemoved = true
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return anyRemoved
+}

src/hooks/session-recovery/types.ts

@@ -0,0 +1,82 @@
+export type ThinkingPartType = "thinking" | "redacted_thinking" | "reasoning"
+export type MetaPartType = "step-start" | "step-finish"
+export type ContentPartType = "text" | "tool" | "tool_use" | "tool_result"
+
+export interface StoredMessageMeta {
+  id: string
+  sessionID: string
+  role: "user" | "assistant"
+  parentID?: string
+  time?: {
+    created: number
+    completed?: number
+  }
+  error?: unknown
+}
+
+export interface StoredTextPart {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "text"
+  text: string
+  synthetic?: boolean
+  ignored?: boolean
+}
+
+export interface StoredToolPart {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "tool"
+  callID: string
+  tool: string
+  state: {
+    status: "pending" | "running" | "completed" | "error"
+    input: Record<string, unknown>
+    output?: string
+    error?: string
+  }
+}
+
+export interface StoredReasoningPart {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "reasoning"
+  text: string
+}
+
+export interface StoredStepPart {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "step-start" | "step-finish"
+}
+
+export type StoredPart = StoredTextPart | StoredToolPart | StoredReasoningPart | StoredStepPart | {
+  id: string
+  sessionID: string
+  messageID: string
+  type: string
+  [key: string]: unknown
+}
+
+export interface MessageData {
+  info?: {
+    id?: string
+    role?: string
+    sessionID?: string
+    parentID?: string
+    error?: unknown
+  }
+  parts?: Array<{
+    type: string
+    id?: string
+    text?: string
+    thinking?: string
+    name?: string
+    input?: Record<string, unknown>
+    callID?: string
+  }>
+}

src/hooks/think-mode/detector.ts

@@ -0,0 +1,57 @@
+const ENGLISH_PATTERNS = [/\bultrathink\b/i, /\bthink\b/i]
+
+const MULTILINGUAL_KEYWORDS = [
+  "생각", "고민", "검토", "제대로",
+  "思考", "考虑", "考慮",
+  "思考", "考え", "熟考",
+  "सोच", "विचार",
+  "تفكير", "تأمل",
+  "চিন্তা", "ভাবনা",
+  "думать", "думай", "размышлять", "размышляй",
+  "pensar", "pense", "refletir", "reflita",
+  "pensar", "piensa", "reflexionar", "reflexiona",
+  "penser", "pense", "réfléchir", "réfléchis",
+  "denken", "denk", "nachdenken",
+  "suy nghĩ", "cân nhắc",
+  "düşün", "düşünmek",
+  "pensare", "pensa", "riflettere", "rifletti",
+  "คิด", "พิจารณา",
+  "myśl", "myśleć", "zastanów",
+  "denken", "denk", "nadenken",
+  "berpikir", "pikir", "pertimbangkan",
+  "думати", "думай", "роздумувати",
+  "σκέψου", "σκέφτομαι",
+  "myslet", "mysli", "přemýšlet",
+  "gândește", "gândi", "reflectă",
+  "tänka", "tänk", "fundera",
+  "gondolkodj", "gondolkodni",
+  "ajattele", "ajatella", "pohdi",
+  "tænk", "tænke", "overvej",
+  "tenk", "tenke", "gruble",
+  "חשוב", "לחשוב", "להרהר",
+  "fikir", "berfikir",
+]
+
+const MULTILINGUAL_PATTERNS = MULTILINGUAL_KEYWORDS.map((kw) => new RegExp(kw, "i"))
+const THINK_PATTERNS = [...ENGLISH_PATTERNS, ...MULTILINGUAL_PATTERNS]
+
+const CODE_BLOCK_PATTERN = /```[\s\S]*?```/g
+const INLINE_CODE_PATTERN = /`[^`]+`/g
+
+function removeCodeBlocks(text: string): string {
+  return text.replace(CODE_BLOCK_PATTERN, "").replace(INLINE_CODE_PATTERN, "")
+}
+
+export function detectThinkKeyword(text: string): boolean {
+  const textWithoutCode = removeCodeBlocks(text)
+  return THINK_PATTERNS.some((pattern) => pattern.test(textWithoutCode))
+}
+
+export function extractPromptText(
+  parts: Array<{ type: string; text?: string }>
+): string {
+  return parts
+    .filter((p) => p.type === "text")
+    .map((p) => p.text || "")
+    .join("")
+}

src/hooks/think-mode/index.ts

@@ -0,0 +1,73 @@
+import { detectThinkKeyword, extractPromptText } from "./detector"
+import { getHighVariant, isAlreadyHighVariant } from "./switcher"
+import type { ThinkModeState, ThinkModeInput } from "./types"
+
+export * from "./detector"
+export * from "./switcher"
+export * from "./types"
+
+const thinkModeState = new Map<string, ThinkModeState>()
+
+export function clearThinkModeState(sessionID: string): void {
+  thinkModeState.delete(sessionID)
+}
+
+export function createThinkModeHook() {
+  return {
+    "chat.params": async (
+      output: ThinkModeInput,
+      sessionID: string
+    ): Promise<void> => {
+      const promptText = extractPromptText(output.parts)
+
+      const state: ThinkModeState = {
+        requested: false,
+        modelSwitched: false,
+      }
+
+      if (!detectThinkKeyword(promptText)) {
+        thinkModeState.set(sessionID, state)
+        return
+      }
+
+      state.requested = true
+
+      const currentModel = output.message.model
+      if (!currentModel) {
+        thinkModeState.set(sessionID, state)
+        return
+      }
+
+      state.providerID = currentModel.providerID
+      state.modelID = currentModel.modelID
+
+      if (isAlreadyHighVariant(currentModel.modelID)) {
+        thinkModeState.set(sessionID, state)
+        return
+      }
+
+      const highVariant = getHighVariant(currentModel.modelID)
+
+      if (!highVariant) {
+        thinkModeState.set(sessionID, state)
+        return
+      }
+
+      output.message.model = {
+        providerID: currentModel.providerID,
+        modelID: highVariant,
+      }
+      state.modelSwitched = true
+      thinkModeState.set(sessionID, state)
+    },
+
+    event: async ({ event }: { event: { type: string; properties?: unknown } }) => {
+      if (event.type === "session.deleted") {
+        const props = event.properties as { info?: { id?: string } } | undefined
+        if (props?.info?.id) {
+          thinkModeState.delete(props.info.id)
+        }
+      }
+    },
+  }
+}

src/hooks/think-mode/switcher.ts

@@ -0,0 +1,124 @@
+// Maps model IDs to their "high reasoning" variant (internal convention)
+// For OpenAI models, this signals that reasoning_effort should be set to "high"
+const HIGH_VARIANT_MAP: Record<string, string> = {
+  // Claude
+  "claude-sonnet-4-5": "claude-sonnet-4-5-high",
+  "claude-opus-4-5": "claude-opus-4-5-high",
+  // Gemini
+  "gemini-3-pro": "gemini-3-pro-high",
+  "gemini-3-pro-low": "gemini-3-pro-high",
+  // GPT-5
+  "gpt-5": "gpt-5-high",
+  "gpt-5-mini": "gpt-5-mini-high",
+  "gpt-5-nano": "gpt-5-nano-high",
+  "gpt-5-pro": "gpt-5-pro-high",
+  "gpt-5-chat-latest": "gpt-5-chat-latest-high",
+  // GPT-5.1
+  "gpt-5.1": "gpt-5.1-high",
+  "gpt-5.1-chat-latest": "gpt-5.1-chat-latest-high",
+  "gpt-5.1-codex": "gpt-5.1-codex-high",
+  "gpt-5.1-codex-mini": "gpt-5.1-codex-mini-high",
+  "gpt-5.1-codex-max": "gpt-5.1-codex-max-high",
+  // GPT-5.2
+  "gpt-5.2": "gpt-5.2-high",
+  "gpt-5.2-chat-latest": "gpt-5.2-chat-latest-high",
+  "gpt-5.2-pro": "gpt-5.2-pro-high",
+}
+
+const ALREADY_HIGH: Set<string> = new Set([
+  // Claude
+  "claude-sonnet-4-5-high",
+  "claude-opus-4-5-high",
+  // Gemini
+  "gemini-3-pro-high",
+  // GPT-5
+  "gpt-5-high",
+  "gpt-5-mini-high",
+  "gpt-5-nano-high",
+  "gpt-5-pro-high",
+  "gpt-5-chat-latest-high",
+  // GPT-5.1
+  "gpt-5.1-high",
+  "gpt-5.1-chat-latest-high",
+  "gpt-5.1-codex-high",
+  "gpt-5.1-codex-mini-high",
+  "gpt-5.1-codex-max-high",
+  // GPT-5.2
+  "gpt-5.2-high",
+  "gpt-5.2-chat-latest-high",
+  "gpt-5.2-pro-high",
+])
+
+export const THINKING_CONFIGS: Record<string, Record<string, unknown>> = {
+  anthropic: {
+    thinking: {
+      type: "enabled",
+      budgetTokens: 64000,
+    },
+  },
+  "amazon-bedrock": {
+    reasoningConfig: {
+      type: "enabled",
+      budgetTokens: 32000,
+    },
+  },
+  google: {
+    providerOptions: {
+      google: {
+        thinkingConfig: {
+          thinkingLevel: "HIGH",
+        },
+      },
+    },
+  },
+  "google-vertex": {
+    providerOptions: {
+      "google-vertex": {
+        thinkingConfig: {
+          thinkingLevel: "HIGH",
+        },
+      },
+    },
+  },
+}
+
+const THINKING_CAPABLE_MODELS: Record<string, string[]> = {
+  anthropic: ["claude-sonnet-4", "claude-opus-4", "claude-3"],
+  "amazon-bedrock": ["claude", "anthropic"],
+  google: ["gemini-2", "gemini-3"],
+  "google-vertex": ["gemini-2", "gemini-3"],
+}
+
+export function getHighVariant(modelID: string): string | null {
+  if (ALREADY_HIGH.has(modelID)) {
+    return null
+  }
+  return HIGH_VARIANT_MAP[modelID] ?? null
+}
+
+export function isAlreadyHighVariant(modelID: string): boolean {
+  return ALREADY_HIGH.has(modelID) || modelID.endsWith("-high")
+}
+
+export function getThinkingConfig(
+  providerID: string,
+  modelID: string
+): Record<string, unknown> | null {
+  if (isAlreadyHighVariant(modelID)) {
+    return null
+  }
+
+  const config = THINKING_CONFIGS[providerID]
+  const capablePatterns = THINKING_CAPABLE_MODELS[providerID]
+
+  if (!config || !capablePatterns) {
+    return null
+  }
+
+  const modelLower = modelID.toLowerCase()
+  const isCapable = capablePatterns.some((pattern) =>
+    modelLower.includes(pattern.toLowerCase())
+  )
+
+  return isCapable ? config : null
+}

src/hooks/think-mode/types.ts

@@ -0,0 +1,20 @@
+export interface ThinkModeState {
+  requested: boolean
+  modelSwitched: boolean
+  providerID?: string
+  modelID?: string
+}
+
+export interface ModelRef {
+  providerID: string
+  modelID: string
+}
+
+export interface MessageWithModel {
+  model?: ModelRef
+}
+
+export interface ThinkModeInput {
+  parts: Array<{ type: string; text?: string }>
+  message: MessageWithModel
+}

src/hooks/todo-continuation-enforcer.ts

@@ -7,18 +7,13 @@ interface Todo {
   id: string
 }
 
-const CONTINUATION_PROMPT = `[SYSTEM REMINDER - TODO ENFORCEMENT]
+const CONTINUATION_PROMPT = `[SYSTEM REMINDER - TODO CONTINUATION]
 
-Your todo list is NOT complete. There are still incomplete tasks remaining.
+Incomplete tasks remain in your todo list. Continue working on the next pending task.
 
-CRITICAL INSTRUCTION:
-- You MUST NOT stop working until ALL todos are marked as completed
-- Continue working on the next pending task immediately
-- Work honestly and diligently to finish every task
-- Do NOT ask for permission to continue - just proceed with the work
-- Mark each task as completed as soon as you finish it
-
-Resume your work NOW.`
+- Proceed without asking for permission
+- Mark each task complete when finished
+- Do not stop until all tasks are done`
 
 function detectInterrupt(error: unknown): boolean {
   if (!error) return false
@@ -41,6 +36,7 @@ export function createTodoContinuationEnforcer(ctx: PluginInput) {
   const remindedSessions = new Set<string>()
   const interruptedSessions = new Set<string>()
   const errorSessions = new Set<string>()
+  const pendingTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
   return async ({ event }: { event: { type: string; properties?: unknown } }) => {
     const props = event.properties as Record<string, unknown> | undefined
@@ -52,6 +48,13 @@ export function createTodoContinuationEnforcer(ctx: PluginInput) {
         if (detectInterrupt(props?.error)) {
           interruptedSessions.add(sessionID)
         }
+        
+        // Cancel pending continuation if error occurs
+        const timer = pendingTimers.get(sessionID)
+        if (timer) {
+          clearTimeout(timer)
+          pendingTimers.delete(sessionID)
+        }
       }
       return
     }
@@ -60,68 +63,78 @@ export function createTodoContinuationEnforcer(ctx: PluginInput) {
       const sessionID = props?.sessionID as string | undefined
       if (!sessionID) return
 
-      // Wait for potential session.error events to be processed first
-      await new Promise(resolve => setTimeout(resolve, 150))
-
-      const shouldBypass = interruptedSessions.has(sessionID) || errorSessions.has(sessionID)
-      
-      interruptedSessions.delete(sessionID)
-      errorSessions.delete(sessionID)
-
-      if (shouldBypass) {
-        return
+      // Cancel any existing timer to debounce
+      const existingTimer = pendingTimers.get(sessionID)
+      if (existingTimer) {
+        clearTimeout(existingTimer)
       }
 
-      if (remindedSessions.has(sessionID)) {
-        return
-      }
+      // Schedule continuation check
+      const timer = setTimeout(async () => {
+        pendingTimers.delete(sessionID)
 
-      let todos: Todo[] = []
-      try {
-        const response = await ctx.client.session.todo({
-          path: { id: sessionID },
-        })
-        todos = (response.data ?? response) as Todo[]
-      } catch {
-        return
-      }
+        const shouldBypass = interruptedSessions.has(sessionID) || errorSessions.has(sessionID)
+        
+        interruptedSessions.delete(sessionID)
+        errorSessions.delete(sessionID)
 
-      if (!todos || todos.length === 0) {
-        return
-      }
+        if (shouldBypass) {
+          return
+        }
 
-      const incomplete = todos.filter(
-        (t) => t.status !== "completed" && t.status !== "cancelled"
-      )
+        if (remindedSessions.has(sessionID)) {
+          return
+        }
 
-      if (incomplete.length === 0) {
-        return
-      }
+        let todos: Todo[] = []
+        try {
+          const response = await ctx.client.session.todo({
+            path: { id: sessionID },
+          })
+          todos = (response.data ?? response) as Todo[]
+        } catch {
+          return
+        }
 
-      remindedSessions.add(sessionID)
+        if (!todos || todos.length === 0) {
+          return
+        }
 
-      // Re-check if abort occurred during the delay
-      if (interruptedSessions.has(sessionID) || errorSessions.has(sessionID)) {
-        remindedSessions.delete(sessionID)
-        return
-      }
+        const incomplete = todos.filter(
+          (t) => t.status !== "completed" && t.status !== "cancelled"
+        )
 
-      try {
-        await ctx.client.session.prompt({
-          path: { id: sessionID },
-          body: {
-            parts: [
-              {
-                type: "text",
-                text: `${CONTINUATION_PROMPT}\n\n[Status: ${incomplete.length}/${todos.length} tasks remaining]`,
-              },
-            ],
-          },
-          query: { directory: ctx.directory },
-        })
-      } catch {
-        remindedSessions.delete(sessionID)
-      }
+        if (incomplete.length === 0) {
+          return
+        }
+
+        remindedSessions.add(sessionID)
+
+        // Re-check if abort occurred during the delay/fetch
+        if (interruptedSessions.has(sessionID) || errorSessions.has(sessionID)) {
+          remindedSessions.delete(sessionID)
+          return
+        }
+
+        try {
+          await ctx.client.session.prompt({
+            path: { id: sessionID },
+            body: {
+              parts: [
+                {
+                  type: "text",
+                  text: `${CONTINUATION_PROMPT}\n\n[Status: ${todos.length - incomplete.length}/${todos.length} completed, ${incomplete.length} remaining]`,
+                },
+              ],
+            },
+            query: { directory: ctx.directory },
+          })
+        } catch {
+          remindedSessions.delete(sessionID)
+        }
+      }, 200)
+
+      pendingTimers.set(sessionID, timer)
     }
 
     if (event.type === "message.updated") {
@@ -129,6 +142,13 @@ export function createTodoContinuationEnforcer(ctx: PluginInput) {
       const sessionID = info?.sessionID as string | undefined
       if (sessionID && info?.role === "user") {
         remindedSessions.delete(sessionID)
+        
+        // Cancel pending continuation on user interaction
+        const timer = pendingTimers.get(sessionID)
+        if (timer) {
+          clearTimeout(timer)
+          pendingTimers.delete(sessionID)
+        }
       }
     }
 
@@ -138,6 +158,13 @@ export function createTodoContinuationEnforcer(ctx: PluginInput) {
         remindedSessions.delete(sessionInfo.id)
         interruptedSessions.delete(sessionInfo.id)
         errorSessions.delete(sessionInfo.id)
+        
+        // Cancel pending continuation
+        const timer = pendingTimers.get(sessionInfo.id)
+        if (timer) {
+          clearTimeout(timer)
+          pendingTimers.delete(sessionInfo.id)
+        }
       }
     }
   }

src/index.ts

@@ -1,133 +1,267 @@
-import type { Plugin } from "@opencode-ai/plugin"
-import { createBuiltinAgents } from "./agents"
-import { createTodoContinuationEnforcer, createContextWindowMonitorHook, createSessionRecoveryHook, createCommentCheckerHooks } from "./hooks"
-import { updateTerminalTitle } from "./features/terminal"
-import { builtinTools } from "./tools"
-import { createBuiltinMcps } from "./mcp"
-import { OhMyOpenCodeConfigSchema, type OhMyOpenCodeConfig } from "./config"
-import * as fs from "fs"
-import * as path from "path"
+import type { Plugin } from "@opencode-ai/plugin";
+import { createBuiltinAgents } from "./agents";
+import {
+  createTodoContinuationEnforcer,
+  createContextWindowMonitorHook,
+  createSessionRecoveryHook,
+  createCommentCheckerHooks,
+  createGrepOutputTruncatorHook,
+  createDirectoryAgentsInjectorHook,
+  createDirectoryReadmeInjectorHook,
+  createEmptyTaskResponseDetectorHook,
+  createThinkModeHook,
+  createClaudeCodeHooksHook,
+  createAnthropicAutoCompactHook,
+} from "./hooks";
+import {
+  loadUserCommands,
+  loadProjectCommands,
+  loadOpencodeGlobalCommands,
+  loadOpencodeProjectCommands,
+} from "./features/claude-code-command-loader";
+import {
+  loadUserSkillsAsCommands,
+  loadProjectSkillsAsCommands,
+} from "./features/claude-code-skill-loader";
+import {
+  loadUserAgents,
+  loadProjectAgents,
+} from "./features/claude-code-agent-loader";
+import { loadMcpConfigs } from "./features/claude-code-mcp-loader";
+import {
+  setCurrentSession,
+  setMainSession,
+  getMainSessionID,
+  getCurrentSessionTitle,
+} from "./features/claude-code-session-state";
+import { updateTerminalTitle } from "./features/terminal";
+import { builtinTools } from "./tools";
+import { createBuiltinMcps } from "./mcp";
+import { OhMyOpenCodeConfigSchema, type OhMyOpenCodeConfig } from "./config";
+import { log } from "./shared/logger";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
 
-function loadPluginConfig(directory: string): OhMyOpenCodeConfig {
-  const configPaths = [
-    path.join(directory, "oh-my-opencode.json"),
-    path.join(directory, ".oh-my-opencode.json"),
-  ]
-
-  for (const configPath of configPaths) {
-    try {
-      if (fs.existsSync(configPath)) {
-        const content = fs.readFileSync(configPath, "utf-8")
-        const rawConfig = JSON.parse(content)
-        const result = OhMyOpenCodeConfigSchema.safeParse(rawConfig)
-
-        if (!result.success) {
-          console.error(`[oh-my-opencode] Config validation error in ${configPath}:`)
-          for (const issue of result.error.issues) {
-            console.error(`  - ${issue.path.join(".")}: ${issue.message}`)
-          }
-          return {}
-        }
-
-        return result.data
-      }
-    } catch {
-      // Ignore parse errors, use defaults
-    }
+/**
+ * Returns the user-level config directory based on the OS.
+ * - Linux/macOS: XDG_CONFIG_HOME or ~/.config
+ * - Windows: %APPDATA%
+ */
+function getUserConfigDir(): string {
+  if (process.platform === "win32") {
+    return process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
   }
 
-  return {}
+  // Linux, macOS, and other Unix-like systems: respect XDG_CONFIG_HOME
+  return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+}
+
+function loadConfigFromPath(configPath: string): OhMyOpenCodeConfig | null {
+  try {
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, "utf-8");
+      const rawConfig = JSON.parse(content);
+      const result = OhMyOpenCodeConfigSchema.safeParse(rawConfig);
+
+      if (!result.success) {
+        log(`Config validation error in ${configPath}:`, result.error.issues);
+        return null;
+      }
+
+      log(`Config loaded from ${configPath}`, { agents: result.data.agents });
+      return result.data;
+    }
+  } catch (err) {
+    log(`Error loading config from ${configPath}:`, err);
+  }
+  return null;
+}
+
+function mergeConfigs(
+  base: OhMyOpenCodeConfig,
+  override: OhMyOpenCodeConfig
+): OhMyOpenCodeConfig {
+  return {
+    ...base,
+    ...override,
+    agents:
+      override.agents !== undefined
+        ? { ...(base.agents ?? {}), ...override.agents }
+        : base.agents,
+    disabled_agents: [
+      ...new Set([
+        ...(base.disabled_agents ?? []),
+        ...(override.disabled_agents ?? []),
+      ]),
+    ],
+    disabled_mcps: [
+      ...new Set([
+        ...(base.disabled_mcps ?? []),
+        ...(override.disabled_mcps ?? []),
+      ]),
+    ],
+  };
+}
+
+function loadPluginConfig(directory: string): OhMyOpenCodeConfig {
+  // User-level config path (OS-specific)
+  const userConfigPath = path.join(
+    getUserConfigDir(),
+    "opencode",
+    "oh-my-opencode.json"
+  );
+
+  // Project-level config path
+  const projectConfigPath = path.join(
+    directory,
+    ".opencode",
+    "oh-my-opencode.json"
+  );
+
+  // Load user config first (base)
+  let config: OhMyOpenCodeConfig = loadConfigFromPath(userConfigPath) ?? {};
+
+  // Override with project config
+  const projectConfig = loadConfigFromPath(projectConfigPath);
+  if (projectConfig) {
+    config = mergeConfigs(config, projectConfig);
+  }
+
+  log("Final merged config", {
+    agents: config.agents,
+    disabled_agents: config.disabled_agents,
+    disabled_mcps: config.disabled_mcps,
+  });
+  return config;
 }
 
 const OhMyOpenCodePlugin: Plugin = async (ctx) => {
-  const todoContinuationEnforcer = createTodoContinuationEnforcer(ctx)
-  const contextWindowMonitor = createContextWindowMonitorHook(ctx)
-  const sessionRecovery = createSessionRecoveryHook(ctx)
-  const commentChecker = createCommentCheckerHooks()
+  const pluginConfig = loadPluginConfig(ctx.directory);
 
-  updateTerminalTitle({ sessionId: "main" })
+  const todoContinuationEnforcer = createTodoContinuationEnforcer(ctx);
+  const contextWindowMonitor = createContextWindowMonitorHook(ctx);
+  const sessionRecovery = createSessionRecoveryHook(ctx);
+  const commentChecker = createCommentCheckerHooks();
+  const grepOutputTruncator = createGrepOutputTruncatorHook(ctx);
+  const directoryAgentsInjector = createDirectoryAgentsInjectorHook(ctx);
+  const directoryReadmeInjector = createDirectoryReadmeInjectorHook(ctx);
+  const emptyTaskResponseDetector = createEmptyTaskResponseDetectorHook(ctx);
+  const thinkMode = createThinkModeHook();
+  const claudeCodeHooks = createClaudeCodeHooksHook(ctx, {});
+  const anthropicAutoCompact = createAnthropicAutoCompactHook(ctx);
 
-  const pluginConfig = loadPluginConfig(ctx.directory)
-
-  let mainSessionID: string | undefined
-  let currentSessionID: string | undefined
-  let currentSessionTitle: string | undefined
+  updateTerminalTitle({ sessionId: "main" });
 
   return {
     tool: builtinTools,
 
+    "chat.message": async (input, output) => {
+      await claudeCodeHooks["chat.message"]?.(input, output)
+    },
+
     config: async (config) => {
-      const agents = createBuiltinAgents(
+      const builtinAgents = createBuiltinAgents(
         pluginConfig.disabled_agents,
-        pluginConfig.agents
-      )
+        pluginConfig.agents,
+      );
+      const userAgents = loadUserAgents();
+      const projectAgents = loadProjectAgents();
 
       config.agent = {
+        ...builtinAgents,
+        ...userAgents,
+        ...projectAgents,
         ...config.agent,
-        ...agents,
-      }
+      };
       config.tools = {
         ...config.tools,
-        grep: false,
-      }
+      };
+
+      const mcpResult = await loadMcpConfigs();
       config.mcp = {
         ...config.mcp,
         ...createBuiltinMcps(pluginConfig.disabled_mcps),
-      }
+        ...mcpResult.servers,
+      };
+
+      const userCommands = loadUserCommands();
+      const opencodeGlobalCommands = loadOpencodeGlobalCommands();
+      const systemCommands = config.command ?? {};
+      const projectCommands = loadProjectCommands();
+      const opencodeProjectCommands = loadOpencodeProjectCommands();
+      const userSkills = loadUserSkillsAsCommands();
+      const projectSkills = loadProjectSkillsAsCommands();
+
+      config.command = {
+        ...userCommands,
+        ...userSkills,
+        ...opencodeGlobalCommands,
+        ...systemCommands,
+        ...projectCommands,
+        ...projectSkills,
+        ...opencodeProjectCommands,
+      };
     },
 
     event: async (input) => {
-      await todoContinuationEnforcer(input)
-      await contextWindowMonitor.event(input)
+      await claudeCodeHooks.event(input);
+      await todoContinuationEnforcer(input);
+      await contextWindowMonitor.event(input);
+      await directoryAgentsInjector.event(input);
+      await directoryReadmeInjector.event(input);
+      await thinkMode.event(input);
+      await anthropicAutoCompact.event(input);
 
-      const { event } = input
-      const props = event.properties as Record<string, unknown> | undefined
+      const { event } = input;
+      const props = event.properties as Record<string, unknown> | undefined;
 
       if (event.type === "session.created") {
-        const sessionInfo = props?.info as { id?: string; title?: string; parentID?: string } | undefined
+        const sessionInfo = props?.info as
+          | { id?: string; title?: string; parentID?: string }
+          | undefined;
         if (!sessionInfo?.parentID) {
-          mainSessionID = sessionInfo?.id
-          currentSessionID = sessionInfo?.id
-          currentSessionTitle = sessionInfo?.title
+          setMainSession(sessionInfo?.id);
+          setCurrentSession(sessionInfo?.id, sessionInfo?.title);
           updateTerminalTitle({
-            sessionId: currentSessionID || "main",
+            sessionId: sessionInfo?.id || "main",
             status: "idle",
             directory: ctx.directory,
-            sessionTitle: currentSessionTitle,
-          })
+            sessionTitle: sessionInfo?.title,
+          });
         }
       }
 
       if (event.type === "session.updated") {
-        const sessionInfo = props?.info as { id?: string; title?: string; parentID?: string } | undefined
+        const sessionInfo = props?.info as
+          | { id?: string; title?: string; parentID?: string }
+          | undefined;
         if (!sessionInfo?.parentID) {
-          currentSessionID = sessionInfo?.id
-          currentSessionTitle = sessionInfo?.title
+          setCurrentSession(sessionInfo?.id, sessionInfo?.title);
           updateTerminalTitle({
-            sessionId: currentSessionID || "main",
+            sessionId: sessionInfo?.id || "main",
             status: "processing",
             directory: ctx.directory,
-            sessionTitle: currentSessionTitle,
-          })
+            sessionTitle: sessionInfo?.title,
+          });
         }
       }
 
       if (event.type === "session.deleted") {
-        const sessionInfo = props?.info as { id?: string } | undefined
-        if (sessionInfo?.id === mainSessionID) {
-          mainSessionID = undefined
-          currentSessionID = undefined
-          currentSessionTitle = undefined
+        const sessionInfo = props?.info as { id?: string } | undefined;
+        if (sessionInfo?.id === getMainSessionID()) {
+          setMainSession(undefined);
+          setCurrentSession(undefined, undefined);
           updateTerminalTitle({
             sessionId: "main",
             status: "idle",
-          })
+          });
         }
       }
 
       if (event.type === "session.error") {
-        const sessionID = props?.sessionID as string | undefined
-        const error = props?.error
+        const sessionID = props?.sessionID as string | undefined;
+        const error = props?.error;
 
         if (sessionRecovery.isRecoverableError(error)) {
           const messageInfo = {
@@ -135,64 +269,81 @@ const OhMyOpenCodePlugin: Plugin = async (ctx) => {
             role: "assistant" as const,
             sessionID,
             error,
+          };
+          const recovered =
+            await sessionRecovery.handleSessionRecovery(messageInfo);
+
+          if (recovered && sessionID && sessionID === getMainSessionID()) {
+            await ctx.client.session
+              .prompt({
+                path: { id: sessionID },
+                body: { parts: [{ type: "text", text: "continue" }] },
+                query: { directory: ctx.directory },
+              })
+              .catch(() => {});
           }
-          await sessionRecovery.handleSessionRecovery(messageInfo)
         }
 
-        if (sessionID && sessionID === mainSessionID) {
+        if (sessionID && sessionID === getMainSessionID()) {
           updateTerminalTitle({
             sessionId: sessionID,
             status: "error",
             directory: ctx.directory,
-            sessionTitle: currentSessionTitle,
-          })
+            sessionTitle: getCurrentSessionTitle(),
+          });
         }
       }
 
       if (event.type === "session.idle") {
-        const sessionID = props?.sessionID as string | undefined
-        if (sessionID && sessionID === mainSessionID) {
+        const sessionID = props?.sessionID as string | undefined;
+        if (sessionID && sessionID === getMainSessionID()) {
           updateTerminalTitle({
             sessionId: sessionID,
             status: "idle",
             directory: ctx.directory,
-            sessionTitle: currentSessionTitle,
-          })
+            sessionTitle: getCurrentSessionTitle(),
+          });
         }
       }
     },
 
     "tool.execute.before": async (input, output) => {
-      await commentChecker["tool.execute.before"](input, output)
+      await claudeCodeHooks["tool.execute.before"](input, output);
+      await commentChecker["tool.execute.before"](input, output);
 
-      if (input.sessionID === mainSessionID) {
+      if (input.sessionID === getMainSessionID()) {
         updateTerminalTitle({
           sessionId: input.sessionID,
           status: "tool",
           currentTool: input.tool,
           directory: ctx.directory,
-          sessionTitle: currentSessionTitle,
-        })
+          sessionTitle: getCurrentSessionTitle(),
+        });
       }
     },
 
     "tool.execute.after": async (input, output) => {
-      await contextWindowMonitor["tool.execute.after"](input, output)
-      await commentChecker["tool.execute.after"](input, output)
+      await claudeCodeHooks["tool.execute.after"](input, output);
+      await grepOutputTruncator["tool.execute.after"](input, output);
+      await contextWindowMonitor["tool.execute.after"](input, output);
+      await commentChecker["tool.execute.after"](input, output);
+      await directoryAgentsInjector["tool.execute.after"](input, output);
+      await directoryReadmeInjector["tool.execute.after"](input, output);
+      await emptyTaskResponseDetector["tool.execute.after"](input, output);
 
-      if (input.sessionID === mainSessionID) {
+      if (input.sessionID === getMainSessionID()) {
         updateTerminalTitle({
           sessionId: input.sessionID,
           status: "idle",
           directory: ctx.directory,
-          sessionTitle: currentSessionTitle,
-        })
+          sessionTitle: getCurrentSessionTitle(),
+        });
       }
     },
-  }
-}
+  };
+};
 
-export default OhMyOpenCodePlugin
+export default OhMyOpenCodePlugin;
 
 export type {
   OhMyOpenCodeConfig,
@@ -200,4 +351,4 @@ export type {
   AgentOverrideConfig,
   AgentOverrides,
   McpName,
-} from "./config"
+} from "./config";

src/mcp/index.ts

@@ -20,5 +20,3 @@ export function createBuiltinMcps(disabledMcps: McpName[] = []) {
 
   return mcps
 }
-
-export const builtinMcps = allBuiltinMcps

src/shared/command-executor.ts

@@ -0,0 +1,203 @@
+import { spawn } from "child_process"
+import { exec } from "child_process"
+import { promisify } from "util"
+import { existsSync } from "fs"
+
+const DEFAULT_ZSH_PATHS = ["/bin/zsh", "/usr/bin/zsh", "/usr/local/bin/zsh"]
+
+function findZshPath(customZshPath?: string): string | null {
+  if (customZshPath && existsSync(customZshPath)) {
+    return customZshPath
+  }
+  for (const path of DEFAULT_ZSH_PATHS) {
+    if (existsSync(path)) {
+      return path
+    }
+  }
+  return null
+}
+
+const execAsync = promisify(exec)
+
+export interface CommandResult {
+  exitCode: number
+  stdout?: string
+  stderr?: string
+}
+
+export interface ExecuteHookOptions {
+  forceZsh?: boolean
+  zshPath?: string
+}
+
+/**
+ * Execute a hook command with stdin input
+ */
+export async function executeHookCommand(
+  command: string,
+  stdin: string,
+  cwd: string,
+  options?: ExecuteHookOptions
+): Promise<CommandResult> {
+  const home = process.env.HOME ?? ""
+
+  let expandedCommand = command
+    .replace(/^~(?=\/|$)/g, home)
+    .replace(/\s~(?=\/)/g, ` ${home}`)
+    .replace(/\$CLAUDE_PROJECT_DIR/g, cwd)
+    .replace(/\$\{CLAUDE_PROJECT_DIR\}/g, cwd)
+
+  let finalCommand = expandedCommand
+
+  if (options?.forceZsh) {
+    const zshPath = options.zshPath || findZshPath()
+    if (zshPath) {
+      const escapedCommand = expandedCommand.replace(/'/g, "'\\''")
+      finalCommand = `${zshPath} -lc '${escapedCommand}'`
+    }
+  }
+
+  return new Promise((resolve) => {
+    const proc = spawn(finalCommand, {
+      cwd,
+      shell: true,
+      env: { ...process.env, HOME: home, CLAUDE_PROJECT_DIR: cwd },
+    })
+
+    let stdout = ""
+    let stderr = ""
+
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString()
+    })
+
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString()
+    })
+
+    proc.stdin?.write(stdin)
+    proc.stdin?.end()
+
+    proc.on("close", (code) => {
+      resolve({
+        exitCode: code ?? 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+      })
+    })
+
+    proc.on("error", (err) => {
+      resolve({
+        exitCode: 1,
+        stderr: err.message,
+      })
+    })
+  })
+}
+
+/**
+ * Execute a simple command and return output
+ */
+export async function executeCommand(command: string): Promise<string> {
+  try {
+    const { stdout, stderr } = await execAsync(command)
+
+    const out = stdout?.toString().trim() ?? ""
+    const err = stderr?.toString().trim() ?? ""
+
+    if (err) {
+      if (out) {
+        return `${out}\n[stderr: ${err}]`
+      }
+      return `[stderr: ${err}]`
+    }
+
+    return out
+  } catch (error: unknown) {
+    const e = error as { stdout?: Buffer; stderr?: Buffer; message?: string }
+    const stdout = e?.stdout?.toString().trim() ?? ""
+    const stderr = e?.stderr?.toString().trim() ?? ""
+    const errMsg = stderr || e?.message || String(error)
+
+    if (stdout) {
+      return `${stdout}\n[stderr: ${errMsg}]`
+    }
+    return `[stderr: ${errMsg}]`
+  }
+}
+
+/**
+ * Find and execute embedded commands in text (!`command`)
+ */
+interface CommandMatch {
+  fullMatch: string
+  command: string
+  start: number
+  end: number
+}
+
+const COMMAND_PATTERN = /!`([^`]+)`/g
+
+function findCommands(text: string): CommandMatch[] {
+  const matches: CommandMatch[] = []
+  let match: RegExpExecArray | null
+
+  COMMAND_PATTERN.lastIndex = 0
+
+  while ((match = COMMAND_PATTERN.exec(text)) !== null) {
+    matches.push({
+      fullMatch: match[0],
+      command: match[1],
+      start: match.index,
+      end: match.index + match[0].length,
+    })
+  }
+
+  return matches
+}
+
+/**
+ * Resolve embedded commands in text recursively
+ */
+export async function resolveCommandsInText(
+  text: string,
+  depth: number = 0,
+  maxDepth: number = 3
+): Promise<string> {
+  if (depth >= maxDepth) {
+    return text
+  }
+
+  const matches = findCommands(text)
+  if (matches.length === 0) {
+    return text
+  }
+
+  const tasks = matches.map((m) => executeCommand(m.command))
+  const results = await Promise.allSettled(tasks)
+
+  const replacements = new Map<string, string>()
+
+  matches.forEach((match, idx) => {
+    const result = results[idx]
+    if (result.status === "rejected") {
+      replacements.set(
+        match.fullMatch,
+        `[error: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}]`
+      )
+    } else {
+      replacements.set(match.fullMatch, result.value)
+    }
+  })
+
+  let resolved = text
+  for (const [pattern, replacement] of replacements.entries()) {
+    resolved = resolved.split(pattern).join(replacement)
+  }
+
+  if (findCommands(resolved).length > 0) {
+    return resolveCommandsInText(resolved, depth + 1, maxDepth)
+  }
+
+  return resolved
+}

src/shared/file-reference-resolver.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync, statSync } from "fs"
+import { join, isAbsolute } from "path"
+
+interface FileMatch {
+  fullMatch: string
+  filePath: string
+  start: number
+  end: number
+}
+
+const FILE_REFERENCE_PATTERN = /@([^\s@]+)/g
+
+function findFileReferences(text: string): FileMatch[] {
+  const matches: FileMatch[] = []
+  let match: RegExpExecArray | null
+
+  FILE_REFERENCE_PATTERN.lastIndex = 0
+
+  while ((match = FILE_REFERENCE_PATTERN.exec(text)) !== null) {
+    matches.push({
+      fullMatch: match[0],
+      filePath: match[1],
+      start: match.index,
+      end: match.index + match[0].length,
+    })
+  }
+
+  return matches
+}
+
+function resolveFilePath(filePath: string, cwd: string): string {
+  if (isAbsolute(filePath)) {
+    return filePath
+  }
+  return join(cwd, filePath)
+}
+
+function readFileContent(resolvedPath: string): string {
+  if (!existsSync(resolvedPath)) {
+    return `[file not found: ${resolvedPath}]`
+  }
+
+  const stat = statSync(resolvedPath)
+  if (stat.isDirectory()) {
+    return `[cannot read directory: ${resolvedPath}]`
+  }
+
+  const content = readFileSync(resolvedPath, "utf-8")
+  return content
+}
+
+export async function resolveFileReferencesInText(
+  text: string,
+  cwd: string = process.cwd(),
+  depth: number = 0,
+  maxDepth: number = 3
+): Promise<string> {
+  if (depth >= maxDepth) {
+    return text
+  }
+
+  const matches = findFileReferences(text)
+  if (matches.length === 0) {
+    return text
+  }
+
+  const replacements = new Map<string, string>()
+
+  for (const match of matches) {
+    const resolvedPath = resolveFilePath(match.filePath, cwd)
+    const content = readFileContent(resolvedPath)
+    replacements.set(match.fullMatch, content)
+  }
+
+  let resolved = text
+  for (const [pattern, replacement] of replacements.entries()) {
+    resolved = resolved.split(pattern).join(replacement)
+  }
+
+  if (findFileReferences(resolved).length > 0 && depth + 1 < maxDepth) {
+    return resolveFileReferencesInText(resolved, cwd, depth + 1, maxDepth)
+  }
+
+  return resolved
+}

src/shared/frontmatter.ts

@@ -0,0 +1,34 @@
+export interface FrontmatterResult<T = Record<string, string>> {
+  data: T
+  body: string
+}
+
+export function parseFrontmatter<T = Record<string, string>>(
+  content: string
+): FrontmatterResult<T> {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/
+  const match = content.match(frontmatterRegex)
+
+  if (!match) {
+    return { data: {} as T, body: content }
+  }
+
+  const yamlContent = match[1]
+  const body = match[2]
+
+  const data: Record<string, string | boolean> = {}
+  for (const line of yamlContent.split("\n")) {
+    const colonIndex = line.indexOf(":")
+    if (colonIndex !== -1) {
+      const key = line.slice(0, colonIndex).trim()
+      let value: string | boolean = line.slice(colonIndex + 1).trim()
+
+      if (value === "true") value = true
+      else if (value === "false") value = false
+
+      data[key] = value
+    }
+  }
+
+  return { data: data as T, body }
+}

src/shared/hook-disabled.ts

@@ -0,0 +1,22 @@
+import type { ClaudeHookEvent, PluginConfig } from "../hooks/claude-code-hooks/types"
+
+export function isHookDisabled(
+  config: PluginConfig,
+  hookType: ClaudeHookEvent
+): boolean {
+  const { disabledHooks } = config
+
+  if (disabledHooks === undefined) {
+    return false
+  }
+
+  if (disabledHooks === true) {
+    return true
+  }
+
+  if (Array.isArray(disabledHooks)) {
+    return disabledHooks.includes(hookType)
+  }
+
+  return false
+}

src/shared/index.ts

@@ -0,0 +1,9 @@
+export * from "./frontmatter"
+export * from "./command-executor"
+export * from "./file-reference-resolver"
+export * from "./model-sanitizer"
+export * from "./logger"
+export * from "./snake-case"
+export * from "./tool-name"
+export * from "./pattern-matcher"
+export * from "./hook-disabled"

src/shared/logger.ts

@@ -0,0 +1,20 @@
+// Shared logging utility for the plugin
+
+import * as fs from "fs"
+import * as os from "os"
+import * as path from "path"
+
+const logFile = path.join(os.tmpdir(), "oh-my-opencode.log")
+
+export function log(message: string, data?: unknown): void {
+  try {
+    const timestamp = new Date().toISOString()
+    const logEntry = `[${timestamp}] ${message} ${data ? JSON.stringify(data) : ""}\n`
+    fs.appendFileSync(logFile, logEntry)
+  } catch {
+  }
+}
+
+export function getLogFilePath(): string {
+  return logFile
+}

src/shared/model-sanitizer.ts

@@ -0,0 +1,13 @@
+/**
+ * Sanitizes model field from frontmatter.
+ * Always returns undefined to let SDK use default model.
+ *
+ * Claude Code and OpenCode use different model ID formats,
+ * so we ignore the model field and let OpenCode use its configured default.
+ *
+ * @param _model - Raw model value from frontmatter (ignored)
+ * @returns Always undefined to inherit default model
+ */
+export function sanitizeModelField(_model: unknown): undefined {
+  return undefined
+}

src/shared/pattern-matcher.ts

@@ -0,0 +1,29 @@
+import type { ClaudeHooksConfig, HookMatcher } from "../hooks/claude-code-hooks/types"
+
+export function matchesToolMatcher(toolName: string, matcher: string): boolean {
+  if (!matcher) {
+    return true
+  }
+  const patterns = matcher.split("|").map((p) => p.trim())
+  return patterns.some((p) => {
+    if (p.includes("*")) {
+      const regex = new RegExp(`^${p.replace(/\*/g, ".*")}$`, "i")
+      return regex.test(toolName)
+    }
+    return p.toLowerCase() === toolName.toLowerCase()
+  })
+}
+
+export function findMatchingHooks(
+  config: ClaudeHooksConfig,
+  eventName: keyof ClaudeHooksConfig,
+  toolName?: string
+): HookMatcher[] {
+  const hookMatchers = config[eventName]
+  if (!hookMatchers) return []
+
+  return hookMatchers.filter((hookMatcher) => {
+    if (!toolName) return true
+    return matchesToolMatcher(toolName, hookMatcher.matcher)
+  })
+}

src/shared/snake-case.ts

@@ -0,0 +1,51 @@
+export function camelToSnake(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+export function snakeToCamel(str: string): string {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase())
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function objectToSnakeCase(
+  obj: Record<string, unknown>,
+  deep: boolean = true
+): Record<string, unknown> {
+   const result: Record<string, unknown> = {}
+   for (const [key, value] of Object.entries(obj)) {
+     const snakeKey = camelToSnake(key)
+     if (deep && isPlainObject(value)) {
+       result[snakeKey] = objectToSnakeCase(value, true)
+     } else if (deep && Array.isArray(value)) {
+       result[snakeKey] = value.map((item) =>
+         isPlainObject(item) ? objectToSnakeCase(item, true) : item
+       )
+     } else {
+       result[snakeKey] = value
+     }
+   }
+   return result
+ }
+
+export function objectToCamelCase(
+  obj: Record<string, unknown>,
+  deep: boolean = true
+): Record<string, unknown> {
+   const result: Record<string, unknown> = {}
+   for (const [key, value] of Object.entries(obj)) {
+     const camelKey = snakeToCamel(key)
+     if (deep && isPlainObject(value)) {
+       result[camelKey] = objectToCamelCase(value, true)
+     } else if (deep && Array.isArray(value)) {
+       result[camelKey] = value.map((item) =>
+         isPlainObject(item) ? objectToCamelCase(item, true) : item
+       )
+     } else {
+       result[camelKey] = value
+     }
+   }
+   return result
+ }

src/shared/tool-name.ts

@@ -0,0 +1,26 @@
+const SPECIAL_TOOL_MAPPINGS: Record<string, string> = {
+  webfetch: "WebFetch",
+  websearch: "WebSearch",
+  todoread: "TodoRead",
+  todowrite: "TodoWrite",
+}
+
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join("")
+}
+
+export function transformToolName(toolName: string): string {
+  const lower = toolName.toLowerCase()
+  if (lower in SPECIAL_TOOL_MAPPINGS) {
+    return SPECIAL_TOOL_MAPPINGS[lower]
+  }
+
+  if (toolName.includes("-") || toolName.includes("_")) {
+    return toPascalCase(toolName)
+  }
+
+  return toolName.charAt(0).toUpperCase() + toolName.slice(1)
+}

src/tools/ast-grep/cli.ts

@@ -1,6 +1,15 @@
 import { spawn } from "bun"
-import { SG_CLI_PATH } from "./constants"
-import type { CliMatch, CliLanguage } from "./types"
+import { existsSync } from "fs"
+import {
+  getSgCliPath,
+  setSgCliPath,
+  findSgCliPathSync,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_MAX_OUTPUT_BYTES,
+  DEFAULT_MAX_MATCHES,
+} from "./constants"
+import { ensureAstGrepBinary } from "./downloader"
+import type { CliMatch, CliLanguage, SgResult } from "./types"
 
 export interface RunOptions {
   pattern: string
@@ -12,7 +21,47 @@ export interface RunOptions {
   updateAll?: boolean
 }
 
-export async function runSg(options: RunOptions): Promise<CliMatch[]> {
+let resolvedCliPath: string | null = null
+let initPromise: Promise<string | null> | null = null
+
+export async function getAstGrepPath(): Promise<string | null> {
+  if (resolvedCliPath !== null && existsSync(resolvedCliPath)) {
+    return resolvedCliPath
+  }
+
+  if (initPromise) {
+    return initPromise
+  }
+
+  initPromise = (async () => {
+    const syncPath = findSgCliPathSync()
+    if (syncPath && existsSync(syncPath)) {
+      resolvedCliPath = syncPath
+      setSgCliPath(syncPath)
+      return syncPath
+    }
+
+    const downloadedPath = await ensureAstGrepBinary()
+    if (downloadedPath) {
+      resolvedCliPath = downloadedPath
+      setSgCliPath(downloadedPath)
+      return downloadedPath
+    }
+
+    return null
+  })()
+
+  return initPromise
+}
+
+export function startBackgroundInit(): void {
+  if (!initPromise) {
+    initPromise = getAstGrepPath()
+    initPromise.catch(() => {})
+  }
+}
+
+export async function runSg(options: RunOptions): Promise<SgResult> {
   const args = ["run", "-p", options.pattern, "--lang", options.lang, "--json=compact"]
 
   if (options.rewrite) {
@@ -35,32 +84,147 @@ export async function runSg(options: RunOptions): Promise<CliMatch[]> {
   const paths = options.paths && options.paths.length > 0 ? options.paths : ["."]
   args.push(...paths)
 
-  const proc = spawn([SG_CLI_PATH, ...args], {
+  let cliPath = getSgCliPath()
+
+  if (!existsSync(cliPath) && cliPath !== "sg") {
+    const downloadedPath = await getAstGrepPath()
+    if (downloadedPath) {
+      cliPath = downloadedPath
+    }
+  }
+
+  const timeout = DEFAULT_TIMEOUT_MS
+
+  const proc = spawn([cliPath, ...args], {
     stdout: "pipe",
     stderr: "pipe",
   })
 
-  const stdout = await new Response(proc.stdout).text()
-  const stderr = await new Response(proc.stderr).text()
-  const exitCode = await proc.exited
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    const id = setTimeout(() => {
+      proc.kill()
+      reject(new Error(`Search timeout after ${timeout}ms`))
+    }, timeout)
+    proc.exited.then(() => clearTimeout(id))
+  })
+
+  let stdout: string
+  let stderr: string
+  let exitCode: number
+
+  try {
+    stdout = await Promise.race([new Response(proc.stdout).text(), timeoutPromise])
+    stderr = await new Response(proc.stderr).text()
+    exitCode = await proc.exited
+  } catch (e) {
+    const error = e as Error
+    if (error.message?.includes("timeout")) {
+      return {
+        matches: [],
+        totalMatches: 0,
+        truncated: true,
+        truncatedReason: "timeout",
+        error: error.message,
+      }
+    }
+
+    const nodeError = e as NodeJS.ErrnoException
+    if (
+      nodeError.code === "ENOENT" ||
+      nodeError.message?.includes("ENOENT") ||
+      nodeError.message?.includes("not found")
+    ) {
+      const downloadedPath = await ensureAstGrepBinary()
+      if (downloadedPath) {
+        resolvedCliPath = downloadedPath
+        setSgCliPath(downloadedPath)
+        return runSg(options)
+      } else {
+        return {
+          matches: [],
+          totalMatches: 0,
+          truncated: false,
+          error:
+            `ast-grep CLI binary not found.\n\n` +
+            `Auto-download failed. Manual install options:\n` +
+            `  bun add -D @ast-grep/cli\n` +
+            `  cargo install ast-grep --locked\n` +
+            `  brew install ast-grep`,
+        }
+      }
+    }
+
+    return {
+      matches: [],
+      totalMatches: 0,
+      truncated: false,
+      error: `Failed to spawn ast-grep: ${error.message}`,
+    }
+  }
 
   if (exitCode !== 0 && stdout.trim() === "") {
     if (stderr.includes("No files found")) {
-      return []
+      return { matches: [], totalMatches: 0, truncated: false }
     }
     if (stderr.trim()) {
-      throw new Error(stderr.trim())
+      return { matches: [], totalMatches: 0, truncated: false, error: stderr.trim() }
     }
-    return []
+    return { matches: [], totalMatches: 0, truncated: false }
   }
 
   if (!stdout.trim()) {
-    return []
+    return { matches: [], totalMatches: 0, truncated: false }
   }
 
+  const outputTruncated = stdout.length >= DEFAULT_MAX_OUTPUT_BYTES
+  const outputToProcess = outputTruncated ? stdout.substring(0, DEFAULT_MAX_OUTPUT_BYTES) : stdout
+
+  let matches: CliMatch[] = []
   try {
-    return JSON.parse(stdout) as CliMatch[]
+    matches = JSON.parse(outputToProcess) as CliMatch[]
   } catch {
-    return []
+    if (outputTruncated) {
+      try {
+        const lastValidIndex = outputToProcess.lastIndexOf("}")
+        if (lastValidIndex > 0) {
+          const bracketIndex = outputToProcess.lastIndexOf("},", lastValidIndex)
+          if (bracketIndex > 0) {
+            const truncatedJson = outputToProcess.substring(0, bracketIndex + 1) + "]"
+            matches = JSON.parse(truncatedJson) as CliMatch[]
+          }
+        }
+      } catch {
+        return {
+          matches: [],
+          totalMatches: 0,
+          truncated: true,
+          truncatedReason: "max_output_bytes",
+          error: "Output too large and could not be parsed",
+        }
+      }
+    } else {
+      return { matches: [], totalMatches: 0, truncated: false }
+    }
+  }
+
+  const totalMatches = matches.length
+  const matchesTruncated = totalMatches > DEFAULT_MAX_MATCHES
+  const finalMatches = matchesTruncated ? matches.slice(0, DEFAULT_MAX_MATCHES) : matches
+
+  return {
+    matches: finalMatches,
+    totalMatches,
+    truncated: outputTruncated || matchesTruncated,
+    truncatedReason: outputTruncated ? "max_output_bytes" : matchesTruncated ? "max_matches" : undefined,
   }
 }
+
+export function isCliAvailable(): boolean {
+  const path = findSgCliPathSync()
+  return path !== null && existsSync(path)
+}
+
+export async function ensureCliAvailable(): Promise<boolean> {
+  const path = await getAstGrepPath()
+  return path !== null && existsSync(path)
+}

src/tools/ast-grep/constants.ts

@@ -1,9 +1,18 @@
 import { createRequire } from "module"
 import { dirname, join } from "path"
-import { existsSync } from "fs"
+import { existsSync, statSync } from "fs"
+import { getCachedBinaryPath } from "./downloader"
 
 type Platform = "darwin" | "linux" | "win32" | "unsupported"
 
+function isValidBinary(filePath: string): boolean {
+  try {
+    return statSync(filePath).size > 10000
+  } catch {
+    return false
+  }
+}
+
 function getPlatformPackageName(): string | null {
   const platform = process.platform as Platform
   const arch = process.arch
@@ -21,32 +30,37 @@ function getPlatformPackageName(): string | null {
   return platformMap[`${platform}-${arch}`] ?? null
 }
 
-function findSgCliPath(): string {
-  // 1. Try to find from @ast-grep/cli package (installed via npm)
+export function findSgCliPathSync(): string | null {
+  const binaryName = process.platform === "win32" ? "sg.exe" : "sg"
+
+  const cachedPath = getCachedBinaryPath()
+  if (cachedPath && isValidBinary(cachedPath)) {
+    return cachedPath
+  }
+
   try {
     const require = createRequire(import.meta.url)
     const cliPkgPath = require.resolve("@ast-grep/cli/package.json")
     const cliDir = dirname(cliPkgPath)
-    const sgPath = join(cliDir, process.platform === "win32" ? "sg.exe" : "sg")
+    const sgPath = join(cliDir, binaryName)
 
-    if (existsSync(sgPath)) {
+    if (existsSync(sgPath) && isValidBinary(sgPath)) {
       return sgPath
     }
   } catch {
-    // @ast-grep/cli not installed, try platform-specific package
+    // @ast-grep/cli not installed
   }
 
-  // 2. Try platform-specific package directly
   const platformPkg = getPlatformPackageName()
   if (platformPkg) {
     try {
       const require = createRequire(import.meta.url)
       const pkgPath = require.resolve(`${platformPkg}/package.json`)
       const pkgDir = dirname(pkgPath)
-      const binaryName = process.platform === "win32" ? "ast-grep.exe" : "ast-grep"
-      const binaryPath = join(pkgDir, binaryName)
+      const astGrepName = process.platform === "win32" ? "ast-grep.exe" : "ast-grep"
+      const binaryPath = join(pkgDir, astGrepName)
 
-      if (existsSync(binaryPath)) {
+      if (existsSync(binaryPath) && isValidBinary(binaryPath)) {
         return binaryPath
       }
     } catch {
@@ -54,12 +68,39 @@ function findSgCliPath(): string {
     }
   }
 
-  // 3. Fallback to system PATH
+  if (process.platform === "darwin") {
+    const homebrewPaths = ["/opt/homebrew/bin/sg", "/usr/local/bin/sg"]
+    for (const path of homebrewPaths) {
+      if (existsSync(path) && isValidBinary(path)) {
+        return path
+      }
+    }
+  }
+
+  return null
+}
+
+let resolvedCliPath: string | null = null
+
+export function getSgCliPath(): string {
+  if (resolvedCliPath !== null) {
+    return resolvedCliPath
+  }
+
+  const syncPath = findSgCliPathSync()
+  if (syncPath) {
+    resolvedCliPath = syncPath
+    return syncPath
+  }
+
   return "sg"
 }
 
-// ast-grep CLI path (auto-detected from node_modules or system PATH)
-export const SG_CLI_PATH = findSgCliPath()
+export function setSgCliPath(path: string): void {
+  resolvedCliPath = path
+}
+
+export const SG_CLI_PATH = getSgCliPath()
 
 // CLI supported languages (25 total)
 export const CLI_LANGUAGES = [
@@ -94,6 +135,10 @@ export const CLI_LANGUAGES = [
 export const NAPI_LANGUAGES = ["html", "javascript", "tsx", "css", "typescript"] as const
 
 // Language to file extensions mapping
+export const DEFAULT_TIMEOUT_MS = 300_000
+export const DEFAULT_MAX_OUTPUT_BYTES = 1 * 1024 * 1024
+export const DEFAULT_MAX_MATCHES = 500
+
 export const LANG_EXTENSIONS: Record<string, string[]> = {
   bash: [".bash", ".sh", ".zsh", ".bats"],
   c: [".c", ".h"],
@@ -121,3 +166,99 @@ export const LANG_EXTENSIONS: Record<string, string[]> = {
   tsx: [".tsx"],
   yaml: [".yml", ".yaml"],
 }
+
+export interface EnvironmentCheckResult {
+  cli: {
+    available: boolean
+    path: string
+    error?: string
+  }
+  napi: {
+    available: boolean
+    error?: string
+  }
+}
+
+/**
+ * Check if ast-grep CLI and NAPI are available.
+ * Call this at startup to provide early feedback about missing dependencies.
+ */
+export function checkEnvironment(): EnvironmentCheckResult {
+  const result: EnvironmentCheckResult = {
+    cli: {
+      available: false,
+      path: SG_CLI_PATH,
+    },
+    napi: {
+      available: false,
+    },
+  }
+
+  // Check CLI availability
+  if (existsSync(SG_CLI_PATH)) {
+    result.cli.available = true
+  } else if (SG_CLI_PATH === "sg") {
+    // Fallback path - try which/where to find in PATH
+    try {
+      const { spawnSync } = require("child_process")
+      const whichResult = spawnSync(process.platform === "win32" ? "where" : "which", ["sg"], {
+        encoding: "utf-8",
+        timeout: 5000,
+      })
+      result.cli.available = whichResult.status === 0 && !!whichResult.stdout?.trim()
+      if (!result.cli.available) {
+        result.cli.error = "sg binary not found in PATH"
+      }
+    } catch {
+      result.cli.error = "Failed to check sg availability"
+    }
+  } else {
+    result.cli.error = `Binary not found: ${SG_CLI_PATH}`
+  }
+
+  // Check NAPI availability
+  try {
+    require("@ast-grep/napi")
+    result.napi.available = true
+  } catch (e) {
+    result.napi.available = false
+    result.napi.error = `@ast-grep/napi not installed: ${e instanceof Error ? e.message : String(e)}`
+  }
+
+  return result
+}
+
+/**
+ * Format environment check result as user-friendly message.
+ */
+export function formatEnvironmentCheck(result: EnvironmentCheckResult): string {
+  const lines: string[] = ["ast-grep Environment Status:", ""]
+
+  // CLI status
+  if (result.cli.available) {
+    lines.push(`✓ CLI: Available (${result.cli.path})`)
+  } else {
+    lines.push(`✗ CLI: Not available`)
+    if (result.cli.error) {
+      lines.push(`  Error: ${result.cli.error}`)
+    }
+    lines.push(`  Install: bun add -D @ast-grep/cli`)
+  }
+
+  // NAPI status
+  if (result.napi.available) {
+    lines.push(`✓ NAPI: Available`)
+  } else {
+    lines.push(`✗ NAPI: Not available`)
+    if (result.napi.error) {
+      lines.push(`  Error: ${result.napi.error}`)
+    }
+    lines.push(`  Install: bun add -D @ast-grep/napi`)
+  }
+
+  lines.push("")
+  lines.push(`CLI supports ${CLI_LANGUAGES.length} languages`)
+  lines.push(`NAPI supports ${NAPI_LANGUAGES.length} languages: ${NAPI_LANGUAGES.join(", ")}`)
+
+  return lines.join("\n")
+}

src/tools/ast-grep/downloader.ts

@@ -0,0 +1,151 @@
+import { spawn } from "bun"
+import { existsSync, mkdirSync, chmodSync, unlinkSync } from "fs"
+import { join } from "path"
+import { homedir } from "os"
+import { createRequire } from "module"
+
+const REPO = "ast-grep/ast-grep"
+
+// IMPORTANT: Update this when bumping @ast-grep/cli in package.json
+// This is only used as fallback when @ast-grep/cli package.json cannot be read
+const DEFAULT_VERSION = "0.40.0"
+
+function getAstGrepVersion(): string {
+  try {
+    const require = createRequire(import.meta.url)
+    const pkg = require("@ast-grep/cli/package.json")
+    return pkg.version
+  } catch {
+    return DEFAULT_VERSION
+  }
+}
+
+interface PlatformInfo {
+  arch: string
+  os: string
+}
+
+const PLATFORM_MAP: Record<string, PlatformInfo> = {
+  "darwin-arm64": { arch: "aarch64", os: "apple-darwin" },
+  "darwin-x64": { arch: "x86_64", os: "apple-darwin" },
+  "linux-arm64": { arch: "aarch64", os: "unknown-linux-gnu" },
+  "linux-x64": { arch: "x86_64", os: "unknown-linux-gnu" },
+  "win32-x64": { arch: "x86_64", os: "pc-windows-msvc" },
+  "win32-arm64": { arch: "aarch64", os: "pc-windows-msvc" },
+  "win32-ia32": { arch: "i686", os: "pc-windows-msvc" },
+}
+
+export function getCacheDir(): string {
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || process.env.APPDATA
+    const base = localAppData || join(homedir(), "AppData", "Local")
+    return join(base, "oh-my-opencode", "bin")
+  }
+
+  const xdgCache = process.env.XDG_CACHE_HOME
+  const base = xdgCache || join(homedir(), ".cache")
+  return join(base, "oh-my-opencode", "bin")
+}
+
+export function getBinaryName(): string {
+  return process.platform === "win32" ? "sg.exe" : "sg"
+}
+
+export function getCachedBinaryPath(): string | null {
+  const binaryPath = join(getCacheDir(), getBinaryName())
+  return existsSync(binaryPath) ? binaryPath : null
+}
+
+async function extractZip(archivePath: string, destDir: string): Promise<void> {
+  const proc =
+    process.platform === "win32"
+      ? spawn(
+          [
+            "powershell",
+            "-command",
+            `Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force`,
+          ],
+          { stdout: "pipe", stderr: "pipe" }
+        )
+      : spawn(["unzip", "-o", archivePath, "-d", destDir], { stdout: "pipe", stderr: "pipe" })
+
+  const exitCode = await proc.exited
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    const toolHint =
+      process.platform === "win32"
+        ? "Ensure PowerShell is available on your system."
+        : "Please install 'unzip' (e.g., apt install unzip, brew install unzip)."
+    throw new Error(`zip extraction failed (exit ${exitCode}): ${stderr}\n\n${toolHint}`)
+  }
+}
+
+export async function downloadAstGrep(version: string = DEFAULT_VERSION): Promise<string | null> {
+  const platformKey = `${process.platform}-${process.arch}`
+  const platformInfo = PLATFORM_MAP[platformKey]
+
+  if (!platformInfo) {
+    console.error(`[oh-my-opencode] Unsupported platform for ast-grep: ${platformKey}`)
+    return null
+  }
+
+  const cacheDir = getCacheDir()
+  const binaryName = getBinaryName()
+  const binaryPath = join(cacheDir, binaryName)
+
+  if (existsSync(binaryPath)) {
+    return binaryPath
+  }
+
+  const { arch, os } = platformInfo
+  const assetName = `app-${arch}-${os}.zip`
+  const downloadUrl = `https://github.com/${REPO}/releases/download/${version}/${assetName}`
+
+  console.log(`[oh-my-opencode] Downloading ast-grep binary...`)
+
+  try {
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true })
+    }
+
+    const response = await fetch(downloadUrl, { redirect: "follow" })
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+    }
+
+    const archivePath = join(cacheDir, assetName)
+    const arrayBuffer = await response.arrayBuffer()
+    await Bun.write(archivePath, arrayBuffer)
+
+    await extractZip(archivePath, cacheDir)
+
+    if (existsSync(archivePath)) {
+      unlinkSync(archivePath)
+    }
+
+    if (process.platform !== "win32" && existsSync(binaryPath)) {
+      chmodSync(binaryPath, 0o755)
+    }
+
+    console.log(`[oh-my-opencode] ast-grep binary ready.`)
+
+    return binaryPath
+  } catch (err) {
+    console.error(
+      `[oh-my-opencode] Failed to download ast-grep: ${err instanceof Error ? err.message : err}`
+    )
+    return null
+  }
+}
+
+export async function ensureAstGrepBinary(): Promise<string | null> {
+  const cachedPath = getCachedBinaryPath()
+  if (cachedPath) {
+    return cachedPath
+  }
+
+  const version = getAstGrepVersion()
+  return downloadAstGrep(version)
+}

src/tools/ast-grep/index.ts

@@ -1,14 +1,12 @@
-import {
-  ast_grep_search,
-  ast_grep_replace,
-} from "./tools"
+import { ast_grep_search, ast_grep_replace } from "./tools"
 
 export const builtinTools = {
   ast_grep_search,
   ast_grep_replace,
 }
 
-export {
-  ast_grep_search,
-  ast_grep_replace,
-}
+export { ast_grep_search, ast_grep_replace }
+export { ensureAstGrepBinary, getCachedBinaryPath, getCacheDir } from "./downloader"
+export { getAstGrepPath, isCliAvailable, ensureCliAvailable, startBackgroundInit } from "./cli"
+export { checkEnvironment, formatEnvironmentCheck } from "./constants"
+export type { EnvironmentCheckResult } from "./constants"

src/tools/ast-grep/napi.ts

@@ -1,4 +1,5 @@
 import { parse, Lang } from "@ast-grep/napi"
+import { NAPI_LANGUAGES } from "./constants"
 import type { NapiLanguage, AnalyzeResult, MetaVariable, Range } from "./types"
 
 const LANG_MAP: Record<NapiLanguage, Lang> = {
@@ -10,7 +11,16 @@ const LANG_MAP: Record<NapiLanguage, Lang> = {
 }
 
 export function parseCode(code: string, lang: NapiLanguage) {
-  return parse(LANG_MAP[lang], code)
+  const parseLang = LANG_MAP[lang]
+  if (!parseLang) {
+    const supportedLangs = NAPI_LANGUAGES.join(", ")
+    throw new Error(
+      `Unsupported language for NAPI: "${lang}"\n` +
+        `Supported languages: ${supportedLangs}\n\n` +
+        `Use ast_grep_search for other languages (25 supported via CLI).`
+    )
+  }
+  return parse(parseLang, code)
 }
 
 export function findPattern(root: ReturnType<typeof parseCode>, pattern: string) {

src/tools/ast-grep/tools.ts

@@ -1,22 +1,46 @@
 import { tool } from "@opencode-ai/plugin/tool"
-import { CLI_LANGUAGES, NAPI_LANGUAGES, LANG_EXTENSIONS } from "./constants"
+import { CLI_LANGUAGES } from "./constants"
 import { runSg } from "./cli"
-import { analyzeCode, transformCode, getRootInfo } from "./napi"
-import { formatSearchResult, formatReplaceResult, formatAnalyzeResult, formatTransformResult } from "./utils"
-import type { CliLanguage, NapiLanguage } from "./types"
+import { formatSearchResult, formatReplaceResult } from "./utils"
+import type { CliLanguage } from "./types"
 
 function showOutputToUser(context: unknown, output: string): void {
   const ctx = context as { metadata?: (input: { metadata: { output: string } }) => void }
   ctx.metadata?.({ metadata: { output } })
 }
 
+function getEmptyResultHint(pattern: string, lang: CliLanguage): string | null {
+  const src = pattern.trim()
+
+  if (lang === "python") {
+    if (src.startsWith("class ") && src.endsWith(":")) {
+      const withoutColon = src.slice(0, -1)
+      return `💡 Hint: Remove trailing colon. Try: "${withoutColon}"`
+    }
+    if ((src.startsWith("def ") || src.startsWith("async def ")) && src.endsWith(":")) {
+      const withoutColon = src.slice(0, -1)
+      return `💡 Hint: Remove trailing colon. Try: "${withoutColon}"`
+    }
+  }
+
+  if (["javascript", "typescript", "tsx"].includes(lang)) {
+    if (/^(export\s+)?(async\s+)?function\s+\$[A-Z_]+\s*$/i.test(src)) {
+      return `💡 Hint: Function patterns need params and body. Try "function $NAME($$$) { $$$ }"`
+    }
+  }
+
+  return null
+}
+
 export const ast_grep_search = tool({
   description:
     "Search code patterns across filesystem using AST-aware matching. Supports 25 languages. " +
     "Use meta-variables: $VAR (single node), $$$ (multiple nodes). " +
+    "IMPORTANT: Patterns must be complete AST nodes (valid code). " +
+    "For functions, include params and body: 'export async function $NAME($$$) { $$$ }' not 'export async function $NAME'. " +
     "Examples: 'console.log($MSG)', 'def $FUNC($$$):', 'async function $NAME($$$)'",
   args: {
-    pattern: tool.schema.string().describe("AST pattern with meta-variables ($VAR, $$$)"),
+    pattern: tool.schema.string().describe("AST pattern with meta-variables ($VAR, $$$). Must be complete AST node."),
     lang: tool.schema.enum(CLI_LANGUAGES).describe("Target language"),
     paths: tool.schema.array(tool.schema.string()).optional().describe("Paths to search (default: ['.'])"),
     globs: tool.schema.array(tool.schema.string()).optional().describe("Include/exclude globs (prefix ! to exclude)"),
@@ -24,14 +48,23 @@ export const ast_grep_search = tool({
   },
   execute: async (args, context) => {
     try {
-      const matches = await runSg({
+      const result = await runSg({
         pattern: args.pattern,
         lang: args.lang as CliLanguage,
         paths: args.paths,
         globs: args.globs,
         context: args.context,
       })
-      const output = formatSearchResult(matches)
+
+      let output = formatSearchResult(result)
+
+      if (result.matches.length === 0 && !result.error) {
+        const hint = getEmptyResultHint(args.pattern, args.lang as CliLanguage)
+        if (hint) {
+          output += `\n\n${hint}`
+        }
+      }
+
       showOutputToUser(context, output)
       return output
     } catch (e) {
@@ -57,7 +90,7 @@ export const ast_grep_replace = tool({
   },
   execute: async (args, context) => {
     try {
-      const matches = await runSg({
+      const result = await runSg({
         pattern: args.pattern,
         rewrite: args.rewrite,
         lang: args.lang as CliLanguage,
@@ -65,7 +98,7 @@ export const ast_grep_replace = tool({
         globs: args.globs,
         updateAll: args.dryRun === false,
       })
-      const output = formatReplaceResult(matches, args.dryRun !== false)
+      const output = formatReplaceResult(result, args.dryRun !== false)
       showOutputToUser(context, output)
       return output
     } catch (e) {
@@ -76,83 +109,4 @@ export const ast_grep_replace = tool({
   },
 })
 
-export const ast_grep_languages = tool({
-  description:
-    "List all supported languages for ast-grep tools with their file extensions. " +
-    "Use this to determine valid language options.",
-  args: {},
-  execute: async (_args, context) => {
-    const lines: string[] = [`Supported Languages (${CLI_LANGUAGES.length}):`]
-    for (const lang of CLI_LANGUAGES) {
-      const exts = LANG_EXTENSIONS[lang]?.join(", ") || ""
-      lines.push(`  ${lang}: ${exts}`)
-    }
-    lines.push("")
-    lines.push(`NAPI (in-memory) languages: ${NAPI_LANGUAGES.join(", ")}`)
-    const output = lines.join("\n")
-    showOutputToUser(context, output)
-    return output
-  },
-})
 
-export const ast_grep_analyze = tool({
-  description:
-    "Parse code and extract AST structure with pattern matching (in-memory). " +
-    "Extracts meta-variable bindings. Only for: html, javascript, tsx, css, typescript. " +
-    "Use for detailed code analysis without file I/O.",
-  args: {
-    code: tool.schema.string().describe("Source code to analyze"),
-    lang: tool.schema.enum(NAPI_LANGUAGES).describe("Language (html, javascript, tsx, css, typescript)"),
-    pattern: tool.schema.string().optional().describe("Pattern to find (omit for root structure)"),
-    extractMetaVars: tool.schema.boolean().optional().describe("Extract meta-variable bindings (default: true)"),
-  },
-  execute: async (args, context) => {
-    try {
-      if (!args.pattern) {
-        const info = getRootInfo(args.code, args.lang as NapiLanguage)
-        const output = `Root kind: ${info.kind}\nChildren: ${info.childCount}`
-        showOutputToUser(context, output)
-        return output
-      }
-
-      const results = analyzeCode(args.code, args.lang as NapiLanguage, args.pattern, args.extractMetaVars !== false)
-      const output = formatAnalyzeResult(results, args.extractMetaVars !== false)
-      showOutputToUser(context, output)
-      return output
-    } catch (e) {
-      const output = `Error: ${e instanceof Error ? e.message : String(e)}`
-      showOutputToUser(context, output)
-      return output
-    }
-  },
-})
-
-export const ast_grep_transform = tool({
-  description:
-    "Transform code in-memory using AST-aware rewriting. " +
-    "Only for: html, javascript, tsx, css, typescript. " +
-    "Returns transformed code without writing to filesystem.",
-  args: {
-    code: tool.schema.string().describe("Source code to transform"),
-    lang: tool.schema.enum(NAPI_LANGUAGES).describe("Language"),
-    pattern: tool.schema.string().describe("Pattern to match"),
-    rewrite: tool.schema.string().describe("Replacement (can use $VAR from pattern)"),
-  },
-  execute: async (args, context) => {
-    try {
-      const { transformed, editCount } = transformCode(
-        args.code,
-        args.lang as NapiLanguage,
-        args.pattern,
-        args.rewrite
-      )
-      const output = formatTransformResult(args.code, transformed, editCount)
-      showOutputToUser(context, output)
-      return output
-    } catch (e) {
-      const output = `Error: ${e instanceof Error ? e.message : String(e)}`
-      showOutputToUser(context, output)
-      return output
-    }
-  },
-})

src/tools/ast-grep/types.ts

@@ -51,3 +51,11 @@ export interface TransformResult {
   transformed: string
   editCount: number
 }
+
+export interface SgResult {
+  matches: CliMatch[]
+  totalMatches: number
+  truncated: boolean
+  truncatedReason?: "max_matches" | "max_output_bytes" | "timeout"
+  error?: string
+}

src/tools/ast-grep/utils.ts

@@ -1,13 +1,28 @@
-import type { CliMatch, AnalyzeResult } from "./types"
+import type { CliMatch, AnalyzeResult, SgResult } from "./types"
 
-export function formatSearchResult(matches: CliMatch[]): string {
-  if (matches.length === 0) {
+export function formatSearchResult(result: SgResult): string {
+  if (result.error) {
+    return `Error: ${result.error}`
+  }
+
+  if (result.matches.length === 0) {
     return "No matches found"
   }
 
-  const lines: string[] = [`Found ${matches.length} match(es):\n`]
+  const lines: string[] = []
 
-  for (const match of matches) {
+  if (result.truncated) {
+    const reason = result.truncatedReason === "max_matches"
+      ? `showing first ${result.matches.length} of ${result.totalMatches}`
+      : result.truncatedReason === "max_output_bytes"
+      ? "output exceeded 1MB limit"
+      : "search timed out"
+    lines.push(`⚠️ Results truncated (${reason})\n`)
+  }
+
+  lines.push(`Found ${result.matches.length} match(es)${result.truncated ? ` (truncated from ${result.totalMatches})` : ""}:\n`)
+
+  for (const match of result.matches) {
     const loc = `${match.file}:${match.range.start.line + 1}:${match.range.start.column + 1}`
     lines.push(`${loc}`)
     lines.push(`  ${match.lines.trim()}`)
@@ -17,15 +32,30 @@ export function formatSearchResult(matches: CliMatch[]): string {
   return lines.join("\n")
 }
 
-export function formatReplaceResult(matches: CliMatch[], isDryRun: boolean): string {
-  if (matches.length === 0) {
+export function formatReplaceResult(result: SgResult, isDryRun: boolean): string {
+  if (result.error) {
+    return `Error: ${result.error}`
+  }
+
+  if (result.matches.length === 0) {
     return "No matches found to replace"
   }
 
   const prefix = isDryRun ? "[DRY RUN] " : ""
-  const lines: string[] = [`${prefix}${matches.length} replacement(s):\n`]
+  const lines: string[] = []
 
-  for (const match of matches) {
+  if (result.truncated) {
+    const reason = result.truncatedReason === "max_matches"
+      ? `showing first ${result.matches.length} of ${result.totalMatches}`
+      : result.truncatedReason === "max_output_bytes"
+      ? "output exceeded 1MB limit"
+      : "search timed out"
+    lines.push(`⚠️ Results truncated (${reason})\n`)
+  }
+
+  lines.push(`${prefix}${result.matches.length} replacement(s):\n`)
+
+  for (const match of result.matches) {
     const loc = `${match.file}:${match.range.start.line + 1}:${match.range.start.column + 1}`
     lines.push(`${loc}`)
     lines.push(`  ${match.text}`)