Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(agents): optionally hide a subagent's card when it finishes

Shogun40dfe37df9f3
diff --git a/CLAUDE.md b/CLAUDE.md
index 420fcd56d..6930e7584 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1672,6 +1672,12 @@ else, and its context links must keep classifying across restarts).
because three surfaces each invented their own timeout) — or a subagent whose end never arrives
pins its card, and its parent, forever. It marks the card **done** rather than deleting it, so a
late `finish()` is the no-op it already was and the next turn boundary takes it.
+ **A third removal path is opt-in:** `settings.autoHideFinishedSubagentCards` (default OFF, and
+ off reproduces the two paths above exactly) mirrors into the store as `autoHideFinished`, and
+ with it on a card is dropped the moment its subagent reports done, by `finish()` and by the
+ decay alike, with no turn boundary. Only a DONE card is ever dropped, so #547's rule (a new turn
+ keeps the cards of subagents still running) and Eco's `liveSubagents` are untouched. Renderer
+ only: Desktop and Server Edition identical, Mobile N/A.
(Subagents share the parent's process — no PTY.) Each card shows
duration/tokens/tool-uses and **expands** (click) to a **live transcript**:
`core/subagent-tail.ts` resolves the subagent's own transcript file
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index ca4761b7d..e19a4baed 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -7475,6 +7475,14 @@ export function Canvas() {
document.documentElement.style.setProperty('--accent', settings.accent)
}, [settings.accent])
+ // Mirror the auto-hide preference into the ephemeral-card store, which is deliberately kept
+ // free of the settings store.
+ useEffect(() => {
+ useAgentNodes
+ .getState()
+ .setAutoHideFinished(settings.autoHideFinishedSubagentCards === true)
+ }, [settings.autoHideFinishedSubagentCards])
+
/** ids to act on for a node menu: the whole selection if the node is part of it, else just it. */
const targetIds = useCallback((node: Node): string[] => {
diff --git a/src/renderer/canvas/canvas-wiring.test.tsx b/src/renderer/canvas/canvas-wiring.test.tsx
index dad80a0d5..39e30ff45 100644
--- a/src/renderer/canvas/canvas-wiring.test.tsx
+++ b/src/renderer/canvas/canvas-wiring.test.tsx
@@ -196,6 +196,18 @@ describe('breadcrumb wiring the CLAUDE.md bullet calls load-bearing', () => {
})
})
+describe('the auto-hide preference reaches the ephemeral-card store', () => {
+ // `autoHideFinishedSubagentCards` lives in settings and is acted on in `state/agentNodes.ts`,
+ // which is deliberately free of the settings store, so this effect is the ONLY thing joining
+ // them. Every test of the behaviour drives `setAutoHideFinished` directly, so deleting the
+ // effect leaves the setting inert with the whole suite and typecheck green: the toggle flips,
+ // persists, and does nothing.
+ it('mirrors the setting into setAutoHideFinished', () => {
+ expect(CANVAS_SRC).toContain('.setAutoHideFinished(settings.autoHideFinishedSubagentCards === true)')
+ expect(CANVAS_SRC).toContain('}, [settings.autoHideFinishedSubagentCards])')
+ })
+})
+
describe('deleteNodes also records persisted closed-session history', () => {
it('builds entries from the full pre-delete tree and the same "now" used for reopenHistory', () => {
expect(CANVAS_SRC).toContain('const deletedAt = Date.now()')
diff --git a/src/renderer/components/settings/sections/AgentsSection.tsx b/src/renderer/components/settings/sections/AgentsSection.tsx
index 2bf875e54..d6a2f4426 100644
--- a/src/renderer/components/settings/sections/AgentsSection.tsx
+++ b/src/renderer/components/settings/sections/AgentsSection.tsx
@@ -91,6 +91,21 @@ const ROWS = {
title: 'One-click approvals',
keywords: ['approve', 'deny', 'approval', 'permission', 'hook', 'phone', 'canvas', 'one click', 'claude']
},
+ autoHideFinishedSubagentCards: {
+ title: 'Hide finished subagent cards',
+ keywords: [
+ 'subagent',
+ 'card',
+ 'fan out',
+ 'hide',
+ 'remove',
+ 'finished',
+ 'done',
+ 'clutter',
+ 'canvas',
+ 'task'
+ ]
+ },
nodeIdentity: {
title: 'Verified node identity',
keywords: [
@@ -400,6 +415,19 @@ export function AgentsSection({ isActive }: { isActive: boolean }): React.JSX.El
}
/>
</SearchableRow>
+ <SearchableRow {...ROWS.autoHideFinishedSubagentCards}>
+ <FieldRow
+ label="Hide finished subagent cards"
+ description="Remove a subagent's card from the canvas as soon as that subagent finishes, instead of keeping it until the agent's next turn. Cards for subagents that are still running are never removed."
+ control={
+ <Switch
+ checked={settings.autoHideFinishedSubagentCards}
+ ariaLabel="Hide finished subagent cards"
+ onChange={(on) => update({ autoHideFinishedSubagentCards: on })}
+ />
+ }
+ />
+ </SearchableRow>
<SearchableRow {...ROWS.nodeIdentity}>
<FieldRow
label="Require verified node identity for canvas control"
diff --git a/src/renderer/state/agentNodes.ts b/src/renderer/state/agentNodes.ts
index 14b271950..0a1c786af 100644
--- a/src/renderer/state/agentNodes.ts
+++ b/src/renderer/state/agentNodes.ts
@@ -58,6 +58,19 @@ interface AgentNodesState {
* derived node. Cards select one at a time, by click, purely to show their resize frame.
*/
selectedId: string | null
+ /**
+ * `settings.autoHideFinishedSubagentCards`, mirrored here by Canvas so the store stays free of
+ * the settings store.
+ *
+ * On, a card is DROPPED at the moment its subagent reports done (by `finish()` and by
+ * `sweepStaleWorking`'s decay alike) rather than left `done` for the next turn boundary to
+ * take. Only a finished card is ever dropped, so #547's rule (a new turn must keep the cards of
+ * subagents that are still running) and Eco's `liveSubagents` are untouched.
+ *
+ * Off is the default and reproduces the previous behavior exactly.
+ */
+ autoHideFinished: boolean
+ setAutoHideFinished(on: boolean): void
select(id: string | null): void
setPosition(id: string, offset: { x: number; y: number }): void
setSize(id: string, size: { width: number; height: number }): void
@@ -197,8 +210,12 @@ export const useAgentNodes = create<AgentNodesState>((set) => ({
byId: {},
activityById: {},
selectedId: null,
+ autoHideFinished: false,
...loadLoopOverrides(),
+ setAutoHideFinished: (on) =>
+ set((s) => (s.autoHideFinished === on ? s : { autoHideFinished: on })),
+
select: (id) => set((s) => (s.selectedId === id ? s : { selectedId: id })),
setPosition: (id, offset) =>
@@ -240,6 +257,7 @@ export const useAgentNodes = create<AgentNodesState>((set) => ({
set((s) => {
const prev = s.byId[toolUseId]
if (!prev || prev.state === 'done') return s
+ if (s.autoHideFinished) return dropCards(s, [toolUseId])
// Async subagents end via a <task-notification> that carries no timing stats — fall
// back to the card's own elapsed time so the duration doesn't vanish on completion.
const durationMs = result.durationMs ?? Date.now() - prev.startedAt
@@ -264,6 +282,7 @@ export const useAgentNodes = create<AgentNodesState>((set) => ({
(id) => s.byId[id].state === 'working' && now - s.byId[id].startedAt > staleMs
)
if (!stale.length) return s
+ if (s.autoHideFinished) return dropCards(s, stale)
const byId = { ...s.byId }
for (const id of stale) {
const prev = byId[id]
diff --git a/src/renderer/state/agentNodes.turn-boundary.test.ts b/src/renderer/state/agentNodes.turn-boundary.test.ts
index 8cd002322..a2a398c70 100644
--- a/src/renderer/state/agentNodes.turn-boundary.test.ts
+++ b/src/renderer/state/agentNodes.turn-boundary.test.ts
@@ -23,7 +23,8 @@ const reset = (): void => {
positions: {},
sizes: {},
expanded: {},
- selectedId: null
+ selectedId: null,
+ autoHideFinished: false
})
}
@@ -146,6 +147,87 @@ describe('sweepStaleWorking — the decay a kept card owes', () => {
})
})
+describe('autoHideFinished: dropping a card the moment its subagent finishes', () => {
+ beforeEach(reset)
+
+ it('keeps the finished card until the turn boundary while the setting is off', () => {
+ const s = useAgentNodes.getState()
+ s.start('tu1', { parentNodeId: 'n1' })
+ s.finish('tu1', { tokens: 7 })
+ expect(useAgentNodes.getState().byId['tu1']).toMatchObject({ state: 'done', tokens: 7 })
+ })
+
+ it('drops the card on finish while the setting is on', () => {
+ const s = useAgentNodes.getState()
+ s.setAutoHideFinished(true)
+ s.start('tu1', { parentNodeId: 'n1' })
+ useAgentNodes.getState().finish('tu1', { tokens: 7 })
+ expect(useAgentNodes.getState().byId['tu1']).toBeUndefined()
+ })
+
+ it('takes the dropped card’s overrides, selection and activity with it', () => {
+ const s = useAgentNodes.getState()
+ s.setAutoHideFinished(true)
+ s.start('tu1', { parentNodeId: 'n1' })
+ s.setPosition('tu1', { x: 1, y: 2 })
+ s.setSize('tu1', { width: 400, height: 300 })
+ s.toggleExpanded('tu1')
+ s.appendActivity('tu1', 'ran')
+ s.select('tu1')
+ useAgentNodes.getState().finish('tu1', {})
+ const st = useAgentNodes.getState()
+ expect(st.positions['tu1']).toBeUndefined()
+ expect(st.sizes['tu1']).toBeUndefined()
+ expect(st.expanded['tu1']).toBeUndefined()
+ expect(st.activityById['tu1']).toBeUndefined()
+ expect(st.selectedId).toBeNull()
+ })
+
+ it('leaves a sibling that is still working, so #547 is unaffected', () => {
+ const s = useAgentNodes.getState()
+ s.setAutoHideFinished(true)
+ s.start('tu-done', { parentNodeId: 'n1' })
+ s.start('tu-running', { parentNodeId: 'n1' })
+ useAgentNodes.getState().finish('tu-done', {})
+ expect(Object.keys(useAgentNodes.getState().byId)).toEqual(['tu-running'])
+ })
+
+ it('marks the stale sweep done while the setting is off', () => {
+ const s = useAgentNodes.getState()
+ s.start('tu1', { parentNodeId: 'n1' })
+ const startedAt = useAgentNodes.getState().byId['tu1'].startedAt
+ s.sweepStaleWorking(startedAt + WORKING_STALE_MS + 1)
+ expect(useAgentNodes.getState().byId['tu1'].state).toBe('done')
+ })
+
+ it('drops the stale sweep’s cards while the setting is on', () => {
+ const s = useAgentNodes.getState()
+ s.setAutoHideFinished(true)
+ s.start('tu-stale', { parentNodeId: 'n1' })
+ s.start('tu-young', { parentNodeId: 'n1' })
+ const now = Date.now()
+ useAgentNodes.setState((st) => ({
+ byId: {
+ ...st.byId,
+ 'tu-stale': { ...st.byId['tu-stale'], startedAt: now - WORKING_STALE_MS - 1 }
+ }
+ }))
+ useAgentNodes.getState().sweepStaleWorking(now)
+ const { byId } = useAgentNodes.getState()
+ expect(byId['tu-stale']).toBeUndefined()
+ expect(byId['tu-young']).toBeDefined()
+ })
+
+ it('a late finish on a dropped card is a no-op', () => {
+ const s = useAgentNodes.getState()
+ s.setAutoHideFinished(true)
+ s.start('tu1', { parentNodeId: 'n1' })
+ useAgentNodes.getState().finish('tu1', {})
+ useAgentNodes.getState().finish('tu1', { tokens: 9 })
+ expect(useAgentNodes.getState().byId['tu1']).toBeUndefined()
+ })
+})
+
describe('Eco still sees the live subagent after a new turn (issue #547)', () => {
beforeEach(reset)
diff --git a/src/shared/default-settings.test.ts b/src/shared/default-settings.test.ts
index 451ba2ef2..e57058475 100644
--- a/src/shared/default-settings.test.ts
+++ b/src/shared/default-settings.test.ts
@@ -25,6 +25,12 @@ describe('DEFAULT_SETTINGS', () => {
expect(DEFAULT_SETTINGS.worktreePathTemplate).toBe(DEFAULT_WORKTREE_PATH_TEMPLATE)
})
+ it('keeps finished subagent cards on the canvas by default', () => {
+ // Default OFF is the whole compatibility promise of the setting: with it off, a finished card
+ // still waits for the turn boundary, exactly as before the feature.
+ expect(DEFAULT_SETTINGS.autoHideFinishedSubagentCards).toBe(false)
+ })
+
it('keeps common identifier and path characters inside terminal word selections', () => {
expect(DEFAULT_SETTINGS.terminalWordSeparator).not.toMatch(/[-_/.]/)
})
diff --git a/src/shared/types.ts b/src/shared/types.ts
index a84a89a55..31dde5591 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1592,6 +1592,11 @@ export interface Settings {
* hook holds briefly for a phone/canvas Approve/Deny before falling through to the normal
* interactive prompt. Off ⇒ the env var is absent ⇒ exact legacy behavior. Claude-only. */
hookReplyApprovals: boolean
+ /** Remove a subagent's ephemeral canvas card the moment that subagent finishes, instead of
+ * keeping it until the parent agent's next turn clears it. Default off ⇒ exact legacy
+ * behavior. A card whose subagent is still running is never removed by this. Settings →
+ * Agents. */
+ autoHideFinishedSubagentCards: boolean
/** Hold an idle-sleep power assertion while a LOCAL agent node is working, so long runs
* survive an unattended laptop. Released when the last one stops (or goes stale). Cannot
* hold through a closed lid. Asked in the setup tour; Settings → Behavior. */
@@ -1743,6 +1748,7 @@ export const DEFAULT_SETTINGS: Settings = {
// Deterministic hook-reply approvals default ON (existing users pick it up on hydrate). Only
// affects Claude terminal sessions; off reproduces the pre-feature launch bit-for-bit.
hookReplyApprovals: true,
+ autoHideFinishedSubagentCards: false,
// Keep-awake-while-agents-work default ON (existing users pick it up on hydrate — deliberate,
// same note style as hookReplyApprovals). Held only while a local agent is actually working.
keepAwakeWhileAgentsWork: true,