🤖 feat: unify bash into task_* tools

[ThomasK33]

This PR makes task_* the single tool surface for both sub-agent tasks and bash execution.

Highlights

• task(kind="bash") supports foreground bash execution (with output limits/truncation) and background spawn (returns bash:<processId>).
• task_await can await both agent reports and bash incremental output (with filter/filter_exclude + timeout semantics).
• task_list / task_terminate now include bash tasks, with descendant-scope checks.
• Tool exposure is tightened so models don’t see the legacy bash_* tools by default (wrappers remain temporarily for compatibility).

Follow-ups addressed in this PR

• Preserved signal when bash output is truncated: task results surface truncated metadata and include an explicit warning in reportMarkdown.
• Fixed agent task scoping after cleanup: task_await can still await a completed sub-agent even if its workspace has been removed.
• UI: task(kind="bash") now renders using the existing Bash tool UI (instead of the task UI wrapper).
• Polling guidance notes are tool-aware (no references to bash_output when surfaced via task_await).

Validation

• make static-check
• bun test src/node/services/tools/task.test.ts src/node/services/tools/task.bash.test.ts
• bun test src/node/services/backgroundProcessManager.test.ts src/node/services/tools/task_await.test.ts
• bun test src/node/services/taskService.test.ts

---

📋 Implementation Plan

Consolidate bash_* into the task_* abstraction (task = agent | bash)

Goal

Reduce tool surface overlap by making task_* the single abstraction for both:

• Agent tasks (existing subagent workspaces)
• Bash tasks (existing background processes + foreground bash execution)

Success criteria

• Models no longer see/need bash, bash_output, bash_background_list, bash_background_terminate in the default toolset.
• task, task_await, task_list, task_terminate cover the full bash workflow:
  • spawn (fg/bg)
  • incremental output
  • list
  • terminate
• Existing behaviors preserved:
  • bash output limits + truncation handling
  • background process semantics (timeouts, filters, queued-message interruption)
  • task scoping rules (only manage descendant work)

Recommended approach (net product LoC ≈ +450)
Extend the task_* tools to support a new bash task kind, backed by BackgroundProcessManager, and stop exposing bash_* to models (align getToolsForModel() with the getAvailableTools() allowlist; keep legacy wrappers temporarily).

---

1) API shape (tool schemas)

1.1 task args: union of agent + bash

Update TaskToolArgsSchema in src/common/utils/tools/toolDefinitions.ts from a single strict object to a strict union:

• Agent (unchanged):
  • { subagent_type, prompt, title, run_in_background? }
• Bash (new):
  • { kind: "bash", script, timeout_secs, run_in_background?, display_name }

Notes:

• Keep agent shape unchanged to avoid breaking existing tool calls.
• Require kind: "bash" so parsing is unambiguous.

1.2 task results: keep current discriminant, add optional bash fields

To avoid changing the status-based discriminated unions:

• Keep status: "queued"|"running"|"completed" exactly as-is.
• Extend completed results with optional bash-oriented fields (safe additive change):
  • exitCode?: number
  • note?: string
  • truncated?: { reason: string; totalLines: number }

For bash tasks:

• Foreground completion returns status:"completed" with reportMarkdown containing a formatted bash summary + output.
• Background spawn returns status:"running" and a taskId.

1.3 task_await becomes the unified “await output/report”

Update TaskAwaitToolArgsSchema to add bash-output knobs (all optional):

• filter?: string
• filter_exclude?: boolean
• timeout_secs?: number (allow 0 for non-blocking, aligning with bash_output)

Update TaskAwaitTool*ResultSchema to include optional streaming fields on active/completed results:

• output?: string (incremental output when kind=bash)
• elapsed_ms?: number
• exitCode?: number
• note?: string

Mapping:

• Agent tasks: identical behavior (waits for agent_report).
• Bash tasks: delegates to BackgroundProcessManager.getOutput(); may return status:"running" with output populated.

Timeout semantics for bash tasks (replacing bash_output):

• task_await.timeout_secs is forwarded to BackgroundProcessManager.getOutput(...) and means “wait up to N seconds for new output (or process exit)”.
• If the timeout elapses and the process is still running, return status:"running" and whatever incremental output was read since the previous call (output may be empty).
• Output is the existing unified stream (stdout+stderr combined from output.log); incomplete final line fragments remain buffered until newline/exit.

1.4 task_list returns both kinds

Extend TaskListToolTaskSchema additively:

• kind?: "agent"|"bash" (optional; omit for agent tasks to minimize churn)
• display_name?: string (bash)
• script?: string (bash)
• uptime_ms?: number (bash)
• exitCode?: number (bash)
• Option A (minimal): map bash terminal statuses to status:"reported" and include exitCode.
• Option B (more expressive): extend TaskListStatusSchema with exited|killed|failed and plumb through.

1.5 task_terminate supports both

Keep task_terminate input shape, but broaden semantics:

• task_ids may include agent or bash tasks.

For results:

• Keep existing terminatedTaskIds array.
• For bash terminations, return terminatedTaskIds: [taskId].

---

2) Backend implementation (node/services/tools)

2.1 Add a tiny task-id router (defensive)

Create a helper (new file) e.g. src/node/services/tools/taskId.ts:

• isBashTaskId(taskId: string): boolean
• toBashTaskId(processId: string): string (e.g. bash:${processId})
• fromBashTaskId(taskId: string): string | null

Defensive checks:

• assert(taskId.trim().length > 0)
• reject malformed bash: ids early with explicit errors.

2.2 Implement task(kind=bash) in src/node/services/tools/task.ts

Dispatch based on args shape:

• Agent path: unchanged.
• Bash path:
  • Validate required deps: config.runtime, config.backgroundProcessManager, config.workspaceId.
  • If run_in_background=true:
    • Call backgroundProcessManager.spawn(runtime, workspaceId, script, { cwd, env, displayName, timeoutSecs }).
    • Return status:"running", taskId: toBashTaskId(processId).
  • If run_in_background=false:
    • Reuse existing bash execution logic (see 2.3) to preserve output limits/truncation.
    • Convert BashToolResult → TaskToolCompletedResult.

2.3 De-duplicate bash execution logic

Refactor src/node/services/tools/bash.ts so that foreground execution is callable from both tools:

• Extract a pure helper like executeBashForeground(config, args, ctx): Promise<BashToolResult>.
• createBashTool() remains as thin wrapper.
• createTaskTool() uses the helper for bash foreground tasks.

This avoids re-implementing:

• line/byte limits
• tmpfile overflow policy
• streaming-to-UI behavior

2.4 Extend task_await to support bash tasks

In src/node/services/tools/task_await.ts:

• Determine candidate IDs:
  • If args.task_ids provided: use them.
  • Else: union of
    • taskService.listActiveDescendantAgentTaskIds(workspaceId)
    • backgroundProcessManager.list() filtered to descendant workspaces + status === "running"
• For each id:
  • If agent id: existing waitForAgentReport() behavior.
  • If bash id:
    • scope check: process.workspaceId must be workspaceId or a descendant agent workspace
    • call backgroundProcessManager.getOutput(processId, filter, filter_exclude, timeout_secs, abortSignal, workspaceId)
    • return:
      • status:"running" with output when running
      • status:"completed" with reportMarkdown and exitCode when exited/killed/failed
      • map interrupted → status:"running" with note:"interrupted" (or add a new status if you choose to extend the schema)

2.5 Extend task_list to merge bash processes

In src/node/services/tools/task_list.ts:

• Get descendant agent tasks as today.
• Compute the set of descendant workspace IDs (include current workspace).
• backgroundProcessManager.list() and include any process whose workspaceId is in that set.
• Convert each process into a TaskListToolTaskSchema entry.
  • Depth: workspaceDepth(process.workspaceId) + 1 (or 1 if owned by current workspace).

2.6 Extend task_terminate to terminate bash tasks

In src/node/services/tools/task_terminate.ts:

• For each id:
  • agent id → existing terminateDescendantAgentTask()
  • bash id → scope check + backgroundProcessManager.terminate(processId)

Optional improvement:

• If terminating an agent task, also terminate any bash processes owned by that terminated subtree (defensive cleanup). This should be safe since BackgroundProcessManager.cleanup(workspaceId) already exists, but doing it explicitly makes the tool semantics deterministic.

2.7 Tool wiring: ensure task_* are init-wait wrapped

Because task_* will now execute bash (runtime-dependent), update src/common/utils/tools/tools.ts#getToolsForModel:

• Wrap task, task_await, task_list, task_terminate with wrapWithInitWait(...) (same as bash today).
  • This prevents calling into runtime.exec() / BackgroundProcessManager before workspace init.
• Keep ask_user_question, propose_plan, todo_*, status_set non-runtime.

---

3) Tool exposure + deprecation

3.1 Remove bash_* from the actual model toolset (not just prompt)

Today, getAvailableTools() is used for system prompt + tool-instruction extraction, but the model still receives whatever getToolsForModel() returns (unless a toolPolicy denies it).

To truly eliminate overlap:

