/ 
Langertha-Raider-0.504
/ Langertha::Raider::WorktreeTools

NAME

Langertha::Raider::WorktreeTools - Internal worktree tools of raider: enter_worktree and exit_worktree

VERSION

version 0.504

SYNOPSIS

my $tools = Langertha::Raider::WorktreeTools->new(
  enter_handler => sub { my ( $in ) = @_; ...; return ( $text, $is_error ) },   # { name, path }
  exit_handler  => sub { my ( $in ) = @_; ...; return ( $text, $is_error ) },   # { action, discard_changes }
  worktrees_dir => '.claude/worktrees/',
);
my $server = $tools->server;   # MCP::Server with enter_worktree and exit_worktree

Langertha::Raider::WorktreeTools->name_error('feature/x');   # undef: a valid name

DESCRIPTION

Internal module. Its interface may change without notice.

The worktree tools of the main run (ADR 0032 §4), shaped after Claude Code's EnterWorktree and ExitWorktree (Langertha::Raider::ToolNames): enter_worktree moves the session's working root into a git worktree -- a new one by name, an existing one by path -- and exit_worktree moves it back, keeping or removing the worktree. The tools carry the texts and the schemas and check the shape of a call (name and path together, a name against Claude Code's rule, an action that is neither keep nor remove); everything else is the handlers' -- the application's ("working_root" in Langertha::Raider::Application). A handler that dies gives an error result, never a dead answer.

enter_handler

Required. Called as $enter_handler->({ name => ..., path => ... }) (each key only when given) for every enter_worktree call that passed the checks of "enter_error"; returns the result text and whether it is an error.

exit_handler

Required. Called as $exit_handler->({ action => 'keep' | 'remove', discard_changes => 0 | 1 }) for every exit_worktree call with a valid action; returns the result text and whether it is an error.

worktrees_dir

The directory below the repository's top that new worktrees go into, as the texts name it: .claude/worktrees/ in the Claude layout, else (the default) .raider/worktrees/.

base_setting

The setting the texts name for the base of a new worktree: worktree.baseRef in the Claude layout, else (the default) worktree_base_ref.

server

The MCP::Server with the tools enter_worktree and exit_worktree, built once.

name_error

my $error = $tools->name_error($name);   # undef when valid

Why $name is no worktree name, or undef: Claude Code's rule -- segments of letters, digits, ., _ and -, joined by /, at most 64 characters -- and no segment . or .. (the name is a directory below "worktrees_dir").

enter_error

my $error = $tools->enter_error({ name => 'x', path => '/repo/wt' });   # 'Pass name or path, not both.'

The error result of an enter_worktree call whose shape is wrong, or undef: name and path together, a path that is not a non-empty string, a name "name_error" refuses.

enter_description

exit_description

The texts of the two tools, after Claude Code's current EnterWorktree and ExitWorktree texts in raider's names and with raider's behaviour: no WorktreeCreate hooks, an existing name is an error, the end of the session keeps a worktree with changes without asking.

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/