opencode-command-hooks 0.1.1 → 0.1.3

package/README.md

@@ -1,74 +1,42 @@
-# 🪝OpenCode Command Hooks
+# 🪝 OpenCode Command Hooks
 
-Attach shell commands to agent, tool, and session lifecycles using JSON/YAML configuration. Execute commands automatically without consuming tokens or requiring agent interaction.
+Use simple configs to easily integrate shell command hooks with tool/subagent invocations. With a single line of configuration, you can inject a hook's output directly into context for your agent to read.
 
-## Markdown Frontmatter Hooks (Core)
+Example use cases: run tests after a subagent finishes a task, auto-lint after writes, etc. You can also configure the hooks to run only when specified arguments are passed to a given tool. The plugin will handle sequential execution with failure recovery, output truncation, exit code capture, template interpolation, session context injection, toast notifications, toolArgs filtering, and non-blocking error handling.
 
-Define hooks directly in markdown frontmatter so they live with the content they affect. This is the default, first-class configuration path.
+## Markdown Frontmatter Hooks
 
-```markdown
----
-command_hooks:
-  tool:
-    - id: custom-hook
-      when: { tool: "write" }
-      run: ["echo 'File modified'"]
----
-
-# Your markdown content
-```
+Define hooks in just a couple lines of markdown frontmatter. Putting them here is also really nice because you can see your entire agent's config in one place.
 
-## Simplified Agent Markdown Hooks
-
-Define hooks directly in your agent's markdown file so configuration stays with the agent. When used via the `task` tool, the hook target is inferred, so you can omit `id`, `when`, and `tool`.
-
-### Quick Example
-
-```yaml
+````yaml
 ---
-description: Engineer agent
+description: Analyzes the codebase and implements code changes.
 mode: subagent
 hooks:
   after:
-    - run: "npm run lint"
-      inject: "Lint results:\n{stdout}"
+    - run: "npm run test"
+      inject: "Test Output:\n{stdout}\n{stderr}"
 ---
-# Engineer agent content
-```
+````
 
-### Practical Example: Self-Validating Engineer
+### How It Works
 
-````jsonc
-{
-  "tool": [
-    {
-      "id": "auto-validate",
-      "when": {
-        "phase": "after",
-        "tool": "task",
-        "toolArgs": { "subagent_type": "engineer" },
-      },
-      "run": ["npm run typecheck", "npm test"],
-      "inject": "Validation: {exitCode, select, 0 {Passed} other {Failed - fix errors below}}\n```\n{stdout}\n```",
-    },
-  ],
-}
-````
+1. **Runs automatically** on the configured event
+2. **Executes shell commands** (sequentially, if you pass an array)
+3. **Captures output** (truncated to configured limit, default 30,000 characters)
+4. **Optionally reports results** via `inject` (to the session) and/or `toast` (to the UI).
 
-Every time the engineer finishes, tests run automatically and results flow back to the orchestrator. Failed validations trigger self-healing—no manual intervention or token costs.
+## Why?
 
-### How It Works
+When working with a fleet of subagents, automatic validation of the state of your codebase is really useful. By setting up quality gates (lint/typecheck/test/etc.) or other automation, you can catch and prevent errors quickly and reliably.  
 
-1. **Automatic Targeting**: Hooks defined in agent markdown automatically apply when that subagent is invoked via the `task` tool
-2. **Simplified Syntax**: No `id`, `when`, or `tool` fields needed—everything is inferred from context
-3. **Before/After Hooks**: Use `before` hooks for setup/preparation and `after` hooks for validation/cleanup
-4. **Dual Location Support**: Works with both:
-   - `.opencode/agent/*.md` (project-level agents)
-   - `~/.config/opencode/agent/*.md` (user-level agents)
+Doing this by asking your orchestrator agent to use the bash tool (or call a validator subagent) is non-deterministic and can cost a lot of tokens over time. You could always write your own custom plugin to achieve this automatic validation behavior, but I found myself writing the same boilerplate, error handling, output capture, and session injection logic over and over again.  
 
-### Simplified vs Global Config Format
+Though this plugin is mostly a wrapper around accessing hooks that Opencode already exposes, it provides basic plumbing that reduces overhead, giving you a simple, opinionated system for integrating command hooks into your Opencode workflow. I also just like having hooks/config for my agents all colocated in one place (markdown files) and thought that maybe somebody else would like this too.
+
+---
 
-**Global Config (verbose):**
+### JSON Config
 
 ```jsonc
 {
@@ -80,488 +48,282 @@ Every time the engineer finishes, tests run automatically and results flow back
         "tool": "task",
         "toolArgs": { "subagent_type": "engineer" },
       },
-      "run": ["npm run typecheck", "npm test"],
-      "inject": "Validation: {exitCode, select, 0 {✓ Passed} other {✗ Failed}}",
-      "toast": {
-        "title": "Validation Complete",
-        "message": "{exitCode, select, 0 {✓ Passed} other {✗ Failed}}",
-      },
+      "run": ["npm run lint", "npm run typecheck", "npm test"],
+      "inject": "Validation Results (exit {exitCode}): \n`{stdout}`\n`{stderr}`",
     },
   ],
 }
 ```
 
-**Agent Markdown (simplified):**
+### Markdown Frontmatter Config
 
 ```yaml
 hooks:
   after:
-    - run: ["npm run typecheck", "npm test"]
-      inject: "Validation: {exitCode, select, 0 {✓ Passed} other {✗ Failed}}"
+    - run: ["npm run lint", "npm run typecheck", "npm test"]
+      inject: "Validation Results (exit {exitCode}): \n`{stdout}`\n`{stderr}`"
       toast:
-        message: "{exitCode, select, 0 {✓ Passed} other {✗ Failed}}"
+        message: "Validation Complete"
 ```
 
-**Reduction: 60% less boilerplate!**
-
 ### Hook Configuration Options
 
-| Option   | Type                   | Required | Description                                         |
-| -------- | ---------------------- | -------- | --------------------------------------------------- |
-| `run`    | `string` \| `string[]` | ✅ Yes   | Command(s) to execute                               |
-| `inject` | `string`               | ❌ No    | Message to inject into session (supports templates) |
-| `toast`  | `object`               | ❌ No    | Toast notification configuration                    |
+| Option   | Type                   | Description                       |
+| -------- | ---------------------- | --------------------------------- |
+| `run`    | `string` \| `string[]` | Command(s) to execute             |
+| `inject` | `string`               | Message injected into the session |
+| `toast`  | `object`               | Toast notification configuration  |
 
 ### Toast Configuration
 
 ```yaml
 toast:
-  message: "Build {exitCode, select, 0 {succeeded} other {failed}}"
-  variant: "{exitCode, select, 0 {success} other {error}}" # info, success, warning, error
-  duration: 5000 # milliseconds (optional)
+  title: "Build" # optional
+  message: "exit {exitCode}"
+  variant: "info" # optional- one of: info, success, warning, error
+  duration: 5000 # optional (milliseconds)
 ```
 
-### Template Variables
-
-Agent markdown hooks support the same template variables as global config:
+### Inject String Template Variables
 
-- `{stdout}` - Command stdout (truncated to 4000 chars)
-- `{stderr}` - Command stderr (truncated to 4000 chars)
-- `{exitCode}` - Command exit code
+- `{id}` - Hook ID
+- `{agent}` - Agent name (if available)
+- `{tool}` - Tool name (tool hooks only)
 - `{cmd}` - Executed command
+- `{stdout}` - Command stdout (truncated)
+- `{stderr}` - Command stderr (truncated)
+- `{exitCode}` - Command exit code
 
 ### Complete Example
 
-````yaml
+````markdown
 ---
 description: Engineer Agent
 mode: subagent
 hooks:
   before:
-    - run: "echo '🚀 Engineer agent starting...'"
+    - run: "echo 'Engineer starting...'"
+      toast:
+        message: "Engineer starting"
+        variant: "info"
   after:
     - run: ["npm run typecheck", "npm run lint"]
-      inject: |
-        ## Validation Results
-
-        **TypeCheck:** {exitCode, select, 0 {✓ Passed} other {✗ Failed}}
-
-        ```
-        {stdout}
-        ```
-
-        {exitCode, select, 0 {} other {⚠️ Please fix validation errors before proceeding.}}
-      toast:
-        message: "TypeCheck & Lint: {exitCode, select, 0 {✓ Passed} other {✗ Failed}}"
-        variant: "{exitCode, select, 0 {success} other {error}}"
-    - run: "npm test -- --coverage --passWithNoTests"
-      inject: "Test Coverage: {stdout}%"
-      toast:
-        message: "Tests {exitCode, select, 0 {✓ Passed} other {✗ Failed}}"
-        variant: "{exitCode, select, 0 {success} other {error}}"
+      inject: "Typecheck + lint (exit {exitCode}) ``` {stdout} ```"
 ---
-# Engineer Agent
-Focus on implementing features with tests and proper error handling.
+
+<your subagent instructions>
 ````
 
 ---
 
