@globant/coda-darwin-x64 1.2.0 → 1.4.0

package/assets/docs/permissions.md

@@ -1,15 +1,17 @@
 # Permissions & Approvals
 
-CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.
+CODA can read files, run shell commands, and edit your code. Every tool call goes through an always-on **authorization engine** that decides `allow` / `ask` / `deny`. `allow` runs, `deny` does not, and `ask` pauses for your decision. This human-in-the-loop (HITL) design keeps you in control without prompting for every routine action.
 
 Rules and modes combine to form a layered safety net — you stay in control even when the agent runs largely on its own. This page covers the permission modes, the easy plain-English way to change permissions (`propose_policy`), the rule syntax the agent writes for you, how decisions are made, and the un-relaxable catastrophic floor.
 
 ## How approvals work
 
-When CODA wants to do something that could change your system, it pauses and shows you exactly what it's about to do. In the interactive TUI you answer with a single key:
+When the engine returns `ask`, CODA pauses and shows the effective action and reason. In the interactive TUI:
 
-- **Y** — allow this action and continue.
-- **N** — skip it; CODA carries on without running that action.
+- **Y** — allow this action once and continue.
+- **A** — allow the displayed reusable rule for this session, when that option is available.
+- **Arrow keys + Enter** — choose another option, including a permanent project rule when CODA can derive one. Permanent changes get a second confirmation that explains their scope.
+- **N** — deny it; CODA carries on without running that action.
 
 Some prompts are **questions** rather than yes/no approvals — for example when a tool needs you to pick from a numbered list or type a short answer. There you type your choice (or the number) and press **Enter**.
 
@@ -17,7 +19,7 @@ How often CODA stops to ask depends on your **permission mode** and your **rules
 
 ## Permission modes
 
-The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default with `permissions.defaultMode` in your config (globally in `~/.coda/config.json`, or per project in `.coda/config.json`).
+The main approval control is the **permission mode** — the master dial that sets the agent's default level of autonomy. Press **Ctrl+P** to cycle the session between three modes; set the default in `~/.coda/config.json`. A project `.coda/config.json` can make that starting mode more restrictive, but it cannot silently raise autonomy above your user setting.
 
 The three valid values are `"read-only"`, `"default"`, and `"auto"`.
 
@@ -130,12 +132,14 @@ It is **on by default**. To stop the agent from ever suggesting permanent rule c
 
 To pin a specific command regardless of mode, add rules under `permissions` in `config.json`:
 
