@expnn/opencode-yaml-hooks 1.0.1

package/README.md

@@ -0,0 +1,352 @@
+# opencode-yaml-hooks
+
+`opencode-yaml-hooks` is an OpenCode plugin that loads hook definitions from `hooks.yaml` and runs command, tool, or bash actions on session and tool lifecycle events.
+
+Use it to run tests after edits, lint changed files, block risky commands before they run, or trigger local automation without another LLM step.
+
+## Install
+
+Register it in your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-yaml-hooks"]
+}
+```
+
+## Quick start
+
+Create one of:
+
+- `~/.config/opencode/hook/hooks.yaml`
+- `<project>/.opencode/hook/hooks.yaml`
+
+Then add a minimal hook:
+
+```yaml
+hooks:
+  - name: npm-test
+    event: file.changed
+    conditions: [matchesCodeFiles]
+    actions:
+      - bash: "npm test"
+```
+
+This runs `npm test` after a supported file mutation tool changes at least one tracked code file.
+
+## Current config locations
+
+Hooks are merged from global and project locations.
+
+| Platform | Global config | Project config |
+|---|---|---|
+| macOS / Linux | `~/.config/opencode/hook/hooks.yaml` | `<project>/.opencode/hook/hooks.yaml` |
+| Windows | `~/.config/opencode/hook/hooks.yaml` preferred, otherwise `%APPDATA%/opencode/hook/hooks.yaml` | `<project>/.opencode/hook/hooks.yaml` |
+
+## Start with these defaults
+
+Unless you need something more specific:
+
+- prefer `file.changed` for file-oriented automation
+- leave `scope` unset unless you need `main` or `child`
+- leave `runIn` unset unless you need actions to execute in the root session
+- treat `tool.after.*` and `tool.after.<name>` as advanced hooks for observability or non-file workflows
+
+Explicit defaults in the current runtime:
+
+- `scope` defaults to `all`
+- `runIn` defaults to `current`
+- `conditions` are optional
+- bash `timeout` defaults to `60000` milliseconds
+
+## Schema overview
+
+```yaml
+hooks:
+  - name: <hook-name>
+    event: <hook-event>
+    action: <stop>            # optional, only for tool.before.* hooks
+    scope: <all|main|child>   # optional, defaults to all
+    runIn: <current|main>     # optional, defaults to current
+    async: <boolean>          # optional, fire-and-forget execution
+    conditions:               # optional
+      - matchesCodeFiles
+      - matchesAnyPath: src/**/*.ts
+      - matchesAllPaths:
+          - package.json
+          - apps/*/package.json
+    actions:                  # required, non-empty
+      - command: <string>
+      - command:
+          name: <string>
+          args: <string>
+      - tool:
+          name: <string>
+          args: <object>
+      - bash: <string>
+      - bash:
+          command: <string>
+          timeout: <positive integer milliseconds>
+```
+
+Validation rules enforced by the runtime:
+
+- `hooks` must exist and be an array
+- each hook must be an object with a supported `event`
+- `scope`, if present, must be `all`, `main`, or `child`
+- `runIn`, if present, must be `current` or `main`
+- `action`, if present, must be `stop` and is only supported on `tool.before.*` and `tool.before.<name>` hooks
+- `async`, if present, must be a boolean; cannot be `true` on `tool.before` or `session.idle` events; async hooks must use only `bash` actions
+- `conditions`, if present, must be an array of supported condition entries
+- `actions` must be a non-empty array
+- each action must define exactly one of `command`, `tool`, or `bash`
+
+## Supported events
+
+### Session events
+
+| Event | When it fires |
+|---|---|
+| `session.created` | When OpenCode creates a session |
+| `session.deleted` | When OpenCode deletes a session |
+| `session.idle` | When a session becomes idle |
+| `file.changed` | After a supported mutation tool reports file changes |
+
+### Tool events
+
+| Event | When it fires |
+|---|---|
+| `tool.before.*` | Before every tool execution |
+| `tool.before.<name>` | Before a specific tool, such as `tool.before.write` |
+| `tool.after.*` | Advanced: after every tool execution |
+| `tool.after.<name>` | Advanced: after a specific tool, such as `tool.after.edit` |
+
+Tool hook order for a tool named `write`:
+
+1. `tool.before.*`
+2. `tool.before.write`
+3. tool executes
+4. `file.changed` if the tool changed tracked files
+5. `tool.after.*`
+6. `tool.after.write`
+
+## Public API versus advanced hooks
+
+### Preferred public API: `file.changed`
+
+Use `file.changed` when your automation depends on changed files.
+
+Why it is preferred:
+
+- it only fires for supported mutation tools: `write`, `edit`, `multiedit`, `patch`, and `apply_patch`
+- it includes `files` and structured `changes` metadata
+- it avoids catch-all after-hook ambiguity
+- it is the recommended path for linting, formatting, indexing, and atomic commit workflows
+
+### Advanced escape hatches: `tool.after.*` and `tool.after.<name>`
+
+Keep using low-level tool hooks only when you need:
+
+- observability for every tool call, including non-file tools
+- tool-specific post-processing unrelated to changed files
+- compatibility with workflows that truly depend on raw tool arguments instead of normalized file changes
+
+## Conditions
+
+All configured conditions must pass for a hook to run.
+
+| Condition | Meaning |
+|---|---|
+| `matchesCodeFiles` | Run only when tracked modified files include at least one supported code extension |
+| `matchesAnyPath` | Run only when at least one final changed file path matches one or more glob patterns |
+| `matchesAllPaths` | Run only when every final changed file path matches at least one glob pattern |
+
+`matchesCodeFiles` is extension-based. Extensionless files such as `Dockerfile` do not currently count as code changes.
+
+`matchesAnyPath` and `matchesAllPaths` only work on `file.changed` and `session.idle`. Both accept either a single string or a string array, and both fail when there are no changed files to evaluate.
+
+Examples:
+
+```yaml
+hooks:
+  - event: file.changed
+    conditions:
+      - matchesAnyPath: src/**/*.ts
+    actions:
+      - bash: "npm run lint -- --fix"
+
+  - event: session.idle
+    scope: main
+    conditions:
+      - matchesAllPaths:
+          - package.json
+          - apps/*/package.json
+    actions:
+      - bash: "npm test"
+```
+
+Invalid usage example:
+
+```yaml
+hooks:
+  - event: tool.after.write
+    conditions:
+      - matchesAnyPath: src/**/*.ts # invalid: path conditions are file.changed/session.idle only
+    actions:
+      - bash: "echo nope"
+```
+
+## Actions
+
+### Command action
+
+Runs an OpenCode command in the same session, unless `runIn: main` redirects it to the root session.
+
+```yaml
+actions:
+  - command: simplify-changes
+  - command:
+      name: review-pr
+      args: "main feature"
+```
+
+### Tool action
+
+Prompts the session to use a tool with specific arguments.
+
+```yaml
+actions:
+  - tool:
+      name: bash
+      args:
+        command: "echo done"
+```
+
+### Bash action
+
+Runs a bash command directly without another LLM step.
+
+```yaml
+actions:
+  - bash: "npm run lint"
+  - bash:
+      command: "$OPENCODE_PROJECT_DIR/.opencode/hooks/init.sh"
+      timeout: 30000
+```
+
+If `timeout` is omitted, bash actions use the runtime default of `60000` milliseconds.
+
+`OPENCODE_PROJECT_DIR` remains the action cwd / project directory that triggered the hook.
+
+## Bash payloads
+
+Every bash action receives:
+
+- inherited `process.env`
+- `OPENCODE_PROJECT_DIR` for the action cwd / project directory
+- `OPENCODE_SESSION_ID`
+- `OPENCODE_GIT_COMMON_DIR` when available
+- JSON over stdin
+
+Example `file.changed` payload:
+
+```json
+{
+  "session_id": "abc123",
+  "event": "file.changed",
+  "cwd": "/path/to/project",
+  "files": ["src/index.ts", "src/renamed.ts"],
+  "changes": [
+    { "operation": "modify", "path": "src/index.ts" },
+    { "operation": "rename", "fromPath": "src/old.ts", "toPath": "src/renamed.ts" }
+  ],
+  "tool_name": "apply_patch",
+  "tool_args": {
+    "patchText": "*** Begin Patch\\n...\\n*** End Patch"
+  }
+}
+```
+
+## Blocking behavior
+
+Only `tool.before.*` and `tool.before.<name>` hooks can block execution.
+
+- a bash action that exits with `2` blocks the tool
+- `action: stop` escalates a blocking pre-tool hook into a best-effort `session.abort(...)` for the active session
+- `tool.after.*`, `tool.after.<name>`, `file.changed`, and session hooks do not block execution
+- non-blocking failures are logged and later actions continue
+
+Example:
+
+```yaml
+hooks:
+  - event: tool.before.bash
+    action: stop
+    actions:
+      - bash: |
+          payload=$(cat)
+          cmd=$(printf '%s' "$payload" | jq -r '.tool_args.command // empty')
+
+          case "$cmd" in
+            "git push"|git\ push\ *)
+              echo "Blocked and stopping session: git push is not allowed." >&2
+              exit 2
+              ;;
+          esac
+```
+
+## Execution behavior on this branch
+
+- hooks for the same event run in declaration order
+- global hooks load before project hooks
+- the runtime reloads discovered `hooks.yaml` files at each hook entrypoint
+- invalid reloads are rejected and the last known good config stays active
+- `session.idle` clears tracked changes only after successful dispatch
+- if idle dispatch fails, tracked changes are preserved for retry
+- reentrant `file.changed` and `tool.after.*` dispatches are queued and replayed after the active dispatch finishes
+- `async: true` hooks return immediately without blocking the tool pipeline; their actions run in the background as best-effort work
+- async actions for the same event and source session are serialized to prevent overlapping executions; note that serialization is per source session, not per target — `runIn: main` hooks from different child sessions are not serialized against each other
+
+## Copy-paste examples
+
+See [`examples/hooks.yaml`](examples/hooks.yaml) for:
+
+- main-session only examples
+- child-to-main `runIn: main` routing
+- recommended `file.changed` automation
+- advanced `tool.after.*` observability
+- conservative atomic commit wiring
+
+## See also
+
+- [`docs/hooks-v2-reference.md`](docs/hooks-v2-reference.md) for the current public config shape
+- [`docs/comparison-with-claude-code-hooks.md`](docs/comparison-with-claude-code-hooks.md) for how this compares to Claude Code's hook system
+
+## Known limitations
+
+- file tracking is limited to supported OpenCode mutation tools, not arbitrary filesystem changes
+- `matchesCodeFiles` is extension-based and ignores extensionless code-like files
+- tool hooks depend on actual emitted OpenCode tool names
+- Windows discovery is supported, but bash actions still require a working shell runtime
+- `async: true` is not allowed on `tool.before.*` or `session.idle` events; async hooks cannot block tool execution or idle dispatch
+- async hooks must use only `bash` actions; `command` and `tool` actions have no timeout and can stall the queue
+- async hook failures are logged but not retried; async execution is best-effort and not guaranteed to complete if the host process exits
+
+## Explicit non-goals for v1/v2 runtime scope
+
+This package does **not** currently try to:
+
+- define custom hook events beyond session, file, and tool lifecycle events
+- provide config inheritance or override priority beyond global-then-project merging
+- provide retries, scheduling, or concurrency controls per hook
+- track arbitrary filesystem changes outside OpenCode mutation tools
+- make command or tool actions blocking
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```

package/dist/adapter/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+export declare function createOpencodeHooksPlugin(input: PluginInput): Promise<Hooks>;

package/dist/core/bash-executor.d.ts

@@ -0,0 +1,4 @@
+import { type BashExecutionRequest, type BashHookContext, type BashHookResult, type BashProcessResult } from "./bash-types.js";
+export declare function executeBashHook(request: BashExecutionRequest): Promise<BashHookResult>;
+export declare function mapBashProcessResultToHookResult(result: BashProcessResult, context: BashHookContext): BashHookResult;
+export declare function isBlockingToolBeforeEvent(event: string): boolean;

package/dist/core/bash-types.d.ts

@@ -0,0 +1,33 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { FileChange } from "./types.js";
+export declare const DEFAULT_BASH_TIMEOUT = 60000;
+export interface BashHookContext {
+    readonly session_id: string;
+    readonly event: string;
+    readonly cwd: string;
+    readonly files?: readonly string[];
+    readonly changes?: readonly FileChange[];
+    readonly tool_name?: string;
+    readonly tool_args?: Record<string, unknown>;
+}
+export interface BashExecutionRequest {
+    readonly command: string;
+    readonly context: BashHookContext;
+    readonly projectDir: string;
+    readonly timeout?: number;
+    readonly client?: PluginInput["client"];
+}
+export interface BashProcessResult {
+    readonly command: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    readonly exitCode: number;
+    readonly signal: NodeJS.Signals | null;
+    readonly timedOut: boolean;
+}
+export type BashHookResultStatus = "success" | "failed" | "blocked" | "timed_out";
+export interface BashHookResult extends BashProcessResult {
+    readonly status: BashHookResultStatus;
+    readonly blocking: boolean;
+}

package/dist/core/config-paths.d.ts

@@ -0,0 +1,13 @@
+export interface HookConfigDiscoveryOptions {
+    readonly projectDir?: string;
+    readonly platform?: string;
+    readonly homeDir?: string;
+    readonly appDataDir?: string;
+    readonly exists?: (filePath: string) => boolean;
+}
+export interface HookConfigPaths {
+    readonly global?: string;
+    readonly project?: string;
+}
+export declare function resolveHookConfigPaths(options?: HookConfigDiscoveryOptions): HookConfigPaths;
+export declare function discoverHookConfigPaths(options?: HookConfigDiscoveryOptions): string[];

package/dist/core/load-hooks.d.ts

@@ -0,0 +1,26 @@
+import { type HookOverrideEntry, type HookMap, type HookValidationError, type ParsedHooksFile } from "./types.js";
+import { type HookConfigDiscoveryOptions } from "./config-paths.js";
+export interface HookDiscoveryResult {
+    readonly hooks: HookMap;
+    readonly errors: HookValidationError[];
+    readonly files: string[];
+}
+export interface HookLoadOptions extends HookConfigDiscoveryOptions {
+    readonly readFile?: (filePath: string) => string;
+}
+export interface HookLoadSnapshot extends HookDiscoveryResult {
+    readonly signature: string;
+}
+type ParsedHooksFileResult = ParsedHooksFile & {
+    readonly files: string[];
+};
+export declare function parseHooksFile(filePath: string, content: string): ParsedHooksFileResult;
+export declare function loadHooksFile(filePath: string, readFile?: (filePath: string) => string): ParsedHooksFileResult;
+export declare function loadDiscoveredHooks(options?: HookLoadOptions): HookDiscoveryResult;
+export declare function loadDiscoveredHooksSnapshot(options?: HookLoadOptions): HookLoadSnapshot;
+export declare function mergeHookMaps(...hookMaps: HookMap[]): HookMap;
+export declare function resolveOverrides(hooks: HookMap, overrides: HookOverrideEntry[]): {
+    hooks: HookMap;
+    errors: HookValidationError[];
+};
+export {};

package/dist/core/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+import { executeBashHook } from "./bash-executor.js";
+import type { BashExecutionRequest } from "./bash-types.js";
+import type { HookMap } from "./types.js";
+type ExecuteBashHook = (request: BashExecutionRequest) => ReturnType<typeof executeBashHook>;
+export interface CreateHooksRuntimeOptions {
+    readonly hooks?: HookMap;
+    readonly executeBash?: ExecuteBashHook;
+    readonly client?: PluginInput["client"];
+}
+export declare function createHooksRuntime(input: PluginInput, options?: CreateHooksRuntimeOptions): Hooks;
+export {};

package/dist/core/session-state.d.ts

@@ -0,0 +1,25 @@
+import type { FileChange } from "./types.js";
+export interface PendingToolCall {
+    readonly sessionID: string;
+    readonly toolArgs: Record<string, unknown>;
+}
+export type SessionScope = "all" | "main" | "child";
+export declare class SessionStateStore {
+    private readonly sessions;
+    private readonly pendingToolCalls;
+    rememberSession(sessionID: string, parentID?: string | null): void;
+    evaluateScope(sessionID: string, scope: SessionScope, resolveParentID: (sessionID: string) => Promise<string | null | undefined>): Promise<boolean>;
+    getRootSessionID(sessionID: string, resolveParentID: (sessionID: string) => Promise<string | null | undefined>): Promise<string>;
+    isDeleted(sessionID: string): boolean;
+    deleteSession(sessionID: string): void;
+    setPendingToolCall(callID: string, sessionID: string, toolArgs: Record<string, unknown>): void;
+    consumePendingToolCall(callID: string): PendingToolCall | undefined;
+    addFileChanges(sessionID: string, changes: Iterable<FileChange>): void;
+    getFileChanges(sessionID: string): FileChange[];
+    getModifiedPaths(sessionID: string): string[];
+    beginIdleDispatch(sessionID: string, changes: readonly FileChange[]): void;
+    consumeFileChanges(sessionID: string, changes: readonly FileChange[]): void;
+    cancelIdleDispatch(sessionID: string): void;
+    private getOrCreateSession;
+    private resolveRootSessionID;
+}

