/ 
Claude-Agent-0.04
/ Claude::Agent::Query

NAME

Claude::Agent::Query - Query iterator for Claude Agent SDK

SYNOPSIS

use Claude::Agent::Query;
use Claude::Agent::Options;

my $query = Claude::Agent::Query->new(
    prompt  => "Find all TODO comments",
    options => Claude::Agent::Options->new(
        allowed_tools => ['Read', 'Glob', 'Grep'],
    ),
);

# Blocking iteration
while (my $msg = $query->next) {
    if ($msg->isa('Claude::Agent::Message::Result')) {
        print $msg->result, "\n";
        last;
    }
}

DESCRIPTION

This module handles communication with the Claude CLI process and provides both blocking and async iteration over response messages.

CONSTRUCTOR

my $query = Claude::Agent::Query->new(
    prompt  => "Find all TODO comments",
    options => $options,
    loop    => $loop,    # optional, for async integration
);

Arguments

  • prompt - Required. The prompt to send to Claude.

  • options - Optional. A Claude::Agent::Options object.

  • loop - Optional. An IO::Async::Loop for async integration. If not provided, a new loop is created internally.

Important: For proper async behavior, pass your application's event loop. This allows next_async to be truly event-driven instead of polling.

next

my $msg = $query->next;

Blocking call to get the next message. Returns undef when no more messages.

next_async

my $msg = await $query->next_async;

Async call to get the next message. Returns a Future that resolves when a message is available. This is truly event-driven - no polling.

session_id

my $id = $query->session_id;

Returns the session ID once available (after init message).

is_finished

if ($query->is_finished) { ... }

Returns true if the query has finished (process exited).

error

if (my $err = $query->error) { ... }

Returns error message if the process failed.

interrupt

$query->interrupt;

Send interrupt signal to abort current operation.

send_user_message

$query->send_user_message("Continue with the next step");

Send a follow-up user message during streaming.

set_permission_mode

$query->set_permission_mode('acceptEdits');

Change permission mode during streaming.

respond_to_permission

$query->respond_to_permission($tool_use_id, {
    behavior      => 'allow',
    updated_input => $input,
});

Respond to a permission request.

rewind_files

$query->rewind_files;

Revert file changes to the checkpoint state.

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