Feature: Add background mode option to agent frontmatter

Resolved 💬 2 comments Opened Jan 30, 2026 by vantasnerdan Closed Feb 28, 2026

Feature Request

Add a background: true frontmatter field for agent definitions that would make agents run in background mode by default.

Problem

Currently, the only way to run an agent in background mode is via the run_in_background: true parameter on the Task tool at invocation time. There's no way to configure an agent to always run in background.

When agents run in foreground and encounter permission prompts or long-running tasks:

  • The main session becomes unresponsive
  • User cannot use /tasks or other commands to debug
  • User cannot see what's happening
  • Only option is kill -9 to recover

Proposed Solution

Add a background field to agent frontmatter:

---
name: my-long-running-agent
description: An agent that does extensive analysis
model: sonnet
color: blue
background: true  # <-- NEW FIELD
---

When background: true:

  • Agent always runs in background mode when invoked
  • Tool result immediately returns output file path
  • Main session stays responsive
  • User can monitor with tail -f on output file

Alternative Considered

  • CLI flag --background when invoking agents
  • Global setting to make all agents run in background
  • Per-invocation control only (current behavior)

Use Case

Long-running specialist agents (e.g., patent analysis agents that read PDFs, load multiple skills, and perform multi-step analysis) benefit from always running in background to prevent session hangs.

Additional Context

The run_in_background parameter already exists on the Task tool, so the underlying mechanism is implemented. This feature would just expose it as a configurable default in agent definitions.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