paperclipai/paperclip · error · Error

Local filesystem/network confinement requires the Claude CLI

Error message

Local filesystem/network confinement requires the Claude CLI engine; ACP confinement is not supported.

What it means

Thrown by resolveClaudeExecutionEngineForRun when the adapter config explicitly sets engine='acp' AND a local filesystemScope or networkScope confinement is also configured. ACP (the agent client protocol lane) cannot enforce spawn-level sandboxing, so requesting confinement under an explicitly-chosen ACP engine is an unsatisfiable combination; the function refuses instead of silently ignoring the confinement request.

Source

Thrown at packages/adapters/claude-local/src/server/acp.ts:84

  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
  if (raw === "acp") return { engine: "acp", explicit: true };
  if (raw === "cli") return { engine: "cli", explicit: true };
  return { engine: "acp", explicit: false };
}

export function resolveClaudeExecutionEngine(config: Record<string, unknown>): ClaudeEngineSelection {
  return normalizeEngine(config.engine);
}

export async function resolveClaudeExecutionEngineForRun(
  input: ClaudeEngineResolutionInput,
): Promise<ClaudeEngineSelection> {
  const selection = normalizeEngine(input.config.engine);
  const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
  const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
  if (filesystemScope || networkScope) {
    if (selection.explicit && selection.engine === "acp") {
      throw new Error("Local filesystem/network confinement requires the Claude CLI engine; ACP confinement is not supported.");
    }
    return {
      engine: "cli",
      explicit: selection.explicit,
      ...(!selection.explicit
        ? { fallbackReason: "Local filesystem/network scope requires spawn-level confinement in the CLI lane." }
        : {}),
    };
  }
  if (selection.explicit || selection.engine !== "acp") return selection;

  const fallbackReason = await defaultClaudeAcpFallbackReason(input);
  if (!fallbackReason) return selection;
  return { engine: "cli", explicit: false, fallbackReason };
}

export function formatClaudeAcpFallbackMessage(reason: string): string {
  return `[paperclip] Claude ACP default unavailable; falling back to Claude CLI. ${reason} Set engine=acp to require ACP or engine=cli to silence this fallback.\n`;

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Drop engine='acp' (leave unset) so the resolver auto-falls back to CLI with a fallbackReason, preserving confinement.
2. Or set engine='cli' explicitly to use the CLI lane that supports spawn-level confinement.
3. If ACP is required, remove filesystemScope and networkScope from the config (accept no local confinement).

Example fix

// before
config = { engine: "acp", filesystemScope: "workspace" };
// after
config = { engine: "cli", filesystemScope: "workspace" };

const hasConfinement =
  parseLocalProcessFilesystemScope(config.filesystemScope) ||
  parseLocalProcessNetworkScope(config.networkScope);
if (config.engine === "acp" && hasConfinement) {
  // pick one: confinement -> use cli; or acp -> drop confinement
  config.engine = "cli";
}

When it happens

Trigger: Adapter config with { engine: 'acp', filesystemScope: 'workspace' } or { engine: 'acp', networkScope: <scope> }. normalizeEngine marks engine explicit=true, parseLocalProcessFilesystemScope/NetworkScope return non-null, and the explicit-acp branch throws.

Common situations: An operator hardening a Claude run with network/filesystem confinement while also pinning engine=acp for performance; a config template that sets both without realizing ACP can't sandbox; upgrading a config that previously relied on implicit fallback.

Related errors

• In-place workspace realization requires the Codex CLI engine
• Local filesystem/network confinement requires the Codex CLI
• prepareSandboxManagedRuntime requires a client that exposes
• Command not found in PATH: "${command}"
• Local process confinement requires Bubblewrap, but "${reques

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/0d3f625f708922c0. Report an issue: GitHub.