feat(core): phase 1 - add step-through mode scaffolding (ApprovalMode.STEP + MessageBus pause)

[TravisHaa]

Summary

Adds the backend scaffolding for a new STEP approval mode that pauses before every tool call, letting the user decide (execute / skip / continue / cancel) without being in DEFAULT confirmation mode.

Closes Phase 1 of #21484

• ApprovalMode.STEP = 'step' added to the core enum; wired through approvalModeUtils, ApprovalModeIndicator, Composer, and the CYCLE_APPROVAL_MODE keybinding cycle (DEFAULT → AUTO_EDIT → STEP → PLAN → DEFAULT)
• STEP_THROUGH_REQUEST / STEP_THROUGH_RESPONSE message bus types added to confirmation-bus/types.ts, mirroring the existing TOOL_CONFIRMATION_REQUEST/RESPONSE pattern
• packages/core/src/scheduler/step-through.ts — pauseForStepThrough() publishes a request and awaits a correlated response via node:events on() with abort-signal support
• Scheduler pause point inserted before the Executing transition when ApprovalMode.STEP is active; handles all four user actions: next (execute), skip (return empty result), cancel (abort all queued), continue (revert to DEFAULT and proceed)
• Keybindings for step-through controls: Enter/n = next, s = skip, c = continue

The UI dialog (ToolStepDialog + useStepThrough hook) that subscribes to the request and publishes the response will follow in a separate PR.

Test plan

• pnpm build passes
• pnpm lint passes
• pnpm typecheck passes
• Cycle through approval modes with the keybinding — STEP appears in the sequence
• ApprovalModeIndicator shows "step-through" label in accent color when STEP is active
• Composer bleed-through shows "step-through" text in STEP mode

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational backend scaffolding for a new "step-through" approval mode. This mode empowers users with granular control over tool execution by pausing before each tool call, enabling them to inspect inputs and make informed decisions to execute, skip, continue, or cancel the operation. The changes encompass new approval mode definitions, message bus communication patterns, scheduler logic to manage pausing and user responses, and CLI keybindings for interaction.

Highlights

• New Approval Mode: Introduced a new ApprovalMode.STEP that pauses before every tool call, allowing users to decide on execution.
• Message Bus Communication: Implemented new message bus types (STEP_THROUGH_REQUEST, STEP_THROUGH_RESPONSE) to facilitate communication between the scheduler and UI for step-through interactions.
• Scheduler Integration: Added core logic within the Scheduler to pause execution in STEP mode, publish requests, and handle user-defined actions (execute, skip, continue, cancel).
• CLI Keybindings: Defined new CLI commands and default keybindings (Enter/n for next, s for skip, c for continue) to control step-through actions.
• Approval Mode Cycling: Updated the approval mode cycling sequence to include STEP mode: DEFAULT → AUTO_EDIT → STEP → PLAN → DEFAULT.
• UI Updates: Modified ApprovalModeIndicator and Composer components to visually reflect when STEP mode is active.

Changelog

• packages/cli/src/config/keyBindings.ts
  • Added STEP_NEXT, STEP_SKIP, and STEP_CONTINUE commands to the Command enum.
  • Assigned default keybindings for the new step-through actions.
  • Created a new command category titled "Step-Through Mode".
  • Provided descriptive text for the new step-through commands.
• packages/cli/src/ui/components/ApprovalModeIndicator.tsx
  • Updated the component to display "step-through" with an accent color when ApprovalMode.STEP is active.
  • Adjusted the cycle hint text to correctly reflect the inclusion of "step" mode.
• packages/cli/src/ui/components/Composer.tsx
  • Modified the composer bleed-through to show "step-through" text with an accent color when ApprovalMode.STEP is active.
• packages/cli/src/ui/hooks/useApprovalModeIndicator.ts
  • Updated the approval mode cycling logic to incorporate ApprovalMode.STEP into the sequence: DEFAULT → AUTO_EDIT → STEP → [PLAN if allowed] → DEFAULT.
• packages/core/src/confirmation-bus/types.ts
  • Defined new MessageBusType values: STEP_THROUGH_REQUEST and STEP_THROUGH_RESPONSE.
  • Introduced StepThroughAction type and interfaces for StepThroughRequest and StepThroughResponse messages.
  • Extended the Message union type to include the newly defined step-through message types.
• packages/core/src/policy/types.ts
  • Added ApprovalMode.STEP enum value with a description for pausing before every tool call.
• packages/core/src/scheduler/scheduler.ts
  • Imported pauseForStepThrough and ApprovalMode.
  • Added stepIndex and stepTotal properties to track step-through progress within a batch.
  • Initialized stepIndex and stepTotal at the beginning of processing a new batch of requests.
  • Implemented a conditional block to pause execution for step-through mode before each tool execution.
  • Handled different StepThroughAction outcomes: skip (returns an empty successful result), cancel (aborts all queued calls), continue (reverts to DEFAULT mode), and next (proceeds with execution).
• packages/core/src/scheduler/step-through.ts
  • Added a new file containing the pauseForStepThrough asynchronous function.
  • Implemented pauseForStepThrough to publish a STEP_THROUGH_REQUEST to the message bus and await a STEP_THROUGH_RESPONSE from the UI, while respecting an abort signal.
• packages/core/src/utils/approvalModeUtils.ts
  • Added a descriptive string for the new ApprovalMode.STEP in getApprovalModeDescription.

Activity

• The pull request was created by TravisHaa.
• The description indicates the summary was generated with Claude Code.
• No human comments or reviews have been recorded yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces the backend scaffolding for a new 'step-through' approval mode, which is a great feature for giving users more granular control over tool execution. The changes are well-structured, adding the necessary enum values, message bus types, and core scheduler logic to pause before each tool call. The implementation in scheduler.ts and the new step-through.ts file correctly handles the different user actions (next, skip, continue, cancel). I've identified one potential issue regarding the step counter's accuracy with tail calls, which could lead to a confusing user experience.

[gemini-code-assist]

Code Review

This pull request introduces the backend scaffolding for a new STEP approval mode, which allows users to pause and inspect each tool call before execution. The changes are well-structured, adding the new approval mode to the core enum, updating relevant UI components and keybindings, and defining a new message bus protocol for step-through confirmation. The core logic in the Scheduler to pause execution and handle user actions (next, skip, continue, cancel) is sound and correctly implemented. The code adheres to existing patterns and is robust. I found no high or critical issues in this implementation.

[TravisHaa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the backend scaffolding for a new "step-through" approval mode, which is a great addition for finer-grained control over tool execution. The changes are well-structured, adding the necessary ApprovalMode enum, MessageBus types, and core pausing logic in the Scheduler. My review focuses on improving the robustness of the new state management logic to prevent future bugs, specifically by ensuring exhaustive handling of StepThroughAction to adhere to fail-closed principles.