6 response object

Introduction

Every call to execute() or executeStreaming() returns an AgentResponse — a readonly DTO that provides a normalized view of the agent’s output regardless of which CLI tool produced it. The response contains the text content, process exit code, session identifier, token usage statistics, cost, tool call records, and parse diagnostics. The AgentResponse class is defined at Cognesy\AgentCtrl\Dto\AgentResponse.

Response Properties

The following public properties are available directly on the AgentResponse object:

`agentType: AgentType`

The agent type that produced this response. This is one of AgentType::ClaudeCode, AgentType::Codex, AgentType::OpenCode, AgentType::Pi, or AgentType::Gemini:

echo "Produced by: {$response->agentType->value}"; // e.g., "claude-code"
// @doctest id="f5ff"

`text: string`

The agent’s main text output. This is the concatenation of all text content blocks from the agent’s response. For most use cases, you should access this through the text() method instead:

echo $response->text;
// or
echo $response->text();
// @doctest id="0486"

`exitCode: int`

The process exit code. A value of 0 indicates success. Non-zero values indicate errors, timeouts, or other failures:

if ($response->exitCode !== 0) {
    echo "Process failed with exit code: {$response->exitCode}";
}
// @doctest id="9f2d"

Common exit codes:

0 — Success
1 — General error (invalid configuration, agent-side failure)
2 — Invalid arguments passed to the CLI
124 / 137 — Process killed due to timeout

`usage: ?TokenUsage`

Token usage statistics, when available. This is null for agents that do not expose usage data (Claude Code does not; Codex, OpenCode, Pi, and Gemini do when the data is present in the CLI output):

$usage = $response->usage;
if ($usage !== null) {
    echo "Input tokens: {$usage->input}\n";
    echo "Output tokens: {$usage->output}\n";
    echo "Total tokens: {$usage->total()}\n";
}
// @doctest id="ca26"

`cost: ?float`

The estimated cost in USD, when available. Currently, OpenCode and Pi expose cost data:

if ($response->cost !== null) {
    echo sprintf("Cost: $%.4f", $response->cost);
}
// @doctest id="b3cb"

`toolCalls: array`

An array of ToolCall objects representing every tool invocation made during the execution. See the Tool Calls section below for details:

echo "Tool calls made: " . count($response->toolCalls);
// @doctest id="b8be"

`rawResponse: mixed`

The original bridge-specific response object (ClaudeResponse, CodexResponse, OpenCodeResponse, PiResponse, or GeminiResponse). This provides access to agent-specific data that is not part of the normalized response:

// Access the raw Codex response for agent-specific data
$codexResponse = $response->rawResponse;
// @doctest id="43d7"

`parseFailures: int`

The number of malformed JSON lines that were skipped during response parsing:

if ($response->parseFailures > 0) {
    echo "Warning: {$response->parseFailures} JSON parse failures";
}
// @doctest id="0cf3"

Response Methods

`isSuccess(): bool`

Returns true if the exit code is 0. This is the recommended way to check whether the execution succeeded:

$response = AgentCtrl::codex()->execute('Create a short summary.');

if ($response->isSuccess()) {
    echo $response->text();
} else {
    echo "Failed with exit code: {$response->exitCode}";
    echo "Partial output: " . $response->text();
}
// @doctest id="1a88"

A completed execution with a non-zero exit code does not throw an exception. Always check isSuccess() before treating the text output as authoritative.

`text(): string`

Returns the agent’s text output. Equivalent to accessing the text property directly:

echo $response->text();
// @doctest id="67d3"

`sessionId(): ?AgentSessionId`

Returns the session identifier as an AgentSessionId value object, or null if no session ID was available. The value object implements __toString() for easy serialization:

$sessionId = $response->sessionId();

if ($sessionId !== null) {
    // Store for later resumption
    $cache->set('last_session', (string) $sessionId);
}
// @doctest id="5cea"

`usage(): ?TokenUsage`

Returns the token usage statistics, or null if the agent does not expose this data:

$usage = $response->usage();
if ($usage !== null) {
    echo "Tokens used: {$usage->total()}";
}
// @doctest id="d900"

`cost(): ?float`

