v0.4.0 — AskHuman: Human-in-the-Loop Clarification

What's New

AskHuman Signal System

Agents can now pause an agentic loop to ask the human for clarification before proceeding. When the LLM decides it needs more information, it calls the built-in ask_human tool — the loop terminates immediately (no second LLM iteration) and fires the onAskHuman callback.

New Classes

• AskHumanSignal — signal value object carrying the question payload
• HumanQuestion — individual question with type, text, and options
• QuestionType — enum: FreeText, SingleChoice, MultipleChoice
• AskHumanTool — built-in tool the LLM calls; schema guides structured question construction

New Lifecycle Hook

$result = (new MyAgent)
    ->onAskHuman(function (AskHumanSignal $signal, int $iteration) {
        broadcast(new ClarificationRequested($signal->toArray()));
    })
    ->reactLoop('Help me build something...');

if ($result->askedHuman()) {
    return response()->json($result->askHumanSignal->toArray());
}

Two Question Modes

Free-text (default) — a single open question:

{ "mode": "free_text", "question": "What kind of project are you building?" }

Structured — typed questions the frontend renders natively:

{
  "mode": "structured",
  "questions": [
    { "type": "single_choice", "question": "What is your timeline?", "options": ["1 week", "1 month", "3+ months"] },
    { "type": "free_text", "question": "Describe the core feature.", "options": [] }
  ]
}

Works Across All Loops

onAskHuman is supported in ReActLoop, ChainOfThoughtLoop, and PlanExecuteLoop. Each result type (LoopResult, CoTResult, PlanResult) gains askedHuman() and askHumanSignal.

Full Changelog

v0.3.1...v0.4.0