owenloop 0.5.14 → 0.5.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,27 @@ 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.16](https://github.com/typicalday/owenloop/compare/v0.5.15...v0.5.16) (2026-08-21)
8
+
9
+
10
+ ### Bug Fixes
11
+
12
+ * **work:** let a declared unrestricted filesystem widen the gatekeeper's read check ([#276](https://github.com/typicalday/owenloop/issues/276)) ([e353402](https://github.com/typicalday/owenloop/commit/e353402d64b57adcd03d6a727a350b918126dbe7))
13
+ * **work:** name capability-silent harness failures ([#272](https://github.com/typicalday/owenloop/issues/272)) ([cff319f](https://github.com/typicalday/owenloop/commit/cff319f32296ca287b37a506d01ba4df3629fdac))
14
+
15
+ ## [0.5.15](https://github.com/typicalday/owenloop/compare/v0.5.14...v0.5.15) (2026-08-21)
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * **setup:** resolve the MCP plugin launch through the PATH binary ([#271](https://github.com/typicalday/owenloop/issues/271)) ([ce25164](https://github.com/typicalday/owenloop/commit/ce25164f0397a1c70e62feeea11715fb6fe59823))
21
+ * **work:** answer an approval with a human credential, not an agent one ([#273](https://github.com/typicalday/owenloop/issues/273)) ([6cd5330](https://github.com/typicalday/owenloop/commit/6cd53308c8040f0e0fc4b7303e555104af0d5e57))
22
+
23
+
24
+ ### Performance Improvements
25
+
26
+ * **work:** skip the targeted whats_next for instances the inbox shows unservable ([#277](https://github.com/typicalday/owenloop/issues/277)) ([4b18fe6](https://github.com/typicalday/owenloop/commit/4b18fe6a2b6e272e7d62b797ad6a8a6c452b0046))
27
+
7
28
  ## [0.5.14](https://github.com/typicalday/owenloop/compare/v0.5.13...v0.5.14) (2026-08-21)
8
29
 
9
30
 
package/README.md CHANGED
@@ -536,9 +536,13 @@ setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes and,
536
536
  when needed, converges the bundled `owenloop` plugins for Claude Code and Codex.
537
537
  Plugin convergence is non-fatal; a missing harness or failed plugin command does
538
538
  not fail setup. A second run with the expected plugin version already installed
539
- performs no plugin writes. `owenloop doctor` is the read-only counterpart: it
540
- checks both harness plugin states, reports version skew, and prints a `✓`/`✗`
541
- line with the remedy. See
539
+ performs no plugin writes when its effective MCP launch is verified safe.
540
+ `owenloop doctor` is the read-only counterpart: it checks both harness plugin
541
+ states, including the effective `owenloop mcp` command and arguments, Codex's
542
+ `PATH` pass-through, and PATH availability. It reports same-version absolute or
543
+ worktree launch declarations as drift, but does not treat a plugin's absolute
544
+ marketplace or cache location as a launch verdict. A known unsafe declaration is
545
+ repaired by the existing non-fatal `owenloop setup` convergence flow. See
542
546
  [`setup`](docs/cli.md#setup--onboard-a-machine) and
543
547
  [`doctor`](docs/cli.md#doctor--check-a-machines-install) in `docs/cli.md`.
544
548
 
@@ -69,6 +69,10 @@ import { resolveCapabilityCandidates, selectCandidate, } from "./capability-mode
69
69
  export const DEFAULT_CONFIRM_INTERVAL_MS = 1_000;
70
70
  /** Default confirm-phase bound: give the hub 15s to show the submit's outcome. */
71
71
  export const DEFAULT_SUBMIT_GRACE_MS = 15_000;
72
+ /** Keep capability-silent release diagnostics useful without growing worker logs without bound. */
73
+ const HARNESS_FAILURE_TAIL_SIZE = 4;
74
+ const HARNESS_FAILURE_FRAGMENT_CAP = 700;
75
+ const HARNESS_FAILURE_TAIL_CAP = 2_000;
72
76
  function errMsg(e) {
73
77
  return e instanceof Error ? e.message : String(e);
74
78
  }
@@ -268,6 +272,47 @@ export function createAgentRunLoop(opts) {
268
272
  let deliveredReasonAt;
269
273
  /** Captures a thrown safety-gate append from the synchronous `started` event. */
270
274
  let activePersistenceFailure;
275
+ /** Provider-selected model, when a harness reports it after its synchronous start gate. */
276
+ let runtimeModel;
277
+ /** Recent unique harness diagnostics for the capability-silent no-submit log only. */
278
+ const harnessFailures = [];
279
+ function oneLine(text) {
280
+ return text.replace(/\s+/gu, ' ').trim();
281
+ }
282
+ function bounded(text) {
283
+ const line = oneLine(text);
284
+ return line.length > HARNESS_FAILURE_FRAGMENT_CAP
285
+ ? `${line.slice(0, HARNESS_FAILURE_FRAGMENT_CAP)}…`
286
+ : line;
287
+ }
288
+ function rememberRuntimeModel(model) {
289
+ if (model === undefined)
290
+ return;
291
+ const normalized = bounded(model);
292
+ if (normalized !== '')
293
+ runtimeModel = normalized;
294
+ }
295
+ function rememberHarnessFailure(failure) {
296
+ if (failure === undefined)
297
+ return;
298
+ const normalized = bounded(failure);
299
+ if (normalized === '')
300
+ return;
301
+ const previous = harnessFailures.indexOf(normalized);
302
+ if (previous >= 0)
303
+ harnessFailures.splice(previous, 1);
304
+ harnessFailures.push(normalized);
305
+ if (harnessFailures.length > HARNESS_FAILURE_TAIL_SIZE)
306
+ harnessFailures.shift();
307
+ }
308
+ function harnessFailureTail() {
309
+ if (harnessFailures.length === 0)
310
+ return undefined;
311
+ const tail = harnessFailures.join(' | ');
312
+ return tail.length > HARNESS_FAILURE_TAIL_CAP
313
+ ? `${tail.slice(0, HARNESS_FAILURE_TAIL_CAP - 1)}…`
314
+ : tail;
315
+ }
271
316
  let resolveOrder;
272
317
  const orderReady = new Promise((r) => {
273
318
  resolveOrder = r;
@@ -379,6 +424,7 @@ export function createAgentRunLoop(opts) {
379
424
  switch (e.kind) {
380
425
  case 'started':
381
426
  sessionRef = e.ref;
427
+ rememberRuntimeModel(e.model);
382
428
  opts.err(`owenloop work agent-run: session started for ${order} (harness '${e.ref.harness}')`);
383
429
  // This synchronous event is the cold-start gate. The adapter must not
384
430
  // begin provider work until the callback returns. A thrown durable append
@@ -393,6 +439,8 @@ export function createAgentRunLoop(opts) {
393
439
  }
394
440
  return;
395
441
  case 'progress':
442
+ rememberRuntimeModel(e.model);
443
+ rememberHarnessFailure(e.failure);
396
444
  opts.err(`owenloop work agent-run: ${e.text}`);
397
445
  return;
398
446
  case 'assistant_response':
@@ -409,6 +457,10 @@ export function createAgentRunLoop(opts) {
409
457
  opts.err(`owenloop work agent-run: turn ended for ${order} (telemetry — the hub decides the outcome)`);
410
458
  return;
411
459
  case 'exited':
460
+ rememberHarnessFailure(e.error);
461
+ if (e.error === undefined && e.exitCode !== null && e.exitCode !== 0) {
462
+ rememberHarnessFailure(`harness exited with code ${String(e.exitCode)}`);
463
+ }
412
464
  opts.err(`owenloop work agent-run: harness exited (code ${String(e.exitCode)}${e.error !== undefined ? `, ${e.error}` : ''}) — telemetry only, ignored for the outcome`);
413
465
  return;
414
466
  }
@@ -610,8 +662,17 @@ export function createAgentRunLoop(opts) {
610
662
  return releaseWith('incompatible-harness-policy', 'incompatible-harness-policy');
611
663
  }
612
664
  if (routing.kind === 'unrouted') {
613
- opts.err(`owenloop work agent-run: ${order} carries no capabilities, so no crew roster row applies — ` +
614
- `running on '${resolution.id}'s own default model.`);
665
+ const authoredSettings = [];
666
+ if (permissions.model !== undefined)
667
+ authoredSettings.push(`model '${permissions.model}'`);
668
+ if (permissions.effort !== undefined)
669
+ authoredSettings.push(`effort '${permissions.effort}'`);
670
+ const executionPolicy = authoredSettings.length === 0
671
+ ? 'no roster model or effort override and no authored step model or effort; it will choose its own default model'
672
+ : `no roster model or effort override; authored step ${authoredSettings.join(' and ')} remains in effect`;
673
+ opts.err(`CAPABILITY-SILENT owenloop work agent-run: ${order} step '${packet.step}' declares no capabilities, so no crew roster row applies; ` +
674
+ `selected harness '${resolution.id}' receives ${executionPolicy} ` +
675
+ `(the exact runtime model id will be reported by the harness when available).`);
615
676
  }
616
677
  else {
617
678
  opts.out(`owenloop work agent-run: ${order} resolved '${routing.capability}' (${routing.match} row) → ` +
@@ -826,6 +887,7 @@ export function createAgentRunLoop(opts) {
826
887
  }
827
888
  // TURN END — NOT task end. Log the failure shape for humans, then confirm.
828
889
  if (raced.failure !== undefined) {
890
+ rememberHarnessFailure(errMsg(raced.failure));
829
891
  const why = isResumeUnavailable(raced.failure)
830
892
  ? `the harness could not resume the session (${errMsg(raced.failure)})`
831
893
  : errMsg(raced.failure);
@@ -876,6 +938,13 @@ export function createAgentRunLoop(opts) {
876
938
  return 'lease-lost';
877
939
  case 'no-submit':
878
940
  record('dead');
941
+ if (routing.kind === 'unrouted') {
942
+ const model = runtimeModel ?? 'model id not reported by the harness';
943
+ const failure = harnessFailureTail() ?? 'no specific harness failure was reported';
944
+ opts.err(`CAPABILITY-SILENT owenloop work agent-run: ${order} step '${packet.step}' on harness '${resolution.id}' ` +
945
+ `reported runtime model ${model}; harness failure context: ${failure}; no submit reached the hub within the confirm grace — releasing for re-offer.`);
946
+ return releaseWith('capability-silent-no-submit', 'no-submit');
947
+ }
879
948
  opts.err(`owenloop work agent-run: the turn ended and no submit reached the hub within the confirm grace — releasing ${order} for re-offer`);
880
949
  // Release so the hub re-offers immediately instead of waiting out the
881
950
  // claim TTL. This is the ONLY path that releases on a turn end.
@@ -1,14 +1,16 @@
1
1
  /**
2
- * Credential read seam. owenloop reads hub credentials through owenloop's
3
- * store ONLY — it never writes, prints, or stores credentials itself, and it
4
- * never reads the keychain or `credentials.json` formats directly.
2
+ * Credential read seam for agent runtime roles. owenloop reads hub credentials
3
+ * through owenloop's store ONLY — it never prints credentials or reads the
4
+ * keychain or `credentials.json` formats directly.
5
5
  *
6
6
  * The live wiring is against owenloop 0.4.0's `readStoredCredential`
7
- * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). owenloop reads
8
- * ONLY the `agent:<account>` slots — never the `human` slot — so a human-only
9
- * origin reads as absent (`null`), which the roles surface as a clean refuse.
10
- * `Credential` is re-exported from owenloop below so this seam and the store
11
- * speak the exact same union.
7
+ * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). That reader
8
+ * addresses ONLY `agent:<account>` slots — never `human` — so a human-only
9
+ * origin reads as absent (`null`) on agent paths. Human decision resolution
10
+ * uses the root `ensureFreshOAuth` surface after its explicit `human` read;
11
+ * an expiring OAuth credential can therefore persist its locked rotation.
12
+ * `Credential` is re-exported below so this seam and the store speak the same
13
+ * union.
12
14
  */
13
15
  /** The root package's stored-credential union (agent / oauth / oauth-pasted). */
14
16
  export type { Credential } from '../../../../src/hub.ts';
@@ -1,14 +1,16 @@
1
1
  /**
2
- * Credential read seam. owenloop reads hub credentials through owenloop's
3
- * store ONLY — it never writes, prints, or stores credentials itself, and it
4
- * never reads the keychain or `credentials.json` formats directly.
2
+ * Credential read seam for agent runtime roles. owenloop reads hub credentials
3
+ * through owenloop's store ONLY — it never prints credentials or reads the
4
+ * keychain or `credentials.json` formats directly.
5
5
  *
6
6
  * The live wiring is against owenloop 0.4.0's `readStoredCredential`
7
- * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). owenloop reads
8
- * ONLY the `agent:<account>` slots — never the `human` slot — so a human-only
9
- * origin reads as absent (`null`), which the roles surface as a clean refuse.
10
- * `Credential` is re-exported from owenloop below so this seam and the store
11
- * speak the exact same union.
7
+ * (src/credentials/owenloop.ts → `OwenloopCredentialReader`). That reader
8
+ * addresses ONLY `agent:<account>` slots — never `human` — so a human-only
9
+ * origin reads as absent (`null`) on agent paths. Human decision resolution
10
+ * uses the root `ensureFreshOAuth` surface after its explicit `human` read;
11
+ * an expiring OAuth credential can therefore persist its locked rotation.
12
+ * `Credential` is re-exported below so this seam and the store speak the same
13
+ * union.
12
14
  */
13
15
  /**
14
16
  * In-memory reader seeded from a `Record<origin, Credential>`. Lives in `src`
@@ -1,3 +1,4 @@
1
+ import type { CredentialIO } from '../../../../src/index.ts';
1
2
  export type BearerResult = {
2
3
  ok: true;
3
4
  token: string;
@@ -6,14 +7,22 @@ export type BearerResult = {
6
7
  code: number;
7
8
  message: string;
8
9
  };
10
+ export type ResolveBearerArgs = {
11
+ origin: string;
12
+ account: string;
13
+ env: Record<string, string | undefined>;
14
+ principal?: 'agent';
15
+ } | {
16
+ origin: string;
17
+ env: Record<string, string | undefined>;
18
+ principal: 'human';
19
+ account?: never;
20
+ credentialIo?: Omit<CredentialIO, 'env'>;
21
+ };
9
22
  /**
10
23
  * The owenloop `--as <slot>` argument for an account: `agent` for the default
11
24
  * account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
12
25
  * semantics (`human` | `agent` | `agent:<account>`).
13
26
  */
14
27
  export declare function slotArg(account: string): string;
15
- export declare function resolveBearer(args: {
16
- origin: string;
17
- account: string;
18
- env: Record<string, string | undefined>;
19
- }): Promise<BearerResult>;
28
+ export declare function resolveBearer(args: ResolveBearerArgs): Promise<BearerResult>;
@@ -1,7 +1,9 @@
1
1
  /**
2
- * The ONE place the bearer-token resolution / refuse / dev-override logic lives,
3
- * so all five roles share identical precedence instead of re-deriving it:
2
+ * The ONE place the bearer-token resolution / refusal logic lives. Agent
3
+ * runtime roles share one precedence here; human-only decisions use their own
4
+ * explicit credential boundary rather than re-deriving either path.
4
5
  *
6
+ * Agent mode:
5
7
  * 1. `OWENLOOP_TOKEN` (trimmed, non-empty) — an EXPLICIT dev-only override.
6
8
  * When set, it is used verbatim and the store + account are skipped.
7
9
  * 2. Otherwise read the `agent:<account>` slot from owenloop's store:
@@ -11,12 +13,21 @@
11
13
  * - a THROW → error (code 1): a genuine read failure (bad origin /
12
14
  * external-command failure), surfaced with its message.
13
15
  *
16
+ * Human mode reads ONLY the `human` slot. It deliberately does not honor the
17
+ * principal-ambiguous dev override or an agent account: callers use it for
18
+ * human-only hub verbs and must either supply a human credential or refuse
19
+ * locally with an actionable login command. A stored human OAuth credential may
20
+ * refresh and persist its rotation through the root package's shared lock; this
21
+ * resolver never mints, logs, or otherwise exposes credentials.
22
+ *
14
23
  * The refuse (code 2) is a refuse-to-start precondition, mirroring the old
15
- * "no token" exit code, so existing exit-code assertions stay valid — only the
16
- * message text changes. owenloop stays read-only w.r.t. credentials.
24
+ * "no token" exit code, so existing exit-code assertions stay valid. Agent
25
+ * mode is read-only; human decision mode may persist a rotation of a credential
26
+ * the user already stored.
17
27
  */
18
28
  import { OwenloopCredentialReader } from "./owenloop.js";
19
29
  import { credentialToToken } from "./reader.js";
30
+ import { ensureFreshOAuth, readStoredCredential } from "../../../../src/index.js";
20
31
  /**
21
32
  * The owenloop `--as <slot>` argument for an account: `agent` for the default
22
33
  * account, `agent:<account>` otherwise. Grounded from owenloop's `--as`
@@ -26,7 +37,42 @@ export function slotArg(account) {
26
37
  return account === 'default' ? 'agent' : `agent:${account}`;
27
38
  }
28
39
  export async function resolveBearer(args) {
29
- const { origin, account, env } = args;
40
+ const { origin, env } = args;
41
+ if (args.principal === 'human') {
42
+ const io = { env, ...args.credentialIo };
43
+ let cred;
44
+ try {
45
+ cred = readStoredCredential(origin, { principal: 'human', env: io.env, keychain: io.keychain });
46
+ }
47
+ catch (err) {
48
+ const detail = err instanceof Error ? err.message : String(err);
49
+ return {
50
+ ok: false,
51
+ code: 1,
52
+ message: `human credential read failed for ${origin}: ${detail}`,
53
+ };
54
+ }
55
+ if (cred === null) {
56
+ return {
57
+ ok: false,
58
+ code: 2,
59
+ message: `no human credential for ${origin} — run: owenloop login --hub ${origin} --as human`,
60
+ };
61
+ }
62
+ try {
63
+ const fresh = await ensureFreshOAuth(io, origin, { principal: 'human' }, cred);
64
+ return { ok: true, token: credentialToToken(fresh) };
65
+ }
66
+ catch (err) {
67
+ const detail = err instanceof Error ? err.message : String(err);
68
+ return {
69
+ ok: false,
70
+ code: 1,
71
+ message: `human credential refresh failed for ${origin}: ${detail}`,
72
+ };
73
+ }
74
+ }
75
+ const { account } = args;
30
76
  // 1. Dev-only override: explicit OWENLOOP_TOKEN bypasses the store + account.
31
77
  const override = env['OWENLOOP_TOKEN']?.trim();
32
78
  if (override !== undefined && override !== '') {
@@ -1,5 +1,5 @@
1
1
  import type { Options, Query, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
2
- import type { GatePolicy } from './gatekeeper.ts';
2
+ import { type GatePolicy } from './gatekeeper.ts';
3
3
  import type { ApprovalRequester } from './contract.ts';
4
4
  import type { AgentEvent, HarnessAdapter, HarnessSessionRef, StartArgs, StepPermissions } from './contract.ts';
5
5
  /**
@@ -26,7 +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
+ import { classifyToolCall, READ_ONLY_TOOLS } from "./gatekeeper.js";
30
30
  import { register } from "./registry.js";
31
31
  import { filterOwenloopEnv } from "./child-env.js";
32
32
  import { normalizeStepPermissions, validateHarnessOptions } from "./permissions.js";
@@ -343,11 +343,11 @@ function decisionMessage(reason, note) {
343
343
  * the behavior is exactly what it was before: deny, and name `ask` as the
344
344
  * channel that does reach someone.
345
345
  */
346
- function buildCanUseTool(cwd, policy, onEvent, approvals) {
346
+ function buildCanUseTool(cwd, policy, filesystem, onEvent, approvals) {
347
347
  return async (toolName, input, options) => {
348
348
  let verdict;
349
349
  try {
350
- verdict = classifyToolCall({ toolName, input, workdir: cwd, blockedPath: options.blockedPath }, policy);
350
+ verdict = classifyToolCall({ toolName, input, workdir: cwd, blockedPath: options.blockedPath, filesystem }, policy);
351
351
  }
352
352
  catch (err) {
353
353
  verdict = { decision: 'escalate', reason: `the gatekeeper could not judge this call (${errText(err)})` };
@@ -402,9 +402,6 @@ function buildCanUseTool(cwd, policy, onEvent, approvals) {
402
402
  }
403
403
  /** The five-value closed union the SDK types `Options.effort` as. */
404
404
  const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
405
- /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
406
- * can read the unrestricted network without weakening a read-only filesystem. */
407
- const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebFetch', 'WebSearch']);
408
405
  /** Audited built-ins allowed when only the network is restricted. */
409
406
  const OWENLOOP_ONLY_NETWORK_TOOLS = new Set([
410
407
  'Read',
@@ -571,12 +568,13 @@ export function buildClaudeOptions(inputs, extra) {
571
568
  : mergeMcpServers(permissions.extensions['mcpServers'], inputs.owenloopMcp),
572
569
  ...(isolated ? { settingSources: [], strictMcpConfig: true, skills: [] } : {}),
573
570
  stderr: (data) => {
574
- extra.onEvent({ kind: 'progress', text: `stderr: ${data.trimEnd()}` });
571
+ const line = data.trimEnd();
572
+ extra.onEvent({ kind: 'progress', text: `stderr: ${line}`, failure: cap(line) });
575
573
  },
576
574
  // Set here, before the `permissionMode` block below, because it is not
577
575
  // conditional on that block running: a step naming no mode at all is exactly
578
576
  // the case that used to reach the SDK's `default` and be denied wholesale.
579
- canUseTool: buildCanUseTool(inputs.cwd, gatePolicyFor(permissions.permissionMode), extra.onEvent, inputs.approvals),
577
+ canUseTool: buildCanUseTool(inputs.cwd, gatePolicyFor(permissions.permissionMode), permissions.filesystem, extra.onEvent, inputs.approvals),
580
578
  };
581
579
  // Omit the key entirely when nothing resolves — see `resolveExecutable`.
582
580
  const executable = resolveExecutable(extra.env);
@@ -743,7 +741,11 @@ function toolResultText(content) {
743
741
  function emitAssistant(message, onEvent) {
744
742
  const from = origin(message.parent_tool_use_id);
745
743
  if (message.error !== undefined) {
746
- onEvent({ kind: 'progress', text: `${from}assistant error: ${message.error}` });
744
+ onEvent({
745
+ kind: 'progress',
746
+ text: `${from}assistant error: ${message.error}`,
747
+ failure: cap(message.error),
748
+ });
747
749
  }
748
750
  for (const block of message.message.content) {
749
751
  switch (block.type) {
@@ -849,6 +851,7 @@ export async function consumeTurn(q, onEvent, onInit, expectedSessionId) {
849
851
  text: `session ${message.session_id}: cliVersion=${message.claude_code_version} ` +
850
852
  `model=${message.model} apiKeySource=${message.apiKeySource} ` +
851
853
  `permissionMode=${message.permissionMode} cwd=${message.cwd} mcp=[${servers}]`,
854
+ model: cap(message.model),
852
855
  });
853
856
  onInit?.(sessionId);
854
857
  }
@@ -912,7 +912,10 @@ async function openClient(cwd, onEvent, gate, approvals) {
912
912
  // in `jsonrpc-stdio.ts`), so the reader keeps draining notifications, and no
913
913
  // timeout wraps a server request the way `client.request` wraps ours.
914
914
  onServerRequest: handleServerRequest(onEvent, approvals),
915
- onStderr: (line) => onEvent({ kind: 'progress', text: cap(line) }),
915
+ onStderr: (line) => {
916
+ const text = cap(line);
917
+ onEvent({ kind: 'progress', text, failure: text });
918
+ },
916
919
  onExit: (code, signal) => {
917
920
  reportExit(code, signal === null ? undefined : `killed by ${signal}`);
918
921
  // Resolve-on-turn-end means a death BEFORE `turn/completed` is a failure,
@@ -59,10 +59,18 @@ export type AgentEvent = {
59
59
  /** Provider-selected model when the session-start response exposes it. */
60
60
  model?: string;
61
61
  }
62
- /** Optional log line. Adapters may emit none; nothing may depend on it. */
62
+ /**
63
+ * Optional log line. Adapters may emit none; nothing may depend on it.
64
+ *
65
+ * Model and failure fields enrich local telemetry when a provider reports them
66
+ * after the synchronous started-event gate. They never affect task outcome,
67
+ * hub confirmation, or release behavior, and adapters may omit either.
68
+ */
63
69
  | {
64
70
  kind: 'progress';
65
71
  text: string;
72
+ model?: string;
73
+ failure?: string;
66
74
  }
67
75
  /** The completed top-level assistant reply, assembled by the owning adapter.
68
76
  * Unlike `progress`, this is suitable for a caller that explicitly needs the
@@ -49,14 +49,17 @@
49
49
  * genuinely all be reviewed should say `permissionMode: ask`, which escalates
50
50
  * every shell call without consulting the deny-list at all.
51
51
  */
52
+ import type { FilesystemPermission } from './contract.ts';
52
53
  /**
53
54
  * How much the gatekeeper escalates, derived by the adapter from the step's
54
55
  * authored `permissionMode`.
55
56
  *
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.
57
+ * - `human-gate` — the `ask` position. Everything beyond a declared-safe
58
+ * filesystem read escalates. Such reads are workdir-contained unless the
59
+ * step explicitly declares `filesystem: unrestricted` and the call belongs
60
+ * to the shared audited read-tool set; a harness `blockedPath` remains
61
+ * authoritative. The classifier is not consulted: the point of `ask` is
62
+ * that a person sees the call, not that a pattern list approves of it first.
60
63
  * - `classifier` — the `auto-safe` position, and the right reading of a step
61
64
  * that named the vendor's own `default`/`acceptEdits` or named nothing at all.
62
65
  * Ordinary work proceeds; the checks below escalate what they can actually
@@ -86,6 +89,11 @@ export interface GateCall {
86
89
  * shell commands this module deliberately does not try to parse.
87
90
  */
88
91
  blockedPath?: string;
92
+ /**
93
+ * The normalized filesystem boundary declared by the step. An explicit
94
+ * `unrestricted` declaration may widen audited filesystem reads only.
95
+ */
96
+ filesystem?: FilesystemPermission;
89
97
  }
90
98
  /** The gatekeeper's answer. `reason` is written to be shown to a person and to
91
99
  * the agent, so it names the specific thing that triggered it. */
@@ -95,6 +103,11 @@ export type GateVerdict = {
95
103
  decision: 'escalate';
96
104
  reason: string;
97
105
  };
106
+ /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
107
+ * can read the unrestricted network without weakening a read-only filesystem.
108
+ * This is the canonical audited read-tool set used by both the adapter's tool
109
+ * surface and the explicit unrestricted-filesystem containment exception. */
110
+ export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
98
111
  /**
99
112
  * Whether `candidate` resolves inside `root`.
100
113
  *
@@ -118,7 +131,10 @@ export declare function dangerousCommand(command: string): string | undefined;
118
131
  * ORDER MATTERS. The owenloop mount is cleared first so no later rule can strand
119
132
  * a step's ability to submit or escalate. The harness's own `blockedPath` is
120
133
  * 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.
134
+ * see. Path calls then stay contained, except when an explicitly unrestricted
135
+ * filesystem declaration and the shared audited read-tool set both permit the
136
+ * exception. Only then does policy divide: `human-gate` allows declared-safe
137
+ * filesystem reads but escalates writes and network operations; `classifier`
138
+ * runs the two checks it can actually decide.
123
139
  */
124
140
  export declare function classifyToolCall(call: GateCall, policy: GatePolicy): GateVerdict;
@@ -51,13 +51,11 @@
51
51
  */
52
52
  import { isAbsolute, relative, resolve } from 'node:path';
53
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']);
54
+ /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
55
+ * can read the unrestricted network without weakening a read-only filesystem.
56
+ * This is the canonical audited read-tool set used by both the adapter's tool
57
+ * surface and the explicit unrestricted-filesystem containment exception. */
58
+ export const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebFetch', 'WebSearch']);
61
59
  /**
62
60
  * Where each tool names a filesystem path. Only tools whose path argument is a
63
61
  * plain string are listed: containment is checked where it can be checked, and
@@ -65,13 +63,13 @@ const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'NotebookRead']);
65
63
  * guessed at.
66
64
  */
67
65
  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'],
66
+ Read: { args: ['file_path'], humanGateSafeRead: true },
67
+ Write: { args: ['file_path'] },
68
+ Edit: { args: ['file_path'] },
69
+ NotebookRead: { args: ['notebook_path'], humanGateSafeRead: true },
70
+ NotebookEdit: { args: ['notebook_path'] },
71
+ Glob: { args: ['path'], humanGateSafeRead: true },
72
+ Grep: { args: ['path'], humanGateSafeRead: true },
75
73
  });
76
74
  /**
77
75
  * The owenloop MCP mount, which is ALWAYS allowed under every policy.
@@ -159,8 +157,11 @@ export function dangerousCommand(command) {
159
157
  * ORDER MATTERS. The owenloop mount is cleared first so no later rule can strand
160
158
  * a step's ability to submit or escalate. The harness's own `blockedPath` is
161
159
  * 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.
160
+ * see. Path calls then stay contained, except when an explicitly unrestricted
161
+ * filesystem declaration and the shared audited read-tool set both permit the
162
+ * exception. Only then does policy divide: `human-gate` allows declared-safe
163
+ * filesystem reads but escalates writes and network operations; `classifier`
164
+ * runs the two checks it can actually decide.
164
165
  */
165
166
  export function classifyToolCall(call, policy) {
166
167
  if (call.toolName.startsWith(OWENLOOP_MCP_PREFIX))
@@ -175,22 +176,29 @@ export function classifyToolCall(call, policy) {
175
176
  reason: `the harness flagged \`${call.blockedPath}\` as outside the directories this step may touch`,
176
177
  };
177
178
  }
178
- const paths = (PATH_ARGS[call.toolName] ?? [])
179
+ const pathArgs = PATH_ARGS[call.toolName];
180
+ const paths = (pathArgs?.args ?? [])
179
181
  .map((key) => stringArg(call.input, key))
180
182
  .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
- };
183
+ // An explicit unrestricted filesystem declaration widens only the declared
184
+ // boundary of the shared audited read set. It does not change which operation
185
+ // categories the `ask` policy regards as safe.
186
+ if (call.filesystem !== 'unrestricted' || !READ_ONLY_TOOLS.has(call.toolName)) {
187
+ for (const p of paths) {
188
+ if (!isInside(call.workdir, p)) {
189
+ return {
190
+ decision: 'escalate',
191
+ reason: `\`${p}\` is outside this step's working directory (\`${call.workdir}\`)`,
192
+ };
193
+ }
187
194
  }
188
195
  }
189
196
  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))
197
+ // Every path this tool named is contained, or it was an explicitly
198
+ // unrestricted audited read. A declared-safe filesystem read is the one
199
+ // thing `ask` lets through; anything that can mutate or reach the network
200
+ // is what the position exists to put in front of a person.
201
+ if (pathArgs?.humanGateSafeRead === true)
194
202
  return ALLOW;
195
203
  return {
196
204
  decision: 'escalate',