owenloop 0.5.4 → 0.5.5

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 (37) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/packages/work/src/agent/brief.js +57 -1
  3. package/dist/packages/work/src/agent/loop.d.ts +10 -1
  4. package/dist/packages/work/src/agent/loop.js +25 -0
  5. package/dist/packages/work/src/agent/workdir.d.ts +22 -0
  6. package/dist/packages/work/src/agent/workdir.js +80 -0
  7. package/dist/packages/work/src/exec/loop.d.ts +13 -1
  8. package/dist/packages/work/src/exec/loop.js +31 -0
  9. package/dist/packages/work/src/harness/claude.js +7 -1
  10. package/dist/packages/work/src/hold/mcp.d.ts +11 -2
  11. package/dist/packages/work/src/hold/mcp.js +69 -2
  12. package/dist/packages/work/src/hub/client.d.ts +8 -1
  13. package/dist/packages/work/src/hub/client.js +1 -0
  14. package/dist/packages/work/src/hub/types.d.ts +29 -0
  15. package/dist/packages/work/src/roles/agent-run.js +9 -1
  16. package/dist/packages/work/src/roles/exec.js +9 -0
  17. package/dist/packages/work/src/roles/shift.js +9 -1
  18. package/dist/packages/work/src/settings/settings.d.ts +20 -1
  19. package/dist/packages/work/src/settings/settings.js +23 -1
  20. package/dist/packages/work/src/shift/runtime.d.ts +7 -0
  21. package/dist/packages/work/src/shift/runtime.js +29 -4
  22. package/dist/packages/work/src/shift/spawn.d.ts +12 -2
  23. package/dist/packages/work/src/shift/spawn.js +16 -3
  24. package/dist/src/cli.js +54 -1
  25. package/dist/src/engine.d.ts +46 -1
  26. package/dist/src/engine.js +72 -0
  27. package/dist/src/index.d.ts +1 -1
  28. package/dist/src/index.js +1 -1
  29. package/dist/src/model.d.ts +29 -5
  30. package/dist/src/model.js +63 -14
  31. package/dist/src/types.d.ts +8 -2
  32. package/docs/cli.md +34 -0
  33. package/package.json +1 -1
  34. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  35. package/plugins/claude-code/plugin/.mcp.json +1 -1
  36. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  37. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
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.5](https://github.com/typicalday/owenloop/compare/v0.5.4...v0.5.5) (2026-08-15)
8
+
9
+
10
+ ### Features
11
+
12
+ * give every step agent a channel to ask a human ([#168](https://github.com/typicalday/owenloop/issues/168)) ([fa9e5f0](https://github.com/typicalday/owenloop/commit/fa9e5f08d3a9f55c6e95cc504966a6389ec699c4))
13
+ * let a shift operator declare where work may happen ([#166](https://github.com/typicalday/owenloop/issues/166)) ([71e9412](https://github.com/typicalday/owenloop/commit/71e9412c534ba826490dc62464989b47a6f551fe))
14
+
7
15
  ## [0.5.4](https://github.com/typicalday/owenloop/compare/v0.5.3...v0.5.4) (2026-08-15)
8
16
 
9
17
 
@@ -28,7 +28,12 @@ export function renderBrief(templateContent, spec) {
28
28
  .join(spec.account)
29
29
  .split(SHIFT_TOKEN)
30
30
  .join(spec.shiftId ?? '');
31
- const blocks = [renderRoutingLine(spec), renderSubmitContract(spec), substituted];
31
+ const blocks = [
32
+ renderRoutingLine(spec),
33
+ renderSubmitContract(spec),
34
+ renderEscalationContract(spec),
35
+ substituted,
36
+ ];
32
37
  return blocks.filter((b) => b !== '').join('\n\n');
33
38
  }
34
39
  /**
@@ -75,6 +80,57 @@ function renderSubmitContract(spec) {
75
80
  '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
81
  ].join('\n');
77
82
  }
83
+ /**
84
+ * What an agent does when it CANNOT complete the order, stated to every agent on
85
+ * every run, right after the submit contract.
86
+ *
87
+ * WHY THIS EXISTS. The submit contract closes one hole (an agent that finished
88
+ * but did not know how to say so). This closes the opposite one: an agent that
89
+ * did NOT finish and has no legal way to say so. Until `ask` shipped there were
90
+ * exactly two exits from a step, and a blocked agent had to pick the less
91
+ * damaging:
92
+ * - Submit anyway. The artifact goes green on a value the agent does not
93
+ * believe, and every downstream step builds on it. Observed on a real run:
94
+ * a planner that could read nothing produced a confident, fictional plan and
95
+ * a builder started executing it.
96
+ * - End the turn without submitting. The lease lapses, the task re-arms, and a
97
+ * fresh worker starts from the identical missing information. It repeats
98
+ * until the stall cap, spending a full model run per attempt to relearn the
99
+ * same blocker, and no human is ever told.
100
+ * Neither reaches a person. Both were watched happening. The tool is the fix and
101
+ * this paragraph is what makes the tool reachable — a mounted tool nobody is
102
+ * told about is dead code.
103
+ *
104
+ * WHY IT NAMES THE COST. Models are heavily biased toward producing an answer,
105
+ * and an escalation path that reads as failure will not be taken. So the text
106
+ * states the two facts that make asking the correct move rather than the
107
+ * cowardly one: it costs no attempts, and guessing is worse than asking.
108
+ *
109
+ * WHY IT STATES THE BAR. "Ask whenever unsure" would turn every ambiguity into a
110
+ * human interrupt and the channel would be ignored within a day. The bar is
111
+ * concrete: ask when the missing thing cannot be recovered by working — reading
112
+ * the repo, running a read-only command, re-reading the inputs — because those
113
+ * are exactly the cases where another attempt cannot help.
114
+ *
115
+ * Rendered only when the order owes something, for the same reason the submit
116
+ * contract is: `ask` takes an owed path as its argument, and a contract that has
117
+ * to write `<path>` into its own example teaches the call shape while leaving
118
+ * the one argument that matters unanswered.
119
+ *
120
+ * Vendor-neutral by construction — names owenloop's own tool and mount only.
121
+ */
122
+ function renderEscalationContract(spec) {
123
+ const owed = (spec.owes ?? []).filter((p) => p !== '');
124
+ if (owed.length === 0)
125
+ return '';
126
+ return [
127
+ `If you CANNOT produce what this order asks for, do not guess and do not end your turn silently — call the \`ask\` tool on the same \`owenloop\` MCP server and stop.`,
128
+ `Example: \`ask({"path": "${owed[0]}", "question": "<the specific decision or fact you need from a person>", "context": "<what you already tried>"})\`.`,
129
+ 'Ask when the thing you are missing cannot be recovered by working: a required input is absent, wrong, or contradicts another input; the order asks for a judgment only the operator can make; or you cannot reach something the order depends on. Do NOT ask for anything you could resolve by reading the repository, re-reading your inputs, or running a read-only command — do that first.',
130
+ 'Asking costs you nothing: it is not a failed attempt, it consumes none of this step\'s retry budget, and it is the correct outcome when the honest answer is "I do not know". Submitting a value you do not believe is worse than asking — it goes green and every later step builds on it. Ending your turn without submitting is worse than asking — this step simply re-runs with the same information missing, and no person is ever told.',
131
+ 'After you ask, your run is over. A human answers on the same artifact and a fresh attempt starts with their answer attached.',
132
+ ].join('\n');
133
+ }
78
134
  /**
79
135
  * The run's depth, stated to the agent in one line, PREPENDED rather than
80
136
  * substituted into a token.
@@ -6,7 +6,7 @@ import type { HarnessAdapter } from '../harness/contract.ts';
6
6
  import { type SessionRecord } from '../harness/session-store.ts';
7
7
  import { type CapabilityModelMap, type CapabilityResolution } from './capability-model.ts';
8
8
  /** Discriminated result of one worker life; the role maps these to exit codes. */
9
- export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unresolvable-capability' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
9
+ export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'workdir-denied' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unresolvable-capability' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
10
10
  /**
11
11
  * Locate the normalized step spec for an order. Injected because the lookup is
12
12
  * I/O (the verified workflow store) and because resolving the local definition
@@ -52,6 +52,15 @@ export interface AgentRunLoopOptions {
52
52
  shiftId?: string;
53
53
  /** cwd for the step agent when the order packet carries no `workdir`. */
54
54
  cwd: string;
55
+ /**
56
+ * The directories this MACHINE's operator declared as places work may happen,
57
+ * already resolved to absolute paths by `resolveAllowedWorkdirRoots`.
58
+ *
59
+ * NOT `workRoot`. `workRoot` is the single directory owenloop CREATES worktrees
60
+ * under; this is the set of directories an ORDER is permitted to name as its
61
+ * cwd. UNSET or EMPTY means NO RESTRICTION.
62
+ */
63
+ allowedWorkdirRoots?: string[];
55
64
  loadStep: StepLoader;
56
65
  resolveAdapter: AdapterResolver;
57
66
  /**
@@ -57,6 +57,7 @@
57
57
  * back would waste a whole re-offer cycle to learn something already known.
58
58
  */
59
59
  import { existsSync } from 'node:fs';
60
+ import { isWorkdirAllowed } from "./workdir.js";
60
61
  import { createLeaseLoop } from "../lease/loop.js";
61
62
  import { isResumeUnavailable } from "../harness/contract.js";
62
63
  import { preflightStepPermissions } from "../harness/permissions.js";
@@ -363,6 +364,30 @@ export function createAgentRunLoop(opts) {
363
364
  }
364
365
  stepName = packet.step;
365
366
  recordCwd = packet.workdir ?? opts.cwd;
367
+ // MACHINE POLICY. The operator who started this shift named the directories
368
+ // work may happen in (`owenloop shift start --work-root`, or
369
+ // `allowedWorkdirRoots` in settings). This worker is one of only two
370
+ // processes that ever sees `OrderPacket.workdir` — the shift's `whats_next`
371
+ // sweep receives a `WorkOrder`, which carries no such field — so the check
372
+ // belongs here and cannot be hoisted into dispatch.
373
+ //
374
+ // RELEASED, not failed, and BEFORE the step spec is loaded or any provider
375
+ // session is opened. Declining work this machine was not configured to host
376
+ // is not a failure of the work: the targeted release returns the order to
377
+ // the hub's pickup window, where a differently-configured machine can take
378
+ // it. `misroute` takes the same shape for the same reason.
379
+ //
380
+ // ONLY an order-NAMED workdir is checked. When the packet names none this
381
+ // worker uses `<workRoot>/<workflow>/<run>/` — a directory owenloop ITSELF
382
+ // created under the operator's own cache root — and denying that would deny
383
+ // every agent order on a machine that declared any root at all.
384
+ if (packet.workdir !== undefined &&
385
+ !isWorkdirAllowed(packet.workdir, opts.allowedWorkdirRoots ?? [])) {
386
+ const roots = (opts.allowedWorkdirRoots ?? []).join(', ');
387
+ opts.err(`owenloop work agent-run: step '${packet.step}' (${order}) names workdir '${packet.workdir}', ` +
388
+ `which is outside every work root this machine declared (${roots}) — releasing for the pickup window`);
389
+ return releaseWith('workdir-denied', 'workdir-denied');
390
+ }
366
391
  // The step spec. No bundle / no spec ⇒ we cannot brief anybody; release so
367
392
  // the order lapses back through the hub's pickup window.
368
393
  let material;
@@ -22,6 +22,28 @@ export declare function resolveWorkRepo(env: Record<string, string | undefined>,
22
22
  * run's directory and must never be removed.
23
23
  */
24
24
  export declare function isUnderWorkRoot(dir: string, workRoot: string): boolean;
25
+ /**
26
+ * Resolve the declared roots: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` >
27
+ * `settings.allowedWorkdirRoots` > none. Mirrors `resolveWorkRoot`'s precedence
28
+ * shape, so there is one rule to remember across this file.
29
+ *
30
+ * The env var is PATH-style `:`-separated because it names a list of
31
+ * directories and that is the convention every operator already knows for one.
32
+ * It REPLACES the settings list rather than adding to it — a narrowing override
33
+ * that could only ever widen would not be a usable safety control.
34
+ *
35
+ * Every entry is resolved to an absolute path against `cwd`, so a relative
36
+ * declaration means what the operator saw when they typed it.
37
+ */
38
+ export declare function resolveAllowedWorkdirRoots(env: Record<string, string | undefined>, settingsRoots: string[] | undefined, cwd: string): string[];
39
+ /**
40
+ * Is `workdir` inside (or equal to) one of `roots`?
41
+ *
42
+ * An EMPTY `roots` returns true for every path — that is the unrestricted
43
+ * default, not an accident, and it is why callers can pass the resolved list
44
+ * unconditionally instead of branching on whether the operator declared one.
45
+ */
46
+ export declare function isWorkdirAllowed(workdir: string, roots: string[]): boolean;
25
47
  export interface EnsureWorkDirOptions {
26
48
  workRoot: string;
27
49
  workflow: string;
@@ -81,6 +81,86 @@ export function isUnderWorkRoot(dir, workRoot) {
81
81
  const rel = relative(resolve(workRoot), resolve(dir));
82
82
  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
83
83
  }
84
+ /**
85
+ * ── OPERATOR-DECLARED WORKDIR ROOTS ─────────────────────────────────────────
86
+ *
87
+ * A SEPARATE MECHANISM FROM `workRoot` ABOVE, and the two are easy to confuse,
88
+ * so state the difference once:
89
+ *
90
+ * | | `workRoot` (singular) | `allowedWorkdirRoots` (plural) |
91
+ * |---|---|---|
92
+ * | what it is | a directory owenloop WRITES INTO | a list of directories orders may NAME |
93
+ * | who supplies the path | this machine's operator | the run, via `OrderPacket.workdir` |
94
+ * | what it does | holds `<workflow>/<run>/` per-run dirs | permits or refuses a cwd |
95
+ * | unset means | default to `<cacheDir>/work` | NO RESTRICTION |
96
+ *
97
+ * WHY THIS EXISTS. `OrderPacket.workdir` is an opaque location hint the HUB
98
+ * supplies and the worker obeys (`src/exec/loop.ts`, `src/agent/loop.ts`). Since
99
+ * a def may set it from a declared INPUT — `workdirFrom: target.path`, the
100
+ * grammar owenloop 0.5.4 added — the string can originate with whoever started
101
+ * the run, and a shift is not project-bound. So without a local check, a run on
102
+ * the hub picks any absolute path on the operator's machine as a working
103
+ * directory.
104
+ *
105
+ * The boundary belongs to the MACHINE'S OWNER, not to the hub: the person who
106
+ * starts a shift decides which directories that shift may work in. That is why
107
+ * the declaration is a `shift start` flag / settings key / env var and never a
108
+ * def field, a hub policy, or anything a run can influence.
109
+ *
110
+ * DEFAULT-OPEN, DELIBERATELY. An empty list means every path is allowed, which
111
+ * preserves the behaviour of every shift running today. Making it default-closed
112
+ * would break every existing shift on upgrade, and — worse — would do so as a
113
+ * silent refusal of work the hub believes was accepted.
114
+ *
115
+ * INCLUSIVE OF THE ROOT ITSELF, unlike `isUnderWorkRoot`. An operator who
116
+ * declares `/Users/alex/code/dev` means "this project", and `target.path` for
117
+ * that project IS that exact directory. `isUnderWorkRoot` excludes `dir ===
118
+ * root` because there it guards a DELETION and the root must survive; here it
119
+ * guards a cwd, and there is nothing to protect the root from.
120
+ */
121
+ /** Split a PATH-style (`:`-separated) list of directories, dropping empties. */
122
+ function splitRootList(raw) {
123
+ return raw
124
+ .split(':')
125
+ .map((entry) => entry.trim())
126
+ .filter((entry) => entry !== '');
127
+ }
128
+ /**
129
+ * Resolve the declared roots: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` >
130
+ * `settings.allowedWorkdirRoots` > none. Mirrors `resolveWorkRoot`'s precedence
131
+ * shape, so there is one rule to remember across this file.
132
+ *
133
+ * The env var is PATH-style `:`-separated because it names a list of
134
+ * directories and that is the convention every operator already knows for one.
135
+ * It REPLACES the settings list rather than adding to it — a narrowing override
136
+ * that could only ever widen would not be a usable safety control.
137
+ *
138
+ * Every entry is resolved to an absolute path against `cwd`, so a relative
139
+ * declaration means what the operator saw when they typed it.
140
+ */
141
+ export function resolveAllowedWorkdirRoots(env, settingsRoots, cwd) {
142
+ const override = env['OWENLOOP_ALLOWED_WORKDIR_ROOTS'];
143
+ const raw = override !== undefined && override.trim() !== ''
144
+ ? splitRootList(override)
145
+ : (settingsRoots ?? []).map((entry) => entry.trim()).filter((entry) => entry !== '');
146
+ return raw.map((entry) => resolve(cwd, entry));
147
+ }
148
+ /**
149
+ * Is `workdir` inside (or equal to) one of `roots`?
150
+ *
151
+ * An EMPTY `roots` returns true for every path — that is the unrestricted
152
+ * default, not an accident, and it is why callers can pass the resolved list
153
+ * unconditionally instead of branching on whether the operator declared one.
154
+ */
155
+ export function isWorkdirAllowed(workdir, roots) {
156
+ if (roots.length === 0)
157
+ return true;
158
+ const target = resolve(workdir);
159
+ return roots.some((root) => {
160
+ const rel = relative(resolve(root), target);
161
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
162
+ });
163
+ }
84
164
  function defaultRunGit(args, cwd) {
85
165
  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
86
166
  return { status: r.status, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() };
@@ -22,7 +22,7 @@ import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
22
22
  */
23
23
  export declare const CONSUMES_INLINE_MAX_BYTES = 65536;
24
24
  /** Discriminated result of an exec run; the role maps these to exit codes. */
25
- export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'unresolved-instructions' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'rejected' | 'judge-rejected' | 'judge-no-verdict' | 'reject-failed' | 'stopped';
25
+ export type ExecOutcome = 'submitted' | 'completed' | 'misroute' | 'workdir-denied' | 'unresolved-instructions' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'submit-rejected' | 'submit-failed' | 'rejected' | 'judge-rejected' | 'judge-no-verdict' | 'reject-failed' | 'stopped';
26
26
  export interface ExecLoopOptions {
27
27
  hub: HubClient;
28
28
  runner: CommandRunner;
@@ -40,6 +40,18 @@ export interface ExecLoopOptions {
40
40
  instructions: InstructionResolver;
41
41
  /** cwd for the command when the order packet carries no `workdir`. */
42
42
  cwd: string;
43
+ /**
44
+ * The directories this MACHINE's operator declared as places work may happen,
45
+ * already resolved to absolute paths by `resolveAllowedWorkdirRoots`.
46
+ *
47
+ * NOT `workRoot`. `workRoot` is the single directory owenloop CREATES worktrees
48
+ * under; this is the set of directories an ORDER is permitted to name as its
49
+ * cwd. They answer different questions and neither derives from the other.
50
+ *
51
+ * UNSET or EMPTY means NO RESTRICTION — the pre-existing behaviour, and the
52
+ * only default that does not break every shift already running.
53
+ */
54
+ allowedWorkdirRoots?: string[];
43
55
  sleep: (ms: number) => Promise<void>;
44
56
  now: () => number;
45
57
  random?: () => number;
@@ -45,6 +45,7 @@ import { createHash } from 'node:crypto';
45
45
  import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
46
46
  import { tmpdir } from 'node:os';
47
47
  import { join, resolve } from 'node:path';
48
+ import { isWorkdirAllowed } from "../agent/workdir.js";
48
49
  import { createLeaseLoop } from "../lease/loop.js";
49
50
  import { parsePayloadLine } from "./payload.js";
50
51
  import { buildReceipt } from "./receipt.js";
@@ -507,6 +508,36 @@ export function createExecLoop(opts) {
507
508
  await leasePromise;
508
509
  return 'misroute';
509
510
  }
511
+ // MACHINE POLICY, checked before any instruction is resolved and long before
512
+ // anything is spawned. The operator who started this shift named the
513
+ // directories work may happen in (`owenloop shift start --work-root`, or
514
+ // `allowedWorkdirRoots` in settings); an order naming anything else is
515
+ // refused HERE, in the worker, because the worker is the only process that
516
+ // ever sees `OrderPacket.workdir` — the shift's `whats_next` sweep receives
517
+ // a `WorkOrder`, which has no such field.
518
+ //
519
+ // RELEASED, not failed. This is not a defect in the order and not a failure
520
+ // of the work: it is one machine declining work it was not configured to
521
+ // host. A targeted release returns the order to the hub's pickup window so a
522
+ // differently-configured machine can take it, exactly like `misroute`.
523
+ // Submitting a failure receipt instead would kill a run that is perfectly
524
+ // valid somewhere else.
525
+ //
526
+ // ONLY an order-NAMED workdir is checked. An order that declares none
527
+ // inherits this worker's own launch directory, which the operator chose
528
+ // themselves when they started the shift — bounding an operator's own
529
+ // choice by the operator's own roots protects nobody and would deny every
530
+ // step that legitimately declares no workdir.
531
+ if (order.workdir !== undefined &&
532
+ !isWorkdirAllowed(order.workdir, opts.allowedWorkdirRoots ?? [])) {
533
+ const roots = (opts.allowedWorkdirRoots ?? []).join(', ');
534
+ opts.err(`owenloop work exec: step '${order.step}' (${workflow}/${runId}) names workdir ` +
535
+ `'${order.workdir}', which is outside every work root this machine declared (${roots}) — ` +
536
+ 'releasing for the pickup window');
537
+ lease.stop('workdir-denied'); // targeted release — local policy, not a failure
538
+ await leasePromise;
539
+ return 'workdir-denied';
540
+ }
510
541
  let resolvedCommand;
511
542
  let resolvedBundleDir;
512
543
  try {
@@ -258,7 +258,13 @@ const OWENLOOP_ONLY_NETWORK_TOOLS = new Set([
258
258
  * unrestricted-network readers. */
259
259
  const READ_ONLY_OWENLOOP_ONLY_NETWORK_TOOLS = [...READ_ONLY_TOOLS]
260
260
  .filter((tool) => OWENLOOP_ONLY_NETWORK_TOOLS.has(tool));
261
- const BORN_BOUND_OWENLOOP_TOOL_NAMES = ['get_order', 'submit'];
261
+ // The tools a born-bound step agent gets no matter how restricted it is.
262
+ // `ask` is here for the same reason `submit` is: without it a restricted agent
263
+ // has no legal way to END. It could previously only submit (fabricating when it
264
+ // did not know) or fall silent (re-arming the step into a retry storm). `ask` is
265
+ // about the agent's OWN owed artifact, so unlike `reject` it grants no authority
266
+ // over anyone else's work and there is no reason to withhold it under isolation.
267
+ const BORN_BOUND_OWENLOOP_TOOL_NAMES = ['get_order', 'submit', 'ask'];
262
268
  const BORN_BOUND_OWENLOOP_TOOLS = BORN_BOUND_OWENLOOP_TOOL_NAMES.map((name) => `mcp__owenloop__${name}`);
263
269
  const RESTRICTED_OWENLOOP_DENIED_TOOLS = ['mcp__owenloop__reject'];
264
270
  const OWENLOOP_CONTROL_TOOLS = new Set([
@@ -4,7 +4,7 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes three bare tools the model uses to do its order:
7
+ * server exposes four bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
@@ -14,6 +14,15 @@
14
14
  * - `reject` → invalidate a consumed artifact through the claiming step's
15
15
  * server-derived authority; the client never supplies `by`. A CLOSED reject
16
16
  * also stops the lease loop without releasing the already-closed claim.
17
+ * - `ask` → stop and escalate to a human about an OWED output path. The
18
+ * third exit. `submit` and `reject` both assume the worker can finish; until
19
+ * `ask` existed a worker that genuinely could not had only two moves, and
20
+ * both damaged the run: submit something it did not believe (greens a
21
+ * fabrication that every downstream step then builds on), or end its turn
22
+ * silently (the task re-arms and a fresh worker relearns the same blocker
23
+ * until the stall cap). `ask` holds the artifact with no counter movement
24
+ * and surfaces the question to an operator, who answers with
25
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
17
26
  *
18
27
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
28
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -33,7 +42,7 @@ import { type SubmissionKeyManager } from '../submit-proof.ts';
33
42
  import type { SshProcessAdapter } from '../../../../src/crypto/ssh.ts';
34
43
  import type { ConsumedVerifier } from '../consumed-verifier.ts';
35
44
  import { type HoldLoop } from './loop.ts';
36
- export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject"];
45
+ export declare const HOLD_MCP_TOOL_NAMES: readonly ["get_order", "submit", "reject", "ask"];
37
46
  export type HoldMcpToolName = (typeof HOLD_MCP_TOOL_NAMES)[number];
38
47
  export interface HoldMcpDeps {
39
48
  hub: HubClient;
@@ -4,7 +4,7 @@
4
4
  * A born-bound work-holder: the D2 stamped Step Agent's frontmatter declares
5
5
  * `mcpServers.owenloop = owenloop work hold --order <wf>/<run> --origin <url> --mcp`,
6
6
  * so when the Step Agent session boots it launches THIS as a stdio MCP server. The
7
- * server exposes three bare tools the model uses to do its order:
7
+ * server exposes four bare tools the model uses to do its order:
8
8
  * - `get_order` → the order packet (prompt, inputs, owed outputs) for the run
9
9
  * this holder is bound to. No ids are arguments — they came in on argv, never
10
10
  * through the model.
@@ -14,6 +14,15 @@
14
14
  * - `reject` → invalidate a consumed artifact through the claiming step's
15
15
  * server-derived authority; the client never supplies `by`. A CLOSED reject
16
16
  * also stops the lease loop without releasing the already-closed claim.
17
+ * - `ask` → stop and escalate to a human about an OWED output path. The
18
+ * third exit. `submit` and `reject` both assume the worker can finish; until
19
+ * `ask` existed a worker that genuinely could not had only two moves, and
20
+ * both damaged the run: submit something it did not believe (greens a
21
+ * fabrication that every downstream step then builds on), or end its turn
22
+ * silently (the task re-arms and a fresh worker relearns the same blocker
23
+ * until the stall cap). `ask` holds the artifact with no counter movement
24
+ * and surfaces the question to an operator, who answers with
25
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
17
26
  *
18
27
  * Underneath the tools, the SAME lease loop the CLI `hold` runs keeps the order's
19
28
  * lease warm: `createHoldMcp` builds the loop with `onOrder` wired to capture the
@@ -30,7 +39,7 @@ import { textResult } from "../mcp/server.js";
30
39
  import { buildSubmitProof } from "../submit-proof.js";
31
40
  import { normalizeSubmitValue } from "../submit-value.js";
32
41
  import { createHoldLoop } from "./loop.js";
33
- export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject'];
42
+ export const HOLD_MCP_TOOL_NAMES = ['get_order', 'submit', 'reject', 'ask'];
34
43
  function errMsg(e) {
35
44
  return e instanceof Error ? e.message : String(e);
36
45
  }
@@ -261,10 +270,68 @@ export function createHoldMcp(deps) {
261
270
  }
262
271
  },
263
272
  };
273
+ const askTool = {
274
+ name: 'ask',
275
+ description: 'Stop and ask a human about an output path you OWE, when you cannot produce it honestly — a required input is missing, wrong, or contradictory, or the order asks for a decision only a person can make. Use this INSTEAD of submitting a guess and INSTEAD of ending your turn without submitting: a guess greens and poisons every step downstream, and ending silently just re-runs this same step until it burns its retry budget. Asking does not count as a failure and costs you no attempts. The step is held until a human answers; your run ends here.',
276
+ inputSchema: {
277
+ type: 'object',
278
+ required: ['path', 'question'],
279
+ properties: {
280
+ path: {
281
+ type: 'string',
282
+ description: 'The owed output path you are blocked on (one of the `owes` paths from get_order).',
283
+ },
284
+ question: {
285
+ type: 'string',
286
+ description: 'The specific question for the human. State what decision or fact you need, not just that you are stuck — this is the whole message they receive.',
287
+ },
288
+ context: {
289
+ type: 'string',
290
+ description: 'Optional: what you already tried, what you read, and why it was not enough. Saves the human from reconstructing it from logs.',
291
+ },
292
+ },
293
+ additionalProperties: false,
294
+ },
295
+ handler: async (args) => {
296
+ const gone = terminalGuard();
297
+ if (gone !== undefined)
298
+ return gone;
299
+ const path = args['path'];
300
+ const question = args['question'];
301
+ const context = args['context'];
302
+ if (typeof path !== 'string' || path.trim() === '') {
303
+ return textResult({ error: 'ask requires a non-empty string "path"' }, true);
304
+ }
305
+ if (typeof question !== 'string' || question.trim() === '') {
306
+ return textResult({ error: 'ask requires a non-empty string "question"' }, true);
307
+ }
308
+ if (context !== undefined && typeof context !== 'string') {
309
+ return textResult({ error: 'ask "context" must be a string when present' }, true);
310
+ }
311
+ try {
312
+ const res = await hub.ask({
313
+ workflow,
314
+ run,
315
+ path,
316
+ question,
317
+ ...(typeof context === 'string' && context.trim() !== '' ? { context } : {}),
318
+ });
319
+ // Asking ENDS the run. Same shape as submit/reject's closed branch:
320
+ // stop without releasing, because the hub already closed the claim.
321
+ if (res.closed === true)
322
+ loop.stop('asked', { release: false });
323
+ return textResult({ ok: res.ok, closed: res.closed ?? false, text: res.text });
324
+ }
325
+ catch (e) {
326
+ return textResult({ error: errMsg(e) }, true);
327
+ }
328
+ },
329
+ };
264
330
  const registrations = {
265
331
  get_order: getOrderTool,
266
332
  submit: submitTool,
267
333
  reject: rejectTool,
334
+ ask: askTool,
268
335
  };
269
336
  const selected = deps.tools ?? HOLD_MCP_TOOL_NAMES;
270
337
  return { tools: selected.map((name) => registrations[name]), loop };
@@ -1,4 +1,4 @@
1
- import type { GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
1
+ import type { AskRequest, AskResponse, GetOrderRequest, GetOrderResponse, HeartbeatRequest, HeartbeatResponse, PresencePingRequest, PresencePingResponse, ReleaseRequest, ReleaseResponse, RejectRequest, RejectResponse, ReportResolutionRequest, ReportResolutionResponse, SubmitRequest, SubmitResponse, WakeResponse, WhatsNextRequest, WhatsNextResponse, WhoamiResponse } from './types.ts';
2
2
  export interface HubClientOptions {
3
3
  /** Hub origin, e.g. `https://hub.owenloop.dev` (no trailing slash needed). */
4
4
  origin: string;
@@ -14,6 +14,13 @@ export interface HubClient {
14
14
  release(req: ReleaseRequest): Promise<ReleaseResponse>;
15
15
  submit(req: SubmitRequest): Promise<SubmitResponse>;
16
16
  reject(req: RejectRequest): Promise<RejectResponse>;
17
+ /**
18
+ * ESCALATION: the worker stops and asks a human about an artifact it OWES.
19
+ * Distinct from `reject`, which is a verdict on somebody else's delivered
20
+ * work. Holds the artifact (no counter moves) until a human answers with
21
+ * `owenloop retry <workflow> <path> --text "<answer>"`.
22
+ */
23
+ ask(req: AskRequest): Promise<AskResponse>;
17
24
  /**
18
25
  * Plan §6: record what this shift resolved the order's compound capability to,
19
26
  * BEFORE the harness launches. Idempotent on the hub by order id, so a
@@ -82,6 +82,7 @@ export function createHubClient(opts) {
82
82
  release: (req) => post('release', req),
83
83
  submit: (req) => post('submit', req),
84
84
  reject: (req) => post('reject', req),
85
+ ask: (req) => post('ask', req),
85
86
  reportResolution: (req) => post('report_resolution', req),
86
87
  whoami: () => get('whoami'),
87
88
  // Cursor is an opaque non-negative integer; omit it entirely to bootstrap
@@ -367,6 +367,35 @@ export interface RejectResponse extends HubResponse {
367
367
  ok: boolean;
368
368
  closed?: boolean;
369
369
  }
370
+ /**
371
+ * ESCALATION: the claiming worker cannot honestly build what it owes and stops
372
+ * to ask a person. `path` is one of the order's OWED paths — unlike `reject`,
373
+ * whose `path` is somebody else's delivered work, this is the worker's own debt.
374
+ *
375
+ * `by` is absent for the same reason it is absent on `reject`: the hub derives
376
+ * the actor from the claiming run's step, so a worker cannot ask on another
377
+ * step's behalf. `question` is what the human is being asked; `context` is
378
+ * optional supporting detail (what the worker already tried, which files it
379
+ * read) that rides the same reason-thread entry so the answering human does not
380
+ * have to reconstruct it from logs.
381
+ */
382
+ export interface AskRequest {
383
+ workflow: string;
384
+ run: string;
385
+ path: string;
386
+ question: string;
387
+ context?: string;
388
+ }
389
+ /**
390
+ * The ask verb's flattened envelope. `closed` reports whether the escalation
391
+ * closed the worker's run — it does, always: a worker that has asked has
392
+ * nothing further to do on this order, and holding the lease open would only
393
+ * let it expire into a reap.
394
+ */
395
+ export interface AskResponse extends HubResponse {
396
+ ok: boolean;
397
+ closed?: boolean;
398
+ }
370
399
  export interface WhoamiResponse extends HubResponse {
371
400
  orgId: string;
372
401
  orgName: string;
@@ -96,7 +96,7 @@ import { adapterFor, defaultHarnessId, registeredHarnessIds } from "../harness/r
96
96
  import { parseHarnessCarrier } from "../bundle/fetch.js";
97
97
  import { normalizeStepPermissions, validateHarnessOptions } from "../harness/permissions.js";
98
98
  import { appendSession, latestFor, sessionsPath } from "../harness/session-store.js";
99
- import { ensureWorkDir, resolveWorkRepo, resolveWorkRoot } from "../agent/workdir.js";
99
+ import { ensureWorkDir, resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
100
100
  import { resolveShiftId, resolveTarget } from "./hold.js";
101
101
  import { installSignalHandlers } from "./signals.js";
102
102
  const DEFAULT_INTERVAL_MS = 60_000;
@@ -195,6 +195,7 @@ export function exitCodeFor(outcome) {
195
195
  case 'completed':
196
196
  return 0;
197
197
  case 'misroute':
198
+ case 'workdir-denied':
198
199
  case 'no-template':
199
200
  case 'no-harness':
200
201
  case 'incompatible-harness-policy':
@@ -495,6 +496,13 @@ export async function run(args, deps = {}) {
495
496
  account,
496
497
  ...(shiftId !== undefined ? { shiftId } : {}),
497
498
  cwd: workCwd,
499
+ // Machine policy, resolved from the SAME two sources the shift resolves it
500
+ // from: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (which `owenloop shift start`
501
+ // exports when the operator passed `--work-root`) then the settings file.
502
+ // Resolved against `process.cwd()`, not `workCwd`: a relative root in the
503
+ // env means "relative to where this process was launched", and `workCwd`
504
+ // may be a directory owenloop just created under the cache root.
505
+ allowedWorkdirRoots: resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, process.cwd()),
498
506
  loadStep,
499
507
  resolveAdapter,
500
508
  ...(capabilityModels !== undefined ? { capabilityModels } : {}),
@@ -34,6 +34,7 @@
34
34
  import { hostname } from 'node:os';
35
35
  import { createHubClient } from "../hub/client.js";
36
36
  import { resolveBearer } from "../credentials/resolve.js";
37
+ import { resolveAllowedWorkdirRoots } from "../agent/workdir.js";
37
38
  import { loadSettings } from "../settings/settings.js";
38
39
  import { createExecLoop } from "../exec/loop.js";
39
40
  import { createDefaultStoreInstructionResolver } from "../exec/instructions.js";
@@ -121,6 +122,7 @@ export function exitCodeFor(outcome) {
121
122
  case 'judge-rejected':
122
123
  return 0;
123
124
  case 'misroute':
125
+ case 'workdir-denied':
124
126
  case 'unresolved-instructions':
125
127
  case 'killed':
126
128
  case 'lease-lost':
@@ -173,6 +175,12 @@ export async function run(args, deps = {}) {
173
175
  return 2;
174
176
  }
175
177
  const cwd = deps.cwd ?? process.cwd();
178
+ // Machine policy, resolved from the SAME two sources the shift resolves it
179
+ // from: `OWENLOOP_ALLOWED_WORKDIR_ROOTS` (which `owenloop shift start` exports
180
+ // when the operator passed `--work-root`) then the settings file. An
181
+ // independently launched `owenloop work exec` therefore honours the settings
182
+ // file on its own, with no shift involved.
183
+ const allowedWorkdirRoots = resolveAllowedWorkdirRoots(env, settings.allowedWorkdirRoots, cwd);
176
184
  let instructions = deps.instructions;
177
185
  if (instructions === undefined) {
178
186
  try {
@@ -208,6 +216,7 @@ export async function run(args, deps = {}) {
208
216
  holder,
209
217
  instructions,
210
218
  cwd,
219
+ allowedWorkdirRoots,
211
220
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
212
221
  now: () => Date.now(),
213
222
  out,