-## Why?
-
-**The Problem:** You want your engineer/validator subagents to automatically run tests/linters and self-heal when validation fails—but asking agents to run validation costs tokens, isn't guaranteed, and requires complex native plugin code with manual error handling.
-
-**The Solution:** This plugin lets you attach validation commands to subagent completions via simple config. Results automatically inject back to the orchestrator, enabling autonomous quality gates with zero tokens spent.
+### Automatic Context Injection
 
-### 1. Zero-Token Automation
-
-Custom OpenCode plugins require TypeScript setup, manual error handling, and build processes. For routine automation tasks, this creates unnecessary complexity. This plugin provides shell hook functionality through configuration files—no tokens spent prompting agents to run repetitive commands.
-
-**Native Plugin (Requires TypeScript):**
-
-```typescript
-// .opencode/plugin/my-plugin.ts
-import type { Plugin } from "@opencode-ai/plugin";
+If `inject` is set, the command output is posted into the session, so your agents can react to failures.
 
-export const MyPlugin: Plugin = async ({ $ }) => {
-  return {
-    "tool.execute.after": async (input) => {
-      if (input.tool === "write") {
-        try {
-          await $`npm run lint`;
-        } catch (e) {
-          console.error(e); // UI spam or crashes
-          // Agent won't see what failed unless you inject it back
-        }
-      }
-    },
-  };
-};
-```
+### Filter by Tool Arguments
 
-**This Plugin (Configuration-Based):**
+You can set up tool hooks to only trigger on specific arguments via `when.toolArgs`.
 
 ```jsonc
 {
-  "tool": [
-    {
-      "id": "lint-ts",
-      "when": { "tool": "write" },
-      "run": ["npm run lint"],
-      "inject": {
-        "as": "system",
-        "template": "Lint results:\n{stdout}\n{stderr}",
-      },
-    },
-  ],
-}
-```
-
-### 2. Automatic Context Injection
-
-Command output returns to the agent automatically without manual SDK calls. The agent can see and react to errors, warnings, or other results:
-
-```jsonc
-{
-  "tool": [
-    {
-      "id": "typecheck",
-      "when": { "tool": "write", "toolArgs": { "path": "*.ts" } },
-      "run": ["npm run typecheck"],
-      "inject": {
-        "as": "system",
-        "template": "TypeScript check:\n{stdout}\n{stderr}",
-      },
-    },
-  ],
-}
-```
-
-For background tasks where the agent doesn't need context, use toast notifications instead:
-
-```jsonc
-{
-  "tool": [
-    {
-      "id": "build-status",
-      "when": { "tool": "write", "phase": "after" },
-      "run": ["npm run build"],
-      "toast": {
-        "title": "Build Status",
-        "message": "Build {exitCode, select, 0 {succeeded} other {failed}}",
-        "variant": "{exitCode, select, 0 {success} other {error}}",
-        "duration": 5000,
-      },
-    },
-  ],
-}
-```
-
-### 3. Filter Tools by Any Argument
-
-Run different hooks based on any tool argument—not just task subagent types. Filter by file paths, API endpoints, model names, or custom parameters.
-
-```jsonc
-// Filter by multiple subagent types
-{
-  "when": {
-    "tool": "task",
-    "toolArgs": { "subagent_type": ["validator", "reviewer", "tester"] }
-  }
-}
-
-// Filter write tool by file extension
-{
+  "id": "playwright-access-localhost",
   "when": {
-    "tool": "write",
-    "toolArgs": { "path": "*.test.ts" }
-  }
-}
-
-// Filter by API endpoint
-{
-  "when": {
-    "tool": "fetch",
-    "toolArgs": { "url": "*/api/validate" }
+    "phase": "after",
+    "tool": "playwright_browser_navigate",
+    "toolArgs": { "url": "http://localhost:3000]" }
+  },
+  "run": [
+    "osascript -e 'display notification \"Agent triggered playwright\"'"
+  ],
+  "toast": {
+    "message": "Agent used the playwright {tool} tool"
   }
 }
 ```
 
-### 4. Reliable Execution
-
-- **Non-blocking**: Hook failures don't crash the agent
-- **Automatic error handling**: Failed hooks inject error messages automatically
-- **Memory safe**: Output truncated to prevent memory issues
-- **Sequential execution**: Commands run in order, even if earlier ones fail
-
----
-
 ## Features
 
