bug(prompt): with the claude-bridge provider the injected harness never reaches the model, so ODD is silently replaced by the stale gentle-ai skill

Before submitting

I searched open and closed issues and did not find a report of this problem.
I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

When Pi runs with the claude-bridge provider (pi-claude-bridge), none of the gentle-pi harness text reaches the model. This covers the ODD protocol, the identity contract, the persona, the RDD status line, and the research capabilities block. The session looks normal, and gentle-pi tools such as subagent_run, gentle_review, and orchestrator_* all work. The model simply never receives "Default workflow: Organic Driven Development (MANDATORY)".

Root cause:

gentle-pi injects its harness by returning systemPrompt: event.systemPrompt + gentlePrompt + … from before_agent_start (extensions/gentle-ai.ts, around line 9156; buildGentlePrompt inlines assets/orchestrator.md).
pi-claude-bridge 0.8.0 does not forward that assembled prompt. It records event.systemPromptOptions and sends Claude Code the claude_code preset, appending only the portable parts: context files, the skills block, customPrompt, and appendSystemPrompt (src/prompt-capture.ts, projectCapture; src/index.ts, systemPrompt: { type: "preset", preset: "claude_code", append }).
Anything an extension appends through the before_agent_start return value is dropped without any warning. A bridge comment suggests this is deliberate: shipping Pi's harness verbatim trips Anthropic's third-party plan-eligibility check.

