Skip to content

fix(claude-code): start a run from Claude Code's own prompt by default (FIX-1185) - #3190

Merged
jhoffner merged 7 commits into
mainfrom
fix/FIX-1185
Oct 12, 2026
Merged

jhoffner merged 7 commits into
mainfrom
fix/FIX-1185

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

This is a draft built for "ship parity", the recommended direction. That direction is with Jake, and the spec amendment that goes with it is #3193.

The problem

When a flow runs Claude Code with no prompt, the Agent SDK sends an empty system prompt. The claude CLI uses Claude Code's own.

What this does

  • New default: when systemPrompt is left out, the block asks the SDK for the claude_code preset, so the run starts the way the CLI starts it. The default is set in one place, so in-session, detached, resumed and capability runs all get it.
  • Everything else passes through unchanged: a string, "", the preset with append, or an array (D2). systemPrompt accepts the SDK's own types (ClaudeAgentSystemPrompt).
  • No promise of a plan. The README, the docs page and the minor changeset say the plan record fills only when the run is offered the to-do tools and the agent chooses to use them. On newer models those tools are off unless they are named in allowedTools.
  • Goal check: goals/claude-code-harness/it-keeps-its-own-plan/ is re-scoped to what holds (below).

What the goal check shows

All runs used Claude Code's default model, claude-sonnet-5, on Agent SDK 0.3.234.

Run Result
Goal PASS. Default arm: the SDK was handed {type:"preset",preset:"claude_code"} on both jobs. Planning arm: 4 rows with 1 completed, and 18 rows with 6 completed
GOAL_CONTROL=empty-prompt FAIL, as expected: prompt:preset only, on both jobs
GOAL_CONTROL=no-record FAIL, as expected: plan:rows and plan:completed only, on both jobs
First contract (an unprompted plan, 3 of 3) FAIL 0/3, kept in the verdict log as evidence. The to-do tools were not offered, and even when offered the agent didn't plan unasked

What's asked of you

Confirm the parity direction (through #3193). If a block-owned plan instruction is chosen instead, this PR grows.

Parts worth reviewing closely

  • The default. agent.ts, where the query options are built: systemPrompt ?? { type: "preset", preset: "claude_code" }. It uses ??, so "" still gives a blank start.
  • The goal check. goals/.../run.mts:
    • The prompt leg reads what the real SDK query() was handed.
    • Plan rows are read only through the resource route, under the request's prefix, with a fresh session per run.
    • The planning arm's request lives in code; the fixture jobs never mention planning.
  • Found, not fixed here. Some recorded rows have status: null: an item was created, and the harness never confirmed a status for it. This is recorder behaviour and outside this change.
Verification
  • V1 test/system-prompt.test-d.ts: the block and the capability accept every SDK shape. Non-prompt objects are @ts-expect-error. The test goes red if preset widens to string (checked).
  • V2/V3 agent.spec.ts "the system prompt a run starts from", plus a capability case:
    • omitted → the preset
    • a string, a long string, "", the preset and an array → byte-identical
    • the same holds on detached+resume, in-session resume, recordWork on and off, and through the capability
    • reverting the default turns 3 tests red (checked)
  • V4 pnpm --filter @flow-state-dev/claude-code test 287/287, typecheck green, goals tsc clean.
  • POC specs/issues/FIX-1185/poc/what-the-sdk-sends still holds on 0.3.234.
  • cursor[bot]/Codex notes from spec(FIX-1185): a coding agent driven through the in-process SDK never invokes its plan tools; the CLI does #3166 folded into the code:
    • one parameterised prompt test across entry paths
    • a second held-out job, used in both arms
    • reads scoped to the request prefix, with a fresh session per run
    • the prompt types declared locally with an open preset object, guarded by a type test
  • Codex P1 (to-do tools off by default) is confirmed and recorded in spec(FIX-1185): amend after implementation: parity default, narrowed goal #3193.

Spec: specs/issues/FIX-1185/ (amendment #3193) · Linear FIX-1185 · epic FIX-1907

🤖 Generated with Claude Code

https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv


Note

Medium Risk
Changing the default system prompt alters agent behavior for every caller that omitted systemPrompt; migration requires explicit "" where the old empty start was intentional.

Overview
Default system prompt now matches the claude CLI. When systemPrompt is omitted, claudeCodeAgent forwards { type: "preset", preset: "claude_code" } to the Agent SDK instead of leaving the run on an empty custom prompt. The default is applied in one place in query options so in-session, detached, resumed, and capability paths behave the same. Hosts that depended on a blank start pass systemPrompt: "" explicitly.

systemPrompt accepts the SDK’s full shapes via new ClaudeAgentSystemPrompt (plain string, string array, or preset with optional append). Docs and examples now show layering instructions with append rather than replacing the whole prompt with a string.

Docs clarify plan recording: observed-plan only fills when TaskCreate/TaskUpdate are in allowedTools and the agent uses them—not from the new default alone.

Verification: unit tests for prompt forwarding, a compile-time type test, capability parity, a minor changeset, and an integration goal (it-keeps-its-own-plan) that asserts the SDK receives the preset and that plan rows record when tools are enabled.

Reviewed by Cursor Bugbot for commit 4ba189e. Configure here.

…t (FIX-1185)

With no systemPrompt the Agent SDK sends an empty custom prompt, not the
one the claude CLI starts from. The block now asks for the claude_code
preset when the host gives none; a string, "" and the SDK's other shapes
pass through unchanged. systemPrompt takes the SDK's union.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
A real Claude Code run with no prompt of its own, recordWork on, and a
held-out job that never mentions planning; the plan rows are read back
through the resource route under the run's own request prefix. Control
GOAL_CONTROL=empty-prompt gives the run the blank start.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
…-1185)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 12, 2026 11:07pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 11:07pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 11:07pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1185

@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: ab96914d-c868-470d-88bd-ed3df7c52ad7)

@jhoffner
jhoffner marked this pull request as ready for review October 12, 2026 22:09
@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 1ac52796-bab9-407b-a843-c8d93088d99b)

…l (FIX-1185)

On Claude Code's current default model the to-do tools are off unless
named in allowedTools, and the agent rarely plans unasked, so the docs no
longer promise the plan fills by default. The goal now checks what holds:
the SDK is handed Claude Code's own prompt by default, and a run that
keeps a to-do list leaves it in the plan record. Controls empty-prompt
and no-record each fail exactly their leg.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: d79d65e8-a7c2-465d-971a-eb92eeee7515)

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / architecture pass (FIX-1185)

Problem: In-process Claude Code runs omitted systemPrompt, so the Agent SDK sent an empty custom prompt and agents rarely used plan/to-do tools — unlike the claude CLI.

Verdict: The production fix is about as small as it can be while matching the spec. One decision site (systemPrompt ?? { type: "preset", preset: "claude_code" }), optional-peer typing mirrored from other harness packages, and tests that pin undefined vs "" vs explicit strings. I would not chase a smaller behavior change (e.g. appending a hand-written “use TaskCreate” line) — that was already measured and rejected in the issue/spec.

Alternatives considered

Approach Why this PR’s shape is better
Document “pass the preset yourself” Every host forgets; plan records stay empty.
Hard-code planning instructions in a string default Not CLI parity; breaks when Claude Code’s prompt changes.
Default only in the capability wrapper Detached/resume/capability paths would still miss it; centralizing at queryOptions is correct.
Import SystemPrompt types from @anthropic-ai/claude-agent-sdk Breaks optional-peer typecheck story; system-prompt.test-d.ts is the right guard.

Where complexity actually lives

Almost all new line count is verification (goal harness + docs), not framework surface. That is appropriate for a behavior claim that must be proved on a real model.

Suggestions (non-blocking)

  1. Goal runner vs goals/lib/http-actions.mts: http.act caps its status poll at ~10s (1000 × 10ms), so run.mts reimplements a longer poll loop. If more claude-code-harness goals need multi-minute runs, consider extending httpActions with an optional deadline (or a waitRequestStatus helper) so goals do not each carry their own polling.
  2. Docs duplication: ClaudeCodeAgentOptions.systemPrompt and ClaudeAgentSystemPrompt repeat the same shape guide; the option JSDoc could defer to the type and keep only recordWork/to-do rationale.
  3. Shared default constant (maybe skip): Tests define CLAUDE_CODE_PROMPT; production inlines the object. A package-level constant would DRY that, but it is optional — the object is tiny and stable.

Skipped / not in this PR

Local main was behind GitHub when I first scanned; the mergeable diff here is 12 files (claude-code + goal + docs + changeset), not the older stacked FIX-1875 orchestration work. I did not re-review dispatch/undispatched in this pass.

Checks: pnpm --filter @flow-state-dev/claude-code test (287 passed); orchestration suite on this branch (1766 passed) — sanity only; orchestration files are not in the PR diff.

Approving — ship when your usual gates are green.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/claude-code/src/sdk/agent.ts Resolved
Comment thread packages/claude-code/src/sdk/agent.ts Resolved
… (FIX-1185)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017pp7wCd87NW4BH7XVuF9Gv
@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 0d3007da-d73f-4e9b-b299-86ca4b4de3d4)

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob — already tight. No POC.

I read packages/claude-code/src/sdk/agent.ts, types.ts, index.ts, capability.ts, test/sdk/agent.spec.ts, test/sdk/capability.spec.ts, test/system-prompt.test-d.ts, packages/claude-code/README.md, apps/docs/docs/tools/claude-code-sdk.md, goals/claude-code-harness/it-keeps-its-own-plan/run.mts, goal.md, and .changeset/claude-code-default-system-prompt.md.

The contract is systemPrompt ?? { type: "preset", preset: "claude_code" }. A named preset adds a symbol. || would turn "" into the default.

ClaudeAgentSystemPrompt is that union once, on the option and on the query options. Inlining it writes it twice. Importing it from the SDK drops the optional-peer pattern ClaudeAgentSettingSource already uses. The open preset object is what lets excludeDynamicSections through; test/system-prompt.test-d.ts is the check that goes red if preset widens or append stops being text.

The option comment is the four spellings a caller has, including what an omitted prompt does to recordWork. The comment on the ?? is why the line is there: an absent prompt makes the SDK send an empty custom prompt, and "" must stay blank. The type comment is why the union is local and why the object stays open. Each of those is a sentence the other two do not say.

promptHandedToSdk is the one spy. The third test is detached resume, in-session resume, and recordWork on and off, plus a host value on two of those paths. The capability test is the other door: createClaudeCodeAgentCapability passes its options into claudeCodeAgent. Sharing the spy is a new module. A runtime test cannot stand in for the @ts-expect-error lines.

The new docs section is the option. The paragraph under observed-plan is the recording consequence (a prose plan is not an observed-gaps row). The README paragraph is that fact next to the record table. The sequencer sample is the append form, because a plain string there would now mean a different agent.

In the goal, tappedResolver is the evidence line (model, tools offered, tool tally) and nothing in it is graded. seedCheckout is eight lines with one caller. The request wait is not untilIdle: a coding run is longer than that helper. The file header matches the other goals; goal.md is the contract.

Head 213a37f9db9d695f7f6de8ac64064a05bb9cb6ae.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob — correction. The review above describes 213a37f9. This head is 268381d3. Still already tight. No POC. Do not put the four spellings back on the option.

268381d3 already points the option at ClaudeAgentSystemPrompt for the shapes. What remains on the option is the omitted default, and the plan caveat: the record fills only when the to-do tools are offered and used, and newer models offer them only when they are named in allowedTools. The comment on ?? is still why the line is there. An absent prompt makes the SDK send an empty custom prompt, and "" stays blank.

The docs section is the option. The paragraph under observed-plan is that tools-off fact, including that an empty record is not an observed-gaps row. The README carries both, next to the record table. The sequencer sample stays the append form.

In the goal, systemPromptSent is the prompt:preset grade. The stream tap (model, tools offered, tool tally) is still not graded. The two loops differ: the default arm checks the preset, the planning arm checks rows. describeRun and finished are the shared lines. seedCheckout is eight lines with one caller. The wait is still not untilIdle.

This correction is the note that counts. Head 268381d3c8e2501b04111f65bfe305f4117dee6a.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T22:19:53.090334Z 268381d Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 268381d3c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 5bba28c8-2b35-4a02-a611-b34aaa63450f)

@jhoffner
jhoffner merged commit faa5326 into main Oct 12, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants