fix(prompt): deliver the harness through appendSystemPrompt so bridge providers receive it

[Alan-TheGentleman]

Linked Issue

Closes #1485

PR Type

• Bug fix

Summary

• gentle-ai and gentle-todo now deliver their before_agent_start text by appending to event.systemPromptOptions.appendSystemPrompt instead of returning a replacement systemPrompt.
• pi-claude-bridge forwards only the structured systemPromptOptions parts, so under claude-bridge the harness (ODD workflow, visible todo projection, review contract, persona, RDD status) and the open-tasks block now reach the model.
• This follows Pi's documented extension contract (docs/extensions.md: prefer changing prompt sections over returning systemPrompt) and adds no bridge-specific handling.

Changes

File	Change
lib/append-system-prompt.ts	New idempotent appendSystemPromptOnce helper
extensions/gentle-ai.ts	Harness goes through appendSystemPrompt; handler returns undefined
extensions/gentle-todo.ts	Open-tasks block goes through appendSystemPrompt
tests/append-system-prompt.test.ts	Helper: separator, idempotency, no-op cases
tests/append-system-prompt-route.test.ts	Both extensions share one appendSystemPrompt, in registration order, without duplication
tests/review-contract-prompt.test.ts, tests/gentle-todo.test.ts	Assert the new route and idempotency
tests/telemetry-trigger.test.ts, tests/runtime-harness.mjs	Updated assertions that read the removed return shape
tests/odd-routing-contract.test.ts	Asserts the phase-reporting clause in the harness
docs/gentle-shell.md	Documents the route and why (docs/review-integration.md is byte-pinned and stays unchanged)
odd/tasks/fix-1485-append-system-prompt.md	Feature document with evidence

Test Plan

• node --experimental-strip-types --test tests/*.test.ts: 3876 pass, 0 fail, 43 skipped (pre-existing Windows-native skips).
• node --experimental-strip-types tests/runtime-harness.mjs: exit 0.
• node scripts/check-provider-contract.mjs: pass.
• node scripts/check-types.mjs: no regressions.
• Live, gentle-shell -p --no-session --model claude-bridge/claude-opus-5-5: asked whether the instructions contain "Default workflow: Organic Driven Development". This branch: yes. Installed release: no.
• Live, openai-codex/gpt-5.5 on this branch: the phrase is present exactly once (no duplication on native providers).
• Shellcheck: not applicable (no scripts changed). Skills: not changed.

Notes

• Pi rebuilds the prompt from the mutated options after before_agent_start (agent-session.js _preparePromptAndToolLoadout), one fresh options object per run, so appends never accumulate across turns. appendSystemPrompt renders as the final addendum section.
• Size: 483 authored lines, above the 400-line budget; about 60% are tests.
• Also inlines a one-line "Phase reporting" instruction for gentle_odd_phase after ODD step 7. It previously lived only in assets/orchestrator-delegation.md, so no provider received it; live under claude-bridge the model now states when to call it.

Contributor Checklist

• Linked issue has status:approved
• Exactly one type:* label
• Docs updated
• Conventional commits
• No Co-Authored-By trailers

Summary by CodeRabbit

• Bug Fixes

  • Gentle AI, review-contract, and open-task instructions are now retained when combined with provider presets, without replacing the existing system prompt.
  • Repeated instructions are not appended twice. ODD phase-change reporting is limited to actual primary-session transitions.

• Documentation

  • Clarified how provider bridges handle structured prompt sections.

[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: 57ce9abe-ee70-47e3-8b85-5bc6eeb69e3f

📥 Commits

Reviewing files that changed from the base of the PR and between cedc69e and 0528e30.

📒 Files selected for processing (11)

• docs/gentle-shell.md
• extensions/gentle-ai.ts
• extensions/gentle-todo.ts
• lib/append-system-prompt.ts
• odd/tasks/fix-1485-append-system-prompt.md
• tests/append-system-prompt-route.test.ts
• tests/append-system-prompt.test.ts
• tests/gentle-todo.test.ts
• tests/review-contract-prompt.test.ts
• tests/runtime-harness.mjs
• tests/telemetry-trigger.test.ts

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

---

📝 Walkthrough

Walkthrough

The gentle-ai and gentle-todo hooks now append prompt content through systemPromptOptions.appendSystemPrompt. A shared helper normalizes and deduplicates additions. Tests and documentation cover the updated hook behavior and provider bridge handling.

Changes

Prompt injection

Layer / File(s)	Summary
Append helper behavior lib/append-system-prompt.ts, tests/append-system-prompt.test.ts	A shared helper normalizes text, skips empty or duplicate additions, and separates distinct additions with a blank line. Tests cover these behaviors and nullish options.
Structured prompt handlers extensions/gentle-ai.ts, extensions/gentle-todo.ts, tests/append-system-prompt-route.test.ts, tests/gentle-todo.test.ts, tests/review-contract-prompt.test.ts, tests/runtime-harness.mjs, tests/telemetry-trigger.test.ts, docs/gentle-shell.md, odd/tasks/fix-1485-append-system-prompt.md	Both hooks append prompt content through the helper and return undefined. Tests check appended content, ordering, duplicate prevention, and handler conditions. Documentation describes how provider bridges forward the structured prompt sections. The task record documents the issue plan and delivery checks.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: decode2

Merge Risk: ⚪ Minimal · up to 0528e

The prompt-routing change is ready to merge after normal checks; no actionable issue remains established.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to 0528e

Task descriptions may gain instruction-level influence on a provider that previously did not receive them. The change is limited to active sessions, but the receiving provider’s authority rules have not been verified.

Retained concerns

• Medium · security · inferred: The new bridge-facing route may elevate tool-state task text into a system-instruction section without separating task data from instructions. This exposure is new for bridges that previously dropped returned prompt values; native providers already received the todo block.

Security review details

Security Blast Radius

• inferred — The identifiable exposure is task text forwarded within the active session to a bridge provider. The inspected change does not establish new cross-tenant, credential, or infrastructure authority.

Security Findings and Attack Paths

• inferred — A task title or note influenced through a tool call can be replayed as part of a higher-authority section on the next turn. Whether the receiving bridge preserves an effective separation between that data and provider controls remains unverified.

Trust Boundaries and Controls

• observed — Task input is normalized to one line before projection, and projected entries appear under a labeled todo heading. Those controls establish formatting, not provider-side authority separation.

Resilience and Maintainability Implications

• observed — Tests cover shared-object ordering, distinct-block accumulation, and repeated identical additions. They construct populated options; they do not establish the external runner’s initialization guarantee.

Hardening Proposals

• proposed — Verify provider instruction ordering and the runner’s options guarantee against the supported external implementations; preserve a clear data boundary around projected task text.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #1485 requires the harness to reach the model through supported providers, or a visible warning when a provider cannot carry it. extensions/gentle-ai.ts and extensions/gentle-todo.ts now app…
Out of Scope Changes check	✅ Passed	The changed helper, extension handlers, tests, documentation, and issue task document directly support Issue #1485. The tests verify the new prompt route and preserve existing session and contract beh…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: routing the harness through appendSystemPrompt so bridge providers receive it.

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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