owenloop 0.5.2 → 0.5.4

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.
Files changed (41) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +6 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +6 -0
  4. package/dist/packages/work/src/agent/brief.js +46 -2
  5. package/dist/packages/work/src/agent/loop.js +3 -0
  6. package/dist/packages/work/src/exec/loop.js +153 -9
  7. package/dist/packages/work/src/harness/child-env.js +8 -0
  8. package/dist/packages/work/src/harness/claude.js +82 -9
  9. package/dist/packages/work/src/harness/codex.js +63 -8
  10. package/dist/packages/work/src/harness/contract.d.ts +84 -1
  11. package/dist/packages/work/src/harness/contract.js +75 -0
  12. package/dist/packages/work/src/settings/settings.d.ts +12 -4
  13. package/dist/packages/work/src/settings/settings.js +14 -11
  14. package/dist/src/bundle/runtime.d.ts +1 -1
  15. package/dist/src/bundle/runtime.js +9 -0
  16. package/dist/src/cli.js +226 -8
  17. package/dist/src/config-dir.d.ts +62 -0
  18. package/dist/src/config-dir.js +87 -0
  19. package/dist/src/crypto/trust-roots.d.ts +8 -4
  20. package/dist/src/crypto/trust-roots.js +18 -12
  21. package/dist/src/defs.js +57 -16
  22. package/dist/src/engine.js +25 -3
  23. package/dist/src/hub.d.ts +5 -1
  24. package/dist/src/hub.js +7 -8
  25. package/dist/src/paths.d.ts +47 -4
  26. package/dist/src/paths.js +36 -5
  27. package/dist/src/work-settings.d.ts +8 -5
  28. package/dist/src/work-settings.js +15 -12
  29. package/docs/agent-runner.md +26 -1
  30. package/docs/authoring.md +40 -13
  31. package/docs/bundles.md +9 -0
  32. package/docs/cli.md +121 -24
  33. package/docs/crypto.md +8 -8
  34. package/docs/design.md +20 -2
  35. package/docs/embedding.md +5 -4
  36. package/docs/wire-contracts.md +3 -2
  37. package/package.json +1 -1
  38. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  39. package/plugins/claude-code/plugin/.mcp.json +1 -1
  40. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  41. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,31 @@ 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.4](https://github.com/typicalday/owenloop/compare/v0.5.3...v0.5.4) (2026-08-15)
8
+
9
+
10
+ ### Features
11
+
12
+ * add `owenloop cancel` to stop a running hub instance ([#158](https://github.com/typicalday/owenloop/issues/158)) ([76ccc75](https://github.com/typicalday/owenloop/commit/76ccc75cf4b1c9312484e691663f9e5c9e1ebe9a))
13
+ * add `owenloop instance show` to read a hub run's live state ([#161](https://github.com/typicalday/owenloop/issues/161)) ([9ab7cec](https://github.com/typicalday/owenloop/commit/9ab7cec6f72dc79c11c2c7079174f9581ff97304))
14
+ * let workdirFrom name a declared input, not only a consume ([#165](https://github.com/typicalday/owenloop/issues/165)) ([fff886b](https://github.com/typicalday/owenloop/commit/fff886b86c097a1b85de745faa322cf92d0e5615))
15
+ * state the submit contract in every rendered brief ([#160](https://github.com/typicalday/owenloop/issues/160)) ([f62430d](https://github.com/typicalday/owenloop/commit/f62430d1febc77597cafb25e8b2928f1ab7e7fb3))
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * deliver a payload reject before the owed submits, not after ([#164](https://github.com/typicalday/owenloop/issues/164)) ([b38b709](https://github.com/typicalday/owenloop/commit/b38b709aededd0ebef2684f8c64abb8fe68226de))
21
+ * relay a failed command step's own output to the exec log ([#162](https://github.com/typicalday/owenloop/issues/162)) ([d40595d](https://github.com/typicalday/owenloop/commit/d40595dbfe40bfbf6f5d729296189e5b88424eec))
22
+ * scope owenloop's config dir without hijacking XDG_CONFIG_HOME ([#163](https://github.com/typicalday/owenloop/issues/163)) ([72838b4](https://github.com/typicalday/owenloop/commit/72838b45e3fb6f52038001148bca62f879a90efc))
23
+
24
+ ## [0.5.3](https://github.com/typicalday/owenloop/compare/v0.5.2...v0.5.3) (2026-08-14)
25
+
26
+
27
+ ### Features
28
+
29
+ * let owenloop start pick a run modifier ([#154](https://github.com/typicalday/owenloop/issues/154)) ([a412b5b](https://github.com/typicalday/owenloop/commit/a412b5b334b5fd228d4558b50125e069512bd860))
30
+ * neutral permissionMode vocabulary across harness adapters ([#156](https://github.com/typicalday/owenloop/issues/156)) ([c96340f](https://github.com/typicalday/owenloop/commit/c96340f2d3f910e49838c6fbd68ed817e52f7ddc))
31
+
7
32
  ## [0.5.2](https://github.com/typicalday/owenloop/compare/v0.5.1...v0.5.2) (2026-08-14)
8
33
 
9
34
 
package/README.md CHANGED
@@ -487,8 +487,12 @@ hub's own def hashes. `owenloop agent new
487
487
  Setting up a machine from scratch? `owenloop setup` may sign you in as a human
488
488
  and, when needed, mint or rekey and store a Scoped Identity. Setup writes only
489
489
  `hubOrigin` into the execution settings file, preserving the other keys. The
490
- file is `$XDG_CONFIG_HOME/owenloop/settings.json` when `XDG_CONFIG_HOME` is
491
- set to a non-blank value; otherwise `$HOME/.config/owenloop/settings.json`. For
490
+ file is `$OWENLOOP_CONFIG_DIR/settings.json` when `OWENLOOP_CONFIG_DIR` is set
491
+ to a non-blank absolute path; otherwise `$XDG_CONFIG_HOME/owenloop/settings.json`
492
+ when `XDG_CONFIG_HOME` is non-blank; otherwise
493
+ `$HOME/.config/owenloop/settings.json`. Prefer `OWENLOOP_CONFIG_DIR` when
494
+ running several shifts on one machine — `XDG_CONFIG_HOME` also relocates `gh`,
495
+ `git`, and `gcloud` for every command step the shift dispatches. For
492
496
  a non-default account,
493
497
  setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes and,
494
498
  when needed, converges the bundled `owenloop` plugins for Claude Code and Codex.
@@ -69,6 +69,12 @@ export interface BriefSpec {
69
69
  * repeated rejections, not a first attempt.
70
70
  */
71
71
  escalated?: boolean;
72
+ /**
73
+ * The owed output paths for this order, in packet order — `packet.owes`
74
+ * mapped to its `path`. Feeds the submit contract; absent or empty renders
75
+ * the contract without naming any path.
76
+ */
77
+ owes?: readonly string[];
72
78
  }
73
79
  /**
74
80
  * Substitute the four dispatch tokens into a step template.
@@ -28,8 +28,52 @@ export function renderBrief(templateContent, spec) {
28
28
  .join(spec.account)
29
29
  .split(SHIFT_TOKEN)
30
30
  .join(spec.shiftId ?? '');
31
- const routing = renderRoutingLine(spec);
32
- return routing === '' ? substituted : `${routing}\n\n${substituted}`;
31
+ const blocks = [renderRoutingLine(spec), renderSubmitContract(spec), substituted];
32
+ return blocks.filter((b) => b !== '').join('\n\n');
33
+ }
34
+ /**
35
+ * How an order is COMPLETED, stated to every agent on every run.
36
+ *
37
+ * WHY THIS EXISTS. Nothing else ever told an agent that finishing means calling
38
+ * a tool. The engine mounts the work-holder MCP server and then relies entirely
39
+ * on the def author's prose; owenloop's own house verb for it is "green <path>
40
+ * with <value>", which names no tool and is not a phrase any model has seen
41
+ * before. A strong enough model infers the tool call from the mounted surface
42
+ * and submits; a weaker one reads the same sentence as "print this JSON",
43
+ * writes the value into a code fence, and ends its turn. The hub then records
44
+ * nothing, the confirm grace lapses, and the order is re-offered — so the step
45
+ * loops forever while every attempt does the work correctly. That is a defect
46
+ * in what the engine states, not in the def or the model: the engine is the
47
+ * only party that knows the submit contract, so the engine has to state it.
48
+ *
49
+ * WHY IT NAMES THE OWED PATHS. `submit` is per-path and takes the path as an
50
+ * argument, so "call submit" alone is not actionable — an agent that owes two
51
+ * outputs and submits one is as stuck as one that submits none. The list comes
52
+ * from `packet.owes`, which is the hub's own answer to "what does this order
53
+ * still owe", so it stays correct on a re-offer where some paths are already
54
+ * paid.
55
+ *
56
+ * WHY THE COUNTER-EXAMPLE IS SPELLED OUT. The observed failure is not a refusal
57
+ * to submit — it is a belief that printing IS submitting. Naming the tool
58
+ * without ruling out the near-miss leaves that belief intact.
59
+ *
60
+ * Vendor-neutral by construction: it names owenloop's own tool and mount, and
61
+ * no harness. `test/vendor-gate.test.ts` fails any shipped file outside
62
+ * `src/harness/` that names a vendor.
63
+ */
64
+ function renderSubmitContract(spec) {
65
+ const owed = (spec.owes ?? []).filter((p) => p !== '');
66
+ // Nothing owed, nothing to say — the same stance the routing line takes on an
67
+ // absent modifier. A contract with no path to name would have to write
68
+ // `<path>` into its own example, which teaches the shape of the call while
69
+ // leaving the one argument that matters unanswered.
70
+ if (owed.length === 0)
71
+ return '';
72
+ return [
73
+ `How this order completes: submit your result with the \`submit\` tool on the mounted \`owenloop\` MCP server. You owe ${owed.map((p) => `\`${p}\``).join(', ')} — call it once for each.`,
74
+ `Example: \`submit({"path": "${owed[0]}", "value": <the value this brief asks for>})\`.`,
75
+ 'Printing that value as text, or inside a code fence, does NOT submit it — the turn ends, the hub records nothing, and this order is re-offered from scratch. Wherever this brief says "green <path> with <value>", it means exactly this tool call.',
76
+ ].join('\n');
33
77
  }
34
78
  /**
35
79
  * The run's depth, stated to the agent in one line, PREPENDED rather than
@@ -402,6 +402,9 @@ export function createAgentRunLoop(opts) {
402
402
  // statement about the RUN, and a shift has no say in it.
403
403
  ...(packet.modifier !== undefined ? { modifier: packet.modifier } : {}),
404
404
  ...(packet.escalated === true ? { escalated: true } : {}),
405
+ // The hub's own answer to "what does this order still owe", so the submit
406
+ // contract names the right paths on a re-offer where some are already paid.
407
+ owes: packet.owes.map((owed) => owed.path),
405
408
  };
406
409
  // Permissions arrive PRE-NORMALIZED in the spec. `prepare` ran
407
410
  // `normalizeStepPermissions` over the step's `x.harness` options at cache
@@ -20,9 +20,12 @@
20
20
  * 3. RUN + RACE — the runner shells the command out while the lease loop runs.
21
21
  * Whichever settles first wins (plan decision 9):
22
22
  * - an ordinary command settles (any exit code, or a machinery error) ⇒
23
- * build a receipt and `submit` it to every owed path. A payload reject
24
- * follows those submits. Exit 0 means the receipt/reject delivery won;
25
- * the receipt's exit code still carries the command result.
23
+ * build a receipt. A payload reject is delivered FIRST (the hub refuses
24
+ * a reject once the claim has closed, and the last owed submit is what
25
+ * closes it); then `submit` the receipt to every owed path, unless that
26
+ * reject closed the run, in which case the owed paths stay debts. Exit 0
27
+ * means the receipt/reject delivery won; the receipt's exit code still
28
+ * carries the command result.
26
29
  * - a judge command exits 0 ⇒ submit its receipt; a non-zero exit ⇒ send
27
30
  * `reject` for `order.judge` without a receipt; signal or machinery
28
31
  * failure ⇒ no verdict, leave the claim for the reap path.
@@ -243,6 +246,102 @@ export function createExecLoop(opts) {
243
246
  return 'reject-failed';
244
247
  }
245
248
  }
249
+ /**
250
+ * Deliver a PAYLOAD reject before the owed submits, and say whether this
251
+ * worker is finished.
252
+ *
253
+ * The distinction from `issueReject` is the third outcome. A judge reject is
254
+ * always the end of the run; a payload reject may leave the claim open, and
255
+ * when it does the owed receipts still have to land. So this returns either a
256
+ * terminal `ExecOutcome` or the sentinel `'continue'`.
257
+ *
258
+ * refused / threw → terminal. `issueReject` has already logged it and
259
+ * settled the lease. Nothing is submitted: a reject that
260
+ * did not land must not be followed by a receipt that
261
+ * greens the path the reject was protesting.
262
+ * landed, closed → terminal `'rejected'`. The rejected path was consumed
263
+ * by this firing, the hub closed the run `no_work`, and
264
+ * the owed paths stay debts for the next firing.
265
+ * landed, still open → `'continue'`. The rejected path was not consumed
266
+ * here, so the claim and the consume fingerprint are
267
+ * both intact and every owed submit proceeds normally.
268
+ *
269
+ * `closed` is read from the hub's own response rather than re-derived from the
270
+ * order, because the consumed-input test lives in the hub
271
+ * (`reject-artifact.ts` checks `runRow.fingerprint`, which is what the engine
272
+ * recorded at claim time — not what the def declares the step consumes).
273
+ */
274
+ async function relayPayloadReject(path, text, owed) {
275
+ let res;
276
+ try {
277
+ res = await hub.reject({ workflow, run: runId, path, text });
278
+ }
279
+ catch (e) {
280
+ opts.err(`owenloop work exec: reject of ${path} failed: ${errMsg(e)}`);
281
+ // Nothing has been submitted yet, so unlike the post-submit case there
282
+ // are no committed receipts to reason about. Release and let the step be
283
+ // re-offered.
284
+ lease.stop('reject-failed');
285
+ await leasePromise;
286
+ return 'reject-failed';
287
+ }
288
+ if (res.ok !== true) {
289
+ opts.err(`owenloop work exec: reject of ${path} was refused: ${res.text}`);
290
+ lease.stop('reject-failed', res.closed === true ? { release: false } : undefined);
291
+ await leasePromise;
292
+ return 'reject-failed';
293
+ }
294
+ if (res.closed === true) {
295
+ opts.out(`owenloop work exec: rejected ${path} — run closed, ${owed} owed path(s) left as debts`);
296
+ lease.stop('rejected', { release: false });
297
+ await leasePromise;
298
+ return 'rejected';
299
+ }
300
+ opts.out(`owenloop work exec: rejected ${path} (not consumed by this firing) — submitting owed receipts`);
301
+ return 'continue';
302
+ }
303
+ /**
304
+ * Relay the child's own output to this process's stderr when the command did
305
+ * not succeed.
306
+ *
307
+ * ## Why this exists
308
+ *
309
+ * Until this was added, a command step that failed produced a worker log that
310
+ * named the failure and said NOTHING about its cause. The runner captures the
311
+ * last 4 KiB of combined stdout+stderr as `outputTail` and puts it in the
312
+ * receipt — but a receipt only reaches a human if the submit is ACCEPTED, and
313
+ * the most common command-step failure is precisely the one where it is not:
314
+ * the script dies before printing a payload line, so the receipt has no
315
+ * `payload` key and `merge`'s schema rejects it. The one artifact carrying the
316
+ * diagnosis was discarded by the same event that made it necessary.
317
+ *
318
+ * Measured on `wf_40bd0c3f6783f9d31291d74d`: the `merger` step failed four
319
+ * times across two shifts and one foreground `owenloop work exec`, and every
320
+ * one of those logs contained the same three lines — holding, running,
321
+ * schema-rejected — with no trace of what the child said. Reproducing the
322
+ * script by hand outside the engine was the only way to see its stderr.
323
+ *
324
+ * `outputTail` is already capped at 4 KiB by the runner, so this cannot flood
325
+ * a log. Each line is prefixed so the child's words are never mistaken for
326
+ * exec's own.
327
+ */
328
+ function relayChildOutput(result, step) {
329
+ if (result.exitCode === 0 && result.error === undefined)
330
+ return;
331
+ const how = result.error !== undefined
332
+ ? `could not be run (${result.error})`
333
+ : result.signal !== undefined
334
+ ? `was killed by ${result.signal}`
335
+ : `exited ${result.exitCode}`;
336
+ opts.err(`owenloop work exec: the command for step '${step}' ${how}; its last output follows`);
337
+ const tail = result.outputTail.replace(/\n+$/, '');
338
+ if (tail === '') {
339
+ opts.err(' (the command produced no output)');
340
+ return;
341
+ }
342
+ for (const line of tail.split('\n'))
343
+ opts.err(` | ${line}`);
344
+ }
246
345
  /** Build the receipt and submit it to every owed path. */
247
346
  async function submitReceipt(result, order, resolvedCommand) {
248
347
  if (signalled) {
@@ -255,6 +354,9 @@ export function createExecLoop(opts) {
255
354
  await leasePromise;
256
355
  return 'killed';
257
356
  }
357
+ // Before any of the branches below decide what to do about the failure.
358
+ // Every one of them is reachable with a useless log otherwise.
359
+ relayChildOutput(result, order.step);
258
360
  const parsedPayload = parsePayloadLine(result.payloadLine, result.payloadOverCap);
259
361
  if (order.judge !== undefined) {
260
362
  if (result.exitCode === null) {
@@ -286,6 +388,54 @@ export function createExecLoop(opts) {
286
388
  run: runId,
287
389
  step: order.step,
288
390
  }, parsedPayload);
391
+ // ---- the payload reject goes FIRST, and it is not an ordering nicety ----
392
+ //
393
+ // It used to run after every owed submit, on the reasoning that "all owed
394
+ // submissions must land before invalidating a consumed input; rejection
395
+ // moves the consume fingerprint and would born-reject later submits from
396
+ // this run". The second half of that sentence is true. The first half made
397
+ // the reject UNDELIVERABLE, because the submits it waited on are what kill
398
+ // the claim it needs.
399
+ //
400
+ // The hub refuses a reject from a run whose claim has closed
401
+ // (`hub-core/src/verbs/reject-artifact.ts`: `held` requires
402
+ // `runRow.outcome === undefined`, and the refusal is explicit —
403
+ // "is not currently held by an open claim — nothing was rejected"). A step's
404
+ // last owed submit closes the run. So for the single-owed-path case — which
405
+ // is every gate in the delivery workflow — submit-then-reject could only
406
+ // ever produce the pair observed on `run_ecfedb23a84194e446159e67`:
407
+ //
408
+ // submitted receipt to mergeable (green)
409
+ // reject of pr was refused: ... is not currently held by an open claim
410
+ //
411
+ // The gate greened its own output and its reject evaporated, so `merger`
412
+ // proceeded on a PR the gate had explicitly refused to confirm. The def-side
413
+ // cascade that was supposed to un-green `mergeable` never fired, because it
414
+ // hangs off a `pr` rejection that never happened.
415
+ //
416
+ // Rejecting first is correct in both directions, and which one applies is
417
+ // the hub's answer, not a guess:
418
+ //
419
+ // `closed: true` — the rejected path WAS one of this firing's consumed
420
+ // inputs, so the hub closed the run `no_work` (not `failed`: no attempt
421
+ // is burned). The owed paths stay debts and the step re-fires against the
422
+ // rebuilt input. Skipping the submits here is not a loss — an artifact
423
+ // derived from an input this same command just declared bad is exactly
424
+ // what the engine's dead-input cascade would have thrown away anyway.
425
+ // This is also the branch that makes the old born-reject warning moot:
426
+ // there are no later submits to born-reject.
427
+ //
428
+ // `closed: false` — the rejected path was NOT consumed by this firing, so
429
+ // the claim is still open and the fingerprint has not moved. Fall through
430
+ // and submit every owed path exactly as before.
431
+ //
432
+ // A REFUSED reject now submits nothing. That is the point: previously the
433
+ // receipt had already landed and greened a path whose gate had failed.
434
+ if (order.judge === undefined && parsedPayload.reject !== undefined) {
435
+ const rejected = await relayPayloadReject(parsedPayload.reject.path, parsedPayload.reject.text, order.owes.length);
436
+ if (rejected !== 'continue')
437
+ return rejected;
438
+ }
289
439
  for (const owe of order.owes) {
290
440
  let res;
291
441
  try {
@@ -332,12 +482,6 @@ export function createExecLoop(opts) {
332
482
  }
333
483
  opts.out(`owenloop work exec: submitted receipt to ${owe.path} (${outcome})`);
334
484
  }
335
- if (order.judge === undefined && parsedPayload.reject !== undefined) {
336
- // All owed submissions must land before invalidating a consumed input;
337
- // rejection moves the consume fingerprint and would born-reject later
338
- // submits from this run.
339
- return issueReject(parsedPayload.reject.path, parsedPayload.reject.text, 'rejected');
340
- }
341
485
  // Every owed path landed — the run has closed, so stop WITHOUT releasing.
342
486
  lease.stop('submitted', { release: false });
343
487
  await leasePromise;
@@ -108,6 +108,14 @@ export const ADMITTED_OWENLOOP_KEYS = new Set([
108
108
  'OWENLOOP_NO_KEYCHAIN',
109
109
  // `holdSession` — src/roles/hold.ts. The fallback when `--session` is absent.
110
110
  'OWENLOOP_SESSION',
111
+ // `owenloopConfigDir` — src/config-dir.ts. Scopes owenloop's OWN config
112
+ // directory (`settings.json`, `credentials.json`, `allowed_signers`) without
113
+ // touching `XDG_CONFIG_HOME`, which the rest of the operator's toolchain also
114
+ // reads. A path, not credential material — but the credential FILE backend
115
+ // resolves under it (`readStoredCredential` → `configDir` → src/hub.ts), so a
116
+ // mount that does not see this variable falls back to `XDG_CONFIG_HOME` and
117
+ // reads a DIFFERENT credential store than the shift that spawned it.
118
+ 'OWENLOOP_CONFIG_DIR',
111
119
  ]);
112
120
  /** The namespace this filter governs. Nothing outside it is ever touched. */
113
121
  const NAMESPACE = 'OWENLOOP_';
@@ -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,63 @@ 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, with no prompt. NOT `acceptEdits`, which auto-approves filesystem
190
+ * operations by category and applies no judgment to anything else, and NOT
191
+ * `dontAsk`, which DENIES an unapproved tool rather than consulting anyone —
192
+ * silently narrower than what the step asked for.
193
+ *
194
+ * MEASURED against SDK 0.3.220, `canUseTool` wired throughout: the classifier
195
+ * consulted the host on NONE of five probe commands, and emitted no
196
+ * `permission_denied` system message for any of them. Four ran, including
197
+ * `rm -rf` on an ABSOLUTE path outside the session cwd (verified by the
198
+ * target directory being gone afterwards), a `curl` to the public internet,
199
+ * and a read of a file under `$HOME` outside cwd.
200
+ *
201
+ * So `auto` does not, in practice, escalate to whoever hosts the session.
202
+ * Wiring `canUseTool` does not give `auto-safe` a human exception path — the
203
+ * callback is simply never reached. Anything that needs a person in the loop
204
+ * has to run under `ask`, whose `default` mode does route to the callback
205
+ * (measured on the same SDK build, including calls originating inside a
206
+ * subagent, which arrive carrying that subagent's `agentID`).
207
+ * - `full-access` → `bypassPermissions`. The only SDK mode that runs tools with
208
+ * no prompt at all, and the one the companion flag below exists for.
209
+ *
210
+ * `plan` has no neutral spelling on purpose: it is a different axis (what the
211
+ * agent may DO — explore only) rather than who approves.
212
+ */
213
+ const NEUTRAL_TO_SDK_MODE = Object.freeze({
214
+ 'ask': 'default',
215
+ 'auto-safe': 'auto',
216
+ 'full-access': 'bypassPermissions',
217
+ });
218
+ /** Values `preflight` accepts: the SDK's own union plus the neutral vocabulary. */
219
+ const ACCEPTED_PERMISSION_MODES = [
220
+ ...PERMISSION_MODES,
221
+ ...NEUTRAL_PERMISSION_MODES,
222
+ ];
223
+ /**
224
+ * Authored `permissionMode` → the SDK mode to send.
225
+ *
226
+ * Total by construction: an out-of-union value returns `undefined` and the
227
+ * caller drops it with a diagnostic, preserving the pre-existing behavior for a
228
+ * bag that lint never saw. A neutral value this adapter refuses (a `null` in the
229
+ * table) also returns `undefined`, and `preflight` has already refused it.
230
+ */
231
+ function toSdkPermissionMode(mode) {
232
+ if (isNeutralPermissionMode(mode)) {
233
+ const mapped = NEUTRAL_TO_SDK_MODE[mode];
234
+ return mapped === null ? undefined : mapped;
235
+ }
236
+ return PERMISSION_MODES.includes(mode) ? mode : undefined;
237
+ }
181
238
  /** The five-value closed union the SDK types `Options.effort` as. */
182
239
  const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
183
240
  /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
@@ -219,11 +276,23 @@ const OWENLOOP_CONTROL_DENY_SPECS = new Set([
219
276
  ]);
220
277
  function claudePreflight(permissions) {
221
278
  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
- });
279
+ const authoredMode = permissions.permissionMode;
280
+ if (authoredMode !== undefined) {
281
+ if (!ACCEPTED_PERMISSION_MODES.includes(authoredMode)) {
282
+ issues.push({
283
+ field: 'permissionMode',
284
+ message: `permissionMode must be one of ${ACCEPTED_PERMISSION_MODES.join('|')}`,
285
+ });
286
+ }
287
+ else if (isNeutralPermissionMode(authoredMode) && NEUTRAL_TO_SDK_MODE[authoredMode] === null) {
288
+ // Unreachable today — every neutral value maps here. Kept because the
289
+ // table's `null` arm is a real contract option, and a refusal that only
290
+ // exists once someone uses it is a refusal nobody has tested.
291
+ issues.push({
292
+ field: 'permissionMode',
293
+ message: `permissionMode '${authoredMode}' is unsupported by this adapter`,
294
+ });
295
+ }
227
296
  }
228
297
  if (permissions.effort !== undefined && !EFFORT_LEVELS.includes(permissions.effort)) {
229
298
  issues.push({ field: 'effort', message: `effort must be one of ${EFFORT_LEVELS.join('|')}` });
@@ -359,8 +428,12 @@ export function buildClaudeOptions(inputs, extra) {
359
428
  }
360
429
  }
361
430
  if (permissions.permissionMode !== undefined) {
362
- if (PERMISSION_MODES.includes(permissions.permissionMode)) {
363
- const mode = permissions.permissionMode;
431
+ // Neutral `full-access` lands here as `bypassPermissions`, so the companion
432
+ // flag below covers it too — that is the point of translating BEFORE the
433
+ // pairing rather than after it. Neutral `auto-safe` lands as `auto` and
434
+ // deliberately does NOT get the flag: it is still allowed to stop and ask.
435
+ const mode = toSdkPermissionMode(permissions.permissionMode);
436
+ if (mode !== undefined) {
364
437
  options.permissionMode = mode;
365
438
  // 'bypassPermissions' is IGNORED by the SDK without this companion flag.
366
439
  // Missing it is a silent downgrade to prompting, which in a headless run
@@ -371,7 +444,7 @@ export function buildClaudeOptions(inputs, extra) {
371
444
  else {
372
445
  extra.onEvent({
373
446
  kind: 'progress',
374
- text: `dropped unknown permissionMode '${permissions.permissionMode}' (expected one of ${PERMISSION_MODES.join('|')})`,
447
+ text: `dropped unknown permissionMode '${permissions.permissionMode}' (expected one of ${ACCEPTED_PERMISSION_MODES.join('|')})`,
375
448
  });
376
449
  }
377
450
  }
@@ -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);
@@ -216,6 +264,13 @@ function isPlainMap(v) {
216
264
  * keeps this list a complete statement of what the child needs.
217
265
  */
218
266
  const MOUNT_ENV_KEEP = ['HOME', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME'];
267
+ /**
268
+ * `OWENLOOP_CONFIG_DIR` rides the `OWENLOOP_*` allowlist below rather than this
269
+ * list, but it belongs to the same job: without it a mount whose parent scoped
270
+ * owenloop's config with `OWENLOOP_CONFIG_DIR` would fall back to
271
+ * `XDG_CONFIG_HOME` and read a DIFFERENT settings file than the shift that
272
+ * spawned it.
273
+ */
219
274
  /**
220
275
  * The environment for the owenloop mount, forwarded from THIS process.
221
276
  *