Returns the estimated cost in USD, or null if the agent does not expose cost data:

$cost = $response->cost();
if ($cost !== null) {
    echo sprintf("This execution cost $%.4f", $cost);
}
// @doctest id="52c6"

`parseFailures(): int`

Returns the number of malformed JSON lines encountered during parsing:

echo "Parse failures: {$response->parseFailures()}";
// @doctest id="57e9"

`parseFailureSamples(): array`

Returns a list of sample malformed payload strings (truncated to 200 characters each) for debugging purposes:

if ($response->parseFailures() > 0) {
    echo "Skipped {$response->parseFailures()} malformed JSON lines:\n";
    foreach ($response->parseFailureSamples() as $sample) {
        echo "  - {$sample}\n";
    }
}
// @doctest id="e727"

Tool Calls

The toolCalls array contains ToolCall objects — a normalized representation of every tool invocation across all agent types. Each ToolCall has the following structure:

ToolCall Properties

Property	Type	Description
`tool`	`string`	The tool name (e.g., `'bash'`, `'file_change'`, `'web_search'`, `'tool_result'`)
`input`	`array`	The tool’s input parameters as an associative array
`output`	`?string`	The tool’s output, or `null` if not yet completed
`isError`	`bool`	Whether the tool call resulted in an error

ToolCall Methods

Method	Return Type	Description
`callId()`	`?AgentToolCallId`	The unique identifier for this tool call, or `null`
`isCompleted()`	`bool`	Whether the tool has produced output (`output !== null`)

Tool Name Normalization

Agent-Ctrl normalizes tool names across all agents so you can handle them consistently: Claude Code tool calls preserve their original tool names and include separate tool_result entries for tool outputs:

Tool invocations: original tool name (e.g., 'Read', 'Edit', 'Bash')
Tool results: 'tool_result' with ['tool_use_id' => '...'] in the input

Codex items are normalized as follows:

CommandExecution becomes tool: 'bash', input: ['command' => '...']
FileChange becomes tool: 'file_change', input: ['path' => '...', 'action' => '...']
McpToolCall becomes tool: <original tool name>, input: <arguments>
WebSearch becomes tool: 'web_search', input: ['query' => '...']
PlanUpdate becomes tool: 'plan_update'
Reasoning becomes tool: 'reasoning'

OpenCode tool calls preserve their original tool names from the ToolUseEvent.

Working with Tool Calls

$response = AgentCtrl::claudeCode()->execute('Refactor the UserService.');

foreach ($response->toolCalls as $toolCall) {
    echo "Tool: {$toolCall->tool}\n";
    echo "Input: " . json_encode($toolCall->input) . "\n";

    if ($toolCall->isCompleted()) {
        echo "Output: " . substr($toolCall->output, 0, 200) . "\n";
    }

    if ($toolCall->isError) {
        echo "  [ERROR]\n";
    }

    $callId = $toolCall->callId();
    if ($callId !== null) {
        echo "Call ID: {$callId}\n";
    }

    echo "---\n";
}
// @doctest id="f5fd"

Token Usage

The TokenUsage DTO provides detailed token statistics when the agent’s CLI exposes this data. It is defined at Cognesy\AgentCtrl\Dto\TokenUsage.

TokenUsage Properties

Property	Type	Description
`input`	`int`	Number of input tokens consumed
`output`	`int`	Number of output tokens produced
`cacheRead`	`?int`	Tokens read from cache (when available)
`cacheWrite`	`?int`	Tokens written to cache (when available)
`reasoning`	`?int`	Tokens used for reasoning (when available)

TokenUsage Methods

Method	Return Type	Description
`total()`	`int`	Sum of `input` and `output` tokens

Usage Data Availability by Agent

Agent	Token Usage	Cost
Claude Code	No	No
Codex	Yes (input, output, cacheRead)	No
OpenCode	Yes (input, output, cacheRead, cacheWrite, reasoning)	Yes
Pi	Yes (input, output, cacheRead, cacheWrite)	Yes
Gemini	Yes (input, output, cacheRead)	No

$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->execute('Summarize this project.');

