feat: Pause Unity at named debug breaks for inspection

.agents/skills/uloop-simulate-keyboard/SKILL.md

@@ -14,7 +14,8 @@ Simulate keyboard input on Unity PlayMode: $ARGUMENTS
 1. Ensure Unity is in PlayMode (use `uloop control-play-mode --action Play` if not)
 2. Execute the appropriate `uloop simulate-keyboard` command
 3. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-4. Report what happened
+4. If the screenshot cannot prove the gameplay state, place and enable a `UnityCliLoopDebug.Break("<id>")` marker with `uloop enable-debug-break`, run the input again, then inspect while Unity is paused
+5. Report what happened
 
 ## Tool Reference
 
@@ -43,6 +44,13 @@ Use `Press` for edge-triggered gameplay code such as `Keyboard.current.spaceKey.
 If a successful `Press` or `KeyDown` leaves `Keyboard.current.<key>.isPressed` true but the game state does not change, do not immediately rewrite the user's gameplay code to `isPressed`. First verify that the gameplay component is active during the command, that it polls input in the configured Input System update phase, and that a missed `KeyDown` edge is followed by `KeyUp` before retrying.
 Use `KeyDown` / `KeyUp` when the scenario intentionally needs a held key.
 
+### Debug Break verification
+
+- Use `UnityCliLoopDebug.Break("<id>")` when a screenshot cannot prove that the keyboard input changed gameplay state, such as jump, sprint, or interaction.
+- Put the marker at a natural state transition after the game consumed the key, such as after jump velocity is applied, not immediately after sending `simulate-keyboard`.
+- If the response has `InterruptedByDebugBreak: true`, Unity is paused for inspection and the tool released its held input bookkeeping. If a `UnityCliLoopDebug.Break` marker caused the pause, `DebugBreakId` and `DebugBreakHitCount` identify it. Use `get-logs`, `get-hierarchy`, `find-game-objects`, or `execute-dynamic-code` before resuming.
+- Use distinct marker ids for strict phases, for example `jump-key-read` and `jump-velocity-applied`.
+
 ### KeyDown/KeyUp Rules
 
 - `KeyDown` fails if the key is already held
@@ -84,6 +92,9 @@ Returns JSON with:
 - `Message` (string): Description of what happened or why it failed
 - `Action` (string): The `--action` value that was applied (`Press`, `KeyDown`, or `KeyUp`)
 - `KeyName` (string, nullable): The key that was acted on; may be `null` when the action could not resolve a key
+- `InterruptedByDebugBreak` (boolean): True when Unity paused during Debug Break inspection and the input bookkeeping was safely released
+- `DebugBreakId` (string, nullable): The marker id when a `UnityCliLoopDebug.Break` marker caused the interruption
+- `DebugBreakHitCount` (integer, nullable): The marker hit count when a `UnityCliLoopDebug.Break` marker caused the interruption
 
 ## Prerequisites
 

.agents/skills/uloop-simulate-mouse-input/SKILL.md

@@ -15,7 +15,8 @@ Simulate mouse input via Input System in Unity PlayMode: $ARGUMENTS
 2. For Click/LongPress: determine the target screen position (use `uloop screenshot` to find coordinates)
 3. Execute the appropriate `uloop simulate-mouse-input` command
 4. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-5. Report what happened
+5. If the screenshot cannot prove the gameplay state, place and enable a `UnityCliLoopDebug.Break("<id>")` marker with `uloop enable-debug-break`, run the input again, then inspect while Unity is paused
+6. Report what happened
 
 ## Tool Reference
 
@@ -47,6 +48,13 @@ uloop simulate-mouse-input --action <action> [options]
 | `SmoothDelta` | Mouse.current.delta (per-frame) | Inject mouse delta smoothly over `--duration` seconds (human-like camera pan) |
 | `Scroll` | Mouse.current.scroll | Inject scroll wheel input (e.g. for hotbar or zoom) |
 
+### Debug Break verification
+
+- Use `UnityCliLoopDebug.Break("<id>")` when a screenshot cannot prove that mouse input changed gameplay state, such as block hit, camera turn, or item placement.
+- Put the marker at a natural state transition after the game consumed the mouse input, such as after a raycast hit, damage application, placement, or camera rotation update, not immediately after sending `simulate-mouse-input`.
+- If the response has `InterruptedByDebugBreak: true`, Unity is paused for inspection and the tool released its held input bookkeeping. If a `UnityCliLoopDebug.Break` marker caused the pause, `DebugBreakId` and `DebugBreakHitCount` identify it. Use `get-logs`, `get-hierarchy`, `find-game-objects`, or `execute-dynamic-code` before resuming.
+- Use distinct marker ids for strict phases, for example `block-raycast-hit` and `block-damage-applied`.
+
 ### Global Options (optional)
 
 | Option | Description |
@@ -106,5 +114,8 @@ Returns JSON with:
 - `Button`: Which button was used (nullable string; populated for `Click` / `LongPress`, null otherwise)
 - `PositionX`: Target X coordinate (nullable float; populated for `Click` / `LongPress`)
 - `PositionY`: Target Y coordinate (nullable float; populated for `Click` / `LongPress`)
+- `InterruptedByDebugBreak`: True when Unity paused during Debug Break inspection and the input bookkeeping was safely released
+- `DebugBreakId`: The marker id when a `UnityCliLoopDebug.Break` marker caused the interruption
+- `DebugBreakHitCount`: The marker hit count when a `UnityCliLoopDebug.Break` marker caused the interruption
 
-These are the only six fields. There is no `DeltaX`, `DeltaY`, `ScrollX`, `ScrollY`, `Duration`, or hit-element field in the response — only the issued action, button, and target position are echoed back. Verify visual outcome with a follow-up screenshot.
+There is no `DeltaX`, `DeltaY`, `ScrollX`, `ScrollY`, `Duration`, or hit-element field in the response — only the issued action, button, target position, and Debug Break interruption state are echoed back. Verify visual outcome with a follow-up screenshot.

.agents/skills/uloop-wait-for-debug-break/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: uloop-wait-for-debug-break
+description: "Pause Unity at named checkpoints for frame-specific PlayMode bugs and transient input, physics, async, or UI state changes."
+---
+
+# uloop wait-for-debug-break
+
+Pause Unity when execution reaches a named marker in user code.
+
+## When to use
+
+- Use when a bug appears only on a specific frame, timing window, animation step, physics tick, or `Update` / `FixedUpdate` branch.
+- Use proactively when PlayMode E2E or development debugging depends on proving a transient runtime state transition.
+- Use it alongside screenshots and logs; it is not only for cases where screenshots fail.
+- Good checkpoints include jump applied, launch complete, collision handled, score changed, line cleared, block mined, item placed, game over shown, or UI updated after input.
+- If you use sleep, repeated polling, or a second state read to catch a transient PlayMode state, prefer `wait-for-debug-break` instead.
+
+## Workflow
+
+1. Add a marker at the state you want to inspect:
+
+```csharp
+using io.github.hatayama.UnityCliLoop.Runtime;
+
+UnityCliLoopDebug.Break("player-jumped");
+```
+
+2. Compile the project.
+3. Enable the marker before triggering the code path:
+
+```bash
+uloop enable-debug-break --id player-jumped --timeout-seconds 30
+```
+
+4. Check marker state if needed:
+
+```bash
+uloop debug-break-status --id player-jumped
+```
+
+5. Trigger the behavior, such as `simulate-keyboard`, `simulate-mouse-input`, UI interaction, or dynamic code.
+6. Wait for the marker:
+
+```bash
+uloop wait-for-debug-break --id player-jumped --timeout-seconds 30
+```
+
+If this command times out, the marker line was not reached while the command waited. Inspect `error.details.status`, `hitCount`, `isPlaying`, `isPaused`, `elapsedSinceEnabledMilliseconds`, and `remainingMilliseconds` to distinguish input not being consumed, gameplay conditions not being met, an id mismatch, or Unity already being paused. `elapsedSinceEnabledMilliseconds` is measured from `enable-debug-break`, not from `wait-for-debug-break`.
+
+7. While Unity is paused, inspect state with `uloop get-logs`, `uloop get-hierarchy`, `uloop find-game-objects`, screenshots, or `uloop execute-dynamic-code`.
+8. Clear the marker if you stop waiting:
+
+```bash
+uloop clear-debug-break --id player-jumped
+```
+
+## Marker placement
+
+- Prefer natural gameplay or state-transition locations after input has been consumed, such as after jump velocity/state changes, physics contact, damage application, or inventory mutation.
+- For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
+- Enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return to avoid domain reload loss or tool Busy states.
+- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect; immediate markers can interrupt the input command before the resulting gameplay state settles.
+- Use separate ids for strict phases, for example `jump-input-read`, `jump-velocity-applied`, and `jump-landed`, instead of reusing one broad marker.
+
+## Safety
+
+- `UnityCliLoopDebug.Break` uses Unity's conditional-call pattern and is compiled out of non-Editor call sites.
+- Code in a custom asmdef must reference `UnityCLILoop.PausePoints.Runtime` to use `UnityCliLoopDebug.Break`.
+- Do not pass side-effect expressions as the id argument. Use stable string ids.
+- This does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
+- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable again after PlayMode starts.

.claude/skills/uloop-simulate-keyboard/SKILL.md

@@ -14,7 +14,8 @@ Simulate keyboard input on Unity PlayMode: $ARGUMENTS
 1. Ensure Unity is in PlayMode (use `uloop control-play-mode --action Play` if not)
 2. Execute the appropriate `uloop simulate-keyboard` command
 3. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-4. Report what happened
+4. If the screenshot cannot prove the gameplay state, place and enable a `UnityCliLoopDebug.Break("<id>")` marker with `uloop enable-debug-break`, run the input again, then inspect while Unity is paused
+5. Report what happened
 
 ## Tool Reference
 
@@ -43,6 +44,13 @@ Use `Press` for edge-triggered gameplay code such as `Keyboard.current.spaceKey.
 If a successful `Press` or `KeyDown` leaves `Keyboard.current.<key>.isPressed` true but the game state does not change, do not immediately rewrite the user's gameplay code to `isPressed`. First verify that the gameplay component is active during the command, that it polls input in the configured Input System update phase, and that a missed `KeyDown` edge is followed by `KeyUp` before retrying.
 Use `KeyDown` / `KeyUp` when the scenario intentionally needs a held key.
 
