owenloop 0.5.4 → 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 +16 -0
- package/dist/packages/work/src/agent/brief.d.ts +28 -4
- package/dist/packages/work/src/agent/brief.js +170 -2
- package/dist/packages/work/src/agent/loop.d.ts +10 -1
- package/dist/packages/work/src/agent/loop.js +60 -3
- package/dist/packages/work/src/agent/workdir.d.ts +22 -0
- package/dist/packages/work/src/agent/workdir.js +80 -0
- package/dist/packages/work/src/exec/loop.d.ts +13 -1
- package/dist/packages/work/src/exec/loop.js +31 -0
- package/dist/packages/work/src/harness/claude.d.ts +24 -0
- package/dist/packages/work/src/harness/claude.js +131 -23
- package/dist/packages/work/src/harness/contract.d.ts +25 -20
- package/dist/packages/work/src/harness/contract.js +25 -20
- package/dist/packages/work/src/harness/gatekeeper.d.ts +124 -0
- package/dist/packages/work/src/harness/gatekeeper.js +208 -0
- package/dist/packages/work/src/hold/mcp.d.ts +11 -2
- package/dist/packages/work/src/hold/mcp.js +69 -2
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +29 -0
- package/dist/packages/work/src/roles/agent-run.js +9 -1
- package/dist/packages/work/src/roles/exec.js +9 -0
- package/dist/packages/work/src/roles/shift.js +9 -1
- package/dist/packages/work/src/settings/settings.d.ts +20 -1
- package/dist/packages/work/src/settings/settings.js +23 -1
- package/dist/packages/work/src/shift/runtime.d.ts +7 -0
- package/dist/packages/work/src/shift/runtime.js +29 -4
- package/dist/packages/work/src/shift/spawn.d.ts +12 -2
- package/dist/packages/work/src/shift/spawn.js +16 -3
- package/dist/src/cli.js +54 -1
- package/dist/src/engine.d.ts +46 -1
- package/dist/src/engine.js +72 -0
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +29 -5
- package/dist/src/model.js +63 -14
- package/dist/src/types.d.ts +8 -2
- package/docs/agent-runner.md +17 -5
- package/docs/cli.md +34 -0
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
|
@@ -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` → `
|
|
189
|
-
*
|
|
190
|
-
*
|
|
191
|
-
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
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': '
|
|
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
|
|
@@ -258,7 +354,13 @@ const OWENLOOP_ONLY_NETWORK_TOOLS = new Set([
|
|
|
258
354
|
* unrestricted-network readers. */
|
|
259
355
|
const READ_ONLY_OWENLOOP_ONLY_NETWORK_TOOLS = [...READ_ONLY_TOOLS]
|
|
260
356
|
.filter((tool) => OWENLOOP_ONLY_NETWORK_TOOLS.has(tool));
|
|
261
|
-
|
|
357
|
+
// The tools a born-bound step agent gets no matter how restricted it is.
|
|
358
|
+
// `ask` is here for the same reason `submit` is: without it a restricted agent
|
|
359
|
+
// has no legal way to END. It could previously only submit (fabricating when it
|
|
360
|
+
// did not know) or fall silent (re-arming the step into a retry storm). `ask` is
|
|
361
|
+
// about the agent's OWN owed artifact, so unlike `reject` it grants no authority
|
|
362
|
+
// over anyone else's work and there is no reason to withhold it under isolation.
|
|
363
|
+
const BORN_BOUND_OWENLOOP_TOOL_NAMES = ['get_order', 'submit', 'ask'];
|
|
262
364
|
const BORN_BOUND_OWENLOOP_TOOLS = BORN_BOUND_OWENLOOP_TOOL_NAMES.map((name) => `mcp__owenloop__${name}`);
|
|
263
365
|
const RESTRICTED_OWENLOOP_DENIED_TOOLS = ['mcp__owenloop__reject'];
|
|
264
366
|
const OWENLOOP_CONTROL_TOOLS = new Set([
|
|
@@ -402,6 +504,10 @@ export function buildClaudeOptions(inputs, extra) {
|
|
|
402
504
|
stderr: (data) => {
|
|
403
505
|
extra.onEvent({ kind: 'progress', text: `stderr: ${data.trimEnd()}` });
|
|
404
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),
|
|
405
511
|
};
|
|
406
512
|
// Omit the key entirely when nothing resolves — see `resolveExecutable`.
|
|
407
513
|
const executable = resolveExecutable(extra.env);
|
|
@@ -430,8 +536,10 @@ export function buildClaudeOptions(inputs, extra) {
|
|
|
430
536
|
if (permissions.permissionMode !== undefined) {
|
|
431
537
|
// Neutral `full-access` lands here as `bypassPermissions`, so the companion
|
|
432
538
|
// flag below covers it too — that is the point of translating BEFORE the
|
|
433
|
-
// pairing rather than after it. Neutral `auto-safe`
|
|
434
|
-
// deliberately
|
|
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`).
|
|
435
543
|
const mode = toSdkPermissionMode(permissions.permissionMode);
|
|
436
544
|
if (mode !== undefined) {
|
|
437
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
|
-
*
|
|
147
|
-
* describe the vocabulary, not a guarantee about how far any given
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
*
|
|
151
|
-
* request, and a read of a file
|
|
152
|
-
* host on none of them and reported no
|
|
153
|
-
*
|
|
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
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
162
|
-
*
|
|
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`
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
* a
|
|
169
|
-
*
|
|
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
|
-
*
|
|
33
|
-
* describe the vocabulary, not a guarantee about how far any given
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
* request, and a read of a file
|
|
38
|
-
* host on none of them and reported no
|
|
39
|
-
*
|
|
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
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
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`
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
* a
|
|
55
|
-
*
|
|
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;
|