jev-agent-tools 0.1.4 → 0.3.0

package/CHANGELOG.md

@@ -9,6 +9,109 @@ modules are not a stable library API.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-05
+
+### Breaking
+
+- `JEV_TOOLS_URL` (and saved or flag URLs) with plain `http:` is refused unless the host is `127.0.0.1`, `::1` or `localhost`; use `https:`. The configuration error shows neither the URL nor the key and occurs before any request.
+- Files whose base name matches `.env`, `.env.*`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*` or `secrets*` (any depth, case-insensitive; `.env.example`, `.env.sample` and `.env.template` excepted) are refused before reading on every evidence path, including diff units, test inventory, find, locate, ask-files and the pi/omp documentation hook. Each refusal is a named exclusion with the new cause `secret_pattern`; a question that explicitly requires such a file stays unjudged. There is no override.
+
+### Security
+
+- `jev_ask` commands and the Windows PowerShell ACL helper no longer inherit `JEV_TOOLS_API_KEY`. The configured key value (environment or saved configuration) is replaced with `[redacted]` in command output before state assembly, including a key prefix left where a long output line is cut, and the number of replacements is reported as a limitation.
+
+### Added
+
+- Optional `root` on all six tools, limited to the initial repository's exact Git root or registered live worktrees with the same common directory; invalid overrides refuse before evidence, commands, cache or judgments.
+- Versioned typed reports for every tool outcome, including refused and unjudged work: evidence context, item provenance, scoped diagnostics/actions and separate requested-result, HTTP, cache, control, passage and cost accounting.
+- MCP output schema and structured results from protocol 2025-06-18 onward, with self-contained text for older clients and per-request version isolation.
+
+### Changed
+
+- Explicit evidence selectors, rather than ordinary lexical mentions, govern missing-evidence exclusions. Canonical file versions are serialized once with alias metadata; before/current evidence remains distinct and missing requirements affect their own question group unless global.
+- Host guidance now makes Jev discretionary, shares versioned canonical fragments across pi/omp/MCP, and reports current conclusions with evidence provenance and material reservations. The pi/omp opt-out documentation hook remains; MCP requires no manual replacement call.
+- Human output is a projection of the typed report. Static/fallback selection and unavailable judgments never acquire fabricated probabilities; cached results are distinct from fresh requests and unknown cost is not zero.
+
+### Fixed
+
+- Historical-only and deleted-file evidence resolution, supplied-file basename precedence and canonical file-count admission without duplicated alias content.
+- Command output reaches bounded passage selection before immutable-evidence budget refusal, including base snapshots and import closure; reports preserve actual command execution/cwd even when later collection fails.
+- Selection reports distinguish unmatched candidate criteria, partial matches, excluded inventory and named conservative-widening triggers from absence of affected tests.
+- Review reports retain documentation completeness/collection reservations and risk/coverage witness diagnostics. Residual absence summaries remain derived observations within the considered inventory, not extra judgments or global coverage claims.
+- Recovery actions preserve the actual evidence/control limitation instructions rather than generic repetition advice.
+- Local-caller reports preserve their independent unsure/abstain bands and matching probabilities; specification drift remains one pointer decision rather than duplicated judgments for every candidate unit.
+- MCP malformed tool arguments remain JSON-RPC invalid-parameter errors, separate from well-formed calls refused by evidence admission.
+- Every judgment stage binds cache identity and serialized admission to its admitted root/base context, including auxiliary command passages. Locate planning reserves that metadata capacity before allocating evidence.
+- Historical selectors use protected base reads for ignored paths, symlinks, non-text content and deleted files; current/base versions share the distinct-file ceiling without bypassing rejected admissions.
+
+## [0.2.0] - 2026-10-03
+
+### Added
+
+- `jev-agent-tools-mcp`: a dependency-free MCP stdio server exposing the same six
+  tools to any MCP client. It reuses the existing tool factories, session limits,
+  HTTP client and saved configuration; the binary ships as compiled JavaScript built
+  by `npm run build`.
+- MCP setup guide (`docs/mcp.md`) and a project instruction template for MCP agents
+  (`docs/agent-instructions.md`, for `CLAUDE.md`, `AGENTS.md` or Kiro steering).
+- `JEV_TOOLS_BASH` and `JEV_TOOLS_ROOT` settings (Windows bash path; MCP root).
+- MCP Registry publication: `server.json` (`io.github.NomenAK/jev-agent-tools`) and
+  `mcpName` in `package.json`. After the npm publish, the release workflow waits for the
+  approved version and its `mcpName` on npm, then publishes with a pinned, checksum-verified
+  `mcp-publisher` over GitHub OIDC; an existing registry version is skipped only
+  when its server definition matches the approved tarball's metadata.
+- `scripts/check-mcp-package.ts`: CI and release gate that installs the packed
+  tarball, checks modern discovery and all advertised legacy handshakes, and
+  exercises `jev_ask` against a local synthetic HTTP endpoint.
+- Native Windows and macOS CI for MCP, managed process termination, private
+  configuration, platform paths and the installed package; Linux retains the
+  complete offline suite.
+
+### Changed
+
+- The npm package now includes `SECURITY.md` and `docs/adr/`, which shipped
+  documentation already linked to.
+
+### Fixed
+
+- MCP command cancellation and timeout now finish process-group escalation even
+  when the parent shell exits first. Closing stdin, SIGTERM and SIGINT drain
+  outstanding tool calls before the server exits; cancelled calls stay silent.
+- Windows command cleanup maps MSYS descendants before forced termination, so
+  Git Bash fork/exec no longer hides ordinary descendants from `taskkill /T`.
+- Package checks use local archive paths on Windows and macOS; private-storage
+  test fixtures use canonical macOS temporary paths without relaxing symlink checks.
+- Modern MCP discovery now includes server identity in result metadata, and
+  tool lists declare immediately stale, private caching as required by the
+  2026-07-28 protocol.
+- MCP Registry reruns skip only an identical server definition. Divergent,
+  malformed or inconclusive responses fail; registry metadata is checked
+  against `server.json` inside the approved tarball before lookup.
+
+- In omp, first-launch Jev setup no longer waits for credential entry inside the
+  bounded `session_start` handler. The offer and input dialogs stay open while
+  users find their endpoint and key, rather than closing after the host's
+  30-second event deadline.
+- `JEV_TOOLS_MAX_USD` could be overshot by up to seven requests: concurrent batches
+  were all admitted before any cost was reported. Under a USD limit, requests are
+  now admitted one at a time, so only the final admitted request can exceed it.
+- Windows: `jev_ask` commands ran `env CI=1 bash`, which fails without `env` and
+  resolves to the WSL launcher. Git for Windows bash is now used.
+- Windows: imported providers were never found for `jev_check_diff` risk callers
+  because a repository path was resolved with platform path semantics.
+- Windows: node:test `file:///C:/...` failure locations (including `%20`) were not
+  mapped back to repository files.
+- Windows: an 8.3 short working directory (for example `C:\Users\NAME~1`) did not
+  relate to the Git root, which emptied import closures and file references.
+- Line endings are pinned to LF via `.gitattributes`, so lint and the rule/guideline
+  parity check pass on Windows checkouts with `core.autocrlf=true`.
+- Windows: saving or loading `/jev-setup` configuration always failed, because the
+  privacy check read POSIX mode bits, which Windows reports as `0o666` for every file.
+  Windows now checks the folder and file access lists (allow entries limited to the
+  current user, SYSTEM and Administrators) and restricts a new folder when saving.
+- Tests: `secret-input` passed a `C:\` path to `import()`; the risk-caller latency
+  test compared one run with a fixed 250 ms and now checks 250- to 1000-line scaling.
+
 ## [0.1.4] - 2026-10-02
 
 ### Added
@@ -74,7 +177,9 @@ Tagged but never published to npm: the unscoped package name was rejected.
 
 Tagged but never published to npm: the publish workflow failed before upload.
 
-[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/NomenAK/jev-tools/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/NomenAK/jev-tools/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/NomenAK/jev-tools/compare/v0.1.4...v0.2.0
 [0.1.4]: https://github.com/NomenAK/jev-tools/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/NomenAK/jev-tools/compare/v0.1.0...v0.1.3
 [0.1.2]: https://github.com/NomenAK/jev-tools/tree/v0.1.2

package/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Issues and external pull requests are welcome. Use English for issues, pull requests, documentation, comments, and test descriptions; keep non-English fixtures when they test language or encoding behavior. For vulnerabilities, follow [SECURITY.md](SECURITY.md).
+
+## Issues or pull requests?
+
+Open an issue for a reproducible product bug or a feature request. Include the package and host versions, expected and actual behavior, and a minimal sanitized reproduction. Small, focused fixes or documentation corrections can go straight to a pull request. Discuss new tools, contract changes, and research-dependent features in an issue before implementing them.
+
+An issue may describe an unmet need without claiming that a method already works. Features such as co-change suggestions are not accepted for implementation without a new, validated method. Propose the method, its evaluation protocol, and reproducible evidence in an issue first; an unvalidated heuristic or a renamed version of it is not enough.
+
+## Local checks
+
+Use Node.js 24 or newer and npm. From a checkout, with development dependencies enabled:
+
+```sh
+npm ci --include=optional
+npm run typecheck
+npm run build
+npm run check:imports
+npm run lint
+node scripts/generate-instructions.ts --check
+npm test
+```
+
+`npm run build` compiles only the MCP server into `dist/` (git-ignored); `npm pack` runs it automatically. To try the server against a checkout, see [From a clone](docs/mcp.md#from-a-clone). CI packs the package and runs `node scripts/check-mcp-package.ts <tarball>`: it installs the tarball into an empty directory, checks modern discovery and all advertised legacy handshakes, lists the six tools with their schemas and caching fields, and runs `jev_ask` through a local synthetic HTTP endpoint. This verifies installed integration, not live model accuracy. Linux runs the full offline suite; native Windows and macOS jobs run targeted MCP, process, configuration and packaging checks.
+
+Agent policy and result-reading guidance are versioned in `src/texts/instructions.ts`. After changing them, run `node scripts/generate-instructions.ts` to update the checked-in omp rule and MCP project block; `--check` verifies that those copies remain synchronized. Keep host differences explicit rather than maintaining independent policy text.
+
+## Releases
+
+Maintainers release by pushing a `vX.Y.Z` tag on reviewed `main`. Before tagging, set the same version in `package.json`, in both `version` fields of `server.json`, and in a `CHANGELOG.md` section; `test/server-json.test.ts` fails if they drift. [`publish.yml`](.github/workflows/publish.yml) then packs once, checks the packed MCP server, publishes the approved tarball to npm with trusted publishing, publishes `server.json` to the MCP Registry with GitHub OIDC, and creates a draft GitHub Release. Each publication step skips a version that already exists with the same content and fails on anything inconclusive.
+
+Keep optional native dependencies enabled for development. These checks make no Jev API calls and need no Jev key. Dependency installation may use the network. Some runner-identity tests skip when additional runners are unavailable locally; CI provisions those runners in [.github/workflows/ci.yml](.github/workflows/ci.yml).
+
+Maintainers run a private regression probe on reviewed release candidates before release and on the published package before announcing it. Contributors do not need access to that probe or its credentials.
+
+## Pull request expectations
+
+Keep changes focused. Explain the user-visible behavior, link the relevant issue when there is one, and report the checks you actually ran, including skips or limitations. Add or update deterministic tests for changed behavior and regressions, and update affected documentation. Public CI must pass without service credentials.
+
+Do not make accuracy, recall, speed, or other measurement claims without describing the method, baseline, data, and limitations sufficiently to reproduce and review them. Do not include credentials, raw service responses, private data, or personal configuration in issues, patches, or logs. Use synthetic or sanitized examples.
+
+Check the name and email attached to your commits before submitting; GitHub's noreply email is an option if you do not want to publish a personal email address.

package/README.md

@@ -1,28 +1,55 @@
 # jev-agent-tools
 
-Six evidence-oriented tools for pi and omp, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.
+Six evidence-oriented tools for pi, omp and any MCP client, compatible with the Jev API format. Use them to navigate unfamiliar code, ask typed questions about repository evidence, review completed changes and select existing tests. They complement reading, searching and execution; they do not replace them.
+
+[![jev-agent-tools launch video: six tools, one habit, show the evidence. Click to play (74 s).](docs/media/jev-agent-tools-launch.jpg)](docs/media/jev-agent-tools-launch.mp4)
+
+[Watch the launch video](docs/media/jev-agent-tools-launch.mp4) (74 s, MP4).
 
 ## Install
 
-Install through your host's package manager. The npm package is `jev-agent-tools`. It ships TypeScript sources; no separate compilation is required.
+Install through your host's package manager, or register the MCP server with an MCP client. The npm package is `jev-agent-tools`. pi and omp load its TypeScript sources directly; the MCP server ships prebuilt.
 
 ### pi
 
 ```sh
