scout-ai 1.2.3 → 2.0.0

data/doc/developer/Backends.md

@@ -0,0 +1,199 @@
+# Backends
+
+This document describes how the LLM backend abstraction works internally:
+the module composition pattern, the inference loop, error handling, and
+provider differences. It is intended for framework contributors.
+
+> For the user-facing guide on configuring inference endpoints and providers,
+> see [../user/RunningInference.md](../user/RunningInference.md).
+> For deep code investigation, see
+> [../../research/backends-analysis.md](../../research/backends-analysis.md).
+
+---
+
+## The Backend abstraction
+
+There is **no abstract base class**. Instead, shared logic lives in the
+`LLM::Backend` module (in `lib/scout/llm/backends/default.rb`), specifically in
+an inner `ClassMethods` module. Each provider is a **module** (not a class)
+that composes it.
+
+### Composition pattern
+
+```ruby
+module LLM
+  module FooMethods       # provider-specific overrides
+    def query(...)
+      ...
+    end
+  end
+
+  module Foo
+    TAG = 'foo'
+    DEFAULT_MODEL = 'foo-model'
+
+    class << self
+      prepend FooMethods             # overrides take priority
+      include Backend::ClassMethods  # shared implementation
+    end
+  end
+end
+```
+
+Ruby's method resolution order (MRO) ensures:
+- `FooMethods#query` shadows `Backend::ClassMethods#query` (via `prepend`).
+- Shared methods (`ask`, `chain_tools`, `tools`, `embed`) come from `ClassMethods`.
+- `self.query(...)` inside the shared `ask` method dispatches to the provider
+  override.
+
+This gives every backend the full inference pipeline for free, while only
+requiring it to implement the provider-specific API call and response parsing.
+
+---
+
+## The `ask` method (template method pattern)
+
+`Backend::ClassMethods.ask` is the universal entry point for all backends. It
+follows a template-method structure:
+
+```
+ask(messages, options)
+  │
+  ├── prepare_client(options, messages)     →  API client setup
+  ├── Chat.prepare_prompt(messages, strategies)  →  ephemeral context management
+  ├── format_messages(prompt)               →  provider-specific formatting
+  ├── tools(prompt, options)                →  tool registry assembly
+  ├── query(client, formatted_prompt, tools, options)  →  API call
+  ├── process_response(...)                 →  parse API response → message list
+  ├── extract_tools(response)               →  detect tool calls
+  ├── chain_tools(...)                      →  recursive tool loop (if needed)
+  ├── update_meta(messages, response)       →  provenance annotations
+  └── return annotated Chat
+```
+
+---
+
+## The `chain_tools` loop
+
+When the model emits a tool call, the backend enters a recursive loop:
+
+```ruby
+def chain_tools(messages, output, tools, options, &block)
+  if output.last[:role] == 'function_call_output'
+    # re-call ask with the tool output appended
+    output + ask(messages + output, options.except(:tool_choice).merge(return_messages: true), &block)
+  else
+    output   # no pending tool call — done
+  end
+end
+```
+
+Each iteration:
+1. Checks if the model's last message is a `function_call_output`.
+2. If so, executes the tool, appends the result, and calls `ask` again with the
+   growing message list.
+3. Terminates when the model's last message is a plain `assistant` message.
+
+### Implicit iteration limiting
+
+There is no hard loop counter. Instead, the `shorten_tools` prompt strategy
+bounds the conversation depth: tool calls beyond `MAX_TOOL_CALLS` (40) are
+dropped from the prompt, and tool outputs beyond `MAX_TOOL_OUTPUTS` are
+truncated or dropped. This naturally constrains how many tool-call rounds a
+conversation can sustain.
+
+---
+
+## Error handling and retries
+
+Backends wrap the API call in `begin/rescue`:
+
+- **`BackendException`** — A custom exception class tagged with a `.chat`
+  accessor so callers can inspect the chat that caused the failure.
+- **Retry policy** — On transient errors (rate limits, timeouts), the backend
+  retries with exponential backoff.
+- **Agent-level exception handling** — `Agent#ask` wraps the backend call and
+  delegates to `@process_exception` (a user-supplied Proc) if set, which may
+  trigger a `retry`.
+
+---
+
+## Backend selection
+
+`LLM.ask` selects a backend via:
+
+1. **Explicit `:backend` option** — `options[:backend]` selects the module.
+2. **Endpoint configuration** — Endpoints defined in
+   `Scout.etc.AI[<endpoint>].yaml` may specify a backend.
+3. **Hard-coded dispatch** — A `case` statement maps `:openai`, `:anthropic`,
+   `:responses`, `:ollama`, `:vllm` to their modules.
+4. **Dynamic loading** — Unknown backend names are resolved as a module name
+   (e.g., `:my_backend` → `LLM::MyBackend`), enabling third-party backends.
+
+---
+
+## Provider differences
+
+### OpenAI (`LLM::OpenAI`)
+
+- **API client**: `OpenAI::Client` (ruby-openai gem).
+- **Streaming**: Supports `stream_results` for token-level streaming.
+- **Tool format**: `type: 'function'` with nested `function:` key.
+- **Images**: Encoded as base64 `image_url` content blocks.
+- **Session continuation**: Supports `previous_response_id` for
+  conversation-threading (Responses API).
+- **Reasoning**: Extracts reasoning summaries from `o1`/`o3`-class models.
+
+### Anthropic (`LLM::Anthropic`)
+
+- **API client**: HTTP client to Anthropic API.
+- **Tool format**: Flat `name`, `description`, `input_schema` (no `function:`
+  nesting).
+- **Images**: Base64 `image` content blocks with media type.
+- **System messages**: Extracted from the message list and sent as a separate
+  parameter.
+- **Reasoning**: Extracts `thinking` content blocks.
+
+### Ollama (`LLM::OLlama`)
+
+- **API client**: HTTP client to local Ollama server.
+- **Tool format**: Uses OpenAI-compatible format.
+- **Endpoint**: Defaults to `http://localhost:11434`.
+- **Embedding**: Supports embedding queries natively.
+
+### Responses API (`LLM::Responses`)
+
+- **Wraps OpenAI's Responses API** — a session-oriented endpoint.
+- **Session state**: Uses `previous_response_id` to maintain context
+  server-side, reducing token consumption.
+- **Compatible with**: OpenAI's `o1`/`o3` reasoning models.
+
+### Bedrock (`LLM::Bedrock`)
+
+- **Multi-provider**: Routes to different providers (Anthropic, Meta, etc.) via
+  the AWS Bedrock API.
+- **Model naming**: Uses provider-prefixed model IDs
+  (e.g., `anthropic.claude-3-sonnet`).
+
+---
+
+## Key source files
+
+| File | Responsibility |
+|---|---|
+| `lib/scout/llm/ask.rb` | Top-level `LLM.ask`, backend dispatch |
+| `lib/scout/llm/backends/default.rb` | `Backend` module + `ClassMethods` |
+| `lib/scout/llm/backends/openai.rb` | OpenAI provider |
+| `lib/scout/llm/backends/anthropic.rb` | Anthropic provider |
+| `lib/scout/llm/backends/ollama.rb` | Ollama provider |
+| `lib/scout/llm/backends/responses.rb` | OpenAI Responses API |
+| `lib/scout/llm/backends/vllm.rb` | vLLM provider |
+| `lib/scout/llm/backends/bedrock.rb` | AWS Bedrock provider |
+
+---
+
+## Cross-references
+
+- [../user/RunningInference.md](../user/RunningInference.md) — User guide for endpoints and providers.
+- [PromptProcessing.md](PromptProcessing.md) — Context management integrated into the backend.
+- [../../research/backends-analysis.md](../../research/backends-analysis.md) — Deep investigation.

data/doc/developer/ChatLifecycle.md

@@ -0,0 +1,183 @@
+# Chat Lifecycle
+
+This document describes how the `Chat` abstraction works internally: its data
+model, the Annotation pattern that gives it a DSL, and the compilation
+pipeline that transforms chat-file text into inference-ready message arrays.
+It is intended for framework contributors.
+
+> For the user-facing chat-file format guide, see
+> [../user/WritingChats.md](../user/WritingChats.md).
+> For deep code investigation, see
+> [../../research/chat-core-analysis.md](../../research/chat-core-analysis.md).
+
+---
+
+## The Chat-as-data philosophy
+
+The most important design decision in Scout-AI:
+
+> **A Chat is a plain `Array` of message `Hash`es, not an opaque object.**
+
+The `Chat` module uses the `Annotation` pattern (from scout-essentials) to add
+DSL methods to a plain Array. The underlying data structure is always directly
+accessible:
+
+```ruby
+chat = Chat.setup([])
+chat.user("Hello")
+
+chat.class            # => Array
+chat.first[:role]     # => "user"
+chat.first[:content]  # => "Hello"
+chat.select { |m| m[:role] == 'system' }  # standard Array operations work
+```
+
+This means chats are serializable, composable, introspectable, and cacheable,
+with no lock-in.
+
+---
+
+## Message roles
+
+Each message in a Chat is a Hash with `:role` and `:content` keys. The system
+recognizes these roles:
+
+| Role | Purpose | Visible to model? |
+|---|---|---|
+| `system` | System instructions | Yes |
+| `user` | User message | Yes |
+| `assistant` | Model response | Yes |
+| `function_call` | Tool invocation request from model | Yes (as provider-specific tool_call) |
+| `function_call_output` | Tool execution result. May carry a `meta` key: an Array of already-deserialized receipt field Hashes (delegated inference metadata such as `pt`/`ct`/`tt`/`inference_id`, or `job=<path>` producer references), embedded by `LLM.process_calls` when the tool returned an `LLM::Agent`. Legacy chats may instead carry a serialized `agent_meta` key; both are read, `meta` wins when both are present. See [Provenance.md](Provenance.md). | Yes (as provider-specific tool result) |
+| `meta` | Provenance metadata (tokens, job references) | **No** — stripped before inference |
+| `tool` | Tool definition (inline in chat) | No — extracted into tool registry |
+| `introduce` | Workflow/tool introduction | No — extracted, introduces tools to the model context |
+| `mcp` | MCP server declaration | No — extracted into tool registry |
+| `kb` | Knowledge base declaration | No — extracted into tool registry |
+| `association` | Association declaration | No — extracted |
+| `option` | LLM option (model, endpoint, etc.) | No — extracted into options hash |
+| `file` / `image` / `pdf` | Binary content | Processed into content blocks |
+
+The `meta`, `tool`, `introduce`, `mcp`, `kb`, `option`, and similar roles are
+**side-channel** roles: they are extracted from the message array during
+compilation and do not appear in the prompt sent to the model.
+
+---
+
+## The Annotation pattern
+
+`Chat` is not a class — it is an Annotation module:
+
+```ruby
+module Chat
+  extend Annotation
+  # DSL methods defined here: user, system, ask, follow, option, ...
+end
+```
+
+When you call `Chat.setup(array)`, the Annotation system:
+
+1. Adds Chat's methods to the **singleton class** of that specific Array instance.
+2. Does **not** change the object's class (it remains `Array`).
+3. Makes the annotation **removable** via `Annotation.purge(obj)`.
+
+This is the "annotate, don't wrap" philosophy: you get rich behavior without
+sacrificing the simplicity of the underlying data type.
+
+---
+
+## The compilation pipeline
+
+When `LLM.ask` (or `Agent#ask`) receives input, the Chat compilation pipeline
+transforms it through several stages:
+
+```
+Input (String / file / Array)
+  │
+  ▼
+1. Parse          — Chat.parse: text → Array<Hash>
+  │                 (handles role: directives, block form, indented content)
+  ▼
+2. Extract options — options: directives extracted into options hash
+  │                 (model:, endpoint:, backend:, etc.)
+  ▼
+3. Extract tools   — tool:/introduce:/mcp:/kb: roles extracted
+  │                 into a tool registry hash
+  ▼
+4. Extract clear   — clear: directives processed
+  │                 (removes tool outputs from history)
+  ▼
+5. prepare_prompt  — context strategies applied (shorten_tools)
+  │                 EPHEMERAL: operates on a copy, never mutates stored chat
+  ▼
+6. format_messages — Backend translates into provider-specific format
+  │
+  ▼
+API call
+```
+
+### Key properties
+
+- **Side-channel extraction**: Roles like `tool`, `option`, and `meta` are
+  removed from the message array before the prompt is formatted. The model
+  never sees them.
+- **Ephemeral prompt preparation**: `prepare_prompt` operates on a **local copy**
+  of the messages. The stored chat retains full-fidelity data. Only the
+  inference API call sees the shortened version.
+- **Provider-specific formatting**: Each backend translates the canonical
+  message hashes into the format its API expects.
+
+---
+
+## Provenance annotations
+
+After each inference, the backend inserts a `meta:` message into the chat
+containing token counts and other provenance:
+
+```
+meta: pt=1234 ct=567 tt=1801 pt_s=5000 ct_s=2000 tt_s=7000 pt_c=15000 ...
+```
+
+These meta messages are:
+- Interleaved with conversational messages in the stored chat.
+- Excluded from the lineage chain (they start segments but are not provider input).
+- Used by the provenance traversal system (see [Provenance.md](Provenance.md)).
+
+---
+
+## Persistence
+
+Chats are serialized to `.chat` files — plain-text files using the chat-file
+format (see [../user/WritingChats.md](../user/WritingChats.md)). The
+`.chat` extension is registered as a load driver:
+
+- **Load**: `LLM.chat(path)` or `Chat.setup(Chat.parse(File.read(path)))`.
+- **Save**: `Chat.print(chat)` produces the text representation.
+
+The format is human-readable and diffable, making it ideal for version control
+and inspection.
+
+---
+
+## Key source files
+
+| File | Responsibility |
+|---|---|
+| `lib/scout/llm/chat.rb` | Chat module definition, `setup`, `parse` |
+| `lib/scout/llm/chat/annotation.rb` | DSL methods (user, system, ask, follow, etc.) |
+| `lib/scout/llm/chat/parse.rb` | Text → Array<Hash> parser |
+| `lib/scout/llm/chat/process/options.rb` | Option extraction |
+| `lib/scout/llm/chat/process/tools.rb` | Tool/introduce/mcp/kb extraction |
+| `lib/scout/llm/chat/process/clear.rb` | Clear directive processing |
+| `lib/scout/llm/chat/process/meta.rb` | Meta messages, provenance, message_index |
+| `lib/scout/llm/chat/prompt.rb` | Prompt strategies (prepare_prompt, shorten_tools) |
+| `lib/scout/llm/chat/persist.rb` | .chat file load/save |
+
+---
+
+## Cross-references
+
+- [../user/WritingChats.md](../user/WritingChats.md) — Chat-file format from the user perspective.
+- [PromptProcessing.md](PromptProcessing.md) — Context management internals.
+- [Provenance.md](Provenance.md) — Provenance data model.
+- [../../research/chat-core-analysis.md](../../research/chat-core-analysis.md) — Deep investigation.

