Skip to content

v2.16.0

Choose a tag to compare

@github-actions github-actions released this 28 Oct 00:33
· 10 commits to main since this release
a32a0b0

[2.16.0] - 2026-10-27

Added

  • PostToolUseFailure and PermissionDenied hooks (vaara hook post-tool-use-failure, vaara hook permission-denied), registered by vaara init and by the plugin's hooks.json, so a call that failed or that the host refused no longer reads as allowed with no outcome. A failed call gets an outcome_recorded with severity 0.7 (1.0 when interrupted) whose description says so. A call the host's permission step refused after Vaara allowed it gets one saying it did not run, and the scorer does not learn from it. The host's error text and denial reason are not copied. Claude Code sends PermissionDenied only in auto mode, and whether it does while these hooks are installed has not been checked on a live session. The bundled Python fallback does not record these two events, and an existing install needs vaara init run again to register them.
  • Reviewer-signed review resolutions. vaara review resolve --sign-key PEM --audit-db AUDIT.db (and ReviewQueue.resolve(reviewer_key=...)) has the reviewer sign the resolution with their own EC P-256 or RSA key over the action's decision record hash, the resolution, the reviewer and the justification (vaara.review-resolution/v1); the escalation_resolved record carries the signature under reviewer_signature and never a key. A signed vaara.permission/v1 can pin reviewer keys in an optional reviewers list, omitted when empty, so existing permissions sign and digest unchanged. vaara trail check-permission and check_review_resolutions check each resolution of a call under the permission against the pinned key and report it as signed, unsigned, unpinned, unknown_reviewer, bad_signature, decision_mismatch or malformed; an allow over a denied or escalated decision is marked override for that action only. Unsigned resolutions are a finding only when the permission names reviewers, and unsigned rows hash as before.
  • A delegating action can name who may act under it. intercept(delegatees=[...]) records the named agent ids as delegatees in the hash-covered request, and a child whose parent_action_id points at that action is denied unless its agent_id is one of them, with policy_id delegatee_binding and violation_type delegation_binding, whatever the scorer said and even when its grant attenuates the parent's. Knowing a parent's action id is no longer enough to act as its child. InterceptionPipeline(require_delegatee_binding=True) also denies a child whose parent named nobody (parent_unbound) or that the pipeline never saw (parent_unknown); it is off by default, and the policy state carries it only when on, so earlier policy digests are unchanged. A request without delegatees hashes as before. The delegation graph reads the binding back: DelegationGraph.binding_of(action_id) is root, bound, substituted, unbound, dangling, cycle or unknown, and substituted and unbound list the hops that are not bound. A decision receipt grades the new ground as evaluated. tests/test_delegatee_binding.py carries the three-hop vector with the hop-2 delegate substituted.
  • A signed erasure record. vaara trail erase takes --legal-ground TEXT, --erased-by WHO and --sign-key PEM; the record_erased record then carries legal_ground, erased_by, erased_at and an eraser_signature block (type, alg, signature, never a key) made with the eraser's own EC P-256 or RSA key over the erased record's id, hash, seq, event type and action id, the reason, the legal ground, the eraser and the time (vaara.record-erasure/v1, RFC 8785). --sign-key needs --erased-by. vaara trail verify --erasure-key PEM, vaara-audit verify --erasure-key PEM, verify_signed(erasure_key=...) and check_erasures report each erasure as signed, unsigned, unpinned, bad_signature or malformed (VerifyResult.erasures); bad_signature and malformed fail verification, and so does unsigned when an erasure key is given. An erasure without the new options writes the same record as before, so existing trails and exports verify unchanged.
  • Cage launches leave a start and a stop on the trail. vaara cage run, vaara cage stop and vaara run write a cage_lifecycle record when a launch starts (driver, launch name, policy digest, the operator) and when it ends (why: exited, operator or guard_gone; the exit code and, when the OS guard goes away under vaara run, how many processes were ended). A stop names the start it closes when that start is on the trail, and the trail refuses a stop that names any other record. A record that cannot be written is reported on stderr and never stops or keeps a cage. verify_signed fails a signed export whose stop names a record that is not an earlier start of the same launch, and lists the launches (VerifyResult.cage_lifecycle), starts no stop closes (cage_open) and stops whose start is outside the export (cage_unpaired_stops); vaara trail verify and vaara-audit verify print them, and vaara-audit verify --json carries all three.
  • docs/supported-platforms.md lists the operating systems the full suite has been run on, with the Python build, the commit, the date and the result. First row: SUSE Linux Enterprise Server 15 SP6 (SLE BCI base 15.6, Python 3.12.12 and SQLite 3.50.2 from the public SLE BCI repository, no registration), 6157 passed, 0 failed; pip install vaara==2.15.0 from PyPI ran on the same system. A test fails the page when a row lacks the commit or the date.
  • docs/supported-platforms.md lists Red Hat Enterprise Linux 9 as a supported platform: Python 3.12 from the RHEL 9 repositories, the tests-rhel CI job on UBI 9, and the UBI 9 Containerfile in packaging/ubi9/. A rerun of the suite on RHEL 9 needs Node.js 20 for the browser verifier tests, since the default Node.js 16 lacks a global crypto. The tested table gains RHEL 9.8 (SELinux enforcing, unregistered, Python 3.12.15 and SQLite 3.34.1 from Red Hat's repositories), commit 0cdb8b6, 5996 passed, 0 failed. OpenShift is not listed.
  • A decision says whether its writer could have stopped the action. record_decision(enforcement=...) and intercept(enforcement=...) write could_block, shadow or recorded_only into the decision record, and the signed receipt evidence carries it as enforcement. The pipeline writes could_block when it enforces and shadow when it does not; the Claude Code hook records its deny-rule verdicts as could_block, or shadow in shadow mode; the MCP proxy marks perimeter denies and filtered reads could_block and forwarded methods, notifications and tool-list changes recorded_only; vaara run egress decisions are could_block. An unknown word is left out with a warning. vaara receipt verify-decision prints verified blocks as stopped, shadow, recorded only and mode not recorded, and its --json rows carry enforcement; a signed word outside the three counts as not recorded. A record written without a mode has no key, so existing trails, receipts and vectors verify unchanged. New vectors in tests/vectors/enforcement_v0/: one receipt per mode, one with no mode, and a shadow deny edited after signing to read as a stop.
  • toolhive-audit-event source profile. vaara ingest recognizes the JSON log line the ToolHive MCP proxy writes for each operation (msg is audit_event and an audit_id is present) and seals it on the outcome plane, with the audit id, event type, logged time, outcome, component, subjects and target lifted as advisory context. The line carries no signature, digest or chain, so the gap report keeps alg, signature, backLink, receiptAsserted and outcomeDerived as missing, and the outcome stays the producer's word. Custody starts at ingestion. The profile is a JSON spec with no new code; it adds a fixture to tests/vectors/normalize_v0/ and one case to the ingest_v0 corpus, and the existing cases are unchanged.
  • A trail that stopped recording says so on the chain. The first write that lands after the audit store refused writes is followed by a trail_not_recording record: how many writes were refused (a lower bound), from when to when, and which record landed first afterwards. vaara trail verify, vaara-audit verify (and its --json) and scripts/verify_vaara_trail.py list each window and fail a record with a nonsense count, time or record id. If the mark itself is refused the outage stays open and the next good write tries again. Nothing is written if the store never recovers, and a process that ends before the first good write loses the marker.
  • Digest-only capture. An operator lists argument fields in ~/.vaara/capture.json, or in the file VAARA_CAPTURE_POLICY names: a tool glob, dotted field paths where a * segment takes every key or list item, and an optional reference. The action_requested row, the modified_parameters of a modify decision, the review queue copy and the approval request file then hold each declared value as {"captured": "digest-only", "digest": "hmac-sha256:...", "reference": ...}; the value itself is not written. The digest is keyed with keys/capture-hmac.key beside the policy file (mode 0600), which is never written to the trail, so a holder of the trail cannot confirm a guessed value and the operator can. It applies through the pipeline, the Claude Code hook, the MCP proxy and the shell proxy. A policy that cannot be read, or a key that cannot be made, withholds the value; the clear value is never written. Not masked: the engine's reason text, tool results, outcome feedback, reviewer free text and records written before the policy existed. A decision receipt's argumentsCommitment covers the arguments as recorded, so with capture on it covers the masked form. With no policy file nothing changes, and vaara trail verify and vaara trail erase are unchanged. New suite capture_digest_only_v0 with a checker that imports no Vaara code; see docs/capture-digest-only.md.
  • A signed rotation record. vaara trail rotate appends a trail_rotated record before it purges: the hash the first surviving record links to, how many records went, and the archive's SHA-256, record count and kind (zip or sealed), signed with the key that signs the archive (vaara.trail-rotation/v1, Ed25519). The purge takes the unbroken prefix of records older than the window. vaara trail verify, vaara-audit verify, scripts/verify_vaara_trail.py and the walks of a live store accept a first record that links to such a record and report begins at a rotation seam: N records archived as <sha256>; a first record that links to nothing stays a chain break. --archive checks an archive against the record's digest (a sealed one by digest alone) and --rotation-key names the signer when it is not the zip's own key. A store that refuses the record skips the purge. With --tenant the record is written into that tenant's chain, and rotation refuses, purging nothing, when another tenant's records are interleaved in it. vaara trail purge on its own says that nothing accounts for what it removed and points at vaara trail rotate. The trail_rotation_v0 conformance suite (14 cases, a checker that imports no Vaara code) covers the link rule, the signature and the archive digest; the corpus is now 55 suites.

Fixed

  • The Claude Code hook binds a call's outcome to that call. PreToolUse records the host's tool_use_id in the request's context and PostToolUse reports against the request that carries it, once. It used to take the latest request with the same agent and tool name, so two calls of one tool in flight put both outcomes on the second call and none on the first, and a repeated report gave one call two outcomes. An id that matches no request records nothing; a request recorded without an id still matches by tool name, latest without an outcome first. The bundled fallback scripts do the same. A host that sends no id gets the record it got before.

  • An approval binds the call's arguments. When a request carries parameters, write_decision signs vaara-approval/v2: HMAC-SHA256 over the context, action id, nonce, parameters_sha256 and decision, one per line. request_approval checks it against the digest it computed itself, so a decision made over other arguments is ignored and the request times out. write_decision refuses a request whose shown parameters no longer hash to its parameters_sha256. A v1 decision still answers (the macOS app signs v1 today) and is reported as not bound. request_approval returns an ApprovalAnswer, a str with parameters_sha256 set when the decision was bound; the Claude Code hook writes that digest into the resolution's justification. New helper parameters_digest; vectors in tests/fixtures/approval_v2/vectors.json. Requests without parameters sign and verify as before.

  • vaara trail verify and scripts/verify_vaara_trail.py print what an OK covers on the line after it: signatures and the chain interior. A tail dropped before the export was signed is not detected without an anchor or seal, as docs/prove-what-an-ai-agent-did.md says. Output change only; no format or vector change.

  • The shell egress rules (shell_netcat_egress, shell_copy_egress) no longer read quoted text that only gets printed or searched. A quoted argument of echo, printf, grep or rg is skipped when the command runs at top level and its output goes only to filters, a file or the screen. It is still matched when the output pipes into a shell, ssh or xargs, sits inside a subshell or substitution, or lands in a file that a later statement runs.

  • shell_netcat_egress no longer reads an escape such as \n followed by cat (in printf 'id\ncat ...') as the tool name. An unquoted \ncat at the start of a command still matches, since the shell drops the backslash.

  • interpreter_network_egress no longer fires on urllib.parse or urllib.error, which open no connection. urllib.request, urllib2 and urllib3 still match.

  • scripts/verify_vaara_trail.py accepts a trail that carries vaara trail erase erasures. It used to report every erased slot as a tampered record. It now gives the verdict vaara trail verify gives: the slot reads as erased (link verified, content not checkable), a tombstone that no later record_erased record names is still a hash mismatch, and the new --erasure-key PEM checks each eraser's ES256 or RS256 signature (an unsigned or wrongly signed erasure fails when the key is given). The script still imports no Vaara code.

  • scripts/verify_vaara_trail.py pairs cage stops with their starts, as vaara trail verify does. It used to skip cage_lifecycle records, so a signer could pass an export with a stop that names another launch's start, or a stop written before its start. Each stop must now name the start of the same driver and launch, written earlier in the chain, or the run fails; starts with no stop and stops whose start is outside the export are listed and do not fail it. The cage lines print after the erasure lines. Standalone-script change only; no format or vector change.

  • vaara trail verify and scripts/verify_vaara_trail.py refuse a trail line or manifest that repeats a member of one object, and a number with no finite value (NaN, Infinity, -Infinity, or a literal such as 1e999). A repeated member reads as its last value to Python and its first to a first-wins parser, and the hash covers only one of them, so a signed export could print Verification: OK while a second reader saw a different call. A bare NaN ended in an uncaught ValueError with no FAILED listing. Both now fail the run as record N: duplicate member "x" or record N: non-finite number NaN (manifest.json: ... for the manifest). Records Vaara writes contain neither, so no existing export is affected. No format or vector change.

  • vaara trail verify and scripts/verify_vaara_trail.py fail a run on a trail line or manifest that is valid JSON but not an object ([1], 7, "x", null). Either verifier used to stop with an AttributeError and no FAILED listing. The run now fails as record N: not a JSON object or manifest.json: not a JSON object. A signature_algorithm that is not a string fails as unknown signature_algorithm: ..., a revocation block that is not an object fails the standalone script as manifest revocation block is not an object, and a record_erased, key_lifecycle or cage_lifecycle record whose data is not an object is read as empty data instead of raising. Records and manifests Vaara writes are objects, so no existing export is affected. No format or vector change.

  • vaara trail verify (verify_signed) checks the revocation registry the way scripts/verify_vaara_trail.py does. It never read revocation.json, so an export with a registry that did not match manifest.revocation.registry_sha256 printed Verification: OK there and FAILED offline. Both verifiers now fail the run, with the same words, when the file does not hash to the pinned digest, when the manifest declares a registry and the file is missing, when the file is present and the manifest declares none, and when the revocation entry is not an object. An export that pins no registry has neither and verifies as before. No format or vector change.

  • docs/capabilities.md names the code that does GDPR Article 17 erasure. The line pointed at a read-time redaction in the SQLite backend, which was removed because a record presented with a different agent id than the stored one cannot be recomputed. It now names audit/erase.py, vaara trail erase and vaara trail verify --erasure-key, and says that receipts, the review queue and earlier exports are not reached. A new trail no longer creates the unused gdpr_redactions table. A trail an older version wrote keeps it and opens unchanged, and a salvage leaves it in the damaged copy.

  • vaara trail purge and vaara trail rotate scrub what they delete. The retention purge ran a plain DELETE, so the purged records stayed readable in the database file's free pages and in the -wal file. It now deletes with secure_delete on and truncates the WAL afterwards, as vaara trail erase does. When another process holds the trail open and the WAL cannot be truncated, both commands say so on stderr and the purged bytes stay in the -wal file until the next checkpoint. SQLiteAuditBackend.last_purge_scrubbed carries the result (None for a dry run or a purge that deleted nothing) and RotateResult.wal_scrubbed reports it for a rotation. Return values and the chain seam at the retention boundary are unchanged.

  • The MCP proxy and the shell proxy no longer run an allowed call whose decision record did not reach the audit store. A refused write was counted and the call ran, with nothing on the chain to say so. Both now compare the trail's failed-write count across the decision, try one repair at most every 30 seconds, and refuse a call that is still unrecorded: the MCP proxy answers a tool error with "type": "vaara_trail_not_recording" and does not forward it, vaara proxy shell exits 1 without running the command. --fail-open (fail_open=True on VaaraMCPProxy) runs it anyway and says so on every call; shadow mode never refuses. In a Claude Code session an mcp__* call that is scored and then not recorded is blocked like one that cannot be scored, and "fail_open": true or shadow mode lets it through. Shell, file and web calls on the hook stay fail-open.

  • vaara trail rotate ran once. The purge left the first surviving record linked to a record that was gone, so an export of the rotated trail failed verification at record 0 and the next rotation refused to run (exported chain did not verify at export time, purge skipped). The rotation record above accounts for that link, and a second rotation now runs.

  • The MCP proxy closes an allowed call whose upstream request raised with an outcome_recorded record that says what the proxy can say about it: not_sent (the request provably never left: a closed client, a refused address, a refused connection, a name that did not resolve), unobserved (the request may have reached the server and no reply was read, so the proxy cannot say whether the call ran) or failed (the server answered with an error status). The record holds the error class and no message, since a message can quote a response body. An error reply or a tool isError result is recorded as failed. A raise used to leave no outcome on the trail. The execution receipt keeps its closed status set and still says errored in all three cases, so an unobserved call is receipted as a failure.

  • docs/execution-receipts.md no longer says the execution receipt proves what happened. It records what the issuer observed happen, and the page now says so. The page also says that MCP pull request 2787, the SEP-2787 the receipt pairs with, was closed without being merged on 2026-09-22.

Security

  • The guardrails-ai extra excludes litellm==1.107.0, the release published to PyPI from an attacker-controlled repository on 2026-10-21. PyPI has pulled it; the exclusion keeps mirrors and caches from installing it through Vaara.
  • vaara llm-proxy redacts GitHub app installation (ghs_), refresh (ghr_) and fine-grained personal (github_pat_) tokens by default, alongside the ghp_, gho_ and ghu_ shapes it already covered.