[FEATURE] Rich Process State and Health Monitoring for Background Commands

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, when Claude Code runs a command in the background, its awareness of that process is limited to its text output (stdout/stderr). The agent operates in a "fire-and-forget" mode; it can start a process but has no insight into its actual state (running, failed, stalled) or resource consumption without being explicitly told to poll its text logs via BashOutput.

This creates several problems for agentic workflows:

• Lack of Autonomy: The agent cannot autonomously detect when a background task has failed. For example, if a build process crashes due to an out-of-memory error, the agent remains unaware until the user notices the process is gone and prompts it to check the logs.
• Inefficient Polling: The only way to check on a process is to repeatedly use BashOutput, which is inefficient and relies on parsing text for clues (e.g., looking for "build failed" strings). This is brittle and unreliable.
• No Health Insight: The agent can't tell the difference between a process that is running correctly but silently, and one that is stalled or consuming excessive resources (e.g., a runaway test stuck in an infinite loop). This prevents proactive debugging.

The core issue is that the agent lacks the structured, real-time state information necessary to manage and react to the processes it creates, limiting its ability to function as a truly autonomous development partner.

Proposed Solution

I propose introducing a new tool and enhancing the agent's internal state awareness to provide rich, structured information about background processes.

1. A New GetBashStatus Tool:

This tool would take a shell_id as input and return a structured JSON object containing key process metadata. This would allow the agent to query the health and status of any background task it has initiated.

Ideal Interaction:
``
> (Internal Agent Action) GetBashStatus(shell_id="sh-123")
``

Example JSON Response:
``json
{
"shellId": "sh-123",
"pid": 54321,
"status": "failed", // "running", "completed", "stalled"
"exitCode": 137, // null if still running
"runtimeSeconds": 185.5,
"cpuUsagePercent": 0.0,
"memoryUsageMB": 2048.7
}
``

1. Proactive State Awareness:

The agent should be proactively notified of process termination events (both success and failure). When a background task finishes, Claude should be able to surface this information without being prompted.

Ideal User Experience:
(User is working on something else)
Claude (proactively): "By the way, the npm run build process I started has finished with an exit code of 1, indicating an error. I am now checking the final logs to identify the cause."

This combination would shift the agent from a passive, poll-based model to a proactive, state-aware one, enabling it to make more intelligent, autonomous decisions.

Alternative Solutions

• Current Workaround: The only current method is to repeatedly use the BashOutput tool to poll for new text in stdout or stderr.
• Drawbacks: This is inefficient and unreliable. The agent has to guess the process's state based on text patterns, which can easily fail. It cannot distinguish between a silent success and a crash that produced no final output.

• Wrapper Scripts: A user could write complex wrapper scripts for every command they want to run in the background. These scripts would have to manually trap exit codes and write status updates to a log file that Claude could then be instructed to read.
• Drawbacks: This is extremely cumbersome, requires significant user effort for every task, and is not a scalable solution.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

A developer is trying to fix a flaky test suite that sometimes hangs or crashes.

1. User: "Run the full test suite in the background. It sometimes hangs, so keep an eye on it for me and let me know if it seems stuck."
2. Claude: "Understood. I'm starting the test suite now in the background (sh-789). I will monitor its status."
3. Claude (Internal Logic): Initiates npm run test:e2e. It then periodically calls GetBashStatus(shell_id="sh-789").
4. (5 minutes later) Claude (Internal Logic): The GetBashStatus call returns {"status": "running", "cpuUsagePercent": 0.1, "memoryUsageMB": 1500}. The agent notices that CPU usage has been near zero for over a minute, which is unusual for a running test suite.
5. Claude (Proactively to User): "The test suite (sh-789) appears to be stalled. It's been running for 5 minutes but has shown no CPU activity for the last 60 seconds. This might indicate a deadlock or hang. Would you like me to inspect the latest output or kill the process?"
6. User: "Kill it and check the logs for the last test that was running."
7. Claude: Uses KillBash and then BashOutput to perform the debugging, having correctly identified the problem without user intervention.

Additional Context

• This is the first of three related feature requests aimed at improving agentic process management. The other two will cover event-driven reactivity and advanced process controls (signals, etc.).
• The functionality is conceptually similar to how process monitoring tools like pm2 or supervisor daemons work, but exposed as tools for an AI agent.
• Implementing this would likely require the Claude Code backend to maintain a more detailed state map of the child processes it spawns.