[FEATURE] Event-Driven Output Streaming and Reactivity 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

The current mechanism for monitoring background processes (BashOutput) relies on a polling model. The agent must repeatedly and explicitly ask for the output of a running process to check its status or look for specific events. This approach has significant limitations for creating efficient, autonomous agents:

• High Latency: There is an inherent delay between an event occurring in a process's output (e.g., an error message, a "ready" signal) and the agent detecting it. The agent is always playing catch-up, which is problematic for time-sensitive workflows.
• Inefficiency: Constant polling consumes unnecessary tokens and compute resources as the agent repeatedly asks, "Is anything new yet?". This clutters the conversation context with repetitive, low-value BashOutput calls.
• Reactive, Not Proactive: The agent cannot be instructed to act immediately upon a specific event. For instance, it can't be told to "start fixing tests the moment a failure appears." Instead, it must wait for its next poll, retrieve all recent logs, and then parse them to discover the failure, which is a slow and reactive loop.

This pull-based architecture prevents the development of sophisticated, event-driven workflows and limits the agent's ability to act as a real-time supervisor for the tasks it manages.

Proposed Solution

I propose an event-driven, push-based model that allows the agent to subscribe to the output stream of a background process and react to specific patterns in real-time.

1. Enhance the Bash Tool with Triggers:

The Bash tool, when starting a background process, should accept an optional triggers parameter. This would be an array of objects, each specifying a regex pattern to watch for in stdout/stderr and a corresponding action.

Ideal Tool Interaction (Agent's perspective):
``json
{
"tool_name": "Bash",
"input": {
"command": "npm run dev",
"run_in_background": true,
"triggers": [
{
"pattern": "webpack compiled successfully",
"action": "NOTIFY_AGENT"
},
{
"pattern": "FATAL ERROR:",
"action": "NOTIFY_AGENT_AND_INTERRUPT"
}
]
}
}
``

1. Introduce a New Event Message:

When a trigger's pattern is matched in the process's output stream, the Claude Code backend should immediately push a new type of message to the agent, something like SystemTriggerEvent.

Example Event Message:
``json
{
"type": "system",
"subtype": "trigger_event",
"shellId": "sh-123",
"trigger": {
"pattern": "webpack compiled successfully"
},
"matchedLine": "[webpack] INFO: webpack compiled successfully in 2.1s"
}
``

This would allow the agent to immediately wake up and react to the event, enabling a new class of powerful, real-time workflows without the inefficiency and latency of polling.

Alternative Solutions

• Current Workaround: The agent must implement a polling loop in its internal logic: repeatedly call BashOutput, store the output, compare it to the previous output, and scan for new patterns.
• Drawbacks: This is extremely inefficient, introduces significant latency, and makes the agent's reasoning process complex and cluttered with boilerplate polling logic. It is not a scalable or robust solution.

• User-Managed External Scripts: A user could write a separate script that uses tail and grep to watch a log file and then calls back to the agent via an API or another trigger.
• Drawbacks: This is overly complex for the user, moves the core logic outside of the agent's control, and breaks the context of the ongoing conversation.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

A developer wants to run a complex data migration script and have the agent automatically validate the results once a specific step is complete.

1. User: "Start the data migration script in the background. When you see the message 'Phase 2: Data validation starting', run the validate-data.sh script to check for inconsistencies."
2. Claude: "Okay, I will start the migration and set a trigger to run the validation script when Phase 2 begins."
3. Claude (Internal Logic): Executes a Bash tool call for run-migration.sh with a trigger pattern Phase 2: Data validation starting.
4. (The migration script runs, logging its progress...)
5. Migration Script Output: ...INFO: Phase 2: Data validation starting...
6. Claude Code Backend: Detects the pattern match and sends a SystemTriggerEvent to the agent.
7. Claude (Reactively): "The migration has reached Phase 2. As requested, I am now executing the validate-data.sh script."
8. Claude (Internal Logic): Executes a new Bash tool call for validate-data.sh.

This demonstrates a seamless, automated, multi-stage workflow that is only possible with an event-driven model. The agent doesn't need to waste time and context polling the log; it acts precisely when needed.

Additional Context

• This feature is the second of three related requests for enhancing agentic process management. It builds upon the "Rich Process State" request and is a prerequisite for more "Advanced Process Control."
• This represents a fundamental architectural shift from a simple pull-based system to a far more powerful push-based, event-driven one, which is essential for building truly autonomous agents.