/ 
Langertha-Raider-0.504
/ Langertha::Raider::PermissionChannel

NAME

Langertha::Raider::PermissionChannel - Internal client of the hall's permission channel: asks a call over a Unix socket, never answers yes by accident

VERSION

version 0.504

SYNOPSIS

# Internal to Langertha-Raider -- no API promise.
my $channel = Langertha::Raider::PermissionChannel->new(
  path      => $path,                          # --permission-channel PATH
  cancelled => sub { $app->run_cancelled },    # optional
);
$app->on_permission_request( $channel->callback );

DESCRIPTION

Internal module. Its interface may change without notice.

The raider's end of the channel the hall opens for a run that belongs to an ACP session (ADR 0021, Nachtrag P2). The hall starts the raider with the hidden option --permission-channel PATH; the application then sets "callback" as its on_permission_request, so a tool call the policy asks about is put to the ACP client instead of being refused.

The wire is JSON Lines over the Unix socket at path. The raider sends { id, tool, source, arguments, reason, rule } and blocks, like the REPL does for its question, until the hall answers { id, answer => 'once' | 'session' | 'no', reason }.

Deny by default. Every failure is the answer no, never once: the socket cannot be reached, it closes, the line is not JSON, the answer is none of the three words, nothing comes within "timeout", or the run is cancelled while the question is open (cancelled returns true: SIGINT of the hall's cancel). The hall answers within its own permission_timeout (default 120 s), so "timeout" is only the raider's last resort.

path

The Unix socket of the channel. Required.

timeout

Seconds after which the raider stops waiting and answers no (default 300). The hall's own timeout is shorter.

cancelled

Optional code that returns true when the run was cancelled; asked every quarter of a second while a question is open.

callback

$app->on_permission_request( $channel->callback );

A code reference for on_permission_request of Langertha::Raider::Application.

request

my $answer = $channel->request({ tool => 'bash', arguments => {...}, reason => '...', rule => 'Bash(make)' });
# { answer => 'once' | 'session' | 'no', reason => ... }

Asks the hall and waits. Never dies, never returns anything but one of the three answers.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests 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.

https://raudssus.de/