Suppress cmux notifications for Codex subagents

[lawrencecchen]

Summary

• add a machine-readable subagent origin contract for child processes and custom-message metadata
• have the cmux Pi session hook skip the notification hook for subagent completions while retaining feed/stop telemetry
• apply Codex Fast mode through the shared provider hook for spawned Codex agents

Verification

• npm test
• npm run check

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Suppresses desktop completion notifications for Codex subagents while retaining feed/stop telemetry and display behavior. Previously subagents disabled cmux hooks globally; now the session classifies subagent work and only skips completion notifications, and it avoids mutating parent completion events.

• Adds src/subagent-origin.ts with a shared origin contract (PI_CODEX_SUBAGENT="pi-codex-subagent-v1") and helpers to classify events and route notifications; attaches typed subagent details on agent_end only for subagent events.
• Updates the tab-title subagent to use subagentEnvironment(); suppression is independent of Pi custom-message display state.
• Requests Codex Fast mode for spawned Codex agents through the shared provider hook.

Migration

• External subagents must set PI_CODEX_SUBAGENT="pi-codex-subagent-v1" or include cmux_activity_origin: "subagent" in custom-message details to suppress completion notifications.
• Stop using CMUX_PI_HOOKS_DISABLED and CMUX_SUPPRESS_SUBAGENT_NOTIFICATIONS.

^{Written for commit be184c6. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Improved handling of activity from spawned Codex processes.
  • Child activity and stop telemetry remain visible while desktop completion notifications are suppressed.
  • Spawned Codex agents now use the shared Fast-mode service tier.

• Documentation

  • Updated Behavior documentation to explain subagent activity markers and notification handling.

• Tests

  • Added coverage for subagent detection, parent activity fallback, notification routing, and Fast-mode requests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1c18633c-daf7-4989-bc1f-6f40dcdb7d75

📥 Commits

Reviewing files that changed from the base of the PR and between 811a0f4 and c859a15.

📒 Files selected for processing (5)

• README.md
• extensions/cmux-tab-title.ts
• extensions/pi-codex.ts
• src/subagent-origin.ts
• test/pi-codex.test.ts

---

📝 Walkthrough

Walkthrough

The change adds shared subagent-origin helpers, propagates origin markers to spawned Codex processes, annotates subagent completion events, and routes completion notifications only for parent activity. Tests cover classification, routing, and Fast-mode service-tier propagation.

Changes

Subagent origin handling

Layer / File(s)	Summary
Origin classification and routing src/subagent-origin.ts	Defines origin constants, metadata types, environment marking, lifecycle classification, and parent-only completion notification routing.
Subagent propagation and event handling extensions/cmux-tab-title.ts, extensions/pi-codex.ts, README.md	Uses the shared marker for title-generation processes. agent_end annotates subagent events and messages. The README documents the cmux telemetry behavior.
Origin behavior and provider validation test/pi-codex.test.ts	Tests environment and metadata detection, parent fallback, notification routing, and Fast-mode service-tier propagation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: 🟡 Moderate · up to c859a

The change may still emit desktop completion notifications for subagents because the new routing decision is not connected to the cmux session hook; merge should wait for that integration or explicit owner acceptance.

Sequence Diagram(s)

sequenceDiagram
  participant SpawnedCodex
  participant PiCodex
  participant Cmux
  SpawnedCodex->>PiCodex: agent_end event
  PiCodex->>PiCodex: Classify subagent origin
  PiCodex->>Cmux: Annotated event and messages
  Cmux->>Cmux: Retain child telemetry
  Cmux->>Cmux: Suppress desktop completion notification

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: suppressing cmux completion notifications for Codex subagents.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/subagent-notification-suppression

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}