Skip to content

chore: backport Coder Agents system-instruction improvements to 2.37 (#29237, #29281, #29401, #29579) - #29654

Merged
ibetitsmike merged 4 commits into
release/2.37from
mike/backport-system-instructions-2.37
Sep 21, 2026
Merged

ibetitsmike merged 4 commits into
release/2.37from
mike/backport-system-instructions-2.37

Conversation

@ibetitsmike

Copy link
Copy Markdown
Collaborator

Backport of the Coder Agents system-instruction improvements that landed on main since 2.37 branched, so 2.37 chats get the same task, completion, and workspace guidance as main.

Source PRs, cherry-picked with -x in merge order:

  1. fix(coderd/x/chatd): clarify the no-workspace tool error message #29237 fix(coderd/x/chatd): clarify the no-workspace tool error message. Applied as-is.
  2. fix(coderd/x/chatd/chatloop): tell the model to gather context before retrying an exclusive tool #29281 fix(coderd/x/chatd/chatloop): tell the model to gather context before retrying an exclusive tool. Applied as-is.
  3. fix(coderd/x/chatd): improve agent task and completion guidance #29401 fix(coderd/x/chatd): improve agent task and completion guidance (inspect, act, validate, finish discipline; explore-subagent search discipline). Applied as-is.
  4. fix: use workspaces when chat capabilities are insufficient #29579 fix: use workspaces when chat capabilities are insufficient (system prompt, workspace awareness, planning overlay, create_workspace tool description, user docs). Applied with one omission, described below.

After these picks coderd/x/chatd/prompt.go, coderd/x/chatd/instruction_internal_test.go, and coderd/x/chatd/chattool/createworkspace.go are byte-identical to main.

Omitted from #29579: the TestCreateWorkspaceTool_EndToEnd rewrite. It depends on DisableWorkspaceAgentContextSync (#28522) and on same-turn workspace-context publication, neither of which is on release/2.37, and without that flag the seeded snapshot races agent discovery. The 2.37 version of the test still passes against the new guidance; only the workspace-awareness assertions in TestCreateChatInsertsWorkspaceAwarenessMessage are updated. The commit message carries the same note.

Other chatd commits since the branch point were reviewed and not backported: they are runtime or feature changes (compaction tool definitions, reasoning overrides, SVG attachments, stream timeout, quickgen model routing), not instruction changes.

Validation on this branch:

  • go test ./coderd/x/chatd/ -run 'TestDefaultSystemPrompt|TestPlanningOverlayPrompt|TestWorkspaceAwareness|TestRenderPlanPathPrompt|TestExploreSubagentOverlayPrompt|TestStoreChatAttachment_NoWorkspace|TestCreateChatInsertsWorkspaceAwarenessMessage|TestCreateWorkspaceTool_EndToEnd': 12 tests pass, including the E2E.
  • go test ./coderd/x/chatd/chattool/ ./coderd/x/chatd/chatloop/ -run 'TestCreateWorkspaceDescription|TestExclusiveToolPolicy': pass.
  • go test ./coderd/ -run TestChatSystemPrompt: pass.
  • markdownlint-cli2 on the five touched docs pages: 0 errors.
  • Pre-commit hook (gen, fmt, lint) passed on the amended fix: use workspaces when chat capabilities are insufficient #29579 commit.

Xum opened this PR on behalf of @ibetitsmike.

bpmct and others added 4 commits September 21, 2026 09:30
)

The old message, "no workspace is associated with this chat," read like
a general chat error and did not make clear that the *tool call itself*
needed a workspace. Smaller/local models tend to misread vague tool
errors as a hard stop, so the new wording says directly what is missing
and what to do: "this tool requires a workspace and this chat does not
have one."

Fixes CODAGT-1029

> Generated by Coder Agents on behalf of @bpmct.

(cherry picked from commit 439f4fd)
… retrying an exclusive tool (#29281)

When the model batches `advisor` (an exclusive tool) with other tool
calls, every call in the batch is rejected and the `advisor` result only
says to retry with `advisor` alone. That nudges the model toward
re-calling `advisor` immediately, even when the sibling calls were there
to gather context for it.

Extend the message so the model is told to run the other tools first
when it still needs their output, then retry with only the exclusive
tool call.

Generated by Coder Agents on behalf of @ibetitsmike.

(cherry picked from commit 0362e53)
Chatd's guidance discouraged workspace creation even when the chat
lacked the tools or context needed to finish a request. Make a suitable
workspace the fallback when missing tools, skills, MCPs, or context
block progress, while preferring existing capabilities when sufficient.

Align the system prompt, workspace awareness, planning guidance, tool
description, regression tests, and user documentation. Preserve
template-selection guardrails and delegated-agent restrictions.

**Open review finding:** workspace readiness can precede initial
MCP/context discovery. The wording now acknowledges this limitation; a
runtime synchronization fix is pending a scope decision.

<details>
<summary>Implementation and verification context</summary>

- Coding requests authorize necessary workspace setup without a separate
workspace request; self-contained examples remain workspace-free when
existing capabilities suffice.
- Detached root chats create a workspace; attached stopped workspaces
use start_workspace. Persisted awareness describes the initial state
rather than claiming the chat remains detached.
- Delegated chats report workspace needs to their parent. Provisioning
does not unlock workspace MCP tools in Plan Mode.
- Use actually exposed capabilities; do not assume readiness means all
skills, MCP tools, and context have loaded, or recreate workspaces to
retry discovery.
- Prompt, workspace-creation, template-selection, setup-failure, Plan
Mode MCP boundary, and API prompt-composition tests pass. The creation
E2E now verifies published instructions, skills, and MCP tools appear in
request two with no extra user turn; repeated and race runs pass. This
does not establish live-model compliance or discovery readiness.
- Full make pre-commit passes, including generation, formatting, lint,
and the slim build. All CI checks pass on f4f6133 (23 passed, 8
skipped), and Codex reports no major issues on that commit.
- Codex review iterations corrected prompt/tool conflicts. The alleged
immutable-per-turn tool catalog was disproved by the per-task generation
lifecycle. The narrower initial-discovery race remains open: no existing
chatd-visible signal distinguishes pending discovery from completed
empty or failed discovery.

</details>

Generated by Coder Agents on behalf of @ibetitsmike.

Backport note: the TestCreateWorkspaceTool_EndToEnd rewrite from the
original commit is omitted. It depends on DisableWorkspaceAgentContextSync
(#28522) and on same-turn workspace-context publication, neither of which
is on release/2.37. The 2.37 version of that test still passes with the
new guidance; only the workspace-awareness assertions are updated.
(cherry picked from commit cc8c766)
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 21, 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-09-21T09:59:51.263853Z 8d21f13 PR opened
ℹ️ 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.

@github-actions

Copy link
Copy Markdown
Contributor

👋 Hey @ibetitsmike!

This PR is targeting the release/2.37 release branch, but its title does not start with fix: or fix(scope):.

Only bug fixes should be cherry-picked to release branches. If this is a bug fix, please update the PR title to match the conventional commit format:

fix: description of the bug fix
fix(scope): description of the bug fix

If this is not a bug fix, it likely should not target a release branch.

@coderagents

coderagents Bot commented Sep 21, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Updates Needed

  • docs/ai-coder/agents/architecture.md (open) - Line 133 still states that chats which don't need workspace access, "answering questions, planning an approach, discussing architecture", "never provision or connect to a workspace." This PR's own docs/ai-coder/agents/index.md change contradicts it: "Any request, including planning or Q&A, can require a workspace if the agent lacks the capabilities or context to complete it." Reword the architecture sentence to say those chats don't provision a workspace when the conversation and available tools are sufficient.

The rest of the diff documents itself. The workspace-provisioning behavior change is covered by the backported edits to index.md, getting-started.md, tools/index.md, platform-controls/template-optimization.md, and tasks-to-chats-migration.md. The system-instruction, exclusive-tool retry, and no-workspace tool error changes have no page that enumerates that text, so they need nothing.

Note: the same sentence is stale on main, so this is drift the source PR (#29579) left behind rather than something this backport introduced. Fixing it on main and cherry-picking is fine.


Automated review via Coder Agents

@ibetitsmike
ibetitsmike merged commit b3cc116 into release/2.37 Sep 21, 2026
52 of 53 checks passed
@ibetitsmike
ibetitsmike deleted the mike/backport-system-instructions-2.37 branch September 21, 2026 16:13
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 21, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants