feat(agents): add proactive progress check-ins for long-running subagents #1323

Before submitting

• I searched open and closed issues and did not find a request for this feature.
• I reviewed this request and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem or opportunity

Gentle Agents exposes useful technical activity through the Agents card and /gentle:agents: task state, elapsed time, model, token usage, retained text/thinking, and tool activity. However, a user can still spend a long time without receiving a meaningful explanation of what a subagent is doing or why the work remains necessary.

This creates an avoidable uncertainty gap during long-running tasks. For example, a subagent may run for 20–30 minutes while the user cannot distinguish among these materially different situations:

• it is performing a necessary long-running check;
• it found an unexpected constraint and is investigating it;
• it expanded the scope incorrectly;
• it is repeating work;
• it is stuck inside a tool call.

Raw elapsed time and tool activity help with diagnosis, but they do not provide the semantic explanation needed to decide whether to wait, redirect, or cancel.

The gap is especially visible for a subagent launched in blocking task mode. The parent model is waiting inside subagent_run, so user steering sent to the parent cannot invoke subagent_status or subagent_send_message until the child yields or finishes. The host TUI remains alive and can inspect or stop the task, but there is no proactive progress explanation.

Comparable agent-harness UX can reduce this uncertainty by reminding a long-running agent that the user has not received an update recently and asking it to briefly explain what it is doing before continuing.

IMAGE: In the attached image, you can see a request to replace an old, unversioned repository with a new, versioned one by cloning the project via Git; the sub-agent then proceeded to do extra work—which might well be correct—but I won't know what happened or why until it's finished.

Proposed outcome

Add bounded, host-owned progress check-ins for long-running Gentle subagents.

When an active subagent has gone beyond a configurable period without a useful user-visible progress update, Gentle Agents should schedule one reminder at the next safe model boundary. The reminder should not interrupt an active tool call.

Suggested reminder contract:

The user has not received a useful progress update recently.
Briefly report:
- what you are doing;
- why it is necessary;
- material evidence or unexpected discoveries;
- the next checkpoint.
Do not invent an ETA. Then continue.

The resulting update should be visible in the Agents card/thread or as a dedicated progress notice, without requiring the parent model to be available.

Example:

Progress · gentle-ai-explore · 8m

Current:
Tracing configuration precedence across global, project, and
repository-pinned profiles.

Why:
Two sources disagree. Returning now could recommend editing a
generated file instead of the authoritative source.

Found:
Repository profile pins override the global model profile.

Next:
Verify launch-time reconciliation, then return the mapping.

Behavioral requirements

• The host owns scheduling and rate limiting; this must not depend solely on the child remembering to volunteer an update.
• Deliver reminders only at a safe boundary before the child's next model call; never interrupt an active tool invocation.
• A useful progress update resets the quiet interval.
• Do not emit empty heartbeat messages such as “still working.”
• Do not fabricate percentages, completion claims, or ETAs.
• Include only bounded, privacy-safe progress information. Never expose prompts, credentials, environment values, private paths, raw tool arguments, or sensitive output.
• Deduplicate and rate-limit reminders so long tasks do not generate transcript spam or repeated model interruptions.
• Keep progress check-ins optional, with an explicit enable/disable choice independent of configuring the quiet threshold.
• When disabled, do not schedule check-in reminders or make model calls solely to generate check-ins; preserve existing Agents telemetry and manual inspection.
• Work for background tasks and for blocking task-mode children without requiring a free parent-model turn.
• Preserve /gentle:agents as the detailed inspection surface; progress check-ins complement rather than replace the existing thread and telemetry.
• Treat progress communication as observational only. It must not grant authority, approve scope expansion, or imply that the task is healthy or complete.

Suggested initial scope

A first reviewable slice could provide:

1. one configurable quiet threshold;
2. one host-scheduled reminder per quiet interval;
3. one bounded progress message type rendered in the existing Agents thread/card;
4. reset/deduplication behavior;
5. focused tests for tool-call boundaries, task/background modes, privacy, rate limiting, cancellation, and shutdown.

A direct Message/Steer action in the Agents overlay would be useful but can remain a separate feature. This request is specifically about proactive progress communication and reducing user uncertainty.

Alternatives considered

• Use /gentle:agents manually: This exposes authoritative technical detail and remains the best current workaround, but it requires repeated active inspection and may still lack a concise explanation of why the work is necessary.
• Always use background mode: This keeps the parent model responsive and enables status/steering tools, but it does not proactively explain the child's reasoning or discoveries. It also does not help existing blocking task-mode runs.
• Add only a subagent skill or prompt rule: A progress-reporting skill could standardize the message format, but it depends on model compliance and can be lost or deprioritized during long tool chains. In task mode, an ordinary child notification may still sit behind the blocked parent. A skill could complement the feature but should not own timing or delivery guarantees.
• Use child queries as progress messages: A task-mode query can yield the blocking parent call, but it pauses the child awaiting a correlated response and is designed for decisions, not periodic liveness reporting.
• Infer health from elapsed time or tool activity: Time and activity are useful telemetry but cannot establish whether the approach is necessary, correct, or still in scope. The child should explain semantic progress; the host should not invent it.
• Cancel and relaunch: This restores control but may discard valid expensive work and does not solve the underlying observability gap.

Additional context

This request is adjacent to, but not a duplicate of:

• #430 — agent/subagent status bar: read-only authoritative activity/status UI. It explicitly excludes timer-based inference and task controls; it does not request explanatory progress check-ins.
• #39 — harness persistence: per-call harness re-anchoring and a slim rules layer for named/SDD agents. It may provide a useful prompt-delivery mechanism, but it does not define quiet-time detection or user-visible progress communication.
• #922 — Todo staleness under long tool-chain turns: evidence that turn-level reminders can arrive late or lose the attention competition during long tool chains. It concerns Todo maintenance rather than subagent progress communication.

The requested feature belongs in Gentle Agents / Gentle Shell rather than the native Gentle AI review backend because it concerns child execution, host scheduling, and Pi UI communication.

Observed environment during investigation:

gentle-pi: 3.3.0
Pi: 0.86.1

Current source already has useful building blocks: the managed task store, elapsed/activity tracking, child RPC steering, retained task threads, subagent_parent_message, and the Agents renderer. The missing behavior is a bounded host-owned policy connecting prolonged lack of user-visible explanation to a safe child progress request and visible result.