feat: pause-point round 10 feedback improvements

[hatayama]

Summary

Addresses pause-point round 10 CLI UX feedback (no pause-point core bugs; five surrounding CLI experience issues):

• P1: Unknown-option NextActions now guide to uloop <tool> --help instead of the non-existent --list-options
• P2: Unity publishes .uloop/tools.json on every domain reload so package updates no longer leave a stale tool cache (UNKNOWN_COMMAND for real tools)
• P3: Adds uloop version / uloop version --json, matching --version / --version --json
• P4: Accepts control-play-mode --action Resume as an alias of Play (pause-point workflows already use "resume" vocabulary)
• P5: enable-pause-point --await hit responses now include enable-time ResolvedLine / ResolvedLineText / ResolvedMethod / SnapshotTiming

Also stamps shared release inputs after non-test cli/common changes.

Test plan

• scripts/check-go-cli.sh (exit 0)
• P2: uloop sync then delete .uloop/tools.json, uloop compile (domain reload), cmp → IDENTICAL
• P3: uloop version matches uloop --version (text and --json)
• P4 E2E: Play → Pause → Resume → ResumedFromPause: true
• uloop compile → 0 errors / 0 warnings
• uloop run-tests full suite: 2361 passed, 0 failed, 7 platform-guarded skips (root status Skipped is pre-existing CLI semantics)

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds Resume Play Mode handling, publishes a tools cache, introduces a dispatcher version command, propagates pause-point resolution fields, and updates unknown-option guidance.

Changes

Play Mode Resume action

