@globant/coda-darwin-x64 1.0.0

package/assets/docs/hooks.md

@@ -0,0 +1,704 @@
+# Lifecycle hooks
+
+**Hooks** are user-defined shell commands or HTTP endpoints that run automatically at specific points in a Coda session. They let you enforce policies, inject context, gate dangerous operations, run linters, log activity, and integrate with external systems — without modifying Coda's source code.
+
+The hook system is **compatible with Claude Code hooks**: the same JSON input/output contract, the same config format, and the same `hooks/hooks.json` plugin convention all work in Coda.
+
+---
+
+## Quick start
+
+Add a `hooks` key to `~/.coda/config.json` (global) or `.coda/config.json` (project):
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'About to run a Bash command' >> ~/.coda/hooks.log"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Restart Coda (or run `/reload-hooks`) for the change to take effect.
+
+---
+
+## Where hooks are configured
+
+| Source | Location | Priority |
+| --- | --- | --- |
+| **Project hooks** | `.coda/config.json` → `hooks` key | Highest — run first |
+| **Global hooks** | `~/.coda/config.json` → `hooks` key | Second |
+| **Plugin hooks** | `hooks/hooks.json` inside an installed plugin | Lowest — run last |
+
+When the same hook command appears in more than one source for the same event and matcher, only the highest-priority copy runs (deduplication by `event + matcher + type + command/url`).
+
+---
+
+## Hook events
+
+Each event fires at a specific point in the session lifecycle.
+
+### Tool events
+
+| Event | When it fires | Can block? |
+| --- | --- | --- |
+| `PreToolUse` | Before a tool executes | **Yes** — return `decision: "block"` or exit code 2 |
+| `PostToolUse` | After a tool succeeds | No — can inject `additionalContext` |
+| `PostToolUseFailure` | After a tool throws an error | No — informational |
+
+The **matcher** on tool events is tested against the **tool name**. g-coda's runtime tool names are lower-case — `bash`, `write`, `edit`, `read`, `glob`, `grep` — but exact / pipe-separated matchers are **case-insensitive**, so Claude Code's capitalized names (`"Bash"`) also match. (Regex matchers, e.g. `"^mcp__.*"`, are matched case-sensitively.)
+
+### Session events
+
+| Event | When it fires | Can block? |
+| --- | --- | --- |
+| `SessionStart` | When a session is created | No |
+| `SessionEnd` | When a session ends | No |
+| `Stop` | When the agent loop finishes a turn | No |
+| `PreCompact` | Before context compaction runs | **Yes** — return `decision: "block"` to cancel |
+| `PostCompact` | After context compaction completes | No |
+
+### Prompt events
+
+| Event | When it fires | Can block? |
+| --- | --- | --- |
+| `UserPromptSubmit` | When the user submits a message | **Yes** — can block or rewrite the prompt |
+
+---
+
+## Configuration schema
+
+### Full example
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".coda/hooks/validate-bash.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "write|edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".coda/hooks/check-file-policy.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "write|edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:8080/hooks/prompt",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"Session started at $(date)\" >> ~/.coda/sessions.log"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Matcher patterns
+
+The `matcher` field filters which tool names (or session sources) trigger the hook. It is optional — omit it or use `"*"` to match everything.
+
+| Pattern | Example | Matches |
+| --- | --- | --- |
+| Omitted or `"*"` | — | All values |
+| Exact string (case-insensitive) | `"bash"` / `"Bash"` | The `bash` tool |
+| Pipe-separated list (case-insensitive) | `"write\|edit"` | `write` or `edit` |
+| JavaScript regex (case-sensitive) | `"^mcp__.*"` | Any MCP tool |
+
+### Hook handler fields
+
+#### Command hook (`type: "command"`)
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | ✅ | `"command"` |
+| `command` | ✅ | The command to run. In **shell form** (no `args`) it is the command string passed to a shell. In **exec form** (`args` present) it is the executable to spawn directly. Receives JSON on stdin. |
+| `args` | — | Argument vector. When present (even `[]`), the hook runs in **exec form**: `command` is spawned directly with `args` as its arguments and **no shell** — each element is passed verbatim (no quoting/globbing). `shell` is ignored. Path placeholders are substituted in each element. |
+| `shell` | — | Shell for **shell form** only (ignored when `args` is set): `"bash"` (→ `bash -c`) or `"powershell"` (→ `powershell -NoProfile -Command`). Defaults to `sh -c`. |
+| `timeout` | — | Seconds before the hook is killed (default: 600). |
+| `if` | — | Permission rule — conditionally skip the hook (see [Conditional execution](#conditional-execution-if-field)). |
+| `statusMessage` | — | Custom spinner label shown while the hook runs. |
+| `async` | — | `true` → run in background; results polled at turn boundaries. |
+| `asyncRewake` | — | `true` → run detached; on exit code 2 the model is re-engaged with the hook's output. |
+| `once` | — | `true` → run once per session then remove (schema accepted; not yet enforced). |
+
+#### HTTP hook (`type: "http"`)
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | ✅ | `"http"` |
+| `url` | ✅ | URL to POST JSON to. |
+| `headers` | — | Extra request headers. `$VAR` and `${VAR}` references anywhere in a value (e.g. `"Bearer $MY_TOKEN"`) are interpolated from env, but only for names listed in `allowedEnvVars`. References to unlisted variables are replaced with an empty string. |
+| `allowedEnvVars` | — | Env var names whose values may be interpolated into `headers`. |
+| `timeout` | — | Seconds before the request is aborted (default: 600). |
+| `async` | — | `true` → fire-and-forget: the POST is dispatched in the background and does not block the lifecycle event. Async HTTP hooks cannot block or return a decision; the response is logged but not applied. |
+| `if` | — | Permission rule (see [Conditional execution](#conditional-execution-if-field)). |
+
+---
+
+## JSON input (what your hook receives)
+
+Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (HTTP hooks). All events include these base fields:
+
+```jsonc
+{
+  "session_id": "abc123",
+  "transcript_path": "",
+  "cwd": "/home/user/my-project",
+  "hook_event_name": "PreToolUse"
+}
+```
+
+### Tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`)
+
+```jsonc
+{
+  "session_id": "abc123",
+  "transcript_path": "",
+  "cwd": "/home/user/my-project",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "git status", "description": "Check git status" },
+  "tool_use_id": "toolu_01XYZ",
+  // PostToolUse only:
+  "tool_response": "On branch main\n...",
+  // PostToolUseFailure only:
+  "error": "Command not found: gti"
+}
+```
+
+### `UserPromptSubmit`
+
+```jsonc
+{
+  "session_id": "abc123",
+  "transcript_path": "",
+  "cwd": "/home/user/my-project",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "Refactor the auth module"
+}
+```
+
+### `SessionStart`
+
+```jsonc
+{
+  "session_id": "abc123",
+  "transcript_path": "",
+  "cwd": "/home/user/my-project",
+  "hook_event_name": "SessionStart",
+  "source": "startup"
+}
+```
+
+### `Stop`
+
+```jsonc
+{
+  "session_id": "abc123",
+  "transcript_path": "",
+  "cwd": "/home/user/my-project",
+  "hook_event_name": "Stop",
+  "stop_reason": "turn_complete"
+}
+```
+
+---
+
+## JSON output (what your hook can return)
+
+Your hook can print a JSON object to **stdout** (command hooks) or return it as the **response body** (HTTP hooks). All fields are optional.
+
+```jsonc
+{
+  // Stop the agent entirely (any event)
+  "continue": false,
+  "stopReason": "Policy violation detected",
+
+  // Show a warning to the user without stopping
+  "systemMessage": "Warning: this file is read-only",
+
+  // Block the current operation (PreToolUse, UserPromptSubmit, PreCompact)
+  "decision": "block",
+  "reason": "Bash commands are not allowed in this project",
+
+  // Event-specific output
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+
+    // PreToolUse: override the permission decision
+    "permissionDecision": "allow",   // or "deny" or "ask"
+    "permissionDecisionReason": "Approved by policy engine",
+
+    // PreToolUse: rewrite the tool's input before it runs
+    "updatedInput": { "command": "git status --short" },
+
+    // PostToolUse: append context to the tool result (shown to the model)
+    "additionalContext": "Lint passed. No issues found.",
+
+    // UserPromptSubmit: rewrite the user's prompt
+    "updatedPrompt": "Refactor the auth module. Follow the style guide in STYLE.md."
+  }
+}
+```
+
+### Exit codes (command hooks only)
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success — stdout is parsed for JSON output |
+| `2` | **Blocking error** — stderr (or stdout) is shown to the user/model; the operation is blocked |
+| Any other | Non-blocking error — execution continues; stderr is logged |
+
+---
+
+## Blocking operations
+
+To **block** a tool call or prompt, use either:
+
+- **Exit code 2** — the simplest approach; stderr becomes the error message
+- **JSON output** with `"decision": "block"` and an optional `"reason"`
+
+```bash
+#!/bin/bash
+# .coda/hooks/no-rm.sh
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+
+if echo "$COMMAND" | grep -qE '\brm\b.*-rf'; then
+  echo "Blocked: rm -rf is not allowed" >&2
+  exit 2
+fi
+```
+
+```jsonc
+// config.json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": ".coda/hooks/no-rm.sh" }]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Injecting context into tool results
+
+A `PostToolUse` hook can append information to the tool result that the model sees as part of the response. Use `hookSpecificOutput.additionalContext`:
+
+```bash
+#!/bin/bash
+# .coda/hooks/lint-after-write.sh
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+if [ -n "$FILE" ]; then
+  RESULT=$(npx eslint "$FILE" --format compact 2>&1)
+  if [ -n "$RESULT" ]; then
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"ESLint: $RESULT\"}}"
+  fi
+fi
+```
+
+The model sees the tool result followed by `[Hook] ESLint: ...`.
+
+---
+
+## Rewriting prompts
+
+A `UserPromptSubmit` hook can modify the user's message before the model sees it:
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt')
+ENHANCED="$PROMPT\n\nContext: $(cat STYLE.md 2>/dev/null | head -20)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"updatedPrompt\":\"$ENHANCED\"}}"
+```
+
+---
+
+## Conditional execution (`if` field)
+
+The `if` field conditionally skips a hook based on the tool name and its input. It uses the same permission rule syntax as Claude Code:
+
+```
+rule ::= toolName | toolName(content)
+```
+
+| Pattern | Example | Matches |
+| --- | --- | --- |
+| Tool name only | `"Bash"` | Any Bash call |
+| Exact content | `"Bash(git add)"` | Only `git add` |
+| Wildcard | `"Bash(git *)"` | Any git subcommand |
+| File glob | `"Edit(src/*.ts)"` | TypeScript files under `src/` |
+| Prefix (legacy) | `"Bash(npm:*)"` | `npm`, `npm install`, `npm run …` |
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".coda/hooks/git-policy.sh",
+            "if": "Bash(git push*)"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+For non-tool events, hooks with an `if` field are silently skipped.
+
+---
+
+## Plugin hooks
+
+Plugins can ship a `hooks/hooks.json` file at the plugin root. The format is identical to the `hooks` key in `config.json`, wrapped in a top-level object:
+
+```jsonc
+// hooks/hooks.json
+{
+  "description": "Runs lint after every file write",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "write|edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODA_PLUGIN_ROOT}/scripts/lint.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Path placeholders in plugin hooks
+
+| Placeholder | Resolves to |
+| --- | --- |
+| `${CODA_PLUGIN_ROOT}` | The plugin's installation directory |
+| `${CODA_PROJECT_DIR}` | The current project directory (cwd) |
+
+---
+
+## Session environment files (`CODA_ENV_FILE`)
+
+Hooks can export environment variables that persist across all subsequent Bash tool commands in the session.
+
+### Mode 1 — External env file (process-level)
+
+Set `CODA_ENV_FILE` in your shell before launching Coda. Its contents are prepended to every Bash command:
+
+```bash
+export CODA_ENV_FILE=~/.coda/my-env.sh
+coda
+```
+
+### Mode 2 — Hook-writable env file (hook-level)
+
+For `SessionStart` hooks (bash/wsl only), Coda sets `CODA_ENV_FILE` to a writable path before spawning your hook. Write `export` statements to that file; they are sourced before every subsequent Bash command in the session:
+
+```bash
+#!/bin/bash
+# SessionStart hook — activate a Python venv for the whole session
+source .venv/bin/activate
+echo "export VIRTUAL_ENV=$VIRTUAL_ENV" >> "$CODA_ENV_FILE"
+echo "export PATH=$PATH" >> "$CODA_ENV_FILE"
+```
+
+---
+
+## Async hooks
+
+By default hooks run **synchronously** — the lifecycle event waits for every matched hook to complete. Two opt-in async modes are available:
+
+### `async: true` — tracked background
+
+The hook runs in the background. Results are polled at the start of each turn and applied (e.g. `additionalContext` is injected into the next tool result).
+
+```jsonc
+{
+  "type": "command",
+  "command": ".coda/hooks/slow-analysis.sh",
+  "async": true,
+  "timeout": 30
+}
+```
+
+### `asyncRewake: true` — detached watcher
+
+The hook runs fully detached. If it exits with code 2, its stderr/stdout is injected as a system message that re-engages the model. Useful for background file watchers or integrity checkers.
+
+```jsonc
+{
+  "type": "command",
+  "command": ".coda/hooks/file-integrity-watcher.sh",
+  "asyncRewake": true
+}
+```
+
+### Runtime async (hook-initiated)
+
+A hook can decide at runtime to go async by printing `{"async": true}` as its first stdout line. Coda backgrounds the process immediately and continues.
+
+---
+
+## Disabling all hooks
+
+Set `disableAllHooks: true` in `config.json` to disable all hooks globally. Useful in CI environments or when debugging unexpected behavior:
+
+```jsonc
+{
+  "disableAllHooks": true
+}
+```
+
+---
+
+## Slash commands
+
+| Command | What it does |
+| --- | --- |
+| `/hooks` | Browse all configured hooks (event → matchers → handlers) |
+| `/hooks list [event]` | Filter the list by event name |
+| `/reload-hooks` | Reload hooks config from disk without restarting the session |
+
+---
+
+## Environment variables available to hooks
+
+| Variable | Value |
+| --- | --- |
+| `CODA_PROJECT_DIR` | Current project directory |
+| `CODA_PLUGIN_ROOT` | Plugin installation directory (plugin hooks only) |
+| `CODA_ENV_FILE` | Writable env file path (SessionStart hooks only, bash/wsl) |
+
+All other environment variables from the Coda process are also inherited.
+
+---
+
+## Execution model
+
+- **All matching hooks run in parallel** (`Promise.all`). There is no guaranteed order between hooks that match the same event.
+- **Mutation conflicts** (`updatedPrompt`, `updatedInput`, `additionalContext`) are resolved by **last-write-wins** across parallel results.
+- **Any `blocked: true` result blocks the event** regardless of what other hooks returned.
+- **Output is capped at 10 000 characters** per hook (stdout and stderr separately).
+- **Default timeout is 600 seconds** per hook. Set `timeout` to a lower value for interactive hooks.
+
+---
+
+## Security considerations
+
+- Hooks only run from config files you control (`~/.coda/config.json`, `.coda/config.json`) or plugins you have explicitly installed. They are not sandboxed.
+- HTTP hook headers only interpolate env vars listed in `allowedEnvVars`.
+- Review hook scripts before enabling them, especially from plugins or shared configs.
+- Use `disableAllHooks: true` in environments where hooks should not run.
+
+---
+
+## Common recipes
+
+### Block `git push` in a project
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -e '.tool_input.command | test(\"git push\")' > /dev/null && echo 'git push is blocked in this project' >&2 && exit 2 || exit 0",
+            "if": "Bash(git push*)"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Run Prettier after every file write
+
+```jsonc
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "write|edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && npx prettier --write \"$FILE\" 2>/dev/null; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Log every session to a file
+
+```jsonc
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"$(date -Iseconds) session=$(jq -r .session_id) cwd=$(jq -r .cwd)\" >> ~/.coda/session-history.log"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Notify a webhook on every prompt
+
+```jsonc
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "http",
+            "url": "https://hooks.example.com/coda-prompt",
+            "headers": { "Authorization": "$WEBHOOK_TOKEN" },
+            "allowedEnvVars": ["WEBHOOK_TOKEN"],
+            "timeout": 3,
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Activate a Python venv for the whole session
+
+```bash
+#!/bin/bash
+# .coda/hooks/activate-venv.sh
+# Used as a SessionStart hook
+if [ -f ".venv/bin/activate" ]; then
+  source .venv/bin/activate
+  echo "export VIRTUAL_ENV=\"$VIRTUAL_ENV\"" >> "$CODA_ENV_FILE"
+  echo "export PATH=\"$PATH\"" >> "$CODA_ENV_FILE"
+fi
+```
+
+```jsonc
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".coda/hooks/activate-venv.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+**Hooks are not running**
+- Check that `disableAllHooks` is not `true` in any config layer.
+- Run `/hooks` to confirm the hook appears in the snapshot.
+- Run `/reload-hooks` after editing config files.
+- Verify the hook script is executable (`chmod +x`).
+
+**Hook is blocking unexpectedly**
+- A non-zero exit code other than 2 is non-blocking. Exit code 2 is the blocking signal.
+- Check that your script does not accidentally exit with code 2 on success paths.
+
+**Hook output is not reaching the model**
+- `additionalContext` only works on `PostToolUse` hooks. Verify the event name in `hookSpecificOutput.hookEventName`.
+- The hook must exit with code 0 and print valid JSON to stdout.
+
+**Async hook results are not appearing**
+- Async hook results are applied at the **start of the next turn**, not immediately.
+- Check that `timeout` is long enough for the hook to complete.
+
+---
+
+## See also
+
+- [Configuration](configuration.md) — where `config.json` files live and how they merge
+- [Features](features.md) — plugins, extensions, agents, skills
+- [How to create a Coda extension](create-extension.md) — programmatic hooks via the extension API
+- [Coda tools overview](tools.md) — tool names to use in `matcher` patterns