[fleet demo] docs: sync agent-hooks event list

[austinywang]

Doc sync against WorkstreamEvent.HookEventName. Created autonomously by the cmux Fleet orchestration demo (#7361 PR 3 dogfood); fine to close if unwanted.

---

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

---

Summary by cubic

Syncs the agent hooks docs with the canonical HookEventName list. Adds the explicit event list and clarifies that per‑agent hook names in CLI/CMUXCLI+AgentHookDefinitions.swift map to Packages/macOS/CMUXAgentLaunch/Sources/CMUXAgentLaunch/Workstream/WorkstreamEvent.swift and do not add new events.

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

Summary by CodeRabbit

• Documentation
  • Clarified that the canonical hook event name list is defined by the shared enum, and that each agent’s event wiring maps its native events onto this canonical set.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Canceled		Jul 6, 2026 4:57am
cmux-staging	Building	Preview, Comment	Jul 6, 2026 4:57am

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a documentation note in docs/agent-hooks.md clarifying that hook event names are canonically defined by the HookEventName enum in WorkstreamEvent.swift, with per-agent event wiring in CLI/CMUXCLI+AgentHookDefinitions.swift.

Changes

Documentation update

Layer / File(s)	Summary
Add clarification note docs/agent-hooks.md	Added a sentence identifying the canonical source for hook event names and the per-agent mapping reference.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• manaflow-ai/cmux#4225: Related hook-definition wiring changes touch the same event-name mapping concepts referenced in this documentation update.

🚥 Pre-merge checks | ✅ 24 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description only gives a brief summary and omits required Testing, Demo Video, Review Trigger, and Checklist sections.	Add the missing template sections with what changed, why, testing/verification, demo video or N/A, review trigger, and checklist.

✅ Passed checks (24 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.
Cmux Swift Actor Isolation	✅ Passed	Only docs/agent-hooks.md changed; no Swift code or actor-isolation-relevant production changes were introduced.
Cmux Swift Blocking Runtime	✅ Passed	Diff only changes docs/agent-hooks.md; no Swift runtime code was added or modified, so the blocking-runtime rule is not implicated.
Cmux Browser Automation Off-Main	✅ Passed	Only docs/agent-hooks.md changed; no browser.* routing, mainActor, WebKit/AppKit, or policy-test files were modified.
Cmux Expensive Synchronous Load	✅ Passed	Only docs/agent-hooks.md changed; no Swift code or synchronous load path was added or moved.
Cmux Cache Substitution Correctness	✅ Passed	PR only updates docs/agent-hooks.md; no Swift/TS/JS persistence, history, undo, or snapshot code is changed, so cache substitution correctness is not implicated.
Cmux No Hacky Sleeps	✅ Passed	Only docs/agent-hooks.md changed; the runtime-no-hacky-sleeps rule targets non-Swift runtime code, not docs.
Cmux Algorithmic Complexity	✅ Passed	Only docs/agent-hooks.md changed; no production Swift/TS/JS/shell/runtime code was modified, so the complexity rule is not implicated.
Cmux Swift Concurrency	✅ Passed	Diff only changes docs/agent-hooks.md; no Swift files or async code changed, so the concurrency modernization check is not applicable.
Cmux Swift @Concurrent	✅ Passed	Diff only touches docs/agent-hooks.md; no Swift files changed, so the @concurrent rule is not applicable.
Cmux Swift File And Package Boundaries	✅ Passed	Only docs/agent-hooks.md changed; no Swift or package-boundary code was modified, so the rule is not applicable.
Cmux Swiftpm Lockfiles	✅ Passed	Only docs/agent-hooks.md changed; no SwiftPM, Xcode, .gitignore, workflow, or dependency files were modified.
Cmux Swift Logging	✅ Passed	Docs-only diff; no Swift/runtime logging statements were added or changed, so the Swift logging rule is not implicated.
Cmux User-Facing Error Privacy	✅ Passed	Change is docs-only, and the added text is explanatory documentation rather than user-facing errors or alerts.
Cmux Full Internationalization	✅ Passed	The PR only adds a clarification to docs/agent-hooks.md; no Swift/UI strings, web messages, or locale catalogs were changed.
Cmux Swiftui State Layout	✅ Passed	Diff is docs-only (docs/agent-hooks.md), with no SwiftUI source changes, so the SwiftUI state/layout rules are not implicated.
Cmux Architecture Rethink	✅ Passed	Diff only touches docs/agent-hooks.md; no Swift code or architectural behavior changed, so the rethink rule isn’t implicated.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	Only docs/agent-hooks.md changed; no Swift windows or shortcut-routing code was added or modified.
Cmux Source Artifacts	✅ Passed	Only docs/agent-hooks.md changed, and the added text is deliberate documentation referencing source-of-truth code, not a local/generated artifact.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	Only docs/agent-hooks.md changed; no Swift files under production Sources/ changed, so the no-test-debug-seam rule is not applicable.
Cmux No Ambient Global State	✅ Passed	Only docs/agent-hooks.md changed; no Swift code or new ambient global state was introduced.
Title check	✅ Passed	The title clearly states the docs sync for the agent-hooks event list, matching the PR's main change.

✨ 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 fleet/local_1cf92170-a45d-4b11-8d1b-2711c3905883-77f2ec36

---

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.}

[greptile-apps]

Greptile Summary

This PR adds a single documentation paragraph to docs/agent-hooks.md syncing the canonical hook event list with WorkstreamEvent.HookEventName. The change is a docs-only addition with no production code changes.

• Adds the full 15-event list (SessionStart through Notification) with pointers to the authoritative Swift enum in WorkstreamEvent.swift and the per-agent wiring file CMUXCLI+AgentHookDefinitions.swift.
• Clarifies that native per-agent event names (e.g., beforeShellExecution, on_tool_permission) are agent-local vocabulary that maps onto the canonical set rather than extending it.

Confidence Score: 5/5

Docs-only addition; no production code touched.

The change adds a single paragraph to a documentation file. All 15 event names listed were verified against the authoritative HookEventName enum in WorkstreamEvent.swift and match exactly. No Swift, web, config, or runtime code is modified.

No files require special attention.

Important Files Changed

Filename	Overview
docs/agent-hooks.md	Adds one paragraph listing the canonical HookEventName events; all 15 names verified accurate against WorkstreamEvent.swift.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent Hook Event] --> B{HookEventName enum\nWorkstreamEvent.swift}
    B --> C[SessionStart / SessionEnd]
    B --> D[UserPromptSubmit]
    B --> E[PreToolUse / PostToolUse]
    B --> F[PreCompact / PostCompact]
    B --> G[PermissionRequest]
    B --> H[AskUserQuestion / ExitPlanMode / TodoWrite]
    B --> I[Stop / SubagentStart / SubagentStop]
    B --> J[Notification]
    B --> K[CMUXCLI+AgentHookDefinitions.swift\nPer-agent native → canonical mapping]
    K --> L[e.g. beforeShellExecution → PreToolUse]
    K --> M[e.g. on_tool_permission → PermissionRequest]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Agent Hook Event] --> B{HookEventName enum\nWorkstreamEvent.swift}
    B --> C[SessionStart / SessionEnd]
    B --> D[UserPromptSubmit]
    B --> E[PreToolUse / PostToolUse]
    B --> F[PreCompact / PostCompact]
    B --> G[PermissionRequest]
    B --> H[AskUserQuestion / ExitPlanMode / TodoWrite]
    B --> I[Stop / SubagentStart / SubagentStop]
    B --> J[Notification]
    B --> K[CMUXCLI+AgentHookDefinitions.swift\nPer-agent native → canonical mapping]
    K --> L[e.g. beforeShellExecution → PreToolUse]
    K --> M[e.g. on_tool_permission → PermissionRequest]

Loading

_{Reviews (2): Last reviewed commit: "[fleet demo] docs: sync agent-hooks even..." | Re-trigger Greptile}