package/dist/core/tool-paths.d.ts

@@ -0,0 +1,13 @@
+import type { FileChange } from "./types.js";
+declare const DIRECT_MUTATION_TOOL_NAMES: readonly ["write", "edit", "multiedit"];
+declare const PATCH_MUTATION_TOOL_NAMES: readonly ["patch", "apply_patch"];
+declare const BASH_TOOL_NAME: "bash";
+export declare const MUTATION_TOOL_NAMES: Set<"bash" | "write" | "edit" | "multiedit" | "patch" | "apply_patch">;
+export type MutationToolName = (typeof DIRECT_MUTATION_TOOL_NAMES)[number] | (typeof PATCH_MUTATION_TOOL_NAMES)[number] | typeof BASH_TOOL_NAME;
+export type NormalizedMutationToolName = "write" | "edit" | "multiedit" | "apply_patch" | "bash";
+export declare function normalizeMutationToolName(toolName: string): NormalizedMutationToolName | undefined;
+export declare function getMutationToolHookNames(toolName: string): string[];
+export declare function getToolAffectedPaths(toolName: string, args: Record<string, unknown>): string[];
+export declare function getToolFileChanges(toolName: string, args: Record<string, unknown>): FileChange[];
+export declare function getChangedPaths(changes: readonly FileChange[]): string[];
+export {};

package/dist/core/types.d.ts

