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