AgentCtrl Cheat Sheet

Note: AgentCtrl::gemini() and AgentType::Gemini are deprecated. The Gemini CLI bridge is kept for compatibility only.

Entry Points

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Config\AgentCtrlConfig;
use Cognesy\AgentCtrl\Enum\AgentType;

$builder = AgentCtrl::claudeCode();
$builder = AgentCtrl::codex();
$builder = AgentCtrl::openCode();
$builder = AgentCtrl::pi();
$builder = AgentCtrl::gemini(); // deprecated
$builder = AgentCtrl::make(AgentType::Codex);

AgentType values:

• AgentType::ClaudeCode
• AgentType::Codex
• AgentType::OpenCode
• AgentType::Pi
• AgentType::Gemini (deprecated)

Backed values:

• claude-code
• codex
• opencode
• pi
• gemini

Common Builder API

All builders support:

• withConfig(AgentCtrlConfig $config): static
• withModel(string $model): static
• withTimeout(int $seconds): static
• inDirectory(string $path): static
• withSandboxDriver(SandboxDriver $driver): static
• onText(callable $handler): static
• onToolUse(callable $handler): static
• onComplete(callable $handler): static
• onError(callable $handler): static
• execute(string|\Stringable $prompt): AgentResponse
• executeStreaming(string|\Stringable $prompt): AgentResponse
• build(): AgentBridge

Callback signatures:

• onText(fn(string $text): void)
• onToolUse(fn(string $tool, array $input, ?string $output): void)
• onComplete(fn(AgentResponse $response): void)
• onError(fn(string $message, ?string $code): void)

AgentCtrlConfig shared fields:

• model
• timeout
• workingDirectory
• sandboxDriver

AgentCtrlConfig additional methods:

• fromDsn(string $dsn): self
• withOverrides(array $values): self
• toArray(): array

AgentCtrlConfig::fromArray() also accepts:

• directory -> workingDirectory
• sandbox -> sandboxDriver

$builder = AgentCtrl::codex()->withConfig(AgentCtrlConfig::fromArray([
    'model' => 'gpt-5-codex',
    'timeout' => 300,
    'directory' => getcwd(),
    'sandbox' => 'host',
]));

Claude Code

• withSystemPrompt(string|\Stringable $prompt): static
• appendSystemPrompt(string|\Stringable $prompt): static
• withMaxTurns(int $turns): static
• withPermissionMode(PermissionMode $mode): static
• verbose(bool $enabled = true): static
• continueSession(): static
• resumeSession(string $sessionId): static
• withAdditionalDirs(array $paths): static

Codex

• withSandbox(SandboxMode $mode): static
• disableSandbox(): static
• fullAuto(bool $enabled = true): static
• dangerouslyBypass(bool $enabled = true): static
• skipGitRepoCheck(bool $enabled = true): static
• continueSession(): static
• resumeSession(string $sessionId): static
• withAdditionalDirs(array $paths): static
• withImages(array $imagePaths): static

OpenCode

• withAgent(string $agentName): static
• withFiles(array $filePaths): static
• continueSession(): static
• resumeSession(string $sessionId): static
• shareSession(): static
• withTitle(string $title): static

Pi

• withProvider(string $provider): static
• withThinking(ThinkingLevel $level): static
• withSystemPrompt(string|\Stringable $prompt): static
• appendSystemPrompt(string|\Stringable $prompt): static
• withTools(array $tools): static
• noTools(): static
• withFiles(array $filePaths): static
• withExtensions(array $extensions): static
• noExtensions(): static
• withSkills(array $skills): static
• noSkills(): static
• withApiKey(string $apiKey): static
• continueSession(): static
• resumeSession(string $sessionId): static
• ephemeral(): static
• withSessionDir(string $dir): static
• verbose(bool $enabled = true): static

Gemini

• withApprovalMode(ApprovalMode $mode): static
• yolo(): static
• planMode(): static
• withSandbox(bool $enabled = true): static
• withIncludeDirectories(array $paths): static
• withExtensions(array $extensions): static
• withAllowedTools(array $tools): static
• withAllowedMcpServers(array $names): static
• withPolicy(array $paths): static
• continueSession(): static
• resumeSession(string $sessionId): static
• debug(bool $enabled = true): static

Sessions and Executions

use Cognesy\AgentCtrl\AgentCtrl;

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

$next = AgentCtrl::codex()
    ->continueSession()
    ->execute('Apply step 1.');

$sessionId = $response->sessionId();

