# Agent Integration Test

## Test Items
- [ ] Sub-agent spawns and returns result
- [ ] Widget shows agent activity
- [x] Background agent completes and notifies (2026-06-13)
- [x] /agents command shows agent types (2026-06-13)

## Pi-Subagents Architecture Analysis (2026-06-13)

The pi-subagents system is a multi-agent orchestration framework built on an RPC-based subagent protocol. It provides a structured execution environment where specialized agents can be spawned, steered, and composed into workflows. Below is an architectural breakdown of its core subsystems.

**Agent Types & Specialization.** The system maintains a roster of agent types — including `obsidian`, `Explore`, `research`, `coder`, `devops`, `general-purpose`, and `meta-subagent` — each with distinct model assignments and tool access profiles. Agent types are defined declaratively in the agent roster, specifying which model (e.g., `sonnet`, `haiku`, `4o-mini`) drives the agent and which tool subsets it can invoke. This allows the system to route tasks to appropriately-capable agents: lightweight types like `Explore` use faster, cheaper models for browsing, while `coder` and `devops` types get more capable reasoning models with development tool access.

**Background Execution Model.** Agents support two execution modes: foreground (sequential, caller blocks on result) and background (parallel, caller receives an agent ID immediately). Background agents are spawned via `task_spawn` and tracked by the subagent manager. The caller can poll for completion or await notification — this test note itself verified that background agents complete and signal their parent. The background model is critical for parallelizing independent work: data gathering, research, and code generation can proceed concurrently, with results merged later.

**Steering & Resumption.** A distinguishing feature is mid-execution steering. A running background agent receives new instructions via `steer_subagent`, allowing the parent to correct course, inject context, or redirect focus without restarting. Completed agents can also be resumed via the `resume` parameter, re-entering execution with fresh instructions while retaining prior context. This enables iterative refinement workflows — e.g., having an agent draft code, then resuming it to apply review feedback.

**Task List Integration.** The task system (TaskCreate/TaskUpdate/TaskList/TaskExecute) provides structured work management. Tasks carry status (pending/in_progress/completed/deleted), dependencies (blocks/blockedBy), owners, and optional agent type annotations. TaskExecute spawns matching pending tasks as subagents, enabling declarative workflow definition: create a task graph, then execute it and let the system resolve dependencies and dispatch agents automatically.

**Isolation Mode.** For file-modifying operations, agents can be launched with an isolation flag that creates a temporary git worktree. Each agent operates on its own sandboxed copy of the repository, making parallel edits safe. On completion, changes can be reviewed cleanly via diff before applying. The worktree is automatically cleaned up after the agent finishes, preventing accumulation of stale working directories.

**Memory & Context Persistence.** The memctx subsystem provides durable memory across sessions. Agents can save observations, decisions, actions, runbooks, and session summaries via `memctx_save` with appropriate type tags. Retrieval supports three modes: `keyword` (BM25, fast), `semantic` (embedding-based, ~2s), and `deep` (hybrid with reranking, ~10s). The Memory Gateway Brief mechanism injects relevant context at session start, and agents can search memory mid-execution to avoid repeating prior work.

**MCP Gateway.** External tool access is mediated through an MCP (Model Context Protocol) gateway. Agents can connect to MCP servers, list tools, describe parameters, and call tools with JSON arguments. This abstracts away the transport layer (stdio, HTTP, WebSocket) and provides a uniform interface to databases, browsers, filesystems, and other external services. The gateway supports lazy connection — servers are connected on first tool use — and auto-refreshes metadata.
