/ 
Langertha-Raider-0.504
/ Langertha::Raider::AgentTools

NAME

Langertha::Raider::AgentTools - Internal subagent tools of raider: agent and send_message

VERSION

version 0.504

SYNOPSIS

my $agents = Langertha::Raider::AgentTools->new(
  catalog  => $context->agent_catalog,
  on_spawn => sub { my ( $agent, $call ) = @_; ...; return ( $text, $is_error ) },
  on_send  => sub { my ( $message ) = @_; ...; return ( $text, $is_error ) },   # optional
);
my $server = $agents->server;      # MCP::Server with agent (and send_message)
my $tools  = $agents->async_tools; # for Langertha::Raider/async_tools

DESCRIPTION

Internal module. Its interface may change without notice.

The agent tool of ADR 0020 §3 and ADR 0027 §10, shaped after Claude Code's Agent (formerly Task, both mapped by Langertha::Raider::ToolNames): the model hands a task to a subagent, which works in a context of its own -- in the foreground, answering with its last text, or in the background (run_in_background), announcing its end with a <task-notification> later. Beside it, when "on_send" is given, the send_message tool of ADR 0027 §5 (Claude Code's SendMessage) continues an agent by its ID or name.

The tools know the agents ("catalog"), check the call and describe every agent in the text; they start nothing themselves. "on_spawn" runs the subagent (Langertha::Raider::Subagent), "on_send" delivers a message. An unknown subagent_type, an empty prompt, a model that is not sonnet, opus or haiku and an isolation that is not worktree ("isolation_refusal", ADR 0032) are error results, and no subagent starts.

A raider runs both as asynchronous tools ("async_tools", ADR 0027 §9): the server carries their name, text and schema, the call itself goes to "call_f", whose Future the raider awaits, so a foreground agent runs on the loop without blocking it and several agent calls of one turn run at the same time. The code of the server's tools is the synchronous fallback for a raider without them: it waits for the Future on the loop (->get), so it must never run inside the loop.

catalog

The Langertha::Raider::Context::Agents the agents come from. Required.

on_spawn

Required. Called for every valid agent call as $on_spawn->($agent, { description => ..., prompt => ..., subagent_type => ..., model => ..., run_in_background => 0|1, name => ..., isolation => 'worktree' }, %ctx) (model, name and isolation only when given), with $agent the catalogue entry and %ctx the call's context ("async_tools" in Langertha::Raider; empty on the synchronous fallback); returns the tool result as ( $text, $is_error ), or a Future of it.

on_send

Called for every send_message call as $on_send->({ to => ..., message => ..., summary => ... }, %ctx); returns the tool result as ( $text, $is_error ), or a Future of it. Without it the server has no send_message.

server

The MCP::Server with the tool agent and, with "on_send", the tool send_message, built once.

async_tools

my $tools = $agents->async_tools;
# { agent => { code => ..., concurrent => 1 }, send_message => { code => ... } }

The tools as "async_tools" in Langertha::Raider: agent concurrent -- several calls of one turn run at the same time --, send_message (with "on_send") not. Each handler is "call_f" for its tool.

call_f

my $f = $agents->call_f( agent => $input, %ctx );   # Future of { content => [...], isError => ... }

One call of the tool agent or send_message with the model's arguments $input: checked as the server's tool checks them, then handed to "on_spawn" or "on_send" with %ctx. Resolves to the MCP result; an error of the call is an error result, never a failed Future.

model_aliases

The values the model parameter takes: sonnet, opus, haiku.

isolation_modes

The values the isolation parameter takes: worktree (ADR 0032).

isolation_refusal

my $text = $agents->isolation_refusal('sandbox');
# Error: isolation "sandbox" is not supported; use "worktree".

The error result of a call whose isolation is not one of "isolation_modes".

tools_label

my $label = $agents->tools_label($agent);   # '*', 'read_file, grep', 'All tools except bash'

What the tool text says an agent may use, in raider names: * for every tool of the caller, else the list of tools without disallowedTools, or All tools except ... when only disallowedTools restricts it.

description

The text of the agent tool, after Claude Code's current Agent text in raider's names: what it does, one line per agent (- name: description (Tools: ...)), when not to use it, and how -- background runs and their notifications, send_message to continue an agent, several calls in one message, isolation in a worktree.

send_description

The text of the send_message tool.

unknown

my $text = $agents->unknown('nope');

The error text for an unknown subagent_type, naming the available agents.

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/