Repository navigation
v2.16.0
[2.16.0] - 2026-10-27
Added
PostToolUseFailureandPermissionDeniedhooks (vaara hook post-tool-use-failure,vaara hook permission-denied), registered byvaara initand by the plugin'shooks.json, so a call that failed or that the host refused no longer reads as allowed with no outcome. A failed call gets anoutcome_recordedwith 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 sendsPermissionDeniedonly 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 needsvaara initrun again to register them.- Reviewer-signed review resolutions.
vaara review resolve --sign-key PEM --audit-db AUDIT.db(andReviewQueue.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); theescalation_resolvedrecord carries the signature underreviewer_signatureand never a key. A signedvaara.permission/v1can pin reviewer keys in an optionalreviewerslist, omitted when empty, so existing permissions sign and digest unchanged.vaara trail check-permissionandcheck_review_resolutionscheck each resolution of a call under the permission against the pinned key and report it assigned,unsigned,unpinned,unknown_reviewer,bad_signature,decision_mismatchormalformed; an allow over a denied or escalated decision is markedoverridefor 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 asdelegateesin the hash-covered request, and a child whoseparent_action_idpoints at that action is denied unless itsagent_idis one of them, withpolicy_iddelegatee_bindingandviolation_typedelegation_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 withoutdelegateeshashes as before. The delegation graph reads the binding back:DelegationGraph.binding_of(action_id)isroot,bound,substituted,unbound,dangling,cycleorunknown, andsubstitutedandunboundlist the hops that are not bound. A decision receipt grades the new ground as evaluated.tests/test_delegatee_binding.pycarries the three-hop vector with the hop-2 delegate substituted. - A signed erasure record.
vaara trail erasetakes--legal-ground TEXT,--erased-by WHOand--sign-key PEM; therecord_erasedrecord then carrieslegal_ground,erased_by,erased_atand aneraser_signatureblock (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-keyneeds--erased-by.vaara trail verify --erasure-key PEM,vaara-audit verify --erasure-key PEM,verify_signed(erasure_key=...)andcheck_erasuresreport each erasure assigned,unsigned,unpinned,bad_signatureormalformed(VerifyResult.erasures);bad_signatureandmalformedfail verification, and so doesunsignedwhen 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 stopandvaara runwrite acage_lifecyclerecord when a launch starts (driver, launch name, policy digest, the operator) and when it ends (why:exited,operatororguard_gone; the exit code and, when the OS guard goes away undervaara 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_signedfails 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 verifyandvaara-audit verifyprint them, andvaara-audit verify --jsoncarries all three. docs/supported-platforms.mdlists 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.0from PyPI ran on the same system. A test fails the page when a row lacks the commit or the date.docs/supported-platforms.mdlists Red Hat Enterprise Linux 9 as a supported platform: Python 3.12 from the RHEL 9 repositories, thetests-rhelCI job on UBI 9, and the UBI 9 Containerfile inpackaging/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 globalcrypto. 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=...)andintercept(enforcement=...)writecould_block,shadoworrecorded_onlyinto the decision record, and the signed receipt evidence carries it asenforcement. The pipeline writescould_blockwhen it enforces andshadowwhen it does not; the Claude Code hook records its deny-rule verdicts ascould_block, orshadowin shadow mode; the MCP proxy marks perimeter denies and filtered readscould_blockand forwarded methods, notifications and tool-list changesrecorded_only;vaara runegress decisions arecould_block. An unknown word is left out with a warning.vaara receipt verify-decisionprints verified blocks as stopped, shadow, recorded only and mode not recorded, and its--jsonrows carryenforcement; 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 intests/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-eventsource profile.vaara ingestrecognizes the JSON log line the ToolHive MCP proxy writes for each operation (msgisaudit_eventand anaudit_idis 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 keepsalg,signature,backLink,receiptAssertedandoutcomeDerivedas 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 totests/vectors/normalize_v0/and one case to theingest_v0corpus, 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_recordingrecord: 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) andscripts/verify_vaara_trail.pylist 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 fileVAARA_CAPTURE_POLICYnames: a tool glob, dotted field paths where a*segment takes every key or list item, and an optional reference. Theaction_requestedrow, themodified_parametersof 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 withkeys/capture-hmac.keybeside 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'sargumentsCommitmentcovers the arguments as recorded, so with capture on it covers the masked form. With no policy file nothing changes, andvaara trail verifyandvaara trail eraseare unchanged. New suitecapture_digest_only_v0with a checker that imports no Vaara code; seedocs/capture-digest-only.md. - A signed rotation record.
vaara trail rotateappends atrail_rotatedrecord 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 (ziporsealed), 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.pyand the walks of a live store accept a first record that links to such a record and reportbegins at a rotation seam: N records archived as <sha256>; a first record that links to nothing stays a chain break.--archivechecks an archive against the record's digest (a sealed one by digest alone) and--rotation-keynames the signer when it is not the zip's own key. A store that refuses the record skips the purge. With--tenantthe record is written into that tenant's chain, and rotation refuses, purging nothing, when another tenant's records are interleaved in it.vaara trail purgeon its own says that nothing accounts for what it removed and points atvaara trail rotate. Thetrail_rotation_v0conformance 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_idin the request'scontextand 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_decisionsignsvaara-approval/v2: HMAC-SHA256 over the context, action id, nonce,parameters_sha256and decision, one per line.request_approvalchecks it against the digest it computed itself, so a decision made over other arguments is ignored and the request times out.write_decisionrefuses a request whose shownparametersno longer hash to itsparameters_sha256. A v1 decision still answers (the macOS app signs v1 today) and is reported as not bound.request_approvalreturns anApprovalAnswer, astrwithparameters_sha256set when the decision was bound; the Claude Code hook writes that digest into the resolution's justification. New helperparameters_digest; vectors intests/fixtures/approval_v2/vectors.json. Requests without parameters sign and verify as before. -
vaara trail verifyandscripts/verify_vaara_trail.pyprint 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, asdocs/prove-what-an-ai-agent-did.mdsays. 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 ofecho,printf,greporrgis 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,sshorxargs, sits inside a subshell or substitution, or lands in a file that a later statement runs. -
shell_netcat_egressno longer reads an escape such as\nfollowed bycat(inprintf 'id\ncat ...') as the tool name. An unquoted\ncatat the start of a command still matches, since the shell drops the backslash. -
interpreter_network_egressno longer fires onurllib.parseorurllib.error, which open no connection.urllib.request,urllib2andurllib3still match. -
scripts/verify_vaara_trail.pyaccepts a trail that carriesvaara trail eraseerasures. It used to report every erased slot as a tampered record. It now gives the verdictvaara trail verifygives: the slot reads as erased (link verified, content not checkable), a tombstone that no laterrecord_erasedrecord names is still a hash mismatch, and the new--erasure-key PEMchecks 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.pypairs cage stops with their starts, asvaara trail verifydoes. It used to skipcage_lifecyclerecords, 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 verifyandscripts/verify_vaara_trail.pyrefuse 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 as1e999). 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 printVerification: OKwhile a second reader saw a different call. A bareNaNended in an uncaught ValueError with no FAILED listing. Both now fail the run asrecord N: duplicate member "x"orrecord 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 verifyandscripts/verify_vaara_trail.pyfail 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 asrecord N: not a JSON objectormanifest.json: not a JSON object. Asignature_algorithmthat is not a string fails asunknown signature_algorithm: ..., arevocationblock that is not an object fails the standalone script asmanifest revocation block is not an object, and arecord_erased,key_lifecycleorcage_lifecyclerecord whosedatais 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 wayscripts/verify_vaara_trail.pydoes. It never readrevocation.json, so an export with a registry that did not matchmanifest.revocation.registry_sha256printedVerification: OKthere 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 therevocationentry is not an object. An export that pins no registry has neither and verifies as before. No format or vector change. -
docs/capabilities.mdnames 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 namesaudit/erase.py,vaara trail eraseandvaara trail verify --erasure-key, and says that receipts, the review queue and earlier exports are not reached. A new trail no longer creates the unusedgdpr_redactionstable. A trail an older version wrote keeps it and opens unchanged, and a salvage leaves it in the damaged copy. -
vaara trail purgeandvaara trail rotatescrub 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-walfile. It now deletes withsecure_deleteon and truncates the WAL afterwards, asvaara trail erasedoes. 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-walfile until the next checkpoint.SQLiteAuditBackend.last_purge_scrubbedcarries the result (Nonefor a dry run or a purge that deleted nothing) andRotateResult.wal_scrubbedreports 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 shellexits 1 without running the command.--fail-open(fail_open=TrueonVaaraMCPProxy) runs it anyway and says so on every call; shadow mode never refuses. In a Claude Code session anmcp__*call that is scored and then not recorded is blocked like one that cannot be scored, and"fail_open": trueor shadow mode lets it through. Shell, file and web calls on the hook stay fail-open. -
vaara trail rotateran 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_recordedrecord 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) orfailed(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 toolisErrorresult is recorded asfailed. A raise used to leave no outcome on the trail. The execution receipt keeps its closed status set and still sayserroredin all three cases, so an unobserved call is receipted as a failure. -
docs/execution-receipts.mdno 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-aiextra excludeslitellm==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-proxyredacts GitHub app installation (ghs_), refresh (ghr_) and fine-grained personal (github_pat_) tokens by default, alongside theghp_,gho_andghu_shapes it already covered.