# src/agent KNOWLEDGE BASE
## OVERVIEW
Main turn engine: prompt build, structured replay, provider stream, tool continuation, cancellation, persistence.
## WHERE TO LOOK
| Session API | `mod.rs` | `AgentSession`, run requests, output sink, replay build, context budget, per-turn loop. |
| Entrypoint | `runner.rs` | Provider selection, auth refresh, settings, hooks/tools/subagents, parent-agent prompt assembly. |
| Provider events | `provider_stream.rs` | Assistant deltas, reasoning summaries, tool-call collection, usage/context projection. |
| Tools | `tool_lifecycle.rs` | Tool start/finish events, hook lifecycle, provider-visible result construction. |
| Continuation | `tool_continuation.rs`, `turn_state.rs` | Function-call/result ordering, duplicate suppression, iteration boundaries. |
| Prompting | `prompt.rs`, `prompt_injections.rs` | Template fragments, dynamic AGENTS injection, skills list, hash-tag context expansion. |
| Persistence | `session_persistence.rs` | Required vs best-effort JSONL records, warnings, replay diagnostics. |
| Cancellation | `cancellation.rs` | Shared cancel flag checked before provider/tool continuation work. |
| Compression | `tool_output_compression.rs` | Provider summary rules; raw tool output preservation stays local. |
| Tests | `tests/*`, inline tests | Ordering, continuation, replay, hooks redaction, cancellation, prompt context. |
## CONVENTIONS
- Construct agent sessions through `runner.rs` when settings, auth refresh, hooks, tools, subagents, or AGENTS context are required.
- Preserve assistant delta flush before tool lifecycle output; UI depends on readable ordering.
- Preserve provider item order: system/replay/user, assistant/function_call, function_result, continuation.
- Persist user input before provider run; persist tool call before tool result.
- Continue tool results only through `tool_lifecycle` + `turn_state` sanctioned continuation path.
- Keep provider-visible payload limited to conversation/tool protocol fields; display metadata, hook internals, and TUI state stay local.
- Keep session replay structured; malformed diagnostics may report shape, never corrupted content.
- Keep cancellation checks before stream, between tool calls, before continuation, before completion.
- Add focused tests when changing replay shape, provider request shape, tool ordering, hook policy, redaction.
## ANTI-PATTERNS
- Do not instantiate providers or start parallel stream loops outside the runner/session path.
- Do not append tool results directly to provider requests outside continuation helpers.
- Do not mix `OutputEvent`/`ActivityEvent` display data into `ProviderConversationItem`.
- Do not persist hidden reasoning, encrypted content, previews, hook stdout/stderr, or UI-only state in session events.
- Do not turn malformed session events into provider context.
- Do not swallow required persistence failures for user input or steering input.
- Do not reorder assistant completion around tool execution; delta flush comes first.
- Do not make bash-mode shortcuts leak into normal agent turn semantics.