$usage = $response->usage();
if ($usage !== null) {
    echo "Input tokens: {$usage->input}\n";
    echo "Output tokens: {$usage->output}\n";
    echo "Total tokens: {$usage->total()}\n";

    if ($usage->cacheRead !== null) {
        echo "Cache read: {$usage->cacheRead}\n";
    }
    if ($usage->cacheWrite !== null) {
        echo "Cache write: {$usage->cacheWrite}\n";
    }
    if ($usage->reasoning !== null) {
        echo "Reasoning tokens: {$usage->reasoning}\n";
    }
}

$cost = $response->cost();
if ($cost !== null) {
    echo sprintf("Cost: $%.4f\n", $cost);
}
// @doctest id="0550"

Complete Example

use Cognesy\AgentCtrl\AgentCtrl;

$response = AgentCtrl::codex()
    ->withTimeout(300)
    ->inDirectory('/projects/my-app')
    ->execute('Review the authentication module and list any issues.');

// Check success
if (!$response->isSuccess()) {
    echo "Execution failed (exit code {$response->exitCode})\n";
    exit(1);
}

// Display text output
echo $response->text() . "\n";

// Display session info
$sessionId = $response->sessionId();
if ($sessionId !== null) {
    echo "Session: {$sessionId}\n";
}

// Display usage stats
$usage = $response->usage();
if ($usage !== null) {
    echo "Tokens: {$usage->total()} (in: {$usage->input}, out: {$usage->output})\n";
}

// Display cost
if ($response->cost() !== null) {
    echo sprintf("Cost: $%.4f\n", $response->cost());
}

// Summarize tool activity
echo "Tool calls: " . count($response->toolCalls) . "\n";
$toolSummary = [];
foreach ($response->toolCalls as $tc) {
    $toolSummary[$tc->tool] = ($toolSummary[$tc->tool] ?? 0) + 1;
}
foreach ($toolSummary as $tool => $count) {
    echo "  {$tool}: {$count}x\n";
}

// Check parse health
if ($response->parseFailures() > 0) {
    echo "Warning: {$response->parseFailures()} parse failures\n";
}
// @doctest id="01fe"

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Introduction

Response Properties

`agentType: AgentType`

`text: string`

`exitCode: int`

`usage: ?TokenUsage`

`cost: ?float`

`toolCalls: array`

`rawResponse: mixed`

`parseFailures: int`

Response Methods

`isSuccess(): bool`

`text(): string`

`sessionId(): ?AgentSessionId`

`usage(): ?TokenUsage`

`cost(): ?float`

`parseFailures(): int`

`parseFailureSamples(): array`

Tool Calls

ToolCall Properties

ToolCall Methods

Tool Name Normalization

Working with Tool Calls

Token Usage

TokenUsage Properties

TokenUsage Methods

Usage Data Availability by Agent

Complete Example

​Introduction

​Response Properties

​agentType: AgentType

​text: string

​exitCode: int

​usage: ?TokenUsage

​cost: ?float

​toolCalls: array

​rawResponse: mixed

​parseFailures: int

​Response Methods

​isSuccess(): bool

​text(): string

​sessionId(): ?AgentSessionId

​usage(): ?TokenUsage

​cost(): ?float

​parseFailures(): int

​parseFailureSamples(): array

​Tool Calls

​ToolCall Properties

​ToolCall Methods

​Tool Name Normalization

​Working with Tool Calls

​Token Usage

​TokenUsage Properties

​TokenUsage Methods

​Usage Data Availability by Agent

​Complete Example

Introduction

Response Properties

`agentType: AgentType`

`text: string`

`exitCode: int`

`usage: ?TokenUsage`

`cost: ?float`

`toolCalls: array`

`rawResponse: mixed`

`parseFailures: int`

Response Methods

`isSuccess(): bool`

`text(): string`

`sessionId(): ?AgentSessionId`

`usage(): ?TokenUsage`

`cost(): ?float`

`parseFailures(): int`

`parseFailureSamples(): array`

Tool Calls

ToolCall Properties

ToolCall Methods

Tool Name Normalization

Working with Tool Calls

Token Usage

TokenUsage Properties

TokenUsage Methods

Usage Data Availability by Agent

Complete Example