-- 🔔 **Toast Notifications** - Non-blocking user feedback with customizable titles, messages, and variants
-- 🎯 **Precise Filtering** - Filter by tool name, agent, phase, slash command, or ANY tool argument
-- 📊 **Complete Template System** - Access to `{id}`, `{agent}`, `{tool}`, `{cmd}`, `{stdout}`, `{stderr}`, `{exitCode}`
-- 🔄 **Multiple Event Types** - `tool.execute.before`, `tool.execute.after`, `tool.result`, `session.start`, `session.idle`
-- 🧩 **Flexible Configuration** - Global configs in `.opencode/command-hooks.jsonc` or markdown frontmatter
-- ⚡ **Zero-Token Automation** - Guaranteed execution without spending tokens on agent prompts
-- 🛡️ **Bulletproof Error Handling** - Graceful failures that never crash the agent
-- 🐛 **Debug Mode** - Detailed logging with `OPENCODE_HOOKS_DEBUG=1`
+- Tool hooks (`before`/`after`) and session hooks (`start`/`idle`)
+  - Hooks are **non-blocking**: failures don’t crash the session/tool.
+  - Commands run **sequentially**, even if earlier ones fail.
+  - `inject`/`toast` interpolate using the **last command’s** output if `run` is an array.
+- Match by tool name, calling agent, slash command, and tool arguments
+- Optional session injection and toast notifications
+- Output truncation to keep memory bounded
+- Debug logging via `OPENCODE_HOOKS_DEBUG=1`
 
 ---
 
 ## Installation
 
-```bash
-opencode install opencode-command-hooks
+Add to your `opencode.json`:
+
+```jsonc
+{
+  "plugin": ["opencode-command-hooks"]
+}
 ```
 
 ---
 
 ## Configuration
 
-### Global Configuration
+### JSON Config
 
-Create `.opencode/command-hooks.jsonc` in your project root:
+Create `.opencode/command-hooks.jsonc` in your project (the plugin searches upward from the current working directory):
 
 ```jsonc
 {
+  "truncationLimit": 30000,
   "tool": [
-    // Your tool hooks here
+    // Tool hooks
   ],
   "session": [
-    // Your session hooks here
+    // Session hooks
   ],
 }
 ```
 
+#### JSON Config Options
+
+| Option | Type  | Description |
+| ------ | ----  | ----------- |
+| `truncationLimit` | `number`  | Maximum characters to capture from command output. Defaults to 30,000 (matching OpenCode's bash tool). Must be a positive integer. |
+| `tool` | `ToolHook[]` | Array of tool execution hooks |
+| `session` | `SessionHook[]`| Array of session lifecycle hooks |
+
 ### Markdown Frontmatter
 
-Override global settings in individual markdown files:
+Use `hooks:` in agent markdown for the simplified format:
 
 ```markdown
 ---
-command_hooks:
-  tool:
-    - id: custom-hook
-      when: { tool: "write" }
-      run: ["echo 'File modified'"]
+description: Engineer agent
+mode: subagent
+hooks:
+  before:
+    - run: "echo 'Starting engineering work...'"
+  after:
+    - run: "npm run lint"
+      inject: "Lint output:\n{stdout}\n{stderr}"
 ---
-
-# Your markdown content
 ```
 
 ### Configuration Precedence
 
-1. **Markdown hooks** override global hooks with the same ID
-2. **Global hooks** are loaded from `.opencode/command-hooks.jsonc`
-3. **Duplicate IDs** within the same source are errors
-4. **Caching** prevents repeated file reads for performance
+1. Hooks are loaded from `.opencode/command-hooks.jsonc`
+2. Markdown hooks are converted to normal hooks with auto-generated IDs
+3. If a markdown hook and a global hook share the same `id`, the markdown hook wins
+4. Duplicate IDs within the same source are errors
+5. Global config is cached to avoid repeated file reads
 
 ---
 
 ## Examples
 
-### 🚀 Power User Example: Autonomous Quality Gates
+### Autonomous Quality Gates (After `task`)
 
-This example demonstrates the plugin's killer feature: **automatic validation injection after subagent work**. Unlike native plugins that require complex TypeScript and manual result handling, this achieves enterprise-grade quality gates with pure configuration.
+Run validation after certain subagents complete, inject results back into the session, and show a small toast.
 
-````jsonc
+```jsonc
 {
   "tool": [
     {
-      "id": "validate-engineer-work",
+      "id": "validate-after-task",
       "when": {
         "phase": "after",
         "tool": "task",
         "toolArgs": { "subagent_type": ["engineer", "debugger"] },
       },
-      "run": [
-        "npm run typecheck",
-        "npm run lint",
-        "npm test -- --coverage --passWithNoTests",
-      ],
-      "inject": "🔍 Validation Results:\n\n**TypeCheck:** {exitCode, select, 0 {✓ Passed} other {✗ Failed}}\n\n```\n{stdout}\n```\n\n{exitCode, select, 0 {} other {⚠️ The code you just wrote has validation errors. Please fix them before proceeding.}}",
+      "run": ["npm run typecheck", "npm run lint", "npm test"],
+      "inject": "Validation (exit {exitCode})\n\n{stdout}\n{stderr}",
       "toast": {
-        "title": "Code Validation",
-        "message": "{exitCode, select, 0 {All checks passed ✓} other {Validation failed - check errors}}",
-        "variant": "{exitCode, select, 0 {success} other {error}}",
+        "title": "Validation",
+        "message": "exit {exitCode}",
+        "variant": "info",
         "duration": 5000,
       },
     },
-    {
-      "id": "verify-test-coverage",
-      "when": {
-        "phase": "after",
-        "tool": "task",
-        "toolArgs": { "subagent_type": "engineer" },
-      },
-      "run": [
-        "npm test -- --coverage --json > coverage.json && node -p 'JSON.parse(require(\"fs\").readFileSync(\"coverage.json\")).coverageMap.total.lines.pct'",
-      ],
-      "inject": "📊 Test Coverage: {stdout}%\n\n{stdout, select, ^[89]\\d|100$ {} other {⚠️ Coverage is below 80%. Please add more tests.}}",
-    },
   ],
 }
