AGENTS.md

1# src/hooks/claude-code-hooks/ (Claude Code Compatibility)
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
7~2850 LOC across 23 files. Claude Code `settings.json` compatibility layer. Parses CC hooks config and maps CC hook events (PreToolUse, PostToolUse, Stop, Notification, PreCompact, Session*) to OpenCode event handlers.
8 
9## WHAT IT DOES
10 
111. Parses Claude Code `settings.json` hooks config (PreToolUse, PostToolUse, Stop, Notification, PreCompact, SessionStart/End, Subagent*, etc.) from `.claude/settings.json` and `.claude/settings.local.json` (`config.ts`)
122. Maps CC hook events to OpenCode event handlers (`claude-code-hooks-hook.ts`)
133. Dispatches CC hook commands (shell via zsh, or HTTP) and reads PermissionDecision / stop / suppress output (`dispatch-hook.ts`, `execute-http-hook.ts`)
144. Loads plugin extended config (`opencode-cc-plugin.json`) from plural OpenCode config dirs + project, merging `disabledHooks` (`config-loader.ts`)
15 
16## CC → OPENCODE HOOK MAPPING
17 
18| CC Hook | OpenCode Event |
19|---------|---------------|
20| PreToolUse | tool.execute.before |
21| PostToolUse | tool.execute.after |
22| Notification | event (session.idle) |
23| Stop | event (session.idle) |
24 
25## PERMISSIONS & DISABLED HOOKS
26 
27- PreToolUse hooks return a `PermissionDecision` (`allow` / `deny` / `ask`); legacy `approve` / `block` are mapped. `permission_mode` (`default` / `plan` / `acceptEdits` / `bypassPermissions`) is forwarded to CC hooks.
28- `disabledHooks` in `opencode-cc-plugin.json` disables specific hook commands by regex per event type. `config-loader.ts` `isHookCommandDisabled()` checks a command against the configured patterns.
29 
30```json
31{
32  "disabledHooks": {
33    "PreToolUse": ["bash-forever", "^dangerous-"],
34    "PostToolUse": ["telemetry"]
35  }
36}
37```
38 
39## PLUGIN CONFIG LOADING
40 
41`config-loader.ts` loads `opencode-cc-plugin.json` from every OpenCode config dir returned by `getOpenCodeConfigDirs({ binary: "opencode" })` (plural), plus the project-local `.opencode/opencode-cc-plugin.json`. User dirs are merged in reverse order so later (custom) dirs override earlier (default) ones; project config overrides all. Only `disabledHooks` is merged. Result is cached 30s (`CONFIG_CACHE_TTL_MS`); the cache key includes `process.cwd()` and the joined user paths.
42 
43## FILES
44 
45| File | Purpose |
46|------|---------|
47| `claude-code-hooks-hook.ts` | `createClaudeCodeHooksHook()`: main factory, maps OpenCode events to CC handlers |
48| `config.ts` | Parse CC `settings.json` hooks config from `.claude/` (matchers + hook actions) |
49| `config-loader.ts` | Load `opencode-cc-plugin.json` (plural config dirs + project), merge `disabledHooks`, cache; `isHookCommandDisabled()` |
50| `dispatch-hook.ts` | `dispatchHook()`: run a CC hook command (shell via zsh, or HTTP) |
51| `execute-http-hook.ts` | Execute HTTP-type CC hooks |
52| `plugin-config.ts` | `DEFAULT_CONFIG` (forceZsh, zshPath) |
53| `pre-tool-use.ts` / `post-tool-use.ts` / `stop.ts` / `user-prompt-submit.ts` / `pre-compact.ts` | Per-event CC hook handlers |
54| `handlers/` | OpenCode event handlers (tool-execute-before/after, chat-message, pre-compact, session-event) |
55| `types.ts` | CC type definitions |
56