-pi install npm:jev-agent-tools@0.1.4
+pi install npm:jev-agent-tools@0.3.0
 # Project-local installation:
-pi install -l npm:jev-agent-tools@0.1.4
+pi install -l npm:jev-agent-tools@0.3.0
 ```
 
 ### omp
 
 ```sh
-omp plugin install jev-agent-tools@0.1.4
+omp plugin install jev-agent-tools@0.3.0
+```
+
+### Any MCP client
+
+Since version 0.2.0, the package also ships `jev-agent-tools-mcp`, a stdio MCP server that exposes the same six tools to any MCP client: Claude Code, Claude Desktop, Kiro, Cursor, VS Code, Codex CLI and others. A typical `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "/path/to/repository"],
+      "env": {
+        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
+        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
+      }
+    }
+  }
+}
 ```
 
+On Windows most clients start commands without a shell, so use `"command": "cmd"` with `"/c", "npx"` at the start of `args`. The [MCP setup guide](docs/mcp.md) has per-client files, CLI commands, variable interpolation, verification and troubleshooting. Releases are also listed in the official MCP Registry as `io.github.NomenAK/jev-agent-tools`. Add the [agent instructions](docs/agent-instructions.md) to `CLAUDE.md`, `AGENTS.md` or a Kiro steering file so the agent uses and reads the tools correctly.
+
+The server reads the same environment variables as pi and omp and the configuration saved by `/jev-setup`. One server process is one session. MCP has no automatic run-end documentation hook; its absence does not require manual replacement calls. `jev_ask` is marked as not read-only while commands are enabled; set `JEV_TOOLS_ALLOW_COMMAND=0` to remove `command` from its schema.
+
 ### Requirements and compatibility
 
-Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
+Requires Node.js 24 or later. Supported host baselines are pi 0.87.1 and omp 18.4.10. These are support baselines, not claims that every later version has been individually validated. omp uses its Bun runtime; Node.js is also required for Node-based project checks. Git and, for optional command evidence, Bash must be available. On Windows, command evidence uses Git for Windows bash (found next to `git` on `PATH` or under Program Files); the WSL `bash.exe` launchers are never used. Set `JEV_TOOLS_BASH` to the full path of another bash. Optional native parsers and file-search acceleration may be unavailable on some platforms; affected tools report their limitations.
 
 The published `jev-agent-tools@0.1.3` package was also checked with **pi 1.0.0** on Linux under Node.js 24.15.0: npm installation, TypeScript checking against the host types, all six tools in the actual CLI, and reading-guide injection passed. The CLI smoke used a simulated conversation provider and Jev endpoint; it verifies host integration, not live model accuracy or every tool scenario.
 
@@ -42,9 +69,11 @@ In the main interactive terminal of pi or omp, a first launch without configurat
 
 No dialog appears in print, JSON or RPC modes, or in sub-agents; configure those with the environment variables below. Changes apply immediately, without restarting the host.
 
+Interactive setup waits for submission or cancellation, without a credential-entry timeout. The first-launch offer does not keep the host's startup event handler open while you find the endpoint or key.
+
 **Precedence per field:** environment variable, then launch flag, then this session's setup, then saved configuration, then the default model `openjev`. A field set by the environment or a flag is shown as controlled and is never saved.
 
-**Saved configuration** lives outside the repository at `$XDG_CONFIG_HOME/jev-agent-tools/config.json` (default `~/.config/jev-agent-tools/config.json`), in a private directory (`0700`) with a private file (`0600`). **The key is stored in plaintext, not encrypted.** Storage that is a symlink, group/world-accessible, not owned by you or malformed is refused rather than overwritten.
+**Saved configuration** lives outside the repository at `$XDG_CONFIG_HOME/jev-agent-tools/config.json` (default `~/.config/jev-agent-tools/config.json`), in a private directory (`0700`) with a private file (`0600`). On Windows, where mode bits do not exist, privacy is the folder's access list: saving restricts it to you, SYSTEM and Administrators, and loading refuses any other account with access. **The key is stored in plaintext, not encrypted.** Storage that is a symlink, accessible to other users, not owned by you or malformed is refused rather than overwritten. The MCP server also reads this file, after environment variables.
 
 ### Environment variables
 
@@ -61,13 +90,15 @@ export JEV_TOOLS_MODEL="openjev"
 
 | Variable | Meaning |
 |---|---|
-| `JEV_TOOLS_URL` | Required complete endpoint URL compatible with the Jev API format. |
-| `JEV_TOOLS_API_KEY` | Required Bearer credential; configuration values are not printed in tool output. |
+| `JEV_TOOLS_URL` | Required 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` | Required Bearer credential; configuration values are not printed in tool output, and command children never receive it. |
 | `JEV_TOOLS_MODEL` | Requested model string, default `openjev`; a moving alias, not a guarantee of served-model identity. |
 | `JEV_TOOLS_MAX_CALLS` | Session-wide non-negative safe-integer call limit; absent or empty means unlimited. Invalid values refuse requests. |
 | `JEV_TOOLS_MAX_USD` | Session-wide finite non-negative cost limit, including fractions; absent or empty means unlimited. Invalid values refuse requests. |
 | `JEV_TOOLS_ALLOW_COMMAND` | `0` disables `command` in `jev_ask`; otherwise commands run with ordinary shell permissions, without an additional sandbox. |
 | `JEV_TOOLS_AUTO_DOCS` | `0` disables the automatic run-end documentation check. |
