Documentation: add guide explaining the agentic tool-use loop, turns, and completion signals

[shravanmn]

The SDK docs cover individual event types but don't explain how the CLI's tool-use loop works — how turns chain, who triggers each turn, and the difference between session.idle and session.task_complete. Proposing a new docs/features/agent-loop.md to cover this.

[github-actions]

Thanks for filing this, @shravanmn! 👍

Documentation Gap Summary

The SDK currently documents individual event types (in docs/features/streaming-events.md) and the high-level session lifecycle, but there is no guide that explains how all the pieces fit together as a complete agentic tool-use loop. Specifically missing:

• How turns chain: what triggers a new assistant turn after a tool executes (the agent re-enters, issues another message/tool-call, etc.)
• Who drives each turn: whether the app needs to re-send, or the CLI agent self-schedules follow-up turns automatically
• session.idle vs session.task_complete: when each is emitted, what they mean, and which one an app should treat as the "done" signal
• Agentic loop sequence diagram: a visual showing the full cycle — user prompt → turn → tool execution → re-entry → … → completion signal

Affected Files / Sections

File	Gap
docs/features/streaming-events.md	Sequence diagram shows a single turn but doesn't illustrate multi-turn tool loops or when session.idle fires vs session.task_complete
docs/features/index.md	No entry for an agent-loop / turn lifecycle guide
(proposed) docs/features/agent-loop.md	Does not exist yet — this is the primary content to create

Suggested Content for docs/features/agent-loop.md

A new guide should cover:

1. The agentic loop lifecycle — a sequence diagram showing: send() → assistant.turn_start → message/reasoning deltas → tool calls → tool.execution_start/complete → re-entry turn(s) → final assistant.turn_end → session.idle / session.task_complete
2. Turn anatomy — what events appear inside a single turn and in what order
3. Multi-turn chaining — how and why the agent loops (tool results feed back in; the CLI re-triggers a turn automatically)
4. Completion signals — difference between session.idle (agent paused, waiting for input) and session.task_complete (task fully finished), and code examples for each
5. Code examples in all four SDK languages showing how to wait for the right completion event

Once the guide exists, docs/features/index.md and docs/features/streaming-events.md should link to it for cross-referencing.

Generated by Documentation Handler for issue #1009 · ◷