EveryInc/compound-engineering-plugin · error · Error

Unknown permissions mode: ${permissions}

Error message

Unknown permissions mode: ${permissions}

What it means

`convert` validates `--permissions` against the known permission modes — "none", "broad", "from-commands" — before doing any conversion work. An unrecognized value throws this error immediately at the start of `run`, before the plugin is even loaded.

Source

Thrown at src/commands/convert.ts:80

    },
    inferTemperature: {
      type: "boolean",
      default: true,
      description: "Infer agent temperature from name/description",
    },
    includeSkills: {
      type: "boolean",
      default: false,
      alias: "include-skills",
      description: "For --to codex only: also emit skills and commands. Default is agents-only, the recommended pairing with `codex plugin install`. Set this flag for a legacy / standalone install without Codex native plugin install. Ignored by other targets.",
    },
  },
  async run({ args }) {
    const targetName = String(args.to)

    const permissions = String(args.permissions)
    if (!permissionModes.includes(permissions as PermissionMode)) {
      throw new Error(`Unknown permissions mode: ${permissions}`)
    }

    const plugin = await loadClaudePlugin(String(args.source))
    const outputRoot = resolveOutputRoot(args.output)
    const hasExplicitOutput = Boolean(args.output && String(args.output).trim())
    const codexHome = resolveCodexHome(args.codexHome)
    const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))

    const options: ClaudeToOpenCodeOptions = {
      agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
      inferTemperature: Boolean(args.inferTemperature),
      permissions: permissions as PermissionMode,
      codexIncludeSkills: Boolean(args.includeSkills),
    }

    if (targetName === "all") {
      const detected = await detectInstalledTools()
      const activeTargets = detected.filter((t) => t.detected && targets[t.name]?.implemented)

View on GitHub (pinned to c9c10f8c75)

Solutions

  1. Pass one of the exact modes: --permissions none, --permissions broad, or --permissions from-commands.
  2. Fix casing/typos — matching is exact, case-sensitive string inclusion.
  3. Check `convert --help` for the current list of supported permission modes in your installed version.

Example fix

// before
bun run src/index.ts convert --to codex --permissions permissive
// Error: Unknown permissions mode: permissive

// after
bun run src/index.ts convert --to codex --permissions from-commands
Defensive patterns

Strategy: validation

Validate before calling

const PERMISSION_MODES = ["none", "broad", "from-commands"] as const
const mode = process.env.PERMISSIONS ?? "broad"
if (!(PERMISSION_MODES as readonly string[]).includes(mode)) {
  throw new Error(`--permissions must be one of ${PERMISSION_MODES.join(" | ")}, got: ${mode}`)
}

Type guard

type PermissionMode = "none" | "broad" | "from-commands"
function isPermissionMode(v: string): v is PermissionMode {
  return v === "none" || v === "broad" || v === "from-commands"
}

Try / catch

try {
  await convert({ to, permissions })
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Unknown permissions mode:")) {
    console.error(`${e.message} — valid modes: none, broad, from-commands`)
    process.exitCode = 2
  } else throw e
}

Prevention

When it happens

Trigger: Calling convert with `--permissions` set to anything other than none/broad/from-commands: typos ("permissive", "nonee"), wrong casing ("None"), or inventing a mode that doesn't exist.

Common situations: Copy-pasting flags from another tool's docs; guessing a mode name from its description; scripting the CLI with a stale value from an older version whose mode set differed; shell scripts interpolating an empty or default string into the flag.

Understand the failure class

Background: "invalid argument", "unknown mode", "not supported": invalid enum-like argument errors explained — this error's family across 19 libraries.

Related errors

AI-assisted analysis of EveryInc/compound-engineering-plugin@c9c10f8c75 (2026-08-31). Data as JSON: /api/errors/719cd9bdb2a9aaf1. Report an issue: GitHub.