Feat/task tree step through

[Khushi281300]

## Summary

Adds **Interactive Progress Visualization and Task Stepping** to the CLI, enabling users to inspect and control multi-step agent execution.

This introduces a hierarchical **task tree view** for tool calls and a new **STEP approval mode** that pauses execution before each tool dispatch. Users can review tool inputs, decide whether to run or skip a tool, and navigate execution interactively.

The goal is to improve **transparency, debugging, and trust** when the agent performs complex multi-step operations across multiple tools or subagents.

---

## Details

This PR implements the first three phases of the Interactive Visualization roadmap.

### Phase 1 – Core Scheduler Scaffolding
- Added `ApprovalMode.STEP` to the core configuration.
- Introduced `STEP_THROUGH_REQUEST` and `STEP_THROUGH_RESPONSE` events in the message bus.
- Implemented scheduler pause/resume logic before tool dispatch.
- Added cancellation propagation and queue suspension while step mode is active.
- Added strict tool lifecycle states:
  

queued → pending → running → success | error | cancelled

### Phase 2 – Step-Through UI
- Implemented `useStepThrough` hook to listen for step events.
- Added `ToolStepDialog` component to preview tool execution.
- Added keyboard controls:

- `Enter` / `n` → run tool  
- `s` → skip tool  
- `c` → continue without stepping  
- `q` / `Esc` → cancel execution

- Added focus lock so the task tree does not consume input while the dialog is active.
- Added step counter and footer hints for user interaction.

### Phase 3 – Task Tree Visualization
- Implemented `useTaskTree` hook to convert flat `TrackedToolCall` arrays into hierarchical structures using `parentCallId`.
- Added `TaskTreeDisplay` and recursive `TaskNode` components for rendering the tree.
- Integrated subagent progress into the task tree.
- Implemented keyboard navigation with focus pointer management.
- Ensured compatibility with existing `ScrollableList`.
- Implemented `freezeTreeState()` behavior so completed task trees render safely inside Ink `<Static>` blocks.

The task tree is currently available behind an experimental feature flag:

```experimental.taskTree

---

Related Issues

Closes #21484

---

How to Validate

1. Install dependencies and build the project:

npm install
npm run build

2. Start the CLI:

npm start

3. Enable STEP mode.

4. Run a command that triggers multiple tool calls, for example:

refactor this file

5. Expected behavior:

• The CLI pauses before each tool execution.
• A step dialog appears showing tool name and input.
• Users can run, skip, or cancel the tool execution.
• Tool calls are displayed in a hierarchical task tree.
• Subagent tasks appear nested under their parent nodes.

6. Verify keyboard navigation:

• ↑ / ↓ moves focus across nodes
• Enter interacts with the selected node
• Step dialog keyboard controls function correctly

---

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)

Validated Platforms

• Windows

  • npm run
  • npx
  • Docker

• MacOS

  • Podman
  • Seatbelt

• Linux

[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 introduces significant enhancements to the CLI's interactive capabilities, providing users with unprecedented control and visibility over agent execution. By implementing a step-through approval mode and a hierarchical task tree visualization, the system now allows for detailed inspection and interactive management of complex, multi-step operations, fostering greater trust and facilitating debugging of agentic workflows.

Highlights

• Interactive Progress Visualization and Task Stepping: Introduced a new 'STEP' approval mode that pauses execution before each tool dispatch, allowing users to inspect tool inputs, decide whether to run or skip a tool, and navigate execution interactively. This significantly improves transparency and debugging for multi-step agent operations.
• Hierarchical Task Tree View: Implemented a hierarchical task tree visualization for tool calls, including subagent progress, to provide a clear overview of complex agentic flows. This feature is currently available behind an experimental flag (experimental.taskTree).
• Enhanced UI Controls and Feedback: Added keyboard controls for interacting with the step-through dialog (run, skip, continue, cancel) and for navigating/collapsing/expanding nodes in the task tree. The UI now includes a 'step-through' indicator and a new /verbosity command to control output verbosity.
• Core Scheduler and Configuration Updates: Integrated ApprovalMode.STEP into the core configuration, introduced STEP_THROUGH_REQUEST and STEP_THROUGH_RESPONSE events for the message bus, and implemented scheduler pause/resume logic. Configuration settings for defaultApprovalMode, ui.verbosityLevel, ui.verbosityOverrides, and experimental.taskTree were updated or added.
• Improved Tool Call Tracking: Modified tool call tracking to include liveOutput for executing tools, with a ring buffer applied to shell tool output to manage large logs. Completed tool calls now also record an endTime.

Changelog

• README.md
  • Updated README to mention interactive task tree visualization.
• docs/CONTRIBUTING.md
  • Modified file with a minor change, likely a newline adjustment.
• docs/cli/cli-reference.md
  • Added /verbosity <level> command to the CLI reference.
  • Updated --approval-mode CLI option to include step as a choice.
• docs/cli/settings.md
  • Updated description for general.defaultApprovalMode to include 'step' mode.
  • Added documentation for new ui.verbosityLevel and ui.verbosityOverrides settings.
  • Added documentation for the new experimental.taskTree setting.
• docs/reference/configuration.md
  • Updated general.defaultApprovalMode configuration to include 'step' mode.
  • Added configuration details for ui.verbosityLevel and ui.verbosityOverrides.
  • Added configuration details for experimental.taskTree.
• errors-cli-8.txt
  • Added a new file containing TypeScript compilation errors, likely for tracking or testing purposes.
• packages/a2a-server/errors8.txt
  • Added a new file containing TypeScript compilation errors, likely for tracking or testing purposes.
• packages/cli/src/config/keyBindings.ts
  • Added TREE_EXPAND and TREE_COLLAPSE commands to the keybinding configuration.
  • Defined default keybindings for task tree expansion and collapse.
• packages/cli/src/config/settingsSchema.ts
  • Updated the schema for general.defaultApprovalMode to include 'step' as a valid option.
  • Added schema definitions for ui.verbosityLevel and ui.verbosityOverrides.
  • Added schema definition for experimental.taskTree.
• packages/cli/src/services/BuiltinCommandLoader.ts
  • Imported and registered the new verbosityCommand.
• packages/cli/src/ui/AppContainer.tsx
  • Imported ToolStepDialog component.
  • Rendered ToolStepDialog within the AppContainer to enable interactive stepping.
• packages/cli/src/ui/commands/verbosityCommand.ts
  • Added a new file implementing the /verbosity slash command for session-only UI verbosity control.
• packages/cli/src/ui/components/ApprovalModeIndicator.tsx
  • Added a case to display 'step-through' text and warning color for ApprovalMode.STEP.
• packages/cli/src/ui/components/Composer.tsx
  • Added a case to display 'step' text for ApprovalMode.STEP in the composer.
• packages/cli/src/ui/components/HistoryItemDisplay.tsx
  • Imported TaskTreeDisplay component.
  • Removed secondaryText property from InfoMessage props.
  • Implemented conditional rendering to display either TaskTreeDisplay or ToolGroupMessage based on the experimental.taskTree setting.
• packages/cli/src/ui/components/ToolStepDialog.tsx
  • Added a new file implementing the ToolStepDialog component, which provides the interactive UI for tool stepping.
• packages/cli/src/ui/components/messages/SubagentProgressDisplay.tsx
  • Added hideToolCalls prop to control visibility of tool calls within subagent progress.
  • Modified rendering logic to respect the hideToolCalls prop.
• packages/cli/src/ui/components/messages/TaskNode.tsx
  • Added a new file implementing the TaskNode component for rendering individual nodes in the hierarchical task tree.
• packages/cli/src/ui/components/messages/TaskTreeDisplay.tsx
  • Added a new file implementing the TaskTreeDisplay component, responsible for rendering the full hierarchical task tree and handling its navigation.
• packages/cli/src/ui/components/messages/ToolMessage.tsx
  • Added hideSubagentTools prop and passed it to ToolResultDisplay.
• packages/cli/src/ui/components/messages/ToolResultDisplay.tsx
  • Added hideSubagentTools prop and passed it to SubagentProgressDisplay.
• packages/cli/src/ui/components/messages/ToolShared.tsx
  • Exported ToolStatusIndicatorProps and ToolInfoProps interfaces.
• packages/cli/src/ui/hooks/useApprovalModeIndicator.ts
  • Updated the logic for cycling through approval modes to include ApprovalMode.STEP.
• packages/cli/src/ui/hooks/useStepThrough.ts
  • Added a new file implementing the useStepThrough hook to manage interactive step-through requests and responses.
• packages/cli/src/ui/hooks/useTaskTree.ts
  • Added a new file implementing the useTaskTree hook, which transforms flat tool call data into a hierarchical tree structure.
• packages/cli/src/ui/hooks/useToolScheduler.ts
  • Imported ToolLiveOutput and SHELL_TOOL_NAME.
  • Modified adaptToolCalls to include liveOutput and apply a ring buffer for shell tool output.
• packages/core/src/config/config.ts
  • Imported Kind from ../tools/tools.js.
  • Defined UiSettings interface for verbosityLevel and verbosityOverrides.
  • Added ui property to ConfigParameters and the Config class.
  • Initialized ui settings in the Config constructor.
  • Implemented getResolvedVerbosity and getToolCategory methods for dynamic verbosity control.
• packages/core/src/confirmation-bus/types.ts
  • Added STEP_THROUGH_REQUEST and STEP_THROUGH_RESPONSE message bus types.
  • Defined interfaces for StepThroughRequest and StepThroughResponse messages.
• packages/core/src/policy/types.ts
  • Added STEP to the ApprovalMode enum.
• packages/core/src/prompts/promptProvider.ts
  • Added stepThroughEnabled to prompt options, activated when ApprovalMode.STEP is in use.
• packages/core/src/prompts/snippets.legacy.ts
  • Added stepThroughEnabled to SystemPromptOptions.
  • Implemented renderStepThroughMode function and integrated it into the system prompt.
  • Modified getCompressionPrompt to accept an optional _approvedPlanPath parameter.
• packages/core/src/prompts/snippets.ts
  • Added stepThroughEnabled to SystemPromptOptions.
  • Implemented renderStepThroughMode function and integrated it into the system prompt.
• packages/core/src/scheduler/scheduler.ts
  • Imported safeJsonStringify for handling tool arguments.
  • Imported ApprovalMode enum directly.
  • Imported StepThroughRequest and StepThroughResponse types.
  • Added cancelCurrentTurn method for immediate cancellation.
  • Modified _executeNextReadyCall to process STEP mode calls sequentially and handle user responses (run, skip, continue, cancel).
  • Implemented logic to pause execution and interact with the user via the message bus for STEP mode.
• packages/core/src/scheduler/state-manager.ts
  • Added endTime property to CompletedToolCall objects for success, error, and cancelled states.
• packages/core/src/scheduler/types.ts
  • Added retryCount and retryReason properties to ToolCallRequestInfo.
• packages/core/src/tools/tools.ts
  • Added SkippedToolResult interface to represent results of skipped tool calls.
• packages/core/src/utils/approvalModeUtils.ts
  • Added a descriptive string for ApprovalMode.STEP.
• packages/core/src/utils/fileUtils.test.ts
  • Expanded file type detection tests to include additional binary and media file extensions.
• packages/core/src/utils/ignorePatterns.test.ts
  • Updated ignore pattern tests to include new binary and media file types.
• packages/core/src/utils/ignorePatterns.ts
  • Expanded BINARY_FILE_PATTERNS and MEDIA_FILE_PATTERNS to include a wider range of file types.
• schemas/settings.schema.json
  • Updated the JSON schema for general.defaultApprovalMode to include 'step'.
  • Added JSON schema definitions for ui.verbosityLevel and ui.verbosityOverrides.
  • Added JSON schema definition for experimental.taskTree.

Activity

• The pull request includes a pre-merge checklist, indicating that documentation and tests have been updated, and validated on Windows.
• No specific comments or reviews from other users were provided in the context.

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 significant new features for monitoring and controlling agent execution: an interactive task tree for visualizing tool calls and a step-through approval mode. The implementation across the core scheduler and UI components appears well-structured. My main concern is the inclusion of temporary build error logs (errors-cli-8.txt and packages/a2a-server/errors8.txt) in the commit history, which should be removed.

[gemini-code-assist]

This file appears to be a log of build errors from development. Such temporary files should not be committed to the repository. Please remove it from the pull request.

[gemini-code-assist]

This file appears to be a log of build errors from development. Such temporary files should not be committed to the repository. Please remove it from the pull request.

[TravisHaa]

Hey @Khushi281300 , I appreciate your efforts, but your PR creates a lot of redundant work that feels like you just copied and pasted my project spec into an agent and hoped for the best. I'd also argue that the task tree visualization is a lot more complicated than just wrapping the existing ToolMessage cards in a paddingLeft box. I have open PRs (#21593, #21595) covering these same features that were submitted ~12 hours earlier — worth coordinating so we're not duplicating effort.

There's a lot of issues with your implementation, here are a few:

1. There's a circular reference in the tree nodes because you store parent?: TaskTreeNode<T>. Any serialization, deep clone, or React reconciliation that touches the tree can infinite-loop.
2. Your step-through implementation doesn't actually pause, it just forces non-step calls to run concurrently while step calls are "waiting". The whole point of STEP mode is sequential gating.
3. Your task tree is missing a lot of features.
4. you committed your error logs.

[psinha40898]

because #21484 was not assigned (b/c it hasn't been labeled "help wanted") it's technically OK for you to open this PR...but we need to ask ourselves if it was worth it.

the more times engineers have to "play referee", the less they're going to love being open source. let's regulate ourselves a bit here guys...let's have some respect and love for the repository...

@Khushi281300 unless you feel like there is a good reason for this PR to compete with the ones @TravisHaa opened, the most respectful thing you could do is just close this.

I know it can be hard to land changes right now because all of the help wanted issues are already taken. there are three paths to landing PRs as an external contributor...

1. check the repo every few hours for new "help wanted" issues. as soon as a new one pops up, if you assign yourself, you're pretty much locked in and good to go! the key here is accepting that you probably need a new issue.
2. give it a few weeks for the automated workflows to clear up issues and for the team to land on some additional ideas for the contribution process
3. identify an issue yourself and open it with a linked PR similar to what travis did...this only works if we regulate ourselves and show each other love and respect

I hope that my advice helps you land changes. its not a smooth and easy path but we can make it better for each other.