-```jsonc
-"permissions": {
-  "defaultMode": "default",
-  "allow": ["Bash(git status)", "Bash(npm test)"],
-  "ask":   ["Bash(git push:*)"],
-  "deny":  ["Bash(rm:*)"]
+```json
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": ["Bash(git status)", "Bash(npm test)"],
+    "ask": ["Bash(git push:*)"],
+    "deny": ["Bash(rm:*)"]
+  }
 }
 ```
 
@@ -327,7 +331,7 @@ Two things to know when reading the output:
 - **See what applies first:** run `/permissions` (or `coda permissions` outside a session) — see the section "Seeing what applies right now" above.
 - **In the session:** press **Ctrl+P** to cycle the permission mode.
 - **Just ask:** tell the agent in plain English (`allow pnpm build`, `never allow rm -rf`) and it drafts the rule via `propose_policy` for your approval.
-- **Default / per project:** `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json` (project config overrides your personal default) — see [Configuration](#configuration).
+- **Default / per project:** set `permissions.defaultMode` and `permissions.allow`/`ask`/`deny` in `~/.coda/config.json` or a project's `.coda/config.json`. Rules accumulate across scopes; a project mode can tighten but cannot raise your personal default — see [Configuration](#configuration).
 - **For a headless run:** the `--auto-approve none|all` flag (see [Commands & Flags](#cli-reference)).
 
 ## See also

package/assets/docs/quickstart.md

@@ -51,12 +51,16 @@ Search the codebase for code smells around error handling, duplicated logic, and
 
 ## 3. Review what CODA does
 
-When CODA wants to run a shell command or write to a file, it shows you what it's about to do and asks for approval (depending on your [bash approval settings](#config-reference)). You can:
+Every tool call passes through CODA's authorization engine. Safe actions can run immediately, denied actions do not run, and actions classified as `ask` open an approval prompt. When a prompt appears, you can:
 
-- Press **Y** to approve and continue
-- Press **N** to skip that step
+- Press **Y** to approve this action
+- Press **A** to approve the displayed reusable rule for this session, when offered
+- Use **Arrow keys + Enter** to choose another offered option, including a permanent project rule (which gets a second confirmation)
+- Press **N** to deny this action
 - Press **Esc** to interrupt the current turn entirely
 
+How often you see a prompt depends on the current permission mode and your `allow` / `ask` / `deny` rules. See [Permissions & Approvals](#permissions).
+
 If CODA goes in the wrong direction, interrupt early — don't let it keep going. Interrupting and redirecting is faster than undoing a lot of changes.
 
 ## 4. Undo anything
@@ -75,7 +79,7 @@ This opens the timeline picker (you can also type `/rewind`, or press **Esc** tw
 
 A few small habits make long sessions much better:
 
-- **Watch the context meter.** The status bar shows how full the conversation context is. As it nears 100%, CODA compacts automatically — or you can run `/compact` before switching to a new topic.
+- **Watch the context meter.** The status bar shows how full the conversation context is. CODA reduces context automatically before it fills the window — or you can run `/compact` before switching to a new topic.
 - **Start fresh for unrelated work.** `/new` opens a clean session (the old one is saved and resumable) so unrelated context doesn't bleed into the next task.
 - **Switch models when it helps.** Press `Shift+Tab` to cycle favorite models, or run `/switch-model` to pick one — use a stronger model for hard reasoning, a cheaper one for routine edits.
 - **Resume later.** When you exit (`Ctrl+C` twice or `/exit`), CODA prints a `coda --session-id <id>` command you can paste to pick up exactly where you left off. You can also run `/sessions` from within any active session to open the session browser and switch directly. For an even quicker pick-up, run `coda --lastsession` from your project root to resume the most recent session automatically.

package/assets/docs/sessions.md

@@ -130,7 +130,7 @@ It prints a health summary: current **State**, the **project** + **workspace id*
 
 ## Watch the context fill level
 
-The status bar at the bottom of the TUI shows a context fill percentage. When it approaches 100%, CODA will automatically compact the session history. If you're deep in a long session and things start feeling off, try:
+The status bar at the bottom of the TUI shows a context fill percentage. CODA begins automatic reduction before the window is exhausted: it can move stale tool output aside first and summarize older history at the configured threshold. If you're deep in a long session and things start feeling off, try:
 
 ```text
 /compact

package/assets/docs/shortcuts.md

@@ -36,7 +36,7 @@ These shortcuts work inside the interactive TUI. Type `?` at any time to open th
 | --- | --- |
 | `Ctrl+↑` | Scroll up in the transcript |
 | `Ctrl+↓` | Scroll down in the transcript |
