diff --git a/packages/core/test/plugin/provider/claude-agent/language-model/instruction-integration.test.ts b/packages/core/test/plugin/provider/claude-agent/language-model/instruction-integration.test.ts
new file mode 100644
index 000000000000..c88b586e1cc3
--- /dev/null
+++ b/packages/core/test/plugin/provider/claude-agent/language-model/instruction-integration.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test"
+import type { LanguageModelV3Prompt } from "@ai-sdk/provider"
+import type { ClaudeSessions } from "@opencode/core/plugin/provider/claude-agent/claude/sessions"
+import { ClaudeAgentLanguageModel } from "@opencode/core/plugin/provider/claude-agent/language-model/claude-agent-language-model"
+import { RequestKind } from "@opencode/core/plugin/provider/claude-agent/language-model/request-kind"
+
+const reminder = "\nrepro.state = B\n"
+
+const prompt = (): LanguageModelV3Prompt => [
+ { role: "system", content: "Base instruction" },
+ { role: "system", content: "Initial policy" },
+ { role: "user", content: [{ type: "text", text: "First question" }] },
+ { role: "assistant", content: [{ type: "text", text: "First answer" }] },
+ { role: "system", content: "repro.state = B" },
+ { role: "user", content: [{ type: "text", text: "What is the current state?" }] },
+]
+
+async function capture(input: { prompt: LanguageModelV3Prompt; headers?: Record }) {
+ const calls: ClaudeSessions.Request[] = []
+ const model = new ClaudeAgentLanguageModel.Model("claude-test", {
+ run: async (request) => {
+ calls.push(request)
+ },
+ })
+ const { stream } = await model.doStream(input)
+ const reader = stream.getReader()
+ while (!(await reader.read()).done) {
+ // Drain the stubbed stream so the asynchronous session call finishes.
+ }
+ expect(calls).toHaveLength(1)
+ return calls[0]!
+}
+
+describe("Claude Agent provider instruction updates", () => {
+ test("primary requests deliver the update to the session without changing the base system prompt", async () => {
+ const raw = prompt()
+ const original = JSON.stringify(raw)
+ const request = await capture({
+ prompt: raw,
+ headers: {
+ [RequestKind.HEADER]: "primary",
+ [RequestKind.SESSION_HEADER]: "existing-session",
+ },
+ })
+
+ expect(request.sessionID).toBe("existing-session")
+ expect(request.system).toMatchObject({ type: "preset", preset: "claude_code" })
+ expect(JSON.stringify(request.system)).not.toContain("repro.state = B")
+ expect(request.prompt.slice(0, 2)).toEqual(raw.slice(0, 2))
+ expect(request.prompt[4]).toEqual({ role: "user", content: [{ type: "text", text: reminder }] })
+ expect(request.prompt[5]).toEqual(raw[5])
+ expect(JSON.stringify(raw)).toBe(original)
+ })
+
+ test("utility requests use only leading system messages and deliver the update once in the prompt", async () => {
+ const request = await capture({ prompt: prompt() })
+
+ expect(request.system).toBe("Base instruction\n\nInitial policy")
+ expect(request.prompt[4]).toEqual({ role: "user", content: [{ type: "text", text: reminder }] })
+ expect(request.prompt.filter((message) => message.role === "system")).toHaveLength(2)
+ expect(JSON.stringify(request.prompt).match(/repro\.state = B/g)).toHaveLength(1)
+ expect(request.sessionID).toBeUndefined()
+ })
+})
diff --git a/packages/core/test/plugin/provider/claude-agent/sync/instruction-history.test.ts b/packages/core/test/plugin/provider/claude-agent/sync/instruction-history.test.ts
new file mode 100644
index 000000000000..83b6beb4d75d
--- /dev/null
+++ b/packages/core/test/plugin/provider/claude-agent/sync/instruction-history.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test"
+import type { LanguageModelV3Prompt } from "@ai-sdk/provider"
+import { ConvertToClaudeMessage } from "@opencode/core/plugin/provider/claude-agent/language-model/convert-to-claude-message"
+import { Fingerprint } from "@opencode/core/plugin/provider/claude-agent/sync/fingerprint"
+import { SyncDecision } from "@opencode/core/plugin/provider/claude-agent/sync/decide"
+import { CatchUp } from "@opencode/core/plugin/provider/claude-agent/sync/catch-up"
+import { Checkpoints } from "@opencode/core/plugin/provider/claude-agent/sync/checkpoints"
+
+// The provider lifts instruction updates before session reconciliation.
+// Exercise recovery and checkpoint behavior using the normalized prompt.
+const user = (text: string): LanguageModelV3Prompt[number] => ({ role: "user", content: [{ type: "text", text }] })
+const assistant = (text: string): LanguageModelV3Prompt[number] => ({
+ role: "assistant",
+ content: [{ type: "text", text }],
+})
+const update = (value: string): LanguageModelV3Prompt[number] => ({
+ role: "system",
+ content: `Instructions updated: repro.state\nrepro.state = ${value}`,
+})
+const lift = (raw: LanguageModelV3Prompt) => ConvertToClaudeMessage.liftInstructionUpdates(raw)
+const past: LanguageModelV3Prompt = [user("First marker"), assistant("COPPER-OTTER")]
+const content = (prompt: LanguageModelV3Prompt, start = 0) =>
+ CatchUp.content(prompt, start)
+ .filter((block) => block.type === "text")
+ .map((block) => block.text)
+ .join("\n")
+
+describe("#62916 instruction update recovery regressions", () => {
+ test("detects edits to a previously synchronized instruction", () => {
+ const previous = lift([...past, update("B"), user("Current state?")])
+ const saved = { claudeSessionID: "claude-a", history: Fingerprint.groups(previous) }
+ const changed = lift([...past, update("C"), user("Current state?")])
+ expect(SyncDecision.decide(changed, saved)).toEqual({ kind: "changed", start: 0 })
+ })
+
+ test("recovers an update from legacy session history", () => {
+ const question = user("What is the current state?")
+ // The saved checkpoints predate the fix, so they omit the update entirely.
+ const legacy = {
+ claudeSessionID: "claude-legacy",
+ history: Fingerprint.groups([...past, question]).map((group, index) => ({
+ hash: group.hash,
+ ...(index < 2 ? { claudeMessageID: `checkpoint-${index}` } : {}),
+ })),
+ }
+ const prompt = lift([...past, update("B"), question])
+ expect(SyncDecision.decide(prompt, legacy)).toEqual({ kind: "changed", start: 0 })
+ const boundary = SyncDecision.boundary(prompt, legacy)
+ expect(boundary?.messageID).toBe("checkpoint-1")
+ expect(boundary?.start).toBe(2)
+ expect(content(prompt, boundary!.start)).toContain("repro.state = B")
+ expect(content(prompt, boundary!.start)).toContain("What is the current state?")
+ })
+
+ test("tracks an update after a reasoning-only assistant message", () => {
+ const raw: LanguageModelV3Prompt = [
+ { role: "system", content: "Initial instructions" },
+ { role: "assistant", content: [{ type: "reasoning", text: "Private reasoning" }] },
+ update("B"),
+ user("Current state?"),
+ ]
+ const prompt = lift(raw)
+ expect(content(prompt)).toContain("repro.state = B")
+ expect(content(prompt)).not.toContain("Private reasoning")
+ expect(Fingerprint.groups(prompt)[0]?.start).toBe(2)
+ })
+
+ test("preserves checkpoint IDs and resumes after the answered update", () => {
+ const raw: LanguageModelV3Prompt = [...past, update("B"), user("Current state?")]
+ const prompt = lift(raw)
+ const previous = {
+ claudeSessionID: "claude-a",
+ history: Fingerprint.groups(past).map((group, index) => ({
+ hash: group.hash,
+ claudeMessageID: `previous-${index}`,
+ })),
+ }
+ const history = Checkpoints.build({
+ prompt,
+ previous,
+ userID: "current-user",
+ reply: [{ type: "text", text: "State B" }],
+ messageID: "reply-b",
+ toolMessages: new Map(),
+ })
+ // The connector may group the update with the next user input.
+ // Check the semantics of checkpoint IDs rather than the number of groups.
+ expect(history[0]?.claudeMessageID).toBe("previous-0")
+ expect(history[1]?.claudeMessageID).toBe("previous-1")
+ expect(history.at(-2)?.claudeMessageID).toBe("current-user")
+ expect(history.at(-1)?.claudeMessageID).toBe("reply-b")
+ const next = lift([...raw, assistant("State B"), user("Next question")])
+ expect(SyncDecision.decide(next, { claudeSessionID: "claude-a", history })).toEqual({
+ kind: "continue",
+ start: 5,
+ })
+ })
+})