@globant/coda-windows-x64 1.3.0 → 1.4.0

package/assets/docs/extensions.md

@@ -23,7 +23,7 @@ The rest of this page is a **reference** for when you want to understand what CO
 
 An extension is a TypeScript file that exports an `activate` (or `default`) function receiving the `ExtensionAPI`. It lives in `.coda/extensions/` (project) or `~/.coda/extensions/` (global) — no configuration needed.
 
-```typescript
+```ts
 import { z, type ExtensionAPI, type AgentTool, type ToolContext } from "@globant/coda-core";
 
 export default function activate(api: ExtensionAPI): void {
@@ -41,16 +41,16 @@ Extensions are auto-discovered, highest priority first:
 | --- | --- | --- |
 | 1 | `.coda/extensions/*.ts` | Project-level (highest) |
 | 2 | `~/.coda/extensions/*.ts` | User-global |
-| 3 | `config.json` → `extensions[]` | Configured paths |
-| 4 | `-e ./path.ts` | CLI flag |
+| 3 | `config.json` → `extensions[]`, including any `-e ./path.ts` values merged by the CLI | Configured or one-run paths |
+| 4 | Enabled plugin extension directories | Plugin-provided |
 
-Subdirectory extensions are also discovered. For a folder, CODA resolves the entry file in this order: `package.json` `coda.extensions` → `package.json` `main` → `main.ts` → `<folder-name>.ts` → `index.ts` / `index.js`. To see what's loaded, run `/extensions` inside CODA.
+Duplicate resolved paths are loaded once, preserving the first source in this order. Within the combined `extensions[]` list, configured paths appear before `-e` paths. Subdirectory extensions are also discovered. For a folder, CODA resolves the entry file in this order: `package.json` `coda.extensions` → `package.json` `main` → `main.ts` → `<folder-name>.ts` → `index.ts` / `index.js`. To see what's loaded, run `/extensions` inside CODA.
 
 ## Registering a tool
 
 Tools are functions the agent can call. Use Zod for the parameter schema.
 
-```typescript
+```ts
 const myTool: AgentTool<MyParams, string> = {
   name: "my_tool",
   description: "Clear description of what the tool does and when to use it",
@@ -88,7 +88,7 @@ Inside `execute`, the `ToolContext` gives you what you need:
 
 Commands are invoked by the user as `/name args`.
 
-```typescript
+```ts
 api.registerCommand("deploy", {
   description: "Deploy the application to staging or production",
   getArgumentCompletions: (prefix) => {
@@ -136,15 +136,15 @@ The handler context (`ExtensionCommandContext`) lets you drive the session:
 
 ```text
 model, models, clear, compact, exit, help, mcp, providers, settings,
-skills, agents, extensions, plugin, plugins, reload-plugins,
-init, timeline, rewind, checkpoint-status
+skills, agents, extensions, plugin, plugins, reload-plugins, usage,
+permissions, init, timeline, rewind, checkpoint-status
 ```
 
 ## Subscribing to lifecycle hooks
 
 Hooks let you react to (or modify) what CODA does at key moments.
 
-```typescript
+```ts
 api.on("session_start", async ({ sessionId }) => {
   console.error("Session started:", sessionId);
 });
@@ -169,20 +169,15 @@ api.on("context", async (context) => {
 | `tool_result` | `ToolResultEvent` | Modify a tool result |
 | `session_before_compact` | — | Before compaction (return `{ cancel: true }` to cancel) |
 | `session_compact` | — | After compaction completes |
-| `session_before_switch` | `{ sessionId }` | Before switching to a different session |
-| `session_switch` | `{ sessionId }` | After a session switch completes |
 | `session_before_fork` | `{ entryId }` | Before forking from a timeline entry |
 | `session_fork` | `{ sessionId }` | After a fork completes |
-| `session_before_tree` | — | Before the session tree is traversed |
-| `session_tree` | — | After the session tree traversal |
-| `message_start` | `MessageEvent` | When a new message begins streaming |
 | `message_update` | `MessageEvent` | On each incremental message update |
-| `message_end` | `MessageEvent` | When a message finishes streaming |
 | `tool_execution_start` | `ToolExecutionEvent` | When a tool starts executing |
 | `tool_execution_update` | `ToolExecutionEvent` | On tool execution progress update |
 | `tool_execution_end` | `ToolExecutionEvent` | When a tool finishes executing |
-| `resources_discover` | — | When CODA discovers extension resources |
-| `user_bash` | `UserBashEvent` | When the user runs a shell command via the bash tool |
+| `resources_discover` | `{ cwd, reason }` | At session start. Returned resource paths are currently diagnostic only. |
+
+The API type also reserves `session_before_switch`, `session_switch`, `session_before_tree`, `session_tree`, `message_start`, `message_end`, and `user_bash`, but the current CLI/runtime does not emit them. Do not depend on those names until they are wired.
 
 > **`context` hook — important invariant:** The `context` payload also contains a `messageIds` field — a parallel array to `messages` where `messageIds[i]` is the DB row id for `messages[i]` (or `null` for synthetic messages). The invariant `messages.length === messageIds.length` is load-bearing. If your hook appends, inserts, or reorders `payload.messages`, you **must** apply the same operation to `payload.messageIds`, pushing `null` for synthetic entries.
 
@@ -190,23 +185,25 @@ The `input` hook returns one of three actions to control the message: `{ action:
 
 ## Intercepting tool calls
 
-Use the `tool_call` hook to block dangerous commands or rewrite inputs before they run:
+Use the `tool_call` hook to return an authorization decision or rewrite the input before policy is evaluated:
 
-```typescript
+```ts
 api.on("tool_call", async ({ toolName, input }) => {
-  if (toolName === "bash" && input.command?.includes("rm -rf /")) {
-    return { deny: true, reason: "Blocked destructive command" };
+  if (toolName === "bash" && input.command?.startsWith("deploy ")) {
+    return { decision: "ask", reason: "Confirm deployment command" };
   }
 });
 ```
 
-The hook can return `{ deny: true, reason }` to cancel the call with an error, or `{ block: true, reason }` to pause it and wait for explicit user approval before proceeding. Returning nothing (or `undefined`) lets the call proceed normally.
+Return `decision: "allow"`, `"ask"`, or `"deny"`, with an optional `reason`. You can also return `updatedInput`; CODA sends that rewritten input back through the authorization engine before execution. Returning nothing lets normal policy decide.
+
+> **Migrating an older extension:** legacy `{ deny: true }` and `{ block: true }` responses are still accepted, but both now mean `deny`. If you previously used `{ block: true }` to ask the user, return `{ decision: "ask" }` instead.
 
 ## Registering shortcuts, providers, and flags
 
 Beyond tools, commands, and hooks, an extension can register a few other surfaces (all optional):
 
-```typescript
+```ts
 // A keyboard shortcut (CLI only). Pick a key that isn't reserved (see below).
 api.registerShortcut?.("ctrl+k", {
   description: "Run my action",
@@ -237,20 +234,20 @@ api.registerMessageRenderer?.("my-custom-type", (entry) => {
 });
 ```
 
-**Reserved shortcuts** — extensions can't override these: `escape`, `ctrl+b`, `ctrl+c`, `ctrl+g`, `ctrl+l`, `ctrl+o`, `ctrl+u`, `ctrl+d`, `ctrl+up`, `ctrl+down`, `ctrl+j`, `ctrl+shift+c`.
+**Reserved shortcuts** — extensions can't override these: `escape`, `ctrl+b`, `ctrl+c`, `ctrl+g`, `ctrl+l`, `ctrl+o`, `ctrl+u`, `ctrl+d`, `ctrl+up`, `ctrl+down`, `ctrl+j`, `ctrl+p`, `ctrl+shift+c`. `Ctrl+Up` / `Ctrl+Down` scroll the transcript; `Ctrl+U` / `Ctrl+D` remain reserved for conventional input behavior rather than scrolling.
 
 ## Loading, testing, and reloading
 
 - **Drop-in load.** Save your `.ts` file under `.coda/extensions/` (project) or `~/.coda/extensions/` (global) and CODA picks it up on the next launch — no registration step.
 - **Verify it loaded.** Run `/extensions list` inside CODA to confirm your extension is active and see the tools and commands it registered; `/extensions guide` prints API help.
-- **Iterate quickly.** If your extension is bundled with plugins, `/reload-plugins` re-reads them after you change the files on disk. Otherwise, relaunch CODA to reload a standalone extension file.
+- **Iterate quickly.** If your extension is bundled with a plugin, `/reload-plugins` starts a fresh session with plugins reloaded. Restart the CLI after changing a standalone extension file.
 - **Try one for a single run.** Pass `-e ./path/to/extension.ts` on the command line to load an extra extension just for that session — useful while developing.
 
 ## Tips for good extensions
 
 - **Write tool descriptions for the model, not the user.** Lead with a CAPS category, say *when* to pick this tool over alternatives, and include a short parameter example. CODA chooses tools from these descriptions.
 - **Respect cancellation.** Honor `context.signal` in long-running tool work so **Esc** can interrupt cleanly.
-- **Ask before doing harm.** Route risky actions through `context.hitl` so they go through the same approval flow as built-in tools.
+- **Let policy own general tool safety.** Extension tools pass through the same authorization engine as built-ins. Use a `tool_call` decision for policy-like `ask` or `deny` behavior. Use `context.hitl.requestAnswer(...)` when the tool genuinely needs a user choice—such as selecting a deployment target—and `context.hitl.requestApproval(...)` only for a separate, tool-specific confirmation that policy cannot express.
 - **Use `context.operations`** for file and shell access instead of importing Node APIs directly — it's the supported, sandbox-aware path.
 
 ## See also

package/assets/docs/faq.md

@@ -61,11 +61,11 @@ Use `coda --lastsession` to resume the most recent session. For a specific sessi
 
 ### What does the context percentage in the status bar mean?
 
-It shows how full the current conversation context is. When it approaches 100%, CODA automatically compacts the session history. If you're seeing degraded quality near 100%, run `/compact` manually or start a `/new` session.
+It shows how full the current conversation context is. CODA starts automatic reduction before the window is exhausted: stale tool output can move aside first, and older history is summarized at the configured threshold. If quality feels degraded, run `/compact` manually or start a `/new` session.
 
 ### CODA seems to have "forgotten" something from earlier in the session. Why?
 
-Automatic compaction condenses older messages into a summary to keep the session running. If you need full history for debugging, open `/settings` → **Context Compaction** to disable it or adjust when it kicks in.
+Automatic reduction may move stale tool output out of the active context and condense older messages into a summary. The original transcript remains stored, but the model works from the reduced view. If you need a less aggressive model-visible context while debugging, open `/settings` → **Context Compaction** to disable automatic reduction or adjust the threshold.
 
 ## Making changes
 
@@ -77,7 +77,7 @@ Type `/timeline` (or `/rewind`, or press **Esc** twice) to see all snapshots fro
 
 CODA runs an **authorization engine** that decides `allow` / `ask` / `deny` for every tool call. Two levers control it:
 
-- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). Set the default in `/settings` or per project in `.coda/config.json` via `permissions.defaultMode`.
+- **Permission mode** — press `Ctrl+P` to cycle the session's mode: **read-only** (only reads run; writes and commands are refused), **default** (reads run, risky actions like `git commit` ask first, destructive ones are denied unless you add an allow rule), and **auto** (risky actions auto-run for unattended/CI use; only catastrophic ones stay blocked). Set your default in `~/.coda/config.json` via `permissions.defaultMode`; a project config can tighten but cannot raise it.
 - **Rules** — to always allow or always block a specific command, add `allow` / `ask` / `deny` rules under `permissions` in `config.json` (e.g. `allow Bash(git status)` or `deny Bash(rm:*)`). **Deny always wins**, and a handful of catastrophic actions (`rm -rf /`, `sudo`, a fork bomb) sit behind an un-relaxable floor that no allow rule can override.
 
 The legacy `bash.autoApproveLevel` ("safe"→"high") was replaced by this model; a stored `high` migrates to `auto`.
@@ -100,7 +100,7 @@ Some editors capture `Ctrl+P` before CODA sees it. On **Windows/Linux**, VS Code
 
 ### What is AGENTS.md and should I have one?
 
-It's optional, but recommended — especially for shared projects. It's a Markdown file at your project root that CODA reads at the start of every session, where you document your coding conventions, how to run tests, what files not to touch, etc. Generate one with `/init` (or write it by hand), customize it, and commit it to Git so the whole team benefits.
+It's optional, but recommended — especially for shared projects. Put `AGENTS.md` in the directory where you launch CODA to document coding conventions, test commands, and files not to touch. CODA also accepts `AGENT.md` or `CLAUDE.md` as fallback names. Generate `AGENTS.md` with `/init` (or write it by hand), customize it, and commit it so the whole team benefits.
 
 ## Extensions and tools
 
@@ -130,7 +130,7 @@ Open `/workflows` and press **`c`** on a running entry, or run `/workflows stop
 
 ### How do I install a plugin or browse the marketplace?
 
-From inside CODA, open the `/plugin` manager to install, enable, disable, and browse the marketplace. From your terminal, `coda plugin install <source>` works too, where `<source>` is an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. CODA is compatible with the Claude Code plugin ecosystem. To browse a marketplace catalog, first register one with `coda marketplace install <source>`; then `/plugin` lists available plugins from that catalog. See [Extend CODA](#guide-extend).
+From inside CODA, open the `/plugin` manager to install, enable, disable, and browse the marketplace. From your terminal, `coda plugin install <source>` works too, where `<source>` is an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. CODA recognizes native CODA plugins plus Claude Code, Cursor, and portable Agent Plugins layouts. To browse a marketplace catalog, first register one with `coda marketplace install <source>`; then `/plugin` lists available plugins from that catalog. See [Extend CODA](#guide-extend).
 
 ## Models and cost
 
@@ -147,6 +147,16 @@ CODA re-checks your configured model against the provider's live catalog at star
 
 To opt out and always be asked, set `"strictPin": true` on the profile (see [Configuration Reference](#config-reference) › "activeProfile and profiles" and "modelResilience"). On a provider without a live catalog (e.g. local Ollama), CODA trusts your id and shows a clear switch-model message if it turns out to be unavailable.
 
+### How do I set the reasoning (thinking) effort for a single headless run?
+
+Pass `coda --reasoning-effort <level>` (`none|minimal|low|medium|high|xhigh|max`, case-insensitive) alongside your headless prompt:
+
+```bash
+coda -p "explain this repo" --reasoning-effort high
+```
+
+The level is applied **in memory for that run only** — it is never written to `~/.coda/config.json`, and it overrides any persisted `reasoning.effort` just for that invocation. Because nothing is written to disk, you can launch several headless runs **concurrently with different efforts** and they won't race on a shared config file (the reason the flag exists). Subagents spawned during the run inherit the same effort. An invalid value fails fast; a level the active model can't honor prints a stderr warning and runs without applying it (no silent fallback). Interactively, use `/effort` instead. See [Configuration Reference](#config-reference) for the persisted reasoning settings and supported levels.
+
 ### Where do I see token usage and cost?
 
 The TUI status bar shows the context fill percentage and running token/cost figures for the session, so you can keep an eye on how much a long session is consuming.
@@ -159,7 +169,7 @@ Everything lives under `~/.coda/` — `config.json`, `.secrets`, the session dat
 
 ### How do I view or share logs safely?
 
-Run `coda logs` for the viewer (filter by `--level`, `--service`, `--since`, or `--follow`). To share with support, `coda logs export` writes a redacted, path-scrubbed bundle to `~/.coda/exports/` — nothing is ever uploaded. Secrets are scrubbed before anything hits disk. See [View & Share Logs](#logging).
+Run `coda logs` for the viewer (filter by `--level`, `--service`, `--since`, or `--follow`). To share with support, `coda logs export` writes a redacted, path-scrubbed bundle to `~/.coda/exports/` — nothing is ever uploaded. Review it, then attach it to your request or email **coda-tech-support@globant.com**. Secrets are scrubbed before anything hits disk. See [View & Share Logs](#logging).
 
 ### Can I use checkpoints in CI?
 
@@ -167,7 +177,7 @@ Not for rollback — the `/timeline` picker is a TUI feature. In headless mode c
 
 ### How does CODA behave in a monorepo?
 
-It loads exactly one `AGENTS.md` — the one in the directory you launch it from. There's no upward walk or merging. Launch from the package you're working in (`cd packages/billing && coda`). See [Collaborate with Your Team](#guide-collaborate).
+At startup, CODA loads an optional global instruction file plus one instruction file from the directory where you launch it (`AGENTS.md`, then `AGENT.md`, then `CLAUDE.md`). It does not inherit parent-directory instructions at startup. When it reads files deeper in the tree, it can attach more-specific instructions from those subdirectories. Launch from the package you're working in (`cd packages/billing && coda`) when that package's rules should be the root conventions. See [Collaborate with Your Team](#guide-collaborate).
 
 ## See also
 

package/assets/docs/glossary.md

@@ -4,18 +4,18 @@ Quick definitions for terms used throughout the docs.
 
 | Term | Definition |
 | --- | --- |
-| **AGENTS.md** | A Markdown file at your project root that CODA reads at the start of every session. Use it to document your project's conventions, quality gates, and constraints for the agent. |
+| **AGENTS.md** | The preferred instruction filename for project conventions, quality gates, and constraints. CODA loads it from the launch directory at startup and can attach more-specific instruction files when reading deeper paths. `AGENT.md` and `CLAUDE.md` are fallback names. |
 | **Agent** | In CODA, an agent is a Markdown-defined profile that describes a specialist persona. CODA can delegate subtasks to agents, running them in parallel for complex work. |
 | **Batch mode** | Headless, non-interactive mode. Run with `coda -p "prompt"`. No TUI, no multi-turn conversation — use in scripts and CI. |
 | **Checkpoint** | A file snapshot taken before each turn — the state from before CODA acts on the message you just sent. Restored via `/timeline` or `/rewind`; your project's Git history is untouched. |
 | **CLI** | The `coda` command-line tool. It runs in two modes: interactive (the TUI) and headless (batch). |
 | **coda-help** | A built-in agent that answers questions about how to use CODA by searching the local user guide. CODA delegates to it automatically when you ask about itself. |
-| **Compaction** | Automatic condensing of older conversation history to free up context window space. Triggered at a configurable fill threshold. |
+| **Compaction** | Context reduction for long sessions. CODA either stores the current context directly or reduces it by moving stale tool output aside and, at the configured threshold, condensing older messages into a summary. |
 | **Extension** | A TypeScript module that registers custom tools, slash commands, or lifecycle hooks into CODA. |
 | **Glob.AI OS** | Globant's internal AI gateway — the primary provider for CODA at Globant. |
 | **MCP** | Model Context Protocol. A standard for connecting AI models to external tools and services. CODA uses MCP servers to talk to GitHub, databases, CI systems, and other integrations. |
 | **MEMORY.md** | Durable notes the agent keeps across sessions — preferences, decisions, and gotchas it learns. Unlike AGENTS.md (which you write), CODA maintains this itself, and it survives checkpoint rollbacks. |
-| **Plugin** | A versioned, installable package that can bundle skills, agents, extensions, and MCP fragments. More structured than an extension; installable via `coda plugin install`. |
+| **Plugin** | A versioned, installable package that can bundle skills, agents, extensions, MCP fragments, and lifecycle hooks. More structured than an extension; installable via `coda plugin install`. |
 | **Provider** | The AI backend CODA sends prompts to — for example a Glob.AI OS instance, a local Ollama server, or any OpenAI-compatible endpoint. Managed with `/providers`. |
 | **Session** | A persistent CODA conversation. Stored on disk; resumable at any time. |
 | **Skill** | A Markdown file that encodes a repeatable workflow. Invoked with a slash command like `/skill-name`. |
@@ -37,7 +37,7 @@ Quick definitions for terms used throughout the docs.
 | **`propose_policy`** | The built-in tool CODA uses to suggest a permanent permission change (add rule, remove rule, or change mode) for you to approve. Triggered when you ask in plain English (e.g. "allow pnpm build") or after a denial. On by default; a *widening* change always needs your explicit approval. Disable with `permissions.proposePolicy: false`, `CODA_PROPOSE_POLICY`, or the admin `disableProposePolicy`. |
 | **Managed policy** | An organization-level policy set by an administrator that overrides and locks certain permission settings in your personal and project configs (e.g. forbidding `auto` mode, restricting MCP servers). A managed `deny` is final. |
 | **Headless mode** | See *Batch mode*. |
-| **Marketplace** | The catalog of installable plugins, reachable from the `/plugin` manager; Claude Code-ecosystem compatible. |
+| **Marketplace** | A catalog of installable plugins, reachable from the `/plugin` manager. CODA recognizes native, Claude Code, Cursor, and portable Agent Plugins layouts. |
 | **Redaction** | The always-on scrubbing of secret-looking keys and values from logs before they're written to disk. |
 | **ripgrep / fastgrep** | The two content-search backends behind the `grep` tool. ripgrep ships bundled and is the default. |
 | **Shadow repository** | The private Git repo where checkpoints are stored, separate from your project's own `.git`. Located at `~/.coda/checkpoints/<hash>/` by default (one per project, keyed by a SHA-256 of the project path). The base directory can be relocated via `CODA_HOME`. |

package/assets/docs/guide-changes.md

@@ -10,11 +10,11 @@ In addition to per-turn snapshots, CODA automatically takes an extra snapshot la
 
 For how checkpoints work in detail — the shadow repo, Git requirements, and how restoring rewinds the conversation — see [Sessions & Checkpoints](#sessions).
 
-## Approve commands as they run
+## Approve actions when CODA asks
 
-When CODA wants to run a shell command, it shows you what it's about to execute and waits for your approval — press **Y** to allow it or **N** to skip it. By default, CODA auto-approves low-risk commands (like `git status` or `cat`) and asks before anything that writes or deletes files.
+Every tool call goes through the authorization engine. It combines your **permission mode** with `allow` / `ask` / `deny` rules and the built-in safety floor. An `allow` decision runs immediately, `deny` does not run, and `ask` opens the approval prompt — press **Y** for this action, **A** for the displayed reusable session rule when offered, or **N** to deny it. Use **Arrow keys + Enter** to select another offered option; a permanent project rule always gets a second confirmation.
 
-How much runs without asking depends on your **permission mode**, which you cycle with **Ctrl+P** or set via `permissions.defaultMode`:
+How much runs without asking depends on your permission mode, which you cycle with **Ctrl+P** or set via `permissions.defaultMode`:
 
 | Mode | What it allows |
 | --- | --- |
@@ -88,7 +88,7 @@ If your project has an `AGENTS.md` with a "quality gate" section, CODA follows i
 ## A quick mental model for staying in control
 
 1. **Checkpoint** — every turn is snapshotted before it runs, so you can always go back.
-2. **Approve** — risky shell commands and unread-file overwrites pause for your **Y**/**N**.
+2. **Authorize** — rules and the current mode decide each tool call; only `ask` decisions pause for you.
 3. **Interrupt** — **Esc** stops a turn the instant it heads the wrong way.
 4. **Steer or queue** — react without stopping the turn (`/settings` → **Composer**).
 5. **Undo** — `/timeline` (or **Esc Esc**) rewinds files *and* the conversation to a chosen point.

package/assets/docs/guide-collaborate.md

@@ -6,7 +6,7 @@ CODA works best when the whole team uses it consistently. This guide covers how
 
 `AGENTS.md` is the most important file for team collaboration. CODA reads it at the start of every session and uses it to understand your project's conventions — coding style, testing approach, which areas to avoid, how to run the quality checks.
 
-CODA looks for it at your project root (`<project>/AGENTS.md`) first, and falls back to `<project>/.coda/AGENTS.md` if the root file isn't present. Put it at the root for visibility, or under `.coda/` if you prefer to keep it out of the top level.
+CODA looks for an instruction file in the directory where you launch it, preferring `AGENTS.md`, then `AGENT.md`, then `CLAUDE.md`. Put project instructions at that root for visibility. A legacy `<project>/.coda/AGENTS.md` is no longer loaded; move it to the project root.
 
 Create or update it with `/init` and then edit it to add what CODA missed. A typical `AGENTS.md` looks like this:
 
@@ -64,13 +64,13 @@ The most valuable things to share live in the repo and apply to everyone who clo
 A project-level `<project>/.coda/config.json` is also **safe to commit** — it never holds secrets (those live in `~/.coda/.secrets`, which is never committed). But be selective about what you put there:
 
 - **Don't commit the active provider.** Which provider you use (a specific Glob.AI OS instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
-- **Think twice before committing an elevated permission mode.** Setting `permissions.defaultMode: "auto"` in the project's `.coda/config.json` means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.
+- **Use project permission modes to tighten, not widen.** A project `.coda/config.json` can start sessions in a more restrictive mode, but CODA ignores attempts to raise autonomy above each developer's user-level default. Share explicit rules only when the team agrees on them.
 
 In short: share **conventions and workflows**, keep **personal and security preferences** local.
 
 ## Working in a monorepo
 
-CODA loads exactly one `AGENTS.md` — the one in the directory where you launch it. **For `AGENTS.md` specifically**, there is no upward directory walk and no merging of parent files. (Agent definitions and workflow modules _do_ walk upward to parent directories, so placing them closer to the repo root makes them available to nested package launches automatically.)
+At startup, CODA loads your optional global instruction file from `~/.coda/` and one instruction file from the directory where you launch it, using the `AGENTS.md` → `AGENT.md` → `CLAUDE.md` fallback order. It does not merge instruction files from parent directories at startup. When CODA later reads a file below that root, it can attach more-specific instruction files found between that file and the launch directory. Agent definitions and workflow modules use their own upward discovery rules.
 
 In a monorepo, launch CODA from the package directory you're working in:
 
@@ -79,7 +79,7 @@ cd packages/billing
 coda   # loads packages/billing/AGENTS.md
 ```
 
-Put conventions that apply everywhere in each package's `AGENTS.md`, or maintain a root-level one and symlink it into each package.
+Put package-specific conventions in each package's `AGENTS.md`. For repository-wide conventions, launch from the repository root or make the shared rules available from the package launch directory; CODA does not automatically inherit a parent root file at startup.
 
 ## Share agents and workflows too
 

package/assets/docs/guide-extend.md

@@ -27,9 +27,9 @@ Everything happens from inside CODA through the `/mcp` manager:
 /mcp
 ```
 
-From there you can **add a server** (paste its JSON or import it from a file), edit the global or project `mcp.json`, list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — no need to hand-edit files outside the app.
+From there you can **add a server** (paste its JSON or import it from a file), edit the global or project `mcp.json`, list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — no need to hand-edit files outside the app. You can also ask CODA to configure one from a package, command, repository, or URL; see [Configure an MCP Server](#add-mcp-server-skill).
 
-**Where MCP servers are defined.** Servers live in `mcp.json` files that layer like the rest of your config: `~/.coda/mcp.json` (global) and `<project>/.coda/mcp.json` (project). A third, session-level file at `~/.coda/sessions/<sessionId>/mcp.json` holds per-session overrides — including a disable-only shorthand `{ "disabled": true }` to switch a higher-tier server off for one session. Each server entry is either **stdio** (`command` plus optional `args`/`env`) or **HTTP** (`url`, optional `headers`/token); add `"disabled": true` to any entry to keep it but turn it off. (CODA builds the live server map from `mcp.json` + plugins + `--mcp-config`, so prefer `mcp.json` over the `mcp.servers` block in `config.json`.)
+**Where MCP servers are defined.** Servers live in `mcp.json` files that layer like the rest of your config: `~/.coda/mcp.json` (global) and `<project>/.coda/mcp.json` (project). A third, session-level file at `~/.coda/sessions/<sessionId>/mcp.json` holds per-session overrides — including a disable-only shorthand `{ "disabled": true }` to switch a higher-tier server off for one session. Each project/global server entry is either **stdio** (`command` plus optional `args`/`env`) or **HTTP** (`url`, optional `headers`/token). Use the `/mcp` manager to enable or disable it for the current session. CODA builds the live server map from `mcp.json` + plugins + `--mcp-config`, so prefer `mcp.json` over the `mcp.servers` block in `config.json`.
 
 Once a server is connected, CODA can use its tools automatically — you just describe what you want in plain language. For example, with a **GitHub MCP server** connected, you could ask:
 
@@ -88,7 +88,7 @@ Ready to build one? The easiest way is to ask CODA — its `create-extension` sk
 
 ## Share packaged integrations with plugins
 
-Plugins are versioned, installable packages — like extensions, but with a manifest, version number, and the ability to bundle skills, agents, and MCP fragments together. Use plugins when you want to share a reusable CODA integration across teams or projects.
+Plugins are versioned, installable packages — like extensions, but with a manifest, version number, and the ability to bundle skills, agents, extensions, MCP fragments, and lifecycle hooks together. Use plugins when you want to share a reusable CODA integration across teams or projects.
 
 Manage plugins from inside CODA with the `/plugin` manager — enable, disable, and browse any registered marketplace catalog. The `/plugin install` slash command accepts **only absolute local paths** to a plugin directory; for npm packages, Git URLs, or marketplace-sourced plugins, use `coda plugin install <source>` from the terminal:
 
@@ -102,7 +102,7 @@ You can also install from your terminal:
 coda plugin install <source> [--name <folder>] [--scope global|project]
 ```
 
-`<source>` can be an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. `--name` selects a subdirectory (useful for monorepo git sources); `--scope` chooses `global` (default) or `project` install scope.
+`<source>` can be an npm package (prefix `npm:`), a Git/HTTPS URL, a local directory path, a `.zip` archive, or a `file://…` URL. `--name` selects a subdirectory (useful for monorepo git sources); `--scope` chooses `global` (default) or `project` install scope. After installing, enabling, or disabling a plugin, run `/reload-plugins`. It starts a fresh session with plugins reloaded.
 
 ### Adding a marketplace
 
@@ -113,7 +113,7 @@ A marketplace is a catalog of plugins. Add one from the terminal with `coda mark
 - a **local folder** containing a `marketplace.json` (Claude-style `.claude-plugin/` or `.coda-plugin/` layouts are recognized);
 - a **local `.zip`** archive — CODA unpacks it and finds the catalog inside, including the single nested top-level folder you get from a GitHub "Download ZIP" / "Source code" archive.
 
-CODA is compatible with the Claude Code plugin and marketplace ecosystem, so catalogs published for Claude Code work here.
+CODA recognizes native CODA plugins plus Claude Code, Cursor, and portable Agent Plugins layouts. Features outside CODA's supported component set may be ignored, so review the detected plugin details before enabling it.
 
 ## Orchestrate multiple agents with workflows
 

package/assets/docs/hooks.md

@@ -10,7 +10,7 @@ The hook system is **compatible with Claude Code hooks**: the same JSON input/ou
 
 Add a `hooks` key to `~/.coda/config.json` (global) or `.coda/config.json` (project):
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -186,15 +186,18 @@ The `matcher` field filters which tool names (or session sources) trigger the ho
 
 Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (HTTP hooks). All events include these base fields:
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
-  "hook_event_name": "PreToolUse"
+  "hook_event_name": "PreToolUse",
+  "cli_version": "0.4.2"
 }
 ```
 
+`cli_version` is the running Coda version — the value `coda --version` prints — so a hook can attribute what it observes to the exact version that produced it. Command hooks also receive it as the `CODA_VERSION` environment variable (see [Environment variables available to hooks](#environment-variables-available-to-hooks)), which is cheaper than parsing stdin in hot-path hooks.
+
 ### Tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`)
 
 ```jsonc
@@ -203,7 +206,8 @@ Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (H
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
+  "cli_version": "0.4.2",
+  "tool_name": "bash",
   "tool_input": { "command": "git status", "description": "Check git status" },
   "tool_use_id": "toolu_01XYZ",
   // PostToolUse only:
@@ -215,36 +219,39 @@ Coda sends a JSON object on **stdin** (command hooks) or as the **POST body** (H
 
 ### `UserPromptSubmit`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "UserPromptSubmit",
+  "cli_version": "0.4.2",
   "prompt": "Refactor the auth module"
 }
 ```
 
 ### `SessionStart`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "SessionStart",
+  "cli_version": "0.4.2",
   "source": "startup"
 }
 ```
 
 ### `Stop`
 
-```jsonc
+```json
 {
   "session_id": "abc123",
   "transcript_path": "",
   "cwd": "/home/user/my-project",
   "hook_event_name": "Stop",
+  "cli_version": "0.4.2",
   "stop_reason": "turn_complete"
 }
 ```
@@ -385,7 +392,7 @@ rule ::= toolName | toolName(content)
 | File glob | `"Edit(src/*.ts)"` | TypeScript files under `src/` |
 | Prefix (legacy) | `"Bash(npm:*)"` | `npm`, `npm install`, `npm run …` |
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -444,29 +451,17 @@ Plugins can ship a `hooks/hooks.json` file at the plugin root. The format is ide
 
 ## 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)
+The hook runtime can give `SessionStart` hooks a writable `CODA_ENV_FILE`, and embedders can use the session-environment API to prepend those exports to later Bash commands. The current CODA CLI does **not** connect that optional callback to its Bash tool, so these files do not currently change later CLI commands. Treat this as an embedding API rather than a CLI feature.
 
-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:
+A `SessionStart` hook may still write the file for a host that supports it:
 
 ```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"
+echo "export VIRTUAL_ENV=$PWD/.venv" >> "$CODA_ENV_FILE"
 ```
 
+Do not rely on this for the standard CLI today; configure the environment before launching CODA instead.
+
 ---
 
 ## Async hooks
@@ -475,9 +470,9 @@ By default hooks run **synchronously** — the lifecycle event waits for every m
 
 ### `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).
+The hook runs in the background. Results are polled at the start of each turn. Completed `additionalContext` is injected into the conversation as an `[Async hook]` user message before that turn proceeds.
 
-```jsonc
+```json
 {
   "type": "command",
   "command": ".coda/hooks/slow-analysis.sh",
@@ -490,7 +485,7 @@ The hook runs in the background. Results are polled at the start of each turn an
 
 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
+```json
 {
   "type": "command",
   "command": ".coda/hooks/file-integrity-watcher.sh",
@@ -508,7 +503,7 @@ A hook can decide at runtime to go async by printing `{"async": true}` as its fi
 
 Set `disableAllHooks: true` in `config.json` to disable all hooks globally. Useful in CI environments or when debugging unexpected behavior:
 
-```jsonc
+```json
 {
   "disableAllHooks": true
 }
@@ -531,8 +526,9 @@ Set `disableAllHooks: true` in `config.json` to disable all hooks globally. Usef
 | Variable | Value |
 | --- | --- |
 | `CODA_PROJECT_DIR` | Current project directory |
+| `CODA_VERSION` | The running Coda version (what `coda --version` prints) — same value as the `cli_version` payload field. Set by Coda and authoritative: it overrides any `CODA_VERSION` you exported, and is absent (not empty) when the running version is unknown |
 | `CODA_PLUGIN_ROOT` | Plugin installation directory (plugin hooks only) |
-| `CODA_ENV_FILE` | Writable env file path (SessionStart hooks only, bash/wsl) |
+| `CODA_ENV_FILE` | Writable env file path for `SessionStart` hooks. It affects later Bash calls only in an embedding that wires session-environment support; the standard CLI currently does not. |
 
 All other environment variables from the Coda process are also inherited.
 
@@ -561,7 +557,7 @@ All other environment variables from the Coda process are also inherited.
 
 ### Block `git push` in a project
 
-```jsonc
+```json
 {
   "hooks": {
     "PreToolUse": [
@@ -602,7 +598,7 @@ All other environment variables from the Coda process are also inherited.
 
 ### Log every session to a file
 
-```jsonc
+```json
 {
   "hooks": {
     "SessionStart": [
@@ -642,38 +638,6 @@ All other environment variables from the Coda process are also inherited.
 }
 ```
 
-### 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**
@@ -698,7 +662,7 @@ fi
 
 ## 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
+- [Configuration](#configuration) — where `config.json` files live and how they merge.
+- [Extend CODA](#guide-extend) — plugins, extensions, agents, skills, and MCP.
+- [Writing Extensions](#extensions) — programmatic lifecycle hooks and tool interception.
+- [Tools Reference](#tools-reference) — built-in tool names used in matcher patterns.