fix(agents): skip parent-only startup work in delegated children

[matraket]

Summary

• In isolated standalone Gentle Shell, delegated children run without the gentle-pi package (bug(agents): standalone subagents run without the gentle-pi package, silently losing guardrails, parent messaging, change capture and package tools #1690). Before forwarding it to them (feat(agents): forward the gentle-pi package to delegated children #1772), the package must not repeat in every child the startup work that belongs to the parent.
• When GENTLE_PI_AGENTS_CHILD=1, a child now skips: package asset install, legacy model migration and saved model config, repository preparation and review-status negotiation, review-permission revoke/refresh (extensions/gentle-ai.ts, moved into startParentSession); repository preparation on tool_result; the skill registry startup (.atl/ writes and an fs watcher); history capture; the upstream pi-pretty fallback (FFF indexing); and the startup banner.
• Session-local state still resets in children, and so does the dev-binary notice (upstream test tests/gentle-ai-dev-binary-surfacing.test.ts).
• Note: in Pi rpc mode ctx.hasUI is true, so hasUI is not a child signal; the guards use GENTLE_PI_AGENTS_CHILD.

This is PR 1 of 4. On its own it hardens regular gentle-pi children, which already load the package through settings.json, and changes nothing for isolated children yet.

Issue

Refs #1690

PR type

• Bug fix (type:bug)

Changes

Commit	Change
22004611	ODD task file: plan and the audit of every package hook that would newly run in a child.
6ae5b9c3	Child guards in gentle-ai.ts, skill-registry.ts, history/index.ts, pi-pretty.ts, startup-banner.ts, with child and parent-control tests.
c3f3c158	Parent-only startup work moved into startParentSession, so code after it still runs in children; tests assert the child resets.
e8aa21d4	Awaited handlers in the test; a child test for the YOLO and review-sidebar resets.
2efe8919	Keeps the dev-binary notice in children.

Test plan

All four branches were verified on top of main (653dad90) with env -u GENTLE_PI_AGENTS_CHILD (delegated shells export it).

• Focused suites: 178 pass, 0 fail. Full suite (node scripts/run-test-suite.mjs): 0 fail.
• node scripts/check-types.mjs, build-runtime-modules --check, verify-package-files: pass.
• Each guard was test-first (RED on the old code, with a parent control that still does the work).
• Native review (RDD): every commit approved, no corrections.

Heads-up: tests/history-session-scan-extract.test.ts fails now and then on mtime resolution under load (#1514). It is unrelated to this chain and passes alone.

Known follow-ups (non-blocking, from review)

• The child dev-binary branch is covered by the upstream test; the invalid-override toast and a failing describe in a child have no dedicated test.
• tests/gentle-ai-dev-binary-surfacing.test.ts (upstream) sets GENTLE_PI_AGENTS_CHILD without restoring it.

Chain Context

Field	Value
Chain	Standalone subagents load the gentle-pi package (#1690)
Tracker PR	Not needed
Position	1 of 4
Base	main (each PR is opened against main; until its predecessors merge, its diff also shows their commits, and I rebase it as they land)
Depends on	None
Follow-up	#1771
Review budget	540 changed lines (+523/-17), of which 119 are the ODD task file and about 360 are tests. Over 400 because each guard ships with its test.

main
 └─ #1770 child guards   📍 this PR
   └─ #1771 launcher injection signal
     └─ #1772 package forwarding + missing-tools warning
       └─ #1773 tests + docs

Review only the commits listed under Changes; earlier commits belong to the PRs below it in the chain.

Summary by CodeRabbit

• Bug Fixes
  • Delegated child sessions now avoid parent-owned startup setup, repository preparation, history capture, registry changes, startup banners, and formatting tools.
  • Child sessions retain their local session behavior, while parent sessions continue to handle shared setup and repository changes.
• Documentation
  • Added guidance and planned tasks for running standalone child sessions.

[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: 5d9a0468-0a86-492d-a1bc-f8ef87c4591c

📥 Commits

Reviewing files that changed from the base of the PR and between 653dad9 and 2efe891.

📒 Files selected for processing (11)

• extensions/gentle-ai.ts
• extensions/history/index.ts
• extensions/pi-pretty.ts
• extensions/skill-registry.ts
• extensions/startup-banner.ts
• odd/tasks/fix-1690-standalone-child-package.md
• tests/gentle-ai-child-guards.test.ts
• tests/history-child-guard.test.ts
• tests/pi-pretty.test.ts
• tests/skill-registry.test.ts
• tests/startup-banner.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

When GENTLE_PI_AGENTS_CHILD is "1", several extensions skip parent-owned startup actions. Child sessions also skip prompt-history capture and direct-write repository preparation. Tests cover child and parent paths.

Changes

Delegated child session guards

Layer / File(s)	Summary
Parent-owned startup and write boundaries extensions/gentle-ai.ts, tests/gentle-ai-child-guards.test.ts, odd/tasks/fix-1690-standalone-child-package.md	Child sessions skip selected parent-owned startup work and direct-write repository preparation. Tests cover child and parent startup, session restarts, write results, and confirmation handling. The ODD records task scope, audit findings, planned work, and current status.
Other extension startup guards extensions/history/index.ts, extensions/pi-pretty.ts, extensions/skill-registry.ts, extensions/startup-banner.ts, tests/history-child-guard.test.ts, tests/pi-pretty.test.ts, tests/skill-registry.test.ts, tests/startup-banner.test.ts	Child sessions skip history capture, pi-pretty loading, skill-registry startup, and startup-banner setup. Tests verify these guards and clear the child flag when exercising parent paths.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to 2efe8

The child startup guards and parent behavior have targeted test coverage. No actionable issue is established that should block merging after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 2efe8

The change reduces repeated shared-file and history-store work in delegated children while preserving local bookkeeping and command safeguards. No introduced security issue was established, but complete write isolation and parent-before-child preparation were not demonstrated.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The visible change affects delegated processes using shared project state, package assets, model settings, and history storage. Removing these child-owned effects reduces opportunities for competing initialization and unintended delegation-brief persistence; it does not establish confinement of arbitrary tool writes.

Trust Boundaries and Controls

• observed — Tool inputs still pass through sensitive-path checks, bounded-writer dispatch validation, recognized destructive-command blocking for children, and command confirmation. These controls predate this PR. The added confirmation regression case asserts that declining a confirmation-class command blocks execution.

Resilience and Maintainability Implications

• observed — Shutdown disables mutation recording, advances the lifecycle epoch, removes preparation bindings, and clears the active manager. Child startup retains local resets before skipping parent work. Regression assertions reject post-shutdown and stale-manager mutation or sidebar activity and accept the replacement manager. Mutation receipts also deduplicate repeated evidence identities.

Hardening Proposals

• proposed — During the planned package-forwarding rollout, validate parent preparation and child write authority together under interrupted startup and concurrent child launches. Treat this as additional assurance, not an observed vulnerability in these guards.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: delegated child sessions skip parent-only startup work.

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

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

---

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.}

[carlosmoradev]

Approving. Clean, well-structured foundation for the #1690 chain.

Key strengths observed:

1. Clear isolation boundary: Extracting parent-only work into startParentSession ensures children skip expensive shared-state operations (asset installation, legacy migration, native review status negotiation, repository preparation) without dropping local lifecycle resets.
2. Resource protection: Suppressing history capture, skill registry watchers, and upstream pretty indexing in children prevents file lock contention and background resource leaks in the shared working directory.
3. Paired test controls: Every child guard in tests/gentle-ai-child-guards.test.ts and companion suites includes a matching parent assertion, verifying that the guards do not pass vacuously.

Ready for merge as PR 1 of 4.

[barbatdev]

Clean foundation for the stack. The child/parent split does exactly what the title promises: delegated children keep their session-local resets and the dev-binary toast, while asset install, model override migration, review negotiation, repository preparation, prompt-history capture, pi-pretty indexing, the skill-registry watcher and the startup banner all stay parent-owned. The new child-guard tests cover the asymmetry in both directions (the child skips, the parent still does), including reminder/YOLO/sidebar re-arming for the child's own session. Focused suites pass (57/57 across the five touched files) and typecheck holds the 186-diagnostic baseline. One registration for #1771: the guard reads permissionEnvironment in gentle-ai.ts but process.env elsewhere; intentional per extension, but worth keeping consistent when the forwarding lands.