+### Debug Break verification
+
+- Use `UnityCliLoopDebug.Break("<id>")` when a screenshot cannot prove that the keyboard input changed gameplay state, such as jump, sprint, or interaction.
+- Put the marker at a natural state transition after the game consumed the key, such as after jump velocity is applied, not immediately after sending `simulate-keyboard`.
+- If the response has `InterruptedByDebugBreak: true`, Unity is paused for inspection and the tool released its held input bookkeeping. If a `UnityCliLoopDebug.Break` marker caused the pause, `DebugBreakId` and `DebugBreakHitCount` identify it. Use `get-logs`, `get-hierarchy`, `find-game-objects`, or `execute-dynamic-code` before resuming.
+- Use distinct marker ids for strict phases, for example `jump-key-read` and `jump-velocity-applied`.
+
 ### KeyDown/KeyUp Rules
 
 - `KeyDown` fails if the key is already held
@@ -84,6 +92,9 @@ Returns JSON with:
 - `Message` (string): Description of what happened or why it failed
 - `Action` (string): The `--action` value that was applied (`Press`, `KeyDown`, or `KeyUp`)
 - `KeyName` (string, nullable): The key that was acted on; may be `null` when the action could not resolve a key
+- `InterruptedByDebugBreak` (boolean): True when Unity paused during Debug Break inspection and the input bookkeeping was safely released
+- `DebugBreakId` (string, nullable): The marker id when a `UnityCliLoopDebug.Break` marker caused the interruption
+- `DebugBreakHitCount` (integer, nullable): The marker hit count when a `UnityCliLoopDebug.Break` marker caused the interruption
 
 ## Prerequisites
 

