refactor: agent state machine, deterministic result passing, overflow-to-file (#57)

* refactor: deterministic agent result passing + completion notification injection

Three architectural changes to the multi-agent communication system:

1. Deterministic result passing (no fallback):
   - agent/completed notification now carries reason + result fields
   - Hub agent_io_loop extracts result from agent/completed only
   - Removed last_stream/completion_output fallback in agent_io_loop
   - AgentOutput.result flows: runtime → server → IPC → Hub (single path)

2. Completion notification injection (push model):
   - MessageSource::System variant for Hub-generated notifications
   - Hub deliver_to_parent() sends Envelope to parent's completion_tx
   - completion_bridge forwards from Hub channel to parent via IPC
   - session_forward handles agent/message notifications for injection
   - System messages are ephemeral (not persisted to session)

3. Remove max_turns limit:
   - TerminateReason::MaxTurns, AgentEventPayload::MaxTurnsReached removed
   - Settings.max_turns, AgentConfig.max_turns fields removed
   - LOOPAL_MAX_TURNS env var handling removed
   - Agent loop runs without artificial turn limits

Agent tool updated: foreground (blocking) is default, multiple foreground
spawns in one turn execute in parallel via JoinSet. Background mode
reserved for when parent has independent work to do.

* refactor: remove AttemptCompletion tool — agent output is streaming text

AttemptCompletion was a flawed abstraction that:
1. Forced LLMs to re-summarize content already output as streaming text
2. Used the compressed summary as agent output, losing information
3. Conflated "I'm done" signal with content delivery

After removal, agent completion works naturally:
- Agent stops when LLM generates no tool calls (existing path)
- Agent output = last assistant streaming text (TurnOutput.output)
- No special tool or is_completion flag needed

Removed across the entire stack:
- AttemptCompletionTool definition and registration
- ToolResult::completion() constructor and is_completion field
- ContentBlock::ToolResult is_completion field
- AgentEventPayload::ToolResult is_completion field
- Runtime completion detection in turn_exec/tools/finalize_tool_results
- Session tool_result_handler completion promotion logic
- Protocol projection completion promotion
- Agent bridge completion_result tracking
- Headless mode is_completion detection
- Sub-agent prompt "call AttemptCompletion" instructions
- All related test infrastructure (FakeCompletionTool, scenarios, etc.)

* refactor: explicit agent state machine — Runtime drives AgentStatus

Runtime layer now holds AgentStatus as source of truth and drives
state transitions via events. Replaces the `initial_prompt` heuristic.

State machine: Starting → Running → WaitingForInput → Running → ... → Finished

Key changes:
- AgentLoopRunner holds `status: AgentStatus` field
- `transition()` method updates status and emits corresponding event
- `run_loop()` unified: all agents (interactive + task) run the same loop
- Removed `initial_prompt = !store.is_empty()` hack
- `wait_for_input()` no longer emits AwaitingInput (run_loop controls it)
- AwaitingInput emitted for ALL agents after turn completion (unified idle signal)
- Task agents exit when input channel closes (channel lifecycle = agent lifecycle)
- IntegrationHarness.close_input() for tests that need prompt-driven exit

* refactor: complete agent state machine — all transitions through transition()

Every AgentStatus change now goes through transition() or transition_error(),
ensuring Runtime is the deterministic SSOT for agent state.

State transition table:
- Starting → Running:        transition(Running) + emit(Started) [once at startup]
- Running → WaitingForInput: transition(WaitingForInput) → emit(AwaitingInput)
- WaitingForInput → Running: transition(Running) [implicit — Stream/ToolCall signal activity]
- Running → Error:           transition_error(msg) → emit(Error { message })
- Interrupted:               status = WaitingForInput + emit(Interrupted)
- * → Finished:              transition(Finished) → emit(Finished)

Removed: direct `self.status = AgentStatus::Running` assignment,
standalone `self.emit(Error/Finished)` calls that bypassed status update.

Exception: FinishedGuard (panic Drop) uses try_emit without status update —
acceptable since self is inaccessible during stack unwinding.

* feat: overflow-to-file for large outputs + agent edge case fixes

Large tool/agent outputs are now saved to overflow files instead of being
silently truncated. The LLM receives a preview + file path and can use
the Read tool to access full content on demand.

Overflow-to-file integration:
- tool-api: handle_overflow() + save_to_overflow_file() core abstraction
- tool_pipeline: uses handle_overflow instead of truncate + manual save
- backend/shell: bash stdout/stderr overflow to file
- backend/grep: full match results saved when exceeding limit
- backend/glob: full file list saved when exceeding limit
- backend/net: HTTP body saved when exceeding fetch size limit
- agent-hub/completion: large agent results overflow before parent delivery

Overflow files stored in {tmp}/loopal/overflow/{label}_{timestamp}.txt

Agent edge case fixes:
- Background spawn: 1-hour timeout on worktree cleanup wait
- GrepSearchResult, GlobSearchResult, FetchResult: overflow_path field added

* fix: close input channel for task agents so they exit after prompt

Prompt-driven (task) sub-agents were hanging forever in wait_for_input()
because SharedSession held the only input_tx sender clone, preventing
the channel from closing.

Fix: for task sessions (has_initial_prompt=true), use a dummy sender in
SharedSession instead of the real input_tx. The real sender is dropped
immediately, and the placeholder clone is dropped on replace_session().
With zero connected senders, recv_input() returns None → agent exits
after processing the pre-loaded prompt.

* Revert "fix: close input channel for task agents so they exit after prompt"

This reverts commit ea9d992.

* feat: LifecycleMode — Task agents exit on idle, Interactive agents wait

Task agents (sub-agents, headless) now exit when idle with no pending
input, instead of relying on channel closure. This is an agent-internal
decision, not an external hack.

- LifecycleMode enum: Task (exit on idle) vs Interactive (wait for input)
- AgentConfig.lifecycle field, set by agent_setup based on prompt presence
- run_loop idle phase: Task drains pending input, exits if empty
- drain_pending_input() non-blocking check for queued messages
- HarnessBuilder defaults to Task; build_spawned() forces Interactive
- Reverted channel-closure hack (ea9d992)

* fix: implement HubFrontend.drain_pending + yield before Task exit

Two fixes for Task agent idle behavior:

1. HubFrontend now implements drain_pending() — non-blocking try_recv
   from input_rx. Previously returned empty (default trait impl),
   causing Task agents to miss queued IPC messages (sub-agent completions).

2. Task agent yields before drain check — gives in-flight IPC messages
   time to arrive before deciding to exit.

Author: yishuiliunian

CLAUDE.md

@@ -96,7 +96,7 @@ TUI Process ──stdio IPC──→ Agent Server Process ←──TCP──→
 <project>/.loopal/settings.local.json  Local overrides (gitignored)
 ```
 
-Environment variable overrides use `LOOPAL_` prefix. Key settings: `model` (default: `claude-sonnet-4-20250514`), `max_turns` (default: 50), `permission_mode`.
+Environment variable overrides use `LOOPAL_` prefix. Key settings: `model` (default: `claude-sonnet-4-20250514`), `permission_mode`.
 
 ## Code Conventions
 

LOOPAL.md

@@ -101,7 +101,7 @@ TUI Process ──stdio IPC──→ Agent Server Process ←──TCP──→
 <project>/.loopal/settings.local.json  Local overrides (gitignored)
 ```
 
-Environment variable overrides use `LOOPAL_` prefix. Key settings: `model` (default: `claude-sonnet-4-20250514`), `max_turns` (default: 50), `permission_mode`.
+Environment variable overrides use `LOOPAL_` prefix. Key settings: `model` (default: `claude-sonnet-4-20250514`), `permission_mode`.
 
 ## Code Conventions
 

README.md

@@ -137,9 +137,6 @@ Loopal uses a layered configuration system. Create a `.loopal/config.toml` in yo
 # Default model
 model = "claude-sonnet-4-20250514"
 
-# Max turns per agent loop
-max_turns = 200
-
 # Permission mode: "supervised" or "bypass"
 permission_mode = "supervised"
 

crates/loopal-acp/src/adapter/events.rs

@@ -59,9 +59,6 @@ impl AcpAdapter {
     async fn handle_event(&self, event: &AgentEvent, session_id: &str) -> Option<StopReason> {
         match &event.payload {
             AgentEventPayload::AwaitingInput => return Some(StopReason::EndTurn),
-            AgentEventPayload::MaxTurnsReached { .. } => {
-                return Some(StopReason::MaxTurnRequests);
-            }
             AgentEventPayload::Finished => return Some(StopReason::EndTurn),
             _ => {}
         }

crates/loopal-acp/src/translate/mod.rs

@@ -96,7 +96,6 @@ pub fn translate_event(payload: &AgentEventPayload, session_id: &str) -> Option<
 
         // ── Events with no ACP counterpart ───────────────────────────
         AgentEventPayload::AwaitingInput
-        | AgentEventPayload::MaxTurnsReached { .. }
         | AgentEventPayload::AutoContinuation { .. }
         | AgentEventPayload::Started
         | AgentEventPayload::Finished

crates/loopal-agent-hub/src/agent_io.rs

@@ -8,7 +8,7 @@ use tracing::{info, warn};
 
 use loopal_ipc::connection::{Connection, Incoming};
 use loopal_ipc::protocol::methods;
-use loopal_protocol::{AgentEvent, AgentEventPayload};
+use loopal_protocol::AgentEvent;
 
 use crate::dispatch::dispatch_hub_request;
 use crate::hub::Hub;
@@ -18,40 +18,29 @@ use crate::ui_relay::relay_to_ui_clients;
 const WAIT_AGENT_METHOD: &str = "hub/wait_agent";
 
 /// Run the IO loop for a connected agent. Returns the agent's final output
-/// (from AttemptCompletion or last stream text) for passing to wait_agent watchers.
+/// extracted from the `agent/completed` notification — the single authoritative source.
 pub async fn agent_io_loop(
     hub: Arc<Mutex<Hub>>,
     conn: Arc<Connection>,
     mut rx: tokio::sync::mpsc::Receiver<Incoming>,
     agent_name: String,
 ) -> Option<String> {
     info!(agent = %agent_name, "agent IO loop started");
-    let mut last_stream = String::new();
-    let mut completion_output: Option<String> = None;
+    let mut agent_result: Option<String> = None;
 
     while let Some(msg) = rx.recv().await {
         match msg {
             Incoming::Notification { method, params } => {
                 if method == methods::AGENT_COMPLETED.name {
-                    // Explicit completion — primary signal (EOF is fallback).
-                    info!(agent = %agent_name, "received agent/completed");
+                    // Extract result from the authoritative completion signal.
+                    agent_result = params
+                        .get("result")
+                        .and_then(|v| v.as_str())
+                        .map(String::from);
+                    info!(agent = %agent_name, has_result = agent_result.is_some(), "received agent/completed");
                     break;
                 } else if method == methods::AGENT_EVENT.name {
                     if let Ok(mut event) = serde_json::from_value::<AgentEvent>(params) {
-                        // Track output for wait_agent result
-                        match &event.payload {
-                            AgentEventPayload::ToolResult {
-                                result,
-                                is_completion: true,
-                                ..
-                            } => {
-                                completion_output = Some(result.clone());
-                            }
-                            AgentEventPayload::Stream { text } => {
-                                last_stream.push_str(text);
-                            }
-                            _ => {}
-                        }
                         if event.agent_name.is_none() {
                             event.agent_name = Some(agent_name.clone());
                         }
@@ -101,12 +90,7 @@ pub async fn agent_io_loop(
             }
         }
     }
-    // Prefer AttemptCompletion output over accumulated stream text
-    completion_output.or(if last_stream.is_empty() {
-        None
-    } else {
-        Some(last_stream)
-    })
+    agent_result
 }
 
 /// Spawn hub/wait_agent in a background task so it doesn't block the IO loop.
@@ -162,13 +146,19 @@ pub fn start_agent_io(
         }
         info!(agent = %n, "agent registered in Hub");
         let output = agent_io_loop(hub2, conn, rx, n.clone()).await;
-        let mut h = hub.lock().await;
-        // Order matters: emit BEFORE unregister to avoid race with wait_agent.
-        // wait_agent checks agent existence → if we unregister first, it returns
-        // "not found" and misses the output. By emitting first, any pending watcher
-        // gets the output before the agent is removed.
-        h.registry.emit_agent_finished(&n2, output);
-        h.registry.unregister_connection(&n2);
+        let pending = {
+            let mut h = hub.lock().await;
+            // Order matters: emit BEFORE unregister to avoid race with wait_agent.
+            let pending = h.registry.emit_agent_finished(&n2, output);
+            h.registry.unregister_connection(&n2);
+            pending
+        }; // Lock released.
+        // Deliver to parent outside the lock — uses async send (no data loss).
+        if let Some((tx, envelope)) = pending {
+            if tx.send(envelope).await.is_err() {
+                tracing::warn!(agent = %n2, "parent completion channel closed");
+            }
+        }
         info!(agent = %n2, "agent IO loop ended");
     });
 }
@@ -185,9 +175,17 @@ pub fn spawn_io_loop(
     let n2 = name.to_string();
     tokio::spawn(async move {
         let output = agent_io_loop(hub2, conn, rx, n.clone()).await;
-        let mut h = hub.lock().await;
-        h.registry.emit_agent_finished(&n2, output);
-        h.registry.unregister_connection(&n2);
+        let pending = {
+            let mut h = hub.lock().await;
+            let pending = h.registry.emit_agent_finished(&n2, output);
+            h.registry.unregister_connection(&n2);
+            pending
+        };
+        if let Some((tx, envelope)) = pending {
+            if tx.send(envelope).await.is_err() {
+                tracing::warn!(agent = %n2, "parent completion channel closed");
+            }
+        }
         info!(agent = %n2, "agent IO loop ended");
     });
 }

crates/loopal-agent-hub/src/agent_registry/completion.rs

@@ -1,21 +1,31 @@
-//! Agent completion tracking and cascade interrupt.
+//! Agent completion tracking, result delivery, and cascade interrupt.
 
 use loopal_ipc::protocol::methods;
-use loopal_protocol::{AgentEvent, AgentEventPayload};
-use tokio::sync::watch;
+use loopal_protocol::{AgentEvent, AgentEventPayload, Envelope, MessageSource};
+use tokio::sync::{mpsc, watch};
 
 use super::AgentRegistry;
 use crate::topology::AgentLifecycle;
 
 impl AgentRegistry {
-    /// Emit Finished event, cache output, notify watchers, cascade orphans.
-    pub fn emit_agent_finished(&mut self, name: &str, output: Option<String>) {
+    /// Emit Finished event, cache output, deliver result to parent, notify watchers.
+    ///
+    /// Returns an optional `(sender, envelope)` pair for the caller to deliver
+    /// **after releasing the Hub lock**. This avoids holding the lock during IPC.
+    pub fn emit_agent_finished(
+        &mut self,
+        name: &str,
+        output: Option<String>,
+    ) -> Option<(mpsc::Sender<Envelope>, Envelope)> {
         tracing::info!(agent = %name, has_output = output.is_some(), "emitting Finished");
         self.set_lifecycle(name, AgentLifecycle::Finished);
 
         let text = output.unwrap_or_else(|| "(no output)".into());
         self.finished_outputs.insert(name.to_string(), text.clone());
 
+        // Prepare delivery envelope (actual send happens after lock release).
+        let pending_delivery = self.prepare_parent_delivery(name, &text);
+
         let event = AgentEvent::named(name, AgentEventPayload::Finished);
         let _ = self.event_tx.try_send(event);
 
@@ -28,6 +38,37 @@ impl AgentRegistry {
             tracing::info!(agent = %name, orphans = ?orphans, "cascade interrupt");
             self.interrupt_orphans(&orphans);
         }
+
+        pending_delivery
+    }
+
+    /// Build the delivery envelope and find the parent's completion_tx.
+    /// Returns None if no parent or no completion channel.
+    fn prepare_parent_delivery(
+        &self,
+        child_name: &str,
+        result: &str,
+    ) -> Option<(mpsc::Sender<Envelope>, Envelope)> {
+        let parent_name = self.agents.get(child_name)?.info.parent.as_deref()?;
+        let tx = self
+            .agents
+            .get(parent_name)?
+            .completion_tx
+            .as_ref()?
+            .clone();
+        // Cap large results: save to overflow file, embed path in envelope.
+        let body = if result.len() > MAX_RESULT_BYTES {
+            overflow_agent_result(child_name, result)
+        } else {
+            result.to_string()
+        };
+        let content = format!("<agent-result name=\"{child_name}\">\n{body}\n</agent-result>");
+        let envelope = Envelope::new(
+            MessageSource::System("agent-completed".into()),
+            parent_name,
+            content,
+        );
+        Some((tx, envelope))
     }
 
     /// Create a completion watcher for a named agent.
@@ -87,3 +128,34 @@ impl AgentRegistry {
         }
     }
 }
+
+/// Max agent result bytes before overflow to file (100 KB).
+const MAX_RESULT_BYTES: usize = 100_000;
+
+/// Save oversized agent result to file, return preview + path.
+fn overflow_agent_result(agent_name: &str, result: &str) -> String {
+    let dir = std::env::temp_dir().join("loopal").join("overflow");
+    let _ = std::fs::create_dir_all(&dir);
+    let ts = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis();
+    let path = dir.join(format!("agent_{agent_name}_{ts}.txt"));
+    let path_str = path.to_string_lossy().into_owned();
+    if std::fs::write(&path, result).is_err() {
+        return result[..MAX_RESULT_BYTES].to_string();
+    }
+    // Preview: first ~25 KB
+    let preview_end = result
+        .char_indices()
+        .take_while(|(i, _)| *i < MAX_RESULT_BYTES / 4)
+        .last()
+        .map(|(i, c)| i + c.len_utf8())
+        .unwrap_or(0);
+    let kb = result.len() / 1024;
+    format!(
+        "{}\n\n[Agent result too large for context ({kb} KB). Full output saved to: {path_str}]\n\
+         Use the Read tool to access the complete output if needed.",
+        &result[..preview_end]
+    )
+}

crates/loopal-agent-hub/src/agent_registry/mod.rs

@@ -46,12 +46,13 @@ impl AgentRegistry {
             ManagedAgent {
                 state: AgentConnectionState::Local(channels),
                 info: AgentInfo::new(name, None, None),
+                completion_tx: None,
             },
         );
     }
 
     pub fn register_connection(&mut self, name: &str, conn: Arc<Connection>) -> Result<(), String> {
-        self.register_connection_with_parent(name, conn, None, None)
+        self.register_connection_with_parent(name, conn, None, None, None)
     }
 
     pub fn register_connection_with_parent(
@@ -60,6 +61,7 @@ impl AgentRegistry {
         conn: Arc<Connection>,
         parent: Option<&str>,
         model: Option<&str>,
+        completion_tx: Option<mpsc::Sender<Envelope>>,
     ) -> Result<(), String> {
         if self.agents.contains_key(name) {
             return Err(format!("agent '{name}' already registered"));
@@ -74,6 +76,7 @@ impl AgentRegistry {
             ManagedAgent {
                 state: AgentConnectionState::Connected(conn),
                 info: AgentInfo::new(name, parent, model),
+                completion_tx,
             },
         );
         Ok(())