@nathapp/nax 0.83.0 → 0.83.2

package/CHANGELOG.md

@@ -12,6 +12,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking
 
+- **nax now requires explicit folder trust before it runs repository-controlled code.** A gated command
+  (`nax run`, `nax plan`, `nax mcp lock`, …) in an untrusted project exits 2 with
+  `Project not trusted: <root>` / `run: nax trust add <root>` instead of proceeding. nax loads project
+  plugins, context plugin providers, hooks, MCP servers and the quality / test / acceptance / setup
+  commands from the repository and runs them unsandboxed on your machine; nothing recorded trust before,
+  so an upgrade refuses everything until you grant it. Existing projects need one command:
+  `nax trust add "$PWD"`, which prompts on a terminal and writes
+  `~/.nax/trust.json` (or `$NAX_GLOBAL_CONFIG_DIR/trust.json`). Trust is hierarchical — an entry for a
+  folder covers every folder beneath it, so trusting a parent also covers the clones, worktrees and new
+  projects you create under it later. `/` and your home directory are refused unless you pass `--force`.
+  Manage the store with `nax trust list`, `nax trust add`, `nax trust rm` and `nax trust check`
+  (`--json` on `list`/`check`); see the [CLI reference](docs/guides/cli-reference.md#nax-trust).
+  **In CI**, grant trust once at the start of the job — `--yes` skips the prompt and requires no TTY, and
+  the same command is a no-op (exit 0) on a cache that already covers the path:
+
+  ```bash
+  nax trust add "$PWD" --yes
+  ```
+
 - `autoMode.defaultAgent`, `autoMode.fallbackOrder`, and `context.v2.fallback` config fields removed. Use `agent.default` and `agent.fallback.map` instead (ADR-012 Phase 6). Loading a config containing any of these keys throws `NaxError CONFIG_LEGACY_AGENT_KEYS` with a per-key migration pointer.
 - **BREAKING (custom permission profiles only):** the agent's file-tool containment root moved from the
   story's package directory to the repo root (single-frame redesign). A custom `scoped` permission

package/README.md

@@ -102,6 +102,7 @@ See [docs/](docs/) for full guides on configuration, test strategies, monorepo s
 | [`nax agents`](docs/guides/cli-reference.md#nax-agents) | List available coding agents |
 | `nax auth` | Manage provider credentials for the native agent (`login`, `import`, `list`, `rm`) |
 | [`nax approvals`](docs/guides/cli-reference.md#nax-approvals-list) | List or revoke remembered command approvals (`list`, `rm`) |
+| [`nax trust`](docs/guides/cli-reference.md#nax-trust) | Trust or untrust project folders (`list`, `add`, `rm`, `check`) |
 | `nax mcp lock` | Pin configured MCP servers' tool surface to `.nax/mcp-lock.json` |
 | [`nax config`](docs/guides/cli-reference.md#nax-config) | Display the effective merged config (`--explain`, `--diff`); `nax config profile` manages config profiles |
 | [`nax curator`](docs/guides/cli-reference.md#nax-curator-status) | Inspect, commit, or garbage-collect curator proposals |
@@ -184,6 +185,20 @@ See [Sandbox & Command Safety](docs/guides/sandbox-and-command-safety.md), [Appr
 
 ## Key Concepts
 
+### Project trust
+
+nax runs repository-controlled code — project plugins, context plugin providers, hooks, MCP servers and the quality / test / acceptance / setup commands — unsandboxed on the host. Before a gated command (`nax run`, `nax plan`, `nax mcp lock`, …) acts on a project, that project's folder must be trusted, and a refusal exits 2 with `run: nax trust add <root>`.
+
+```bash
+nax trust add "$PWD"          # trust this checkout (asks for confirmation)
+nax trust list                # what is trusted, and which entry covers the cwd
+nax trust check --json        # machine-readable answer for a script
+```
+
+Trust is hierarchical and stored once per machine (`~/.nax/trust.json`): an entry for a folder covers that folder and **every folder beneath it**, so trusting a parent covers the clones, worktrees and new projects you create under it later — you do not re-grant trust per checkout. Trusting `/` or your home directory would cover everything you own and is refused unless you pass `--force`. In CI, grant trust once at the top of the job with `nax trust add "$PWD" --yes`, which is a no-op (exit 0) on a cache that already covers the path.
+
+See [`nax trust`](docs/guides/cli-reference.md#nax-trust) for the full surface.
+
 ### Test Strategies
 
 nax supports five test strategies. When `tdd.strategy` is `"auto"` (default), the planner selects the strategy per story based on complexity and content — security-critical stories always get `three-session-tdd` regardless of complexity.