@codai/axiom-mcp 1.0.24 → 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,423 +1,175 @@
-# @codai/axiom-mcp
-
-**AXIOM Model Context Protocol Server** - Generate artifacts, validate policies, and apply manifests directly from AI conversations.
-
-[![npm version](https://img.shields.io/npm/v/@codai/axiom-mcp.svg)](https://www.npmjs.com/package/@codai/axiom-mcp)
-[![License](https://img.shields.io/npm/l/@codai/axiom-mcp.svg)](https://github.com/dragoscv/axiom/blob/main/LICENSE)
-
----
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-npm install -g @codai/axiom-mcp@latest
-```
-
-### VS Code MCP Configuration
-
-Add to your `.vscode/mcp.json` or global MCP config:
-
-```json
-{
-  "mcpServers": {
-    "axiom": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "--package=@codai/axiom-mcp@latest",
-        "axiom-mcp-stdio"
-      ]
-    }
-  }
-}
-```
-
-**Alternative (if installed globally)**:
-```json
-{
-  "mcpServers": {
-    "axiom": {
-      "command": "axiom-mcp-stdio"
-    }
-  }
-}
-```
-
-### Test Server
-
-```bash
-npx @codai/axiom-mcp@latest
-# Output: AXIOM MCP Server running on stdio
-```
-
----
-
-## 📋 Available Tools
-
-### 1. `axiom_parse`
-
-Parse `.axm` source code to Intermediate Representation (IR).
-
-**Input**:
-```typescript
-{
-  source: string  // AXIOM .axm source code
-}
-```
-
-**Output**:
-```typescript
-{
-  ir: IR  // Parsed intermediate representation
-}
-```
-
-**Example**:
-```json
-{
-  "source": "agent \"my-app\" {\n  capability net(\"api\")\n  check sla \"latency\" { expect \"cold_start_ms <= 50\" }\n  emit service \"app\"\n}"
-}
-```
-
----
-
-### 2. `axiom_validate`
-
-Validate IR semantics and constraints.
-
-**Input**:
-```typescript
-{
-  ir: IR  // IR object from axiom_parse
-}
-```
-
-**Output**:
-```typescript
-{
-  valid: boolean,
-  errors?: string[]
-}
-```
-
----
-
-### 3. `axiom_generate`
-
-Generate artifacts and manifest from validated IR.
-
-**Input**:
-```typescript
-{
-  ir: IR,
-  profile?: string  // "edge" | "default" | "budget" (default: "default")
-}
-```
-
-**Output**:
-```typescript
-{
-  manifest: Manifest,  // Complete manifest with artifacts
-  artifacts: Artifact[]  // Generated artifacts (files)
-}
-```
-
-**Features**:
-- ✅ **POSIX paths**: All artifact paths use `/` (cross-platform)
-- ✅ **Deterministic**: Same IR + profile → same manifest SHA256
-- ✅ **Profile-based**: Different cold start thresholds per profile
-
----
-
-### 4. `axiom_check`
-
-Run policy checks on generated manifest.
-
-**Input**:
-```typescript
-{
-  manifest: Manifest,
-  ir?: IR  // Optional for enhanced checking
-}
-```
-
-**Output**:
-```typescript
-{
-  passed: boolean,  // AND over all checks
-  report: {
-    checkName: string,
-    kind: "sla" | "policy",
-    passed: boolean,
-    details: {
-      expression: string,
-      evaluated: true,  // Always true (real evaluation)
-      message: string,
-      measurements: {
-        cold_start_ms: number,
-        frontend_bundle_kb: number,
-        max_dependencies: number,
-        no_pii_in_artifacts: boolean,
-        // ... more metrics
-      }
-    }
-  }[]
-}
-```
-
-**Features**:
-- ✅ **Real evaluation**: Deterministic metrics calculation
-- ✅ **Profile-aware**: Edge (50ms), Default (100ms), Budget (120ms)
-- ✅ **Transparent**: `evaluated:true` confirms real computation
-
----
-
-### 5. `axiom_apply`
-
-Apply manifest to filesystem or create Pull Request.
-
-**Input**:
-```typescript
-{
-  manifest: Manifest,
-  mode: "fs" | "pr",  // "fs" = filesystem, "pr" = pull request
-  repoPath?: string,  // Default: process.cwd()
-  
-  // PR mode only:
-  branchName?: string,
-  commitMessage?: string
-}
-
-// Manifest artifact structure (enhanced v1.0.17):
-interface Artifact {
-  path: string;              // POSIX relative path
-  kind: "file" | "report";
-  sha256: string;            // Content hash for validation
-  bytes: number;
-  
-  // ✨ NEW in 1.0.17: Optional embedded content (store-less operation)
-  contentUtf8?: string;      // UTF-8 text content (for README, configs)
-  contentBase64?: string;    // Base64 binary content (for images, compiled assets)
-}
-```
-
-**Output**:
-```typescript
-{
-  filesWritten: string[],  // POSIX relative paths: "out/webapp/index.html"
-  summary: string
-}
-```
-
-**Features**:
-- ✅ **Versioned Artifact Cache**: `.axiom/cache/v1/<sha256>` (future-proof structure)
-- ✅ **3-Tier Content Fallback** (NEW in 1.0.17):
-  1. `artifact.contentUtf8` → Buffer.from(utf-8) - **Fastest, no store lookup**
-  2. `artifact.contentBase64` → Buffer.from(base64) - **Embedded binary content**
-  3. `artifactStore.get(sha256)` → Cached content - **Fallback for large files**
-  4. Throws `ERR_ARTIFACT_CONTENT_MISSING` if all sources unavailable
-- ✅ **Real Filesystem Writes**: Physical `fs/promises.writeFile()` to `out/` directory
-- ✅ **SHA256 Validation**: Verifies file integrity after write (throws `ERR_SHA256_MISMATCH`)
-- ✅ **Auto-creates `./out/`**: No manual directory setup required
-- ✅ **POSIX Paths**: `filesWritten[]` use `/` on all platforms (guaranteed no backslash)
-- ✅ **Security**: Comprehensive protection:
-  - Blocks absolute paths (`/etc/passwd`)
-  - Blocks path traversal (`../../../sensitive`)
-  - Blocks mid-path traversal (`safe/../evil/hack.txt`)
-  - Validates all paths stay within `out/` directory
-- ✅ **Error Handling**: Clear errors with diagnostic context
-
-**Workflow Integration**:
-1. **Generate**: Creates manifest + optionally embeds small content OR caches by SHA256 in `.axiom/cache/v1/`
-2. **Apply**: 
-   - Tries embedded content first (fast path for README, configs)
-   - Falls back to cache lookup for large artifacts
-   - Writes real files to `out/` with SHA256 validation
-3. **Deterministic**: Identical IR → identical SHA256 → identical files (verified post-write)
-
----
-
-## 🎯 Complete Workflow Example
-
-```json
-// 1. Parse .axm source
-{
-  "tool": "axiom_parse",
-  "input": {
-    "source": "agent \"notes-app\" {\n  capability net(\"firebase\")\n  check sla \"fast\" { expect \"cold_start_ms <= 50\" }\n  emit service \"web\"\n}"
-  }
-}
-
-// 2. Validate IR
-{
-  "tool": "axiom_validate",
-  "input": {
-    "ir": "<IR from step 1>"
-  }
-}
-
-// 3. Generate artifacts (edge profile for performance)
-{
-  "tool": "axiom_generate",
-  "input": {
-    "ir": "<IR from step 1>",
-    "profile": "edge"
-  }
-}
-
-// 4. Check policies
-{
-  "tool": "axiom_check",
-  "input": {
-    "manifest": "<manifest from step 3>",
-    "ir": "<IR from step 1>"
-  }
-}
-
-// 5. Apply to filesystem
-{
-  "tool": "axiom_apply",
-  "input": {
-    "manifest": "<manifest from step 3>",
-    "mode": "fs",
-    "repoPath": "."
-  }
-}
-```
-
----
-
-## 🧪 Validation & Testing
-
-### Test Suite Status
-
-```bash
-cd packages/axiom-tests
-npx vitest run
-
-# Results:
-# ✅ 31/31 tests passing
-# ✅ Duration: ~800ms
-# ✅ Coverage: 100% of critical paths
-```
-
-### Key Test Validations
-
-| Bug Fix | Test File | Status |
-|---------|-----------|--------|
-| POSIX paths | `path-normalization.test.ts` | ✅ 2/2 |
-| Real check evaluator | `check-evaluator.test.ts` | ✅ 3/3 |
-| Apply to FS | `apply-reporoot.test.ts` | ✅ 3/3 |
-| Security guards | `apply-sandbox.test.ts` | ✅ 3/3 |
-| Determinism | `determinism-edge.test.ts` | ✅ 3/3 |
-| Parser completeness | `parser-roundtrip.test.ts` | ✅ 3/3 |
-
----
-
-## 📊 Performance & Quality
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| Package Size | 4.1KB | ✅ Optimized |
-| Install Time | ~5s (97 packages) | ✅ Good |
-| Test Duration | 816ms | ✅ Fast |
-| Test Coverage | 31/31 (100%) | ✅ Excellent |
-| Determinism | Identical SHA256 | ✅ Maintained |
-
----
-
-## 🔒 Security Features
-
-1. **Path Traversal Protection**: Blocks `..` and absolute paths in `axiom_apply`
-2. **SHA256 Validation**: Verifies file integrity after write
-3. **POSIX Normalization**: Prevents OS-specific path exploits
-4. **Input Validation**: Strict schema validation on all tool inputs
-
----
-
-## 📚 Documentation
-
-- **API Reference**: See [docs/mcp_api.md](../../docs/mcp_api.md)
-- **Syntax Spec**: See [docs/syntax_spec.md](../../docs/syntax_spec.md)
-- **IR Spec**: See [docs/ir_spec.md](../../docs/ir_spec.md)
-- **GO-NOGO Report**: See [GO-NOGO-AXIOM-1.0.9.md](../../GO-NOGO-AXIOM-1.0.9.md)
-
----
-
-## 🐛 Troubleshooting
-
-### Issue: "EUNSUPPORTEDPROTOCOL" error
-
-**Problem**: Older version (1.0.7) used `workspace:*` dependencies  
-**Solution**: Update to latest version
-```bash
-npm install @codai/axiom-mcp@latest
-```
-
-### Issue: MCP server not starting in VS Code
-
-**Check**:
-1. Verify `.vscode/mcp.json` configuration
-2. Restart VS Code MCP extension
-3. Check VS Code Output panel (MCP logs)
-
-**Debug**:
-```bash
-npx @codai/axiom-mcp@latest
-# Should output: "AXIOM MCP Server running on stdio"
-```
-
-### Issue: Files not written to `./out/`
-
-**Check**:
-1. Verify `repoPath` is correct (default: `process.cwd()`)
-2. Ensure write permissions for directory
-3. Check `filesWritten[]` in response for actual paths
-
----
-
-## 🔄 Version History
-
-### v1.0.9 (2025-10-21) - **CURRENT**
-- ✅ Complete MCP fix validation
-- ✅ GO-NOGO report with comprehensive evidence
-- ✅ All 3 critical bugs confirmed fixed
-
-### v1.0.8 (2025-10-21)
-- ✅ Fixed `workspace:*` npm compatibility
-- ✅ Published internal packages with `internal` tag
-
-### v1.0.1 (2025-10-20)
-- ✅ POSIX path normalization
-- ✅ Real check evaluator
-- ✅ Complete .axm parser
-- ✅ Apply defaults to `process.cwd()`
-- ✅ Determinism enhancements
-
----
-
-## 📦 Package Information
-
-- **Name**: `@codai/axiom-mcp`
-- **Version**: `1.0.9`
-- **License**: MIT
-- **Repository**: https://github.com/dragoscv/axiom
-- **npm**: https://www.npmjs.com/package/@codai/axiom-mcp
-
----
-
-## 🤝 Contributing
-
-See main repository: https://github.com/dragoscv/axiom
-
----
-
-## 📄 License
-
-MIT License - see [LICENSE](../../LICENSE) for details
-
----
-
-**Built with 💙 by the AXIOM team**
+# @codai/axiom-mcp
+
+MCP server (stdio or Streamable HTTP) and CLI for AXIOM v2 — the transactional write gate for coding agents:
+`Plan` → canonical `ManifestBundle` → set-level checks → hash-gated two-phase `apply` → journal.
+`dist/cli.js` (thin entry) + `dist/cli-main.js` (lazy-loaded engines, SDK and zod bundled in); no runtime dependencies.
+
+## Install & run
+
+```sh
+npx @codai/axiom-mcp mcp --root /abs/path/to/repo          # stdio MCP server
+npx @codai/axiom-mcp mcp --root /abs/path/to/repo --http 127.0.0.1:3411   # Streamable HTTP at /mcp
+npx @codai/axiom-mcp --help                                # CLI verbs
+```
+
+`--root` may repeat. Every tool `root` argument must equal or lie inside one of them; with exactly one
+root it is the default. There is **no** env-var or `cwd` fallback (`ERR_ROOT_REQUIRED` / `ERR_ROOT_NOT_ALLOWED`).
+
+### VS Code — `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "axiom": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@codai/axiom-mcp", "mcp", "--root", "${workspaceFolder}"]
+    }
+  }
+}
+```
+
+### Streamable HTTP — `--http <host:port>`
+
+```sh
+axiom mcp --root /abs/repo --http 127.0.0.1:3411            # loopback, no token needed
+axiom mcp --root /abs/repo --http 0                          # random port; URL logged at info level
+AXIOM_HTTP_TOKEN=$(openssl rand -hex 32) axiom mcp --root /abs/repo --http 0.0.0.0:3411 --log-level info
+```
+
+- Endpoints: `POST /mcp` (an `initialize` opens a session and returns `Mcp-Session-Id`; every later
+  request must send it), `GET /mcp` (standalone SSE stream, one per session), `DELETE /mcp` (close the
+  session), `GET /health` → `{ ok, name, version }` (unauthenticated). Anything else is `404` JSON.
+- **Loopback by default.** A non-loopback host **refuses to start** unless a bearer token is present in
+  the env var named by `--http-token-env <NAME>` (default `AXIOM_HTTP_TOKEN`, ≥ 16 chars). Clients send
+  `Authorization: Bearer <token>`; the compare is constant-time. A token is optional on loopback.
+- DNS-rebinding protection is on for loopback binds (`Host` must be `<host>:<port>`, `localhost:<port>`
+  or `127.0.0.1:<port>`; otherwise `403`). Request bodies over 4 MiB are `413`.
+- Sessions idle for 30 minutes are evicted; each session has its own server instance (roots and guard
+  settings are shared). The transport lives in `dist/http-lazy.js`, loaded only with `--http`, and is
+  plain `node:http` — no express/hono at runtime.
+- VS Code: `{ "type": "http", "url": "http://127.0.0.1:3411/mcp" }`; add
+  `"headers": { "Authorization": "Bearer ${input:axiom-token}" }` when a token is set.
+
+Conformance: `packages/conformance` runs `@modelcontextprotocol/conformance server` against this transport
+in CI with an expected-failures baseline (`packages/conformance/baseline.yml`).
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "axiom": { "command": "npx", "args": ["-y", "@codai/axiom-mcp", "mcp", "--root", "/abs/path/to/repo"] }
+  }
+}
+```
+
+## Tools
+
+| tool | risk | input | output |
+|---|---|---|---|
+| `axiom_plan_validate` | READ | `{ plan }` | `{ ok, planDigest?, errors[] }` |
+| `axiom_plan_compile` | ACT | `{ plan, store?: inline\|cas, root? }` | `ManifestBundle` (writes only under `<root>/.axiom/` — CAS blobs and the stored manifest — when a root is given) |
+| `axiom_manifest_verify` | READ | `{ bundle, root? }` | `{ ok, manifestDigest, canonical, signed, missing[], errors[], signatures?: { trustFile, keyids[], findings[], ok } }` — `signatures` only when `root` has `.axiom/trust/keys.json` |
+| `axiom_check` | READ | `{ bundle, profile?, root? }` | `CheckReport` (`verdict: pass\|fail\|error`) |
+| `axiom_apply_dry_run` | READ | `{ bundle, root, profile? }` | `ApplyResult{mode:"dry-run", diff}` |
+| `axiom_apply` | SENSITIVE | `{ bundle, root, profile?, confirmDigest }` | `ApplyResult` |
+| `axiom_rollback` | SENSITIVE | `{ root, manifestDigest }` | `{ status:"rolled-back", phase, steps }` |
+| `axiom_manifest_diff` | READ | `{ a: bundle\|"sha256:…", b }` | `{ added[], removed[], changed[] }` |
+| `axiom_axm_parse` | READ | `{ source }` (`.axm` text) | `{ plan?, diagnostics: [{ severity, code, message, range: { start: {line, column}, end } }] }` |
+| `axiom_roots_list` | READ | `{}` | `{ roots: [{ path, writable, hasGit }] }` |
+| `axiom_repo_snapshot` | READ | `{ root?, include?[], exclude?[], maxFiles? (20000, cap 50000), maxBytes? (64 MiB), respectGitignore? (true), withContentDigest? (true) }` | `RepoSnapshot { snapshotDigest, body: { files: [{ path, bytes, sha256?, mode, kind }], truncated, counts } }` — sorted, no timestamps/absolute paths; `.git/`, `.axiom/` always skipped; symlinks recorded, never followed (`docs/snapshot.md`) |
+
+Every tool carries MCP `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+and an `outputSchema`; `structuredContent` is the full result, `content[0].text` a small summary (digest,
+verdict, counts, first 20 findings). Errors come back as `isError: true` with `{ code, message, path? }`
+from the closed `ERROR_CODES` enum — a handler never throws. `spec/tools.json` is generated from the same
+registry (`pnpm build:spec`) and guarded by a parity test. `spec/codai-tools.json` is the same registry in
+codai's `packages/agent-core/spec/tools-v2.json` entry shape (`{ name, risk, description, parameters }`) —
+see `docs/integration/codai.md`.
+
+Resources: `axiom://manifest/{sha}`, `axiom://report/{sha}`, `axiom://applied/{sha}`,
+`axiom://profile/{name}`, `axiom://schema/{Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot}`,
+`axiom://emitters` (template emitters available to `axiom_plan_compile` — `web@2.0.0`, see `docs/emitters.md`).
+
+## Trust model
+
+- Roots are realpath'd at startup, must be directories, and the set is frozen. Requested roots are
+  realpath'd too (case-insensitive containment on Windows); anything outside is a hard error.
+- `axiom_apply` requires `confirmDigest === bundle.manifestDigest` — echo the digest you saw in dry-run.
+  Pre-apply checks run against the profile (default `default`, or `<root>/.axiom/profiles/<name>.json`);
+  a non-`pass` verdict aborts with `ERR_CHECKS_FAILED` before any write.
+- Payloads over 4 MiB are rejected up front (`ERR_BUNDLE_TOO_LARGE`).
+- `.axiom/lock` makes apply single-writer per root; the journal makes it crash-safe and reversible.
+- stdout carries only JSON-RPC. Logs are JSON lines on stderr (`--log-level error|warn|info|debug`, default `warn`).
+- External guards (`guard.external`) are **off** unless the process is started with `--allow-guards`
+  *and* the profile sets `facts.allowGuards: true`. Relative commands must live under `<root>/scripts/`;
+  absolute ones must be listed exactly via `--guard-allowlist <abs>` (repeatable). Guards are spawned
+  with an args array (never a shell), a scrubbed environment, a wall-clock timeout, and must print
+  `GuardOutput` JSON — see `docs/checks.md`.
+- **Signed manifests** (`docs/signing.md`): a root can pin Ed25519 public keys in
+  `.axiom/trust/keys.json`; a profile with `manifest.requireSigned` then refuses unsigned, tampered or
+  untrusted bundles, and with `antiRollback: true` refuses any `counter ≤ .axiom/trust/state.json#lastCounter`.
+  `axiom_apply` advances that state only on `status: "applied"`. Private keys never enter the server:
+  signing is `axiom sign` with `AXIOM_SIGNING_KEY` or `--key-file`.
+
+## CLI
+
+```
+axiom mcp     [--root <abs>]... [--allow-guards] [--guard-allowlist <abs>]... [--log-level warn]
+              [--http <host:port>] [--http-token-env AXIOM_HTTP_TOKEN]
+axiom compile <plan.json> [-o out.json] [--store cas --root .] [--allow-net [--net-allow host[,host]]] [--allow-file]
+axiom verify  <bundle.json> [--root .]          (--root: also verify signatures against .axiom/trust/keys.json)
+axiom check   <bundle.json> --root . [--profile p] [--json] [--allow-guards] [--guard-allowlist <abs>]...
+axiom apply   <bundle.json> --root . [--dry-run] [--profile p] [--confirm <digest>] [--allow-guards] [--guard-allowlist <abs>]...
+axiom rollback <digest> --root .
+axiom gc      --root . [--dry-run] [--older-than 30d] [--keep all-manifests|journal]   (CAS garbage collection; CLI only, no MCP tool)
+axiom diff    <a.json> <b.json>
+axiom schema  <Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot>
+axiom emitters [--json]
+axiom keygen  [--out <dir>] [--name <label>]     (ed25519; private key → <dir>/axiom-signing-<id>.key 0600, public entry → stdout)
+axiom sign    <bundle.json> [--key-file <path>] [-o out.json]   (key from --key-file or $AXIOM_SIGNING_KEY)
+axiom trust   add <pub.json> --root . | remove <keyid> --root . | list --root .
+axiom gate    --stdin [--root <dir>] [--profile <file>] [--strict] [--log-level warn]
+axiom migrate v1 <manifest.json> [-o plan.json] [--profile default] [--cas <root>] [--content <dir>] [--overwrite]
+                                               (v1 manifest → v2 Plan, lazy chunk; exit 1 = migrated with warnings — docs/migrate.md)
+axiom snapshot --root . [-o snap.json] [--include <glob>]... [--exclude <glob>]... [--max-files n] [--max-bytes n] [--no-gitignore] [--no-digest]
+axiom snapshot-diff <a.json> <b.json>          (RepoSnapshot → { added, removed, changed })
+```
+
+Exit codes: `0` ok · `1` verdict fail / apply failed · `2` usage or error. Non-`mcp` verbs print JSON to stdout.
+
+`ref` sources (`{ type: "ref", uri, digest }`) are offline by default: a digest already in
+`<root>/.axiom/cas` resolves without network, anything else is `ERR_NET_DISABLED`. `--allow-net`
+fetches `https:` only (no redirects, 30 s timeout, 32 MiB cap), optionally restricted to
+`--net-allow` hosts (`*.example.com` wildcards), verifies the pinned digest and stores the blob in
+the CAS — a mismatch stores nothing (`ERR_DIGEST_MISMATCH`). `apply` never fetches. The MCP
+`axiom_plan_compile` tool has no network switch. See [docs/plan-format.md](../../docs/plan-format.md#ref-sources)
+and [docs/cas.md](../../docs/cas.md).
+
+## Hook mode — `axiom gate --stdin`
+
+A PreToolUse hook for Claude Code, Copilot CLI and VS Code agent hooks. It reads **one** harness
+payload from stdin (both `{tool_name, tool_input, cwd}` and `{toolName, toolArgs, cwd}` casings;
+`toolArgs` may be a JSON string), extracts the write target(s) of `Write|Edit|MultiEdit|NotebookEdit`,
+`create_file|replace_string_in_file|insert_edit_into_file|apply_patch|multi_replace_string_in_file|edit_notebook_file`
+and generic `write|edit`, and runs **only** the fast predicates: containment + `RelPath` rules
+(`..`, `CON`, NTFS ADS → `ERR_CONTAINMENT` / `ERR_PATH_*`), `path.deny`, `path.allow`,
+`content.noSecrets` and `content.maxBytes` on the new content when the payload carries it.
+
+| outcome | exit | stdout | stderr |
+|---|---|---|---|
+| allow / unknown tool | `0` | — | — |
+| deny | `2` | `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"…"}}` | `AXIOM GATE DENY <code>: <reason> (<relpath>)` |
+| malformed payload, stdin timeout (2 s), internal error | `0` (**fail open**) | — | `AXIOM GATE WARN: …` |
+| same, with `--strict` | `2` | deny JSON | `AXIOM GATE DENY ERR_INTERNAL: …` |
+
+Root = payload `cwd`, else `--root`, else the process cwd (the hook is the one place where cwd is
+acceptable: the harness spawns the hook in the project directory and owns that value).
+Profile = `--profile <file>` → `<root>/.axiom/gate-profile.json` → `~/.axiom/gate-profile.json` →
+built-in `{ deny: [".git/**", ".axiom/**", "**/*.lock", "pnpm-lock.yaml", ".env", ".env.*", "**/node_modules/**"], noSecrets: true }`.
+Schema: `{ deny: string[], allow?: string[], noSecrets: boolean, maxBytes?: number }` (strict).
+
+`gate` is a separate lazy chunk (`dist/gate-lazy.js`, no MCP SDK): in-process p95 ≈ 5 ms per payload,
+end-to-end ≈ 150–200 ms including node startup; `check-gate-latency` guards p95 ≤ 250 ms.
+Wiring for each harness is in [`docs/hooks.md`](../../docs/hooks.md).