data/doc/developer/DelegationInternals.md

@@ -0,0 +1,295 @@
+# Delegation Internals
+
+This document explains how Scout-AI implements multi-agent delegation at the
+code level: the `SOCIAL_INHERIT_MODES` system, the `ask` tool mechanics, the
+`delegate` method, and the template-clone lifecycle. It is intended for
+framework contributors.
+
+> For the user-facing guide to delegation, see
+> [../user/Delegation.md](../user/Delegation.md).
+> For deep code investigation, see
+> [../../research/agent-delegation-analysis.md](../../research/agent-delegation-analysis.md).
+
+---
+
+## Overview
+
+Delegation is implemented in `lib/scout/llm/agent/delegate.rb` (323 lines). It
+provides two mechanisms for one Agent to invoke another:
+
+1. **`socialize`** — Registers a generic `ask` tool that lets the LLM delegate
+   to any specialist agent by name at runtime.
+2. **`delegate`** — Registers a named `hand_off_to_<name>` tool for a specific,
+   pre-loaded Agent instance.
+
+Both mechanisms build on a common infrastructure: the **template-clone
+pattern**, the **socialized chat store**, and the **inheritance modes**.
+
+---
+
+## The template-clone pattern
+
+Each specialist agent type is loaded **once** as an immutable template and stored
+in `@society`:
+
+```
+@society = {
+  "Worker"  => Agent (template, loaded once),
+  "Critic"  => Agent (template, loaded once)
+}
+```
+
+When a new conversation with a specialist is needed, the template is **deep
+cloned** (`clone_social_agent`):
+
+```ruby
+def clone_social_agent(template)
+  agent = template.clone
+  agent.start_chat     = social_chat_copy(template.start_chat)
+  agent.other_options  = IndiferentHash.setup(social_duplicate(template.other_options || {}))
+  agent.society        = nil    # prevent cross-contamination
+  agent.chats          = nil    # of delegation state
+  agent.instance_variable_set(:@current_chat, nil)
+  agent
+end
+```
+
+Each clone gets:
+- Its own `start_chat` (deep-copied).
+- Its own `other_options` (deep-copied via `social_duplicate`).
+- Nilled `society` and `chats` — no accidental access to the caller's delegation state.
+- A nilled `current_chat` — forces lazy re-creation.
+
+The deep-copy (`social_duplicate`) is recursive for Hash, Array, and String,
+and passes Procs by reference (since they can't be marshalled but are safe to
+share).
+
+---
+
+## The socialized chat store
+
+Live specialist instances are stored in `@chats`, keyed by `"agent_name/conversation"`:
+
+```
+@chats = {
+  "Worker/default"     => Agent (clone, persistent conversation),
+  "Worker/analysis_1"  => Agent (clone, named conversation),
+  "Critic/default"     => Agent (clone)
+}
+```
+
+Conversation keys are **scoped by agent**: `Worker/work_A` and
+`Critic/work_A` are independent conversations.
+
+### Persisted society layout
+
+Live conversations are also mirrored to disk, but **lazily**: nothing is
+created until an agent actually saves. `Agent#save` decides the canonical
+location from the save target of the *parent* agent:
+
+- The root chat saved at `p.chat` produces a society tree rooted at
+  `p.chat.files/agent.society/<agent_name>/<conversation>/agent.chat`
+  (named agents use `<name>.society`, e.g. `worker.society`).
+- A nested chat already stored at
+  `.../society/<a>/<c>/<file>` makes the society of *its* children the
+  **sibling** directory `.../society/<a>/<c>/society/...`. A nested
+  `agent.chat` never grows a second `.files` tree of its own. Only the
+  depth-0 society directory is named after the chat (`<name>.society`);
+  every deeper level keeps the plain `society` basename.
+- `chat_task` jobs and the `scout-ai agent ask` CLI always write the agent's
+  own chat at `<chat_or_job_path>.files/<name>.chat`: `agent.chat` for an
+  unnamed/`agent` agent, `worker.chat`/`critic.chat` for named ones.
+- For a persisted **chat** root that file is a full copy of the root
+  conversation; provenance scanning of the sidecar excludes exactly that
+  top-level copy, while the society conversations under
+  `<chat>.files/<name>.society/<agent_name>/<conversation>/agent.chat` are
+  included even though they are also named `agent.chat`. Job roots keep
+  their own top-level `<name>.chat` as a normal log node (renderers hide
+  it), and the `:log` relation covers exactly
+  `*.files/*.chat`, `*.files/*.society/**/*.chat` and the legacy
+  `*.files/log/**/*.chat`, so `resets/` snapshots stay out.
+
+**Legacy layout (read-only).** Older scout-ai wrote
+`<chat>.files/log/agent.chat` and the society tree under
+`<chat>.files/log/society/<agent_name>/<conversation>/agent.chat`. Nothing
+writes there anymore, old files are never migrated, and provenance
+traversal still globs `log/**/*.chat` so chats saved by those versions
+remain visible.
+
+An agent with no live society writes only its own chat file and creates no
+`.files` tree at all; parent directories are created on demand by
+`Open.sensible_write`. Children get their `save_file` assigned during a
+parent save, so later independent child turns keep auto-saving in place.
+Saves are cycle-safe (visited paths + seen agents + a depth limit of 32) and
+non-fatal: a failure is logged as a warning and the run continues.
+
+### `load_chat` — get-or-create
+
+```ruby
+def load_chat(agent_name, options = {}, conversation = nil, inherit: 'tools')
+  key = social_chat_key(agent_name, conversation)   # "Worker/work_A"
+  @chats[key] ||= start_social_chat(agent_name, options, inherit)
+end
+```
+
+The `inherit` parameter is only consulted **once** — when the conversation is
+first created. Follow-up turns reuse the existing conversation with its
+accumulated history.
+
+---
+
+## SOCIAL_INHERIT_MODES
+
+Three modes control how much caller context flows to a specialist on first
+contact:
+
+| Mode | What is inherited | Use case |
+|---|---|---|
+| `none` | Nothing. Specialist starts with its own `start_chat` only. | Fully isolated sub-agent. |
+| `tools` *(default)* | Tooling roles (`introduce`, `tool`, `mcp`, `kb`) from the caller's current chat. | Shared capabilities, private history. |
+| `conversation` | The caller's entire current chat minus its own `start_chat` prefix. | Full context sharing for tight collaboration. |
+
+### Implementation: `social_inherited_context`
+
+```ruby
+def social_inherited_context(inherit)
+  case inherit
+  when 'none'
+    Chat.setup([])
+  when 'tools'
+    tooling = self.current_chat.tooling
+    social_chat_copy(tooling)
+  when 'conversation'
+    social_caller_context
+  end
+end
+```
+
+### `social_caller_context` — extracting non-start-chat messages
+
+For `conversation` mode, the method extracts the "new" messages the caller
+has added beyond its own `start_chat`. It uses a fast path (object identity
+comparison) when the same Hash objects are shared, and a fallback (prefix
+matching) for separately parsed Chats.
+
+The specialist's rebuilt `start_chat` becomes:
+
+```
+[specialist's original start_chat] + [inherited context from caller]
+```
+
+So the specialist always gets its own system prompt first, then optionally the
+caller's tools or full conversation.
+
+---
+
+## The `socialize` method
+
+Registers a single tool named `:ask` that the LLM can invoke to delegate to
+any specialist:
+
+**Tool schema exposed to the model:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `agent` | string | Yes | Name of the specialist agent. |
+| `prompt` | string | Yes | Plain-text prompt. |
+| `conversation` | string | No | Named conversation ID (omit for one-shot). |
+| `inherit` | enum `[none, tools, conversation]` | No (default `tools`) | Context policy for new conversations only. |
+
+**Security boundary:** The tool block calls `ask_agent`, which uses
+`agent.user(prompt)` rather than `agent.prompt(prompt)`. This is deliberate:
+`prompt` parses chat-file syntax, which could allow prompt injection to inject
+`tool:` or `system:` directives. The `user` method only appends a single
+user-role message, making delegation safe even with untrusted LLM-generated
+prompts.
+
+**Option stripping:** Private options (`SOCIAL_PRIVATE_OPTIONS`) are stripped
+before being passed to the specialist:
+
+```ruby
+SOCIAL_PRIVATE_OPTIONS = %i[
+  agent client current_meta format messages no_ask_override
+  previous_response_id process return_messages tool_choice tools
+].freeze
+```
+
+This prevents leaking session state, tool blocks, or message arrays from the
+caller to the specialist.
+
+### Delegated inference receipts
+
+When a delegation tool returns an `LLM::Agent`, `LLM.process_calls` embeds
+the child agent's `meta` messages in the parent `function_call_output`
+envelope under the `meta` key, as an Array of **already-deserialized** field
+Hashes (one for the child's own inference metadata, one per producer
+reference). These receipts are provenance evidence, not parent-chat
+messages: the child's inference metadata and producer job reference are read
+from the paired tool output and never injected into the parent chat. Provenance
+tooling consumes them through `Chat.agent_meta_evidence` and the `:agent_job`
+relation; see [Provenance.md](Provenance.md) for the extraction, precedence
+(current `meta` over legacy `agent_meta`), and accounting rules.
+
+---
+
+## The `delegate` method — named hand-off
+
+```ruby
+def delegate(agent, name, description, task_name = nil, &block)
+```
+
+Creates a tool named `hand_off_to_#{name}` for a **specific, pre-loaded**
+Agent instance. Unlike `socialize`, the agent is not chosen by the model at
+call time — it is hard-coded at registration time.
+
+| Parameter | Description |
+|---|---|
+| `agent` | A pre-loaded `LLM::Agent` instance. |
+| `name` | Tool name suffix (e.g., `worker` → `hand_off_to_worker`). |
+| `description` | Tool description for the LLM. |
+| `&block` | Optional custom tool block. Defaults to: `agent.user(message); agent.chat`. |
+
+### Differences from `socialize`
+
+| Aspect | `socialize` | `delegate` |
+|---|---|---|
+| Agent name | Model chooses at call time | Hard-coded at registration |
+| Tool name | `:ask` (one tool for all agents) | `hand_off_to_#{name}` (one per agent) |
+| Custom block | No (fixed block) | Yes |
+| Conversation mgmt | Named conversations via `conversation` param | Single conversation, resettable via `new_conversation` |
+
+---
+
+## Legacy parameter handling
+
+The old `chat` parameter is silently accepted for backward compatibility via
+`social_tool_parameters`:
+
+| Legacy `chat` value | Maps to `conversation` | Maps to `inherit` |
+|---|---|---|
+| `'current'` | `'current'` | `'conversation'` |
+| `''`, `'none'`, `'false'` | `nil` (one-shot) | `'none'` |
+| Any other name | That name | `'tools'` |
+
+New code should use `conversation` and `inherit` as separate parameters.
+
+---
+
+## Key source files
+
+| File | Responsibility |
+|---|---|
+| `lib/scout/llm/agent/delegate.rb` | All delegation logic |
+| `lib/scout/llm/agent.rb` | `Agent` class, `ask` entry point, `load_agent` class method |
+| `lib/scout/llm/agent/chat.rb` | `start_chat`, `current_chat`, Chat proxy via `method_missing` |
+| `lib/scout/llm/agent/workflow.rb` | `chat_task`, `log_agent` — workflow integration |
+
+---
+
+## Cross-references
+
+- [../user/Delegation.md](../user/Delegation.md) — User guide to delegation.
+- [Provenance.md](Provenance.md) — Receipt-based provenance for delegated inference.
+- [../user/MultiAgentWorkflows.md](../user/MultiAgentWorkflows.md) — Orchestration patterns.
+- [../../research/agent-delegation-analysis.md](../../research/agent-delegation-analysis.md) — Deep investigation.
+- [../../research/multi-agent-patterns-analysis.md](../../research/multi-agent-patterns-analysis.md) — SC26 patterns.