Feature: Add background mode option to agent frontmatter
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
/tasksor other commands to debug - User cannot see what's happening
- Only option is
kill -9to 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 -fon output file
Alternative Considered
- CLI flag
--backgroundwhen 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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