docs: Added documentation for the new agent and task spawning functionality that supports variables

Agents.md

@@ -155,6 +155,12 @@ The `variables` setting in an agent's config has the following fields:
 | `description` | *        | The description of the field                                                                       |
 | `default`     |          | A default value for the field. If left undefined, the user will be prompted for a value at runtime |
 
+Variable values can be supplied three ways (highest precedence first):
+
+1. **At spawn time:** A parent agent passes them via `agent__spawn`'s / `agent__task_create`'s `variables` parameter (see [Passing Agent Variables at Spawn](#passing-agent-variables-at-spawn)). Spawned child agents also inherit the parent's CLI-set variables by name as a fallback.
+2. **On the CLI:** `coyote -a my-agent --agent-variable <name> <value> "..."`.
+3. **Declared `default`:** Used when nothing else supplies a value. A required variable (no default) with no supplied value triggers an interactive prompt at startup, except for spawned child agents, which never prompt (see below).
+
 These variables can be referenced in both the agent's instructions, and in the tool definitions via `LLM_AGENT_VAR_<name>`.
 
 **Example:**
@@ -627,10 +633,10 @@ When `can_spawn_agents` is enabled, the agent receives tools for spawning and ma
 
 | Tool                    | Description                                                                                                            |
 |-------------------------|------------------------------------------------------------------------------------------------------------------------|
-| `agent__spawn`          | Spawn a child agent in the background. Returns an agent ID immediately.                                                |
+| `agent__spawn`          | Spawn a child agent in the background, optionally passing its declared `variables`. Returns an agent ID immediately.  |
 | `agent__check`          | Non-blocking check: is the agent done? Returns `PENDING` or the result.                                                |
 | `agent__collect`        | Blocking wait: wait for an agent to finish, return its output.                                                         |
-| `agent__list_available` | List all agent types installed and available to spawn (name + description). Discovery counterpart to `agent__spawn`.   |
+| `agent__list_available` | List all agent types installed and available to spawn (name + description + declared variables). Discovery counterpart to `agent__spawn`. |
 | `agent__list_running`   | List all subagents you have spawned, with their status.                                                                |
 | `agent__cancel`         | Cancel a running agent by ID.                                                                                          |
 
@@ -656,6 +662,52 @@ Any agent defined in your `<coyote-config-dir>/agents/` directory can be spawned
 - Have their output suppressed from the terminal (no spinner, no tool call logging)
 - Return their accumulated output to the parent when collected
 
+### Passing Agent Variables at Spawn
+
+`agent__spawn` accepts an optional `variables` parameter (an object of string values). This is the spawn-time
+equivalent of the CLI's `--agent-variable`:
+
+```
+agent__spawn --agent pr-reviewer --variables {"pr": "1234"} --prompt "Review this PR."
+```
+
+**Discovering an agent's variables.** `agent__list_available` advertises each agent's declared
+variables, so a parent can learn the spawn contract up front:
+
+```json
+{
+  "name": "pr-reviewer",
+  "description": "Reviews pull requests",
+  "variables": [
+    { "name": "pr", "description": "The PR URL or number", "required": true }
+  ]
+}
+```
+
+`required` is `true` when the variable declares no `default`; the `variables` key is omitted for
+agents that declare none.
+
+**Precedence.** For each declared variable, the value is resolved in this order:
+
+1. The spawn call's `variables` entry
+2. A same-named variable inherited from the parent (e.g. set on the parent via `--agent-variable`)
+3. The variable's declared `default`
+
+**Validation and error behavior.** Unknown variable names, non-string values, or passing
+`variables` to an agent that declares none all return a self-correcting error listing the target
+agent's declared variables. Spawned children never trigger the interactive variable prompt: if a
+required variable ends up with no value, the spawn fails with an error naming each missing
+variable so the parent can re-spawn with the right `variables`.
+
+**Notes:**
+- Values reach the child's instructions (`{{name}}` interpolation), its tools
+  (`LLM_AGENT_VAR_<NAME>`), and, for [graph agents](Graph-Agents), the initial graph state, so
+  `{{name}}` resolves inside `llm` node prompts.
+- If the target agent is configured with a persistent `agent_session` and an existing session is
+  resumed, the session's stored variables win and spawn-provided `variables` are ignored.
+- `agent__task_create` accepts the same `variables` parameter for auto-dispatched tasks (see
+  [Active Task Dispatch](#active-task-dispatch)).
+
 ## Task Queue with Dependencies
 
 For complex workflows where tasks have ordering requirements, the spawning system includes a dependency-aware
@@ -663,7 +715,7 @@ task queue:
 
 | Tool                   | Description                                                                 |
 |------------------------|-----------------------------------------------------------------------------|
-| `agent__task_create`   | Create a task with optional dependencies and auto-dispatch agent.           |
+| `agent__task_create`   | Create a task with optional dependencies, auto-dispatch agent, and agent `variables`. |
 | `agent__task_list`     | List all tasks with their status, dependencies, and assignments.            |
 | `agent__task_complete` | Mark a task done. Returns newly unblocked tasks and auto-dispatches agents. |
 | `agent__task_fail`     | Mark a task as failed. Dependents remain blocked.                           |
@@ -687,11 +739,15 @@ agent__task_create \
   --subject "Implement the auth module" \
   --blocked_by ["task_1"] \
   --agent coder \
+  --variables {"project_dir": "/path/to/repo"} \
   --prompt "Implement auth module based on patterns found in task_1"
 ```
 
 When `task_1` completes and the dependent task becomes unblocked, an agent is automatically spawned with the
-specified prompt. No manual intervention needed. This enables fully automated multi-step pipelines.
+specified prompt, and with the task's stored `variables` passed through to the spawn, exactly as if they
+had been given to `agent__spawn` directly (same precedence and validation). `agent__task_list` echoes each
+task's `variables` alongside its prompt. No manual intervention needed. This enables fully automated
+multi-step pipelines.
 
 ## Output Summarization
 

Graph-Agents.md

@@ -132,10 +132,12 @@ nodes:
   Each declared variable becomes available to script nodes as the env var
   `LLM_AGENT_VAR_<UPPER_NAME>`, exactly like bash tools called by normal
   agents. Values may be overridden at runtime via
-  `coyote -a <agent> --agent-variable <name> <value> "..."`. For LLM nodes to
+  `coyote -a <agent> --agent-variable <name> <value> "..."` (or when the
-  see a variable inside prompts, seed its value into state (typically via
+  graph agent is spawned as a subagent), via `agent__spawn`'s `variables`
-  a setup script that reads the env var and writes it into state) so
+  parameter (see [Passing Agent Variables at Spawn](Agents#passing-agent-variables-at-spawn)).
-  `{{name}}` resolves.
+  Declared variables are seeded into the initial graph state automatically
+  (resolved value first, then declared default), so `{{name}}` resolves
+  inside `llm` node prompts with no setup script required.
 - **`can_spawn_agents` is declared, or derived when omitted.** When the key
   is absent, a graph agent can spawn dynamic child agents iff its graph
   contains at least one `agent` node; an explicit value overrides that