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(claude-local): resume sessions across agent file working copies (#15437)
Dotta1ead554bd18a
diff --git a/doc/agent-files.md b/doc/agent-files.mdindex a4154551f1..f037cb2551 100644--- a/doc/agent-files.md+++ b/doc/agent-files.md@@ -37,6 +37,12 @@ workspace: their independent agent copy therefore lives under the excluded`.paperclip-runtime/agent-files/<agent>/<run>/` area. It is not included in taskworkspace sync, Git staging, or task deliverables.+Claude CLI runs keep the working-copy location in each run's prompt, separate+from the cached system instructions. A new copy path alone does not reset the+task session. Each turn names the current copy for relative file references;+instruction or enabled skill content changes still invalidate the prompt bundle.+Sessions saved with the older path-bearing bundle start fresh once after upgrade.+Regular files (including binary bytes) and directories are supported, up to100,000 entries (files and folders), 256 MiB per file and 2 GiB total. Symlinks,hardlinks, and specialdiff --git a/packages/adapters/claude-local/src/server/execute.remote.test.ts b/packages/adapters/claude-local/src/server/execute.remote.test.tsindex 9ccc3ef77e..cbb6ed5501 100644--- a/packages/adapters/claude-local/src/server/execute.remote.test.ts+++ b/packages/adapters/claude-local/src/server/execute.remote.test.ts@@ -285,6 +285,34 @@ describe("claude remote execution", () => {expect(call?.[2]).not.toContain("--resume");});+ it("explains a remote-to-local session reset even when the cwd matches", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-local-reset-"));+ cleanupDirs.push(rootDir);+ vi.stubEnv("PAPERCLIP_HOME", rootDir);+ const onLog = vi.fn(async () => {});++ await execute({+ runId: "run-local-reset",+ agent: { id: "agent-1", companyId: "company-1", name: "Claude Coder", adapterType: "claude_local", adapterConfig: {} },+ runtime: {+ sessionId: "12345678-1234-4abc-9def-123456789012",+ sessionParams: {+ cwd: rootDir,+ remoteExecution: { transport: "ssh", host: "remote.test", port: 22, username: "fixture", remoteCwd: rootDir },+ },+ sessionDisplayId: null,+ taskKey: null,+ },+ config: { engine: "cli", command: "claude", cwd: rootDir, paperclipRuntimeSkills: [] },+ context: {},+ onLog,+ });++ expect(runChildProcess.mock.calls[0]?.[2]).not.toContain("--resume");+ expect(onLog).toHaveBeenCalledWith("stdout", expect.stringContaining("does not match the current execution target"));+ expect(onLog).not.toHaveBeenCalledWith("stdout", expect.stringContaining("was saved for cwd"));+ });+it("resumes saved Claude sessions for remote SSH execution when the remote identity matches", async () => {const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-resume-match-"));cleanupDirs.push(rootDir);diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.tsindex ee1f3e35a7..de03c588c0 100644--- a/packages/adapters/claude-local/src/server/execute.ts+++ b/packages/adapters/claude-local/src/server/execute.ts@@ -499,19 +499,21 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecconst billingType = resolveClaudeBillingType(effectiveEnv);const claudeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);const desiredSkillNames = new Set(resolveClaudeDesiredSkillNames(config, claudeSkillEntries));- // When instructionsFilePath is configured, build a stable content-addressed- // file that includes both the file content and the path directive, so we only- // need --append-system-prompt-file (Claude CLI forbids using both flags together).+ // Keep per-run working-copy paths out of the content-addressed system prompt.+ // Resumed sessions retain that prompt, so refresh the location on every turn.let combinedInstructionsContents: string | null = null;+ let instructionsPathDirective = "";if (instructionsFilePath) {try {const instructionsContent = await fs.readFile(instructionsFilePath, "utf-8");- const pathDirective =- `\nThe above agent instructions were loaded from ${instructionsFilePath}. ` ++ instructionsPathDirective =+ `Agent instructions for this run were loaded from ${instructionsFilePath}. ` +`Resolve any relative file references from ${instructionsFileDir}. ` +`This base directory is authoritative for sibling instruction files such as ` +- `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`;- combinedInstructionsContents = instructionsContent + pathDirective;+ `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory. ` ++ `This location replaces any instruction file location from earlier turns.`;+ combinedInstructionsContents = instructionsContent ++ "\nUse the agent instruction file location supplied in the current run prompt to resolve relative file references.";} catch (err) {const reason = err instanceof Error ? err.message : String(err);await onLog(@@ -778,18 +780,20 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec? runtimeMcpServers.length === 0: runtimeMcpServerIdentity === runtimeMcpIdentity;const isValidUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(runtimeSessionId);+ const hasMatchingSessionCwd = claudeSessionCwdMatchesExecutionTarget({+ runtimeSessionCwd,+ effectiveExecutionCwd,+ executionTargetIsRemote,+ });+ const hasMatchingExecutionTarget = adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);const canResumeSession =runtimeSessionId.length > 0 &&isValidUuid &&hasMatchingPromptBundle &&// Each CLI invocation loads --mcp-config, including --resume invocations.// Refreshing tools does not invalidate the saved conversation.- claudeSessionCwdMatchesExecutionTarget({- runtimeSessionCwd,- effectiveExecutionCwd,- executionTargetIsRemote,- }) &&- adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);+ hasMatchingSessionCwd &&+ hasMatchingExecutionTarget;const sessionId = canResumeSession ? runtimeSessionId : null;if (runtimeSessionId && !isValidUuid) {await onLog(@@ -798,26 +802,20 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec);}if (- executionTargetIsRemote &&runtimeSessionId &&isValidUuid &&- !canResumeSession+ !hasMatchingExecutionTarget) {await onLog("stdout",- `[paperclip] Claude session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,+ `[paperclip] Claude session "${runtimeSessionId}" does not match the current execution target and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh session.\n`,);} else if (runtimeSessionId &&isValidUuid &&runtimeSessionCwd.length > 0 &&- path.resolve(runtimeSessionCwd) !== path.resolve(effectiveExecutionCwd)+ !hasMatchingSessionCwd) {- await onLog(- "stdout",- `[paperclip] Claude session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,- );- } else if (runtimeSessionId && isValidUuid && !canResumeSession) {await onLog("stdout",`[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,@@ -916,6 +914,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec: renderTemplate(promptTemplate, templateData);const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();const prompt = joinPromptSections([+ instructionsPathDirective,renderedBootstrapPrompt,selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),wakePrompt,@@ -944,7 +943,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec}if (attemptInstructionsFilePath && !resumeSessionId) {commandNotes.push(- `Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with path directive appended)`,+ `Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with current file location in the run prompt)`,);}if (runtimeMcpServers.length > 0) {diff --git a/server/src/__tests__/claude-local-execute.test.ts b/server/src/__tests__/claude-local-execute.test.tsindex b45af79f0a..adea792ca6 100644--- a/server/src/__tests__/claude-local-execute.test.ts+++ b/server/src/__tests__/claude-local-execute.test.ts@@ -685,8 +685,9 @@ describe("claude execute", () => {expect(captured[1]?.appendedSystemPromptFilePath).toContain("agent-instructions.md");expect(captured[1]?.appendedSystemPromptFilePath).not.toBe(instructionsFile);expect(captured[1]?.appendedSystemPromptFileContents).toContain("# Agent instructions");- expect(captured[1]?.appendedSystemPromptFileContents).toContain(- `The above agent instructions were loaded from ${instructionsFile}. ` ++ expect(captured[1]?.appendedSystemPromptFileContents).not.toContain(instructionsFile);+ for (const prompt of prompts) expect(prompt).toContain(+ `Agent instructions for this run were loaded from ${instructionsFile}. ` +`Resolve any relative file references from ${path.dirname(instructionsFile)}/. ` +`This base directory is authoritative for sibling instruction files such as ` +`./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`,@@ -1338,7 +1339,9 @@ describe("claude execute", () => {expect(capture1.addDir?.startsWith(expectedRoot)).toBe(true);expect(capture1.instructionsFilePath?.startsWith(expectedRoot)).toBe(true);expect(capture1.instructionsContents).toContain("You are managed instructions.");- expect(capture1.instructionsContents).toContain(`The above agent instructions were loaded from ${instructionsPath}.`);+ expect(capture1.instructionsContents).not.toContain(instructionsPath);+ expect(capture1.prompt).toContain(`Agent instructions for this run were loaded from ${instructionsPath}.`);+ expect(capture2.prompt).toContain(`Agent instructions for this run were loaded from ${instructionsPath}.`);expect(capture1.skillEntries).toContain("paperclip");expect(capture2.argv).toContain("--resume");expect(getFreshSessionHandoff).not.toHaveBeenCalled();@@ -1362,6 +1365,81 @@ describe("claude execute", () => {}});+ it("resumes across per-run instruction copies and refreshes their location", async () => {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-working-copy-"));+ const workspace = path.join(root, "workspace");+ const commandPath = path.join(root, "claude");+ const capturePath = path.join(root, "capture.json");+ const skillDir = path.join(root, "skill");+ await fs.mkdir(workspace, { recursive: true });+ await fs.mkdir(skillDir);+ await fs.writeFile(path.join(skillDir, "SKILL.md"), "First skill version.\n");+ await writeFakeClaudeCommand(commandPath);+ vi.stubEnv("PAPERCLIP_HOME", path.join(root, "paperclip-home"));+ vi.stubEnv("PAPERCLIP_INSTANCE_ID", "default");++ try {+ let sessionParams: Record<string, unknown> | null = null;+ let previousBundleKey: unknown;+ let previousInstructionsPath = "";+ for (const [index, change] of ["initial", "location", "instructions", "skill"].entries()) {+ const runId = `run-${index}`;+ const instructionsPath = path.join(root, "companies", "company-1", "agents", "agent-1",+ "file-sync", "runs", runId, "live", "AGENTS.md");+ await fs.mkdir(path.dirname(instructionsPath), { recursive: true });+ await fs.writeFile(instructionsPath, index < 2 ? "First instructions.\n" : "Changed instructions.\n");+ if (change === "skill") {+ await fs.writeFile(path.join(skillDir, "SKILL.md"), "Changed skill version.\n");+ }+ const logs: string[] = [];+ const result = await execute({+ runId,+ agent: { id: "agent-1", companyId: "company-1", name: "Test", adapterType: "claude_local", adapterConfig: { engine: "cli" } },+ runtime: { sessionId: null, sessionParams, sessionDisplayId: null, taskKey: "issue-1" },+ config: {+ engine: "cli",+ command: commandPath,+ cwd: workspace,+ instructionsFilePath: instructionsPath,+ paperclipRuntimeSkills: [{ key: "test-skill", runtimeName: "test-skill", source: skillDir }],+ paperclipSkillSync: { desiredSkills: ["test-skill"] },+ env: { PAPERCLIP_TEST_CAPTURE_PATH: capturePath, CLAUDE_CONFIG_DIR: path.join(root, "claude-config") },+ },+ context: { issueId: "issue-1" },+ onLog: async (_stream, chunk) => { logs.push(chunk); },+ });+ expect(result.exitCode).toBe(0);+ const capture = JSON.parse(await fs.readFile(capturePath, "utf8")) as CapturePayload;+ if (change === "location") {+ expect(capture.argv).toContain("--resume");+ expect(capture.argv).toContain("11111111-1111-4111-8111-111111111111");+ expect(capture.instructionsFilePath).toBeNull();+ expect(result.sessionParams?.promptBundleKey).toBe(previousBundleKey);+ } else {+ expect(capture.argv).not.toContain("--resume");+ expect(capture.instructionsContents).toContain(index < 2 ? "First instructions." : "Changed instructions.");+ expect(result.sessionParams?.promptBundleKey).not.toBe(previousBundleKey);+ if (index > 0) {+ expect(capture.instructionsContents).not.toContain(instructionsPath);+ expect(logs.join("")).toContain("was saved for prompt bundle");+ expect(logs.join("")).not.toContain("was saved for cwd");+ }+ }+ if (index > 0) {+ expect(capture.prompt).toContain(instructionsPath);+ expect(capture.prompt).toContain(`Resolve any relative file references from ${path.dirname(instructionsPath)}/.`);+ }+ if (previousInstructionsPath) expect(capture.prompt).not.toContain(previousInstructionsPath);+ sessionParams = sessionCodec.deserialize(sessionCodec.serialize(result.sessionParams ?? null));+ previousBundleKey = result.sessionParams?.promptBundleKey;+ previousInstructionsPath = instructionsPath;+ }+ } finally {+ vi.unstubAllEnvs();+ await fs.rm(root, { recursive: true, force: true });+ }+ });+it("starts a fresh Claude session when the stable prompt bundle changes", async () => {const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-reset-"));const workspace = path.join(root, "workspace");