+| `JEV_TOOLS_BASH` | Optional full path of the bash used for `jev_ask` commands on Windows. |
+| `JEV_TOOLS_ROOT` | MCP server only: repository directory when `--root` is not given. |
 
 Without the endpoint or key, tools remain registered and explain the missing configuration; the automatic documentation check is disabled. There is no fallback to a chat model. Per-tool `max_calls` is separate from session limits. A model name echoed by the response does not establish which model was actually served.
 
@@ -84,39 +115,49 @@ Without the endpoint or key, tools remain registered and explain the missing con
 
 Use native read/search tools or code for exact source text, known symbols, filenames, line numbers, counts and arithmetic. Run commands yourself when you need their full output. Tool reference examples use fictional repository paths and are illustrative calls, not recorded executions.
 
+### Evidence root
+
+All six tools accept optional `root: string`. Without it, the host's current directory or configured MCP server directory retains its existing behavior. An override must name exactly the initial repository's Git top-level or a registered live worktree with the same canonical Git common directory. Relative overrides resolve against the initial directory; absolute paths are accepted only for this parameter. Subdirectories, other clones/repositories, parent traversal and symlink components are refused before evidence collection, command execution, cache access or judgment. There is no fallback to a different checkout.
+
+The admitted root governs files, base/diff, inventories, specification paths, runner plans and command cwd for that call only. It does not change another call or the automatic documentation hook. File arguments remain repository-relative and confined. A command still has ordinary shell permissions, not a sandbox. Check the reported authority, requested/effective root and resolved base before using a result.
+
 ## Read the results
 
-A line without a mark is a **verdict**: a lead to check before editing, deleting or reporting completion, not a proof. Probabilities concern the evidence shown, not everything in your repository.
+Each result begins with execution state: **complete**, **partial**, **not_judged** or **refused**. This describes processing, not correctness, safety or coverage. Items distinguish fresh or cached Jev judgments, static treatment and work never judged. Static selection and conservative fallback carry no invented probability. A judged line without an uncertainty mark is a **verdict**: a lead to check, not proof beyond the supplied evidence.
 
 | Mark | Meaning and next action |
 |---|---|
 | `unsure` | The answer is ambiguous or a control failed. Read the indicated passage or add the specific evidence that would settle it. Do not merely reword the question. |
-| `abstain` | A necessary piece is missing. Add the named file or command evidence and ask once. |
+| `abstain` | A necessary piece is missing. Obtain the named evidence or leave the conclusion open; another Jev call is optional when the changed evidence makes it useful. |
 | `no (not shown)` / `not addressed` | The supplied evidence does not show the statement; that does not make it false. |
 | `uncalibrated` | No established error-rate calibration applies to this ask; treat it as a hint even if its probability is high. |
-| Bracketed lines | Collection, parsing, budget or display limitations, with the next manual action. |
+| Diagnostics and next actions | Typed cause, origin, affected scope, materiality and recovery instructions; distinguish uncertain judgments from work never judged. |
 
 Ordinary boolean verdict bands are at or below 0.20 and at or above 0.80; category/level verdicts require a leading-option probability of at least 0.85 after applicable controls. Fixed checks and navigation tools have their own thresholds, described in their references and [design](docs/design.md).
 
-The footer reports **calls · questions · cost · cache · time**: request count, questions judged, reported USD cost, cache hits/requests and elapsed time. A tool invocation may require several requests for batching or controls. Missing cost reporting is not evidence of a free request.
+Accounting separates **HTTP attempts**, **questions sent**, **requested results** (fresh/cache/static/not judged), **cache probes**, auxiliary controls and passage selection, current reported USD cost and elapsed time. These counts are not interchangeable. A cached judgment can have zero HTTP attempts; zero attempts can also mean static work or no judgment. Unknown cost is unreported, not free. Context values distinguish known, unknown, not collected and not applicable.
+
+pi and omp expose the versioned report as `details.result`. MCP versions from 2025-06-18 expose the same report under `structuredContent.result` with an advertised output schema; older versions receive self-contained text from the same report. Text preserves material limitations, evidence provenance and useful read/runner commands.
 
-In a final report, explicitly identify conclusions marked `unsure` or `abstain` as unconfirmed by Jev. If subsequent reading settles them, distinguish that verification from the tool's result and cite the decisive evidence. Otherwise retain the uncertainty in your summary and recommendation.
+Report current conclusions, decisive evidence with origin and scope, and material reservations. If native reading or execution settles an earlier `unsure` or `abstain` on the same context, attribute the current conclusion to that native evidence, not Jev. If uncertainty returned by Jev remains material, explicitly say Jev did not confirm the conclusion and name the missing evidence and impact. Independent limits, stale evidence and conflicting contexts remain visible. Reported checks are not observed execution; no exhaustive history block or new persistent register is required.
 
 ## Usage guidance for pi and omp
 
 The extension supplies the shared reading guide in both hosts. omp discovers enabled npm plugin rules during normal startup; pi does not automatically discover the package's `rules/` directory. In pi, the same decision policy is part of the `jev_ask` tool guidelines, so it is present whenever `jev_ask` is active. A forced opaque prompt override may bypass this integration; disabled tools or disabled omp rules are not covered. This README block is recommended usage guidance, not itself an installed instruction:
 
-> Before concluding that a failure is a code bug, an incorrect test or an environment problem, or that a plan matches documentation, pass the relevant files to [jev_ask](docs/tools/jev_ask.md) and weigh its answer against your own reading. Include both the failing test and the code it exercises; identify any conclusion that remains unconfirmed.
+> Use Jev for a bounded semantic judgment when it can change an open decision or focus inspection. Use decisive native reading, search or authorized execution directly. A Jev call is not a prerequisite for a conclusion, review or completion. When choosing a call, supply both sides of a comparison and the evidence that distinguishes explanations. Revisit only when changed evidence, context or a useful new question warrants it; repeating unchanged evidence is not a recovery action.
+
+MCP clients receive the guide as server `instructions`, which some clients ignore. Add the [agent instructions](docs/agent-instructions.md) to the project's `CLAUDE.md`, `AGENTS.md` or Kiro steering file.
 
 ## Data and command safety
 
 Repository evidence, notes and optional command output are sent to your configured endpoint. Review its data-handling policy before using confidential repositories. See [security guidance](SECURITY.md).
 
-File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions. omp uses execution approval for commands; pi does not supply an additional per-tool command approval. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
+File collection is confined to the repository: absolute paths, parent traversal, escaping symlinks, Git metadata and internal URLs are not file inputs. Files named like secrets (`.env`, `.env.*` except `.env.example`/`.env.sample`/`.env.template`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*`, `secrets*`, any depth, any case) are refused before reading and named with cause `secret_pattern`. Build output, binaries, lockfiles and oversized files are skipped or refused with visible limits; evidence is not silently truncated into a verdict. This confinement does **not** sandbox a command. `jev_ask` commands can read, write or access the network with the host's shell permissions; they run without `JEV_TOOLS_API_KEY`, and the configured key is replaced with `[redacted]` in their output. omp uses execution approval for commands; pi does not supply an additional per-tool command approval; MCP clients apply their own tool approval, and the server marks `jev_ask` as not read-only. Set `JEV_TOOLS_ALLOW_COMMAND=0` to disable them.
 
 ## Automatic documentation check
 
-On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including untracked files. A flagged existing sentence can request one additional turn to update it or explain why it remains correct. Merely unsure sections do not trigger another turn. Missing configuration, disabled automation, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This is not a check for every missing documentation obligation.
+On a dirty tree, the extension can check existing Markdown documentation once at run end against changes from `HEAD`, including admitted untracked files (not gitignored, not secret-named), which are sent to the endpoint without an explicit tool call. A flagged existing sentence can request one additional turn to inspect and update it or explain with evidence why it remains correct; a flag does not itself establish falsehood or require a second call. Merely unsure sections do not trigger another turn. `JEV_TOOLS_AUTO_DOCS=0`, missing configuration, invalid/exhausted session budgets or a clean tree skip the check. Errors and timeout do not block the host. This opt-out host feature does not certify documentation completeness. MCP has no hook and requires no manual replacement ritual.
 
 ## Known limits
 

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security policy
+
+## Supported versions
+
+Security fixes target the latest patch release in the 0.1.x series. Older 0.1.x patches should be upgraded; 0.0.x and unreleased snapshots are not supported releases.
+
+## Report privately
+
+Use GitHub's [Report a vulnerability](https://github.com/NomenAK/jev-tools/security/advisories/new) form. Do not disclose vulnerabilities in public issues or pull requests. If the form is unavailable, open an issue asking to restore private reporting, without vulnerability details. There is no email reporting channel.
+
+Include the affected version, impact, and a minimal reproduction using synthetic data. Never include live credentials, private repository contents, or personal configuration. If a credential may have been exposed, revoke or rotate it independently of this report.
+
+This is a solo-maintained project. Reports are reviewed on a best-effort basis; there is no guaranteed acknowledgement or fix deadline. Follow-up and disclosure coordination take place in the private report. Please coordinate public disclosure there.
+
+## Scope and trust boundaries
+
+Report repository-confinement escapes in file evidence collection, including reads outside the selected repository; unintended secret exposure caused by jev-tools; and unintended command execution or bypasses of disabled command execution.
+
+File evidence collection is confined to the repository, but optional commands are not sandboxed: they run with the host's permissions and may read or modify files or access the network. `JEV_TOOLS_ALLOW_COMMAND=0` disables this command path. Selected repository evidence and requested command output are sent to the configured API endpoint. Review the data and endpoint before use.
+
+### Secret-named files are refused
+
+Every evidence admission path (`jev_ask` paths and import closure, `jev_ask_files`, `jev_find_files`, `jev_locate_in_file`, `jev_check_diff` diff units and local callers, `jev_select_tests` inventory and the automatic pi/omp documentation check) refuses a file whose base name matches `.env`, `.env.*`, `*.pem`, `id_rsa*`, `*.p12`, `credentials*` or `secrets*`, at any depth and case-insensitively, whatever its Git status (tracked, untracked or added). `.env.example`, `.env.sample` and `.env.template` remain admitted. The refusal happens before the content is read: the result names the path with cause `secret_pattern`, and a question that explicitly requires that file stays unjudged. There is no per-call or environment override. Files with other names are not inspected for secrets.
+
+### Commands never receive the API key
+
+`jev_ask` commands and the Windows PowerShell ACL helper run with the host environment minus `JEV_TOOLS_API_KEY`. Before command output enters a state, every occurrence of the configured key value, whether it came from the environment or the saved configuration, is replaced with `[redacted]` in stdout, stderr and the echoed command line; the result reports how many replacements were made. Detection of other secrets in command output is not promised.
+
+### The key travels only over HTTPS or loopback
+
+`JEV_TOOLS_URL` must use `https:`. Plain `http:` is accepted only for `127.0.0.1`, `::1` or `localhost`; any other `http:` URL is a configuration error, reported without the URL or key and before any request, so the Bearer key is never sent in clear text over a network.
+
+### Automatic documentation check
+
+On pi and omp, the run-end documentation check (disable with `JEV_TOOLS_AUTO_DOCS=0`) sends changed units from a dirty tree to the endpoint without an explicit tool call, including admitted untracked files that are not gitignored. Secret-named files are refused as above; anything else untracked and not ignored can be sent. Keep sensitive scratch files gitignored or outside the repository.
+
+Saved interactive configuration stores the API key in plaintext in a private user-level file (`~/.config/jev-agent-tools/config.json` by default). Privacy uses each operating system's own model: owner-only mode bits on POSIX; on Windows, an access list whose allow entries are only the current user, SYSTEM and Administrators, read by SID through the system Windows PowerShell. Protect the account and back-ups accordingly, or use environment variables from a secret manager instead.
+
+The MCP server (`jev-agent-tools-mcp`) has the same boundaries. It talks to its client only over stdio and opens no network listener. MCP client configuration files that contain a literal API key are as sensitive as the saved configuration; prefer the client's environment-variable interpolation and do not commit such files. Tool approval is the MCP client's responsibility; the server marks `jev_ask` as not read-only while commands are enabled.
+
+Command cancellation and timeout, and MCP connection shutdown, complete bounded termination of the managed process group on POSIX or await the system process-tree termination operation on Windows. This is cleanup, not containment: deliberately detached descendants or processes that escape that tree are not tracked, and previously completed side effects are not undone.
+
+Expected execution of an explicitly supplied command, intentional submission of evidence, inaccurate judgments, and ordinary bugs or feature requests are not by themselves security vulnerabilities. Report ordinary product problems through issues; report host or API-service vulnerabilities to their respective maintainers. If unsure about a jev-tools security impact, use the private form.

package/dist/adapters/analysis-context.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { tokenize, } from "../core/lexical.js";
+import { loadSyntaxRootParser } from "./syntax.js";
+/** Owns one invocation's source versions; never retains repository data across calls. */
+export async function createAnalysisContext(counter, sourceParser) {
+    const fingerprints = new Map();
+    const fingerprint = (text) => {
+        let value = fingerprints.get(text);
+        if (value === undefined) {
+            value = createHash("sha256").update(text).digest("hex");
+            fingerprints.set(text, value);
+        }
+        return value;
+    };
+    const lexical = new Map();
+    const tokenizeSource = (path, text, python = false) => {
+        const version = fingerprint(text);
+        let versions = lexical.get(path);
+        if (!versions) {
+            versions = new Map();
+            lexical.set(path, versions);
+        }
+        const key = `${version}:${python}`;
+        let tokens = versions.get(key);
+        if (!tokens) {
+            counter?.tokenized(path, version);
+            tokens = tokenize(text, python);
+            versions.set(key, tokens);
+        }
+        return tokens;
+    };
+    const source = sourceParser ?? (await loadSyntaxRootParser());
+    if (!source)
+        return {
+            parser: undefined,
+            fingerprint,
+            counter,
+            tokenize: tokenizeSource,
+        };
+    const roots = new Map();
+    const parser = {
+        supports: source.supports,
+        parseRaw(path, text) {
+            const version = fingerprint(text);
+            let versions = roots.get(path);
+            if (!versions) {
+                versions = new Map();
+                roots.set(path, versions);
+            }
+            let parsed = versions.get(version);
+            if (!parsed) {
+                counter?.parsed(path, version);
+                parsed = source.parseRaw(path, text);
+                versions.set(version, parsed);
+            }
+            return parsed;
+        },
+        parse(path, text) {
+            const parsed = this.parseRaw(path, text);
+            if (!parsed.ok)
+                return parsed;
+            return parsed.root.find({ rule: { kind: "ERROR" } })
+                ? { ok: false, error: "Source syntax incomplete" }
+                : parsed;
+        },
+        declarations: source.declarations,
+    };
+    return {
+        parser,
+        fingerprint,
+        counter,
+        tokenize: tokenizeSource,
+        resolved: (path, text) => counter?.resolved(path, fingerprint(text)),
+    };
+}