Add Approval Navigation Banner and Related Functionality by govindavashishtha · Pull Request #474 · truefoundry/trueforge

govindavashishtha · 2026-08-27T13:36:02Z

Summary

Adds a composer approval navigation banner for threads with one or more pending tool approvals, so users can find, cycle through, and re-focus approvals — including nested subagent tools — without losing context after scrolling.

New overridable ApprovalNavBanner slot + ApprovalNavContainer, wired above the composer when approvals are pending
Banner shows count (N tools need your input), (current/total), and prev/next chevrons (no wrap)
Clicking the banner scrolls back to the currently selected approval (expand ancestors → scroll → flash)
ApprovalFocusProvider registers approval DOM targets / subagent expand callbacks and handles focus + flash
Composer pause view updated so pending approvals keep the input paused while the banner is active
Changeset: @truefoundry/trueforge-ui minor

Screen.Recording.2026-08-27.at.7.11.08.PM.mov

Test plan

Single pending approval: banner shows singular copy; chevrons disabled; click banner scrolls/flashes that card
Multiple pending approvals: prev/next moves focus without wrapping; counter updates; allow/deny advances correctly
Nested subagent approval: focusing expands ancestor tool calls, then scrolls/flashes the nested approval
Scroll away from the focused approval, then click the banner (not chevrons) → returns to the same current item
After resolving all approvals, banner disappears and composer unpauses
Slot override still works for ApprovalNavBanner
pnpm --filter @truefoundry/trueforge-ui test passes

Note

Medium Risk
Changes composer pause ordering and thread-wide focus/scroll behavior for human-in-the-loop tool approvals, including nested sub-agent DOM timing with retry logic.

Overview
Adds an approval navigation banner above the composer when one or more tool approvals are pending, with an overridable ApprovalNavBanner slot and ApprovalNavContainer.

While approvals are open, useComposerPauseView returns { kind: 'approval' } (below MCP/custom/ask-user): the banner shows “N tools need your input”, a (current/total) counter, and prev/next chevrons that do not wrap; the message input stays disabled and visually flush with the banner. useApprovalNav drives selection from useTrueFoundryApprovals, auto-focuses the first item, and keeps the same list index as items are resolved.

ApprovalFocusProvider (on the thread) registers scroll targets on ToolCallCard via approvalId, expands nested create_sub_agent ancestors (findSubAgentAncestorsForApproval), smooth-scrolls, and applies a short flash highlight. Tool call rendering passes approvalId through sandbox/MCP/generic paths and registers sub-agent expand callbacks.

Theme adds approval-banner tokens and aui-approval-flash animation; public exports include ApprovalNavBanner, useApprovalNav, and useTrueFoundryApprovals.

^{Reviewed by Cursor Bugbot for commit e50e635. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-08-27T13:36:10Z

🦋 Changeset detected

Latest commit: e50e635

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@truefoundry/trueforge-ui	Minor
frontend	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…al-flow-for-multiple-approvals-composer-it

kumarsks619 · 2026-08-27T14:13:04Z

should add some padding to the highlighting box @govindavashishtha

…ability during flashing

…al-flow-for-multiple-approvals-composer-it

cursor

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit e50e635. Configure here.}

cursor · 2026-08-28T04:59:32Z

+ flashingApprovalId,
+ }),
+ [registerTarget, registerExpand, focus, flashingApprovalId],
+ );


Focus context churns on stream
Medium Severity
ApprovalFocusProvider reads thread.messages into the focus callback, so the context value is recreated on every message update. Every ToolCallCard subscribes via useOptionalApprovalFocus, so streaming tokens re-render all tool cards — including expanded Monaco/markdown bodies — even when no approval is pending.
Additional Locations (1)
packages/trueforge-ui/src/atoms/ToolCallCard.tsx#L60-L69
^{Reviewed by Cursor Bugbot for commit e50e635. Configure here.}

cursor · 2026-08-28T04:59:32Z

+ }
+ }
+ }, MOUNT_RETRY_MS);
+ },


Stale ancestors block nested focus
Medium Severity
focus snapshots subagent ancestors once from messages at call time, and useApprovalNav then records focusedIdRef so the same id is never focused again. If useTrueFoundryApprovals updates before the thread tree contains the nested tool, retries expand nothing, and a later message update does not re-focus.
Additional Locations (1)
packages/trueforge-ui/src/hooks/useApprovalNav.ts#L45-L54
^{Reviewed by Cursor Bugbot for commit e50e635. Configure here.}

kumarsks619 · 2026-08-27T20:08:49Z

+ aria-label={`${label}. Click to go to approval ${String(current)} of ${String(count)}.`}
+ onClick={onFocusCurrent}
+ className={cn(
+ // Figma light 6747:4232 / dark 6748:1977 — top border only; sides & bottom open into the composer.


can remove comment, not useful

kumarsks619 · 2026-08-27T20:09:08Z

+ onFocusCurrent,
+ className,
+}: ApprovalNavBannerProps) {
+ // Figma Agents node 6747:4232 — "N tools need your input"


kumarsks619 · 2026-08-27T20:10:10Z

+import { cn } from './lib/cn.js';
+
+export type ApprovalNavBannerProps = {
+ count: number;


Suggested change
count: number;
total: number;

kumarsks619 · 2026-08-27T20:58:13Z

+ // Pending-approval cards keep top/right padding always so flash doesn't jump the layout.
+ // Left stays unpadded so the step rail stays aligned with siblings.


kumarsks619 · 2026-08-27T21:00:23Z

 toolName?: string;
 argsText?: string;
+ /** Kept for call-site compat; flash/scroll target is `ToolCallCard`. */
+ approvalId?: string;


couldn't get it why we need this prop if not being used

kumarsks619 · 2026-08-28T07:08:07Z

+export function useRegisterApprovalTarget(approvalId: string | undefined, getElement: () => HTMLElement | null): void {
+ const api = useOptionalApprovalFocus();
+ const getElementRef = useRef(getElement);
+ getElementRef.current = getElement;


shouldn't be part of render cycle, should do it a useeffect

kumarsks619 · 2026-08-28T07:08:13Z

+export function useRegisterApprovalExpand(toolCallId: string, expand: () => void): void {
+ const api = useOptionalApprovalFocus();
+ const expandRef = useRef(expand);
+ expandRef.current = expand;


kumarsks619 · 2026-08-28T07:10:17Z

+}
+
+/** Registers a sub-agent expand callback. No-ops outside the provider (tests). */
+export function useRegisterApprovalExpand(toolCallId: string, expand: () => void): void {


i think this unused

kumarsks619 · 2026-08-28T07:11:59Z

+}
+
+/** Registers a DOM target for scroll/flash. No-ops outside the provider (tests). */
+export function useRegisterApprovalTarget(approvalId: string | undefined, getElement: () => HTMLElement | null): void {


want to understand how it is working, whats the flow here

Add Approval Navigation Banner and Related Functionality
c6c6d93

govindavashishtha requested review from kumarsks619, qaifi-tf, sajal-truefoundry, sayan-truefoundry and vinit-truefoundry as code owners August 27, 2026 13:36

Merge branch 'main' into chore/FRONTEN-2362/trueforge-subagent-approv…
b3b55ec
…al-flow-for-multiple-approvals-composer-it

cursorBot reviewed Aug 27, 2026
View reviewed changes

Comment threadpackages/trueforge-ui/src/containers/ToolCallContainer.tsx
Comment threadpackages/trueforge-ui/src/containers/approvalFocus.tsx
Comment threadpackages/trueforge-ui/src/hooks/useApprovalNav.ts
Comment thread.changeset/pre/approval-nav-banner.md

fixed PR comments
2c31a1b

govindavashishtha added 2 commits August 27, 2026 20:09

Update ToolCallCard styling for approval states to maintain layout st…
ea55f91
…ability during flashing

Merge branch 'main' into chore/FRONTEN-2362/trueforge-subagent-approv…
e50e635
…al-flow-for-multiple-approvals-composer-it

cursorBot reviewed Aug 28, 2026
View reviewed changes

kumarsks619 reviewed Aug 28, 2026
View reviewed changes

		// Pending-approval cards keep top/right padding always so flash doesn't jump the layout.
		// Left stays unpadded so the step rail stays aligned with siblings.

Uh oh!

Conversation

govindavashishtha commented Aug 27, 2026• edited by cursor BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

changeset-botBot commented Aug 27, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kumarsks619 commented Aug 27, 2026

Uh oh!

cursorBot left a comment

Choose a reason for hiding this comment

Uh oh!

cursorBotAug 28, 2026

Choose a reason for hiding this comment

Focus context churns on stream

Uh oh!

cursorBotAug 28, 2026

Choose a reason for hiding this comment

Stale ancestors block nested focus

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

govindavashishtha commented Aug 27, 2026•
edited by cursor Bot
Loading

changeset-botBot commented Aug 27, 2026•
edited
Loading