-````
-
-**What makes this powerful:**
-
-1. **Zero-Token Enforcement** - Quality gates run automatically after engineer/debugger subagents without consuming tokens to prompt validation
-2. **Intelligent Filtering** - Uses `toolArgs.subagent_type` to target specific subagents (impossible with native plugins without SDK access)
-3. **Context Injection** - Validation results automatically flow back to the orchestrator/agent, enabling self-healing workflows
-4. **Non-Blocking** - Failed validations don't crash the session; the agent sees errors and can fix them
-5. **Dual Feedback** - Users get instant toast notifications while agents receive detailed error context
-6. **Sequential Commands** - Multiple validation steps run in order, even if earlier ones fail
-7. **Template Power** - Conditional messages using ICU MessageFormat syntax (`{exitCode, select, ...}`)
-
-**Real-world impact:** A single hook configuration replaces 50+ lines of TypeScript plugin code with error handling, session.prompt calls, and manual filtering logic. The agent becomes self-validating without you spending a single token to ask it to run tests.
-
----
-
-### Basic Examples
+```
 
-#### Auto-Verify Subagent Work
+### Run Tests After Any `task` (subagent creation toolcall)
 
-````jsonc
+```jsonc
 {
   "tool": [
     {
-      "id": "verify-subagent-work",
-      "when": {
-        "phase": "after",
-        "tool": ["task"],
-      },
+      "id": "tests-after-task",
+      "when": { "phase": "after", "tool": "task" },
       "run": ["npm test"],
-      "inject": "Test Runner:\nExit Code: {exitCode}\n\nOutput:\n```\n{stdout}\n```\n\nIf tests failed, please fix them before proceeding.",
+      "inject": "Tests (exit {exitCode})\n\n{stdout}\n{stderr}",
     },
   ],
 }
-````
+```
 
-#### Multi-Stage Validation Pipeline
+### Enforce Linting After a Specific `write`
 
-````jsonc
-{
-  "tool": [
-    {
-      "id": "validator-security-scan",
-      "when": {
-        "phase": "after",
-        "tool": "task",
-        "toolArgs": { "subagent_type": "validator" },
-      },
-      "run": [
-        "npm audit --audit-level=moderate",
-        "git diff --name-only | xargs grep -l 'API_KEY\\|SECRET\\|PASSWORD' || true",
-      ],
-      "inject": "🔒 Security Scan:\n\n**Audit:** {exitCode, select, 0 {No vulnerabilities} other {⚠️ Vulnerabilities found}}\n\n```\n{stdout}\n```\n\nPlease address security issues before deployment.",
-    },
-  ],
-}
-````
-
-#### Enforce Linting on File Edits
+Tool-arg matching is exact. This example runs only when the tool arg `path` equals `src/index.ts`.
 
 ```jsonc
 {
   "tool": [
     {
-      "id": "lint-on-save",
+      "id": "lint-src-index",
       "when": {
         "phase": "after",
-        "tool": ["write"],
+        "tool": "write",
+        "toolArgs": { "path": "src/index.ts" },
       },
-      "run": ["npm run lint -- --fix"],
-      "inject": "Linting auto-fix results: {stdout}",
+      "run": ["npm run lint"],
+      "inject": "Lint (exit {exitCode})\n\n{stdout}\n{stderr}",
     },
   ],
 }
 ```
 
-### Advanced Examples
-
-#### Toast Notifications for Build Status
+### Toast Notifications for Build Status
 
-````jsonc
+```jsonc
 {
   "tool": [
     {
-      "id": "build-notification",
-      "when": {
-        "phase": "after",
-        "tool": ["write"],
-        "toolArgs": { "path": "*.ts" },
-      },
+      "id": "build-toast",
+      "when": { "phase": "after", "tool": "write" },
       "run": ["npm run build"],
       "toast": {
-        "title": "TypeScript Build",
-        "message": "Build {exitCode, select, 0 {succeeded ✓} other {failed ✗}}",
-        "variant": "{exitCode, select, 0 {success} other {error}}",
+        "title": "Build",
+        "message": "exit {exitCode}",
+        "variant": "info",
         "duration": 3000,
       },
-      "inject": {
-        "as": "system",
-        "template": "Build output:\n```\n{stdout}\n```",
-      },
-    },
-  ],
-}
-````
-
-#### Filter by Multiple Tool Arguments
-
-```jsonc
-{
-  "tool": [
-    // Run for specific file types
-    {
-      "id": "test-js-files",
-      "when": {
-        "tool": "write",
-        "toolArgs": {
-          "path": ["*.js", "*.jsx", "*.ts", "*.tsx"],
-        },
-      },
-      "run": ["npm test -- --testPathPattern={toolArgs.path}"],
-    },
-    // Filter by multiple subagent types
-    {
-      "id": "validate-subagents",
-      "when": {
-        "tool": "task",
-        "toolArgs": {
-          "subagent_type": ["validator", "reviewer", "tester"],
-        },
-      },
-      "run": ["echo 'Validating {toolArgs.subagent_type} subagent'"],
     },
   ],
 }
 ```
 
-#### Handle Async Tool Completion
+### Handle Async Tool Completion (`tool.result`)
 
 ```jsonc
 {
   "tool": [
     {
-      "id": "task-complete",
+      "id": "task-result-hook",
       "when": {
-        "event": "tool.result",
-        "tool": ["task"],
+        "phase": "after",
+        "tool": "task",
         "toolArgs": { "subagent_type": "code-writer" },
       },
       "run": ["npm run validate-changes"],
-      "toast": {
-        "title": "Code Writer Complete",
-        "message": "Validation: {exitCode, select, 0 {Passed} other {Failed}}",
-        "variant": "{exitCode, select, 0 {success} other {warning}}",
-      },
+      "toast": { "title": "Code Writer", "message": "exit {exitCode}" },
     },
   ],
 }
 ```
 
