view release on metacpan or  search on metacpan

lib/Claude/Agent/Options.pm  view on Meta::CPAN

Boolean. If true, forking the session when resuming creates a new session ID.

=head2 agents

HashRef of subagent definitions. Keys are agent names, values are
L<Claude::Agent::Subagent> objects.

=head2 output_format

Configuration for structured outputs. Should be a hashref with:

    output_format => {
        type   => 'json_schema',
        schema => { ... JSON Schema ... }
    }

=head2 setting_sources

ArrayRef specifying which settings files to load. Valid values:
'user', 'project', 'local'.

=head2 sandbox

Sandbox configuration settings.

=head2 include_partial_messages

Boolean. If true, include partial messages during streaming.

=head2 continue_conversation

Boolean. If true, continue from previous conversation messages.

=head2 query_timeout

Timeout in seconds for the C<next()> method to wait for messages.
Defaults to 600 seconds (10 minutes). Set to a lower value for
interactive applications, or higher for complex long-running queries.

The MCP tool handler timeout can be configured via the
C<CLAUDE_AGENT_TOOL_TIMEOUT> environment variable (default 60 seconds).

=head2 dry_run

Boolean. If true, enables dry-run mode where file-modifying tools (Write, Edit,
Bash with write operations) are intercepted and their effects are previewed
without actually executing them. Read-only tools (Read, Glob, Grep) still execute
normally.

    my $options = Claude::Agent::Options->new(
        dry_run => 1,
        on_dry_run => sub {
            my ($tool_name, $tool_input, $preview) = @_;
            print "Would execute $tool_name:\n";
            print "  $preview\n";
        },
    );

=head2 on_dry_run

Coderef callback invoked when a tool is blocked in dry-run mode. Receives:

=over 4

=item * tool_name - Name of the tool that would execute

=item * tool_input - HashRef of input parameters

=item * preview - Human-readable preview of what would happen

=back

=head1 METHODS

=head2 to_hash

    my $hash = $options->to_hash;

Convert options to a hashref for CLI arguments or serialization.
Uses camelCase keys to match the SDK API format.

=cut

sub to_hash {
    my ($self) = @_;

    my %hash;

    $hash{allowedTools} = $self->allowed_tools if $self->has_allowed_tools;
    $hash{disallowedTools} = $self->disallowed_tools if $self->has_disallowed_tools;
    $hash{systemPrompt} = $self->system_prompt if $self->has_system_prompt;
    $hash{permissionMode} = $self->permission_mode if $self->has_permission_mode;
    $hash{model} = $self->model if $self->has_model;
    $hash{maxTurns} = $self->max_turns if $self->has_max_turns;
    $hash{cwd} = $self->cwd if $self->has_cwd;
    $hash{resume} = $self->resume if $self->has_resume;
    $hash{forkSession} = $self->fork_session if $self->has_fork_session;
    $hash{outputFormat} = $self->output_format if $self->has_output_format;
    $hash{settingSources} = $self->setting_sources if $self->has_setting_sources;
    $hash{sandbox} = $self->sandbox if $self->has_sandbox;
    $hash{includePartialMessages} = $self->include_partial_messages if $self->has_include_partial_messages;
    $hash{continueConversation} = $self->continue_conversation if $self->has_continue_conversation;

    # Handle MCP servers
    if ($self->has_mcp_servers) {
        $hash{mcpServers} = {
            map {
                my $server = $self->mcp_servers->{$_};
                $_ => ($server->can('to_hash') ? $server->to_hash : $server)
            } keys %{$self->mcp_servers}
        };
    }

    # Handle agents (subagents)
    if ($self->has_agents) {
        $hash{agents} = {
            map {
                my $agent = $self->agents->{$_};
                $_ => ($agent->can('to_hash') ? $agent->to_hash : $agent)
            } keys %{$self->agents}
        };