.claude/skills/uloop-simulate-mouse-input/SKILL.md

@@ -15,7 +15,8 @@ Simulate mouse input via Input System in Unity PlayMode: $ARGUMENTS
 2. For Click/LongPress: determine the target screen position (use `uloop screenshot` to find coordinates)
 3. Execute the appropriate `uloop simulate-mouse-input` command
 4. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-5. Report what happened
+5. If the screenshot cannot prove the gameplay state, place and enable a `UnityCliLoopDebug.Break("<id>")` marker with `uloop enable-debug-break`, run the input again, then inspect while Unity is paused
+6. Report what happened
 
 ## Tool Reference
 
@@ -47,6 +48,13 @@ uloop simulate-mouse-input --action <action> [options]
 | `SmoothDelta` | Mouse.current.delta (per-frame) | Inject mouse delta smoothly over `--duration` seconds (human-like camera pan) |
 | `Scroll` | Mouse.current.scroll | Inject scroll wheel input (e.g. for hotbar or zoom) |
 
+### Debug Break verification
+
+- Use `UnityCliLoopDebug.Break("<id>")` when a screenshot cannot prove that mouse input changed gameplay state, such as block hit, camera turn, or item placement.
+- Put the marker at a natural state transition after the game consumed the mouse input, such as after a raycast hit, damage application, placement, or camera rotation update, not immediately after sending `simulate-mouse-input`.
+- If the response has `InterruptedByDebugBreak: true`, Unity is paused for inspection and the tool released its held input bookkeeping. If a `UnityCliLoopDebug.Break` marker caused the pause, `DebugBreakId` and `DebugBreakHitCount` identify it. Use `get-logs`, `get-hierarchy`, `find-game-objects`, or `execute-dynamic-code` before resuming.
+- Use distinct marker ids for strict phases, for example `block-raycast-hit` and `block-damage-applied`.
+
 ### Global Options (optional)
 
 | Option | Description |
