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 +8 -0
- package/dist/packages/work/src/agent/brief.d.ts +28 -4
- package/dist/packages/work/src/agent/brief.js +114 -2
- package/dist/packages/work/src/agent/loop.js +35 -3
- package/dist/packages/work/src/harness/claude.d.ts +24 -0
- package/dist/packages/work/src/harness/claude.js +124 -22
- 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/docs/agent-runner.md +17 -5
- 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
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
|
|
74
|
-
*
|
|
75
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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` → `
|
|
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
|
|
@@ -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`
|
|
440
|
-
// 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`).
|
|
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
|
-
*
|
|
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;
|
|
@@ -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
|
+
}
|
package/docs/agent-runner.md
CHANGED
|
@@ -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`,
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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"
|