1. Filter the tools passed to the model to the allowlist from getAvailableTools(modelString, mode, options) (plus MCP tools). Best place: src/common/utils/tools/tools.ts#getToolsForModel just before returning.
2. Once (1) is in place, remove these from getAvailableTools() (src/common/utils/tools/toolDefinitions.ts):
   • bash
   • bash_output
   • bash_background_list
   • bash_background_terminate
3. Optional cleanup: stop constructing legacy bash_* tools at all (or gate behind a temporary env/feature flag).

3.2 Keep legacy bash_* as wrappers (short-lived)

To reduce risk, keep the tools around during rollout:

• Update their descriptions to say “Deprecated: use task with kind:"bash".”
• Optionally re-implement bash_output/list/terminate by delegating to the new task_* internals.

Why keep wrappers temporarily?

• Some internal code paths / older sessions may still refer to bash_* tool names.
• PTC sandbox currently lists bash_* as bridgeable tools.
• Keeping wrappers allows phased migration without a flag day.

---

4) Frontend/UI updates (tool message rendering)

Because the model will now call task_* for bash operations, update task-tool renderers to handle the new union types:

• src/browser/components/tools/TaskToolCall.tsx

  • TaskToolCall: render bash variant (script, display_name, background vs foreground)
  • TaskAwaitResult: if output present, render it (even when status !== completed)
  • TaskListItem: display display_name/script when agentType/title absent
  • TaskStatusBadge: optionally style bash terminal states if you extend the enum

• src/browser/stories/App.task.stories.tsx + src/browser/stories/mockFactory.ts

  • Add a scenario showing a bash task spawned in background, then task_await output streaming.

---

5) Tests + validation

5.1 Backend tool tests

Add/extend tests under src/node/services/tools/:

• task.bash.test.ts (new):
  • spawn bash task in background
  • task_await returns incremental output + running
  • task_terminate kills it
• task_list includes bash processes for:
  • current workspace
  • descendant workspace (spawned by a child agent workspace)
• scope validation:
  • parent can manage descendant’s bash tasks
  • unrelated workspace cannot

5.2 UI rendering tests (lightweight)

If there are existing component tests, add minimal assertions for bash-variant rendering. Otherwise rely on storybook + typecheck.

5.3 Manual validation checklist

• make typecheck
• Run targeted unit tests:
  • bun test src/node/services/tools/task_await.test.ts
  • bun test src/node/services/tools/task_list.test.ts (or add if missing)
  • bun test src/node/services/tools/bash_output.test.ts (ensure wrappers still work if kept)

---

6) Rollout plan

1. Land schema + backend changes (task supports bash, task_await/list/terminate support bash IDs).
2. Update UI tool renderers to avoid regressions.
3. Remove bash_* from getAvailableTools() so models stop seeing them.
4. After a release or two, delete legacy wrappers and remove bash_* from PTC bridgeables if desired.

---

Generated with mux • Model: openai:gpt-5.2 • Thinking: xhigh

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

Fixed in db76e83 - coerceTimeoutMs now accepts 0 and only rejects negative values, so timeout_secs: 0 correctly translates to an immediate non-blocking check for both agent and bash tasks.

[ThomasK33]

@codex review

Follow-up: fixed static-check by aligning RefreshController unit tests with the current (post-revert) RefreshController API.

[chatgpt-codex-connector]

💡 Codex Review

mux/src/node/services/tools/task_await.ts

Lines 174 to 176 in f84415d

	try {
	const report = await taskService.waitForAgentReport(taskId, {
	timeoutMs,

Handle timeout_secs=0 for agent tasks

task_await now allows timeout_secs=0 (per schema/docs for non‑blocking bash), but createTaskAwaitTool forwards timeoutMs directly into taskService.waitForAgentReport. When timeout_secs is 0 and any agent task is included (explicitly or via the default “all active tasks”), waitForAgentReport asserts timeoutMs > 0 and throws, so those agent results come back as error instead of queued|running|awaiting_report. Consider treating 0 as “no wait” for agent tasks (return current status) or defaulting to the 10‑minute wait when timeout_secs is 0.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

Fixed in cac38ca.

• task_await now treats timeout_secs: 0 (or values that round down to 0ms) as non-blocking for agent tasks.
• We validate scope first, then return the current task status (queued/running/awaiting_report) instead of calling waitForAgentReport (which asserts timeoutMs > 0).
• Added a regression test covering timeout_secs=0.

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

@codex review

Addressed the truncation metadata issue for task(kind="bash") by:

• adding truncated?: { reason; totalLines } to the task completed result schema
• including a truncation warning + metadata in reportMarkdown when present
• making bash tool init lazy so agent-only task tests don't require bash deps

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".