claude-agent-acp/src/permissions/presentation.ts

import type { RequestPermissionRequest, ToolCallContent } from "@agentclientprotocol/sdk/unstable";
import { AIR_PERMISSION_KEY, withAirMeta } from "../air-extension.js";
import { ClientCapabilities } from "../tool-calls/client-capabilities.js";
import { AcpToolCallRenderer } from "../tool-calls/renderer.js";

/**
 * A permission request as the agent builds it. For a v2 client it also
 * carries the heading and the explanation of the prompt, which ACP v2 sends as
 * the request's `title` and `description`. v1 has no field for them; AIR gets
 * them in `_meta`.
 */
export type AcpPermissionRequest = RequestPermissionRequest & {
  /** The heading of the prompt. It is not the title of the tool call. */
  title?: string;
  /** Why the permission is asked. */
  description?: string;
};

export interface ClaudePermissionPresentationInput {
  toolName: string;
  input: Record<string, unknown>;
  toolUseID: string;
  cwd?: string;
  capabilities?: ClientCapabilities;
  /** The exact patch of the change to approve, for a negotiated `diffPatch` client or a v2 client. */
  previewContent?: ToolCallContent[];
  blockedPath?: string;
  title?: string;
  displayName?: string;
  description?: string;
  decisionReason?: string;
  defaultToNo?: boolean;
}

function humanText(value: unknown, maxLength: number, singleLine = false): string | undefined {
  if (typeof value !== "string") return undefined;
  const withoutControls = Array.from(value)
    .filter((character) => {
      const code = character.charCodeAt(0);
      return !(
        code <= 0x08 ||
        code === 0x0b ||
        code === 0x0c ||
        (code >= 0x0e && code <= 0x1f) ||
        code === 0x7f
      );
    })
    .join("");
  const normalized = singleLine
    ? withoutControls.replace(/\s+/gu, " ").trim()
    : withoutControls.trim();
  return normalized && normalized.length <= maxLength ? normalized : undefined;
}

function compactText(value: unknown): string | undefined {
  return humanText(value, 160, true);
}

/**
 * The permission request presentation.
 *
 * The request `toolCall` carries `toolCallId`, `title`, and `rawInput`. The
 * adapter emits the `tool_call` before the request, so the client already
 * holds the rest. The request adds only what it shows new: the exact preview
 * patch, and the blocked path when the tool call has no such location.
 *
 * The heading and the explanation of the prompt go to AIR in `_meta`, and to a
 * v2 client as `title` and `description`.
 */
export function buildClaudePermissionPresentation(
  value: ClaudePermissionPresentationInput,
): Pick<AcpPermissionRequest, "toolCall" | "_meta" | "title" | "description"> {
  const capabilities = value.capabilities ?? new ClientCapabilities();
  const renderer = new AcpToolCallRenderer(capabilities);
  const toolUse = { id: value.toolUseID, name: value.toolName, input: value.input };
  const facts = renderer.facts(toolUse, value.cwd);
  const host =
    value.toolName === "SandboxNetworkAccess" ? compactText(value.input.host) : undefined;
  const isComputerUse = value.toolName.startsWith("mcp__computer-use__");
  const subjectTitle = host ?? (isComputerUse ? compactText(value.displayName) : undefined);
  // Reuse the exact standard tool-call heading as the permission heading so
  // the approval never maintains a second, divergent name for the operation.
  // decisionReason is temporarily exposed as the permission description so
  // its actual SDK values can be inspected; it remains diagnostic policy text.
  const toolCallTitle = subjectTitle ?? facts.title;
  const permissionTitle = value.toolName === "ExitPlanMode" ? "Ready to code?" : toolCallTitle;
  // Shell titles are executable input: compacting whitespace changes quoted
  // arguments and comment boundaries, and length limits can hide the command.
  const title =
    value.toolName === "Bash" || value.toolName === "PowerShell"
      ? permissionTitle
      : (humanText(permissionTitle, 4_000, true) ?? "Use tool?");
  const decisionReason = humanText(value.decisionReason, 4_000);
  const description = decisionReason ? `Reason: ${decisionReason}` : undefined;
  const blockedPath = humanText(value.blockedPath, 4_096, true);
  const extraLocations =
    blockedPath && !(facts.locations ?? []).some((location) => location.path === blockedPath)
      ? [{ path: blockedPath }]
      : undefined;
  return {
    toolCall: renderer.permissionToolCall(toolUse, {
      cwd: value.cwd,
      title: toolCallTitle,
      previewContent: value.previewContent,
      extraLocations,
      // The upstream request shows the input of a network or computer-use
      // request that has no content of its own.
      fallbackContent:
        host || isComputerUse
          ? [
              {
                type: "content" as const,
                content: {
                  type: "text" as const,
                  text: `\`\`\`json\n${JSON.stringify(value.input, null, 2)}\n\`\`\``,
                },
              },
            ]
          : undefined,
    }),
    // Only AIR gets the permission presentation.
    ...(title && capabilities.air.client
      ? { _meta: airPermissionMeta({ title, description, defaultToNo: value.defaultToNo }) }
      : {}),
    ...(capabilities.v2 ? { title, ...(description ? { description } : {}) } : {}),
  };
}

/**
 * The `_meta.jetbrains.air.permission` of a permission request, from the
 * heading and explanation that {@link buildClaudePermissionPresentation}
 * built. The v2 core adds it for an AIR client, whose tool calls it
 * renders without the AIR tool call contract.
 */
export function airPermissionMeta({
  title,
  description,
  defaultToNo,
}: {
  title: string;
  description?: string;
  defaultToNo?: boolean;
}): Record<string, unknown> {
  return withAirMeta(undefined, AIR_PERMISSION_KEY, {
    version: 1,
    title,
    ...(description ? { description } : {}),
    // The CLI's own hint, forwarded so a client that can pre-select an
    // option keeps the decline focused; the option order already leads with
    // the reject options when this is set.
    ...(defaultToNo === true ? { defaultToNo: true } : {}),
  });
}

/**
 * The `_meta.claudeCode` of a permission request's tool call: which MCP
 * server serves an `mcp__*` tool and where its definition came from
 * (`mcpServer`, SDK 0.3.274+), so a client can key trust on `source`, and,
 * for clients other than AIR, the tool name and the Agent or Task call of a
 * subagent's request. Undefined when there is nothing to add.
 */
export function permissionToolCallMeta({
  toolName,
  parentToolUseId,
  mcpServer,
  airClient,
}: {
  toolName: string;
  parentToolUseId: string | undefined;
  mcpServer: { name: string; source: string } | undefined;
  airClient: boolean;
}): { claudeCode: Record<string, unknown> } | undefined {
  if (!mcpServer && !(parentToolUseId && !airClient)) return undefined;
  // The name is the config key as authored: untrusted text, so it rides
  // `_meta` rather than the title.
  return {
    claudeCode: {
      ...(airClient ? {} : { toolName }),
      ...(parentToolUseId && !airClient ? { parentToolUseId } : {}),
      ...(mcpServer ? { mcpServer: { name: mcpServer.name, source: mcpServer.source } } : {}),
    },
  };
}