jev-agent-tools 0.1.4 → 0.3.0

package/docs/design.md

@@ -6,9 +6,17 @@ The tools construct bounded evidence before asking for judgment. They preserve u
 
 Supply the discriminating evidence, not an argument about it. For comparisons, show both sides: a failing test and its implementation, or a file before and after. A bounded static import closure adds declarations before judgment where supported; it cannot establish completeness or discover relationships without imports. Commands are evidence sources, not a sandbox or a substitute for reading the output directly.
 
+Every call captures its host/server authority independently. Optional `root` admits only an exact repository top-level or live registered worktree with the same Git common directory, before content, commands, cache or HTTP. No override preserves existing cwd behavior; an invalid override never falls back. The effective context, requested/resolved base and inventory limits travel with evidence and results. See [root admission](../README.md#evidence-root).
+
+Explicit selectors define required evidence; lexical hints do not become vetoes merely because they resemble filenames. Exact directory paths cannot fall back to suffix matches. Canonical paths serialize each current/base version once, with aliases as metadata, and file admission counts identities rather than versions. Missing requirements gate their full question/control group; global-note requirements remain global. Captured output and repository files keep separate provenance.
+
+Historical-only files pass the same protected-path, ignore, regular-file and text admission checks before their base content is disclosed. Current and base versions share the distinct-file ceiling; unresolved or over-budget selectors are not retried through raw historical reads.
+
 ## Pure core, thin adapters
 
-Pure core transformations construct states, units, questions and display envelopes. Adapters own filesystem, Git, parsing and host effects; the HTTP client owns transport. Presets define fixed review questions and texts define host-facing guidance. Dependency checks keep shared contracts below consumers, reject cycles and account for erased type imports. Pure path operations and erased parser types are explicit architectural exceptions. Both hosts use the same HTTP judgment protocol.
+Pure core transformations construct states, units, questions and display envelopes. Adapters own filesystem, Git, parsing and host effects; the HTTP client owns transport. Presets define fixed review questions and texts define host-facing guidance. Hosts sit on top: `src/index.ts` registers the tools with pi and omp, and `src/mcp/` serves the same tool factories to any MCP client over stdio ([ADR 0010](adr/0010-mcp-server-thin-host.md), [setup](mcp.md)). Dependency checks keep shared contracts below consumers, reject cycles and account for erased type imports. Pure path operations and erased parser types are explicit architectural exceptions. Both hosts use the same HTTP judgment protocol.
+
+The dependency-free `src/result-types.ts` defines `ResultReportV1`; `core/result-report.ts` builds reports and validates semantic invariants, while `report-schema.ts` supplies the closed transport schema and structural validator. Producers record actual observations rather than reconstructing them from rendered prose. `renderResultReport` projects the same report to self-contained text, retaining native read/runner details. pi/omp publish `details.result`; supported MCP versions publish `structuredContent.result` without introducing a second judgment policy.
 
 ## Typed intents and fixed checks
 
@@ -18,11 +26,15 @@ Caller intents compile to typed questions with canonical options and exact state
 
 Leading-option probability (p_max) is the probability of the most likely choice, not the response's separate confidence field. Gray bands and applicable option-order checks expose ambiguity. Missing evidence remains abstention. Preset witnesses use a decoy and a known positive reference to detect a biased setup; failed controls do not promote findings. No mark establishes that unseen evidence is complete. See [result reading](../README.md#read-the-results).
 
+Execution state and judgment band are independent: complete/partial/refused/not judged describe processing, while verdict/unsure/abstain describe admitted judgments. Every requested item is fresh, cache, static or unjudged; static/fallback decisions have no invented probability. Auxiliary controls and passage decisions do not inflate requested-result counts. Missing required controls leave the requested group unjudged. Accounting distinguishes HTTP attempts, questions sent, cache probes, current cost and elapsed time; unknown cost is never reconstructed as zero or historical cached cost. Scoped diagnostics preserve material omissions and useful conditional actions.
+
 ## Bounded work, visible limits
 
-Admission limits, request planning, rate limiting and retry bounds are distinct. Oversized evidence is refused or visibly omitted, never silently converted into an ordinary verdict. Per-invocation max_calls and session call/cost limits are separate; control and severity requests count too. Unjudged tests stay selected. Automatic documentation review is the only run-end automation and can request at most one extra turn.
+Admission limits, request planning, rate limiting and retry bounds are distinct. Oversized evidence is refused or visibly omitted, never silently converted into an ordinary verdict. Per-invocation max_calls and session call/cost limits are separate; control and severity requests count too. Under a session USD limit, requests are admitted one at a time so each admission sees all cost reported so far. Unjudged tests stay selected. Automatic documentation review is the only run-end automation and can request at most one extra turn.
+
+Successful non-command judgments are cached only in session memory by canonical evidence, question and requested model string. Every judgment input, including control and passage decisions, carries admitted authority/root provenance and the resolved base when applicable; that metadata participates in both cache identity and serialized evidence admission. Identical content from different roots or base revisions cannot reuse a judgment. Errors are not cached; command judgments bypass caching. The default openjev alias can move, and an echoed model name does not prove served-model identity. Fractional budgets bound admission, not an exact prediction of the final request's cost.
 
-Successful non-command judgments are cached only in session memory by canonical evidence, question and requested model string. Errors are not cached; command judgments bypass caching. The default openjev alias can move, and an echoed model name does not prove served-model identity. Fractional budgets bound admission, not an exact prediction of the final request's cost.
+`src/texts/instructions.ts` is the versioned source for host policy, evidence guidance and current-state presentation. `node scripts/generate-instructions.ts` updates checked-in omp/MCP fragments; `--check` detects drift. Jev is discretionary when it can inform an open decision; native decisive evidence requires no certification call. Unchanged retries and mandatory risk/docs sequences are not recovery policy. pi/omp retain the opt-out documentation hook; MCP has no replacement obligation. Final presentation distinguishes native execution, Jev's static judgment and reported evidence, preserving independent material reservations without requiring an exhaustive history registry.
 
 ## Policy thresholds
 
@@ -184,4 +196,4 @@ Optional native syntax parsing and file-search acceleration can be absent. Tools
 
 ## Architecture decisions
 
-See the [architecture decision records](adr/) for durable trade-offs. Start with the [README](../README.md) for installation and follow its six tool references for complete parameter contracts.
+See the [architecture decision records](adr/) for durable trade-offs. Start with the [README](../README.md) for installation and follow its six tool references for complete parameter contracts. MCP clients: [setup guide](mcp.md) and [agent instructions](agent-instructions.md).

package/docs/mcp.md

@@ -0,0 +1,233 @@
+# MCP setup guide
+
+`jev-agent-tools-mcp` is a stdio [MCP](https://modelcontextprotocol.io) server that exposes the same six `jev_*` tools as the pi and omp extension to any MCP client. It ships in the `jev-agent-tools` npm package, has no runtime dependencies beyond that package, and runs one session per server process.
+
+Setup takes three steps: provide the endpoint and key, register the server with your client, and add the [agent instructions](agent-instructions.md) to your project.
+
+## 1. Requirements
+
+- Node.js 24 or later, and Git, on the machine that runs the client.
+- Bash for optional `jev_ask` command evidence. On Windows this is Git for Windows bash, found automatically next to `git` or under Program Files; set `JEV_TOOLS_BASH` to use another. The WSL `bash.exe` launchers are never used.
+- A Jev endpoint URL and API key.
+
+The server ships in `jev-agent-tools` version 0.2.0 and later. For a development checkout, see [From a clone](#from-a-clone).
+
+## 2. Provide the endpoint and key
+
+The server reads, per field, the environment first and then the configuration saved by `/jev-setup` in pi or omp. There is no interactive setup inside MCP.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `JEV_TOOLS_URL` | yes | Complete endpoint URL compatible with the Jev API format. Must be `https:`; plain `http:` is accepted only for `127.0.0.1`, `::1` or `localhost`. |
+| `JEV_TOOLS_API_KEY` | yes | Bearer credential. Never printed in tool output, never passed to `jev_ask` commands, and replaced with `[redacted]` in their output. |
+| `JEV_TOOLS_MODEL` | no | Requested model, default `openjev`. |
+| `JEV_TOOLS_ROOT` | no | Repository directory when `--root` is not given. |
+| `JEV_TOOLS_MAX_CALLS`, `JEV_TOOLS_MAX_USD` | no | Session call and cost limits for this server process. |
+| `JEV_TOOLS_ALLOW_COMMAND` | no | `0` removes `command` from `jev_ask`. |
+| `JEV_TOOLS_BASH` | no | Full path of the bash used for commands on Windows. |
+
+Prefer passing secrets through your client's environment-variable interpolation (shown per client below) rather than writing the key into a committed file. Saved configuration from `/jev-setup` lives in `~/.config/jev-agent-tools/config.json` and is refused unless the directory and file are private: owner-only mode bits on Linux and macOS, an access list limited to you, SYSTEM and Administrators on Windows. Unusable saved storage is reported on the server's stderr and never stops the server.
+
+Without an endpoint and key the server still starts, lists the tools and answers each call with what is missing.
+
+## 3. Register the server
+
+Every example registers a server named `jev`. Replace the repository path. The repository the tools work in is `--root`, else `JEV_TOOLS_ROOT`, else the directory the client starts the server in.
+
+**Windows:** most clients start the command without a shell, and `npx` is a `.cmd` script there, so `"command": "npx"` fails to start. Use `"command": "cmd"` with `"args": ["/c", "npx", ...]`, as in the Windows examples. This was checked on Windows 11 with Node.js 24: a shell-less spawn of `npx` failed with `ENOENT`, `cmd /c npx` started the server.
+
+The shared arguments are:
+
+```text
+npx -y -p jev-agent-tools jev-agent-tools-mcp --root <repository>
+```
+
+`-p jev-agent-tools` is required because the binary name differs from the package name. Pin a version (`jev-agent-tools@X.Y.Z`) for reproducible setups.
+
+### From the MCP Registry
+
+Releases are also published to the official [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.NomenAK/jev-agent-tools`, from [`server.json`](../server.json). Clients and catalogs that read the registry can install the server from there; they start it as `npx jev-agent-tools` (the package's only binary) and ask for `JEV_TOOLS_URL` and the secret `JEV_TOOLS_API_KEY`. The manual entries below give the same result.
+
+### Claude Code
+
+For a private registration, add it from the project directory with the CLI. Your shell expands the variables, so the values are stored in your private `~/.claude.json`, not in the project:
+
+```sh
+claude mcp add --scope local --env JEV_TOOLS_URL="$JEV_TOOLS_URL" --env JEV_TOOLS_API_KEY="$JEV_TOOLS_API_KEY" --transport stdio jev -- npx -y -p jev-agent-tools jev-agent-tools-mcp --root .
+```
+
+To share the server with the team, write `.mcp.json` at the project root instead. Claude Code expands `${VAR}` and `${VAR:-default}` from each user's environment when it loads the file, so no key is committed:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${CLAUDE_PROJECT_DIR:-.}"],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+On Windows use `"command": "cmd"` and prepend `"/c", "npx"` to `args`. Check with `claude mcp list`. Add the instructions to `CLAUDE.md` ([template](agent-instructions.md#claudemd)).
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings, Developer, Edit Config): `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Claude Desktop has no project directory, so `--root` is required. Its documentation does not describe variable interpolation, so values here are literal; keep this file private.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "C:\\path\\to\\repository"],
+      "env": {
+        "JEV_TOOLS_URL": "https://your-jev-endpoint.example/judge",
+        "JEV_TOOLS_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+On macOS use `"command": "npx"` without `"/c", "npx"`. Restart Claude Desktop after saving. One server serves one repository; add a second entry with another name for another repository.
+
+### Kiro (IDE and CLI)
+
+Workspace: `.kiro/settings/mcp.json`. User: `~/.kiro/settings/mcp.json`. The workspace file wins for a server of the same name. Kiro expands `${VAR}`.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "."],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      },
+      "disabled": false,
+      "autoApprove": ["jev_ask_files", "jev_find_files", "jev_locate_in_file", "jev_check_diff", "jev_select_tests"]
+    }
+  }
+}
+```
+
+`autoApprove` above leaves `jev_ask` on manual approval because it can run shell commands. On Windows use `"command": "cmd"` with `"/c", "npx"` first in `args`. Add the instructions as a steering file ([template](agent-instructions.md#kiro-steering)).
+
+### Cursor
+
+Project: `.cursor/mcp.json`. Global: `~/.cursor/mcp.json`. Cursor expands `${env:NAME}` and `${workspaceFolder}`.
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${workspaceFolder}"],
+      "env": {
+        "JEV_TOOLS_URL": "${env:JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${env:JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+Workspace: `.vscode/mcp.json`. The top-level key is `servers`, not `mcpServers`.
+
+```json
+{
+  "servers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "${workspaceFolder}"],
+      "env": {
+        "JEV_TOOLS_URL": "https://your-jev-endpoint.example/judge",
+        "JEV_TOOLS_API_KEY": "${input:jev-api-key}"
+      }
+    }
+  },
+  "inputs": [
+    { "type": "promptString", "id": "jev-api-key", "description": "Jev API key", "password": true }
+  ]
+}
+```
+
+The `inputs` prompt follows VS Code's MCP configuration reference; check it for your VS Code version.
+
+### OpenAI Codex CLI
+
+```sh
+codex mcp add jev --env JEV_TOOLS_URL=https://your-jev-endpoint.example/judge -- npx -y -p jev-agent-tools jev-agent-tools-mcp --root .
+```
+
+Or in `~/.codex/config.toml` (or a trusted project's `.codex/config.toml`). `env_vars` forwards variables from your environment without writing them into the file:
+
+```toml
+[mcp_servers.jev]
+command = "npx"
+args = ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "."]
+env_vars = ["JEV_TOOLS_URL", "JEV_TOOLS_API_KEY"]
+```
+
+Add the instructions to `AGENTS.md` ([template](agent-instructions.md#agentsmd)).
+
+### Windsurf and other clients
+
+Clients that use an `mcpServers` object accept the Claude Code JSON entry above. Windsurf reads `mcp_config.json` (see its MCP documentation for the current path) and expands `${env:NAME}`.
+
+## 4. Verify
+
+Run the server once by hand; it reads protocol messages from stdin and writes diagnostics to stderr:
+
+```sh
+npx -y -p jev-agent-tools jev-agent-tools-mcp --version
+npx -y -p jev-agent-tools jev-agent-tools-mcp --root . < /dev/null
+```
+
+In PowerShell, run the second as `$null | npx -y -p jev-agent-tools jev-agent-tools-mcp --root .`.
+
+The second command prints `jev-agent-tools MCP server ready (root ...; endpoint configured)` on stderr and exits when stdin closes. In the client, the six tools should be listed: `jev_ask`, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff`, `jev_select_tests`. A smoke call with a one-line note and a yes/no question reports execution, evidence context, fresh/cache/static/unjudged items, diagnostics and separate request/result accounting. This verifies integration, not model accuracy.
+
+## From a clone
+
+```sh
+npm ci --include=optional
+npm run build
+```
+
+Then use `"command": "node"` with `"args": ["/absolute/path/to/jev-tools/dist/mcp/main.js", "--root", "<repository>"]`. This form also avoids the Windows `npx` issue. Node does not strip TypeScript types under `node_modules`, which is why the server ships as compiled `dist/` while pi and omp load `src/`.
+
+## Differences from pi and omp
+
+- **No run-end documentation check.** pi/OMP retain an automatic opt-out host hook (`JEV_TOOLS_AUTO_DOCS=0`). MCP has no hook and its absence does not require manual replacement calls, including risk followed by docs; choose a review only when it can inform an open decision.
+- **Approval is the client's.** `jev_ask` is annotated as not read-only and potentially destructive while it accepts `command`; the other five are read-only. All six are open-world because evidence goes to your endpoint. `JEV_TOOLS_ALLOW_COMMAND=0` removes `command` from the schema and makes `jev_ask` read-only.
+- **Instructions.** The full reading guide and discretionary policy are sent as the server's `instructions`, using the same canonical fragments as pi/OMP with MCP's explicit hook difference. Clients may ignore them, so also copy the versioned [agent instructions](agent-instructions.md) into the project and update the copy on release upgrades.
+- **Tool names in descriptions** refer to "your text search tool" and "your file-name search tool" instead of pi or omp tool names.
+- **Protocol.** Versions 2024-11-05 through 2025-11-25 use `initialize`; 2026-07-28 uses `server/discover` and per-request `_meta`. Versions 2025-06-18 and later advertise `outputSchema` and return `structuredContent.result`; 2024-11-05 and 2025-03-26 receive self-contained text only. Each request retains its negotiated version even if another request changes the session version. Only 2026-07-28 adds `resultType: "complete"` and `ttlMs: 0` / `cacheScope: "private"`; this transport completion is independent of the report's execution state. Modern discovery supplies identity in `_meta["io.modelcontextprotocol/serverInfo"]`. Expected refusals use typed reports and appropriate `isError`; unexpected server exceptions remain JSON-RPC internal errors without invented report accounting. Tools only; no resources, prompts or sampling. Cancelling a call aborts its Jev requests and command.
+- **Malformed arguments.** Input-schema violations return JSON-RPC `INVALID_PARAMS` without a result report or judgment; well-formed calls rejected by root/evidence admission retain their typed refusal report.
+- **One process, one session.** Limits, cache and counters last as long as the connection; restart the server to reset them.
+- **Per-call evidence root.** All six tools accept `root` for a registered worktree of the same repository, with the [shared admission restrictions](../README.md#evidence-root). The startup directory remains the authority; `root` is not permission to access unrelated repositories.
+- **Command shutdown.** Cancellation, command timeout, stdin closure, SIGTERM and SIGINT wait for bounded command-tree termination. On POSIX the managed group receives SIGTERM, then SIGKILL after two seconds if it remains. On Windows, the server maps ordinary MSYS descendants through the same Bash installation's process table before running the system `taskkill /T /F`; each subprocess is bounded to five seconds. Cancelled calls receive no response. This is not a sandbox: descendants that deliberately detach from the managed group or escape the tracked tree are not contained.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| Client shows the server failed to start on Windows | `npx` cannot start without a shell. Use `cmd /c npx` or `node <path>/dist/mcp/main.js`. |
+| `jev-tools is not configured` in every result | The server did not receive `JEV_TOOLS_URL` and `JEV_TOOLS_API_KEY`. Check the client's `env` block and that interpolated variables exist where the client was started. |
+| stderr: `Cannot read or save Jev configuration` | Saved `/jev-setup` storage is not private or is malformed. Environment variables still apply. Fix permissions (on Windows, remove other accounts from the folder's Security tab) or delete the file and save again. |
+| `Repository directory not found` | `--root` or `JEV_TOOLS_ROOT` points to a missing directory. |
+| Command evidence reports `Command executable unavailable` | No usable bash. Install Git for Windows or set `JEV_TOOLS_BASH`. |
+| Results from the wrong repository | The client started the server elsewhere. Pass an absolute `--root`. |
+
+## Data and safety
+
+Repository evidence, notes and command output are sent to your configured endpoint; review its data-handling policy first. File collection is confined to the repository, but `jev_ask` commands run with your shell permissions and no sandbox. See [SECURITY.md](../SECURITY.md).

package/docs/tools/jev_ask.md

@@ -14,7 +14,9 @@ Use [jev_ask_files](jev_ask_files.md) for independent answers per file. Use nati
 
 The tool assembles one JSON situation. A note appears as `state`; repository files as `files["path"]`; historical versions as `files_before["path"]`; and command evidence as `output` with `command`, `exit_code`, `timed_out`, `stdout` and `stderr`. You receive answers, not the assembled file contents or captured output. Jev reads the evidence at a glance; it does not count, calculate or infer missing dependencies. Evidence outweighs an explanation of its role.
 
-Before judgment, bounded depth-one static import closure adds supported used declarations and data files, including before/after versions when applicable. A `closure:` line records additions and gaps. This is not completeness: configuration, documentation and other flow relationships without imports must be passed explicitly. Named missing file references can be added if uniquely resolvable; unresolved or empty referenced evidence prevents the affected ask from being posed.
+Before judgment, bounded depth-one static import closure adds supported used declarations and data files, including before/after versions when applicable. A closure diagnostic records additions and gaps; it cannot establish completeness or discover relationships without imports. Explicit `files[...]` and `files_before[...]` selectors name required evidence. Ordinary lexical mentions such as `.only` or `process.env` do not create missing-file vetoes, and names printed in command output are not disk evidence. An exact path with directory segments never falls back to another file with the same basename. For abbreviated references, a uniquely matching supplied file takes precedence over inventory discovery; ambiguity is reported, not guessed.
+
+One canonical path stores each file version; lightweight aliases do not duplicate content. Current and base versions remain distinct, and the 20-file limit counts distinct file identities, not their versions. A before-only selector can load historical content without a current file. `null` denotes a proven absent base version, not unavailable evidence. Missing/empty requirements exclude their question group and its controls; a requirement in the global note applies to all groups. Numeric zero and boolean false are not empty evidence.
 
 For recognizable assertion failures, the tool attempts to attach the failing test named by the log. An unidentifiable target produces a warning; any bug-versus-wrong-test conclusion under that warning remains unproven. Pass the failing test and implementation yourself whenever possible.
 
@@ -24,10 +26,11 @@ At least one of `state`, `paths` or `command` must provide evidence.
 
 | Field | Type / default | Meaning |
 |---|---|---|
-| `state` | Optional string, at most 8,000 characters | Short request, plan or observation not shown by the files; not a place to paste files or logs. JSON object text is accepted as structured state; `files` is reserved and rejected in such a note. |
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
+| `state` | Optional string, at most 8,000 characters | Short request, plan or observation not shown by the files; not a place to paste files or logs. JSON object text is accepted, but reserved evidence keys such as `files`, `files_before`, `evidence` and `output` cannot be supplied by the note. |
 | `paths` | Optional array of nonempty strings, at most 20 | Repository-relative files to read; not recursive directory or glob triage. |
-| `base` | Optional nonempty Git ref | Add each requested file's earlier version; absent earlier files are `null`. Use `HEAD` for uncommitted before/after questions. Historical evidence counts toward admission. |
-| `command` | Optional nonempty string | Execute `bash -c` at the repository root with `CI=1`, normal shell permissions and no additional sandbox. |
+| `base` | Optional nonempty Git ref | Add historical versions for the resolved revision; only established absence is `null`. Use `HEAD` for uncommitted before/after questions. Both versions count toward serialized evidence admission. |
+| `command` | Optional nonempty string | Execute `bash -c` at the repository root with `CI=1` and without `JEV_TOOLS_API_KEY`, normal shell permissions and no additional sandbox. The configured key is replaced with `[redacted]` in captured output, with the count reported. |
 | `timeout_s` | Optional number, default 60, range 1–300 | Command timeout in seconds. |
 | `asks` | Required intent, nonempty intent array, or JSON string encoding them | Typed questions; one intent per judgment. |
 | `max_calls` | Optional non-negative integer | Limit requests including controls and output passage finding; unjudged work is reported. |
@@ -81,7 +84,7 @@ Verification distinguishes `holds`, `contradicted`, `not addressed by the state`
 
 Serialized evidence, including keys and escapes, is bounded to 80,000 characters. Oversized files/state are refused with a split suggestion, not silently shortened. Repository file confinement rejects escaping paths and internal URLs.
 
-Commands are captured in private temporary files and cleaned up. Captured streams over 64 MiB are refused after execution; this neither caps disk usage nor interrupts execution. Repeated line shapes are compressed; lines over 8,192 characters and more than 2,048 distinct shapes produce visible notices. If compression still cannot fit, bounded passage judgments retain failure details and beginning/end context with omission markers. Excessive passage work is refused with guidance to narrow the command. A timeout gives `exit_code: null` and `timed_out: true`, not success; cancellation stops without judgment. Command calls bypass caching. `JEV_TOOLS_ALLOW_COMMAND=0` disables command evidence. Missing endpoint/key refuses judgment without a chat-model fallback.
+Commands are captured in private temporary files and cleaned up. Captured streams over 64 MiB are refused after execution; this neither caps disk usage nor interrupts execution. Repeated line shapes are compressed; lines over 8,192 characters and more than 2,048 distinct shapes produce visible notices. If compression still cannot fit, bounded passage judgments retain failure details and beginning/end context with omission markers. Command output reaches this stage before immutable file/note budget refusal, including calls with base snapshots and import closure. Excessive passage work is refused with guidance to narrow the command. Reports distinguish not started, finished and unknown execution, preserve observed cwd/exit/timeout even if later processing fails, and do not equate a judgment refusal with an unexecuted command. A timeout gives `exit_code: null` and `timed_out: true`, not success; cancellation stops without judgment. Command calls bypass caching. `JEV_TOOLS_ALLOW_COMMAND=0` disables command evidence. Missing endpoint/key refuses judgment without a chat-model fallback.
 
 ## Host differences
 

package/docs/tools/jev_ask_files.md

@@ -18,6 +18,7 @@ Each admitted file is judged alone as `path` and `content`. Every ask applies to
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `paths` | Required nonempty array of nonempty strings | Repository-relative files, recursive directories or globs; at most 255 admitted files. |
 | `asks` | Required typed intent, nonempty array of intents, or JSON string encoding them | All asks apply to every admitted file. An array is the clearest form. |
 | `max_calls` | Optional non-negative integer | Request limit for this invocation; remaining files are listed unchecked. Separate from session budgets. |
@@ -65,7 +66,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 ## Results and next action
 
-Results preserve the exact statement next to each file's answer. Boolean `yes` or `no (not shown)` includes the probability of yes; intermediate probabilities between 0.20 and 0.80 are unsure. Categories and levels need a leading-option probability of at least 0.85 after applicable controls. `classify`, `rate`, `decide` and `free` are uncalibrated; sharing a display band does not establish an error rate. Failed integrity or option-order controls make clear-looking results unsure. Read the candidate file before acting. Skipped and unchecked files and bracketed limits explain missing work. See [shared result reading](../../README.md#read-the-results).
+Results preserve the exact statement next to each file's answer and distinguish fresh/cache judgments from unjudged files. Boolean `yes` or `no (not shown)` includes the probability of yes; intermediate probabilities between 0.20 and 0.80 are unsure. Categories and levels need a leading-option probability of at least 0.85 after applicable controls. `classify`, `rate`, `decide` and `free` are uncalibrated; sharing a display band does not establish an error rate. Failed integrity or option-order controls make clear-looking results unsure; missing required judgments never become fabricated probabilities. Read the candidate file before acting. Typed diagnostics and actions explain skipped/unchecked files, causes and scope. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior
 

package/docs/tools/jev_check_diff.md

@@ -18,6 +18,7 @@ Changed declarations, slices, files or hunks become before/after evidence units.
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `check` | Required `"risk"`, `"docs"` or `"spec"` | Select the preset below. |
 | `base` | Optional nonempty Git ref, default `HEAD` | Compare the current tree, including untracked files, with this revision. |
 | `spec_path` | Optional nonempty repository-relative string | Required for `spec`: Markdown specification with `### REQ-…` headings. |
@@ -36,7 +37,7 @@ For replaced member accesses, separate local-caller checks inspect statically re
 
 ### docs
 
-Judge up to 40 existing tracked Markdown sections mentioning changed code or importing source, and identify the existing sentence made false. Collection and traversal limits are visible. This is not an exhaustive detector of missing documentation, arbitrary companion edits or every stale sentence.
+Judge up to 40 existing tracked Markdown sections mentioning changed code or importing source, and identify an existing sentence that may no longer match the change. Collection and traversal limits remain material reservations in the report. This is not an exhaustive detector of missing documentation, arbitrary companion edits or every stale sentence; inspect the sentence against the code before changing it.
 
 ### spec
 
@@ -64,6 +65,8 @@ For another preset, use `{"check":"docs","base":"HEAD"}` or `{"check":"spec","ba
 
 Findings name the evidence unit, stale sentence or requirement and its probability. Fixed findings require at least 0.7. Docs probabilities from 0.2 up to 0.7 are unsure without an additional judgment; read the indicated wording. Local-caller probabilities between 0.2 and 0.7 are unsure; `cannot_tell` at least 0.3 is abstain naming the missing provider or binding. Failed witness batches remain unsure. Read flagged source, callers or documentation before editing and preserve unresolved uncertainty in reports. See [shared result reading](../../README.md#read-the-results).
 
+Structured items retain negative as well as positive review results, actual control values and fresh/cache provenance. Budget-exhausted or incomplete groups are unjudged, not negative findings. Documentation completeness limits, collection omissions and witness failures remain scoped diagnostics even when another part of the review yields usable results.
+
 ## Limits and failure behavior
 
 No findings is not proof of safety, unseen-caller coverage or complete documentation. Unjudged units, callers, sections, requirements and severity are named when request or session budgets stop work. Parser gaps and unresolved dynamic providers remain limits, not invented answers. Missing configuration refuses judgment without a chat-model fallback. Static collection is bounded and does not evaluate third-party code.

package/docs/tools/jev_find_files.md

@@ -18,6 +18,7 @@ Deterministic lexical pre-ranking and name judgments produce candidates; the too
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `goal` | Required nonempty string | Behavioral sentence with at least five content words for an unqualified entry verdict. Shorter goals are accepted but capped at unsure. |
 | `keywords` | Optional array of nonempty strings, default empty | Known identifiers or terms steering lexical ranking and excerpt selection. |
 | `scope` | Optional directory string or array of directory strings, default repository | Restrict search; an incorrect scope may yield none. |
@@ -44,7 +45,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 ## Results and next action
 
-`entry:` names the file to open first with its probability, followed by ranked related paths and a suggested read. `entry: unsure` can mean two plausible entries, order sensitivity, inconclusive excerpts or a short goal: read the leading two candidates. `entry: none` means no candidate fit the supplied evidence: rephrase the behavioral goal or widen scope. Paths and probabilities are not source text; read the files before editing. See [shared result reading](../../README.md#read-the-results).
+The report distinguishes the primary entry decision from auxiliary ranking and controls, retains actual fresh/cache provenance and supplies useful read actions. Unsure can mean two plausible entries, order sensitivity, inconclusive excerpts or a short goal: inspect the leading candidates. A judged `none` means no candidate fit the supplied evidence: clarify the behavioral goal or widen the relevant scope. An empty collection, exhausted budget or missing response is not a `none` judgment and carries no invented probability. Paths and probabilities are not source text; read the files before editing. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior
 

package/docs/tools/jev_locate_in_file.md

@@ -18,6 +18,7 @@ Code splits the file into declarations or sections and constructs a choice over
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `path` | Required nonempty string | One repository-relative file, at least 19,000 bytes. |
 | `goal` | Required nonempty string | Sentence describing the behavior you need to find. |
 
@@ -38,10 +39,14 @@ Illustrative call with a fictional repository path, not a recorded execution:
 
 A result names `path:start-end`, a label, probability and the next read. Above 0.7 an unmarked range is a verdict: read it. From 0.4 through 0.7, unsure lists the two best ranges by probability: read both, not an arbitrary next section. Below 0.4 the tool narrows to three leading candidates plus none and judges again, retaining the original unsure band. Option-order sensitivity can also leave the result unsure. `none` means no supplied section fits: search elsewhere or clarify the goal. See [shared result reading](../../README.md#read-the-results).
 
+The versioned report preserves actual primary/control values and their fresh/cache source. Missing required control answers produce unjudged work rather than a synthesized range or probability. Typed diagnostics retain parsing/window omissions and native next actions, including searching elsewhere for a judged `none`.
+
 ## Limits and failure behavior
 
 Small files are refused with direct-read guidance. Whole-file admission is bounded by 320,000 characters and 1,280,000 bytes; larger files take the streamed-window path, not silent whole-file truncation. Window serialization, fallback section sizes, parsing support and choice cardinality are separately bounded. Unreadable or invalid evidence, missing configuration and exhausted session budgets are reported rather than producing a range verdict. Missing optional Python grammar is named with installation guidance. A selected window does not prove every relevant declaration was inspected.
 
+The serialized judgment budget includes per-call evidence provenance. Block planning, excerpt allocation and full-text refinement reserve that metadata capacity before selecting evidence; provenance never silently pushes an otherwise planned request past admission. Selected blocks still require at least two sections and obey the choice limit.
+
 ## Host differences
 
 omp `read` already outlines code files: use this tool when that outline does not tell you which range serves your goal. Both hosts use the same judgment protocol; omp marks the tool read-only.

package/docs/tools/jev_select_tests.md

@@ -20,6 +20,7 @@ Residual exported-unit checks concern changed units not exercised by any discove
 
 | Field | Type / default | Meaning |
 |---|---|---|
+| `root` | Optional nonempty string | Exact initial Git root or registered worktree of the same repository; see [evidence-root admission](../../README.md#evidence-root). |
 | `base` | Optional nonempty Git ref, default `HEAD` | Compare the current tree with this revision. |
 | `paths` | Optional array of nonempty strings, default discovered inventory | Candidate test files or globs, not changed source paths. |
 | `witnesses` | Optional `"off"`, `"auto"` (default), `"on"` | Controls residual coverage checks; test pointers have no witnesses. |
@@ -27,6 +28,8 @@ Residual exported-unit checks concern changed units not exercised by any discove
 
 Unknown fields and unresolved refs are rejected with guidance. Repository-relative evidence paths are confined to the repository; internal URLs are not file inputs. Narrowing candidate paths also narrows the inventory to which coverage observations apply.
 
+Each requested criterion reports its matches and any excluded or unmatched inventory. Partial matches keep the matched selection and identify the unmatched criteria; zero matches are not proof of no affected tests. Changed files outside the supported dependency graph retain conservative widening, with the triggering paths named. Runner commands remain static plans and use the admitted root.
+
 ## Example
 
 Illustrative call with fictional repository paths, not a recorded execution:
@@ -44,7 +47,7 @@ Illustrative call with fictional repository paths, not a recorded execution:
 
 Inspect selected scenarios and the returned runner commands, then execute them yourself. A scenario is selected when `1 - p(none) >= 0.5`; missing answers are selected too. If at least 80% of a file's scenarios are selected, names are uncertain or counts unknown, the command runs the whole file instead of a fragile name filter. Commands remain separate when runner context differs.
 
-`fallback: all` means conservative selection, not that Jev confirmed every scenario is affected. `changed, run by no discovered test` is limited to discovery evidence; do not call it repository-wide uncovered behavior. Read unsure or unsupported-runner limits and follow the named manual check. See [shared result reading](../../README.md#read-the-results).
+Static selection identifies its deterministic reason separately from fresh/cache Jev judgments. Conservative fallback preserves tests when judgments are unavailable; it is not confirmation that every scenario is affected. Residual absence is a derived reservation linked to retained coverage items or the considered inventory, not an extra requested judgment or fabricated probability. It does not establish repository-wide uncovered behavior. Read material limits and follow the named native action. See [shared result reading](../../README.md#read-the-results).
 
 ## Limits and failure behavior
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "jev-agent-tools",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
-  "description": "Six evidence-oriented tools for pi and omp coding agents, compatible with the Jev API format.",
+  "mcpName": "io.github.NomenAK/jev-agent-tools",
+  "description": "Six evidence-oriented tools for pi and omp coding agents and any MCP client, compatible with the Jev API format.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/NomenAK/jev-tools.git"
@@ -19,7 +20,9 @@
     "test-selection",
     "pi",
     "omp",
-    "jev"
+    "jev",
+    "mcp",
+    "model-context-protocol"
   ],
   "files": [
     "src/",
@@ -33,8 +36,18 @@
     "docs/tools/jev_find_files.md",
     "docs/tools/jev_locate_in_file.md",
     "docs/tools/jev_check_diff.md",
-    "docs/tools/jev_select_tests.md"
+    "docs/tools/jev_select_tests.md",
+    "docs/mcp.md",
+    "docs/agent-instructions.md",
+    "dist/",
+    "server.json",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "docs/adr/"
   ],
+  "bin": {
+    "jev-agent-tools-mcp": "dist/mcp/main.js"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"
@@ -49,6 +62,8 @@
     "node": ">=24"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "check:imports": "node scripts/check-imports.ts",
     "lint": "biome check src test scripts",

package/rules/jev-ask.md

@@ -1,4 +1,25 @@
 ---
 alwaysApply: true
 ---
-jev_ask: before you conclude that a failure is a bug in the code, a wrong test or the environment, or that a plan matches the docs, pass the files to jev_ask and weigh its answer against your own reading
+<!-- Generated policy 2026-10-03.1 from src/texts/instructions.ts; run node scripts/generate-instructions.ts after editing the source. -->
+Use Jev for a bounded semantic judgment when its answer could change an open decision or focus the next inspection, and the relevant evidence is available. Use decisive reading, search or authorized execution directly when it settles the question. Exact lookup, counting and runtime causality belong to native tools. A Jev call is not a prerequisite for a conclusion, a review or task completion; no explanation is needed for choosing native tools.
+
+Before a chosen call, identify the open decision and supply only the evidence needed for a bounded question; a complete prior analysis is not required. Ask about one positive, self-contained observable fact per claim, with its sources, and show both sides of a comparison.
+- Failure: relevant output, the failing test and the implementation it exercises; output alone is a lead, not a bug-versus-wrong-test diagnosis. Include configuration or runtime evidence when the hypothesis depends on it. A static judgment does not establish runtime causality.
+- Change: current evidence and the earlier reference via base. Use the checkout/root corresponding to the work and admitted by the tool; another clone is not the same context.
+- Plan/documentation: precise observable commitments and the passages that constrain them. Local confirmation does not establish that omitted obligations were searched.
+- Selection/review: compatible inventory, references and configuration. Suggested commands are not executed commands; existing tests need not cover a new scenario. Read the diff natively for its contents, not as proof of safety or global coverage.
+
+After an unavailable, refused or out-of-scope result, continue natively within the existing permissions; do not widen sharing or confinement to obtain a judgment. For uncertainty or missing evidence, inspect or obtain the decisive piece, or leave the conclusion open. Revisit Jev only when new evidence, a material context change or a new useful question makes the judgment useful; rewording unchanged evidence is not a reason to retry. There is no retry quota for genuinely changed evidence, and no certification is needed once decisive evidence settles the question. A reached cap or an unjudged result is not evidence of safety or zero affected tests.
+
+jev_check_diff: Review a stable diff for semantic risks, stale documentation or specification drift when that review can inform an open decision. Read the diff natively when you need its contents. Choose risk, docs or spec for the question at hand; neither risk followed by docs nor a Jev review before done is required. Findings are leads within the inspected scope, not proof of global safety or completeness.
+
+Report current conclusions first, then decisive evidence, origin and scope, then material reservations. Established means supported by relevant decisive evidence; a reported check remains explicitly reported, not observed execution. Distinguish native reading/execution, Jev's static judgment and testimony. A call count or global status is not proof.
+If native evidence settles the same scope and context after a Jev uncertainty, attribute the current conclusion to that evidence; old unsure or abstain results need not be recited as current reservations. A later Jev confirmation is attributed to Jev and retains its static limits. Independent reservations survive either resolution.
+Where an uncertainty actually returned by Jev remains material, explicitly say “Jev did not confirm X”, identify the missing evidence or guarantee, its known or indeterminate impact and the evidence to obtain. Preserve that reservation in the main text, summary and recommendation. Name native reservations and unjudged work as such, not as Jev uncertainty. Unresolved contradiction, stale evidence or a different checkout/base/scenario remains a reservation; the latest favorable answer does not win by default.
+Keep material limits in the main text, not only behind a link. Do not generalize a checked scenario into a universal guarantee. Separate relevant unestablished hypotheses from observations; omit irrelevant hypotheses. Explain unavailable historical causes only when material to action or requested, without inventing causality.
+Use existing history references when useful or requested; no exhaustive historical relay, persistent register or History block is required. A requested audit details available steps separately from the current state and does not reopen settled conclusions. Preserve existing traces; identify unavailable traces when they limit evidence or audit, without reconstructing evidence, executions or call counts. pi/OMP may reference an existing trace; MCP references must be client-accessible or explicitly unavailable.
+
+pi and OMP retain an automatic, opt-out documentation check at task completion (JEV_TOOLS_AUTO_DOCS=0 disables it). It is a host feature, not an agent requirement to call Jev. Inspect any flagged sentence against the change and update it or explain with evidence why it remains correct. The check is limited and does not certify documentation completeness or demonstrated usefulness. A flagged sentence does not require a second call or recursive reviews.
+
+Evidence passed to jev_* tools leaves the machine for the configured endpoint. Review its data handling; share only authorized evidence, never secrets or credentials. Host/client approvals still apply. jev_ask commands run with normal shell permissions and no sandbox; prefer read-only commands. Tool choice does not relax quality, proof, approval or confidentiality obligations.

package/server.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.NomenAK/jev-agent-tools",
+  "title": "Jev agent tools",
+  "description": "Evidence-oriented code questions, diff review and test selection via a Jev endpoint.",
+  "version": "0.3.0",
+  "repository": {
+    "url": "https://github.com/NomenAK/jev-tools",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/NomenAK/jev-tools/blob/main/docs/mcp.md",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "jev-agent-tools",
+      "version": "0.3.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        {
+          "type": "named",
+          "name": "--root",
+          "description": "Repository directory the tools work in. Defaults to the directory the client starts the server in.",
+          "format": "filepath",
+          "isRequired": false
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "JEV_TOOLS_URL",
+          "description": "Complete endpoint URL compatible with the Jev API format.",
+          "isRequired": true
+        },
+        {
+          "name": "JEV_TOOLS_API_KEY",
+          "description": "Bearer credential for the endpoint.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "JEV_TOOLS_MODEL",
+          "description": "Requested Jev model.",
+          "default": "openjev",
+          "isRequired": false
+        },
+        {
+          "name": "JEV_TOOLS_ALLOW_COMMAND",
+          "description": "Set to 0 to remove shell commands from jev_ask.",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}