@orygn/opa-mcp 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -17,6 +17,293 @@ not part of the public surface and may change in minor releases.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-26
+
+### Added
+
+- `conftest_test` accepts the `cyclonedx`, `groovy` and `jsonc` parsers,
+  which conftest offers and the closed list here lacked.
+
+### Changed
+
+- The bundled OPA is now 1.21.0, from 1.19.0. Three upstream changes reach
+  users through it. OPA reads YAML against the 1.2 core schema, so the bare
+  words `yes`, `no`, `on` and `off` in data files and `yaml.unmarshal` are
+  strings now rather than booleans; quote them or use `true` and `false`.
+  The type checker types an empty `{}`, `[]` or `set()` literal as empty and
+  checks `in` against the collection's type, so a policy that indexes,
+  iterates or tests membership in an empty literal now fails `rego_check`
+  with `rego_type_error` where it compiled before; OPA suggests
+  `count(x) == 0` for an emptiness test. Coverage reports from `rego_test`,
+  `rego_eval_with_coverage` and `rego_coverage_gaps` may tag a not-covered
+  range with a `kind` of `index_excluded` or `early_exit`, which says why
+  evaluation skipped it, at the cost of up to two extra evaluation passes
+  when coverage is requested. Nothing changes when `OPA_BINARY` or `PATH`
+  supplies the binary.
+- Node.js 22 or later is required. Node 20 reached end of life in April
+  2026, and the CI matrix now covers 22, 24 and 26, the last being what the
+  Docker image runs.
+- The Docker image ships Regal 0.42.0, from 0.30.0, and CI tests against
+  Regal 0.42.0 and conftest 0.70.1.
+
+### Fixed
+
+- `rego_security_audit` failed outright on Regal 0.31 and later, which refuse
+  a category no rule defines; the tool always enabled `security` as the home
+  for a project's custom rules. When Regal rejects it, the sweep runs again
+  with `bugs` alone.
+- `rego_fix` with `force: true` sent Regal 0.41 and later a flag those
+  releases deprecated, since they no longer refuse files with uncommitted
+  changes. The flag now goes only to a Regal that still has that check. The
+  tool's description names the nine rules Regal 0.42 can fix; it named the
+  five of 0.30.
+- The hint on `REGAL_NOT_FOUND` pointed at a Regal documentation site that
+  no longer resolves; it points at the project's page on openpolicyagent.org.
+- Regal's own update check is switched off in the subprocesses the server
+  runs (`REGAL_DISABLE_VERSION_CHECK`), so `mcp_server_info` and `rego_fix`
+  no longer make a network request through it.
+
+## [0.6.0] - 2026-09-07
+
+### Security
+
+- `rego_playground_share` created public Gists, listed on the account and
+  searchable, while the README described them as secret. Anyone who shared a
+  policy with it should assume the policy was public from the moment it was
+  posted. Gists are now secret unless `public: true` is passed: reachable by
+  their link, listed nowhere. The change is not retroactive: GitHub cannot make
+  an existing Gist secret, so a Gist created earlier that should not have been
+  public has to be deleted at github.com/gists and shared again.
+
+### Changed
+
+- `rego_bench` reports `iterations`, `nsPerOp`, `allocsPerOp` and
+  `bytesPerOp`, whole numbers as opa's own summary prints them, and keeps the
+  document opa printed under `raw` for a single run. Its fields `N`, `T`,
+  `Bytes`, `MemAllocs`, `MemBytes` and `Extra` were top-level before and now
+  sit under `raw`; the type had promised `iterations` and `metrics`, which
+  were never set. With `count` above one, `runs` holds every document and
+  `fastest` indexes the one the figures come from, so none is repeated.
+
+### Added
+
+- `rego_capabilities` takes a `builtins` filter of up to 100 names and returns
+  their full records under `builtins`, with a `matched` count and the
+  `missing` names. When the records would not fit the response cap it returns
+  `OUTPUT_TOO_LARGE` rather than a truncated result, and `names_only: true`
+  alongside it is refused as a contradiction; `names_only: false`
+  returns every record and is documented as needing the cap raised.
+
+### Fixed
+
+- Windows: a Rego module on a different drive from the server's working
+  directory was reported missing. The 0.5.0 drive-letter fix respelled data
+  documents relative to a working directory on their drive but left modules
+  absolute, since a module mounts at its own `package` whatever path it
+  arrives by. OPA still opens the module by the remainder after the colon, a
+  root-relative path it resolves against the drive the child is running on, so
+  a module on any other drive failed with a file-not-found. Every load path now
+  takes part in choosing the working directory; only data documents are
+  respelled.
+- Windows: `rego_check` with inline source and `rego_inspect` reported a
+  module missing when the server's temp directory was on a different drive
+  from its working directory, and `conftest_test` and `conftest_verify` failed
+  the same way through `--policy`. OPA and conftest open an absolute path by
+  the part after its first colon, resolved on the drive the process runs on;
+  each command now runs from the path's own drive. The configs under test are
+  read by conftest itself and may sit on any drive; a policy and a data
+  directory spread across two drives are refused with a message saying so.
+- The subprocess timeout is now hard on Linux and macOS. The SIGKILL escalation
+  fired on a flag Node sets when a signal is sent rather than when the child
+  ends, so a child that ignored SIGTERM hung the tool call for good, and a
+  wrapper script that left a grandchild holding the pipes kept the result from
+  ever settling. A child killed from outside the server is reported as
+  `SUBPROCESS_KILLED` naming the signal, not as a missing binary. On SIGINT or
+  SIGTERM the server now signals the children it started before exiting.
+- `rego_eval`, `rego_eval_with_explain`, `rego_eval_with_profile`,
+  `rego_eval_with_coverage`, `rego_compile_query`, `rego_explain_decision`: a
+  string input that happened to parse as JSON, such as `"42"`, `"true"` or a
+  quoted string, was retyped or unwrapped before evaluation. Strings now reach
+  the policy as strings; only an object or array that arrived serialized as a
+  string is still repaired, the way `rego_bench` and the server-management
+  tools already did.
+- `rego_fix`: a real run reported zero fixes and no changed files after
+  changing them, because only the dry-run wording of regal's summary was read.
+  Both forms are read now.
+- `opa_*` server tools: a request that OPA did not answer within
+  `OPA_MCP_HTTP_TIMEOUT_MS` was reported as `OPA_UNREACHABLE`, with a hint to
+  start a server that was already running. It is now `TIMEOUT`, naming the
+  limit, and the timer covers the response body as well as the headers.
+- `conftest_test`: a denial reported under `failOnWarn` came back as a tool
+  error rather than as a failed check, because conftest exits 2 for it. Any
+  exit code with results on stdout is now an outcome, and only output without
+  results is treated as a command error, whose message now carries conftest's
+  own text; `conftest_verify` shares that last part.
+- `rego_verify`: a policy that exhausted the Z3 WASM heap took the whole
+  server down, since the abort surfaced outside every try/catch. The solver is
+  now bounded at 768 MB, under a 1 GiB ceiling on Z3's allocations, so an
+  oversized problem comes back inconclusive.
+- `rego_verify`: a helper whose body contains a literal `false` was inlined as
+  an always-true body, so a rule that can never fire was reported proven always
+  true, and a negated literal (`not false`, `not true`) was read as the bare
+  one in helpers and rule bodies alike. Boolean literals are now read as what
+  they say, and a helper with a true default and a body that never holds is
+  recognised as always holding.
+- Every tool that evaluates Rego, including the Regal tools that run a
+  project's custom rules, now declares `openWorldHint: true` and no longer
+  claims `readOnlyHint`, since a policy's own `http.send` can reach, and write
+  to, a remote system. A client that gates on the hints will ask before running
+  one. The destructive and idempotent hints on those tools are left to the
+  spec's defaults, since a policy chooses its own HTTP method.
+- Docker: the `opa` and `regal` downloads in the image build are now checked
+  against the digests published with their releases. The image was described
+  as reproducible while nothing verified those downloads; the wording now says
+  what the build does.
+- `rego_security_audit` was described as running regal's `security` and
+  `bugs` categories; regal ships no `security` category, so that half of the
+  sweep matched nothing. The description now says what runs: the `bugs`
+  category, plus any custom rules a project places in a `security` category.
+- `rego_explain_undefined`: on the path where OPA's indexer skips the rule, the
+  blocking condition was chosen from each body expression evaluated on its own,
+  so an expression that needs an earlier local or a sibling rule came back
+  unevaluable and was blamed ahead of the guard that really failed. The body is
+  now evaluated as cumulative prefixes inside the rule's package, with its
+  imports, and the first condition that stops holding is the one reported; the
+  conditions after it are left unevaluated, as on the traced path.
+- `rego_check_schema` reported `valid: true` when `schemaPath` was a
+  directory, since opa reads a schema directory only through `schemas:`
+  annotations in the policy. A directory is now accepted when the policy
+  carries them (read from the source, or reported by `opa inspect` for files
+  on disk) and refused before opa runs when it does not, with the file form,
+  `inlineSchema` and the annotation named as the ways to make it work.
+- `opa_bundle_sign` reported `signed: true` for a `.tar.gz` archive after
+  writing a `.signatures.json` beside it, which OPA never reads, so the
+  archive stayed unsigned. An archive is now refused with a pointer to
+  `opa_bundle_build`, which produces a signed one. The `outputDir` input,
+  which only applied to archives, is gone.
+- `OPA_MCP_MAX_RESPONSE_BYTES` now bounds error envelopes as well as
+  results. An oversize error was sent whole with `truncated: true` set; its
+  details are now dropped first and its message cut last, so the code and
+  the message stay readable within the cap.
+  The cap bounds a success envelope's warnings as well, and
+  `OPA_MCP_MAX_RESPONSE_BYTES` refuses a value below 512, which sits above
+  the smallest complete envelope, rather than exceeding it.
+- The temp directory inline source is written to could appear in the error
+  details of a dozen tools, in the message a binary printed about the file.
+  Every error envelope now passes through the sanitiser, which also covers a
+  JSON-encoded spelling, a directory name with a space, the inline schema and
+  bundle-verify temp files, and takes linear time on any input.
+  The server's own temp directory is matched by its exact spelling first,
+  so no guess about where a path begins is involved for the files it writes.
+- `rego_explain_undefined` turned a spawn failure during its per-condition
+  evals or its parse step into a per-condition note or an empty analysis. A
+  binary that cannot run or a run that timed out now returns the tool's
+  `OPA_BINARY_NOT_FOUND` or `TIMEOUT` like every other tool.
+- `rego_explain_undefined` validated `inputPath` and then passed the argument
+  as written to opa instead of the resolved path.
+- The `*_BINARY` variables now refuse a relative path at startup, which the
+  README said they did, a drive-relative or root-relative name included; a
+  bare command name or an absolute path is accepted.
+- Docs: the install note described a missing-`opa` failure that the npm
+  package's bundled binary already prevents, and now says where it still
+  applies; CONTRIBUTING said input fields are `snake_case` when the surface
+  is `camelCase`; two prompts sent readers to `rego_describe_policy` for input
+  refs, which `rego_infer_input_schema` reports.
+- `rego_migrate_v1` reported a built-in that v1 removed, which fails type
+  checking in the `opa fmt --rego-v1` phase, as a parse failure with advice to
+  fix syntax. The type error opa gives is now the message, with a hint to
+  replace the built-in first; the description says so.
+- `rego_verify`: a quoted key holding a dot, `input["a.b"]`, and the nested
+  path `input.a.b` were treated as one field, so a rule reading both was
+  proved never true, and a witness for the quoted key was built as the nested
+  object. Paths are now rendered the way Rego writes them and read back the
+  same way.
+  The soundness fuzz now carries quoted keys, so it exercises this.
+- `conftest_test`, `conftest_verify`: an error from conftest named the temp
+  file an inline config or policy had been written to, a file the tool had
+  already removed. The path is replaced in stderr as it already was in the
+  results.
+- `rego_verify`: a witness holding a non-ASCII string came back in Z3's
+  escape text, one escape per byte, which OPA did not accept as the string
+  the policy compares against. The escapes are decoded now. A backslash in a
+  policy literal is escaped on the way into Z3, so a literal that spells such
+  an escape itself is no longer read as one.
+- Docs: the README now says an argument that fails a tool's input schema is
+  rejected by the MCP layer before the handler runs, names `rego_verify`'s
+  `kind` field, and describes `rego_suggest_fix` as returning suggestions with
+  a confidence level; the `opa://builtins` resource says which `opa` binary
+  it reflects.
+- `rego_verify`: a field compared as a string, number or boolean and also read
+  as the object holding a deeper field was modelled as two unrelated values,
+  so a rule no input can satisfy was reported satisfiable with a witness OPA
+  rejects. The solver now knows that a field the rule compared equal to a
+  scalar, or fed to a string built-in, is never present alongside a path
+  beneath it. A rule that compares such a field in any other way (an
+  inequality, an ordering, a bare read, a comparison against another field)
+  and also reads beneath it is reported inconclusive, since the model gives
+  the field one scalar value that no input holding the deeper field can
+  match; before, that produced a counterexample OPA rejects. Both readings
+  are taken from the rule under test alone, so another rule in the module
+  does not decide either.
+- `rego_verify` built its witness from every input path in the policy, so a
+  field only another rule reads was given a value and placed in the input.
+  Where that field was the parent of one the rule under test reads, the two
+  collided and the witness no longer satisfied the rule: `allow if input.x.y
+  == 2` beside `other if input.x > 1` returned `{"x": 0}`, which the policy
+  evaluates to undefined, and reported it as proof the rule can be true. A
+  witness now names only the fields its own rule reads. The witness
+  search that prefers every field present also re-checks after backing out,
+  rather than reading a stale model.
+- `rego_test` with `coverage` or `threshold` and `count` above 1 returned no
+  coverage and reported the threshold as met: opa prints one report per
+  repetition and the concatenation did not parse as JSON, so none was read.
+  One is read now.
+- `rego_test_multiroot` in coverage mode reported a root holding a `todo_`
+  test as failed and dropped its report, as `rego_test` used to; the report is
+  kept and the root passes.
+- `rego_generate_test_skeleton` referenced every rule the same way, so a
+  function rule made the generated file fail to compile and a set, object or
+  value rule was compared to `true`. Each stub now follows the rule's head: a
+  function is called with placeholder arguments, a set or object is compared
+  to an empty one, a value rule to its literal when the head is one; a
+  computed head, which offers nothing to assert, becomes a `todo_test_` that
+  opa test skips rather than a placeholder that passes. The generated file no longer
+  imports the package it references by full path, which `opa check --strict`
+  reported as an unused import.
+- A username and password embedded in `OPA_URL` were echoed into every
+  `opa_*` error envelope and the startup log, and made every call fail as
+  `OPA_UNREACHABLE`, since the HTTP client refuses such a URL. They are now
+  redacted wherever the URL is shown, and such a URL is refused with
+  `OPA_URL_INVALID` and a hint to use `OPA_TOKEN`.
+  Only the credentials are removed from the URL shown; its case, port and
+  path stay as the operator wrote them.
+- `rego_verify` never gave the Z3 engine's memory back: its solver and
+  model were left to the JavaScript collector, which cannot see Z3's heap and
+  so had no reason to run, and the engine grew by half to one megabyte per
+  solve until its ceiling, between 600 MB and 1.7 GB over 1500 solves in the
+  same process depending on the run, with verdicts degrading to inconclusive
+  along the way. The solver is released as each solve ends, and its model
+  with it; 1500 solves now hold at about 210 MB.
+- `rego_verify` could fault Z3 intermittently, which disabled verification
+  until the server restarted: z3-solver frees its objects from finalizers on
+  the main thread while a solve runs on a worker over the same shared
+  memory, and one landing mid-solve corrupted the heap. Finalizers are now
+  held while a solve runs, and a fault brings up a fresh Z3 on the next call,
+  three times per process, with the interrupted call retried once.
+- The server reported itself as 0.4.0 on the 0.5.0 release, in the MCP
+  handshake, `mcp_server_info`, `--version` and the startup log: the version
+  was a constant kept apart from package.json. It is now read from
+  package.json, a test holds package.json, manifest.json and server.json to
+  one version, and a release stops before publishing when its tag names a
+  version package.json does not carry.
+- The startup warning and hint for a missing `regal` named `rego_lint` alone;
+  `rego_security_audit` and `rego_fix` need it too, and the manifest, the
+  registry entry and the Smithery config say so now. `--help` lists
+  `OPA_MCP_BLOCK_ENV`. `conftest_verify` said an omitted `namespace` both
+  defaulted to `main` and verified all namespaces; it verifies all.
+  `rego_check_schema` and `rego_playground_share` describe the schema
+  directory form and the `public` field they already had.
+
 ## [0.5.0] - 2026-09-04
 
 ### Security
