/ 
Claude-Agent-0.15
/ 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 => 'acceptEdits',
    model           => 'sonnet',
    effort          => 'high',
    max_turns       => 10,
);

DESCRIPTION

This module defines every option that query(), session() and Claude::Agent::Query accept. Each option maps to a flag of the claude CLI, an entry of the SDK initialize request, or a behaviour of the Perl side; the mapping is given with each attribute.

CONSTRUCTORS

new

my $options = Claude::Agent::Options->new(%options);

Takes a flat list of name/value pairs. An option this class does not know is ignored, so prefer create when the names come from configuration. Passing a hashref is not supported.

create

my $options = Claude::Agent::Options->create(%options);

As new, but croaks naming every unknown option. Claude::Agent::query and session build their options this way when given a hashref.

ATTRIBUTES

Every attribute is optional and has a has_* predicate that reports whether it was given.

allowed_tools

ArrayRef of tool names Claude may use without asking. --allowedTools.

disallowed_tools

ArrayRef of tool names Claude may not use. --disallowedTools.

tools

Which built-in tools exist at all: an ArrayRef of names, [] for none, or { type => 'preset' } for the default set. --tools.

system_prompt

A string replaces the system prompt (--system-prompt). A hashref is one of { type => 'preset', preset => 'claude_code', append => $text } (keep the CLI's prompt and append; --append-system-prompt), { type => 'custom', prompt => $text } (--system-prompt) or { type => 'file', path => $file } (--system-prompt-file). A hashref with only preset is read as the preset form. When unset the CLI's own prompt is used.

permission_mode

One of default, acceptEdits, bypassPermissions, dontAsk, plan, auto or manual. --permission-mode.

permission_prompt_tool_name

The MCP tool that answers permission prompts (--permission-prompt-tool). Cannot be combined with can_use_tool, which sets it to stdio.

can_use_tool

can_use_tool => sub {
    my ($tool_name, $input, $context) = @_;
    return Claude::Agent::Permission->allow;
}

Callback asked whenever the CLI would prompt for permission. It receives the tool name, its input and a Claude::Agent::Permission::Context, and returns a Claude::Agent::Permission::Result, a hashref with a behavior key, or a Future of either.

mcp_servers

HashRef of MCP server configurations keyed by name: Claude::Agent::MCP::Server objects run in this process, Claude::Agent::MCP::StdioServer, Claude::Agent::MCP::SSEServer and Claude::Agent::MCP::HTTPServer objects (or plain hashrefs) are passed to the CLI. --mcp-config.

strict_mcp_config

Use only the servers in mcp_servers. --strict-mcp-config.

hooks

HashRef of event name to ArrayRef of Claude::Agent::Hook::Matcher objects, registered with the CLI in the initialize request.

agents

HashRef of subagent name to Claude::Agent::Subagent, sent in the initialize request.

cwd

Working directory for the CLI process.

add_dirs

ArrayRef of extra directories the tools may touch. One --add-dir each.

env

HashRef of environment variables set for the CLI process, over the inherited environment.

model

Model name or alias. --model.

fallback_model

Model to use when the first is overloaded. --fallback-model.

effort

One of low, medium, high, xhigh, max. --effort.

thinking

{ type => 'adaptive' }, { type => 'enabled', budget_tokens => $n } or { type => 'disabled' }. --thinking or --max-thinking-tokens.

max_thinking_tokens

Thinking budget. --max-thinking-tokens. Ignored when thinking is set.

betas

ArrayRef of beta header names. --betas.

max_turns

Maximum number of agentic turns. --max-turns.

max_budget_usd

Spending cap for the query. --max-budget-usd.

resume

Session ID to resume. --resume.

continue_conversation

Continue the most recent conversation in the working directory. --continue.

session_id

UUID to use for the new session. --session-id. Validated at construction.

fork_session

When resuming, start a new session ID. --fork-session.

output_format

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

Structured output. The schema goes to --json-schema and the parsed result arrives in the result message's structured_output.

settings

Path to a settings file, a JSON string, or a hashref. --settings.

setting_sources

ArrayRef of user, project, local. --setting-sources.

sandbox

Sandbox settings hashref, merged into settings as its sandbox key.

plugins

ArrayRef of { type => 'local', path => $dir }. One --plugin-dir each.

include_partial_messages

Deliver Claude::Agent::Message::StreamEvent messages as the model streams. --include-partial-messages.

include_hook_events

Deliver Claude::Agent::Message::HookEvent messages for every hook. --include-hook-events.

forward_subagent_text

Deliver subagent assistant and user messages, with parent_tool_use_id set. Sent in the initialize request.

enable_file_checkpointing

Let the CLI checkpoint file changes so rewind_files can undo them.

extra_args

HashRef of extra CLI flags without the leading dashes. A value of undef passes the bare flag.

stderr

Callback given each line of the CLI's standard error. By default they are logged at debug level.

cli_path

Path to the claude executable, instead of searching for it.

query_timeout

Seconds the blocking next() waits for a message. Default 600, maximum 3600. Always set, so has_query_timeout is always true.

dry_run

Preview file-modifying tools instead of running them. See Claude::Agent::DryRun.

on_dry_run

on_dry_run => sub {
    my ($tool_name, $tool_input, $preview) = @_;
    ...
}

Callback for each tool blocked in dry-run mode.

METHODS

with

my $resumed = $options->with(resume => $session_id);

A copy with the given options changed. A value of undef removes the option from the copy.

to_hash

my $hash = $options->to_hash;

The options that were given, as a hashref with camelCase keys. Callbacks and hooks are left out; MCP servers and agents are expanded with their own to_hash.

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).