owenloop 0.5.5 → 0.5.6

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.6](https://github.com/typicalday/owenloop/compare/v0.5.5...v0.5.6) (2026-08-15)
8
+
9
+
10
+ ### Features
11
+
12
+ * gate tool calls so ask actually asks and auto-safe actually classifies ([#171](https://github.com/typicalday/owenloop/issues/171)) ([f1e95f5](https://github.com/typicalday/owenloop/commit/f1e95f5990f73399c5542cf2d103e16761792a64))
13
+ * tell every step agent where its inputs are and how much rope is left ([#169](https://github.com/typicalday/owenloop/issues/169)) ([47d0485](https://github.com/typicalday/owenloop/commit/47d0485f44ac893c9d2870f7afe31b8a4c42ca92))
14
+
7
15
  ## [0.5.5](https://github.com/typicalday/owenloop/compare/v0.5.4...v0.5.5) (2026-08-15)
8
16
 
9
17
 
@@ -70,11 +70,35 @@ export interface BriefSpec {
70
70
  */
71
71
  escalated?: boolean;
72
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.
73
+ * The owed outputs for this order, in packet order. Feeds the submit contract
74
+ * (which names every path) and the attempt history (which reads the two reject
75
+ * counters); absent or empty renders neither.
76
+ *
77
+ * The caller is responsible for the FALLBACK: `packet.owes` is the hub's live
78
+ * answer to "what does this order still owe" and is the right source, but a
79
+ * hub old enough to project no `owes` array at all leaves it empty while
80
+ * `packet.outputs` still names the same paths. See `agent/loop.ts` — an empty
81
+ * list here silently deletes both contracts, which is the exact failure they
82
+ * were written to close.
76
83
  */
77
- owes?: readonly string[];
84
+ owes?: readonly OwedBrief[];
85
+ }
86
+ /**
87
+ * One owed output as the brief sees it: the path, plus how many times a prior
88
+ * submission to it was knocked back.
89
+ *
90
+ * Both counters are optional because a hub that does not project them is not a
91
+ * hub reporting zero — it is a hub with nothing to say, and the attempt history
92
+ * stays silent rather than telling an agent on its fourth attempt that this is
93
+ * its first.
94
+ */
95
+ export interface OwedBrief {
96
+ path: string;
97
+ /** Consumer/judge verdicts against a submitted value (`packet.owes[].judgmentRejects`). */
98
+ judgmentRejects?: number;
99
+ /** Engine refusals of a malformed value against the path's declared JSON
100
+ * Schema (`packet.owes[].schemaRejects`). */
101
+ schemaRejects?: number;
78
102
  }
79
103
  /**
80
104
  * Substitute the four dispatch tokens into a step template.
@@ -11,6 +11,12 @@ export const SHIFT_TOKEN = '__OWENLOOP_SHIFT__';
11
11
  function composite(spec) {
12
12
  return `${spec.workflow}/${spec.run}`;
13
13
  }
14
+ /** The owed paths worth naming: every non-empty `path`, in packet order. An
15
+ * empty string is not a path a `submit` or `ask` call could be made against, so
16
+ * it is dropped here once rather than guarded at each use. */
17
+ function owedPaths(spec) {
18
+ return (spec.owes ?? []).map((o) => o.path).filter((p) => p !== '');
19
+ }
14
20
  /**
15
21
  * Substitute the four dispatch tokens into a step template.
16
22
  *
@@ -30,12 +36,118 @@ export function renderBrief(templateContent, spec) {
30
36
  .join(spec.shiftId ?? '');
31
37
  const blocks = [
32
38
  renderRoutingLine(spec),
39
+ renderInputContract(spec),
33
40
  renderSubmitContract(spec),
41
+ renderAttemptHistory(spec),
34
42
  renderEscalationContract(spec),
35
43
  substituted,
36
44
  ];
37
45
  return blocks.filter((b) => b !== '').join('\n\n');
38
46
  }
47
+ /**
48
+ * Where this order's INPUTS are, stated to every agent on every run.
49
+ *
50
+ * WHY THIS EXISTS. The brief and the mounted work-holder are two halves of one
51
+ * order and nothing ever joined them. The brief is a rendered template; the
52
+ * order's actual data — the resolved `consumes` map, the owed paths, each path's
53
+ * reason thread — lives on the hub behind `get_order`, a tool the agent is
54
+ * mounted with and was never told about. So an agent whose template says "review
55
+ * the plan" has no stated way to obtain the plan, and the two things it does
56
+ * instead are both silent: it looks in its working directory and finds nothing,
57
+ * or it writes what a plan would plausibly say. Observed live: a planner whose
58
+ * working directory was empty produced a confident, fully-fabricated plan, and a
59
+ * builder began executing it. The working-directory half of that run was a
60
+ * separate defect and is fixed; this half is not, and it is the half that turns
61
+ * "I have no inputs" into fiction rather than into a question.
62
+ *
63
+ * WHEN IT RENDERS. On the same condition as the submit and escalation contracts
64
+ * — the order owes at least one named path — even though `get_order` itself
65
+ * takes no arguments and could always be stated. Two reasons, both concrete:
66
+ * this block's closing sentence sends the agent to `ask`, and `ask` is only
67
+ * described when there is an owed path for it to name, so an unconditional
68
+ * version would point at a section that is not there; and an order owing nothing
69
+ * has no work to orient for. The tool it names is always mounted — every agent
70
+ * order gets the full work-holder surface, because `buildOwenloopMcp` passes no
71
+ * tool selector.
72
+ *
73
+ * WHY IT RANKS `get_order` ABOVE THE BRIEF. The brief is rendered once at
74
+ * dispatch and is a summary; the packet is live and authoritative, and on a
75
+ * re-offer it carries reason threads this text cannot. Telling the agent which
76
+ * of the two wins removes the judgement call.
77
+ *
78
+ * WHY THE LAST LINE POINTS AT `ask`. Naming the source of inputs without saying
79
+ * what to do when an input is missing from it just relocates the guess.
80
+ *
81
+ * Vendor-neutral by construction: names owenloop's own tool and mount, no
82
+ * harness. `test/vendor-gate.test.ts` enforces this.
83
+ */
84
+ function renderInputContract(spec) {
85
+ if (owedPaths(spec).length === 0)
86
+ return '';
87
+ return [
88
+ 'Before you start: call the `get_order` tool on the mounted `owenloop` MCP server. It takes no arguments and returns THIS order in full — the inputs you were given (`consumes`), the exact output paths you owe, and each path\'s reason thread, including why any previous attempt was rejected.',
89
+ 'That packet is authoritative. This brief is a summary of it, rendered once when the order was dispatched; where the two disagree, the packet is right.',
90
+ 'If something you need is not in what `get_order` returns and you cannot recover it by working — reading the repository, re-reading your inputs, running a read-only command — then it was not given to you. Do not invent it and do not proceed on an assumption: use `ask` (below).',
91
+ ].join('\n');
92
+ }
93
+ /**
94
+ * How much rope is left, stated only when some has already been used.
95
+ *
96
+ * WHY THIS EXISTS, GIVEN THE REJECTION DELTA ALREADY SHIPS. `renderRejection` /
97
+ * `renderReplayBrief` tell a re-offered agent WHAT was wrong with its last
98
+ * submission. Neither tells it that the retrying is BOUNDED. Those are different
99
+ * facts and they drive different behaviour: the reasons make an agent revise,
100
+ * and revising is right up until the point where the blocker is not something
101
+ * revision can fix — at which point the agent needs to know that grinding out
102
+ * one more attempt is not free. Without a count, every attempt looks like the
103
+ * first one, so an agent has no reason to ever switch from retrying to asking,
104
+ * and the step burns its whole budget rediscovering the same blocker. The
105
+ * counter is the input to that decision and the packet has carried it all along.
106
+ *
107
+ * WHY IT DOES NOT NAME THE CAP. The cap is `maxAttempts` / `maxSchemaFailures`,
108
+ * resolved per-produce from the def (`model.ts`'s `effectiveMaxAttempts`), and
109
+ * the order packet does not carry it. Rendering a guessed number would be worse
110
+ * than rendering none: an agent told it has "2 of 5" left when it has 2 of 3
111
+ * will keep grinding. So this states the counts, which are true, and states that
112
+ * the budget is finite, which is also true, and states neither more precisely
113
+ * than the packet allows.
114
+ *
115
+ * WHY IT SEPARATES THE TWO COUNTERS. They mean opposite things to the agent. A
116
+ * judgment reject is a reader disagreeing with the CONTENT of a value that was
117
+ * otherwise well-formed. A schema reject is the engine refusing the SHAPE before
118
+ * anybody read it — rewriting the content again cannot help, and the fix is the
119
+ * structure of what was submitted. Reporting them as one number would send an
120
+ * agent to revise prose that was never read.
121
+ *
122
+ * Silent when every counter is zero or absent: a first attempt has no history,
123
+ * and "0 previous rejections" is a sentence that costs tokens to say nothing.
124
+ */
125
+ function renderAttemptHistory(spec) {
126
+ const lines = [];
127
+ for (const owed of spec.owes ?? []) {
128
+ if (owed.path === '')
129
+ continue;
130
+ const judgment = owed.judgmentRejects ?? 0;
131
+ const schema = owed.schemaRejects ?? 0;
132
+ if (judgment === 0 && schema === 0)
133
+ continue;
134
+ const parts = [];
135
+ if (judgment > 0) {
136
+ parts.push(`${judgment} rejected on judgment (a reader disagreed with the value — see its reason thread via \`get_order\`)`);
137
+ }
138
+ if (schema > 0) {
139
+ parts.push(`${schema} rejected on schema (the value did not match the declared shape — the fix is the STRUCTURE of what you submit, not its wording)`);
140
+ }
141
+ lines.push(`- \`${owed.path}\`: ${parts.join('; ')}.`);
142
+ }
143
+ if (lines.length === 0)
144
+ return '';
145
+ return [
146
+ 'Attempt history for this order — previous submissions that were knocked back:',
147
+ ...lines,
148
+ 'This retrying is bounded. After enough rejections on a path the engine stops re-arming this step entirely and it sits until a person intervenes, so a further attempt that repeats the last one costs a real attempt and gains nothing. If you now believe the blocker is something another attempt cannot fix, `ask` instead of resubmitting.',
149
+ ].join('\n');
150
+ }
39
151
  /**
40
152
  * How an order is COMPLETED, stated to every agent on every run.
41
153
  *
@@ -67,7 +179,7 @@ export function renderBrief(templateContent, spec) {
67
179
  * `src/harness/` that names a vendor.
68
180
  */
69
181
  function renderSubmitContract(spec) {
70
- const owed = (spec.owes ?? []).filter((p) => p !== '');
182
+ const owed = owedPaths(spec);
71
183
  // Nothing owed, nothing to say — the same stance the routing line takes on an
72
184
  // absent modifier. A contract with no path to name would have to write
73
185
  // `<path>` into its own example, which teaches the shape of the call while
@@ -120,7 +232,7 @@ function renderSubmitContract(spec) {
120
232
  * Vendor-neutral by construction — names owenloop's own tool and mount only.
121
233
  */
122
234
  function renderEscalationContract(spec) {
123
- const owed = (spec.owes ?? []).filter((p) => p !== '');
235
+ const owed = owedPaths(spec);
124
236
  if (owed.length === 0)
125
237
  return '';
126
238
  return [
@@ -71,6 +71,40 @@ export const DEFAULT_SUBMIT_GRACE_MS = 15_000;
71
71
  function errMsg(e) {
72
72
  return e instanceof Error ? e.message : String(e);
73
73
  }
74
+ /**
75
+ * The owed outputs the brief renders its submit contract, attempt history and
76
+ * escalation contract from.
77
+ *
78
+ * `packet.owes` is the RIGHT source and is used whenever it has anything in it:
79
+ * it is the hub's live answer to "what does this order still owe", so on a
80
+ * re-offer where some paths are already paid it names only the ones left, and it
81
+ * is the only source carrying the reject counters.
82
+ *
83
+ * THE FALLBACK, and why it is not defensive noise. `owes` reaching this function
84
+ * empty is a real, reachable state, not a can't-happen: the hub's order
85
+ * projection (`projectReferenceOrder`) is a deliberate allow-list that emits
86
+ * `owes: []` for any persisted row whose `owes` is not an array — every order
87
+ * written before the engine emitted the field. `packet.outputs` is projected
88
+ * from the same row and names the same paths, minus the counters. Preferring an
89
+ * empty `owes` over a populated `outputs` would render a brief with NO submit
90
+ * contract and NO escalation contract — silently reproducing, on exactly the old
91
+ * runs least able to cope with it, the defect both contracts exist to close. So:
92
+ * fall back to the paths, and let the attempt history stay silent because there
93
+ * are genuinely no counters to report.
94
+ *
95
+ * An order that owes nothing under BOTH fields renders neither contract, which
96
+ * is correct — there is no path for `submit` or `ask` to name.
97
+ */
98
+ function briefOwes(packet) {
99
+ if (packet.owes.length > 0) {
100
+ return packet.owes.map((owed) => ({
101
+ path: owed.path,
102
+ judgmentRejects: owed.judgmentRejects,
103
+ schemaRejects: owed.schemaRejects,
104
+ }));
105
+ }
106
+ return packet.outputs.map((path) => ({ path }));
107
+ }
74
108
  /**
75
109
  * Resolve an order's composed capabilities against this machine's map.
76
110
  *
@@ -427,9 +461,7 @@ export function createAgentRunLoop(opts) {
427
461
  // statement about the RUN, and a shift has no say in it.
428
462
  ...(packet.modifier !== undefined ? { modifier: packet.modifier } : {}),
429
463
  ...(packet.escalated === true ? { escalated: true } : {}),
430
- // The hub's own answer to "what does this order still owe", so the submit
431
- // contract names the right paths on a re-offer where some are already paid.
432
- owes: packet.owes.map((owed) => owed.path),
464
+ owes: briefOwes(packet),
433
465
  };
434
466
  // Permissions arrive PRE-NORMALIZED in the spec. `prepare` ran
435
467
  // `normalizeStepPermissions` over the step's `x.harness` options at cache
@@ -1,4 +1,5 @@
1
1
  import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
+ import type { GatePolicy } from './gatekeeper.ts';
2
3
  import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
3
4
  /**
4
5
  * Build the environment the harness child runs under.
@@ -65,6 +66,29 @@ export declare function allowApiBillingFrom(source: Record<string, string | unde
65
66
  * and the `PATH` searched are the same ones the child will see.
66
67
  */
67
68
  export declare function resolveExecutable(source: Record<string, string | undefined>): string | undefined;
69
+ /**
70
+ * How hard the gatekeeper gates, from the mode the step ACTUALLY AUTHORED.
71
+ *
72
+ * Derived from the authored string rather than from the translated SDK mode
73
+ * because the translation is deliberately lossy in exactly the place that
74
+ * matters: `ask` and `auto-safe` both become `default`, and the whole difference
75
+ * between them now lives here.
76
+ *
77
+ * WHY AN UNSET MODE CLASSIFIES RATHER THAN DENYING. A step that names no
78
+ * `permissionMode` gets the SDK's own `default`, which routes to the callback.
79
+ * Before a callback existed that meant the SDK denied every unapproved call —
80
+ * silently, finally, with nobody prompted and nothing recorded. Treating the
81
+ * unset case as `classifier` is not a widening of what those steps were promised;
82
+ * it is the first time they get anything at all. The same reasoning covers a
83
+ * step that named the vendor's `default` or `acceptEdits`.
84
+ *
85
+ * `dontAsk` is the one value that keeps its narrow meaning: it is documented as
86
+ * "deny if not pre-approved", so it maps to the policy that denies rather than
87
+ * being folded into the classifier. The SDK short-circuits that mode before the
88
+ * callback, so this is a statement of intent more than a live path — but a
89
+ * future SDK that does route it must not find it silently widened here.
90
+ */
91
+ export declare function gatePolicyFor(authoredMode: string | undefined): GatePolicy;
68
92
  /** Everything `buildClaudeOptions` reads for either cold start or resume. */
69
93
  export interface ClaudeOptionInputs {
70
94
  cwd: string;
@@ -26,6 +26,7 @@
26
26
  import { randomUUID } from 'node:crypto';
27
27
  import { accessSync, constants, existsSync } from 'node:fs';
28
28
  import { delimiter, join } from 'node:path';
29
+ import { classifyToolCall } from "./gatekeeper.js";
29
30
  import { register } from "./registry.js";
30
31
  import { filterOwenloopEnv } from "./child-env.js";
31
32
  import { normalizeStepPermissions, validateHarnessOptions } from "./permissions.js";
@@ -185,25 +186,33 @@ const PERMISSION_MODES = [
185
186
  * - `ask` → `default`. The SDK's `default` routes each unapproved tool to the
186
187
  * `canUseTool` callback — a human decision point — and denies when no callback
187
188
  * 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`).
189
+ * - `auto-safe` → `default`, with this adapter's own gatekeeper in the
190
+ * `canUseTool` callback. NOT the SDK's `auto`, and that is the substance of
191
+ * this mapping rather than a detail of it.
192
+ *
193
+ * MEASURED against SDK 0.3.220, `canUseTool` wired throughout: `auto`'s
194
+ * model-side classifier consulted the host on NONE of five probe commands and
195
+ * emitted no `permission_denied` system message for any of them. Four ran,
196
+ * including `rm -rf` on an ABSOLUTE path outside the session cwd (verified by
197
+ * the target directory being gone afterwards), a `curl` to the public
198
+ * internet, and a read of a file under `$HOME` outside cwd.
199
+ *
200
+ * So `auto` never reaches the callback and cannot escalate to anyone. The
201
+ * position `auto-safe` names — a classifier gates, a human is the exception
202
+ * path — is therefore not something `auto` can be configured into; it has to
203
+ * be built on the one mode that does route to the callback. `default` is that
204
+ * mode (measured on the same SDK build, including calls originating inside a
205
+ * subagent, which arrive carrying that subagent's `agentID`), so `auto-safe`
206
+ * and `ask` now share it and differ by the `GatePolicy` handed to the
207
+ * gatekeeper. The trade is deliberate: `auto` classifies with a model and this
208
+ * adapter classifies with path containment plus a short deny-list, which is
209
+ * the blunter instrument — but it is the only one of the two that can put a
210
+ * person in the loop, which is the whole of what the position promises.
211
+ *
212
+ * NOT `acceptEdits`, which auto-approves filesystem operations by category and
213
+ * applies no judgment to anything else, and NOT `dontAsk`, which DENIES an
214
+ * unapproved tool rather than consulting anyone — silently narrower than what
215
+ * the step asked for.
207
216
  * - `full-access` → `bypassPermissions`. The only SDK mode that runs tools with
208
217
  * no prompt at all, and the one the companion flag below exists for.
209
218
  *
@@ -212,7 +221,7 @@ const PERMISSION_MODES = [
212
221
  */
213
222
  const NEUTRAL_TO_SDK_MODE = Object.freeze({
214
223
  'ask': 'default',
215
- 'auto-safe': 'auto',
224
+ 'auto-safe': 'default',
216
225
  'full-access': 'bypassPermissions',
217
226
  });
218
227
  /** Values `preflight` accepts: the SDK's own union plus the neutral vocabulary. */
@@ -235,6 +244,93 @@ function toSdkPermissionMode(mode) {
235
244
  }
236
245
  return PERMISSION_MODES.includes(mode) ? mode : undefined;
237
246
  }
247
+ /**
248
+ * How hard the gatekeeper gates, from the mode the step ACTUALLY AUTHORED.
249
+ *
250
+ * Derived from the authored string rather than from the translated SDK mode
251
+ * because the translation is deliberately lossy in exactly the place that
252
+ * matters: `ask` and `auto-safe` both become `default`, and the whole difference
253
+ * between them now lives here.
254
+ *
255
+ * WHY AN UNSET MODE CLASSIFIES RATHER THAN DENYING. A step that names no
256
+ * `permissionMode` gets the SDK's own `default`, which routes to the callback.
257
+ * Before a callback existed that meant the SDK denied every unapproved call —
258
+ * silently, finally, with nobody prompted and nothing recorded. Treating the
259
+ * unset case as `classifier` is not a widening of what those steps were promised;
260
+ * it is the first time they get anything at all. The same reasoning covers a
261
+ * step that named the vendor's `default` or `acceptEdits`.
262
+ *
263
+ * `dontAsk` is the one value that keeps its narrow meaning: it is documented as
264
+ * "deny if not pre-approved", so it maps to the policy that denies rather than
265
+ * being folded into the classifier. The SDK short-circuits that mode before the
266
+ * callback, so this is a statement of intent more than a live path — but a
267
+ * future SDK that does route it must not find it silently widened here.
268
+ */
269
+ export function gatePolicyFor(authoredMode) {
270
+ if (authoredMode === 'ask')
271
+ return 'human-gate';
272
+ if (authoredMode === 'dontAsk')
273
+ return 'deny-unapproved';
274
+ return 'classifier';
275
+ }
276
+ /**
277
+ * What an escalated call tells the agent.
278
+ *
279
+ * This is the whole of the "human exception path" today, and it is a ROUTE
280
+ * rather than an answer: no person is watching a headless run at the moment the
281
+ * call is made, so the honest thing is to refuse the call and name the channel
282
+ * that does reach one. `ask` is that channel — it freezes the owed artifact,
283
+ * closes the run cheaply instead of burning attempts against a wall, and puts a
284
+ * question on the operator's attention feed with an answer path back into the
285
+ * next attempt.
286
+ *
287
+ * The message names the specific reason and tells the agent both of its real
288
+ * options, because the wrong outcome here is an agent that reads a denial as
289
+ * "try a different phrasing" and grinds through its attempt budget. Most
290
+ * escalations have an ordinary alternative — the same work done inside the
291
+ * step's own directory — and the message says so before it points at `ask`.
292
+ */
293
+ function escalationMessage(reason) {
294
+ return [
295
+ `Denied: ${reason}.`,
296
+ 'Nobody is watching this run to approve it, so this call cannot be granted here and rephrasing it will not change that.',
297
+ 'If the work has an equivalent inside your own working directory, do that instead.',
298
+ 'If it does not — if you genuinely cannot finish what you owe without this — call the `ask` tool on the mounted `owenloop` MCP server and state what you need and why. That reaches a person, and their answer comes back to you on your next attempt. Do not guess, and do not submit work that pretends this succeeded.',
299
+ ].join(' ');
300
+ }
301
+ /**
302
+ * The `canUseTool` callback, wired on every start.
303
+ *
304
+ * WIRED UNCONDITIONALLY, including under `bypassPermissions`, where the SDK
305
+ * never consults it. A callback that is present but unreached costs nothing; a
306
+ * callback wired only under the modes we predict will reach it is one SDK change
307
+ * away from restoring the silent deny-everything behavior this exists to end.
308
+ *
309
+ * FAIL-CLOSED, deliberately. A throw inside this callback would leave the SDK
310
+ * with no `control_response` and the tool blocked forever — permission prompts
311
+ * have no park deadline. So the classification is wrapped: anything unexpected
312
+ * becomes a denial with the same routing message rather than a hang.
313
+ */
314
+ function buildCanUseTool(cwd, policy, onEvent) {
315
+ return async (toolName, input, options) => {
316
+ let verdict;
317
+ try {
318
+ verdict = classifyToolCall({ toolName, input, workdir: cwd, blockedPath: options.blockedPath }, policy);
319
+ }
320
+ catch (err) {
321
+ verdict = { decision: 'escalate', reason: `the gatekeeper could not judge this call (${errText(err)})` };
322
+ }
323
+ if (verdict.decision === 'allow')
324
+ return { behavior: 'allow' };
325
+ // Recorded as well as returned: a denial the operator cannot see is how the
326
+ // pre-callback behavior stayed invisible for as long as it did.
327
+ onEvent({
328
+ kind: 'progress',
329
+ text: `permission escalation: ${toolName} denied — ${verdict.reason}`,
330
+ });
331
+ return { behavior: 'deny', message: escalationMessage(verdict.reason) };
332
+ };
333
+ }
238
334
  /** The five-value closed union the SDK types `Options.effort` as. */
239
335
  const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
240
336
  /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
@@ -408,6 +504,10 @@ export function buildClaudeOptions(inputs, extra) {
408
504
  stderr: (data) => {
409
505
  extra.onEvent({ kind: 'progress', text: `stderr: ${data.trimEnd()}` });
410
506
  },
507
+ // Set here, before the `permissionMode` block below, because it is not
508
+ // conditional on that block running: a step naming no mode at all is exactly
509
+ // the case that used to reach the SDK's `default` and be denied wholesale.
510
+ canUseTool: buildCanUseTool(inputs.cwd, gatePolicyFor(permissions.permissionMode), extra.onEvent),
411
511
  };
412
512
  // Omit the key entirely when nothing resolves — see `resolveExecutable`.
413
513
  const executable = resolveExecutable(extra.env);
@@ -436,8 +536,10 @@ export function buildClaudeOptions(inputs, extra) {
436
536
  if (permissions.permissionMode !== undefined) {
437
537
  // Neutral `full-access` lands here as `bypassPermissions`, so the companion
438
538
  // flag below covers it too — that is the point of translating BEFORE the
439
- // pairing rather than after it. Neutral `auto-safe` lands as `auto` and
440
- // deliberately does NOT get the flag: it is still allowed to stop and ask.
539
+ // pairing rather than after it. Neutral `ask` and `auto-safe` both land as
540
+ // `default` and deliberately do NOT get the flag: `default` is the mode that
541
+ // routes to `canUseTool`, which is where the difference between those two
542
+ // positions is actually drawn (see `gatePolicyFor`).
441
543
  const mode = toSdkPermissionMode(permissions.permissionMode);
442
544
  if (mode !== undefined) {
443
545
  options.permissionMode = mode;
@@ -143,30 +143,35 @@ export interface StepPermissions {
143
143
  * `full-access`, and the two exist separately so that choice is stated rather
144
144
  * than inferred.
145
145
  *
146
- * WHAT `auto-safe` COSTS YOU TODAY, MEASURED. The three positions above
147
- * describe the vocabulary, not a guarantee about how far any given classifier
148
- * actually goes before it consults someone. On one shipped adapter the
149
- * classifier was probed with five actions — among them a recursive delete on an
150
- * absolute path outside the session working directory, an outbound network
151
- * request, and a read of a file outside that directory — and it consulted the
152
- * host on none of them and reported no auto-denial for any of them; four ran.
153
- * On the other, the position that maps to `auto-safe` keys its judgment on
146
+ * WHO ACTUALLY DOES THE GATING, AND WHAT IT COSTS. The three positions above
147
+ * describe the vocabulary, not a guarantee about how far any given VENDOR
148
+ * classifier goes before it consults someone — and measurement showed the
149
+ * vendor classifiers do not, in practice, consult anyone. One was probed with
150
+ * five actions, among them a recursive delete on an absolute path outside the
151
+ * session working directory, an outbound network request, and a read of a file
152
+ * outside that directory; it consulted the host on none of them and reported no
153
+ * auto-denial for any of them, and four ran. The other keys its judgment on
154
154
  * filesystem access being restricted, so a step that also declares
155
155
  * `filesystem: unrestricted` moves it close to `full-access` as well.
156
156
  *
157
- * The practical consequence for a definition author: choosing `auto-safe`
158
- * because you want a person consulted on the dangerous cases may get you
159
- * neither the prompt nor a record that one was skipped. Choose `ask` when a
160
- * human decision genuinely has to happen, and `full-access` when it genuinely
161
- * must not. Treat `auto-safe` as the classifier's own judgment with no
162
- * guaranteed appeal, not as a supervised `full-access`.
157
+ * So `auto-safe` is NOT implemented by handing the decision to a vendor
158
+ * classifier and hoping. An adapter that can intercept its harness's tool calls
159
+ * gates them itself (see `./gatekeeper.ts`) — path containment against the
160
+ * step's own working directory, plus a short deny-list of destructive shell
161
+ * patterns — which is a blunter instrument than a model-side classifier and the
162
+ * only one of the two that can actually escalate. An adapter that CANNOT
163
+ * intercept owes this vocabulary the other legitimate answer: refuse the value
164
+ * in `preflight`, per "WHAT AN ADAPTER OWES THIS VOCABULARY" below.
163
165
  *
164
- * `ask` and `auto-safe` are meaningful only where something can answer a
165
- * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
166
- * Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into
167
- * a retry storm whose every worker dies in the same place. That is a reason for
168
- * a definition author to choose `full-access` for unattended steps, not a
169
- * reason for an adapter to silently upgrade one value into another.
166
+ * `ask` and `auto-safe` name positions where something is consulted. In a
167
+ * Shift-dispatched run no person is watching at the moment of the call, so the
168
+ * consultation cannot be synchronous: an adapter refuses the call and routes the
169
+ * agent to the `ask` MCP tool, which freezes the owed artifact and puts the
170
+ * question on a human's attention feed with an answer path back into the next
171
+ * attempt. What an adapter must never do is leave the call waiting on a prompt
172
+ * nobody will answer — that is a stall, and the hub re-arms the step into a
173
+ * retry storm whose every worker dies in the same place. Nor may it silently
174
+ * upgrade one value into another to avoid the problem.
170
175
  *
171
176
  * WHAT AN ADAPTER OWES THIS VOCABULARY. For each value an adapter must either
172
177
  * map it onto the vendor mode with the same meaning, or refuse it in
@@ -29,30 +29,35 @@
29
29
  * `full-access`, and the two exist separately so that choice is stated rather
30
30
  * than inferred.
31
31
  *
32
- * WHAT `auto-safe` COSTS YOU TODAY, MEASURED. The three positions above
33
- * describe the vocabulary, not a guarantee about how far any given classifier
34
- * actually goes before it consults someone. On one shipped adapter the
35
- * classifier was probed with five actions — among them a recursive delete on an
36
- * absolute path outside the session working directory, an outbound network
37
- * request, and a read of a file outside that directory — and it consulted the
38
- * host on none of them and reported no auto-denial for any of them; four ran.
39
- * On the other, the position that maps to `auto-safe` keys its judgment on
32
+ * WHO ACTUALLY DOES THE GATING, AND WHAT IT COSTS. The three positions above
33
+ * describe the vocabulary, not a guarantee about how far any given VENDOR
34
+ * classifier goes before it consults someone — and measurement showed the
35
+ * vendor classifiers do not, in practice, consult anyone. One was probed with
36
+ * five actions, among them a recursive delete on an absolute path outside the
37
+ * session working directory, an outbound network request, and a read of a file
38
+ * outside that directory; it consulted the host on none of them and reported no
39
+ * auto-denial for any of them, and four ran. The other keys its judgment on
40
40
  * filesystem access being restricted, so a step that also declares
41
41
  * `filesystem: unrestricted` moves it close to `full-access` as well.
42
42
  *
43
- * The practical consequence for a definition author: choosing `auto-safe`
44
- * because you want a person consulted on the dangerous cases may get you
45
- * neither the prompt nor a record that one was skipped. Choose `ask` when a
46
- * human decision genuinely has to happen, and `full-access` when it genuinely
47
- * must not. Treat `auto-safe` as the classifier's own judgment with no
48
- * guaranteed appeal, not as a supervised `full-access`.
43
+ * So `auto-safe` is NOT implemented by handing the decision to a vendor
44
+ * classifier and hoping. An adapter that can intercept its harness's tool calls
45
+ * gates them itself (see `./gatekeeper.ts`) — path containment against the
46
+ * step's own working directory, plus a short deny-list of destructive shell
47
+ * patterns — which is a blunter instrument than a model-side classifier and the
48
+ * only one of the two that can actually escalate. An adapter that CANNOT
49
+ * intercept owes this vocabulary the other legitimate answer: refuse the value
50
+ * in `preflight`, per "WHAT AN ADAPTER OWES THIS VOCABULARY" below.
49
51
  *
50
- * `ask` and `auto-safe` are meaningful only where something can answer a
51
- * prompt. In a Shift-dispatched run nothing can, so a prompt is a stall: the
52
- * Step Agent stops mid-turn, submits nothing, and the hub re-arms the step into
53
- * a retry storm whose every worker dies in the same place. That is a reason for
54
- * a definition author to choose `full-access` for unattended steps, not a
55
- * reason for an adapter to silently upgrade one value into another.
52
+ * `ask` and `auto-safe` name positions where something is consulted. In a
53
+ * Shift-dispatched run no person is watching at the moment of the call, so the
54
+ * consultation cannot be synchronous: an adapter refuses the call and routes the
55
+ * agent to the `ask` MCP tool, which freezes the owed artifact and puts the
56
+ * question on a human's attention feed with an answer path back into the next
57
+ * attempt. What an adapter must never do is leave the call waiting on a prompt
58
+ * nobody will answer — that is a stall, and the hub re-arms the step into a
59
+ * retry storm whose every worker dies in the same place. Nor may it silently
60
+ * upgrade one value into another to avoid the problem.
56
61
  *
57
62
  * WHAT AN ADAPTER OWES THIS VOCABULARY. For each value an adapter must either
58
63
  * map it onto the vendor mode with the same meaning, or refuse it in
@@ -0,0 +1,124 @@
1
+ /**
2
+ * The tool-call gatekeeper: the decision an adapter makes when its harness asks
3
+ * "may this tool call run?".
4
+ *
5
+ * WHY THIS EXISTS. `permissionMode` names three positions — `ask` (a human is
6
+ * the gate), `auto-safe` (a classifier is the gate, a human is the exception
7
+ * path), `full-access` (nothing is gated). Until this module, only the third
8
+ * one was real:
9
+ *
10
+ * - `ask` mapped to the SDK's `default` mode, which routes every unapproved
11
+ * tool call to a `canUseTool` callback and DENIES when no callback is wired.
12
+ * No callback was wired anywhere in this codebase. So `ask` denied everything,
13
+ * silently and finally: the agent saw a bare tool error, nobody was prompted,
14
+ * and nothing was recorded. That is the mechanism behind a planner step
15
+ * reporting that every read of its own target repository was blocked.
16
+ * - `auto-safe` mapped to the SDK's `auto` mode, whose model-side classifier was
17
+ * measured (SDK 0.3.220, callback wired throughout) to consult the host on
18
+ * NONE of five probe actions and to auto-deny none of them: four ran,
19
+ * including a recursive delete on an absolute path outside the session working
20
+ * directory, an outbound network request, and a read under `$HOME`. `auto`
21
+ * never reaches the callback at all, so no amount of host-side wiring gives it
22
+ * an exception path.
23
+ *
24
+ * The practical response to both was to write `permissionMode: full-access` on
25
+ * every step, because it was the only value whose behavior matched its name.
26
+ * That is a workflow author turning permissions off to get work done, which is
27
+ * the failure this module exists to end.
28
+ *
29
+ * WHAT THIS MODULE DECIDES, AND WHAT IT DOES NOT. It answers one question per
30
+ * tool call — allow it, or escalate it — against a stated policy. It does NOT
31
+ * decide what escalation means: the adapter owns that, because the useful
32
+ * answers differ by deployment. Today every adapter denies an escalated call
33
+ * with guidance routing the agent to the `ask` MCP tool, which puts the question
34
+ * to a person through the hub. A worker that can block on a hub-side approval
35
+ * gate would instead wait here and resolve the original call. Keeping that
36
+ * choice out of this module is what lets the second shape land without
37
+ * reopening the classification.
38
+ *
39
+ * HONESTY ABOUT THE CLASSIFIER. Two of the three checks below are decidable and
40
+ * one is not. Path containment is decidable: a resolved path either is or is not
41
+ * inside the tree this step was given. A shell command is not — no pattern list
42
+ * decides whether an arbitrary `bash -c` string is safe, and this one does not
43
+ * pretend to. `dangerousCommand` is a DENY-LIST of high-signal, rarely-legitimate
44
+ * patterns. It catches the measured probes and the ordinary footguns; a
45
+ * deliberately obfuscated command gets past it. The deny-list is kept short on
46
+ * purpose: under `classifier` policy a false positive stops real work in a
47
+ * headless run, and the honest posture for a mode documented as "proceeds on
48
+ * ordinary work" is to allow what it cannot judge. A step whose commands must
49
+ * genuinely all be reviewed should say `permissionMode: ask`, which escalates
50
+ * every shell call without consulting the deny-list at all.
51
+ */
52
+ /**
53
+ * How much the gatekeeper escalates, derived by the adapter from the step's
54
+ * authored `permissionMode`.
55
+ *
56
+ * - `human-gate` — the `ask` position. Everything beyond a trivially safe read
57
+ * inside the step's own directory escalates. The classifier is not consulted:
58
+ * the point of `ask` is that a person sees the call, not that a pattern list
59
+ * approves of it first.
60
+ * - `classifier` — the `auto-safe` position, and the right reading of a step
61
+ * that named the vendor's own `default`/`acceptEdits` or named nothing at all.
62
+ * Ordinary work proceeds; the checks below escalate what they can actually
63
+ * establish is dangerous.
64
+ * - `deny-unapproved` — the vendor's `dontAsk`, whose documented meaning is to
65
+ * deny an unapproved call rather than consult anyone. Present so that value
66
+ * keeps its meaning rather than being quietly widened into `classifier`. In
67
+ * practice the SDK short-circuits this mode before the callback, so it is a
68
+ * statement of intent more than a live path.
69
+ */
70
+ export type GatePolicy = 'human-gate' | 'classifier' | 'deny-unapproved';
71
+ /** One tool call, as much as the gatekeeper needs to judge it. */
72
+ export interface GateCall {
73
+ /** The harness's own tool name, e.g. `Read`, `Bash`, `mcp__owenloop__submit`. */
74
+ toolName: string;
75
+ /** The tool's arguments, unvalidated — this is a model-authored bag. */
76
+ input: Record<string, unknown>;
77
+ /**
78
+ * The directory this step was placed in and is entitled to work inside. For
79
+ * an owenloop order this is the resolved `workdir`; containment is measured
80
+ * against it and nothing else.
81
+ */
82
+ workdir: string;
83
+ /**
84
+ * A path the harness itself already determined to be outside the directories
85
+ * it allows, when it says so. Authoritative when present: the harness sees
86
+ * shell commands this module deliberately does not try to parse.
87
+ */
88
+ blockedPath?: string;
89
+ }
90
+ /** The gatekeeper's answer. `reason` is written to be shown to a person and to
91
+ * the agent, so it names the specific thing that triggered it. */
92
+ export type GateVerdict = {
93
+ decision: 'allow';
94
+ } | {
95
+ decision: 'escalate';
96
+ reason: string;
97
+ };
98
+ /**
99
+ * Whether `candidate` resolves inside `root`.
100
+ *
101
+ * Resolved against `root` first, so a relative path means what the harness will
102
+ * mean by it. The `..` test is on the RELATIVE result rather than on the input
103
+ * string: `a/../../b` contains no leading `..` but lands outside, and a string
104
+ * test would pass it.
105
+ */
106
+ export declare function isInside(root: string, candidate: string): boolean;
107
+ /**
108
+ * The first deny-list pattern this command matches, or `undefined`.
109
+ *
110
+ * Exported for the tests, which assert the list's shape directly: the value of a
111
+ * deny-list is entirely in which patterns are on it, so those assertions are the
112
+ * documentation of what it does and does not claim to catch.
113
+ */
114
+ export declare function dangerousCommand(command: string): string | undefined;
115
+ /**
116
+ * Judge one tool call.
117
+ *
118
+ * ORDER MATTERS. The owenloop mount is cleared first so no later rule can strand
119
+ * a step's ability to submit or escalate. The harness's own `blockedPath` is
120
+ * consulted next because it is authoritative and covers cases this module cannot
121
+ * see. Only then does policy divide: `human-gate` escalates everything but a
122
+ * contained read, `classifier` runs the two checks it can actually decide.
123
+ */
124
+ export declare function classifyToolCall(call: GateCall, policy: GatePolicy): GateVerdict;
@@ -0,0 +1,208 @@
1
+ /**
2
+ * The tool-call gatekeeper: the decision an adapter makes when its harness asks
3
+ * "may this tool call run?".
4
+ *
5
+ * WHY THIS EXISTS. `permissionMode` names three positions — `ask` (a human is
6
+ * the gate), `auto-safe` (a classifier is the gate, a human is the exception
7
+ * path), `full-access` (nothing is gated). Until this module, only the third
8
+ * one was real:
9
+ *
10
+ * - `ask` mapped to the SDK's `default` mode, which routes every unapproved
11
+ * tool call to a `canUseTool` callback and DENIES when no callback is wired.
12
+ * No callback was wired anywhere in this codebase. So `ask` denied everything,
13
+ * silently and finally: the agent saw a bare tool error, nobody was prompted,
14
+ * and nothing was recorded. That is the mechanism behind a planner step
15
+ * reporting that every read of its own target repository was blocked.
16
+ * - `auto-safe` mapped to the SDK's `auto` mode, whose model-side classifier was
17
+ * measured (SDK 0.3.220, callback wired throughout) to consult the host on
18
+ * NONE of five probe actions and to auto-deny none of them: four ran,
19
+ * including a recursive delete on an absolute path outside the session working
20
+ * directory, an outbound network request, and a read under `$HOME`. `auto`
21
+ * never reaches the callback at all, so no amount of host-side wiring gives it
22
+ * an exception path.
23
+ *
24
+ * The practical response to both was to write `permissionMode: full-access` on
25
+ * every step, because it was the only value whose behavior matched its name.
26
+ * That is a workflow author turning permissions off to get work done, which is
27
+ * the failure this module exists to end.
28
+ *
29
+ * WHAT THIS MODULE DECIDES, AND WHAT IT DOES NOT. It answers one question per
30
+ * tool call — allow it, or escalate it — against a stated policy. It does NOT
31
+ * decide what escalation means: the adapter owns that, because the useful
32
+ * answers differ by deployment. Today every adapter denies an escalated call
33
+ * with guidance routing the agent to the `ask` MCP tool, which puts the question
34
+ * to a person through the hub. A worker that can block on a hub-side approval
35
+ * gate would instead wait here and resolve the original call. Keeping that
36
+ * choice out of this module is what lets the second shape land without
37
+ * reopening the classification.
38
+ *
39
+ * HONESTY ABOUT THE CLASSIFIER. Two of the three checks below are decidable and
40
+ * one is not. Path containment is decidable: a resolved path either is or is not
41
+ * inside the tree this step was given. A shell command is not — no pattern list
42
+ * decides whether an arbitrary `bash -c` string is safe, and this one does not
43
+ * pretend to. `dangerousCommand` is a DENY-LIST of high-signal, rarely-legitimate
44
+ * patterns. It catches the measured probes and the ordinary footguns; a
45
+ * deliberately obfuscated command gets past it. The deny-list is kept short on
46
+ * purpose: under `classifier` policy a false positive stops real work in a
47
+ * headless run, and the honest posture for a mode documented as "proceeds on
48
+ * ordinary work" is to allow what it cannot judge. A step whose commands must
49
+ * genuinely all be reviewed should say `permissionMode: ask`, which escalates
50
+ * every shell call without consulting the deny-list at all.
51
+ */
52
+ import { isAbsolute, relative, resolve } from 'node:path';
53
+ const ALLOW = { decision: 'allow' };
54
+ /**
55
+ * Tools that read without mutating anything. Under `human-gate` these are the
56
+ * "trivially safe reads" the `ask` position exempts — but only inside the
57
+ * step's own directory; a read of an arbitrary absolute path is exactly the
58
+ * probe that ran unchallenged under `auto`.
59
+ */
60
+ const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'NotebookRead']);
61
+ /**
62
+ * Where each tool names a filesystem path. Only tools whose path argument is a
63
+ * plain string are listed: containment is checked where it can be checked, and
64
+ * a tool absent from this table simply is not path-checked rather than being
65
+ * guessed at.
66
+ */
67
+ const PATH_ARGS = Object.freeze({
68
+ Read: ['file_path'],
69
+ Write: ['file_path'],
70
+ Edit: ['file_path'],
71
+ NotebookRead: ['notebook_path'],
72
+ NotebookEdit: ['notebook_path'],
73
+ Glob: ['path'],
74
+ Grep: ['path'],
75
+ });
76
+ /**
77
+ * The owenloop MCP mount, which is ALWAYS allowed under every policy.
78
+ *
79
+ * This is not a convenience. `submit` is how a step discharges what it owes and
80
+ * `ask` is how it escalates to a person — including how it escalates a call this
81
+ * very gatekeeper just refused. Gating either one makes an escalated step unable
82
+ * to report that it is stuck, which converts a recoverable stall into a silent
83
+ * one. The mount is worker-owned and its surface is fixed at four tools
84
+ * (`get_order`, `submit`, `reject`, `ask`), none of which touch the filesystem
85
+ * or the network beyond the hub, so there is nothing here for a human to weigh.
86
+ */
87
+ const OWENLOOP_MCP_PREFIX = 'mcp__owenloop__';
88
+ /**
89
+ * Shell patterns the deny-list escalates. Each entry has to clear a high bar:
90
+ * genuinely destructive or exfiltrating, AND essentially never legitimate in a
91
+ * step doing repository work. Anything that merely LOOKS alarming but has an
92
+ * ordinary use in this pipeline is deliberately absent — `git push --force`, for
93
+ * one, is routine on a step's own branch, and escalating it would stop real work
94
+ * every run in exchange for no safety.
95
+ */
96
+ const DANGEROUS_COMMAND_PATTERNS = Object.freeze([
97
+ { pattern: /\b(?:sudo|doas)\b/u, what: 'runs a command as another user' },
98
+ {
99
+ pattern: /\brm\s+(?:-[a-zA-Z]*[rR][a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*[rR])\b/u,
100
+ what: 'is a recursive force-delete',
101
+ },
102
+ { pattern: /\bdd\b[^\n]*\bof=\/dev\//u, what: 'writes directly to a device' },
103
+ { pattern: /\b(?:mkfs(?:\.\w+)?|diskutil\s+erase\w*)\b/u, what: 'erases or formats a volume' },
104
+ { pattern: /\bchown\b/u, what: 'changes file ownership' },
105
+ { pattern: /\bchmod\s+(?:[0-7]*777|a\+[rwx]*w)/u, what: 'makes a file world-writable' },
106
+ {
107
+ pattern: /\b(?:curl|wget)\b[^\n]*(?:\s-X\s*(?:POST|PUT|PATCH|DELETE)\b|\s--(?:data|upload-file|post-file)\b|\s-d\s)/u,
108
+ what: 'sends data to a remote host',
109
+ },
110
+ {
111
+ pattern: /\b(?:crontab|launchctl|systemctl|schtasks)\b/u,
112
+ what: 'changes what runs on this machine outside this step',
113
+ },
114
+ {
115
+ pattern: /(?:>>?\s*)(?:~|\$HOME)?\/?\.(?:zshrc|bashrc|bash_profile|zprofile|profile)\b/u,
116
+ what: 'writes to a shell startup file',
117
+ },
118
+ ]);
119
+ /** Every string in a model-authored argument bag, at the top level. Enough for
120
+ * the path table (whose arguments are all top-level strings) without walking an
121
+ * arbitrary nested value. */
122
+ function stringArg(input, key) {
123
+ const v = input[key];
124
+ return typeof v === 'string' && v !== '' ? v : undefined;
125
+ }
126
+ /**
127
+ * Whether `candidate` resolves inside `root`.
128
+ *
129
+ * Resolved against `root` first, so a relative path means what the harness will
130
+ * mean by it. The `..` test is on the RELATIVE result rather than on the input
131
+ * string: `a/../../b` contains no leading `..` but lands outside, and a string
132
+ * test would pass it.
133
+ */
134
+ export function isInside(root, candidate) {
135
+ const absRoot = resolve(root);
136
+ const absCandidate = isAbsolute(candidate) ? resolve(candidate) : resolve(absRoot, candidate);
137
+ if (absCandidate === absRoot)
138
+ return true;
139
+ const rel = relative(absRoot, absCandidate);
140
+ return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
141
+ }
142
+ /**
143
+ * The first deny-list pattern this command matches, or `undefined`.
144
+ *
145
+ * Exported for the tests, which assert the list's shape directly: the value of a
146
+ * deny-list is entirely in which patterns are on it, so those assertions are the
147
+ * documentation of what it does and does not claim to catch.
148
+ */
149
+ export function dangerousCommand(command) {
150
+ for (const { pattern, what } of DANGEROUS_COMMAND_PATTERNS) {
151
+ if (pattern.test(command))
152
+ return what;
153
+ }
154
+ return undefined;
155
+ }
156
+ /**
157
+ * Judge one tool call.
158
+ *
159
+ * ORDER MATTERS. The owenloop mount is cleared first so no later rule can strand
160
+ * a step's ability to submit or escalate. The harness's own `blockedPath` is
161
+ * consulted next because it is authoritative and covers cases this module cannot
162
+ * see. Only then does policy divide: `human-gate` escalates everything but a
163
+ * contained read, `classifier` runs the two checks it can actually decide.
164
+ */
165
+ export function classifyToolCall(call, policy) {
166
+ if (call.toolName.startsWith(OWENLOOP_MCP_PREFIX))
167
+ return ALLOW;
168
+ if (policy === 'deny-unapproved') {
169
+ return { decision: 'escalate', reason: `permissionMode denies unapproved tool calls` };
170
+ }
171
+ // The harness saw something this module did not — trust it.
172
+ if (call.blockedPath !== undefined && call.blockedPath !== '') {
173
+ return {
174
+ decision: 'escalate',
175
+ reason: `the harness flagged \`${call.blockedPath}\` as outside the directories this step may touch`,
176
+ };
177
+ }
178
+ const paths = (PATH_ARGS[call.toolName] ?? [])
179
+ .map((key) => stringArg(call.input, key))
180
+ .filter((p) => p !== undefined);
181
+ for (const p of paths) {
182
+ if (!isInside(call.workdir, p)) {
183
+ return {
184
+ decision: 'escalate',
185
+ reason: `\`${p}\` is outside this step's working directory (\`${call.workdir}\`)`,
186
+ };
187
+ }
188
+ }
189
+ if (policy === 'human-gate') {
190
+ // Every path this tool named is contained, or it named none. A read is the
191
+ // one thing `ask` lets through; anything that can mutate or reach the
192
+ // network is what the position exists to put in front of a person.
193
+ if (READ_ONLY_TOOLS.has(call.toolName))
194
+ return ALLOW;
195
+ return {
196
+ decision: 'escalate',
197
+ reason: `permissionMode is \`ask\`, so \`${call.toolName}\` needs a person's approval`,
198
+ };
199
+ }
200
+ const command = stringArg(call.input, 'command');
201
+ if (call.toolName === 'Bash' && command !== undefined) {
202
+ const what = dangerousCommand(command);
203
+ if (what !== undefined) {
204
+ return { decision: 'escalate', reason: `the command ${what}` };
205
+ }
206
+ }
207
+ return ALLOW;
208
+ }
@@ -59,8 +59,8 @@ A cache created by an older CLI may contain `filesystem` or `network` under `per
59
59
  | `network: owenloop-only` | supported through isolated settings, skills, MCP, and built-in tools | refused |
60
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 |
61
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` |
62
+ | `permissionMode: ask` | translated to `default`, with the adapter's gatekeeper set to `human-gate` | translated to `approvalPolicy: untrusted` |
63
+ | `permissionMode: auto-safe` | translated to `default` (NOT the SDK's `auto`, which never reaches the permission callback), with the adapter's gatekeeper set to `classifier`; no danger companion flag | translated to `approvalPolicy: on-request` |
64
64
  | `permissionMode: full-access` | translated to `bypassPermissions` plus the SDK's `allowDangerouslySkipPermissions` companion flag | translated to `approvalPolicy: never` |
65
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 |
66
66
 
@@ -81,12 +81,24 @@ The neutral vocabulary is three positions on one axis, and both shipped harnesse
81
81
  | Neutral value | What is the gate | Claude Code | Codex |
82
82
  |---|---|---|---|
83
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` |
84
+ | `auto-safe` | a classifier; it proceeds on ordinary work and escalates only when an action is potentially dangerous | `default` + the adapter's gatekeeper | `on-request` |
85
85
  | `full-access` | nothing; the harness never consults a human and a failed action is reported back to the model | `bypassPermissions` + `allowDangerouslySkipPermissions` | `never` |
86
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.
87
+ `auto-safe` is not a milder `full-access`. It can still escalate, 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
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.
89
+ ### Who does the gating, and how a headless step escalates
90
+
91
+ The vendor classifiers do not, in practice, consult anyone. The SDK's `auto` mode was probed with five actions — among them a recursive delete on an absolute path outside the session working directory, an outbound network request, and a read of a file outside that directory. It consulted the host on none of them, auto-denied none of them, and four ran. `auto` also never reaches the SDK's `canUseTool` callback, so no host-side wiring can give it an exception path.
92
+
93
+ The Claude Code adapter therefore does not delegate `auto-safe` to `auto`. Both `ask` and `auto-safe` translate to `default`, the one SDK mode that routes every unapproved tool call to `canUseTool`, and the adapter's own gatekeeper decides:
94
+
95
+ - **Path containment.** A tool call naming a path outside the step's working directory escalates, under either policy. This is decidable and is the check that catches the probes above.
96
+ - **A shell deny-list.** Under `auto-safe`, `Bash` escalates on a short list of destructive or exfiltrating patterns (`sudo`, recursive force-delete, device writes, ownership changes, `curl`/`wget` carrying a request body, changes to what runs on the machine outside the step). It is a deny-list, not a proof: an obfuscated command gets past it. A step whose every command must be reviewed says `ask`, which escalates all of them without consulting the list.
97
+ - **Policy.** `ask` allows only a contained read and escalates everything else. `auto-safe` allows ordinary work and escalates what the two checks above establish. The worker-owned `owenloop` MCP mount is allowed under both, because gating it would remove a stuck step's ability to say so.
98
+
99
+ An escalation in a Shift-dispatched run cannot be a synchronous prompt — no person is watching at the moment of the call, and a call left waiting is a stall that re-arms the step into a retry storm. The adapter denies the call and routes the agent to the `ask` MCP tool, which freezes the owed artifact, closes the run without burning further attempts, and puts the question on a human's attention feed with an answer path back into the next attempt. The denial is also emitted as a progress event, so an operator can see a gate that fired.
100
+
101
+ A step that names no `permissionMode` at all reaches the SDK's `default` and is gated under the `classifier` policy. Before the gatekeeper existed such a step was denied wholesale — `default` denies when no callback is wired — silently and finally, with nobody prompted and nothing recorded.
90
102
 
91
103
  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
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.5",
3
+ "version": "0.5.6",
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.5",
3
+ "version": "0.5.6",
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.5"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.6"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.5",
3
+ "version": "0.5.6",
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.5"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.6"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",