if ($sessionId !== null) {
    $again = AgentCtrl::codex()
        ->resumeSession((string) $sessionId)
        ->execute('Apply step 2.');
}

Identity rules:

• executionId() returns AgentCtrlExecutionId
• sessionId() returns AgentSessionId|null
• executionId() is generated once per execute() or executeStreaming() call
• sessionId() is provider continuity metadata for resumed conversations
• separate runs may share one sessionId() and still have different executionId() values

Session correlation in telemetry

AgentExecutionStarted and AgentExecutionCompleted both expose sessionId(): ?AgentSessionId, and AgentCtrlEventTelemetry puts it on the envelope correlation. When it is populated:

• resumeSession($id) — the root is born with the session; this is the earliest point the runtime honestly knows one.
• continueSession() — the root has no session. The flag selects "the most recent" without naming it, and no placeholder is invented. Gemini is the sharp case: continueSession() writes the literal 'latest' into the same field resumeSession() uses, and 'latest' is excluded.
• fresh run — no session at start; the agent reports one, so it lands on the completion event.

The root operation id is always the execution id, so runs sharing a session stay distinct traces that merely correlate.

Response

AgentResponse public properties:

• agentType
• text
• exitCode
• usage
• cost
• toolCalls
• rawResponse
• parseFailures

AgentResponse methods:

• executionId(): AgentCtrlExecutionId
• sessionId(): ?AgentSessionId
• isSuccess(): bool
• text(): string
• usage(): ?TokenUsage
• cost(): ?float
• parseFailures(): int
• parseFailureSamples(): array

Tool Calls and Usage

ToolCall:

• tool
• input
• output
• isError
• callId(): ?AgentToolCallId
• isCompleted(): bool

TokenUsage:

• input
• output
• cacheRead
• cacheWrite
• reasoning
• total(): int

StreamHandler

StreamHandler interface (Cognesy\AgentCtrl\Contract\StreamHandler):

• onText(string $text): void
• onToolUse(ToolCall $toolCall): void
• onComplete(AgentResponse $response): void
• onError(StreamError $error): void

CallbackStreamHandler implements StreamHandler with optional closures:

• hasTextHandler(): bool
• hasToolUseHandler(): bool
• hasCompleteHandler(): bool
• hasErrorHandler(): bool
• hasAnyHandler(): bool

StreamError:

• message (string)
• code (?string)
• details (array<string,mixed>)

Events

Concrete builders also expose event wiring through HandlesEvents:

• withEventHandler(CanHandleEvents $events): static
• wiretap(?callable $listener): self
• onEvent(string $class, ?callable $listener): self

Event classes (Cognesy\AgentCtrl\Event\*):

Execution lifecycle: - AgentExecutionStarted -- execution begins - AgentExecutionCompleted -- execution finishes - ExecutionAttempted -- an execution attempt is made

Request building: - RequestBuilt -- request object assembled - CommandSpecCreated -- CLI command spec created

Process execution: - ProcessExecutionStarted -- sandbox process starts - ProcessExecutionCompleted -- sandbox process finishes

Streaming: - StreamProcessingStarted -- stream parsing begins - StreamChunkProcessed -- a JSONL chunk is parsed - StreamProcessingCompleted -- stream parsing finishes

Response parsing: - ResponseParsingStarted -- response parser begins - ResponseDataExtracted -- data extracted from raw response - ResponseParsingCompleted -- response parser finishes

Agent content: - AgentTextReceived -- text content received - AgentToolUsed -- tool call detected - AgentErrorOccurred -- error event from agent

Sandbox: - SandboxInitialized -- sandbox driver initialized - SandboxPolicyConfigured -- sandbox policy set - SandboxReady -- sandbox ready for execution

Testing

Deterministic test seams:

• core package logic
• test AgentCtrlConfig, command builders, parsers, and DTOs directly
• Cognesy\Sandbox\Testing\FakeSandbox
• use for deterministic command execution without running a real CLI
• best for bridge execution paths, timeout behavior, and stdout/stderr handling
• Cognesy\Instructor\Laravel\Testing\AgentCtrlFake
• use only when testing the Laravel facade layer
• queued responses and execution assertions live there, not in core agent-ctrl

Streaming

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Dto\AgentResponse;

$response = AgentCtrl::openCode()
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("[{$tool}]"))
    ->onComplete(fn(AgentResponse $response) => print("\nDone\n"))
    ->onError(fn(string $message, ?string $code) => print("\nError: {$message}\n"))
    ->executeStreaming('Explain this project structure.');