mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Claude agents run through the Claude ACP bridge (`claude-agent-acp` 0.73.0), which Paperclip patches in `patches/` > - The bridge reads Claude Code's final result for each turn. If the result text contains "Please run /login", the bridge fails the turn as a sign-in failure > - That check does not look at `is_error`. A successful reply that quotes the CLI's sign-in hint also fails the turn > - Agents quote that hint when they report the output of a `claude` command that they ran. The work is done, but the run fails with "ACP agent reported a terminal access failure." > - Upstream fixed this in [agentclientprotocol/claude-agent-acp#1103](https://github.com/agentclientprotocol/claude-agent-acp/pull/1103) (commit [`6e97e07`](https://github.com/agentclientprotocol/claude-agent-acp/commit/6e97e071c581002b43d9556dbd1d1376ebf9516f), released in 0.81.1), "fix: gate login result text on error state" > - This pull request ports that upstream change into the 0.73.0 bridge patch > - The benefit is that a correct, finished run is not reported as a failed sign-in ## Linked Issues or Issue Description Upstream fix: [agentclientprotocol/claude-agent-acp#1103](https://github.com/agentclientprotocol/claude-agent-acp/pull/1103) (commit [`6e97e07`](https://github.com/agentclientprotocol/claude-agent-acp/commit/6e97e071c581002b43d9556dbd1d1376ebf9516f), released in 0.81.1). This pull request ports it. Refs #14089. That pull request fixes the same class of problem in the Claude CLI lane (`execute.ts`). This pull request fixes the ACP lane. Related: #14093 shows the same error text, but it has a different cause. This pull request does not fix #14093. **What happened?** An agent ran a script that calls the `claude` CLI without credentials. The CLI printed "Not logged in · Please run /login". The agent finished its task and quoted that text in its final reply. Claude Code ended the turn with a successful result (`is_error: false`). The bridge saw "Please run /login" in the result text and failed the turn with `auth_required`. Paperclip then failed the run with "ACP agent reported a terminal access failure." **Expected behavior** A successful result completes the turn. Only an error result with the sign-in hint is a sign-in failure. **Steps to reproduce** 1. Run a Claude agent on the ACP lane. 2. Make the model's final reply contain the text "Please run /login" (for example, quote the output of `claude -p hi` without credentials). 3. See that the run fails with "ACP agent reported a terminal access failure." The new test in this pull request does these steps against a local API stand-in. **Agent adapter(s) involved** `claude_local` on the ACP engine, and the Runner's ACPX Claude profile. Both use the same patched bridge. ## What Changed - `patches/@agentclientprotocol__claude-agent-acp@0.73.0.patch`: port [agentclientprotocol/claude-agent-acp#1103](https://github.com/agentclientprotocol/claude-agent-acp/pull/1103) (commit [`6e97e07`](https://github.com/agentclientprotocol/claude-agent-acp/commit/6e97e071c581002b43d9556dbd1d1376ebf9516f), released in 0.81.1). It has two parts, the same as upstream: - The `success` result check is now `message.is_error && message.result.includes("Please run /login")`. A successful result that quotes the sign-in hint no longer fails the turn. - The goal-command check also requires `message.is_error`. A `/goal` command whose successful result quotes the sign-in hint no longer rolls the session goal back. - Both patch comments name the upstream change. All other patch hunks are unchanged. - `packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-login-text.test.ts`: a new test. It runs the real bridge and the bundled Claude Code against a local API stand-in. The model's reply quotes the sign-in hint, and the test expects the turn to complete. ## Verification - Red: on `master`'s patch, the new test fails with `{"status":"failed","error":{"message":"ACP agent reported a terminal access failure."}}`. - Green: with this patch, the new test passes (`status: "completed"`, `stopReason: "end_turn"`). - I ran Claude Code 2.1.286 (the bundled version) with no credentials. Its real sign-in failure is a result with `is_error: true` and the text "Not logged in · Please run /login". The guard still catches it. The separate synthetic sign-in message check is unchanged. - The goal-command part has no new test here. The upstream change adds a test for it. The runner's `session-goals.test.ts` passes with the new patch. - `node --test scripts/acpx-patch-packaging.test.mjs`: 26 passed. - `node --test packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs`: 9 passed. - Runner real-bridge Claude tests (`acpx-runtime-adapter.claude-*.test.ts`, `acpx-runtime-adapter.test.ts`, `claude-scheduling-tools.claude-acp.test.ts`, `runner-tool-bridge.claude-*.test.ts`): 139 passed. - `claude-local` ACP tests (`acp.test.ts`, `acp.auth.test.ts`, `acp.quota.test.ts`): 95 passed. - `pnpm --filter @paperclipai/paperclip-runner run typecheck:typescript`: passed. - I did not commit `pnpm-lock.yaml`. The patch hash changes, and CI resolves the lockfile for this run. ## Risks - Low risk. The change adds one condition to each of two checks in the bridge patch. Both match the upstream change. - The bridge's `commandDigest` does not change, because the patch does not touch `dist/index.js`. Saved sessions are not reset. - A sign-in failure that Claude Code reports as a successful, non-error result is no longer caught by this check. Claude Code 2.1.286 reports sign-in failures as error results, and upstream uses the same rule. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, subagents) and extended thinking. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
272 lines
18 KiB
Diff
272 lines
18 KiB
Diff
diff --git a/dist/acp-agent.js b/dist/acp-agent.js
|
|
index 0214a50..a68121d 100644
|
|
--- a/dist/acp-agent.js
|
|
+++ b/dist/acp-agent.js
|
|
@@ -2490,11 +2490,88 @@ export class ClaudeAcpAgent {
|
|
break;
|
|
}
|
|
case "hook_started":
|
|
+ case "hook_response": {
|
|
+ // Paperclip patch: forward hook lifecycle so automatic hook
|
|
+ // decisions stay auditable. ACP has no hook update, so it rides
|
|
+ // on session_info_update `_meta` (no title/updatedAt change).
|
|
+ // Output is bounded; the runner derives the outcome.
|
|
+ const bounded = (value) => typeof value === "string" ? value.slice(0, 4000) : undefined;
|
|
+ // Read the hook's JSON decision from the full stdout before the
|
|
+ // display text is bounded, so a long reason cannot hide a block.
|
|
+ const hookDecision = (stdout) => {
|
|
+ if (typeof stdout !== "string" || !stdout.trim().startsWith("{")) return undefined;
|
|
+ let parsed;
|
|
+ try { parsed = JSON.parse(stdout); } catch { return undefined; }
|
|
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
|
|
+ const specific = parsed.hookSpecificOutput && typeof parsed.hookSpecificOutput === "object" ? parsed.hookSpecificOutput : {};
|
|
+ const decision = {
|
|
+ ...(typeof parsed.continue === "boolean" ? { continue: parsed.continue } : {}),
|
|
+ ...(typeof parsed.stopReason === "string" ? { stopReason: bounded(parsed.stopReason) } : {}),
|
|
+ ...(typeof parsed.decision === "string" ? { decision: bounded(parsed.decision) } : {}),
|
|
+ ...(typeof parsed.reason === "string" ? { reason: bounded(parsed.reason) } : {}),
|
|
+ ...(typeof parsed.systemMessage === "string" ? { systemMessage: bounded(parsed.systemMessage) } : {}),
|
|
+ ...(typeof specific.permissionDecision === "string" ? { permissionDecision: bounded(specific.permissionDecision) } : {}),
|
|
+ ...(typeof specific.permissionDecisionReason === "string" ? { permissionDecisionReason: bounded(specific.permissionDecisionReason) } : {}),
|
|
+ ...(typeof specific.additionalContext === "string" ? { additionalContext: bounded(specific.additionalContext) } : {}),
|
|
+ };
|
|
+ return Object.keys(decision).length > 0 ? decision : undefined;
|
|
+ };
|
|
+ await sendUpdate({
|
|
+ sessionId: message.session_id,
|
|
+ update: {
|
|
+ sessionUpdate: "session_info_update",
|
|
+ _meta: {
|
|
+ claudeCode: {
|
|
+ hook: {
|
|
+ phase: message.subtype === "hook_started" ? "started" : "completed",
|
|
+ hookId: message.hook_id,
|
|
+ hookName: message.hook_name,
|
|
+ hookEvent: message.hook_event,
|
|
+ ...(message.subtype === "hook_response" ? {
|
|
+ outcome: message.outcome,
|
|
+ ...(typeof message.exit_code === "number" ? { exitCode: message.exit_code } : {}),
|
|
+ output: bounded(message.output),
|
|
+ stdout: bounded(message.stdout),
|
|
+ stderr: bounded(message.stderr),
|
|
+ decision: hookDecision(message.stdout),
|
|
+ } : {}),
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ });
|
|
+ break;
|
|
+ }
|
|
case "hook_progress":
|
|
- case "hook_response":
|
|
case "files_persisted":
|
|
break;
|
|
- case "task_progress":
|
|
+ case "task_progress": {
|
|
+ // Paperclip: a subagent's progress summary (SDK option
|
|
+ // agentProgressSummaries) has no ACP home while native
|
|
+ // subagent sessions are off. Attach it to the spawning
|
|
+ // Agent/Task tool call so the client can show it there.
|
|
+ const progressTask = session.liveBackgroundTasks.get(message.task_id);
|
|
+ if (process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT === "1" &&
|
|
+ progressTask?.isSubagent &&
|
|
+ progressTask.parentToolUseId &&
|
|
+ (message.summary || message.description)) {
|
|
+ await sendUpdate({
|
|
+ sessionId: message.session_id,
|
|
+ update: {
|
|
+ sessionUpdate: "tool_call_update",
|
|
+ toolCallId: progressTask.parentToolUseId,
|
|
+ _meta: {
|
|
+ claudeCode: {
|
|
+ subagentProgress: {
|
|
+ ...(message.summary ? { summary: String(message.summary).slice(0, 2000) } : {}),
|
|
+ ...(message.description ? { description: String(message.description).slice(0, 2000) } : {}),
|
|
+ ...(message.last_tool_name ? { lastToolName: String(message.last_tool_name).slice(0, 160) } : {}),
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ });
|
|
+ }
|
|
await asyncTasks.taskProgress({
|
|
task_id: message.task_id,
|
|
description: message.description,
|
|
@@ -2503,6 +2580,7 @@ export class ClaudeAcpAgent {
|
|
usage: message.usage,
|
|
});
|
|
break;
|
|
+ }
|
|
case "task_started":
|
|
// For subagent tasks `task_id` is the subagent's agent id (the
|
|
// SDK keys its task registry by agent id) and `tool_use_id` is
|
|
@@ -2550,6 +2628,7 @@ export class ClaudeAcpAgent {
|
|
case "task_notification":
|
|
// The task settled — no further tool calls can originate
|
|
// from it, so its registry entry can be dropped.
|
|
+ await this.paperclipForwardSubagentState(session, message.session_id, message.task_id, message.tool_use_id ?? null, message.status, message.summary, sendUpdate);
|
|
await subagents.finishTask(message.task_id, message.status, sendUpdate, message.tool_use_id);
|
|
await asyncTasks.taskNotification({
|
|
task_id: message.task_id,
|
|
@@ -2571,6 +2650,7 @@ export class ClaudeAcpAgent {
|
|
if (message.patch.status === "completed" ||
|
|
message.patch.status === "failed" ||
|
|
message.patch.status === "killed") {
|
|
+ await this.paperclipForwardSubagentState(session, message.session_id, message.task_id, undefined, message.patch.status, undefined, sendUpdate);
|
|
await subagents.finishTask(message.task_id, message.patch.status, sendUpdate);
|
|
session.liveBackgroundTasks.delete(message.task_id);
|
|
}
|
|
@@ -2794,7 +2874,9 @@ export class ClaudeAcpAgent {
|
|
session.pendingGoalUpdate = undefined;
|
|
const goalCommandFailed = message.is_error ||
|
|
message.stop_reason === "refusal" ||
|
|
- ("result" in message && message.result.includes("Please run /login"));
|
|
+ ("result" in message &&
|
|
+ message.is_error &&
|
|
+ message.result.includes("Please run /login"));
|
|
if (goalCommandFailed) {
|
|
await this.publishGoal(params.sessionId, pendingGoalUpdate.previous ?? null);
|
|
}
|
|
@@ -2922,9 +3004,19 @@ export class ClaudeAcpAgent {
|
|
amount: message.total_cost_usd,
|
|
currency: "USD",
|
|
},
|
|
- ...(message.origin && {
|
|
- _meta: { "_claude/origin": message.origin },
|
|
- }),
|
|
+ _meta: {
|
|
+ ...(message.origin && { "_claude/origin": message.origin }),
|
|
+ // ACP's core Usage shape exposes context occupancy and
|
|
+ // cost, but not the billable input/output split. Keep the
|
|
+ // SDK's bounded aggregate in extension metadata so ACPX can
|
|
+ // normalize it without persisting a raw provider message.
|
|
+ usage: {
|
|
+ input_tokens: message.usage.input_tokens,
|
|
+ output_tokens: message.usage.output_tokens,
|
|
+ cache_read_input_tokens: message.usage.cache_read_input_tokens,
|
|
+ cache_creation_input_tokens: message.usage.cache_creation_input_tokens,
|
|
+ },
|
|
+ },
|
|
},
|
|
});
|
|
}
|
|
@@ -3081,7 +3173,7 @@ export class ClaudeAcpAgent {
|
|
}
|
|
switch (message.subtype) {
|
|
case "success": {
|
|
- if (message.result.includes("Please run /login")) {
|
|
+ if (message.is_error && message.result.includes("Please run /login")) {
|
|
await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), message.result);
|
|
break;
|
|
}
|
|
@@ -4506,6 +4598,48 @@ export class ClaudeAcpAgent {
|
|
* `$/cancel_request`, and our local abort race settles even if the client
|
|
* ignores it. A `cancelled` outcome, request rejection, and local abort all
|
|
* surface the same "Tool use aborted" the callers already expect. */
|
|
+ /**
|
|
+ * Paperclip: an async subagent's Agent/Task tool call completes as soon as
|
|
+ * the subagent launches. With native subagent sessions off, report the
|
|
+ * subagent's own terminal state and summary on that tool call so the
|
|
+ * client can settle its subagent card. Sent once per task.
|
|
+ */
|
|
+ async paperclipForwardSubagentState(session, sessionId, taskId, toolUseId, status, summary, sendUpdate) {
|
|
+ if (process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT !== "1")
|
|
+ return;
|
|
+ // The terminal task_updated branch drops the live registry entry
|
|
+ // before task_notification arrives, so remember subagent parents here.
|
|
+ const parents = (session.paperclipSubagentParents ??= new Map());
|
|
+ const task = session.liveBackgroundTasks.get(taskId);
|
|
+ if (task?.isSubagent && task.parentToolUseId)
|
|
+ parents.set(taskId, task.parentToolUseId);
|
|
+ const parentToolUseId = parents.get(taskId) ?? (task?.isSubagent ? toolUseId : undefined);
|
|
+ if (!parentToolUseId)
|
|
+ return;
|
|
+ // The terminal task_updated patch can precede task_notification, which
|
|
+ // alone carries the summary; dedupe only the notification.
|
|
+ const forwarded = (session.paperclipForwardedSubagentStates ??= new Set());
|
|
+ if (forwarded.has(taskId))
|
|
+ return;
|
|
+ if (toolUseId !== undefined || summary)
|
|
+ forwarded.add(taskId);
|
|
+ await sendUpdate({
|
|
+ sessionId,
|
|
+ update: {
|
|
+ sessionUpdate: "tool_call_update",
|
|
+ toolCallId: parentToolUseId,
|
|
+ _meta: {
|
|
+ claudeCode: {
|
|
+ subagentState: {
|
|
+ status: String(status ?? "completed").slice(0, 40),
|
|
+ // One character past the display bound lets the client mark a cut.
|
|
+ ...(summary ? { summary: String(summary).slice(0, 4001) } : {}),
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ },
|
|
+ });
|
|
+ }
|
|
async requestPermissionFromClient(params, toolName, signal, parentToolUseId, ownerSessionId = params.sessionId) {
|
|
if (signal.aborted)
|
|
throw new Error("Tool use aborted");
|
|
@@ -5311,14 +5445,24 @@ export class ClaudeAcpAgent {
|
|
settingSources: ["user", "project", "local"],
|
|
...(thinking !== undefined && { thinking }),
|
|
...userProvidedOptions,
|
|
+ // Paperclip Runner owns the complete session context. Its isolated
|
|
+ // user root contains only assigned skills; project/local settings
|
|
+ // would reintroduce host prompts, plugins, skills, and MCP servers.
|
|
+ ...(process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT === "1" && { settingSources: ["user"] }),
|
|
+ // Subagent progress summaries (~30s) feed the task chat's subagent card.
|
|
+ ...(process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT === "1" && { agentProgressSummaries: true }),
|
|
...(settings && { settings }),
|
|
env,
|
|
// Override certain fields that must be controlled by ACP
|
|
cwd: params.cwd,
|
|
includePartialMessages: true,
|
|
+ // Paperclip patch: emit hook_started/hook_response for every hook event.
|
|
+ includeHookEvents: true,
|
|
forwardSubagentText,
|
|
mcpServers: {
|
|
- ...(userProvidedOptions?.mcpServers || {}),
|
|
+ ...(process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT === "1"
|
|
+ ? {}
|
|
+ : (userProvidedOptions?.mcpServers || {})),
|
|
...mcpServers,
|
|
...(fileChangeAuditSupport
|
|
? { [FILE_CHANGE_AUDIT_SERVER_NAME]: fileChangeAuditSupport.mcpServer }
|
|
@@ -5329,6 +5473,16 @@ export class ClaudeAcpAgent {
|
|
allowDangerouslySkipPermissions: ALLOW_BYPASS,
|
|
permissionMode: initialPermissionMode,
|
|
canUseTool: this.canUseTool(sessionId),
|
|
+ // The runner pins this actual MCP endpoint before provider launch.
|
|
+ // Exempt only task delivery/control tools at the SDK dispatch boundary,
|
|
+ // not arbitrary provider permission metadata or MCP name prefixes.
|
|
+ ...(process.env.PAPERCLIP_ACPX_ISOLATED_CONTEXT === "1" && {
|
|
+ allowedTools: mcpServers.paperclip?.type === "http"
|
|
+ && mcpServers.paperclip.url === process.env.PAPERCLIP_ACPX_TASK_TOOL_BRIDGE_URL
|
|
+ ? ["paperclip_finish", "paperclip_block", "read_current_wake_comments", "request_human_input"]
|
|
+ .map((tool) => `mcp__paperclip__${tool}`)
|
|
+ : [],
|
|
+ }),
|
|
// Forward MCP elicitation requests onto ACP elicitation. Only attached
|
|
// when the client advertised support, so non-supporting clients keep the
|
|
// SDK's default (auto-decline) behavior. (AskUserQuestion is handled in
|
|
diff --git a/dist/settings.js b/dist/settings.js
|
|
index fff1f03..2d98307 100644
|
|
--- a/dist/settings.js
|
|
+++ b/dist/settings.js
|
|
@@ -88,6 +88,12 @@ export class SettingsManager {
|
|
async loadAllSettings() {
|
|
try {
|
|
const resolved = await resolveSettings({ cwd: this.cwd });
|
|
+ const userPath = resolved.sources.find((entry) => entry.source === "user")?.path;
|
|
+ for (const entry of resolved.sources) {
|
|
+ if (userPath && entry.source === "project" && entry.path === userPath) {
|
|
+ entry.source = "user";
|
|
+ }
|
|
+ }
|
|
this.effective = filterEscalatingDefaultMode(resolved);
|
|
}
|
|
catch (error) {
|