@@ -0,0 +1,102 @@
+export declare const SESSION_HOOK_EVENTS: readonly ["session.idle", "session.created", "session.deleted", "file.changed"];
+export declare const LEGACY_HOOK_CONDITIONS: readonly ["matchesCodeFiles"];
+export declare const PATH_HOOK_CONDITION_KEYS: readonly ["matchesAnyPath", "matchesAllPaths"];
+export declare const HOOK_SCOPES: readonly ["all", "main", "child"];
+export declare const HOOK_RUN_IN: readonly ["current", "main"];
+export declare const HOOK_BEHAVIORS: readonly ["stop"];
+export type SessionHookEvent = (typeof SESSION_HOOK_EVENTS)[number];
+export type ToolHookPhase = "before" | "after";
+export type ToolHookEvent = `tool.${ToolHookPhase}.*` | `tool.${ToolHookPhase}.${string}`;
+export type HookEvent = SessionHookEvent | ToolHookEvent;
+export type HookLegacyCondition = (typeof LEGACY_HOOK_CONDITIONS)[number];
+export type HookPathConditionKey = (typeof PATH_HOOK_CONDITION_KEYS)[number];
+export type HookPathCondition = {
+    readonly matchesAnyPath: readonly string[];
+} | {
+    readonly matchesAllPaths: readonly string[];
+};
+export type HookCondition = HookLegacyCondition | HookPathCondition;
+export type HookScope = (typeof HOOK_SCOPES)[number];
+export type HookRunIn = (typeof HOOK_RUN_IN)[number];
+export type HookBehavior = (typeof HOOK_BEHAVIORS)[number];
+export interface CreateFileChange {
+    readonly operation: "create";
+    readonly path: string;
+}
+export interface ModifyFileChange {
+    readonly operation: "modify";
+    readonly path: string;
+}
+export interface DeleteFileChange {
+    readonly operation: "delete";
+    readonly path: string;
+}
+export interface RenameFileChange {
+    readonly operation: "rename";
+    readonly fromPath: string;
+    readonly toPath: string;
+}
+export type FileChange = CreateFileChange | ModifyFileChange | DeleteFileChange | RenameFileChange;
+export interface HookCommandActionConfig {
+    readonly name: string;
+    readonly args?: string;
+}
+export interface HookToolActionConfig {
+    readonly name: string;
+    readonly args?: Record<string, unknown>;
+}
+export interface HookBashActionConfig {
+    readonly command: string;
+    readonly timeout?: number;
+}
+export interface HookCommandAction {
+    readonly command: string | HookCommandActionConfig;
+}
+export interface HookToolAction {
+    readonly tool: HookToolActionConfig;
+}
+export interface HookBashAction {
+    readonly bash: string | HookBashActionConfig;
+}
+export type HookAction = HookCommandAction | HookToolAction | HookBashAction;
+export interface HookConfigSource {
+    readonly filePath: string;
+    readonly index: number;
+}
+export interface HookConfig {
+    readonly id?: string;
+    readonly event: HookEvent;
+    readonly name?: string;
+    readonly action?: HookBehavior;
+    readonly actions: HookAction[];
+    readonly scope: HookScope;
+    readonly runIn: HookRunIn;
+    readonly async?: boolean;
+    readonly conditions?: HookCondition[];
+    readonly source: HookConfigSource;
+}
+export interface HookOverrideEntry {
+    readonly targetId: string;
+    readonly disable: boolean;
+    readonly replacement?: HookConfig;
+    readonly source: HookConfigSource;
+}
+export type HookMap = Map<HookEvent, HookConfig[]>;
+export type HookValidationErrorCode = "invalid_frontmatter" | "missing_hooks" | "invalid_hooks" | "invalid_hook" | "invalid_event" | "invalid_scope" | "invalid_run_in" | "invalid_hook_action" | "invalid_conditions" | "invalid_actions" | "invalid_action" | "duplicate_hook_id" | "override_target_not_found" | "invalid_override" | "invalid_async";
+export interface HookValidationError {
+    readonly code: HookValidationErrorCode;
+    readonly filePath: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export interface ParsedHooksFile {
+    readonly hooks: HookMap;
+    readonly overrides: HookOverrideEntry[];
+    readonly errors: HookValidationError[];
+}
+export declare function isHookEvent(value: unknown): value is HookEvent;
+export declare function isHookLegacyCondition(value: unknown): value is HookLegacyCondition;
+export declare function isHookPathConditionKey(value: unknown): value is HookPathConditionKey;
+export declare function isHookScope(value: unknown): value is HookScope;
+export declare function isHookRunIn(value: unknown): value is HookRunIn;
+export declare function isHookBehavior(value: unknown): value is HookBehavior;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const OpencodeHooksPlugin: Plugin;
+export default OpencodeHooksPlugin;