owenloop 0.5.2 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,14 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.5.3](https://github.com/typicalday/owenloop/compare/v0.5.2...v0.5.3) (2026-08-14)
8
+
9
+
10
+ ### Features
11
+
12
+ * let owenloop start pick a run modifier ([#154](https://github.com/typicalday/owenloop/issues/154)) ([a412b5b](https://github.com/typicalday/owenloop/commit/a412b5b334b5fd228d4558b50125e069512bd860))
13
+ * neutral permissionMode vocabulary across harness adapters ([#156](https://github.com/typicalday/owenloop/issues/156)) ([c96340f](https://github.com/typicalday/owenloop/commit/c96340f2d3f910e49838c6fbd68ed817e52f7ddc))
14
+
7
15
  ## [0.5.2](https://github.com/typicalday/owenloop/compare/v0.5.1...v0.5.2) (2026-08-14)
8
16
 
9
17
 
@@ -29,7 +29,7 @@ import { delimiter, join } from 'node:path';
29
29
  import { register } from "./registry.js";
30
30
  import { filterOwenloopEnv } from "./child-env.js";
31
31
  import { normalizeStepPermissions, validateHarnessOptions } from "./permissions.js";
32
- import { ResumeUnavailableError } from "./contract.js";
32
+ import { ResumeUnavailableError, NEUTRAL_PERMISSION_MODES, isNeutralPermissionMode } from "./contract.js";
33
33
  /** The registry key — the id a step def names in `x.harness.id`, and the key
34
34
  * `harness-versions.json` pins the CLI under. */
35
35
  const HARNESS_ID = 'claude-code';
@@ -178,6 +178,50 @@ const PERMISSION_MODES = [
178
178
  'dontAsk',
179
179
  'auto',
180
180
  ];
181
+ /**
182
+ * This adapter's neutral-vocabulary translation. Every value maps: this harness
183
+ * draws all three distinctions itself, so none of them is refused here.
184
+ *
185
+ * - `ask` → `default`. The SDK's `default` routes each unapproved tool to the
186
+ * `canUseTool` callback — a human decision point — and denies when no callback
187
+ * is wired. That is the "human is the gate" position.
188
+ * - `auto-safe` → `auto`. `auto` is the SDK's model-classifier mode: it decides
189
+ * per call and escalates the ones it judges dangerous. NOT `acceptEdits`,
190
+ * which auto-approves filesystem operations by category and applies no
191
+ * judgment to anything else, and NOT `dontAsk`, which DENIES an unapproved
192
+ * tool rather than consulting anyone — silently narrower than what the step
193
+ * asked for.
194
+ * - `full-access` → `bypassPermissions`. The only SDK mode that runs tools with
195
+ * no prompt at all, and the one the companion flag below exists for.
196
+ *
197
+ * `plan` has no neutral spelling on purpose: it is a different axis (what the
198
+ * agent may DO — explore only) rather than who approves.
199
+ */
200
+ const NEUTRAL_TO_SDK_MODE = Object.freeze({
201
+ 'ask': 'default',
202
+ 'auto-safe': 'auto',
203
+ 'full-access': 'bypassPermissions',
204
+ });
205
+ /** Values `preflight` accepts: the SDK's own union plus the neutral vocabulary. */
206
+ const ACCEPTED_PERMISSION_MODES = [
207
+ ...PERMISSION_MODES,
208
+ ...NEUTRAL_PERMISSION_MODES,
209
+ ];
210
+ /**
211
+ * Authored `permissionMode` → the SDK mode to send.
212
+ *
213
+ * Total by construction: an out-of-union value returns `undefined` and the
214
+ * caller drops it with a diagnostic, preserving the pre-existing behavior for a
215
+ * bag that lint never saw. A neutral value this adapter refuses (a `null` in the
216
+ * table) also returns `undefined`, and `preflight` has already refused it.
217
+ */
218
+ function toSdkPermissionMode(mode) {
219
+ if (isNeutralPermissionMode(mode)) {
220
+ const mapped = NEUTRAL_TO_SDK_MODE[mode];
221
+ return mapped === null ? undefined : mapped;
222
+ }
223
+ return PERMISSION_MODES.includes(mode) ? mode : undefined;
224
+ }
181
225
  /** The five-value closed union the SDK types `Options.effort` as. */
182
226
  const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
183
227
  /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
@@ -219,11 +263,23 @@ const OWENLOOP_CONTROL_DENY_SPECS = new Set([
219
263
  ]);
220
264
  function claudePreflight(permissions) {
221
265
  const issues = [];
222
- if (permissions.permissionMode !== undefined && !PERMISSION_MODES.includes(permissions.permissionMode)) {
223
- issues.push({
224
- field: 'permissionMode',
225
- message: `permissionMode must be one of ${PERMISSION_MODES.join('|')}`,
226
- });
266
+ const authoredMode = permissions.permissionMode;
267
+ if (authoredMode !== undefined) {
268
+ if (!ACCEPTED_PERMISSION_MODES.includes(authoredMode)) {
269
+ issues.push({
270
+ field: 'permissionMode',
271
+ message: `permissionMode must be one of ${ACCEPTED_PERMISSION_MODES.join('|')}`,
272
+ });
273
+ }
274
+ else if (isNeutralPermissionMode(authoredMode) && NEUTRAL_TO_SDK_MODE[authoredMode] === null) {
275
+ // Unreachable today — every neutral value maps here. Kept because the
276
+ // table's `null` arm is a real contract option, and a refusal that only
277
+ // exists once someone uses it is a refusal nobody has tested.
278
+ issues.push({
279
+ field: 'permissionMode',
280
+ message: `permissionMode '${authoredMode}' is unsupported by this adapter`,
281
+ });
282
+ }
227
283
  }
228
284
  if (permissions.effort !== undefined && !EFFORT_LEVELS.includes(permissions.effort)) {
229
285
  issues.push({ field: 'effort', message: `effort must be one of ${EFFORT_LEVELS.join('|')}` });
@@ -359,8 +415,12 @@ export function buildClaudeOptions(inputs, extra) {
359
415
  }
360
416
  }
361
417
  if (permissions.permissionMode !== undefined) {
362
- if (PERMISSION_MODES.includes(permissions.permissionMode)) {
363
- const mode = permissions.permissionMode;
418
+ // Neutral `full-access` lands here as `bypassPermissions`, so the companion
419
+ // flag below covers it too — that is the point of translating BEFORE the
420
+ // pairing rather than after it. Neutral `auto-safe` lands as `auto` and
421
+ // deliberately does NOT get the flag: it is still allowed to stop and ask.
422
+ const mode = toSdkPermissionMode(permissions.permissionMode);
423
+ if (mode !== undefined) {
364
424
  options.permissionMode = mode;
365
425
  // 'bypassPermissions' is IGNORED by the SDK without this companion flag.
366
426
  // Missing it is a silent downgrade to prompting, which in a headless run
@@ -371,7 +431,7 @@ export function buildClaudeOptions(inputs, extra) {
371
431
  else {
372
432
  extra.onEvent({
373
433
  kind: 'progress',
374
- text: `dropped unknown permissionMode '${permissions.permissionMode}' (expected one of ${PERMISSION_MODES.join('|')})`,
434
+ text: `dropped unknown permissionMode '${permissions.permissionMode}' (expected one of ${ACCEPTED_PERMISSION_MODES.join('|')})`,
375
435
  });
376
436
  }
377
437
  }
@@ -63,7 +63,7 @@
63
63
  * `{kind:'exited'}` and rejects with the underlying error.
64
64
  */
65
65
  import { existsSync } from 'node:fs';
66
- import { ResumeUnavailableError } from "./contract.js";
66
+ import { ResumeUnavailableError, NEUTRAL_PERMISSION_MODES, isNeutralPermissionMode } from "./contract.js";
67
67
  import { register } from "./registry.js";
68
68
  import { normalizeStepPermissions, validateHarnessOptions } from "./permissions.js";
69
69
  import { ADMITTED_OWENLOOP_KEYS, filterOwenloopEnv } from "./child-env.js";
@@ -135,6 +135,36 @@ const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-acce
135
135
  const DEFAULT_SANDBOX = 'workspace-write';
136
136
  /** `AskForApproval` values this adapter passes through untouched. */
137
137
  const NATIVE_APPROVAL_POLICIES = new Set(['untrusted', 'on-request', 'never']);
138
+ /**
139
+ * This adapter's neutral-vocabulary translation. Every value maps: Codex's
140
+ * `AskForApproval` draws all three distinctions itself, so none is refused here.
141
+ *
142
+ * - `ask` → `untrusted` (`AskForApproval::UnlessTrusted`). It escalates every
143
+ * command to the user except a small trusted read-only allowlist — `ls`,
144
+ * `cat`, `sed`. The allowlist is why this is "consults a human before
145
+ * anything beyond trivially safe reads" rather than a literal every-call
146
+ * prompt, which is exactly how the neutral value is worded.
147
+ * - `auto-safe` → `on-request`. The model decides when to escalate. That is the
148
+ * model-side-judgment position, matching the neutral value's meaning.
149
+ * - `full-access` → `never`. Never asks; a failed command is returned to the
150
+ * model instead of raising a prompt.
151
+ *
152
+ * SEPARATE AXIS, DELIBERATELY. None of these touches `sandbox`. What the step
153
+ * may REACH comes from neutral `filesystem` (and the legacy `sandbox`
154
+ * extension); this field only decides who approves reaching it. `full-access`
155
+ * therefore means "never ask", not "unsandboxed" — a step wanting both states
156
+ * both.
157
+ */
158
+ const NEUTRAL_TO_APPROVAL_POLICY = Object.freeze({
159
+ 'ask': 'untrusted',
160
+ 'auto-safe': 'on-request',
161
+ 'full-access': 'never',
162
+ });
163
+ /** Values `codexPreflight` accepts: this adapter's own set plus the neutral vocabulary. */
164
+ const ACCEPTED_APPROVAL_POLICIES = new Set([
165
+ ...NATIVE_APPROVAL_POLICIES,
166
+ ...NEUTRAL_PERMISSION_MODES,
167
+ ]);
138
168
  const UNRESTRICTED_SANDBOX = 'danger-full-access';
139
169
  function unsupportedFilesystemMessage(filesystem) {
140
170
  return (`filesystem '${filesystem}' is unsupported by this adapter because Codex app-server ` +
@@ -173,12 +203,24 @@ function codexPreflight(permissions) {
173
203
  "use sandbox 'workspace-write' or 'danger-full-access'",
174
204
  });
175
205
  }
176
- if (permissions.permissionMode !== undefined &&
177
- !NATIVE_APPROVAL_POLICIES.has(permissions.permissionMode)) {
178
- issues.push({
179
- field: 'permissionMode',
180
- message: `permissionMode must be one of ${[...NATIVE_APPROVAL_POLICIES].join('|')}`,
181
- });
206
+ const authoredMode = permissions.permissionMode;
207
+ if (authoredMode !== undefined) {
208
+ if (!ACCEPTED_APPROVAL_POLICIES.has(authoredMode)) {
209
+ issues.push({
210
+ field: 'permissionMode',
211
+ message: `permissionMode must be one of ${[...ACCEPTED_APPROVAL_POLICIES].join('|')}`,
212
+ });
213
+ }
214
+ else if (isNeutralPermissionMode(authoredMode) &&
215
+ NEUTRAL_TO_APPROVAL_POLICY[authoredMode] === null) {
216
+ // Unreachable today — every neutral value maps here. Kept because the
217
+ // table's `null` arm is a real contract option, and a refusal that only
218
+ // exists once someone uses it is a refusal nobody has tested.
219
+ issues.push({
220
+ field: 'permissionMode',
221
+ message: `permissionMode '${authoredMode}' is unsupported by this adapter`,
222
+ });
223
+ }
182
224
  }
183
225
  const sandbox = permissions.extensions['sandbox'];
184
226
  if (sandbox !== undefined && (typeof sandbox !== 'string' || !SANDBOX_MODES.has(sandbox))) {
@@ -203,9 +245,15 @@ function codexPreflight(permissions) {
203
245
  function toApprovalPolicy(mode) {
204
246
  if (mode === undefined)
205
247
  return 'never';
248
+ if (isNeutralPermissionMode(mode)) {
249
+ const mapped = NEUTRAL_TO_APPROVAL_POLICY[mode];
250
+ if (mapped !== null)
251
+ return mapped;
252
+ throw new Error(`permissionMode '${mode}' is unsupported by this adapter`);
253
+ }
206
254
  if (NATIVE_APPROVAL_POLICIES.has(mode))
207
255
  return mode;
208
- throw new Error(`permissionMode must be one of ${[...NATIVE_APPROVAL_POLICIES].join('|')}`);
256
+ throw new Error(`permissionMode must be one of ${[...ACCEPTED_APPROVAL_POLICIES].join('|')}`);
209
257
  }
210
258
  function isPlainMap(v) {
211
259
  return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -97,7 +97,11 @@ export interface StepPermissions {
97
97
  filesystem?: FilesystemPermission;
98
98
  /** Network authority requested by the workflow definition. */
99
99
  network?: NetworkPermission;
100
- /** Opaque adapter permission mode. Each adapter validates its own vocabulary. */
100
+ /**
101
+ * Adapter permission mode. Each adapter validates its own vocabulary, PLUS the
102
+ * neutral values every adapter must either translate or refuse — see
103
+ * `NEUTRAL_PERMISSION_MODES`.
104
+ */
101
105
  permissionMode?: string;
102
106
  /** Only ever a positive integer; anything else was dropped in normalization. */
103
107
  maxTurns?: number;
@@ -108,6 +112,66 @@ export interface StepPermissions {
108
112
  * no adapter needs a null check. */
109
113
  extensions: Record<string, unknown>;
110
114
  }
115
+ /**
116
+ * The HARNESS-NEUTRAL `permissionMode` vocabulary: three distinct positions on
117
+ * ONE axis — how much a step may do before a human is consulted.
118
+ *
119
+ * WHY THIS EXISTS. `permissionMode` sits in `NEUTRAL_KEYS` (see
120
+ * `./permissions.ts`) alongside `filesystem` and `network`, but it did not
121
+ * behave like them. `filesystem: unrestricted` is an INTENT the step states and
122
+ * each adapter translates into its own dialect — one shipped adapter turns it
123
+ * into that vendor's own sandbox setting. `permissionMode` had no translation
124
+ * layer at all: the authored string went to the adapter verbatim, and the
125
+ * shipped adapters accept DISJOINT vocabularies for the same ideas, each
126
+ * refusing the other's at preflight. A step therefore had to name one vendor's
127
+ * word, which pinned it to that vendor as surely as an explicit `id:` would
128
+ * have. That is exactly the pin the neutral-key contract exists to prevent.
129
+ *
130
+ * THE THREE POSITIONS ARE NOT INTERCHANGEABLE. Both shipped harnesses draw the
131
+ * same three distinctions, so collapsing any two would lose a real one:
132
+ *
133
+ * - `ask` — the harness consults a human before anything beyond trivially safe
134
+ * reads. The human is the gate.
135
+ * - `auto-safe` — a model-side classifier judges each action: it proceeds on
136
+ * ordinary work and consults a human only when an action is potentially
137
+ * dangerous. The classifier is the gate; a human is the exception path.
138
+ * - `full-access` — nothing is gated. The harness never consults a human, and
139
+ * a failed action is simply reported back to the model.
140
+ *
141
+ * `auto-safe` is NOT a milder `full-access`: it can still stop and ask. A
142
+ * headless step that must not stall wants `full-access`, and the two exist
143
+ * separately so that choice is stated rather than inferred.
144
+ *
145
+ * `ask` and `auto-safe` are meaningful only where something can answer a
146
+ * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
147
+ * Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into
148
+ * a retry storm whose every worker dies in the same place. That is a reason for
149
+ * a definition author to choose `full-access` for unattended steps, not a
150
+ * reason for an adapter to silently upgrade one value into another.
151
+ *
152
+ * WHAT AN ADAPTER OWES THIS VOCABULARY. For each value an adapter must either
153
+ * map it onto the vendor mode with the same meaning, or refuse it in
154
+ * `preflight` with a `PermissionIssue` naming `permissionMode`. Refusing is a
155
+ * legitimate answer and fails closed: the worker releases its claim and starts
156
+ * no model process. Mapping a value onto a mode that grants MORE than the value
157
+ * describes is never legitimate.
158
+ *
159
+ * VENDOR VALUES ARE UNCHANGED. Each adapter still accepts its own native
160
+ * vocabulary and still refuses every other adapter's. These values are an
161
+ * ADDITION, so no already-published definition changes meaning.
162
+ */
163
+ export declare const NEUTRAL_PERMISSION_MODES: readonly ["ask", "auto-safe", "full-access"];
164
+ export type NeutralPermissionMode = (typeof NEUTRAL_PERMISSION_MODES)[number];
165
+ /**
166
+ * An adapter's neutral-vocabulary translation table.
167
+ *
168
+ * EXHAUSTIVE BY TYPE, and that is the point: adding a fourth neutral value
169
+ * breaks compilation in every adapter until each one decides what it means
170
+ * there. `null` is the explicit "this adapter has no equivalent" decision and
171
+ * makes `preflight` refuse — distinct from an adapter that simply forgot.
172
+ */
173
+ export type NeutralPermissionModeMap = Readonly<Record<NeutralPermissionMode, string | null>>;
174
+ export declare function isNeutralPermissionMode(value: string): value is NeutralPermissionMode;
111
175
  /** One fail-closed adapter preflight refusal. */
112
176
  export interface PermissionIssue {
113
177
  /** The normalized permission field or extension key responsible, when one exists. */
@@ -1,3 +1,59 @@
1
+ /**
2
+ * The HARNESS-NEUTRAL `permissionMode` vocabulary: three distinct positions on
3
+ * ONE axis — how much a step may do before a human is consulted.
4
+ *
5
+ * WHY THIS EXISTS. `permissionMode` sits in `NEUTRAL_KEYS` (see
6
+ * `./permissions.ts`) alongside `filesystem` and `network`, but it did not
7
+ * behave like them. `filesystem: unrestricted` is an INTENT the step states and
8
+ * each adapter translates into its own dialect — one shipped adapter turns it
9
+ * into that vendor's own sandbox setting. `permissionMode` had no translation
10
+ * layer at all: the authored string went to the adapter verbatim, and the
11
+ * shipped adapters accept DISJOINT vocabularies for the same ideas, each
12
+ * refusing the other's at preflight. A step therefore had to name one vendor's
13
+ * word, which pinned it to that vendor as surely as an explicit `id:` would
14
+ * have. That is exactly the pin the neutral-key contract exists to prevent.
15
+ *
16
+ * THE THREE POSITIONS ARE NOT INTERCHANGEABLE. Both shipped harnesses draw the
17
+ * same three distinctions, so collapsing any two would lose a real one:
18
+ *
19
+ * - `ask` — the harness consults a human before anything beyond trivially safe
20
+ * reads. The human is the gate.
21
+ * - `auto-safe` — a model-side classifier judges each action: it proceeds on
22
+ * ordinary work and consults a human only when an action is potentially
23
+ * dangerous. The classifier is the gate; a human is the exception path.
24
+ * - `full-access` — nothing is gated. The harness never consults a human, and
25
+ * a failed action is simply reported back to the model.
26
+ *
27
+ * `auto-safe` is NOT a milder `full-access`: it can still stop and ask. A
28
+ * headless step that must not stall wants `full-access`, and the two exist
29
+ * separately so that choice is stated rather than inferred.
30
+ *
31
+ * `ask` and `auto-safe` are meaningful only where something can answer a
32
+ * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
33
+ * Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into
34
+ * a retry storm whose every worker dies in the same place. That is a reason for
35
+ * a definition author to choose `full-access` for unattended steps, not a
36
+ * reason for an adapter to silently upgrade one value into another.
37
+ *
38
+ * WHAT AN ADAPTER OWES THIS VOCABULARY. For each value an adapter must either
39
+ * map it onto the vendor mode with the same meaning, or refuse it in
40
+ * `preflight` with a `PermissionIssue` naming `permissionMode`. Refusing is a
41
+ * legitimate answer and fails closed: the worker releases its claim and starts
42
+ * no model process. Mapping a value onto a mode that grants MORE than the value
43
+ * describes is never legitimate.
44
+ *
45
+ * VENDOR VALUES ARE UNCHANGED. Each adapter still accepts its own native
46
+ * vocabulary and still refuses every other adapter's. These values are an
47
+ * ADDITION, so no already-published definition changes meaning.
48
+ */
49
+ export const NEUTRAL_PERMISSION_MODES = Object.freeze([
50
+ 'ask',
51
+ 'auto-safe',
52
+ 'full-access',
53
+ ]);
54
+ export function isNeutralPermissionMode(value) {
55
+ return NEUTRAL_PERMISSION_MODES.includes(value);
56
+ }
1
57
  /** The `code` every `ResumeUnavailableError` carries. Match on THIS, not on the class. */
2
58
  export const RESUME_UNAVAILABLE = 'RESUME_UNAVAILABLE';
3
59
  /**
@@ -1,6 +1,6 @@
1
1
  import type { BundleRuntimeRequirements } from './types.ts';
2
2
  /** Runtime features implemented by this Owenloop release. */
3
- export declare const SUPPORTED_RUNTIME_FEATURES: readonly ["harness-policy-enforcement.v1", "native-judge-policy-inheritance.v1"];
3
+ export declare const SUPPORTED_RUNTIME_FEATURES: readonly ["harness-policy-enforcement.v1", "native-judge-policy-inheritance.v1", "neutral-approval-modes.v1"];
4
4
  export interface RuntimeCompatibilityEnvironment {
5
5
  /** The running Owenloop package version. `0.0.0` is the unavailable-version sentinel. */
6
6
  version: string;
@@ -6,6 +6,15 @@ const semver = createRequire(import.meta.url)('semver');
6
6
  export const SUPPORTED_RUNTIME_FEATURES = Object.freeze([
7
7
  'harness-policy-enforcement.v1',
8
8
  'native-judge-policy-inheritance.v1',
9
+ // A def may write `x.harness.permissionMode` as one of the three neutral
10
+ // values (`ask`, `auto-safe`, `full-access`) and every adapter translates it
11
+ // into the vendor mode with the same meaning, or refuses it at preflight.
12
+ // A def that uses one MUST require this id: on a CLI that predates it, every
13
+ // adapter refuses the neutral value as out-of-vocabulary, so the step fails
14
+ // closed — correct, but with a message about a bad permission mode rather
15
+ // than about an old runtime. Requiring the id moves the diagnosis to the
16
+ // bundle check, before any order is offered.
17
+ 'neutral-approval-modes.v1',
9
18
  ]);
10
19
  /** True only for one canonical strict SemVer value, with no prefix, range, or whitespace. */
11
20
  export function isCanonicalSemver(value) {
package/dist/src/cli.js CHANGED
@@ -1120,8 +1120,11 @@ Commands:
1120
1120
  push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <origin>] [--as <slot>]
1121
1121
  publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (server-diffed, idempotent)
1122
1122
  --as names the credential slot: human (default), agent, or agent:<account>
1123
- start <defName> [--provide name=json ...] [--crew <name>] [--title <text>] [--hub <url>]
1123
+ start <defName> [--provide name=json ...] [--crew <name>] [--title <text>] [--modifier <name>] [--hub <url>]
1124
1124
  ${' '.repeat(41)}start a published workflow on the bound hub (human credential)
1125
+ ${' '.repeat(41)}--modifier names one value from the def's declared \`modifiers:\` set; every
1126
+ ${' '.repeat(41)}step's capability is then offered as \`<capability>:<modifier>\`. Omit it and
1127
+ ${' '.repeat(41)}the run carries no modifier and its steps are offered on BARE capabilities.
1125
1128
  agent new <name> [--crews <a,b>] [--scopes <a,b>] [--shift] [--hub <url>] mint a new Scoped Identity on the hub and store its token in slot agent:<name> (the token is never printed; --shift = --scopes work,run)
1126
1129
  capability bind <capability> <crew> [--hub <url>] add a crew to a workflow capability on the hub org — a capability may bind many crews (admin; human credential)
1127
1130
  capability unbind <capability> <crew> [--hub <url>] remove one (capability, crew) route
@@ -1210,7 +1213,7 @@ export const COMMAND_OPTIONS = new Map([
1210
1213
  ['publish', cmdOpts('unsigned', 'output', 'source', 'hub')],
1211
1214
  ['trust', cmdOpts('force', 'key', 'principal', 'pools', 'labels', 'namespaces', 'delegate', 'signing-key', 'output', 'reason', 'effective-from')],
1212
1215
  ['push', cmdOpts('dry-run', 'force', 'hub', 'as', 'bundle')],
1213
- ['start', cmdOpts('hub', 'crew', 'title', 'provide')],
1216
+ ['start', cmdOpts('hub', 'crew', 'title', 'provide', 'modifier')],
1214
1217
  ['agent', cmdOpts('crews', 'hub', 'scopes', 'shift')],
1215
1218
  ['capability', cmdOpts('hub')],
1216
1219
  ['crew', cmdOpts('hub', 'kind', 'owner')],
@@ -3951,6 +3954,13 @@ async function dispatchStart(io, args) {
3951
3954
  // Validate request-only options before project binding, Keychain, or network access.
3952
3955
  const crew = requiredTextOption('crew', 'name');
3953
3956
  const title = requiredTextOption('title', 'text');
3957
+ // The run's ONE routing modifier. Validated by the hub against the def's
3958
+ // declared `modifiers:` set (a value outside it is a 400 `modifier_refused`),
3959
+ // so the CLI only enforces the shape every other text option enforces:
3960
+ // `--modifier` with no value, or with an empty one, is a usage error rather
3961
+ // than a silent unmodified run. Omitting the flag entirely IS the unmodified
3962
+ // run — that is the difference `requiredTextOption` preserves.
3963
+ const modifier = requiredTextOption('modifier', 'name');
3954
3964
  const origin = resolveStartHub(io, args);
3955
3965
  const slot = { principal: 'human' };
3956
3966
  const cred = readCredential(io, origin, slot);
@@ -3963,6 +3973,10 @@ async function dispatchStart(io, args) {
3963
3973
  ...(Object.keys(provide).length > 0 ? { provide } : {}),
3964
3974
  ...(crew !== undefined ? { default_crew: crew } : {}),
3965
3975
  ...(title !== undefined ? { title } : {}),
3976
+ // Spread-conditional, not `modifier` outright: the route reads `''` and
3977
+ // absent as the same thing, but sending an explicit `undefined` would put a
3978
+ // `modifier` key in the JSON body with a null value. Omitted means omitted.
3979
+ ...(modifier !== undefined ? { modifier } : {}),
3966
3980
  };
3967
3981
  const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/start_run', request);
3968
3982
  if (res.status === 401)
@@ -3997,6 +4011,13 @@ async function dispatchStart(io, args) {
3997
4011
  workflow: wire.workflow,
3998
4012
  def: wire.def,
3999
4013
  status: wire.status,
4014
+ // Echoed from the REQUEST, not the response — `start_run` returns no
4015
+ // `modifier` field. That is not an assumption about what the hub stored: a
4016
+ // value outside the def's declared `modifiers:` set is refused with a 400
4017
+ // before any instance exists, so reaching this line at all proves the hub
4018
+ // accepted exactly this value. Printed only when the flag was passed, so an
4019
+ // unmodified run's output is byte-identical to what it was before.
4020
+ ...(modifier !== undefined ? { modifier } : {}),
4000
4021
  ...(Array.isArray(wire.stampedCrews) ? { stampedCrews: wire.stampedCrews } : {}),
4001
4022
  ...(Array.isArray(wire.validatedCrews) ? { validatedCrews: wire.validatedCrews } : {}),
4002
4023
  });
@@ -38,6 +38,7 @@ x:
38
38
  - `tools: []` is an explicit empty allow-list and disables all built-in tools on adapters that support tool lists.
39
39
  - `filesystem` is one of `read-only`, `workspace-write`, or `unrestricted`.
40
40
  - `network` is one of `owenloop-only` or `unrestricted`.
41
+ - `permissionMode` accepts each adapter's own vocabulary, plus three neutral values: `ask`, `auto-safe`, and `full-access`.
41
42
  - `tools` and `disallowedTools` must not overlap.
42
43
  - Invalid types, invalid closed-set values, generated `name`/`description` fields, and the legacy `x.claude-code` carrier are definition errors.
43
44
  - Unknown `x.harness` keys remain opaque extension data. The selected adapter may interpret or warn about those keys.
@@ -58,6 +59,10 @@ A cache created by an older CLI may contain `filesystem` or `network` under `per
58
59
  | `network: owenloop-only` | supported through isolated settings, skills, MCP, and built-in tools | refused |
59
60
  | `network: unrestricted` | supported | supported with `filesystem: unrestricted`, or with an omitted filesystem field and legacy sandbox `workspace-write` / `danger-full-access`; legacy sandbox `read-only` is refused because Codex has no independent read-only network control |
60
61
  | `maxTurns` | enforced by the SDK | refused; Codex app-server has no thread or turn limit parameter |
62
+ | `permissionMode: ask` | translated to `default` | translated to `approvalPolicy: untrusted` |
63
+ | `permissionMode: auto-safe` | translated to `auto`, without the danger companion flag | translated to `approvalPolicy: on-request` |
64
+ | `permissionMode: full-access` | translated to `bypassPermissions` plus the SDK's `allowDangerouslySkipPermissions` companion flag | translated to `approvalPolicy: never` |
65
+ | another adapter's `permissionMode` value | refused; the Claude Code adapter accepts only its own SDK union plus the three neutral values | refused; the Codex adapter accepts only `untrusted`, `on-request`, `never`, plus the three neutral values |
61
66
 
62
67
  Codex refusal of explicit `filesystem: read-only` and `filesystem: workspace-write` is intentional and runs before both cold start and resume. Codex app-server loads configuration from thread, project, global/managed, and persisted session layers. The pinned Codex version has no reliable switch that isolates every layer, and some layers can introduce host processes, providers, endpoints, MCP servers, or additional writable roots outside the thread sandbox. Partial filtering would claim a boundary the adapter cannot prove, so the adapter starts no app-server process and the worker releases the held claim.
63
68
 
@@ -65,7 +70,27 @@ Codex also refuses every defined `maxTurns` value before both cold start and res
65
70
 
66
71
  An omitted `filesystem` field preserves the existing Codex default sandbox behavior. `filesystem: unrestricted` preserves the existing explicit `danger-full-access` behavior. The legacy adapter extension `sandbox` remains available with `read-only`, `workspace-write`, or `danger-full-access` for backward compatibility, but `sandbox` is a vendor-specific pass-through rather than Owenloop's neutral filesystem guarantee. A workflow that requires an enforceable neutral read-only policy must select the Claude Code adapter.
67
72
 
68
- The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never`.
73
+ The worker-created `owenloop` MCP mount still wins any `mcp_servers.owenloop` name clash. The default unrestricted mount registers `get_order`, `submit`, and `reject`. Codex approval policy still accepts only `untrusted`, `on-request`, or `never` as vendor values.
74
+
75
+ ## Neutral approval modes
76
+
77
+ `permissionMode` names how much a step may do before a human is consulted. It is the one neutral field whose values were vendor-specific: Claude Code's never-prompt mode is `bypassPermissions` and Codex's is `never`, and each adapter refuses the other's. A step that must never prompt therefore had to name one vendor's word, which pinned the step to that vendor exactly as an explicit `id:` would.
78
+
79
+ The neutral vocabulary is three positions on one axis, and both shipped harnesses draw all three distinctions themselves:
80
+
81
+ | Neutral value | What is the gate | Claude Code | Codex |
82
+ |---|---|---|---|
83
+ | `ask` | a human, before anything beyond trivially safe reads | `default` | `untrusted` |
84
+ | `auto-safe` | a model-side classifier; it proceeds on ordinary work and consults a human only when an action is potentially dangerous | `auto` | `on-request` |
85
+ | `full-access` | nothing; the harness never consults a human and a failed action is reported back to the model | `bypassPermissions` + `allowDangerouslySkipPermissions` | `never` |
86
+
87
+ `auto-safe` is not a milder `full-access`. It can still stop and ask, which is the whole point of it, so an adapter must never map it onto a never-ask mode. The two exist separately so a definition states the choice rather than having it inferred.
88
+
89
+ `ask` and `auto-safe` are meaningful only where something can answer a prompt. In a Shift-dispatched run nothing can today, so a prompt is a stall: the Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into a retry storm whose every worker dies in the same place. That is a reason for a definition author to choose `full-access` for headless steps, not a reason for an adapter to silently upgrade one value into another.
90
+
91
+ For each neutral value an adapter must either map it onto the vendor mode with the same meaning, or refuse it in preflight. Refusal is a legitimate answer and fails closed: the worker releases its claim and starts no model process. Mapping a value onto a mode that grants more than the value describes is never legitimate.
92
+
93
+ Each adapter still accepts its own vendor vocabulary and still refuses the other's, so no already-published definition changes meaning. A definition that uses a neutral value must declare the `neutral-approval-modes.v1` runtime feature. On a CLI that predates the feature, both shipped adapters refuse the neutral value as out-of-vocabulary and the step fails closed, but the message names a bad permission mode rather than an old runtime; the feature declaration moves that diagnosis to the bundle compatibility check, before any order is offered.
69
94
 
70
95
  The Claude Code adapter refuses a `read-only` allow-list containing anything outside `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, and the born-bound control tools. With `network: owenloop-only`, the allowed read-only built-ins narrow to `Read`, `Glob`, and `Grep`; `WebFetch` and `WebSearch` remain available only with `network: unrestricted`. The Claude Code adapter refuses an `owenloop-only` allow-list containing Bash, web tools, skills, agent delegation, or any unaudited tool. The Claude Code adapter also refuses authored external MCP tool names because the current option surface cannot prove an exact per-tool allow-list for an external server.
71
96
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.2"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.3"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.2"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.3"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",