fix(changes): install session change capture in isolated child agents (#1688)

[carlosmoradev]

Fixes #1688

Problem

Successful native write and edit operations performed by isolated workers do not appear in the parent /gentle:changes view. Parent-authored changes appear normally, but delegated source changes are missing from the view even though the files were actually modified (#1688).

Root cause: The child launch path explicitly passes extensions via childContextExtensionPaths() (child-context.ts and child-safety.ts), but does not install the change capture hook. Change capture is registered only by gentle-shell.ts in the parent, which isolated children do not load. Although the parent runner already supports relaying child evidence, no gentleSessionChange details were emitted by child tool results without that capture hook.

Change

• Create extensions/child-capture.ts: installs installSessionChangeCapture(pi, env) when GENTLE_PI_AGENTS_CHILD === "1", remaining completely inert in the parent to avoid duplicate handlers.
• Add ./child-capture.ts to childContextExtensionPaths() in extensions/gentle-agents.ts, so isolated children automatically receive the capture hook at spawn.
• Add unit tests in tests/child-capture.test.ts verifying that child-capture is inert in the parent and registers lifecycle and tool hooks in children.
• Update tests/gentle-agents.test.ts asserting that childContextExtensionPaths() includes child-capture.ts and passes it to spawned children.

Verification

• Strict TDD RED: tests/gentle-agents.test.ts failed against base main with missing child-capture.ts in childContextExtensionPaths().
• Strict TDD GREEN: 190/190 tests passed in tests/gentle-agents.test.ts.
• Child capture suite: 2/2 tests passed in tests/child-capture.test.ts.
• Session change capture suite: 6/6 tests passed in tests/session-change-capture.test.ts.
• Package manifest suite: 56/56 tests passed in tests/package-manifest.test.ts.
• Typecheck: pnpm run typecheck clean (186 recorded baseline diagnostics, 0 regressions, 12 improved).
• Package integrity: node scripts/verify-package-files.mjs clean (155 files, 69 exact byte-pinned artifacts verified).

Summary by CodeRabbit

• New Features
  • Child agents can capture their session changes for review in the parent’s changes view.
  • Child change capture is enabled only in child-agent sessions.
  • Child-agent setup now includes the change-capture capability alongside context and safety features.

[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: 154b0e7d-c917-464a-9199-4a81ed4e40f9

📥 Commits

Reviewing files that changed from the base of the PR and between cf3012f and 4bcf288.

📒 Files selected for processing (5)

• extensions/child-capture.ts
• extensions/gentle-agents.ts
• odd/tasks/fix-1688-child-agents-change-capture.md
• tests/child-capture.test.ts
• tests/gentle-agents.test.ts

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

---

📝 Walkthrough

Walkthrough

The child extension installs session-change capture only when GENTLE_PI_AGENTS_CHILD is "1". Child extension selection now includes the capture extension, with tests for registration and path selection.

Changes

Child-agent change capture

Layer / File(s)	Summary
Child-only capture registration extensions/child-capture.ts, tests/child-capture.test.ts, odd/tasks/fix-1688-child-agents-change-capture.md	The extension registers capture only when the child flag is "1". Tests check hook registration in child and parent modes. The task document records the objective, checklist, and reported verification results.
Child extension selection extensions/gentle-agents.ts, tests/gentle-agents.test.ts	The selected child extension paths now include child-capture.ts. Tests check the added path when the extension exists and the existing empty-arguments case when it is missing.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to 4bcf2

Child-agent change capture is wired into the launch path, and the child marker reaches the extension. No actionable merge-blocking risk remains.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 4bcf2

Child workers now send file snapshots into the parent’s change history. Existing ownership, session, and path checks constrain that flow, and no new authorization bypass was established. The remaining uncertainty concerns trust in child-supplied snapshot contents and behavior during interrupted or concurrent execution.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected new exposure is file-snapshot data entering an authorized parent session’s change history, including granted foreign worktrees. The traced consumer records diff state; this evidence does not establish an undo or filesystem-write authority expansion.

Trust Boundaries and Controls

• observed — Child-controlled tool paths and result details cross into parent bookkeeping only after successful-result and identity checks. The parent compares the resolved tool path with the evidence path, namespaces evidence IDs by task, and validates bounded snapshot structures and relative paths that exclude traversal and .git components.
• inferred — Snapshot-content integrity still depends on the delegated execution and capture hook. Capture checks write contents or edit patches and downgrades mismatches to unavailable snapshots, but the inspected parent relay validates structure and attribution rather than independently authenticating snapshot contents.

Resilience and Maintainability Implications

• inferred — Capture is observational, not a transactional mutation ledger. A process interruption before successful evidence delivery can leave a real edit absent from the change view. Existing cleanup and continuity checks limit stale attribution, but do not guarantee complete reconstruction after interruption.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 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: installing session change capture in isolated child agents.
Linked Issues check	✅ Passed	Issue [#1688]: child-capture.ts installs session change capture only when GENTLE_PI_AGENTS_CHILD === "1". childContextExtensionPaths() includes it for isolated children. The existing capture hoo…
Out of Scope Changes check	✅ Passed	All reported changes support issue [#1688]. The task document and tests cover the child capture fix, its parent-only safeguards, and its child launch wiring. No unrelated changes are identified.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 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.}

[matraket]

Hi @carlosmoradev, thanks for picking up #1688! Heads-up so we don't step on each other: #1690 covers the same root cause, and @barbatdev already chose a direction there (forward the parent's package to children instead of growing the curated childContextExtensionPaths() list, since that list doesn't scale).

I have that fully implemented and reviewed locally as a stack of four PRs, and I'm only waiting for status:approved on #1690 before opening them. With the package forwarded, children load gentle-shell.ts, which already calls installSessionChangeCapture in child sessions, so #1688 is fixed without a new entry.

If both land as they are, children would install the capture hooks twice: once from gentle-shell.ts and once from child-capture.ts, which would also be loaded as a package entrypoint. installSessionChangeCapture has no idempotency guard, so I'd expect duplicated handlers. I haven't measured the exact effect. The two changes would also conflict in gentle-agents.ts.

@barbatdev, how would you like to sequence this? I can open the #1690 stack as soon as it's approved, or adapt to whatever order you prefer.

[carlosmoradev]

Thanks for the heads-up and for tracing the broader root cause, @matraket!

Forwarding the parent package in #1690 is definitely the right architectural call here. Curating individual child entrypoints was only a stopgap, and resolving all seven missing surfaces at once is much cleaner than patching capture in isolation.

Since @barbatdev already approved #1690, go ahead with your PR stack. Once your stack lands and closes #1688, we can close this PR (or I can close it now if you prefer to keep the queue clean). I can also help test and review your stack when you open it.

[matraket]

Thanks a lot @carlosmoradev, much appreciated! The stack is open now: #1770 → #1771 → #1772 → #1773. #1772 is the one that fixes #1688 (it closes both issues). Feel free to close this one whenever you like, and any testing or review on the stack is very welcome.