{"record":{"id":"9ea3884677c661f2","repo":"EveryInc/compound-engineering-plugin","slug":"unknown-permissions-mode-permissions-9ea388","errorCode":null,"errorMessage":"Unknown permissions mode: ${permissions}","messagePattern":"Unknown permissions mode: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/commands/install.ts","lineNumber":87,"sourceCode":"      description: \"Infer agent temperature from name/description\",\n    },\n    includeSkills: {\n      type: \"boolean\",\n      default: false,\n      alias: \"include-skills\",\n      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.\",\n    },\n    branch: {\n      type: \"string\",\n      description: \"Git branch to clone from (e.g. feat/new-agents)\",\n    },\n  },\n  async run({ args }) {\n    const targetName = String(args.to)\n\n    const permissions = String(args.permissions)\n    if (!permissionModes.includes(permissions as PermissionMode)) {\n      throw new Error(`Unknown permissions mode: ${permissions}`)\n    }\n\n    const branch = args.branch ? String(args.branch) : undefined\n    const resolvedPlugin = await resolvePluginPath(String(args.plugin), branch)\n\n    try {\n      const plugin = await loadClaudePlugin(resolvedPlugin.path)\n      const outputRoot = resolveOutputRoot(args.output)\n      const codexHome = resolveCodexHome(args.codexHome)\n      const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), \".pi\", \"agent\"))\n      const hasExplicitOutput = Boolean(args.output && String(args.output).trim())\n\n      const options: ClaudeToOpenCodeOptions = {\n        agentMode: String(args.agentMode) === \"primary\" ? \"primary\" : \"subagent\",\n        inferTemperature: Boolean(args.inferTemperature),\n        permissions: permissions as PermissionMode,\n        codexIncludeSkills: Boolean(args.includeSkills),\n      }","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/EveryInc/compound-engineering-plugin/blob/c9c10f8c75412c7232cb2bd663e5fd1cea98d84e/src/commands/install.ts#L69-L105","documentation":"`install` validates `--permissions` exactly like `convert`: the value must be one of \"none\", \"broad\", or \"from-commands\" (the `permissionModes` array). An unknown value throws this error at the top of `run`, before plugin path resolution or any file writes.","triggerScenarios":"Calling install with `--permissions` set to a value outside none/broad/from-commands — misspellings, wrong casing, an empty interpolated variable in a script, or a mode name borrowed from another tool.","commonSituations":"CI scripts with a stale or misconfigured permissions variable; copying install commands between tools with different permission vocabularies; hand-editing a script and dropping part of a hyphenated value (\"from commands\" with a space instead of \"from-commands\").","solutions":["Pass one of the exact modes: none, broad, or from-commands (note the hyphen in from-commands).","Fix casing and whitespace — comparison is exact and case-sensitive.","Echo the variable feeding --permissions in scripts to confirm it isn't empty or mis-expanded.","Check `install --help` for the supported modes in your installed CLI version."],"exampleFix":"// before\nbun run src/index.ts install --to codex --permissions \"from commands\"\n// Error: Unknown permissions mode: from commands\n\n// after\nbun run src/index.ts install --to codex --permissions from-commands","handlingStrategy":"validation","validationCode":"const PERMISSION_MODES = [\"none\", \"broad\", \"from-commands\"] as const\nconst mode = args.permissions ?? \"broad\"\nif (!(PERMISSION_MODES as readonly string[]).includes(mode)) {\n  throw new Error(`install --permissions must be one of ${PERMISSION_MODES.join(\" | \")}, got: '${mode}'`)\n}","typeGuard":"type PermissionMode = \"none\" | \"broad\" | \"from-commands\"\nfunction isPermissionMode(v: unknown): v is PermissionMode {\n  return typeof v === \"string\" && ([\"none\", \"broad\", \"from-commands\"] as const).includes(v as never)\n}","tryCatchPattern":"try {\n  await install({ to, permissions })\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"Unknown permissions mode:\")) {\n    console.error(`${e.message} — use none | broad | from-commands`)\n    process.exitCode = 2\n  } else throw e\n}","preventionTips":["Validate the permissions value in CI scripts before invoking install.","Watch whitespace and hyphens: \"from-commands\" with a hyphen, no spaces.","Share one PermissionMode type/constant between scripts and the CLI to prevent drift."],"tags":["cli","validation","argument-parsing"],"backgroundTag":"invalid-enum-argument","analyzedSha":"c9c10f8c75412c7232cb2bd663e5fd1cea98d84e","analyzedAt":"2026-08-31T15:18:07.959Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}