paperclipai/paperclip · error

Local filesystem/network confinement requires the Claude…

Error message

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

What it means

Engine-capability guard for the Claude local adapter: local filesystem/network confinement is implemented only in the Claude CLI engine, but the run's configuration resolves to (or explicitly pins) the ACP engine, which has no confinement support — so the run is rejected instead of running unconstrained by accident.

Solutions

  1. Use the Claude CLI engine for local filesystem/network confinement.
  2. Drop the confinement requirement when using ACP.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at packages/adapters/claude-local/src/server/acp.ts:96 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

type ClaudeAcpExecutor = (ctx: AdapterExecutionContext) => Promise<AdapterExecutionResult>;

function normalizeEngine(value: unknown): ClaudeEngineSelection {
  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);
  // Engine availability must never change the agent's execution or permission contract.
  if (selection.engine === "cli") return selection;
  const unavailable = (reason: string): ClaudeEngineSelection => ({
    ...selection,
    unavailableReason: `${reason} Repair the ACP setup, or explicitly set engine=cli to use the CLI engine.`,
  });
  const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
  const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
  if (filesystemScope || networkScope) {
    return unavailable("Local filesystem/network confinement requires the Claude CLI engine; ACP confinement is not supported.");
  }

  const reason = await claudeAcpUnavailableReason(input);
  return reason ? unavailable(reason) : selection;
}

function firstNonEmptyString(...values: unknown[]): string | undefined {
  for (const value of values) {
    if (typeof value !== "string") continue;

View on GitHub (pinned to 3f1d897a7c)