The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(runner): preserve stock Codex base instructions (#14920)
Dotta408f70e69f9c
diff --git a/doc/plans/2026-10-02-stock-harness-paperclip-checklist.md b/doc/plans/2026-10-02-stock-harness-paperclip-checklist.mdnew file mode 100644index 0000000000..f71067ff07--- /dev/null+++ b/doc/plans/2026-10-02-stock-harness-paperclip-checklist.md@@ -0,0 +1,219 @@+# Stock harness, with Paperclip: working checklist++Created: 2026-10-02. Status: item 1 implemented for native Codex app-server;+PR validation in progress. Other implementation items remain open.++Goal: keep the agent's stock harness behavior and add only what it needs to work+with Paperclip. Apply this across legacy adapters, the new Runner, and their+configuration variants.++We will work through the numbered items one at a time with Dotta. For each item,+record the proposed behavior and Dotta's direction, make a bounded change, and+verify the affected paths before moving on. New findings get stable IDs in the+ledger below so they do not disappear into conversation history.++**Current item: 1 — validate and review the native Codex instruction fix.**++## Agreed direction and boundaries++- Preserve vendor base instructions. Paperclip context should be additive where+ the harness supports it.+- Reduce the default hire operating manual and review every role/team template+ for reduction or removal. Prefer a tiny default, potentially one paragraph.+- Keep a minimal coordination boundary; load uncommon procedures on demand.+- Move bookkeeping into the runtime where it can own the operation reliably.+- Check capability and configuration behavior across all harness paths.+- Paperclip owns MCP configuration. Missing personal integrations are acceptable+ and intentional; restoring them is not a goal of this work.+- Configuration changes and configuration-driven session resets are acceptable.+- Preserve Paperclip authentication, assigned skills, workspace access, tool+ authorization, company boundaries, checkout, approvals, budget hard stops,+ pause/cancel behavior, audit records, and usable task/artifact delivery.+- Restore appropriate repository instruction context without accidentally+ importing unrelated host configuration or displacing Paperclip-owned MCPs.+- Decide explicitly how changed defaults affect existing agents and sessions;+ do not assume existing custom instructions should be rewritten.++## 1. Preserve the native Codex base instructions++- [x] Trace every instruction path: backend composition, TypeScript driver,+ runnerd bridge, and Rust provider; include fresh threads, resume, and recovery.+- [x] Record the chosen additive mechanism and the minimum Paperclip context it+ needs to carry. Include fallback/direct execution paths.+- [x] Remove default replacement of stock base instructions across those paths.+- [x] Verify the actual app-server request and retained session instructions,+ including resume; checking only a prompt builder is insufficient.+- [ ] Verify Paperclip task context, tools, auth, assigned skills, and completion+ still work. Record applicable regressions and eval results.++Starting points: [Codex backend](../../packages/paperclip-runner/src/backends/codex-native-backend.ts),+[app-server driver](../../packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts),+[runnerd transport](../../packages/paperclip-runner/src/live/runnerd-codex-transport.ts),+[Rust provider](../../packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs).++Decision: use additive `developerInstructions` on Codex start and resume in the+TypeScript driver, Runner Lab/eval sessions, and Rust provider. Retain existing+instruction fields for other provider facades. Keep the Paperclip fragment and+its historical option/trace names unchanged in this bounded fix.++Transition: pre-change Codex threads retain their saved replacement base prompt+and need a provider session reset. Do not reset active sessions automatically.+The separate Codex-through-ACP dependency patch remains a coverage follow-up+under item 6; this change covers the native app-server path.++## 2. Reduce the default operating manual and shared prompt layers++- [ ] Inventory what an agent actually receives: hire instructions, shared+ prompt template, wake context, runtime prompt, bootstrap, and loaded skills.+ Separate always-present text from content loaded on demand.+- [ ] Agree on the tiny common contract and the coordination details that each+ runtime still requires. Legacy API coordination and native semantic tools+ need appropriate instructions for their respective interfaces.+- [ ] Remove repeated workflow rules and stock coding/style/autonomy guidance.+- [ ] Move detailed planning, hiring, artifacts, and exceptional procedures to+ discoverable references or tools where feasible.+- [ ] Check fresh and resumed task/chat flows for instruction duplication and+ contradictory completion or waiting rules.++Starting points: [default hire instructions](../../server/src/onboarding-assets/default/AGENTS.md),+[shared adapter utilities](../../packages/adapter-utils/src/server-utils.ts),+[native runtime contract](../../packages/paperclip-runner/src/contracts/runtime-context.ts),+[Paperclip operational skill](../../skills/paperclip/SKILL.md).++Decision: exact retained paragraph and on-demand boundaries pending.++## 3. Review every hiring and role template++- [ ] Cover default hires, CEO, chief of staff, coder, QA, UX, security, CTO, and+ every other shipped team/role instruction set.+- [ ] Trace onboarding, API/UI/CLI hiring, team imports, and agent-creation skill+ rules so a removed manual is not regenerated through another entry point.+- [ ] For each template, decide: remove it, retain a tiny role description, or+ keep specific domain guidance with a stated reason.+- [ ] Review forced delegation, mandatory memory workflows, procedural review+ routing, comment requirements, and old governance instructions.+- [ ] Update hiring references and draft-review requirements alongside templates.+ Native Runner agents must not be required to follow legacy skill/API procedures+ that their runtime intentionally does not expose.+- [ ] Decide rollout for new hires, existing managed bundles, imported teams,+ and custom agent instructions.+- [ ] If substantial behavioral instructions remain, identify the behavior they+ should improve and add appropriate eval coverage. A tiny role paragraph may+ need only creation/configuration coverage.++Starting points: [onboarding assets](../../server/src/onboarding-assets/),+[default bundle service](../../server/src/services/default-agent-instructions.ts),+[agent routes](../../server/src/routes/agents.ts),+[hiring skill and references](../../skills/paperclip-create-agent/),+[teams catalog](../../packages/teams-catalog/catalog/).++Decision: per-template disposition and migration policy pending.++## 4. Fix repository context while retaining Paperclip configuration++- [ ] Map instruction discovery and precedence for each harness: repository+ AGENTS.md/CLAUDE.md or equivalent, project/local settings, isolated homes, and+ explicit Paperclip instruction injection.+- [ ] Distinguish repository instructions from settings that also load MCPs,+ plugins, credentials, or skills; choose selective loading/injection as needed.+- [ ] Verify repository instructions are available in the correct workspace,+ including worktrees, remote execution, and resumed sessions.+- [ ] Verify assigned skill discovery/pinning, authentication, Paperclip MCP+ ownership, tool authorization, and configuration-change invalidation.+- [ ] Record intentional isolation separately from accidental lost context.++Claude starting points: [local adapter](../../packages/adapters/claude-local/src/server/execute.ts),+[ACP patch](../../patches/@[email protected]),+[runtime sandbox](../../packages/paperclip-runner/src/drivers/acpx/runtime-sandbox.ts).++Decision: repository-context loading mechanism per harness pending. Personal MCP+isolation is approved and should remain.++## 5. Let the runtime own bookkeeping++- [ ] Map which runtime owns checkout, status transitions, completion comments,+ artifacts, waiting/review states, and recovery; identify manual duplicates.+- [ ] Keep one valid completion path per runtime and preserve meaningful user+ questions, approval requests, dependency waits, and final deliverables.+- [ ] Remove agent instructions for operations the runtime already performs;+ retain necessary coordination for legacy/external adapters.+- [ ] Verify durable task state, visible final answer, artifact access, audit,+ and restart/recovery behavior through the real product paths.++Decision: exact runtime responsibilities and legacy compatibility pending.++## 6. Complete the harness and configuration coverage audit++This matrix is an inventory seed, not a claim that every path has been audited+or qualified. Expand it from the registry and provider/profile definitions.+For every numbered change, record applicability here or an explicit reason it+does not apply.++| Execution family | Paths to cover | Audit status |+| --- | --- | --- |+| Legacy Codex / Claude | Local adapters, managed auth and isolated configuration | Initial inspection only |+| Other legacy local adapters | ACPX, OpenCode, Pi, Cursor, Gemini, Grok, Kimi, Hermes | Pending |+| Other adapter transports | Cursor Cloud, Hermes/OpenClaw gateways, process, HTTP, external adapter plugins | Pending |+| Runner Codex | App-server driver, runnerd bridge, Rust provider, direct/fallback paths | Additive instruction fix implemented; PR validation pending |+| Runner ACPX | Enabled profiles, especially Claude/Grok; declared or pending profiles tracked separately | Claude initial inspection; remaining audit pending |+| Runner OpenCode | Native provider and configuration paths | Pending |+| Hosted/remote providers | Claude Managed and AWS AgentCore; identify their own baseline rather than assuming CLI semantics | Pending |++- [ ] Inventory supported profiles and qualification status from the+ [adapter registry](../../server/src/adapters/registry.ts) and+ [provider resolver](../../server/src/services/native-runtime/provider-profile.ts).+- [ ] Cover local/remote environments, fresh/resumed sessions, managed/custom+ hires, task/chat/planning flows, and auth/configuration variants as applicable.+- [ ] Audit restrictions on tools, skills, subagents, memory, and other harness+ capabilities. Trace effective provider configuration, not just intermediate+ configuration objects; document intentional limits and decide accidental ones.+- [ ] Check shared fixes reach every relevant adapter; document provider-specific+ exceptions instead of silently extending a Codex/Claude assumption.++## Verification and evals — apply to each item++- [ ] Map existing coverage before adding cases; use [doc/evals.md](../evals.md).+ Keep Runner protocol evals and Product E2E evals distinct.+- [ ] Start with narrow deterministic checks for instruction layering, effective+ configuration, skill/auth delivery, and session behavior where appropriate.+- [ ] Use Runner evals for provider/session/tool protocol changes; use Product+ E2E for real hiring, repository context, task lifecycle, and artifact delivery.+- [ ] Review existing context-integrity, hiring, completion-updates, and blocker+ suites for reusable coverage; record gaps rather than claiming coverage from+ a similarly named case.+- [ ] Compare task quality as well as Paperclip protocol compliance when claiming+ that fewer instructions improve agent performance. Keep model, effort,+ permissions, tools, and fixture comparable.+- [ ] Select narrow live cells when implementation is ready; retain revisions,+ profile/environment, grader, retries, usage/cost, and failure classification.+- [ ] Run the relevant checks for each change and the repository's required full+ verification before a PR-ready handoff. Record unrun checks and their reasons.++## Findings ledger++Confirmed mechanics below do not by themselves establish an effect on task quality.++| ID | Finding | Work item / disposition |+| --- | --- | --- |+| F1 | Native Codex sent Paperclip text as `baseInstructions`. Probes on codex-cli 0.153.4 showed replacement; additive `developerInstructions` retained the stock base on start and cold resume. | 1; app-server fix implemented, PR validation pending |+| F2 | Default hires and role templates prescribe substantial operating procedures; common prompt and wake layers add further coordination text. | 2–3; mechanics confirmed, performance effect unmeasured |+| F3 | Hiring references require legacy Paperclip skill/comment procedures, while native Runner intentionally omits that operational skill and uses semantic tools. | 2–3, 5; reconcile runtime contracts |+| F4 | Local Claude appends instructions; Runner Claude preserves the Claude Code preset. Runner isolation excludes project/local settings, which can also exclude repository instruction discovery. | 4; selective context fix to design |+| F5 | Some Codex capability settings differ between the direct driver and daemon path; an intermediate configuration does not prove the final provider behavior. | 6; effective-path audit pending |+| F6 | Omitting or nulling `baseInstructions` on an old Codex thread's resume preserves its saved replacement; an empty string produces an empty base. | 1; document the required provider session reset; no automatic migration in this PR |+| F7 | The isolated Codex-through-ACP dependency patch also sets `baseInstructions` on start/resume. It is a separate path from the native app-server backend. | 6; follow-up patch/profile audit pending |++Append new findings with evidence, affected paths, and the numbered item that+will address them. Record intentional behavior explicitly rather than as a bug.++## Decision and completion log++| Date | Decision / outcome | Evidence / follow-up |+| --- | --- | --- |+| 2026-10-02 | Dotta approved preserving stock instructions, smaller defaults/templates, minimal coordination, runtime bookkeeping, and coverage across harnesses. | Implementation details to work through one item at a time. |+| 2026-10-02 | Paperclip-owned MCP isolation and configuration changes/session resets are acceptable. | Preserve Paperclip auth and assigned skills while fixing repository context. |+| 2026-10-02 | Dotta requested implementation and a PR for item 1. Native app-server paths now use additive developer instructions. | 139 targeted TypeScript tests and 91 Rust provider tests passed; repository typecheck/build passed. Remaining test/review results to record. |+| 2026-10-02 | Verified actual Codex instruction layering using a localhost Responses stub, without paid inference. | codex-cli 0.153.4 sent identical 14,732-character stock base instructions on start and cold resume, with the Paperclip marker retained in developer input. This is protocol evidence, not a task-quality eval. |++For each completed item, add the chosen behavior, changed paths, verification+results, remaining exceptions, and follow-ups here before checking it off.diff --git a/packages/paperclip-runner/docs/tutorials/codex.md b/packages/paperclip-runner/docs/tutorials/codex.mdindex 47b57433d7..e4c0d1126d 100644--- a/packages/paperclip-runner/docs/tutorials/codex.md+++ b/packages/paperclip-runner/docs/tutorials/codex.md@@ -73,6 +73,17 @@ test "$(cat "$codex_workspace/hello.txt")" = "hello from Codex runner"## Step 3: Inspect the exact model boundary+Paperclip sends its runtime instructions as additive `developerInstructions`+on Codex thread start and resume. Codex retains its stock base instructions.+The historical `context.baseInstructions` trace field contains the Paperclip+fragment, not the full Codex base prompt. The driver option with the same name+also supplies this additive fragment.++Threads created before this change retain their saved replacement base prompt+when resumed. Reset those provider sessions to apply the stock base instructions;+adding developer instructions does not repair an already saved base prompt.+This change does not alter session recovery or reset active sessions automatically.+```shjq '.context | {protocolVersion,diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs b/packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rsindex 437e0ea01a..95bc8579d5 100644--- a/packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/src/codex_provider.rs@@ -1038,12 +1038,19 @@ impl CodexProvider {"model": config.model,"approvalPolicy": config.approval_policy,"runtimeWorkspaceRoots": [config.cwd],- "baseInstructions": config.instructions,"dynamicTools": dynamic_tools,});let params_object = params.as_object_mut().expect("Codex thread parameters are an object");+ // Codex's baseInstructions replaces its stock prompt. OpenCode+ // uses the same protocol facade but keeps its existing contract.+ let instruction_field = if config.provider == "codex" {+ "developerInstructions"+ } else {+ "baseInstructions"+ };+ params_object.insert(instruction_field.to_owned(), json!(config.instructions));if provider.permission_profile == "paperclip-runner-external-sandbox" {// The execution target (for example Daytona) is the OS sandbox.// Codex must not try to create nested user/network namespaces,diff --git a/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs b/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rsindex dac280fdf3..601fb38394 100644--- a/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs+++ b/packages/paperclip-runner/runner/crates/runner-core/tests/codex_provider.rs@@ -6290,6 +6290,34 @@ fn skill_wire_requests(directory: &Path) -> Vec<Value> {.collect()}+#[test]+fn runtime_instructions_are_additive_for_codex_on_start_and_resume() {+ let directory = temporary_directory("instruction-channel-wire");+ let log = directory.join("requests.ndjson");+ let config = provider_config(&directory, &["--request-log", log.to_str().unwrap()]);+ let mut provider = CodexProvider::start(&config, None).unwrap();+ let thread_id = provider.thread_id().to_owned();+ provider.shutdown().unwrap();+ let mut resumed = CodexProvider::start(&config, Some(&thread_id)).unwrap();+ resumed.shutdown().unwrap();+ let frames = skill_wire_requests(&directory);+ for method in ["thread/start", "thread/resume"] {+ let frame = frames+ .iter()+ .find(|frame| frame["method"] == method)+ .unwrap();+ assert_eq!(+ frame["params"]["developerInstructions"], config.instructions,+ "{method}"+ );+ assert!(+ frame["params"].get("baseInstructions").is_none(),+ "{method}"+ );+ }+ fs::remove_dir_all(directory).unwrap();+}+#[test]fn skill_instructions_flag_reaches_start_and_resume_and_preserves_absent_config() {for flag in [Some(true), Some(false), None] {diff --git a/packages/paperclip-runner/src/contracts/codex.ts b/packages/paperclip-runner/src/contracts/codex.tsindex 605fd29d52..b8db8eb86b 100644--- a/packages/paperclip-runner/src/contracts/codex.ts+++ b/packages/paperclip-runner/src/contracts/codex.ts@@ -50,6 +50,8 @@ export interface CodexModelContextSnapshot {collaborationMode: "default" | "plan";sandbox: unknown;approvalPolicy: unknown;+ /** Historical trace field for the Paperclip instruction fragment, supplied+ * to Codex as developerInstructions rather than replacing its stock base. */baseInstructions: string;instructionSources: string[];instructionPolicy: {diff --git a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.tsindex da221eff7f..62151df5ea 100644--- a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts+++ b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts@@ -199,6 +199,14 @@ export class CodexAppServerDriver implements HarnessDriver {return this.#options.baseInstructions ?? CODEX_SKILLLESS_BASE_INSTRUCTIONS;}+ #instructionParams(instructions = this.#baseInstructions()): Record<string, string> {+ // baseInstructions replaces Codex's stock prompt. Other providers use this+ // driver as a protocol facade and retain their existing instruction field.+ return (this.#options.driverIdentity?.kind ?? DRIVER_KIND) === DRIVER_KIND+ ? { developerInstructions: instructions }+ : { baseInstructions: instructions };+ }+async descriptor(): Promise<HarnessDriverDescriptor> {const unsupported = Object.entries(this.#caps).filter(([, supported]) => !supported)@@ -280,7 +288,7 @@ export class CodexAppServerDriver implements HarnessDriver {...(this.#direct()? {}: {- baseInstructions: this.#baseInstructions(),+ ...this.#instructionParams(),completionContract: {revision:this.#options.taskEnvelope.completionContract.revision,@@ -408,7 +416,7 @@ export class CodexAppServerDriver implements HarnessDriver {this.#options.includeSkillInstructions ?? false,this.#options.environment,),- baseInstructions: this.#direct() ? "" : this.#baseInstructions(),+ ...this.#instructionParams(this.#direct() ? "" : this.#baseInstructions()),approvalPolicy: this.#options.approvalPolicy ?? "never",...(this.#options.model ? { model: this.#options.model } : {}),dynamicTools: this.#providerDynamicTools(),diff --git a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.lifecycle.test.ts b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.lifecycle.test.tsindex 91ec041ee1..81e8a3def9 100644--- a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.lifecycle.test.ts+++ b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.lifecycle.test.ts@@ -477,7 +477,7 @@ describe("Codex app-server Codex driver", () => {});});- it("places Paperclip runtime instructions in Codex's system channel and enables only selected skill instructions", async () => {+ it("adds Paperclip developer instructions without replacing the Codex base and enables selected skills", async () => {const transport = new FakeCodexTransport();const baseInstructions = ["You are running as a Paperclip agent.",@@ -499,17 +499,68 @@ describe("Codex app-server Codex driver", () => {(call) => call.method === "thread/start",);expect(threadStart?.params).toMatchObject({- baseInstructions,+ developerInstructions: baseInstructions,config: {"skills.include_instructions": true,include_apps_instructions: false,},});+ expect(threadStart?.params).not.toHaveProperty("baseInstructions");expect(JSON.stringify(threadStart?.params.input ?? null)).not.toContain(baseInstructions,);});+ it.each(["task", "prepared", "direct"] as const)("preserves stock Codex instructions on %s recovery", async (conversationMode) => {+ const originalTransport = new FakeCodexTransport();+ const recoveryTransport = new FakeCodexTransport();+ const baseInstructions = "Paperclip coordination and assigned instruction paths.";+ const driver = makeDriver([originalTransport, recoveryTransport], {+ conversationMode,+ baseInstructions,+ includeSkillInstructions: true,+ });+ const original = await driver.openSession({+ runId: "run-additive-recovery",+ normalizedSessionId: "normalized-additive-recovery",+ workingDirectory: WORKSPACE,+ });+ const snapshot = await original.snapshot();+ recoveryTransport.readResponse = {+ thread: { id: snapshot.driverSessionId, sessionId: snapshot.providerSessionId, cwd: WORKSPACE, turns: [] },+ };+ await original.close({ reason: "verify additive recovery" });++ const recovered = await driver.recoverSession(snapshot);+ expect(recovered.recovered).toBe(true);+ const started = originalTransport.calls.find((call) => call.method === "thread/start")!.params;+ const resumed = recoveryTransport.calls.find((call) => call.method === "thread/resume")!.params;+ expect(started).not.toHaveProperty("baseInstructions");+ expect(resumed).not.toHaveProperty("baseInstructions");+ expect(started.developerInstructions).toBe(conversationMode === "direct" ? undefined : baseInstructions);+ expect(resumed.developerInstructions).toBe(conversationMode === "direct" ? "" : baseInstructions);+ expect(resumed.dynamicTools).toEqual(started.dynamicTools);+ expect(resumed.config).toEqual(started.config);+ await recovered.session?.close({ reason: "verified additive recovery" });+ });++ it("retains the instruction field for non-Codex provider facades", async () => {+ const transport = new FakeCodexTransport();+ const driver = makeDriver([transport], {+ baseInstructions: "Provider-specific runtime context.",+ driverIdentity: { kind: "opencode_server", displayName: "OpenCode", version: "1" },+ });+ const session = await driver.openSession({+ runId: "run-facade-instructions",+ normalizedSessionId: "normalized-facade-instructions",+ workingDirectory: WORKSPACE,+ });+ const started = transport.calls.find((call) => call.method === "thread/start")!.params;+ expect(started.baseInstructions).toBe("Provider-specific runtime context.");+ expect(started).not.toHaveProperty("developerInstructions");+ await session.close({ reason: "verified facade instructions" });+ });+it("passes the common typed-event contract and reports one provider turn terminal", async () => {const transport = new FakeCodexTransport();const driver = makeDriver([transport]);diff --git a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.test.ts b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.test.tsindex 3f68152e45..2f667d72ee 100644--- a/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.test.ts+++ b/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver.test.ts@@ -572,7 +572,7 @@ describe("Codex app-server Codex driver", () => {});});- it("places Paperclip runtime instructions in Codex's system channel and enables only selected skill instructions", async () => {+ it("adds Paperclip developer instructions without replacing the Codex base and enables selected skills", async () => {const transport = new FakeCodexTransport();const baseInstructions = ["You are running as a Paperclip agent.",@@ -592,12 +592,13 @@ describe("Codex app-server Codex driver", () => {const threadStart = transport.calls.find((call) => call.method === "thread/start");expect(threadStart?.params).toMatchObject({- baseInstructions,+ developerInstructions: baseInstructions,config: {"skills.include_instructions": true,include_apps_instructions: false,},});+ expect(threadStart?.params).not.toHaveProperty("baseInstructions");expect(JSON.stringify(threadStart?.params.input ?? null)).not.toContain(baseInstructions);});diff --git a/packages/paperclip-runner/src/drivers/codex/codex-driver-types.ts b/packages/paperclip-runner/src/drivers/codex/codex-driver-types.tsindex 77303d77be..33b56c880a 100644--- a/packages/paperclip-runner/src/drivers/codex/codex-driver-types.ts+++ b/packages/paperclip-runner/src/drivers/codex/codex-driver-types.ts@@ -20,6 +20,8 @@ export interface CodexAppServerDriverOptions {/** Per-run reasoning effort sent with each Codex turn, including resumed turns. */reasoningEffort?: string;approvalPolicy?: "never" | "on-request" | "untrusted";+ /** Paperclip runtime instructions. Codex receives these as additive developer+ * instructions; the historical option name remains compatible with callers. */baseInstructions?: string;includeSkillInstructions?: boolean;/** Private instruction directory registered by the control plane for this run. */diff --git a/packages/paperclip-runner/src/live/live-session.test.ts b/packages/paperclip-runner/src/live/live-session.test.tsindex 8eef8f295f..938479a0da 100644--- a/packages/paperclip-runner/src/live/live-session.test.ts+++ b/packages/paperclip-runner/src/live/live-session.test.ts@@ -918,8 +918,9 @@ describe("Capability live runnerd and Codex session", () => {expect(names.filter((name) => name === "paperclip_finish")).toHaveLength(1);expect(names.filter((name) => name === "paperclip_block")).toHaveLength(1);expect(names).not.toContain("create_task");- expect(opened.params.baseInstructions).toContain('"revision":"paperclip-capability-live-v1"');- expect(opened.params.baseInstructions).toContain('"criterionIds":["objective"]');+ expect(opened.params).not.toHaveProperty("baseInstructions");+ expect(opened.params.developerInstructions).toContain('"revision":"paperclip-capability-live-v1"');+ expect(opened.params.developerInstructions).toContain('"criterionIds":["objective"]');await first.suspend();const restoredService = new CapabilityLiveSessionService({ store, transportFactory: factory });const restored = await restoredService.restore(first.id);@@ -928,7 +929,8 @@ describe("Capability live runnerd and Codex session", () => {names.filter((name) => name !== "paperclip_finish" && name !== "paperclip_block"),);const resumed = state.transports[1]!.requests.find((request) => request.method === "thread/resume")!;- expect(resumed.params.baseInstructions).toBe(opened.params.baseInstructions);+ expect(resumed.params).not.toHaveProperty("baseInstructions");+ expect(resumed.params.developerInstructions).toBe(opened.params.developerInstructions);await restoredService.shutdown(restored.id);await firstService.shutdown(first.id);});@@ -989,11 +991,11 @@ describe("Capability live runnerd and Codex session", () => {expect(state.transports[0]?.requests.find((request) => request.method === "thread/start",- )?.params.baseInstructions,+ )?.params.developerInstructions,).toContain("Native instructions\n\nRead-only instruction sibling root: /runtime/instructions",);- expect(state.transports[0]?.requests.find((request) => request.method === "thread/start")?.params.baseInstructions)+ expect(state.transports[0]?.requests.find((request) => request.method === "thread/start")?.params.developerInstructions).toContain('Native completion report contract: {"revision":"paperclip-capability-live-v1","criterionIds":["objective"]}');await service.shutdown(session.id);});diff --git a/packages/paperclip-runner/src/live/live-session.ts b/packages/paperclip-runner/src/live/live-session.tsindex d24995b5ec..28ec49d172 100644--- a/packages/paperclip-runner/src/live/live-session.ts+++ b/packages/paperclip-runner/src/live/live-session.ts@@ -2479,7 +2479,7 @@ export class CapabilityLiveSession {config: createSkilllessCodexThreadConfig(this.#config.workingDirectory),permissions: CODEX_PERMISSION_PROFILE,runtimeWorkspaceRoots: [this.#config.workingDirectory],- baseInstructions,+ ...(provider === "codex" ? { developerInstructions: baseInstructions } : { baseInstructions }),persistExtendedHistory: true,});const resumedThread = record(resumed.thread);@@ -2504,7 +2504,7 @@ export class CapabilityLiveSession {permissions: CODEX_PERMISSION_PROFILE,runtimeWorkspaceRoots: [this.#config.workingDirectory],approvalPolicy: "never",- baseInstructions,+ ...(provider === "codex" ? { developerInstructions: baseInstructions } : { baseInstructions }),completionContract: LIVE_COMPLETION_CONTRACT,dynamicTools: [...semanticTools, ...codexSemanticToolSpecs()],experimentalRawEvents: true,diff --git a/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts b/packages/paperclip-runner/src/live/runnerd-codex-transport.test.tsindex 94c744c7e5..8ab547d221 100644--- a/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts+++ b/packages/paperclip-runner/src/live/runnerd-codex-transport.test.ts@@ -4247,11 +4247,14 @@ it("captures exact provider frames and correlates Rust and TypeScript interpretadecodedFrames.find((frame) => frame.method === "thread/start"),).toMatchObject({params: {- baseInstructions: withCodexCollaborationRuntimeInstructions(+ developerInstructions: withCodexCollaborationRuntimeInstructions(CODEX_SKILLLESS_BASE_INSTRUCTIONS,),},});+ expect(+ (decodedFrames.find((frame) => frame.method === "thread/start")?.params as Record<string, unknown>),+ ).not.toHaveProperty("baseInstructions");const stages = new Set([...nativeEntries, ...rehydratedEntries].filter((entry) => entry.kind === "interpretation")diff --git a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts b/packages/paperclip-runner/src/live/runnerd-codex-transport.tsindex 1a49999f21..c067f2a541 100644--- a/packages/paperclip-runner/src/live/runnerd-codex-transport.ts+++ b/packages/paperclip-runner/src/live/runnerd-codex-transport.ts@@ -4544,7 +4544,7 @@ class DurablePrpCodexTransport implements CodexAppServerTransport {provider === "codex" &&record(params.config).include_collaboration_mode_instructions !== false;const unboundBaseInstructions = String(- params.baseInstructions ?? "You are a Paperclip agent.",+ params.developerInstructions ?? params.baseInstructions ?? "You are a Paperclip agent.",);const baseInstructions =sourceRuntimeContext && runtimeContext