Layer / File(s)	Summary
Resume action contract and execution Packages/src/Editor/FirstPartyTools/ControlPlayMode/*, cli/common/tools/default-tools.json, cli/project-runner/internal/projectrunner/control_play_mode_wait.go	Adds Resume, routes it through Play handling, normalizes it for waiting, and preserves the requested action in errors.
Resume behavior validation Assets/Tests/Editor/*, cli/project-runner/internal/projectrunner/control_play_mode_wait_test.go	Tests compile-error blocking, wait polling, diagnostics, and requested-action preservation.
Resume action documentation .agents/skills/uloop-control-play-mode/SKILL.md, .claude/skills/uloop-control-play-mode/SKILL.md, Packages/src/Editor/FirstPartyTools/ControlPlayMode/Skill/SKILL.md	Documents Resume as an alias of Play across Play Mode states.

Tool catalog cache publishing

Layer / File(s)	Summary
Tool catalog cache generation and startup wiring Packages/src/Editor/Infrastructure/Api/ToolCatalogCachePublisher.cs, Packages/src/Editor/ToolContracts/UnityCliLoopConstants.cs, Packages/src/Editor/CompositionRoot/UnityCliLoopApplicationRegistration.cs	Publishes serialized tool details to .uloop/tools.json, avoids identical rewrites, and runs during editor registration.

Version command

Layer / File(s)	Summary
Version command registration cli/common/clicore/*, cli/dispatcher/internal/dispatcher/{help_test.go,native_command_options.go}, cli/project-runner/internal/projectrunner/runner_usage_test.go	Registers version as dispatcher-owned and updates help, option, ownership, and runner-rejection coverage.
Version request handling cli/dispatcher/internal/dispatcher/{version.go,dispatcher_version.go,dispatcher_process.go}	Handles plain, JSON, help, and invalid-option forms while sharing version output logic.
Version behavior validation cli/dispatcher/internal/dispatcher/dispatcher_test.go, cli/dispatcher/shared-inputs-stamp.json	Verifies subcommand output matches global version flags and validates trailing arguments.

Pause-point await response propagation

Layer / File(s)	Summary
Await response fields and propagation cli/project-runner/internal/projectrunner/{pause_point_types.go,pause_point_enable.go}	Adds optional resolution fields and carries enable-time values and warnings through awaited hit, fallback, and error responses.
Await propagation tests cli/project-runner/internal/projectrunner/pause_point_enable_test.go	Tests propagation for file-line enables and omission for method-name enables.

Tool option error guidance

Layer / File(s)	Summary
Unknown-option next actions cli/project-runner/internal/projectrunner/{tool_params.go,tool_params_test.go}, cli/project-runner/shared-inputs-stamp.json	Changes unknown-option guidance to the tool-specific help command and validates the resulting error action.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• hatayama/unity-cli-loop#1943: Modifies the same Play Mode action model and handling paths.
• hatayama/unity-cli-loop#1894: Modifies the pause-point --await flow and awaited response behavior.
• hatayama/unity-cli-loop#1354: Modifies the Play Mode compile-error blocking path used by the Resume alias.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.78% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is related to the main theme of the changes and clearly points to pause-point UX improvements.
Description check	✅ Passed	The description accurately summarizes the PR’s CLI UX changes and test plan.
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.

✨ 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 feature/pause-point-round10-feedback

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cli/common/tools/default-tools.json`:
- Line 329: Update the action description in the default-tools schema to
document Resume as an alias of Play that resumes a paused session or starts Play
Mode when the Editor is stopped, while preserving the descriptions of the other
actions.

In `@cli/dispatcher/internal/dispatcher/version.go`:
- Around line 28-33: Update the version argument error handling around the
dispatcher’s ArgumentError construction to identify the actual invalid argument,
including trailing arguments after a valid option such as --json, instead of
always using args[1]. Add the documented uloop version --help action to
NextActions, and add regression coverage for both the invalid trailing-argument
report and the help guidance.

In
`@Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs`:
- Around line 99-100: Update the StatusOnly compile-gate flow in
ControlPlayModeUseCase so PlayModeAction.Resume is normalized to Play before
calling ShouldBlockPlayForCompileErrors. Preserve the existing Resume execution
path through ExecutePlayModeStart and ensure both actions receive identical
compile-blocking behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 538edaf6-080f-4074-ad83-e3d78175f618

📥 Commits

Reviewing files that changed from the base of the PR and between 1ea3696 and 0d5f95a.

⛔ Files ignored due to path filters (1)

• Packages/src/Editor/Infrastructure/Api/ToolCatalogCachePublisher.cs.meta is excluded by none and included by none

📒 Files selected for processing (25)

• .agents/skills/uloop-control-play-mode/SKILL.md
• .claude/skills/uloop-control-play-mode/SKILL.md
• Packages/src/Editor/CompositionRoot/UnityCliLoopApplicationRegistration.cs
• Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeSchema.cs
• Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs
• Packages/src/Editor/FirstPartyTools/ControlPlayMode/Skill/SKILL.md
• Packages/src/Editor/Infrastructure/Api/ToolCatalogCachePublisher.cs
• Packages/src/Editor/ToolContracts/UnityCliLoopConstants.cs
• cli/common/clicore/command_registry.go
• cli/common/clicore/command_registry_test.go
• cli/common/tools/default-tools.json
• cli/dispatcher/internal/dispatcher/dispatcher_process.go
• cli/dispatcher/internal/dispatcher/dispatcher_test.go
• cli/dispatcher/internal/dispatcher/dispatcher_version.go
• cli/dispatcher/internal/dispatcher/help_test.go
• cli/dispatcher/internal/dispatcher/native_command_options.go
• cli/dispatcher/internal/dispatcher/version.go
• cli/dispatcher/shared-inputs-stamp.json
• cli/project-runner/internal/projectrunner/pause_point_enable.go
• cli/project-runner/internal/projectrunner/pause_point_enable_test.go
• cli/project-runner/internal/projectrunner/pause_point_types.go
• cli/project-runner/internal/projectrunner/runner_usage_test.go
• cli/project-runner/internal/projectrunner/tool_params.go
• cli/project-runner/internal/projectrunner/tool_params_test.go
• cli/project-runner/shared-inputs-stamp.json

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs (1)

98-100: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Bump the IPC protocol generation for the new Resume wire action.

A newer runner sends Resume to Unity, but a previous package generation does not define that action. Without a protocol bump, the exact-match gate can admit an incompatible pair that fails when this request is dispatched. Increment both cli/common/clicontract/contract.json protocolVersion and CliConstants.REQUIRED_CLI_PROTOCOL_VERSION; ensure the runner pin targets a published runner release advertising that protocol before package release.

As per path instructions, “If a change makes a CLI/package from the previous protocol generation unable to interoperate,” both protocol values must be incremented in the same PR.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs`
around lines 98 - 100, Increment the protocol version in
cli/common/clicontract/contract.json and update
CliConstants.REQUIRED_CLI_PROTOCOL_VERSION to the same new value for the added
PlayModeAction.Resume wire action. Update the runner version pin to a published
release advertising that protocol before release, keeping both protocol values
synchronized.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In
`@Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs`:
- Around line 98-100: Increment the protocol version in
cli/common/clicontract/contract.json and update
CliConstants.REQUIRED_CLI_PROTOCOL_VERSION to the same new value for the added
PlayModeAction.Resume wire action. Update the runner version pin to a published
release advertising that protocol before release, keeping both protocol values
synchronized.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d8b897d7-bf8b-4b07-a2fc-4ecf739ea4cc

📥 Commits

Reviewing files that changed from the base of the PR and between 0d5f95a and 3d4e79a.

📒 Files selected for processing (7)

• Assets/Tests/Editor/ControlPlayModeUseCaseTests.cs
• Packages/src/Editor/FirstPartyTools/ControlPlayMode/ControlPlayModeUseCase.cs
• cli/common/tools/default-tools.json
• cli/dispatcher/internal/dispatcher/dispatcher_test.go
• cli/dispatcher/internal/dispatcher/version.go
• cli/project-runner/internal/projectrunner/control_play_mode_wait.go
• cli/project-runner/internal/projectrunner/control_play_mode_wait_test.go

🚧 Files skipped from review as they are similar to previous changes (3)

• cli/dispatcher/internal/dispatcher/version.go
• cli/dispatcher/internal/dispatcher/dispatcher_test.go
• cli/common/tools/default-tools.json