-#### Session Lifecycle Hooks
+### Session Lifecycle Hooks
 
 ```jsonc
 {
@@ -570,11 +332,7 @@ This example demonstrates the plugin's killer feature: **automatic validation in
       "id": "session-start",
       "when": { "event": "session.start" },
       "run": ["echo 'New session started'"],
-      "toast": {
-        "title": "Session Started",
-        "message": "Ready to assist!",
-        "variant": "info",
-      },
+      "toast": { "title": "Session", "message": "started", "variant": "info" },
     },
     {
       "id": "session-idle",
@@ -589,217 +347,93 @@ This example demonstrates the plugin's killer feature: **automatic validation in
 
 ## Template Placeholders
 
-All templates support these placeholders:
-
-| Placeholder  | Description                              | Example                    |
-| ------------ | ---------------------------------------- | -------------------------- |
-| `{id}`       | Hook ID                                  | `lint-ts`                  |
-| `{agent}`    | Calling agent name                       | `orchestrator`             |
-| `{tool}`     | Tool name                                | `write`                    |
-| `{cmd}`      | Executed command                         | `npm run lint`             |
-| `{stdout}`   | Command stdout (truncated to 4000 chars) | `Linting complete`         |
-| `{stderr}`   | Command stderr (truncated to 4000 chars) | `Error: missing semicolon` |
-| `{exitCode}` | Command exit code                        | `0` or `1`                 |
+All inject/toast string templates support these placeholders:
 
-**Advanced Usage:**
-
-```jsonc
-{
-  "inject": {
-    "template": "Command '{cmd}' exited with code {exitCode}\n\nStdout:\n{stdout}\n\nStderr:\n{stderr}",
-  },
-}
-```
+| Placeholder  | Description                | Example                    |
+| ------------ | -------------------------- | -------------------------- |
+| `{id}`       | Hook ID                    | `lint-ts`                  |
+| `{agent}`    | Calling agent name         | `orchestrator`             |
+| `{tool}`     | Tool name                  | `write`                    |
+| `{cmd}`      | Executed command           | `npm run lint`             |
+| `{stdout}`   | Command stdout (truncated) | `Linting complete`         |
+| `{stderr}`   | Command stderr (truncated) | `Error: missing semicolon` |
+| `{exitCode}` | Command exit code          | `0` or `1`                 |
 
 ---
 
-## Debugging
-
-Enable detailed debug logging:
-
-```bash
-export OPENCODE_HOOKS_DEBUG=1
-opencode start
-```
-
-This logs:
-
-- Command execution details
-- Template interpolation
-- Hook matching logic
-- Error handling
-
-**Example Debug Output:**
-
-```
-[DEBUG] Hook matched: lint-ts
-[DEBUG] Executing: npm run lint
-[DEBUG] Template interpolated: Exit code: 0
-[DEBUG] Toast shown: Lint Complete
-```
-
----
-
-## Event Types
-
-### Tool Events
-
-- **`tool.execute.before`** - Before tool execution
-- **`tool.execute.after`** - After tool execution
-- **`tool.result`** - When async tools complete (task, firecrawl, etc.)
-
-### Session Events
-
-- **`session.start`** - New session started
-- **`session.idle`** - Session became idle
-- **`session.end`** - Session ended
-
----
-
-## Tool vs Session Hooks
-
-### Tool Hooks
-
-- Run before/after specific tool executions
-- Can filter by tool name, calling agent, slash command, tool arguments
-- Access to tool-specific context (tool name, call ID, args)
-- **Best for**: Linting after writes, tests after code changes, validation
-
-### Session Hooks
-
-- Run on session lifecycle events
-- Can only filter by agent name (session events lack tool context)
-- **Best for**: Bootstrapping, cleanup, periodic checks
-
----
+## Why Use This Plugin?
+**It lets you easily set up bash hooks with ~3-5 lines of YAML which are cleanly colocated with your subagent configuration.**
+Conversely, rolling your own looks something like this (for each project and set of hooks you want to set up):
+```ts
+import type { Plugin } from "@opencode-ai/plugin";
 
-## Native Plugin vs This Plugin
+export const MyHooks: Plugin = async ({ $, client }) => {
+  const argsCache = new Map();
 
-**The Real Difference:** The Power User Example above would require this native plugin implementation:
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "task") {
+        argsCache.set(input.callID, output.args);
+      }
+    },
 
