vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

ACP permission mapping for ${JSON.stringify(permissionMode)}

Error message

ACP permission mapping for ${JSON.stringify(permissionMode)} requires session mode ${JSON.stringify(target.modeId)}, but the agent advertised ${formatChoices({ values: availableModeIds })}.

What it means

When the permission mode maps to an ACP 'session-mode' target, validateTarget checks that the modeId the harness wants to switch to was advertised by the agent in the session's modes.availableModes. If the agent did not advertise that mode id, the harness throws this unsupported error listing the modes the agent actually offers.

Source

Thrown at packages/harness-acp/src/v1/bridge/permission-mode.ts:89

  });
}

function validateTarget({
  target,
  permissionMode,
  sessionConfiguration,
  harnessId,
}: {
  target: ACPPermissionModeTarget;
  permissionMode: HarnessV1PermissionMode;
  sessionConfiguration: ACPSessionConfiguration;
  harnessId: string;
}): void {
  if (target.type === 'session-mode') {
    const availableModeIds =
      sessionConfiguration.modes?.availableModes.map(mode => mode.id) ?? [];
    if (!availableModeIds.includes(target.modeId)) {
      throw unsupported({
        harnessId,
        message:
          `ACP permission mapping for ${JSON.stringify(permissionMode)} requires session mode ` +
          `${JSON.stringify(target.modeId)}, but the agent advertised ` +
          `${formatChoices({ values: availableModeIds })}.`,
      });
    }
    return;
  }

  const configOption = sessionConfiguration.configOptions?.find(
    option => option.id === target.configId,
  );
  if (configOption == null) {
    const availableConfigIds =
      sessionConfiguration.configOptions?.map(option => option.id) ?? [];
    throw unsupported({
      harnessId,

View on GitHub (pinned to 69428b1f8b)

Solutions

Pick a permissionMode whose mapped modeId appears in the agent's advertised availableModes (the error lists them).
Update the harness's permissionModeMapping to use one of the advertised mode ids.
Upgrade or fix the agent so it advertises the expected session mode.

Example fix

// before (mapping points at an unadvertised mode)
permissionModeMapping: { default: { type: 'session-mode', modeId: 'acceptEdits' } }
// after (use an id the agent advertised)
permissionModeMapping: { default: { type: 'session-mode', modeId: 'accept-edits' } }

Defensive patterns

Strategy: validation

Validate before calling

const advertised = (sessionConfiguration.modes?.availableModes ?? []).map(m => m.id);
if (!advertised.includes(target.modeId)) {
  throw new Error(`modeId ${target.modeId} not advertised; pick one of ${advertised.join(', ')}`);
}

Type guard

const isAdvertisedMode = (modeId: string, cfg: SessionConfiguration): boolean =>
  (cfg.modes?.availableModes ?? []).some(m => m.id === modeId);

Prevention

Discover availableModes at session start and derive mappings from them instead of hard-coding.
Re-validate mappings whenever the agent version changes.
Avoid hand-typing mode ids; copy them from the advertised payload.

When it happens

Trigger: configureACPPermissionMode resolves the permissionMode to a { type: 'session-mode', modeId } mapping whose modeId is not present in sessionConfiguration.modes.availableModes (or the agent advertised no modes at all).

Common situations: Hard-coded mapping for an agent version whose mode ids changed (e.g. 'acceptEdits' vs 'accept-edits'); connecting to an agent that simply doesn't offer the required mode; stale harness config after an agent upgrade.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ee8674c2ebdfedb0. Report an issue: GitHub.