@@ -1364,7 +1651,10 @@ wrappers end-to-end. CI matrix: Ubuntu, macOS, and Windows on Node
 20 and 22, plus CodeQL security scanning and weekly Dependabot updates
 for npm, GitHub Actions, and Docker base images.
 
-[Unreleased]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.2.0...v0.2.1

package/README.md

@@ -22,10 +22,22 @@ environment.
 +--------------------+  52 tools  +-----------------+            +---------------------+
 ```
 
-> **Status:** v0.4.0. Tool surface, error codes, and
+> **Status:** v0.7.0. Tool surface, error codes, and
 > environment variables follow [SemVer](https://semver.org/) from
 > v0.1.0 forward.
 
+> **Upgrading to 0.7.0:** Node.js 22 or later is required. The bundled OPA
+> is 1.21, which reads YAML against the 1.2 schema: bare `yes`, `no`, `on`
+> and `off` in data files are strings now, not booleans. If you supply your
+> own binary via `OPA_BINARY` or `PATH`, only the Node requirement applies.
+
+> **Upgrading to 0.6.0:** `rego_bench` reports `iterations`, `nsPerOp`,
+> `allocsPerOp` and `bytesPerOp`. The fields opa prints (`N`, `T`, `Bytes`,
+> `MemAllocs`, `MemBytes`, `Extra`) were top-level and now sit under `raw`
+> for a single run, so anything that read them from the top level has to
+> look there. With `count` above one, `raw` is omitted: every document is in
+> `runs`, and `fastest` indexes the one the top-level figures come from.
+
 > **Upgrading to 0.4.0:** subprocesses no longer inherit the server's
 > environment. A policy that read a variable through `opa.runtime().env`
 > will no longer see it; name the variable in `OPA_MCP_PASSTHROUGH_ENV` if
@@ -216,11 +228,15 @@ The image is multi-arch (`linux/amd64`, `linux/arm64`), bundles pinned
 versions of `opa` and `regal`, and runs as a non-root user. No host
 install of OPA or Regal is required.
 
-### ⚠ First-time install gotcha (read this if you used `npx` or the global install)
+### ⚠ If every tool call returns `OPA_BINARY_NOT_FOUND`
 
-If your client's `PATH` doesn't include the directory where `opa` lives
-(this happens with Claude Desktop on Windows and macOS by default), the
-server boots fine but every tool call returns `OPA_BINARY_NOT_FOUND`.
+The npm package carries its own `opa` for the five platforms it is built
+for, so a client `PATH` without `opa` on it does not matter there. The MCPB
+has no bundled copy, and on any other platform neither does npm: then the
+server boots but every tool call returns `OPA_BINARY_NOT_FOUND`. Neither the
+npm package nor the MCPB bundles `regal` or `conftest`, and the Docker image
+ships `regal` but not `conftest`, so their tools need a `PATH` entry or an
+explicit path either way.
 
 **Fix:** add `OPA_BINARY` and `REGAL_BINARY` env entries to your client
 config with the absolute path to each binary. The example configs under
@@ -257,17 +273,18 @@ variable is optional; defaults are sensible for a local OPA on
 | `OPA_MCP_ALLOWED_PATHS`        | _(unset)_                    | Comma- or semicolon-separated list of directories the server is allowed to read policies from. **When unset, file-based tools refuse to read from disk.**                                                                                                                                    |
 | `OPA_MCP_LOG_FILE`             | `<tmpdir>/orygn-opa-mcp.log` | Path the server appends logs to. The server never writes to stdout; that channel is reserved for the MCP protocol.                                                                                                                                                                           |
 | `OPA_MCP_LOG_LEVEL`            | `info`                       | One of `debug`, `info`, `warn`, `error`.                                                                                                                                                                                                                                                     |
-| `OPA_MCP_MAX_RESPONSE_BYTES`   | `100000`                     | Hard cap on a single tool response. Larger payloads are truncated with a `__truncated: true` marker.                                                                                                                                                                                         |
+| `OPA_MCP_MAX_RESPONSE_BYTES`   | `100000`                     | Hard cap on a single tool response. Larger payloads are truncated with a `__truncated: true` marker. Values below 512 are refused.                                                                                                                                                           |
 | `OPA_MCP_TIMEOUT_MS`           | `30000`                      | Hard timeout for any spawned subprocess (`opa`, `regal`). After this, the child gets `SIGTERM` and then `SIGKILL`.                                                                                                                                                                           |
-| `OPA_MCP_HTTP_TIMEOUT_MS`      | `15000`                      | Timeout for HTTP requests to the OPA REST API.                                                                                                                                                                                                                                               |
+| `OPA_MCP_HTTP_TIMEOUT_MS`      | `15000`                      | Timeout for each request to the OPA REST API, from the connection attempt to the last byte of the response; reported as `TIMEOUT`.                                                                                                                                                           |
 | `OPA_MCP_NO_TELEMETRY`         | _(unset)_                    | Set to `1` to disable the anonymous startup ping. The ping sends the server version, OS platform, and a random install ID. The install ID is stored at `~/.orygn/opa-mcp/install-id` and is generated once on first run. No policy content or file paths are ever sent.                      |
 | `OPA_MCP_MAX_SUBPROCESS_BYTES` | `33554432` (32 MiB)          | Maximum bytes captured from a subprocess's stdout and stderr, counted separately. On overflow the stream is clamped, the child is stopped, and the tool returns `OUTPUT_TOO_LARGE`. Distinct from `OPA_MCP_MAX_RESPONSE_BYTES`, which trims the reply after the output is already in memory. |
 | `OPA_MCP_PASSTHROUGH_ENV`      | _(unset)_                    | Comma-separated variable names to pass through to `opa`, `regal` and `conftest`. Everything else is withheld. **Anything named here is readable by any policy the server evaluates**, via `opa.runtime().env`, so use it only for values that are safe in that position.                     |
 | `OPA_MCP_BLOCK_ENV`            | _(unset)_                    | Comma-separated variable names to withhold from `opa`, `regal` and `conftest` even when they are on the built-in allow-list. Applied last, so it also overrides `OPA_MCP_PASSTHROUGH_ENV`. Use it to drop the proxy variables, which can carry credentials, at the cost of proxy support.    |
 
-Paths in `OPA_MCP_ALLOWED_PATHS` and the `*_BINARY` variables must be
-absolute. Relative paths and missing binaries are rejected with structured
-errors.
+Paths in `OPA_MCP_ALLOWED_PATHS` must be absolute, and a `*_BINARY` value is
+either a bare command name looked up on `PATH` or an absolute path; anything
+else stops the server at startup. A binary that cannot be run is reported by
+each tool call with a structured error.
 
 ## Tool reference
 
@@ -283,7 +300,7 @@ Stable error codes: `INVALID_INPUT`, `INVALID_REGO`, `INVALID_BUNDLE`,
 `CONFTEST_NOT_FOUND`, `OPA_UNREACHABLE`, `OPA_AUTH_FAILED`,
 `POLICY_NOT_FOUND`, `DATA_NOT_FOUND`, `PATH_NOT_ALLOWED`, `PATH_NOT_FOUND`,
 `NO_TESTS_FOUND`, `COVERAGE_BELOW_THRESHOLD`, `OPA_VERSION_UNSUPPORTED`,
-`GITHUB_TOKEN_MISSING`, `GIST_CREATE_FAILED`, `OUTPUT_TOO_LARGE`, `TIMEOUT`,
+`GITHUB_TOKEN_MISSING`, `GIST_CREATE_FAILED`, `OUTPUT_TOO_LARGE`, `SUBPROCESS_KILLED`, `OPA_URL_INVALID`, `TIMEOUT`,
 `CANCELLED`, `UNKNOWN_ERROR`.
 
 ### Category A: Authoring & static analysis
@@ -292,17 +309,17 @@ Operate on Rego source code without needing a running OPA server. Wrap
 `opa fmt`, `opa parse`, `opa check`, `opa inspect`, `opa capabilities`,
 `opa deps`, and `regal`.
 
-| Tool                | What it does                                                                                                                                                                                            |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rego_format`       | Format Rego source. Wraps `opa fmt`. Idempotent.                                                                                                                                                        |
-| `rego_check`        | Type-check and validate Rego. Wraps `opa check`.                                                                                                                                                        |
-| `rego_lint`         | Run Regal across a file or directory. Returns each violation with its category, level and location. **Requires `regal` on `PATH` or `REGAL_BINARY` set.**                                               |
-| `rego_parse_ast`    | Parse Rego to AST JSON. Wraps `opa parse`.                                                                                                                                                              |
-| `rego_inspect`      | Inspect a bundle or directory: packages, rules, annotations. Wraps `opa inspect`.                                                                                                                       |
-| `rego_capabilities` | List the built-ins and features the resolved `opa` binary understands (`OPA_BINARY`, then `PATH`, then the bundled copy)                                                                                |
-| `rego_deps`         | Static dependency analysis: rule-level data references and cross-package calls.                                                                                                                         |
-| `rego_migrate_v1`   | Migrate Rego v0 source to v1 syntax. Runs `opa fmt --rego-v1` then validates with `opa check --v1-compatible`. Returns `{ original, migrated, changed, valid, errors }`.                                |
-| `rego_check_schema` | Check Rego against a JSON Schema. Validates that every `input.*` field the policy reads exists in the schema using `opa check --schema`. Accepts inline schema or a path to a JSON Schema file on disk. |
+| Tool                | What it does                                                                                                                                                                                                                                                            |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rego_format`       | Format Rego source. Wraps `opa fmt`. Idempotent.                                                                                                                                                                                                                        |
+| `rego_check`        | Type-check and validate Rego. Wraps `opa check`.                                                                                                                                                                                                                        |
+| `rego_lint`         | Run Regal across a file or directory. Returns each violation with its category, level and location. **Requires `regal` on `PATH` or `REGAL_BINARY` set.**                                                                                                               |
+| `rego_parse_ast`    | Parse Rego to AST JSON. Wraps `opa parse`.                                                                                                                                                                                                                              |
+| `rego_inspect`      | Inspect a bundle or directory: packages, rules, annotations. Wraps `opa inspect`.                                                                                                                                                                                       |
+| `rego_capabilities` | List the built-ins and features the resolved `opa` binary understands (`OPA_BINARY`, then `PATH`, then the bundled copy); `builtins` names up to 100 to return full records for                                                                                         |
+| `rego_deps`         | Static dependency analysis: rule-level data references and cross-package calls.                                                                                                                                                                                         |
+| `rego_migrate_v1`   | Migrate Rego v0 source to v1 syntax. Runs `opa fmt --rego-v1` then validates with `opa check --v1-compatible`. Returns `{ original, migrated, changed, valid, errors }`.                                                                                                |
+| `rego_check_schema` | Check Rego against a JSON Schema. Validates that every `input.*` field the policy reads exists in the schema using `opa check --schema`. Accepts an inline schema, a path to a JSON Schema file, or a schema directory when the policy declares `schemas:` annotations. |
 
 #### Featured: `rego_format`
 
@@ -387,11 +404,11 @@ Run a query against a policy and input. Wrap `opa eval`, `opa test`, and
 
 Package, sign, and verify deployable bundles. Wrap `opa build`, `opa sign`, and `opa build --verification-key`.
 
-| Tool                | What it does                                                                                                                                                                                                            |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `opa_bundle_build`  | Build a `.tar.gz` bundle from a policy directory. Supports `optimize` and `revision`.                                                                                                                                   |
-| `opa_bundle_sign`   | Sign a bundle directory in place, or an archive beside itself, with a private key. A directory signature stays valid wherever the directory is placed under the same name. Returns the path, algorithm, and file count. |
-| `opa_bundle_verify` | Verify a signed bundle with a public key through `opa build --verification-key`. Failures name the reason: wrong key, scope, modified, added, missing or unparseable file, unsigned, or a bundle that does not load.    |
+| Tool                | What it does                                                                                                                                                                                                                                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `opa_bundle_build`  | Build a `.tar.gz` bundle from a policy directory. Supports `optimize` and `revision`.                                                                                                                                                                                                                    |
+| `opa_bundle_sign`   | Sign a bundle directory in place with a private key; an archive is refused, since OPA reads the signature from inside it, and comes signed from `opa_bundle_build`. A directory signature stays valid wherever the directory is placed under the same name. Returns the path, algorithm, and file count. |
+| `opa_bundle_verify` | Verify a signed bundle with a public key through `opa build --verification-key`. Failures name the reason: wrong key, scope, modified, added, missing or unparseable file, unsigned, or a bundle that does not load.                                                                                     |
 
 ### Category D: OPA server management
 
@@ -419,21 +436,21 @@ point at a reachable server.
 The differentiation surface. These compose lower-level primitives into
 the tasks agents are actually asked to do.
 
-| Tool                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rego_explain_decision`       | Turn an evaluation trace into a structured per-rule summary of what fired and what did not                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `rego_generate_test_skeleton` | Given a policy, generate a `_test.rego` skeleton covering each rule.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `rego_describe_policy`        | Summarize a policy's package, imports and per-rule structure from its AST. For the input references a policy reads, use `rego_infer_input_schema`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `rego_suggest_fix`            | For a failed `rego_check` or `rego_lint`, propose minimal patches.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `rego_coverage_gaps`          | Run `opa test --coverage` and return per-file uncovered line ranges, sorted worst first. Use `threshold` to focus on files below a target percentage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `rego_security_audit`         | Run regal lint restricted to `security` and `bugs` categories across a directory. Returns severity-grouped findings with remediation guidance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `rego_infer_input_schema`     | Statically analyse a policy (or directory of policies) with `opa parse` and return a JSON Schema describing every `input.*` field the policy reads. No running OPA required. Correct starting point for writing integration tests or configuring `opa check --schema`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `rego_fix`                    | Run `regal fix` to auto-apply mechanical fixes: `opa-fmt`, `use-rego-v1`, `use-assignment-operator`, `no-whitespace-comment`, and `directory-package-mismatch`. Use `dryRun: true` to preview changes first. Returns a per-file breakdown of which rules were applied and, for `directory-package-mismatch`, the new path the file was moved to.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `rego_format_write`           | Run `opa fmt --write` to canonically format one or more Rego files or directories in place. Use `dryRun: true` to list which files would change without modifying them. Validates all files parse successfully before writing any. Supports `regoV1`, `v0Compatible`, and `v1Compatible` flags. Only requires `opa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `rego_policy_diff`            | Evaluate the same query against two policies in parallel and compare the results. Returns `equal: true/false`, the raw value from each side (`resultA`/`resultB`), and `changedPaths` -- dot/bracket JSON paths that differ. Each side takes inline source or a file/directory path. Useful for verifying refactor equivalence or mapping divergence between two policy versions.                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `rego_verify`                 | Formally verify a property about a Rego rule using SMT solving (Microsoft Z3 via WASM). Unlike testing, this checks ALL possible inputs mathematically and either proves the property holds or returns a concrete counterexample. Supports `always_true`, `never_true`, and `satisfiable` property kinds. Handles equality, comparison, string built-ins (`startswith`, `endswith`, `contains`, `regex.match`), multi-clause rules, rule defaults, non-boolean head values, and cross-rule inlining. Reports `INCONCLUSIVE` rather than guessing for negation-as-failure, comprehensions, partial set and object rules, functions, else chains, and complex regex. A body reading an absent field is undefined rather than true, so `always_true` requires the rule to hold for an empty input too. |
-| `rego_explain_undefined`      | Explain why a Rego query is undefined. Combines a plain eval, a full-trace eval, and per-condition AST analysis to identify the exact body expression blocking each rule. Returns a structured breakdown of which conditions blocked each rule plus a human-readable summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `rego_playground_share`       | Publish a policy (and optional input) as a secret GitHub Gist and return the link, for sharing a reproduction. Requires `GITHUB_TOKEN` with the `gist` scope; returns `GITHUB_TOKEN_MISSING` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Tool                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rego_explain_decision`       | Turn an evaluation trace into a structured per-rule summary of what fired and what did not                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `rego_generate_test_skeleton` | Given a policy, generate a `_test.rego` skeleton covering each rule.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `rego_describe_policy`        | Summarize a policy's package, imports and per-rule structure from its AST. For the input references a policy reads, use `rego_infer_input_schema`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `rego_suggest_fix`            | For a failed `rego_check` or `rego_lint`, propose fix suggestions with a confidence level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `rego_coverage_gaps`          | Run `opa test --coverage` and return per-file uncovered line ranges, sorted worst first. Use `threshold` to focus on files below a target percentage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `rego_security_audit`         | Run regal lint restricted to its `bugs` category, plus any custom rules in a `security` category, across a directory. Returns severity-grouped findings with remediation guidance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `rego_infer_input_schema`     | Statically analyse a policy (or directory of policies) with `opa parse` and return a JSON Schema describing every `input.*` field the policy reads. No running OPA required. Correct starting point for writing integration tests or configuring `opa check --schema`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `rego_fix`                    | Run `regal fix` to auto-apply mechanical fixes: `opa-fmt`, `use-rego-v1`, `use-assignment-operator`, `no-whitespace-comment`, and `directory-package-mismatch`. Use `dryRun: true` to preview changes first. Returns a per-file breakdown of which rules were applied and, for `directory-package-mismatch`, the new path the file was moved to.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `rego_format_write`           | Run `opa fmt --write` to canonically format one or more Rego files or directories in place. Use `dryRun: true` to list which files would change without modifying them. Validates all files parse successfully before writing any. Supports `regoV1`, `v0Compatible`, and `v1Compatible` flags. Only requires `opa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `rego_policy_diff`            | Evaluate the same query against two policies in parallel and compare the results. Returns `equal: true/false`, the raw value from each side (`resultA`/`resultB`), and `changedPaths` -- dot/bracket JSON paths that differ. Each side takes inline source or a file/directory path. Useful for verifying refactor equivalence or mapping divergence between two policy versions.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `rego_verify`                 | Formally verify a property about a Rego rule using SMT solving (Microsoft Z3 via WASM). Unlike testing, this checks ALL possible inputs mathematically and either proves the property holds or returns a concrete counterexample. The `kind` field takes `always_true`, `never_true` or `satisfiable`. Handles equality, comparison, string built-ins (`startswith`, `endswith`, `contains`, `regex.match`), multi-clause rules, rule defaults, non-boolean head values, and cross-rule inlining. Reports `INCONCLUSIVE` rather than guessing for negation-as-failure, comprehensions, partial set and object rules, functions, else chains, and complex regex. A body reading an absent field is undefined rather than true, so `always_true` requires the rule to hold for an empty input too. |
+| `rego_explain_undefined`      | Explain why a Rego query is undefined. Combines a plain eval, a full-trace eval, and per-condition AST analysis to identify the exact body expression blocking each rule. Returns a structured breakdown of which conditions blocked each rule plus a human-readable summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `rego_playground_share`       | Publish a policy (and optional input) as a secret GitHub Gist (pass `public: true` to list it) and return the link, for sharing a reproduction. Requires `GITHUB_TOKEN` with the `gist` scope; returns `GITHUB_TOKEN_MISSING` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Category F: Conftest (configuration policy testing)
 
@@ -474,7 +491,14 @@ YAML/JSON/HCL/TOML/INI against Rego policies using
         "exceptions": []
       }
     ],
-    "summary": { "passed": 0, "failed": 1, "warnings": 0, "skipped": 0 }
+    "summary": {
+      "passed": 0,
+      "failed": 1,
+      "warnings": 0,
+      "skipped": 0,
+      "successes": 0,
+      "failures": 1
+    }
   }
 }
 ```
@@ -568,10 +592,12 @@ Agent: Done. Policy `rbac` is live on staging at $OPA_URL.
 │                          ├── tools/bundles/           ─┼─── lib/opa-cli.ts ──┐        │
 │                          ├── tools/server-management/ ─┤                     │        │
 │                          ├── tools/helpers/           ─┤                     │        │
+│                          ├── tools/conftest/          ─┤                     │        │
 │                          ├── tools/meta/              ─┘                     │        │
 │                          │                                                   ▼        │
 │                          │                              lib/subprocess.ts ──┴── opa   │
 │                          │                              lib/regal-cli.ts   ───── regal│
+│                          │                              lib/conftest-cli.ts ─ conftest│
 │                          │                              lib/opa-client.ts  ───── HTTP │
 │                          │                                                            │
 │                          └── lib/output.ts (envelope + truncation)                    │
@@ -586,12 +612,16 @@ Four things worth knowing if you're going to operate this:
 1. **stdout is the protocol channel.** The server logs to a file via
    `lib/logger.ts` and never writes to stdout. If you see stray stdout
    bytes, the client disconnects; the MCP transport layer is strict.
-2. **No tool throws.** Every tool catches its own exceptions and returns
-   a structured `{ ok: false, error: ... }` envelope. The agent sees a
-   stable error vocabulary, not a stack trace. Decoding subprocess output
-   happens inside an async callback, where a throw would bypass those
-   handlers entirely, so that path is bounded by bytes rather than left to
-   a `try`/`catch` that could not see it.
+2. **No tool handler throws.** Every handler catches its own exceptions and
+   returns a structured `{ ok: false, error: ... }` envelope, so the agent
+   sees a stable error vocabulary, not a stack trace. An argument that fails
+   the tool's input schema never reaches the handler: the MCP layer rejects
+   it and returns a tool result with `isError: true` whose text begins
+   `MCP error -32602: Input validation error:`, rather than the envelope.
+   Decoding subprocess output happens inside an async callback, where a throw
+   would bypass those handlers entirely, so that path is bounded by bytes
+   rather than left to a `try`/`catch` that could not see it.
+
 3. **Subprocesses are bounded in time, size, and environment.**
    `lib/subprocess.ts` runs the binaries with `shell: false`, a hard
    timeout with `SIGTERM`-then-`SIGKILL` escalation, and a per-stream byte
@@ -629,9 +659,23 @@ be exposed on the network.
   `OPA_MCP_PASSTHROUGH_ENV` opts individual variables back in.
 - `OPA_TOKEN` is never echoed in tool responses or log entries, and is not
   passed to any child process.
+- **Tools that evaluate Rego are annotated open-world and not read-only.**
+  `rego_eval` and its variants, `rego_test`, `rego_test_multiroot`,
+  `rego_bench`, `rego_compile_query`, `opa_exec`, the explain, diff and
+  coverage helpers, the conftest tools, and the Regal tools (`rego_lint`,
+  `rego_security_audit`, `rego_fix`, which run a project's custom rules) all
+  run Rego, and OPA's `http.send` lets a policy reach, and write to, any
+  network address. A client that gates on the hints will ask before running
+  one. `opa_query_decision` and `opa_compile_query` are the exception: the
+  remote OPA evaluates a policy it already holds, and their hints describe
+  what the call does to that server. No evaluating tool passes or accepts a
+  capabilities file, so `http.send` cannot be restricted for evaluation;
+  `rego_check` and `opa_bundle_build` accept one, which affects only checking
+  and building.
 - Releases are published with
   [npm provenance](https://docs.npmjs.com/generating-provenance-statements);
-  the Docker image is built reproducibly from the committed `Dockerfile`.
+  the Docker image is built from the committed `Dockerfile`, with pinned
+  versions of `opa` and `regal` checked against their published digests.
 
 To report a vulnerability, follow [SECURITY.md](./SECURITY.md). **Please
 do not open a public issue for security problems.**
@@ -694,6 +738,13 @@ path(s) you want the server to read from, comma-separated.
 `OPA_URL` (default `http://localhost:8181`) must point at a running OPA
 server (`opa run --server ...`). Check with `curl $OPA_URL/health`.
 
+**`TIMEOUT` when calling `opa_*` tools.**
+
+The request did not finish within `OPA_MCP_HTTP_TIMEOUT_MS` (default 15 s).
+Either OPA is up but slow, or nothing is answering at `OPA_URL` and the
+connection attempt is being dropped rather than refused, which looks the
+same from here. Check `OPA_URL` and the server's load, or raise the limit.
+
 **`directory-package-mismatch` violation when linting inline source.**
 
 Since v0.1.1, the server auto-disables this rule for inline-source calls.
@@ -729,8 +780,9 @@ npm run build             # compile to dist/
 ```
 
 CI runs lint, typecheck, build, and unit tests on every push and PR
-across Ubuntu and Windows on Node 20, 22 and 24, plus macOS on Node 22. Integration
-tests run on Linux against pinned `opa` and `regal` releases.
+across Ubuntu and Windows on Node 22, 24 and 26, plus macOS on Node 22. Integration
+tests run on Linux, and on Windows as a non-required check, against pinned
+`opa`, `regal` and `conftest` releases.
 
 For the full contributor workflow (adding tools, naming conventions,
 logging discipline, release process), see [CONTRIBUTING.md](./CONTRIBUTING.md).