-**Native Plugin: 73 lines of TypeScript with manual everything**
+    "tool.execute.after": async (input, output) => {
+      if (!output && input.tool === "task") return;
 
-```typescript
-import type { Plugin } from "@opencode-ai/plugin";
+      const args = argsCache.get(input.callID);
+      argsCache.delete(input.callID);
 
-export const ValidationPlugin: Plugin = async ({ $, client }) => {
-  return {
-    "tool.execute.after": async (input) => {
+      // Filter by tool and subagent type
       if (input.tool !== "task") return;
-
-      // No way to filter by toolArgs.subagent_type without complex parsing
+      if (!["engineer", "debugger"].includes(args?.subagent_type)) return;
 
       try {
-        const results: string[] = [];
-
-        try {
-          const typecheck = await $`npm run typecheck`.text();
-          results.push(`TypeCheck: ${typecheck}`);
-        } catch (e: any) {
-          results.push(`TypeCheck failed: ${e.stderr || e.message}`);
-        }
-
-        try {
-          const lint = await $`npm run lint`.text();
-          results.push(`Lint: ${lint}`);
-        } catch (e: any) {
-          results.push(`Lint failed: ${e.stderr || e.message}`);
-        }
-
-        try {
-          const test = await $`npm test -- --coverage --passWithNoTests`.text();
-          results.push(`Tests: ${test}`);
-        } catch (e: any) {
-          results.push(`Tests failed: ${e.stderr || e.message}`);
+        // Run commands sequentially, even if they fail
+        let lastResult = { exitCode: 0, stdout: "", stderr: "" };
+        
+        for (const cmd of ["npm run typecheck", "npm run lint"]) {
+          try {
+            const result = await $`sh -c ${cmd}`.nothrow().quiet();
+            const stdout = result.stdout?.toString() || "";
+            const stderr = result.stderr?.toString() || "";
+            
+            // Truncate to 30k chars to match OpenCode's bash tool
+            lastResult = {
+              exitCode: result.exitCode ?? 0,
+              stdout: stdout.length > 30000 
+                ? stdout.slice(0, 30000) + "\n[Output truncated: exceeded 30000 character limit]"
+                : stdout,
+              stderr: stderr.length > 30000
+                ? stderr.slice(0, 30000) + "\n[Output truncated: exceeded 30000 character limit]"
+                : stderr,
+            };
+          } catch (err) {
+            lastResult = { exitCode: 1, stdout: "", stderr: String(err) };
+          }
         }
 
-        const output = results.join("\n\n");
-        const exitCode = results.some((r) => r.includes("failed")) ? 1 : 0;
-        const message = `🔍 Validation Results:\n\n${output}\n\n${
-          exitCode !== 0
-            ? "⚠️ The code you just wrote has validation errors. Please fix them before proceeding."
-            : ""
-        }`;
-
-        await client.session.prompt({
-          sessionID: input.sessionID,
-          message,
+        // Inject results into session (noReply prevents LLM response)
+        const message = `Validation (exit ${lastResult.exitCode})\n\n${lastResult.stdout}\n${lastResult.stderr}`;
+        await client.session.promptAsync({
+          path: { id: input.sessionID },
+          body: {
+            noReply: true,
+            parts: [{ type: "text", text: message }],
+          },
         });
 
-        console.log(
-          exitCode === 0 ? "✓ All checks passed" : "✗ Validation failed",
-        );
-      } catch (e) {
-        console.error("Validation hook failed:", e);
+        // Show toast notification
+        await client.tui.showToast({
+          body: {
+            title: "Validation",
+            message: `exit ${lastResult.exitCode}`,
+            variant: "info",
+          },
+        });
+      } catch (err) {
+        console.error("Hook failed:", err);
       }
     },
   };
 };
-```
-
-Problems: Can't filter by subagent_type, manual error handling for each command, manual template building, manual session.prompt calls, no toast notifications, must rebuild after changes.
-
-**This Plugin: 15 lines of JSON**
-
-````jsonc
-{
-  "id": "validate-engineer-work",
-  "when": {
-    "phase": "after",
-    "tool": "task",
-    "toolArgs": { "subagent_type": ["engineer", "debugger"] },
-  },
-  "run": [
-    "npm run typecheck",
-    "npm run lint",
-    "npm test -- --coverage --passWithNoTests",
-  ],
-  "inject": "🔍 Validation Results:\n\n**TypeCheck:** {exitCode, select, 0 {✓ Passed} other {✗ Failed}}\n\n```\n{stdout}\n```\n\n{exitCode, select, 0 {} other {⚠️ Please fix validation errors.}}",
-  "toast": {
-    "title": "Code Validation",
-    "message": "{exitCode, select, 0 {All checks passed ✓} other {Validation failed}}",
-    "variant": "{exitCode, select, 0 {success} other {error}}",
-  },
-}
-````
-
----
-
-### Feature Comparison
-
-| Feature                  | Native Plugin                           | This Plugin                  |
-| ------------------------ | --------------------------------------- | ---------------------------- |
-| **Setup**                | TypeScript, build steps, error handling | JSON/YAML config             |
-| **Error Handling**       | Manual try/catch required               | Automatic, non-blocking      |
-| **User Feedback**        | Console logs (UI spam)                  | Toast notifications          |
-| **Context Injection**    | Manual SDK calls                        | Automatic                    |
-| **Tool Filtering**       | Basic tool name only                    | Tool name + ANY arguments    |
-| **Subagent Targeting**   | Complex parsing required                | Native `toolArgs` filter     |
-| **Guaranteed Execution** | Depends on agent                        | Always runs                  |
-| **Token Cost**           | Variable                                | Zero tokens                  |
-| **Hot Reload**           | Requires rebuild                        | Edit config, works instantly |
-| **Debugging**            | Console.log                             | OPENCODE_HOOKS_DEBUG=1       |
-
----
-
-## Known Limitations
-
-### Session Hooks Cannot Filter by Agent
-
-Session lifecycle events (`session.start`, `session.idle`, `session.end`) don't include the calling agent name. You **cannot** use the `agent` filter field in session hook conditions—it matches all agents.
-
-**Workaround:** Use `tool.execute.after` events instead, which provide agent context.
-
----
-
-## Development
-
-```bash
-bun install
-bun run build
-```
-
-TODO:
-
-- Implement max-length output using tail
-- Add more template functions (date formatting, etc.)
+```