/ 
Claude-Agent-0.10
/ Claude::Agent::Options

NAME

Claude::Agent::Options - Configuration options for Claude Agent queries

SYNOPSIS

use Claude::Agent::Options;

my $options = Claude::Agent::Options->new(
    allowed_tools   => ['Read', 'Glob', 'Grep'],
    permission_mode => 'bypassPermissions',
    model           => 'claude-sonnet-4-5',
    max_turns       => 10,
);

DESCRIPTION

This module defines all configuration options that can be passed to the query() function in Claude::Agent.

ATTRIBUTES

allowed_tools

ArrayRef of tool names that Claude is allowed to use.

disallowed_tools

ArrayRef of tool names that Claude is not allowed to use.

system_prompt

Custom system prompt. Can be a string or a hashref with a preset key.

permission_mode

Controls how permissions are handled. Valid values:

  • default - Normal permission behavior

  • acceptEdits - Auto-accept file edits

  • bypassPermissions - Bypass all permission checks

  • dontAsk - Auto-deny tools unless explicitly allowed

mcp_servers

HashRef of MCP server configurations. Keys are server names, values are configuration hashrefs.

hooks

HashRef of hook configurations. Keys are event names (e.g., 'PreToolUse'), values are arrayrefs of Claude::Agent::Hook::Matcher objects.

can_use_tool

Coderef callback for permission prompts. Called when Claude needs permission to use a tool.

can_use_tool => sub {
    my ($tool_name, $input, $context) = @_;
    # Return Claude::Agent::Permission->allow(...) or ->deny(...)
}

cwd

Working directory for the agent.

model

Model name to use (e.g., 'claude-sonnet-4-5', 'claude-opus-4').

max_turns

Maximum number of conversation turns before stopping.

resume

Session ID to resume a previous conversation.

fork_session

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

agents

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

output_format

Configuration for structured outputs. Should be a hashref with:

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

setting_sources

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

sandbox

Sandbox configuration settings.

include_partial_messages

Boolean. If true, include partial messages during streaming.

continue_conversation

Boolean. If true, continue from previous conversation messages.

query_timeout

Timeout in seconds for the 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 CLAUDE_AGENT_TOOL_TIMEOUT environment variable (default 60 seconds).

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";
    },
);

on_dry_run

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

  • tool_name - Name of the tool that would execute

  • tool_input - HashRef of input parameters

  • preview - Human-readable preview of what would happen

METHODS

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.

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).