fix(agents): preserve prompt lifecycle for idle child delivery

[Alan-TheGentleman]

Linked issue

Closes #1528

PR type

• Bug fix

Summary

• Store structured child output durably and wake idle parents through the normal prompt lifecycle, preserving before_agent_start and prompt capture.
• Preserve active-run steering; defer delivery during out-of-run compaction; bound wake suppression after rejected or handled prompts.
• Isolate five parent permission tests from inherited child environment without changing production child safety.

Changes

File	Change
extensions/gentle-agents.ts	Idle/run/hold delivery routing, coalesced wakes, lifecycle cleanup
tests/gentle-agents.test.ts	Regression coverage for idle, active, compaction, rejected wake and stale context
tests/gentle-ai.test.ts	Explicit parent processEnv in five permission lifecycle tests
odd/tasks/idle-subagent-prompt-capture.md	Scope, work-unit evidence and review outcome

Test plan

• npm test: 4530 pass, 34 skipped, 0 fail; all three stages passed.
• npm run typecheck: 187 recorded baseline diagnostics, no regressions.
• Focused agents tests: 172/172 pass.
• Permission tests with GENTLE_PI_AGENTS_CHILD=1: 90/90 pass.
• Child-safety tests: 4/4 pass.
• Independent verification completed.
• Scoped native RDD review approved and exact acknowledgement completed (review-75f8046642f4a6f8); four non-blocking informational findings.
• Live Claude bridge reproduction (not performed).
• Required remote CI (pending).

Size exception

Explicitly authorized by the maintainer. Keep this coherent delivery-state fix and its regression tests together; do not remove coverage or split artificially. Source/test changes are 523 authored diff lines. Inherited float-chrome changes are excluded from this PR base.

Notes

Source and tests have not changed after native review; the final commit only records approval in the passive task document. No shell scripts or skills changed, so shellcheck and skill-loading checks are not applicable. A slow pre-run race and missing-compaction-event delay remain documented limitations.

Summary by CodeRabbit

• New Features
  • Child results and queries are now delivered to idle parent sessions and can wake them to review the updates.
  • Updates are grouped to avoid repeated wake-ups, with retries limited to a short window.
  • When a parent is busy or temporarily unavailable, queued updates are held for a later safe delivery point rather than triggering an interrupt.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 409c73ea-0c06-42b9-a6d4-1d2893841e82

📥 Commits

Reviewing files that changed from the base of the PR and between a287bdb and 3fb2c28.

📒 Files selected for processing (4)

• extensions/gentle-agents.ts
• odd/tasks/idle-subagent-prompt-capture.md
• tests/gentle-agents.test.ts
• tests/gentle-ai.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Parent delivery now routes according to the parent’s run state. Idle parents receive stored messages and a coalesced wake; active parents receive steering messages. Lifecycle hooks manage deferred flushes, bounded wake retries, and session-state resets.

Changes

Parent delivery lifecycle

Layer / File(s)	Summary
Route delivery and wake idle parents extensions/gentle-agents.ts	Delivery checks the parent context and state. Active runs receive steering messages; idle parents receive stored content followed by a coalesced system wake.
Flush at lifecycle boundaries extensions/gentle-agents.ts	Run settlement and compaction schedule or trigger flushes. Session start and shutdown reset delivery state and pending work.
Test delivery and lifecycle behavior tests/gentle-agents.test.ts, tests/gentle-ai.test.ts, odd/tasks/idle-subagent-prompt-capture.md	Tests cover delivery routes, wake timing, lifecycle boundaries, and stale contexts. Permission lifecycle tests set GENTLE_PI_AGENTS_CHILD through processEnv. The task record documents implementation and test work.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant ChildCompletion
  participant gentle-agents
  participant pi.sendMessage
  participant pi.sendUserMessage
  ChildCompletion->>gentle-agents: deliver child content
  gentle-agents->>pi.sendMessage: store content without triggering a turn when parent is idle
  gentle-agents->>pi.sendUserMessage: send a coalesced system wake when parent is idle
  gentle-agents->>pi.sendMessage: steer content when parent has an active run

Loading

Suggested reviewers: decode2

Merge Risk: ⚪ Minimal · up to 3fb2c

Idle parents now receive stored child results along with a single wake that goes through the normal prompt lifecycle. Active runs still use steering. The open questions about compaction timing and session-reset races were checked and did not reveal defects. Two items remain the author's to resolve before release: remote CI is still pending, and the live bridge reproduction was not performed.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3fb2c

The change preserves session ownership and separates child output from automated wake instructions. No introduced permission bypass or cross-session exposure was established. Remaining uncertainty concerns live integration behavior and recovery after failed delivery.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected delivery path exposes child-controlled content to its owning parent conversation, as it did before this PR. The scoped change alters when that parent continues; it does not establish new cross-session access or additional child tool authority. Effects beyond the host APIs remain outside verified coverage.

Trust Boundaries and Controls

• observed — Completion and message sends check parent-session identity at the final forwarding boundary. Notification and query ingress reject mismatched or finished tasks, and queue selection additionally requires a live owned task. Missing or stale parent context prevents forwarding.
• observed — The five permission-test changes explicitly select parent-process environment behavior. They do not change production child safety or permission enforcement in the scoped base-to-head diff.

Resilience and Maintainability Implications

• observed — Session start and shutdown discard pending queues and reset parent-delivery state. Reset cancels grace and deferred-boundary timers and clears owed wakes, while dispatch rechecks the live route. Completion deduplication and query consumption or expiry provide existing at-most-once lifecycle controls.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 3 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving prompt lifecycle behavior when delivering results from child agents to idle parents.
Linked Issues check	✅ Passed	Issue #1528 requires idle background-subagent completion delivery to use the normal prompt lifecycle so the appended gentle harness remains available and the result is not lost. The PR stores idle chi…
Out of Scope Changes check	✅ Passed	The changes remain connected to issue #1528. Active-run steering preserves existing delivery behavior. Compaction deferral, wake coalescing, retry bounds, session reset handling, and permission-test e…

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}