Add TaskOutput tool for retrieving background task results

[evansenter]

Summary

Add a task_output tool to retrieve stdout/stderr from background tasks spawned via the task or bash tools.

Current State (as of PR #87)

• BACKGROUND_TASKS: HashMap<String, tokio::process::Child> lives in bash.rs
• task.rs imports it from bash.rs (tight coupling)
• Background tasks use Stdio::null() - no output capture
• Foreground tasks have kill_on_drop(true) for proper cleanup
• kill_shell tool works for both bash and task background processes

Proposed Design (Revised)

Step 1: Extract Background Registry Module

First, extract shared state to src/tools/background.rs:

// src/tools/background.rs
use std::collections::HashMap;
use std::sync::{Arc, LazyLock, Mutex};
use std::sync::atomic::{AtomicUsize, AtomicBool, AtomicI32};
use tokio::process::Child;

pub static NEXT_TASK_ID: AtomicUsize = AtomicUsize::new(1);

pub struct BackgroundTask {
    pub child: Child,
    pub stdout_buffer: Arc<Mutex<String>>,
    pub stderr_buffer: Arc<Mutex<String>>,
    pub completed: AtomicBool,
    pub exit_code: AtomicI32,
}

pub static BACKGROUND_TASKS: LazyLock<Mutex<HashMap<String, BackgroundTask>>> =
    LazyLock::new(|| Mutex::new(HashMap::new()));

This cleans up the bash→task coupling and prepares for output capture.

Step 2: Async Output Collection

When spawning background tasks, create collection tasks:

let (stdout_tx, stdout_buffer) = create_output_collector();
let (stderr_tx, stderr_buffer) = create_output_collector();

let child = Command::new(&cmd)
    .args(&args)
    .stdout(Stdio::piped())
    .stderr(Stdio::piped())
    .spawn()?;

// Spawn collectors
let stdout = child.stdout.take().unwrap();
tokio::spawn(collect_output(stdout, stdout_tx));

let stderr = child.stderr.take().unwrap();
tokio::spawn(collect_output(stderr, stderr_tx));

Step 3: TaskOutput Tool

struct TaskOutputTool;

// Parameters
{
    "task_id": "string",     // Required
    "wait": "boolean",       // Wait for completion (default: false)
    "timeout": "integer"     // Max wait time in seconds (default: 30)
}

// Returns
{
    "task_id": "abc123",
    "status": "running" | "completed",
    "exit_code": 0,          // Only if completed
    "stdout": "output...",
    "stderr": "errors..."
}

Implementation Order

1. Extract background.rs - Move registry, clean up imports in bash.rs and task.rs
2. Add output capture - Modify background spawning in both tools
3. Implement TaskOutput tool - New tool that reads from buffers
4. Add integration tests (per comments below)

Complexity

Medium - requires:

• New module extraction (straightforward refactor)
• Registry structure change
• Async output collection tasks
• New tool implementation
• Integration tests

Related

• PR feat: add task tool for spawning subagents #80 - Task tool implementation
• PR refactor: consolidate formatting, remove TUI, fix MCP interaction format #87 - Added kill_on_drop(true) for foreground tasks
• Bash tool: add run_in_background and description options #13, bash: Add run_in_background parameter #69, Add KillShell tool for background task management #70 - Background bash (also doesn't capture output)

[evansenter]

Additional Scope

When implementing TaskOutput, also add integration tests for the Task tool. The current implementation (#78) has unit tests for the declaration and helper functions, but lacks integration tests for the actual subprocess spawning behavior.

Suggested tests:

• Foreground task with simple prompt returns expected structure
• Background task returns task_id and can be killed via kill_shell
• CWD inheritance verification

[evansenter]

Additional scope: Integration tests for task tool

The task tool implementation (PR #80) includes unit tests but no integration tests. When addressing this issue, please also add integration tests for the task tool covering:

1. Foreground task - spawns subagent, captures stdout/stderr, returns exit code
2. Background task - returns task_id immediately, task appears in BACKGROUND_TASKS registry
3. Kill background task - verify kill_shell terminates task spawned by task tool

These tests are non-trivial since they require spawning actual clemini subprocesses, but they're important for validating the tool works end-to-end.

[evansenter]

Why Extract background.rs First

The coupling issue isn't just about code organization—it's about peer relationships.

Current problem:

task.rs ──imports──► bash.rs (BACKGROUND_TASKS, NEXT_TASK_ID)

task.rs depends on bash.rs, making bash the "owner" of shared state. This is wrong because:

• Neither tool is more important than the other
• kill_shell.rs also needs this state
• Future task_output.rs will need it too

After extracting background.rs:

bash.rs ──────┐
task.rs ──────┼──► background.rs (shared registry)
kill_shell.rs─┤
task_output.rs┘

All tools become peers importing from shared infrastructure. This is the correct dependency direction—tools depend on shared modules, not on each other.