@@ -106,5 +114,8 @@ Returns JSON with:
 - `Button`: Which button was used (nullable string; populated for `Click` / `LongPress`, null otherwise)
 - `PositionX`: Target X coordinate (nullable float; populated for `Click` / `LongPress`)
 - `PositionY`: Target Y coordinate (nullable float; populated for `Click` / `LongPress`)
+- `InterruptedByDebugBreak`: True when Unity paused during Debug Break inspection and the input bookkeeping was safely released
+- `DebugBreakId`: The marker id when a `UnityCliLoopDebug.Break` marker caused the interruption
+- `DebugBreakHitCount`: The marker hit count when a `UnityCliLoopDebug.Break` marker caused the interruption
 
-These are the only six fields. There is no `DeltaX`, `DeltaY`, `ScrollX`, `ScrollY`, `Duration`, or hit-element field in the response — only the issued action, button, and target position are echoed back. Verify visual outcome with a follow-up screenshot.
+There is no `DeltaX`, `DeltaY`, `ScrollX`, `ScrollY`, `Duration`, or hit-element field in the response — only the issued action, button, target position, and Debug Break interruption state are echoed back. Verify visual outcome with a follow-up screenshot.

.claude/skills/uloop-wait-for-debug-break/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: uloop-wait-for-debug-break
+description: "Pause Unity at named checkpoints for frame-specific PlayMode bugs and transient input, physics, async, or UI state changes."
+---
+
+# uloop wait-for-debug-break
+
+Pause Unity when execution reaches a named marker in user code.
+
+## When to use
+
+- Use when a bug appears only on a specific frame, timing window, animation step, physics tick, or `Update` / `FixedUpdate` branch.
+- Use proactively when PlayMode E2E or development debugging depends on proving a transient runtime state transition.
+- Use it alongside screenshots and logs; it is not only for cases where screenshots fail.
+- Good checkpoints include jump applied, launch complete, collision handled, score changed, line cleared, block mined, item placed, game over shown, or UI updated after input.
+- If you use sleep, repeated polling, or a second state read to catch a transient PlayMode state, prefer `wait-for-debug-break` instead.
+
+## Workflow
+
+1. Add a marker at the state you want to inspect:
+
+```csharp
+using io.github.hatayama.UnityCliLoop.Runtime;
+
+UnityCliLoopDebug.Break("player-jumped");
+```
+
+2. Compile the project.
+3. Enable the marker before triggering the code path:
+
+```bash
+uloop enable-debug-break --id player-jumped --timeout-seconds 30
+```
+
+4. Check marker state if needed:
+
+```bash
+uloop debug-break-status --id player-jumped
+```
+
+5. Trigger the behavior, such as `simulate-keyboard`, `simulate-mouse-input`, UI interaction, or dynamic code.
+6. Wait for the marker:
+
+```bash
+uloop wait-for-debug-break --id player-jumped --timeout-seconds 30
+```
+
+If this command times out, the marker line was not reached while the command waited. Inspect `error.details.status`, `hitCount`, `isPlaying`, `isPaused`, `elapsedSinceEnabledMilliseconds`, and `remainingMilliseconds` to distinguish input not being consumed, gameplay conditions not being met, an id mismatch, or Unity already being paused. `elapsedSinceEnabledMilliseconds` is measured from `enable-debug-break`, not from `wait-for-debug-break`.
+
+7. While Unity is paused, inspect state with `uloop get-logs`, `uloop get-hierarchy`, `uloop find-game-objects`, screenshots, or `uloop execute-dynamic-code`.
+8. Clear the marker if you stop waiting:
+
+```bash
+uloop clear-debug-break --id player-jumped
+```
+
+## Marker placement
+
+- Prefer natural gameplay or state-transition locations after input has been consumed, such as after jump velocity/state changes, physics contact, damage application, or inventory mutation.
+- For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
+- Enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return to avoid domain reload loss or tool Busy states.
+- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect; immediate markers can interrupt the input command before the resulting gameplay state settles.
+- Use separate ids for strict phases, for example `jump-input-read`, `jump-velocity-applied`, and `jump-landed`, instead of reusing one broad marker.
+
+## Safety
+
+- `UnityCliLoopDebug.Break` uses Unity's conditional-call pattern and is compiled out of non-Editor call sites.
+- Code in a custom asmdef must reference `UnityCLILoop.PausePoints.Runtime` to use `UnityCliLoopDebug.Break`.
+- Do not pass side-effect expressions as the id argument. Use stable string ids.
+- This does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
+- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable again after PlayMode starts.