Background Tool Execution

Background Tool Execution#

MassGen supports non-blocking tool execution for long-running work. This lets agents continue useful foreground tasks while a tool runs in the background.

Use this guide for the generic background lifecycle used by custom tools and MCP targets.

Note

This page covers tool-level background jobs (custom tools + MCP tools). For running an entire MassGen CLI command in the background, see LLM Agent Automation Guide (BackgroundShellManager).

When to Use Background Tools#

Use background mode when a tool call is expected to take noticeable time and you can continue meaningful work without waiting.

Common examples:

  • Large test suites and benchmark runs

  • Long data processing tasks

  • Media generation and heavy file processing

  • Slow MCP/API calls

Foreground mode is usually better for short checks where immediate output is needed.

Lifecycle Overview#

MassGen exposes a consistent lifecycle:

  1. Start a background job with custom_tool__start_background_tool

  2. Check progress with custom_tool__get_background_tool_status

  3. Get final output with custom_tool__get_background_tool_result

  4. Optionally wait for the next completion with custom_tool__wait_for_background_tool

  5. Cancel with custom_tool__cancel_background_tool if no longer needed

  6. Inspect all jobs with custom_tool__list_background_tools

Important

Lifecycle tools use job_id (background job identifier), not tool-specific IDs such as subagent_id.

You can request background execution in two ways:

  • Preferred for normal custom tool calls: include background: true (or mode: background) on the original tool call

  • Explicit management flow: call custom_tool__start_background_tool with target tool_name and arguments

How Waiting Works#

custom_tool__wait_for_background_tool blocks until the next unseen background job reaches a terminal state (completed, error, or cancelled), or until timeout.

Timeout behavior:

  • Default timeout is 30 seconds

  • Maximum timeout is 600 seconds

  • Timeout returns a success payload with ready: false and timed_out: true

Wait Interruption by Runtime Input#

custom_tool__wait_for_background_tool can return early when runtime-injection content becomes available.

Interruption payload shape:

{
  "success": true,
  "ready": false,
  "interrupted": true,
  "interrupt_reason": "runtime_injection_available",
  "injected_content": "...",
  "waited_seconds": 4.231
}

Notes:

  • interrupt_reason may be runtime_injection_available (new context ready) or turn_cancelled.

  • injected_content contains the runtime context to incorporate before proceeding.

  • Runtime input delivered this way is persisted for that agent within the current turn, so if the agent round restarts, the same instruction context is still present.

  • If runtime input is queued just before the wait call starts, MassGen now signals an interrupt immediately after wait activation so the input is not stranded in queue.

  • After handling injected context, you can continue foreground work or call wait again.

Result Delivery and Polling#

In many runs, completed background results are automatically injected back into agent context by the hook framework. When results are not auto-injected (or when deterministic control is needed), poll status and fetch results explicitly.

Recommended pattern:

  1. Start job(s)

  2. Continue foreground work

  3. When blocked, use custom_tool__wait_for_background_tool

  4. Fetch final payload with custom_tool__get_background_tool_result as needed

Subagents + Background Lifecycle#

For subagent work, keep these roles separate:

  • spawn_subagents: starts subagent work

  • list_subagents: discovery/index of subagent metadata (status, workspace, session pointers)

  • custom_tool__*background* lifecycle tools: status/result/wait/cancel management for background jobs

When cancelling a background subagent flow, call custom_tool__cancel_background_tool(job_id) with the background job ID returned by the lifecycle system.

Backend Notes#

  • This lifecycle is available across the primary MassGen tool-capable backends.

  • Codex custom-tool sessions include these lifecycle tools via the massgen_custom_tools MCP wrapper.

  • For Codex/Claude Code MCP targets, background-capable MCP server configs are derived from normal mcp_servers and filtered to avoid recursive/internal servers.

UI Notes (TUI)#

When using the textual UI, background jobs are surfaced in status/ribbon indicators and a background-jobs modal. This makes it easier to monitor asynchronous progress without manual log inspection.

See Also#