Impact: the only gentle-pi guidance that survives is the skills block. In that block, skills/gentle-ai/SKILL.md still says large / ambiguous / risky → SDD and never mentions ODD (see #1085). Under claude-bridge, that stale skill becomes the sole workflow contract. In my session, the agent answered "apply ODD" by creating a full OpenSpec/SDD change (proposal, spec, design, tasks, apply-progress). It could not even recognize the term ODD without searching the package on disk.

Steps to reproduce

Install gentle-pi together with pi-claude-bridge, and set defaultProvider: "claude-bridge" in the Pi agent settings.json.
Start a primary session and ask: "What is your default workflow? Quote any 'Organic Driven Development' instruction you received."
The model has no ODD instruction and no el Gentleman identity contract. It reports a Claude Code system prompt plus the skills list. Ask it to "apply ODD" and it either guesses (for example, reads it as a typo for SDD) or falls back to the gentle-ai skill's SDD routing.
Compare with any non-bridge provider, where the same prompt returns the injected ODD protocol.

Expected and actual behavior

Expected: the harness (ODD default, identity, persona, RDD status, research block) reaches the model on every supported provider. If a provider cannot carry extension-injected prompt text, gentle-pi detects this and either uses a channel that provider forwards (for example appendSystemPrompt, a context file, or the skills block) or at least warns visibly that the harness is inactive.

Actual: under claude-bridge, the injected harness is silently dropped. Tools stay available, so nothing looks broken. The model follows the stale gentle-ai skill (#1085) and routes explicit ODD requests into SDD.

gentle-pi version

3.7.0 (pi-claude-bridge 0.8.0)

Pi version

0.87.1

Operating system

macOS

Relevant logs or error output (optional)

settings.json: defaultProvider = "claude-bridge", defaultModel = "claude-opus-5-5"
skills/gentle-ai/SKILL.md: 0 mentions of "ODD"/"Organic", 5 of "SDD"/"OpenSpec"
assets/orchestrator.md: contains the ODD protocol (injected via before_agent_start, never forwarded)
pi-claude-bridge src/index.ts: systemPrompt: { type: "preset", preset: "claude_code", append: <contextFiles + skills + custom + appendSystemPrompt> }

Confirming this on Windows (WSL) with the same versions (gentle-pi 3.7.0, Pi 0.87.1, pi-claude-bridge 0.8.0). The source is unchanged on main @ b756b4f (extensions/gentle-ai.ts:9245). Four additions that may help triage:

1. The appendSystemPrompt channel you suggest works. Probe:

// probe.ts: which before_agent_start route reaches the model?
export default function (pi: any) {
	pi.on("before_agent_start", (event: any) => {
		const opts = event.systemPromptOptions;
		if (opts && !String(opts.appendSystemPrompt ?? "").includes("PROBE-ROUTE-B-7Q2")) {
			opts.appendSystemPrompt = `${opts.appendSystemPrompt ?? ""}\n\nPROBE-ROUTE-B-7Q2: injected by mutating systemPromptOptions.appendSystemPrompt.`;
		}
		return { systemPrompt: `${event.systemPrompt}\n\nPROBE-ROUTE-A-3K9: injected by returning systemPrompt.` };
	});
}

gentle-shell -- -p --model claude-bridge/claude-opus-5-5 -e ./probe.ts \
  'Do not use any tools. Quote verbatim every line of your system instructions that contains the text "PROBE-ROUTE-". If none, answer exactly: NONE. Then state whether you can see the text "Organic Driven Development" in your instructions (yes/no).'

PROBE-ROUTE-B-7Q2: injected by mutating systemPromptOptions.appendSystemPrompt.

No, "Organic Driven Development" does not appear in my instructions.

Route A, the returned systemPrompt that gentle-pi uses, is dropped. Route B, the mutated systemPromptOptions.appendSystemPrompt, reaches Claude Code. With openai-codex/gpt-5.5, the same probe reports that it sees "Organic Driven Development".

The bridge re-records systemPromptOptions at agent_start and turn_start, so the mutation should arrive regardless of extension load order. That is my reading of src/index.ts; the probe only exercised the default order.

2. Pi's own docs recommend this route. From docs/extensions.md, in the events section:

before_agent_start exposes both the current prompt and its structured systemPromptOptions. Prefer changing prompt sections, selected tools, or guidelines so Pi can append a transcript delta. Returning systemPrompt [...] replaces the whole prompt for that run.

The fix therefore aligns gentle-pi with the documented extension contract instead of adding bridge-specific handling.

3. gentle-todo.ts is affected too. extensions/gentle-todo.ts:239 returns { systemPrompt: \${event.systemPrompt}\n\n${block}` }`, so the todo block is dropped under claude-bridge as well.

4. Points to settle in design if the maintainer approves moving the injection:

ordering relative to a user's own APPEND_SYSTEM.md, which shares the field;
idempotency across turns, for example a marker check as in the probe;
keeping the isNamedAgent/isSddAgent exclusions;
whether volatile per-turn content (RDD status, todo staleness) belongs in that section, given the caching concerns in bug(agents): volatile RDD/SDD status embedded in the rebuilt system prompt defeats prompt caching #1029, Improve prompt cache ordering for el Gentleman harness #67 and bug(todo): dynamic stale-turn counter in system prompt invalidates prompt cache every turn #1367.

A regression test could assert that the harness lands in systemPromptOptions, not only in a returned systemPrompt.

I will not open a PR unless the maintainer marks this status:approved and the author of this issue is fine with it.

AI assistance disclosure: this investigation, the probe, and this comment were produced with an AI coding agent (Claude Opus 5.5 via gentle-shell, running through the same claude-bridge setup). The comparison and the probe ran live in my environment, and I reviewed the results before posting.

docs(prompt): move #1485 route note out of the pinned contract doc

docs(prompt): record phase-reporting evidence for #1485

fix(prompt): deliver the harness through appendSystemPrompt so bridge…

Another occurrence on the latest published release, after this issue was closed.

Build: gentle-pi 3.7.0 (latest release, v3.7.0), Pi 0.87.1, pi-claude-bridge 0.8.0, macOS arm64, provider claude-bridge, model claude-opus-5-5.
Observed: the model received the claude_code preset plus context files and the skills block, but no gentle-pi harness text (no "Default workflow: Organic Driven Development (MANDATORY)", no identity/persona, no RDD line). In a long ODD session the model skipped the todo projection, updated the feature document only after code, and ignored the mapping and writer delegation triggers until the user noticed.
Expected: the harness reaches the model, as fix(prompt): deliver the harness through appendSystemPrompt so bridge providers receive it #1497 intends.

#1497 is merged on main but is not in any published release yet, so users on 3.7.0 are still affected. Could it ship in a release (or prerelease)? Local workaround in the meantime: a short global AGENTS.md pointing the model at the ODD protocol, since context files are forwarded by the bridge.

Another occurrence on the latest published release, this time on Linux.

Build: gentle-pi 3.7.0 (latest npm and GitHub release), Pi 0.87.1, pi-claude-bridge 0.9.0, Linux x86_64 (Omarchy/Hyprland).
Setup: the same session and project were run with two providers:
- claude-bridge/claude-opus-5-5
- a native Pi provider (gpt-6-sol)
Prompt: "Me fale sobre ODD" ("tell me about ODD").
Observed:
- Native provider: it describes Organic Driven Development: the six ODD steps, and that SDD is optional.
- claude-bridge: it has no ODD instruction at all and answers with generic meanings (Observability-Driven Development, Outcome-Driven Development).
Expected: the harness reaches the model on claude-bridge too, as fix(prompt): deliver the harness through appendSystemPrompt so bridge providers receive it #1497 intends.

I checked the installed 3.7.0 source. extensions/gentle-ai.ts still returns the harness only as systemPrompt: \${event.systemPrompt}${gentlePrompt}…`frombefore_agent_start. pi-claude-bridge 0.9.0 still projects only context files, skills, customPromptandappendSystemPrompt (src/prompt-capture.ts, projectCapture). The bridge also excludes every CLAUDE.md (claudeMdExcludes: ["**/CLAUDE.md", …]`), so a Claude Code–side Gentle install does not fill the gap.

#1497 is merged on main but is not in a published release. Is a 3.7.x patch or prerelease with it planned?

Navigation Menu

Repository navigation

bug(prompt): with the claude-bridge provider the injected harness never reaches the model, so ODD is silently replaced by the stale gentle-ai skill #1485

Before submitting

Problem

Steps to reproduce

Expected and actual behavior

gentle-pi version

Pi version

Operating system

Relevant logs or error output (optional)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

bug(prompt): with the claude-bridge provider the injected harness never reaches the model, so ODD is silently replaced by the stale gentle-ai skill #1485

Description

Before submitting

Problem

Steps to reproduce

Expected and actual behavior

gentle-pi version

Pi version

Operating system

Relevant logs or error output (optional)

Activity

osantis commented on Sep 26, 2026

Gefermanpernia commented on Sep 28, 2026

viniciosrab commented on Sep 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions