@joenandez/academy 0.5.17 → 0.5.18

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "academy",
   "description": "Academy v3 — portable AI agents.",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "hooks": "./hooks/hooks.json"
 }

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The heading at the top of this file is the version in `package.json`.
 
+## 0.5.18 — 2026-11-11
+
+### Fixed
+
+- **`academy create --runtime claude-code|codex|copilot`.** `create` stores
+  the agent's launch runtime, the same value `run --agent` persists, before
+  its jobs register. Before, `create` refused the flag, so a client that hired
+  a Codex agent (Subspace's Hire a Principal) failed. An unknown value is
+  refused with `invalid_spec` and writes nothing.
+
 ## 0.5.17 — 2026-11-11
 
 This release collects the 0.5.17 release candidates (rc.1 to rc.6, below) and

package/README.md

@@ -80,7 +80,7 @@ academy tokens <name> [--json]       # compiled prompt size by surface
 academy budget <name> [--json]       # surfaces over their cap
 academy sessions [--agent <name>] [--json]
 academy events --since <seq> [--logid <id>] [--json]
-academy create [<name>] [--kind <kind>] [--model <id>] [--display-name <text>] [--json]
+academy create [<name>] [--kind <kind>] [--model <id>] [--display-name <text>] [--runtime claude-code|codex|copilot] [--no-start] [--json]
 academy hire                         # interactive
 academy hire --spec <file> [--json]  # headless
 academy rename <old> [<new>] [--display-name <text>] [--json]  # no folder or job changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joenandez/academy",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "Academy v3 — portable AI agents with 8 boot surfaces and a skills primitive.",
   "type": "module",
   "bin": {

package/scripts/cli/args-kinds.mjs

@@ -1,29 +1,42 @@
-// `create <name> [--kind <kind>] [--model <id>] [--display-name <text>] [--no-start]
-// [--json]`. Like
+// `create <name> [--kind <kind>] [--model <id>] [--display-name <text>]
+// [--runtime <runtime>] [--no-start] [--json]`. Like
 // `rename`, an option Academy does not know stays on the command so the handler
 // answers it inside the envelope the caller asked for. The kind and model stay
 // raw strings: only `create` can answer an unsupported one in the envelope.
+const CREATE_VALUE_FLAGS = {
+  '--kind': 'kind',
+  '--model': 'model',
+  '--display-name': 'displayName',
+  '--runtime': 'runtime',
+};
+
 export function parseCreateArgs(command, rest) {
   const json = rest.includes('--json');
+  const values = {};
   let name;
-  let kind;
-  let model;
-  let displayName;
   let noStart = false;
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
+    const value = createValueFlag(rest, i);
     if (arg === '--json') continue;
     else if (arg === '--no-start') noStart = true;
-    else if (arg === '--kind') kind = rest[++i] ?? '';
-    else if (arg.startsWith('--kind=')) kind = arg.slice('--kind='.length);
-    else if (arg === '--model') model = rest[++i] ?? '';
-    else if (arg.startsWith('--model=')) model = arg.slice('--model='.length);
-    else if (arg === '--display-name') displayName = rest[++i] ?? '';
-    else if (arg.startsWith('--display-name=')) displayName = arg.slice('--display-name='.length);
+    else if (value) [values[value.key], i] = [value.value, value.next];
     else if (arg.startsWith('--')) return { command, json, name, invalidOption: arg };
     else name ??= arg;
   }
-  return { command, json, name, kind, model, displayName, noStart };
+  const { kind, model, displayName, runtime } = values;
+  return { command, json, name, kind, model, displayName, runtime, noStart };
+}
+
+// `--flag value` or `--flag=value` for a create option that takes a value.
+function createValueFlag(rest, i) {
+  const arg = rest[i];
+  const eq = arg.indexOf('=');
+  const flag = arg.startsWith('--') && eq > 0 ? arg.slice(0, eq) : arg;
+  const key = CREATE_VALUE_FLAGS[flag];
+  if (!key) return null;
+  if (flag !== arg) return { key, value: arg.slice(eq + 1), next: i };
+  return { key, value: rest[i + 1] ?? '', next: i + 1 };
 }
 
 // `skills check <agent> [--json]`. Like `create`, an option Academy does not

package/scripts/cli/args.mjs

@@ -175,11 +175,13 @@ Usage: ${CLI_NAME} <command> [options]
 Commands:
   doctor [--json]         Report Academy's version, roots, runtimes, and capability
   create [<name>] [--kind specialist|principal|owner] [--model <id>]
-         [--display-name <text>] [--no-start] [--json]
+         [--display-name <text>] [--runtime claude-code|codex|copilot]
+         [--no-start] [--json]
                           Scaffold a portable agent at ~/.academy/agents/<name>/ (default
                           specialist); a terminal Principal opens its first session;
                           --model stores its default model; --display-name stores a
-                          person-facing name ("Principal Two"); <name> stays kebab-case
+                          person-facing name ("Principal Two"); <name> stays kebab-case;
+                          --runtime stores the launch runtime, as run --agent does
   set-model <name> <model> [--json]
                           Change an agent's default model; run passes it to the
                           runtime (Claude --model, Codex -m) unless the caller does

package/scripts/cli/create-options.mjs

@@ -0,0 +1,43 @@
+import { KIND_PROFILES, exitJsonError } from './core.mjs';
+import { isModelId } from './model.mjs';
+import { toRuntimeProvider } from './runtime.mjs';
+import { DISPLAY_NAME_RULE, isDisplayName } from './yaml.mjs';
+
+// Every refusal comes before the name is asked about, so a create Academy will
+// not perform writes nothing. `invalid_spec` is the published code for an
+// unknown option; there is no sixteenth code for it.
+export function assertCreateOptions(kind, invalidOption, json, { model, displayName, runtime }) {
+  if (invalidOption !== undefined) {
+    refuseCreate(
+      `Unknown create option: ${invalidOption}. Use create <name> [--kind <kind>] [--model <id>] [--display-name <text>] [--runtime claude-code|codex|copilot] [--no-start] [--json].`,
+      { option: invalidOption },
+      json,
+    );
+  }
+  if (model !== undefined && !isModelId(model)) {
+    refuseCreate(`Model "${model}" is not a model id Academy can store.`, { model }, json);
+  }
+  if (runtime !== undefined && !toRuntimeProvider(runtime)) {
+    refuseCreate(
+      `Runtime "${runtime}" is not a runtime Academy supports. Use claude-code, codex, or copilot.`,
+      { runtime },
+      json,
+    );
+  }
+  if (displayName !== undefined && !isDisplayName(displayName)) {
+    refuseCreate(DISPLAY_NAME_RULE, { displayName }, json);
+  }
+  if (Object.hasOwn(KIND_PROFILES, kind)) return;
+  const kinds = Object.keys(KIND_PROFILES).join(', ');
+  refuseCreate(
+    `Agent kind "${kind}" is not a kind Academy supports. Use ${kinds}.`,
+    { kind },
+    json,
+  );
+}
+
+function refuseCreate(message, fields, json) {
+  if (json) exitJsonError('invalid_spec', message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}

package/scripts/cli/create.mjs

@@ -5,13 +5,11 @@ import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
 import {
   ACADEMY_ROOT,
   CLI_NAME,
-  KIND_PROFILES,
   activeCommandName,
   NIGHTLY_JOB_CRON,
   agentDir,
   contractError,
   contractOk,
-  exitJsonError,
   kindOf,
   LockTimeoutError,
   RuntimeUnavailableError,
@@ -26,8 +24,8 @@ import { claimDefaultName, claimName, isAgentNameFree } from './default-name.mjs
 import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
 import { agentRecord } from './inspect.mjs';
 import { creatorOf } from './leads.mjs';
-import { isModelId } from './model.mjs';
-import { DISPLAY_NAME_RULE, isDisplayName } from './yaml.mjs';
+import { assertCreateOptions } from './create-options.mjs';
+import { toRuntimeProvider } from './runtime.mjs';
 import { nextSteps } from './next-steps.mjs';
 import { deleteAcademyJobs } from './lifecycle.mjs';
 import {
@@ -65,46 +63,16 @@ export const INTRO_PENDING_MARKER = 'intro-pending.md';
 export function createAgent(
   name,
   json = false,
-  { kind = DEFAULT_KIND, model, displayName, invalidOption, guided } = {},
+  { kind = DEFAULT_KIND, model, displayName, runtime, invalidOption, guided } = {},
 ) {
-  assertCreateOptions(kind, invalidOption, json, { model, displayName });
-  const created = provisionAgent(name, json, kind, { model, displayName });
+  assertCreateOptions(kind, invalidOption, json, { model, displayName, runtime });
+  // Stored in the provider form `run --agent` writes, before the jobs register.
+  const yamlOptions = { model, displayName, runtime: runtime && toRuntimeProvider(runtime) };
+  const created = provisionAgent(name, json, kind, yamlOptions);
   reportCreated(created.name, created.dir, created.jobs, json, guided);
   return created.name;
 }
 
-// Every refusal comes before the name is asked about, so a create Academy will
-// not perform writes nothing. `invalid_spec` is the published code for an
-// unknown option; there is no sixteenth code for it.
-function assertCreateOptions(kind, invalidOption, json, { model, displayName }) {
-  if (invalidOption !== undefined) {
-    refuseCreate(
-      `Unknown create option: ${invalidOption}. Use create <name> [--kind <kind>] [--model <id>] [--display-name <text>] [--no-start] [--json].`,
-      { option: invalidOption },
-      json,
-    );
-  }
-  if (model !== undefined && !isModelId(model)) {
-    refuseCreate(`Model "${model}" is not a model id Academy can store.`, { model }, json);
-  }
-  if (displayName !== undefined && !isDisplayName(displayName)) {
-    refuseCreate(DISPLAY_NAME_RULE, { displayName }, json);
-  }
-  if (Object.hasOwn(KIND_PROFILES, kind)) return;
-  const kinds = Object.keys(KIND_PROFILES).join(', ');
-  refuseCreate(
-    `Agent kind "${kind}" is not a kind Academy supports. Use ${kinds}.`,
-    { kind },
-    json,
-  );
-}
-
-function refuseCreate(message, fields, json) {
-  if (json) exitJsonError('invalid_spec', message, fields);
-  console.error(`Error: ${message}`);
-  process.exit(1);
-}
-
 // The one creation path. `create` reports what it returns as a create and the
 // headless hire reports the same thing as a hire, so an agent hired without a
 // terminal is indistinguishable from a created one in ownership, scheduling and

package/scripts/cli/scaffold.mjs

@@ -62,7 +62,7 @@ function bootTemplate(kind, surface) {
 // `displayName`, `model` and `createdBy` are written only when known, so an agent without them
 // reads as null, the same as an agent created before either existed.
 export function writeAgentYaml(dir, name, today, kind = 'specialist', options = {}) {
-  const { displayName, model, createdBy } = options;
+  const { displayName, model, createdBy, runtime = 'claude_code' } = options;
   const { surfaces } = KIND_PROFILES[kind];
   const totalCap = surfaces.reduce((sum, { cap }) => sum + cap, 0).toLocaleString('en-US');
   const surfaceList = surfaces.map(({ name: surface }) => `  - ${surface}.md`).join('\n');
@@ -70,7 +70,7 @@ export function writeAgentYaml(dir, name, today, kind = 'specialist', options =
 name: ${name}
 ${displayName ? `displayName: ${displayNameScalar(displayName)}\n` : ''}created: ${today}
 ${createdBy ? `created_by: ${createdBy}\n` : ''}# Launch runtime — claude_code, codex, or copilot. \`academy run --agent\` rewrites it.
-runtime: claude_code
+runtime: ${runtime}
 ${model ? `model: ${model}\n` : ''}# Launch permissions. yolo skips approvals and the sandbox; delete it for the runtime's default.
 permission_mode: yolo
 # Memory systems that are on — list them, e.g. "memory: [backstory]". Leave it out for the default.