NAME
Langertha::Raider::Approval - Internal approval of one exact tool call, bound to session, run, tool, arguments and policy revision
VERSION
version 0.503
SYNOPSIS
# Internal to Langertha-Raider -- no API promise.
my $approval = Langertha::Raider::Approval->for_call(
session_id => $session->id,
run_id => $run,
policy_revision => $revision,
call => { name => 'write_file', source => 'engine:1', arguments => \%args },
);
# later, for the call about to run -- same named arguments:
run_it() if $approval->covers(
session_id => $session->id, run_id => $run, policy_revision => $revision, call => $call,
);DESCRIPTION
Internal module. Its interface may change without notice.
An approval as ADR 0005 binds it: to one session, one run, one tool (by name and source) and one set of arguments, under one policy revision. Any change of any of these invalidates it -- fixture F20: arguments changed after the approval are not covered by it. The arguments are held as the SHA-256 of their canonical JSON ("digest_arguments"), never by reference, so a hash changed in place after the approval is seen as changed.
The call is the canonical call the tool gate sees ({ name => ..., source => ..., arguments => ... }, see _tool_gate in Langertha::Raider). This class is pure logic: nothing asks for an approval or consults one yet, and an approval lives only as long as the run that holds it -- nothing persists it.
session_id
The session the approval was given in. Required.
run_id
The run the approval was given in. Required.
tool
The name of the approved tool. Required.
source
Where the approved tool runs, as the tool gate names it (raider, inline, engine:N, catalog:NAME). Required: the same tool name from another source is another tool.
arguments_sha256
The "digest_arguments" of the approved arguments. Required.
policy_revision
The revision of the policy the approval was given under. Required; compared as a string.
for_call
my $approval = Langertha::Raider::Approval->for_call(
session_id => $sid, run_id => $rid, policy_revision => $rev,
call => { name => $tool, source => $source, arguments => $args },
);Builds the approval of call in its context. Croaks when call is not a hash, or when the session id, run id, policy revision, tool name or source is missing. arguments may be absent; it is then bound as null, which is not the same as {}.
covers
if ( $approval->covers( session_id => $sid, run_id => $rid,
policy_revision => $rev, call => $call ) ) { ... }True when the call in its context is exactly the approved one: same session, run, tool, source, policy revision and canonical arguments. False on any difference, and false when any of them is missing -- a missing field never matches. Croaks only when call is not a hash.
digest_arguments
my $hex = Langertha::Raider::Approval->digest_arguments(\%args);The SHA-256 (hex) of the canonical JSON of $arguments: hash keys sorted at every depth, arrays in order, UTF-8. Before encoding, every plain scalar is taken by its string form, so 5 and "5" are the same argument -- the digest does not depend on whether Perl last used a value as a number or a string, nor on how the JSON backend writes numbers. "1.0" and "1" stay different. Booleans ("is_bool" in JSON::MaybeXS) stay booleans and undef stays null, so true, 1, "true", false, 0, "", and null are all different. Croaks on anything JSON arguments cannot hold: code refs, objects other than booleans, scalar refs.
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-raider/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.