[FEATURE] Include reason in tool result when Bash command moves to background

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

When a Bash command moves to background execution, the tool result returned to the model is always the same message regardless of the cause:

Command running in background with ID: xxx. Output is being written to: /path/to/output

There are at least three distinct causes for this transition:

1. The model explicitly set run_in_background: true (intentional)
2. The command exceeded its timeout and was moved to background
3. The user manually sent the command to background

The model cannot distinguish between these cases. This causes confusion and suboptimal behavior, particularly in case 2 (timeout): the model sees the same message it would see if it had requested background execution, but it didn't — so it has to guess what happened.

Observed behavior: When a long-running command timed out and was moved to background, the model's internal reasoning showed explicit confusion ("Oh wait, it ran in background? I didn't specify that. Let me check the output.") before recovering. It then had to infer the situation from context rather than from the tool result.

Proposed Solution

Include the reason for the background transition in the tool result message. For example:

Intentional (model requested):

Command running in background with ID: xxx. Output is being written to: /path
Reason: requested by model (run_in_background: true)

Timeout:

Command running in background with ID: xxx. Output is being written to: /path
Reason: command exceeded timeout (120000ms)

User action:

Command running in background with ID: xxx. Output is being written to: /path
Reason: moved to background by user

This is a small change to the tool result string, but it gives the model the information it needs to respond appropriately:

• Timeout → the command is still running; consider waiting or checking output later
• User action → the user wanted to move on; don't block on this result
• Intentional → expected behavior; proceed as planned

Alternative Solutions

• The model could infer the reason by checking whether it set run_in_background: true in its own tool call. However, this self-check is not reliable in practice — the model may not recall its own parameters accurately, especially in long sessions.
• A system message or annotation could be injected instead of modifying the tool result, but keeping the information in the tool result is simpler and more natural.

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

1. User asks the model to run a computationally expensive script
2. Model calls Bash with a 5-minute timeout but does NOT set run_in_background
3. The command takes longer than the timeout and is moved to background
4. Model receives: "Command running in background with ID: xxx..."
5. Model is confused — did it request this? Did the user do this? Is the command still running or did it fail?
6. Model wastes a turn checking the output or asking the user what happened

With the proposed change, step 4 would include "Reason: command exceeded timeout (300000ms)", and the model would immediately know to check the output later or inform the user that the command is still running.

Additional Context

This is particularly impactful for long-running operations like:

• Large file processing (e.g., AST parsing of 500K+ line files)
• Package installations
• Build processes
• Test suites

In all these cases, timeout-to-background is common and the model needs to know why it happened to decide its next action correctly.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)