-| `Ctrl+Shift+C` | Copy the last code block to clipboard |
+| `Ctrl+Shift+C` | Copy the last code block to clipboard (use [`/copy`](#cli-reference) to copy a full response instead) |
 | `Esc Esc` | Open the timeline picker (double-press within ~750 ms when the chat input is empty and no turn is running) |
 
 ## Model switching

package/assets/docs/tools-reference.md

@@ -36,9 +36,15 @@ To limit which tools a single run may use, pass `coda --tools …` (see [Command
 | `skills` | Load a discovered skill by name |
 | `run_agent`, `wait_agents`, `cancel_agent` | Start and manage delegated [agent](#agents) runs |
 | `workflow` | Run a named workflow script that orchestrates multiple agents in the background (requires agents to be enabled) |
+| `todo_write`, `todo_update`, `todo_list` | Record, revise, and read the session's TODO plan (enabled by config; see [What you can configure](#what-you-can-configure)) |
+| `propose_policy` | Propose a permanent change to your authorization policy — add/remove a rule or set the permission mode (a tightening applies immediately; a loosening asks you first) |
+| `update_run` | End the active autonomous run — mark it `complete` or `blocked`. Available only while an autonomous run is active |
+| `reconfigure_loop` | Reconfigure the active `/loop`'s schedule in place (`intervalMs`, `cap`, and/or `maxDurationMs`). Available only while a loop is active |
 
 Extensions and plugins can register more tools the same way the core registers these built-ins.
 
+A few tools are **registered dynamically** and only appear while the matching mode is running: `update_run` exists only during an [autonomous run](#guide-automate) and `reconfigure_loop` only during a `/loop` — both are unregistered the moment that run or loop ends (mirroring how `mcp_execute` comes and goes with its MCP servers).
+
 ### How CODA chooses a tool
 
 You never name a tool — CODA picks based on the task. A few patterns are worth knowing so its behavior feels predictable:
@@ -66,6 +72,7 @@ Tool behavior is configured in a few different places — some from the `/settin
 | **OmniParser** | How much extracted document text is inlined in a result vs written to `.coda/omni-parser/`. | `CODA_OMNI_PARSER_INLINE_THRESHOLD_CHARS` env var |
 | **MCP** | Which servers load — which in turn decides whether `mcp_execute` is useful. | The `/mcp` manager |
 | **Agents** | Whether the delegation tools exist, and how runs behave. See [Agents](#agents). | Config (`agents.*`) + the `/agents` manager |
+| **TODO planning** | Whether the `todo_write` / `todo_update` / `todo_list` tools exist. On by default in interactive sessions; headless runs enable them only when `CODA_ENABLE_TODOS` is set to `1`, `true`, or `yes`. | Config (`tools.todos.enabled`) + `CODA_ENABLE_TODOS` env var (headless) |
 
 ## Web fetch
 
@@ -111,7 +118,7 @@ The tool can also write a fetched page straight to a file (always confined to `.
 
 When a delegated [agent](#agents) run executes, it uses a trimmed tool set. Two categories are removed from every child session:
 
-- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs.
+- **Delegation tools** — `run_agent`, `wait_agents`, and `cancel_agent` are unregistered, so a sub-agent **cannot delegate further** (no nested sub-agents) or wait on other runs. `workflow` is currently still registered in a child session, so a sub-agent can launch a workflow.
 - **User prompting** — `ask_user` is unregistered, so a sub-agent **cannot prompt you** for input. It must complete its task from the instructions it was given.
 
 The `skills` tool is also unavailable in child sessions — skill loading is main-agent-only. The remaining parent tools (read, edit, write, bash, search, etc.) are inherited, and the MCP service is deliberately shared, so `mcp_execute` also works inside a child run.

package/assets/docs/workflows.md

@@ -76,7 +76,7 @@ Create a workflow that keeps generating test ideas until it finds no new ones or
 
 > **Tip — name the inputs.** Mentioning the folder, the diff, or the output location in your request helps `create-workflow` set up the workflow's arguments, so later runs can infer them from a one-line prompt.
 
-The `create-workflow` agent **writes the file but doesn't run it**. The **first** time you run a freshly authored workflow, CODA asks you to confirm — you can approve it, view the generated script, or decline. After that first confirmation, running it again goes straight to the background.
+The `create-workflow` agent **writes the file but doesn't run it**. A freshly authored workflow gets a first-run confirmation where you can run it, view the generated script, request amendments, or decline. Workflows already committed under the current project's `.coda/workflows/` can run directly. Workflows discovered from parent/user directories or plugins ask for approval the first time; editing one changes its content and asks again.
 
 ## Workflow authoring conventions
 
@@ -118,6 +118,7 @@ A workflow doesn't just print a wall of text. As it runs it typically:
 - **Fans out** the work across agents (one per file, module, or ticket) and runs them up to a concurrency cap derived from available CPU cores (capped at 16).
 - **Synthesizes** their results — often into one or more **artifacts** written to disk (a report, a JSON summary, a translated doc).
 - **Reports back** on a later turn with a short overview and links to any artifacts it wrote, so you can open them when you're ready.
+- **Tracks usage** across its agent runs, including the agent count, output tokens, and USD cost when the provider reports it.
 
 Because each step is a real agent run, you can watch the individual agents in the `/workflows` dashboard and open their transcripts, exactly like standalone [agents](#agents).
 

package/assets/skills/configure-mcp/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: configure-mcp
+description: Configure g-coda's MCP client to connect to an MCP server from a Git URL, remote HTTP endpoint, or npm/pip package, at project or global scope. Use when the user asks to add, register, configure, install, or set up an MCP server or MCP client. e.g. "add the playwright MCP server", "configure an MCP server from this URL", "install this MCP tool globally".
+---
+
+# Configure MCP
+
+Configure g-coda's MCP client to connect to an MCP server by registering the server entry in the correct config file at the user-chosen scope. The input can be a Git URL, remote HTTP endpoint, or npm/pip package. Reject inputs from which no valid transport (`command` or `url`) can be derived — write nothing in that case.
+
+---
+
+## Golden Rule
+
+**Never overwrite existing server entries.** Always merge your new entry into the existing `mcpServers` object. If a server with the same name already exists, confirm with the user before replacing it.
+
+**Never hardcode secrets.** Tokens, API keys, and credentials must use `${VAR}` or `${VAR:-default}` interpolation — never inline values.
+
+---
+
+## Step 1: Determine Scope
+
+Ask the user which scope they want if not specified:
+
+| Scope | Write to | When to use |
+|---|---|---|
+| **Project** | `<cwd>/.coda/mcp.json` | Only this repo; shared via version control |
+| **Global** | `~/.coda/mcp.json` | All projects on this machine; personal |
+
+- `<cwd>` = `process.cwd()` where g-coda is running, not the nearest `.git` root.
+- If unsure, **default to project scope**.
+- A project entry always wins over a global entry with the same server name.
+
+**Target file:** always write to `mcp.json` (top-level `mcpServers` key).
+
+---
+
+## Step 2: Detect Input Type and Validate
+
+### 2a. Remote HTTP endpoint
+
+Input is `https://…` or `http://…` pointing to a live MCP endpoint (Streamable HTTP transport).
+
+Example entry — replace the URL, token variable name, and header values with the real ones:
+
+```jsonc
+{
+  "url": "https://api.example.com/mcp",
+  "authorizationToken": "Bearer ${API_TOKEN}",
+  "headers": { "X-Custom": "${CUSTOM_HEADER}" },
+  "timeout": 30
+}
+```
+
+> ⚠️ Make sure no tokens or secrets are exposed — always use `${VAR}` interpolation for credentials.
+
+Transport: `url` → HTTP. Do **not** set `command`.
+
+### 2b. npm/pip package or CLI tool
+
+Input is a package name, `npx`/`uvx` invocation, or local binary path (stdio transport).
+
+Example entry — replace the package name and env var names with the real ones:
+
+```jsonc
+{
+  "command": "npx",
+  "args": ["-y", "@scope/mcp-package@latest"],
+  "env": { "API_KEY": "${MY_API_KEY}" }
+}
+```
+
+> ⚠️ Make sure no tokens or secrets are exposed — always use `${VAR}` interpolation for credentials.
+
+Common patterns: `npx -y <pkg>`, `uvx <pkg>`, `node /path/to/server.js`, `/path/to/binary`.
+
+Transport: `command` → stdio. Do **not** set `url`.
+
+### 2c. Git URL
+
+Most MCP server repositories support **multiple installation methods** (e.g. `npx`, `uvx`, Docker, a remote HTTP endpoint, or a local build). Do not assume — read the repo's documentation first, then ask the user which method they prefer.
+
+Steps:
+
+1. **Clone temporarily** to read the docs:
+   - Project scope: `<cwd>/.coda/tmp/<name>/`
+   - Global scope: `~/.coda/tmp/<name>/`
+   - Command: `git clone --depth 1 <url> <tmp-dir>`
+2. **Read the README and any MCP-specific docs** to identify all available installation methods.
+3. **Ask the user** which method they prefer — present the options you found. Common options:
+   - `npx -y <pkg>` or `uvx <pkg>` (no local build needed — preferred when available)
+   - Remote HTTP endpoint (if the project exposes one)
+   - Local build (`npm install && npm run build`, entry via `node dist/index.js`)
+4. **Derive the entry** using the chosen method (see sections 2a and 2b for the corresponding entry shape).
+5. **Write the config entry** to `mcp.json`.
+6. **Delete the temporary clone** (`<tmp-dir>`) — it is no longer needed once the config entry is written.
+
+> If the chosen method does not require the cloned directory at runtime (e.g. `npx`/`uvx`/HTTP), the tmp directory is always safe to remove. If the user explicitly chooses a local-build method and the runtime depends on the clone, move the directory to its final location (`<cwd>/.coda/mcp-servers/<name>/` or `~/.coda/mcp-servers/<name>/`) instead of deleting it, and tell the user.
+
+### 2d. Rejection — no derivable transport
+
+If you **cannot** determine either a `command` or a `url` from the input, **do not write anything**. Respond:
+
+> "I couldn't determine a valid MCP server transport from what you provided. An MCP server needs either a runnable command (for stdio transport) or an HTTP URL (for Streamable HTTP transport). Please share the server's npm package name, a Git URL, a binary path, or its HTTP endpoint."
+
+---
+
+## Step 3: Build the Server Entry
+
+A valid entry has **exactly one** of `command` (stdio) or `url` (http) — never both, never neither.
+
+| Field | Transport | Description |
+|---|---|---|
+| `command` | stdio | Executable to run as a subprocess |
+| `args` | stdio | Arguments for the subprocess |
+| `cwd` | stdio | Working directory for the subprocess |
+| `url` | http | MCP server HTTP endpoint |
+| `authorizationToken` | http | Shorthand `Authorization` header; supports `${VAR}` |
+| `headers` | http | Extra request headers; string values support `${VAR}` |
+| `timeout` | http | Request timeout in seconds |
+| `env` | both | Environment variables; supports `${VAR}` and `${VAR:-default}` |
+| `disabled` | both | `true` to skip at load time (default: `false`) |
+
+Secrets in `env`, `headers`, and `authorizationToken` are resolved from `~/.coda/.secrets`, project `.env`, and `process.env` at load time. Never put raw credentials in the config.
+
+Choose a descriptive, kebab-case server name (e.g., `playwright`, `github`, `my-internal-api`).
+
+---
+
+## Step 4: Non-Destructive Merge into Config
+
+### Writing to `mcp.json` (preferred)
+
+```jsonc
+// <cwd>/.coda/mcp.json  (project)  or  ~/.coda/mcp.json  (global)
+{
+  "mcpServers": {
+    "<server-name>": { /* entry fields */ }
+  }
+}
+```
+
+Merge steps:
+1. Read the existing file, or start with `{ "mcpServers": {} }` if absent.
+2. Check whether `mcpServers["<server-name>"]` exists — confirm with the user before replacing.
+3. Add or replace only the target key; preserve all other entries.
+4. Write the file back.
+
+---
+
+## Step 5: Verify and Notify
+
+After writing:
+
+1. Show the user exactly what was written (entry + file path).
+2. Confirm the file is valid JSON (no trailing commas, balanced braces).
+3. Remind the user how to activate the change:
+
+> **MCP changes are not picked up by `/skills refresh`.** To activate:
+> - Run `/mcp` → select **Reload MCP servers**, or
+> - Restart g-coda.
+
+4. For cloned Git repos, delete the temporary directory (`<cwd>/.coda/tmp/<name>/` or `~/.coda/tmp/<name>/`) once the config entry has been written — unless the user chose a local-build method that requires the directory at runtime, in which case it was already moved to its final location as part of step 2c.
+
+---
+
+## Examples
+
+### Example 1 — npm package, project scope
+
+**User:** "Add the Playwright MCP server to this project."
+
+Written to `<cwd>/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+**Response:** Added `playwright` to `.coda/mcp.json`. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 2 — HTTP endpoint, global scope, with auth
+
+**User:** "Set up the GitHub MCP server globally. My token is in `GITHUB_TOKEN`."
+
+Written to `~/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "authorizationToken": "Bearer ${GITHUB_TOKEN}",
+      "timeout": 30
+    }
+  }
+}
+```
+
+**Response:** Added `github` to `~/.coda/mcp.json`. Make sure `GITHUB_TOKEN` is set in your environment or `~/.coda/.secrets`. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 3 — Git URL, project scope
+
+**User:** "Install from https://github.com/example/my-mcp-server into this project."
+
+Steps:
+1. Clone to `<cwd>/.coda/tmp/my-mcp-server/` with `git clone --depth 1 <url> <tmp-dir>`.
+2. Read `README.md` — it documents two options: `npx -y @example/my-mcp-server` or a local build.
+3. Ask the user: *"The repository supports `npx` (no local build needed) or a local build. Which do you prefer?"*
+4. User chooses `npx`. Derive the entry (section 2b).
+5. Write config, then delete `<cwd>/.coda/tmp/my-mcp-server/`.
+
+Written to `<cwd>/.coda/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "my-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@example/my-mcp-server@latest"]
+    }
+  }
+}
+```
+
+**Response:** Added `my-mcp-server` to `.coda/mcp.json` and removed the temporary clone. Run `/mcp` → Reload MCP servers to activate it.
+
+---
+
+### Example 4 — Rejection
+
+**User:** "Add `my-special-tool` as an MCP server."
+
+No URL or command is derivable from the name alone.
+
+**Response:** I couldn't determine a valid MCP server transport for `my-special-tool`. Please share the npm package name, a Git URL, a binary path, or the HTTP endpoint.
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| File exists but is invalid JSON | Report the parse error and path; do not overwrite. Ask user to fix manually. |
+| Server name already exists | Show the existing entry; ask user to confirm replacement. |
+| No transport derivable | Reject with a clear explanation (Step 2d). Do not write anything. |
+| Git clone fails | Report the error and path; do not write a config entry. Clean up any partial tmp directory. |
+| No installation method found in repo docs | Tell the user no clear method was found; ask them to provide the command or URL directly. |
+| Secret value unclear | Ask which env var name to use; never guess a value. |
+
+---
+
+## Instructions for the Agent
+
+1. **Clarify scope first** — ask project vs global if not stated. Default to project.
+2. **Derive the entry** — HTTP URL → `url` field; package/git/binary → `command` field. For Git URLs, clone to a tmp dir, read the docs, ask the user which method to use, then delete the tmp dir. If no transport is derivable, reject immediately (do not write).
+3. **Choose the config file** — always use `mcp.json` (top-level `mcpServers` key).
+4. **Merge non-destructively** — read the existing file first; preserve all other entries.
+5. **No inline secrets** — always use `${VAR}` notation; tell the user which env var to set.
+6. **Validate JSON** — ensure the written file is syntactically valid.
+7. **Remind about reload** — MCP changes need `/mcp` → Reload MCP servers or a restart. `/skills refresh` does NOT reload MCP.
+8. **Show the result** — always display the final entry and the full path of the file written.
+
+---
+
+## Deliverables
+
+When done, provide:
+
+1. The exact file path written (e.g., `<cwd>/.coda/mcp.json` or `~/.coda/mcp.json`).
+2. The server entry that was added (JSON block).
+3. Any env vars the user needs to set (if secrets are involved).
+4. The activation command: `/mcp` → Reload MCP servers (or restart g-coda).

package/assets/skills/create-hook/SKILL.md

@@ -154,15 +154,15 @@ Every hook receives a JSON object on stdin. All events include these base fields
 ```json
 {
   "session_id": "abc123",
-  "transcript_path": "/path/to/transcript.json",
+  "transcript_path": "",
   "cwd": "/path/to/project",
   "hook_event_name": "PreToolUse",
-  "permission_mode": "default",
-  "agent_id": "...",
-  "agent_type": "main"
+  "cli_version": "0.4.2"
 }
 ```
 
+`transcript_path` is always an empty string (Coda persists conversations to a database, not a transcript file; the field exists for wire-compatibility). `cli_version` is the running Coda version — also available to command hooks as the `CODA_VERSION` env var, which is cheaper than parsing stdin in hot-path hooks. `permission_mode`, `agent_id`, and `agent_type` are reserved fields that are currently never populated — do not depend on them.
+
 Additional fields by event:
 
 **Tool events** (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`):