@agent-corpus/policy-manager 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +126 -29
  2. package/dist/adapters.d.ts +3 -1
  3. package/dist/adapters.js +37 -18
  4. package/dist/classifier.d.ts +98 -0
  5. package/dist/classifier.js +343 -0
  6. package/dist/cli.js +66 -7
  7. package/dist/config.d.ts +2 -0
  8. package/dist/config.js +6 -2
  9. package/dist/evidence.d.ts +1 -0
  10. package/dist/evidence.js +60 -0
  11. package/dist/flow.d.ts +4 -0
  12. package/dist/flow.js +91 -18
  13. package/dist/gitalias.d.ts +13 -0
  14. package/dist/gitalias.js +33 -0
  15. package/dist/grants.d.ts +9 -9
  16. package/dist/grants.js +46 -30
  17. package/dist/hard.d.ts +63 -0
  18. package/dist/hard.js +1637 -0
  19. package/dist/helpers.d.ts +59 -0
  20. package/dist/helpers.js +304 -0
  21. package/dist/merged.d.ts +6 -0
  22. package/dist/merged.js +23 -0
  23. package/dist/nativerules.d.ts +44 -0
  24. package/dist/nativerules.js +653 -0
  25. package/dist/permissive.js +179 -7
  26. package/dist/policy.d.ts +12 -0
  27. package/dist/policy.js +228 -45
  28. package/dist/profile.d.ts +7 -0
  29. package/dist/profile.js +32 -1
  30. package/dist/prompt.d.ts +32 -0
  31. package/dist/prompt.js +334 -0
  32. package/dist/reads.d.ts +46 -0
  33. package/dist/reads.js +812 -0
  34. package/dist/replay.d.ts +42 -0
  35. package/dist/replay.js +174 -1
  36. package/dist/service.d.ts +12 -1
  37. package/dist/service.js +23 -6
  38. package/dist/session.d.ts +76 -13
  39. package/dist/session.js +373 -116
  40. package/dist/shell.d.ts +2 -0
  41. package/dist/shell.js +1 -1
  42. package/dist/shellscan.d.ts +58 -0
  43. package/dist/shellscan.js +395 -0
  44. package/dist/statepaths.d.ts +41 -0
  45. package/dist/statepaths.js +706 -0
  46. package/dist/types.d.ts +11 -1
  47. package/package.json +1 -1
package/dist/session.js CHANGED
@@ -1,20 +1,40 @@
1
- import { isClassifyRecord, looksLikeApproveGrant, looksLikeClassifyRecord } from "./adapters.js";
1
+ import { basename, dirname } from "node:path";
2
+ import { looksLikeApproveGrant, looksLikeClassifyRecord } from "./adapters.js";
2
3
  import { audit, requestSummary } from "./audit.js";
3
- import { creationTargets, pathKey, settle, withCreated, } from "./created.js";
4
+ import { classifyWithCli } from "./classifier.js";
5
+ import { creationTargets, located, pathKey, settle, stamp, withCreated, } from "./created.js";
4
6
  import { grantScope, scopeLabel } from "./grants.js";
7
+ import { APPROVE_GUARD, hardRules } from "./hard.js";
8
+ import { nativeRules } from "./nativerules.js";
5
9
  import { evaluate, hash, requestHash as requestHashOf, result, SHELL_TOOLS } from "./policy.js";
6
10
  import { strictProfile } from "./profile.js";
11
+ import { buildPrompt } from "./prompt.js";
7
12
  import { redactText } from "./redact.js";
8
13
  import { CATEGORIES, } from "./types.js";
9
- /** How long a classification outcome for one exact request is remembered. */
14
+ /** How long a classification verdict for one exact request (tool, input and cwd) is reused. */
10
15
  const CLASSIFICATION_TTL_MS = 5 * 60_000;
11
- /** AI approvals per session; beyond this, ambiguous requests go to a human. */
12
- export const MAX_AI_APPROVALS = 50;
13
16
  /** How long after its approval an execution report may still record the files a tool created. */
14
17
  const CREATION_REPORT_MS = 15 * 60_000;
15
- export const APPROVE_GUARD = "Only the user may approve a request, by running approve in their own terminal";
18
+ export { APPROVE_GUARD };
19
+ /** Claude Code permission modes in which a hook's ask is shown to a person. */
20
+ const PROMPTING_MODES = new Set(["default", "acceptEdits", "plan"]);
21
+ /** Hard items no allow rule approves, at any level: they always ask the person. */
22
+ const NO_ALLOW = new Set([
23
+ "credential-read",
24
+ "harness-settings",
25
+ "policy-profile",
26
+ "policy-state",
27
+ "force-push",
28
+ ]);
29
+ /** Longest shell command checked at all; a longer one is asked at once, with no parsing. */
30
+ export const MAX_HOOK_COMMAND = 100_000;
31
+ export const TOO_LONG_REASON = "Command is too long to check";
16
32
  /** How long after a human decision the user may still approve that exact request once. */
17
33
  export const GRANT_WINDOW_MS = 15 * 60_000;
34
+ /** How long a harness prompt may stay open and still have its answer remembered. */
35
+ const ASK_WINDOW_MS = 60 * 60_000;
36
+ /** A failed tool whose error says the user turned it down: that is not a "yes". */
37
+ const REJECTED = /doesn't want to proceed|does not want to proceed|rejected|denied|declined|not approved|permission/i;
18
38
  /** A grant the service refuses; its message is safe to show the user. */
19
39
  export class GrantError extends Error {
20
40
  }
@@ -41,8 +61,6 @@ export class PolicySession {
41
61
  cache = new Map();
42
62
  pending = new Map();
43
63
  states = new Map();
44
- /** Requests the AI approved, counted once each however often they are retried. */
45
- approvedByAi = new Set();
46
64
  /** Files this session created, and the paths each approved request may create. */
47
65
  created = new Map();
48
66
  creating = new Map();
@@ -52,20 +70,30 @@ export class PolicySession {
52
70
  grants = new Map();
53
71
  /** Session grants: hashes of a human rule and the scope the user approved it for. */
54
72
  sessionGrants = new Set();
73
+ /** Harness prompts waiting for their answer, by `tool_use_id` (or `request:<hash>`). */
74
+ asks = new Map();
75
+ /** Classifications running now, so concurrent hooks for one request share one CLI run. */
76
+ running = new Map();
77
+ /** The classifier CLI is not installed: later requests go straight to a person. */
78
+ classifierMissing = false;
79
+ deps;
55
80
  constructor(directory, harness, sessionId, profile = strictProfile,
56
81
  /** This package's `cli.js`: the path in the record command the hook gives the model. */
57
- cliPath) {
82
+ cliPath, deps = {}) {
58
83
  this.directory = directory;
59
84
  this.harness = harness;
60
85
  this.sessionId = sessionId;
61
86
  this.profile = profile;
62
87
  this.cliPath = cliPath;
88
+ this.deps = {
89
+ classify: deps.classify ??
90
+ ((cli, prompt, profile) => classifyWithCli(cli, prompt, profile.classifier)),
91
+ nativeRules: deps.nativeRules ?? nativeRules,
92
+ };
63
93
  }
64
94
  /**
65
- * The record command the hook gives this session is approved before the policy runs: the
66
- * engine cannot always verify an installed CLI outside the repository or a here-string (strict
67
- * mode never can), so the round trip could not finish. Any other classification record, for
68
- * another session or CLI or with anything added, goes to a person.
95
+ * A command that runs a policy-manager `classify` record goes to a person: the hook classifies
96
+ * requests itself, and an agent that could record its own verdict could approve itself.
69
97
  */
70
98
  classifyRecord(request) {
71
99
  const input = request.input;
@@ -74,18 +102,10 @@ export class PolicySession {
74
102
  typeof command !== "string" ||
75
103
  !looksLikeClassifyRecord(command))
76
104
  return undefined;
77
- const cwd = input.workdir ?? input.cwd ?? request.cwd;
78
- if (this.cliPath &&
79
- cwd === request.cwd &&
80
- input.env === undefined &&
81
- input.shell === undefined &&
82
- input.stdin === undefined &&
83
- isClassifyRecord(command, request.harness, {
84
- cliPath: this.cliPath,
85
- sessionId: this.sessionId,
86
- }))
87
- return result(request, "temp-write", "Records a classification for this session", true);
88
- return result(request, "unknown", "A classification record for another session or CLI, or with anything added, requires human review");
105
+ return {
106
+ ...result(request, "unknown", "A classification record requires human review: the hook classifies requests itself"),
107
+ hard: "foreign-classification-record",
108
+ };
89
109
  }
90
110
  /**
91
111
  * Only the user approves a request once, from their own terminal. A shell command that runs a
@@ -97,7 +117,7 @@ export class PolicySession {
97
117
  return undefined;
98
118
  if (!looksLikeApproveGrant(command))
99
119
  return undefined;
100
- return result(request, "sensitive", APPROVE_GUARD);
120
+ return { ...result(request, "sensitive", APPROVE_GUARD), hard: "self-approve" };
101
121
  }
102
122
  /**
103
123
  * A user approval that covers this human decision: a one-time grant for this exact request
@@ -146,6 +166,13 @@ export class PolicySession {
146
166
  latest = { requestHash, at: entry.at };
147
167
  return latest && { ...latest, harness: this.harness, sessionId: this.sessionId };
148
168
  }
169
+ addSessionGrant(reason, scope) {
170
+ if (this.sessionGrants.size >= 64)
171
+ this.sessionGrants.clear();
172
+ const key = hash([reason, scope]);
173
+ this.sessionGrants.add(key);
174
+ return key;
175
+ }
149
176
  /**
150
177
  * Looks up, and with `confirm` grants, a user approval of a request this session sent to a
151
178
  * person within the last GRANT_WINDOW_MS. Without `session` the next review of that exact
@@ -172,11 +199,8 @@ export class PolicySession {
172
199
  if (!confirm)
173
200
  return { ...preview, granted: false, scope };
174
201
  this.humanDecisions.delete(requestHash);
175
- if (scope === "session" && sessionScope !== undefined) {
176
- if (this.sessionGrants.size >= 64)
177
- this.sessionGrants.clear();
178
- this.sessionGrants.add(hash([preview.reason, sessionScope]));
179
- }
202
+ if (scope === "session" && sessionScope !== undefined)
203
+ this.addSessionGrant(preview.reason, sessionScope);
180
204
  if (this.grants.size >= 64)
181
205
  this.grants.delete(this.grants.keys().next().value ?? "");
182
206
  this.grants.set(requestHash, { phases: new Set() });
@@ -210,24 +234,28 @@ export class PolicySession {
210
234
  if (this.states.size >= 512)
211
235
  this.states.clear();
212
236
  this.states.set(requestHash, {
213
- requested: false,
214
237
  invalid: false,
215
238
  fallback: false,
216
- limited: false,
217
239
  ...this.states.get(requestHash),
218
240
  ...change,
219
241
  expires: Date.now() + CLASSIFICATION_TTL_MS,
220
242
  });
221
243
  }
222
244
  /**
223
- * `phase` is the hook event. Only `PreToolUse` runs the classification flow: the first time an
224
- * ambiguous request arrives it is blocked with an instruction to classify and retry; the next
225
- * time, with no usable classification, a human is asked and the reason is recorded.
245
+ * The deterministic decision for a request, with any classification this session already has
246
+ * for it and the user's own grants applied. Synchronous: it never runs the classifier. A request
247
+ * that still needs one comes back `human` with `needsClassification`; `decide` runs it.
226
248
  */
227
249
  review(request, ai, phase) {
250
+ return this.conclude(request, this.judge(request, ai, phase), ai);
251
+ }
252
+ judge(request, ai, phase,
253
+ /** The request was already recorded by this hook call. */
254
+ again = false) {
228
255
  if (request.sessionId !== this.sessionId || request.harness !== this.harness)
229
256
  throw new Error("Session mismatch");
230
- audit(this.directory, { event: "request", ...requestSummary(request) });
257
+ if (!again)
258
+ audit(this.directory, { event: "request", ...requestSummary(request) });
231
259
  if (ai &&
232
260
  (!CATEGORIES.includes(ai.category) ||
233
261
  typeof ai.confidence !== "number" ||
@@ -244,12 +272,7 @@ export class PolicySession {
244
272
  });
245
273
  throw new Error("Malformed AI classification");
246
274
  }
247
- const key = hash([
248
- requestHashOf(request),
249
- "policy-v1",
250
- this.profile.digest ?? this.profile.mode,
251
- ]);
252
- const entry = this.cache.get(key);
275
+ const entry = this.cache.get(this.cacheKey(request));
253
276
  const cachedAi = entry && entry.expires > Date.now() ? entry.ai : undefined;
254
277
  const requestHash = requestHashOf(request);
255
278
  const known = ai ? undefined : this.state(requestHash);
@@ -268,63 +291,18 @@ export class PolicySession {
268
291
  if (decision.tier === "ambiguous") {
269
292
  if (ai && !decision.classification)
270
293
  this.remember(requestHash, { invalid: true });
271
- else if (ai) {
272
- // The cap is checked when the approval is first given and stored with the outcome, so a
273
- // retry cannot turn a limited request into an approval.
274
- if (decision.classification === "approved" &&
275
- !this.approvedByAi.has(requestHash) &&
276
- this.approvedByAi.size >= MAX_AI_APPROVALS) {
277
- decision = {
278
- ...decision,
279
- decision: "human",
280
- classification: "fallback",
281
- fallbackReason: "limit",
282
- reason: "Session limit on AI approvals reached; a human decides",
283
- };
284
- this.remember(requestHash, { limited: true });
285
- }
286
- else {
287
- if (decision.classification === "approved")
288
- this.approvedByAi.add(requestHash);
289
- this.remember(requestHash, { ai });
290
- }
291
- }
292
- if (decision.needsClassification && !ai && phase === "PreToolUse") {
293
- if (!known?.requested) {
294
- this.remember(requestHash, { requested: true });
295
- audit(this.directory, {
296
- event: "classification-requested",
297
- requestHash,
298
- tier: "ambiguous",
299
- reason: decision.reason,
300
- redactedCommand: redactText(String(request.input.command ?? request.input.cmd ?? request.tool), 300),
301
- });
302
- decision = {
303
- ...decision,
304
- decision: "deny",
305
- classification: "requested",
306
- };
307
- }
308
- else {
309
- const fallbackReason = known.limited
310
- ? "limit"
311
- : known.invalid
312
- ? "invalid-result"
313
- : "unavailable";
314
- if (!known.fallback) {
315
- this.remember(requestHash, { fallback: true });
316
- audit(this.directory, {
317
- event: "classification-fallback",
318
- requestHash,
319
- fallbackReason,
320
- });
321
- }
322
- decision = {
323
- ...decision,
324
- classification: "fallback",
325
- fallbackReason,
326
- };
327
- }
294
+ else if (ai)
295
+ this.remember(requestHash, { ai });
296
+ else if (known?.fallback || known?.invalid) {
297
+ // Classified before without an answer that counts: a person decides, without a new run.
298
+ decision = {
299
+ ...decision,
300
+ needsClassification: false,
301
+ classification: "fallback",
302
+ fallbackReason: known.invalid
303
+ ? "invalid-result"
304
+ : (known.fallbackReason ?? "unavailable"),
305
+ };
328
306
  }
329
307
  }
330
308
  if (decision.decision === "human") {
@@ -332,6 +310,17 @@ export class PolicySession {
332
310
  if (allowed)
333
311
  decision = allowed;
334
312
  }
313
+ return decision;
314
+ }
315
+ cacheKey(request) {
316
+ return hash([requestHashOf(request), "policy-v1", this.profile.digest ?? this.profile.mode]);
317
+ }
318
+ /** Records a final decision: the person's queue, caches, pending creations and the audit log. */
319
+ conclude(request, input, ai) {
320
+ let decision = input;
321
+ const key = this.cacheKey(request);
322
+ const entry = this.cache.get(key);
323
+ const requestHash = decision.requestHash;
335
324
  if (decision.decision === "human" && decision.reason === APPROVE_GUARD) {
336
325
  this.cache.delete(key);
337
326
  decision = { ...decision, userOnly: true, sessionGrantable: false };
@@ -359,6 +348,8 @@ export class PolicySession {
359
348
  ...(sessionScope === undefined ? {} : { sessionScope }),
360
349
  });
361
350
  }
351
+ else
352
+ this.humanDecisions.delete(requestHash);
362
353
  // Evaluation always precedes lookup. Filesystem evidence is never cached.
363
354
  if (decision.decision === "approve" && decision.cache === "session") {
364
355
  decision.cached = entry !== undefined && entry.expires > Date.now() && ai === undefined;
@@ -371,34 +362,35 @@ export class PolicySession {
371
362
  });
372
363
  }
373
364
  }
374
- // A denied request is final for its remembered state: only a human decision or a request
375
- // still waiting for its first classification can be classified.
376
- if ((decision.decision === "human" || decision.classification === "requested") &&
377
- (["unknown", "cloud-read"].includes(decision.category) || decision.needsClassification) &&
365
+ if (decision.needsClassification && !ai)
366
+ this.noteRequested(request, decision);
367
+ // The compatibility `classify` command may still classify a request a person was asked about.
368
+ if (decision.decision === "human" &&
369
+ (["unknown", "cloud-read"].includes(decision.category) || decision.tier === "ambiguous") &&
370
+ !decision.hard &&
378
371
  !ai) {
379
372
  if (this.pending.size >= 64)
380
373
  this.pending.delete(this.pending.keys().next().value ?? "");
381
- this.pending.set(decision.requestHash, request);
374
+ this.pending.set(requestHash, request);
382
375
  }
383
376
  // Every decision replaces the pending creations for this request, so a report can only ever
384
377
  // settle the most recent approval: an earlier approval whose report never came is forgotten.
385
- this.creating.delete(decision.requestHash);
378
+ this.creating.delete(requestHash);
386
379
  if (decision.decision === "approve") {
387
380
  const targets = creationTargets(request, this.created);
388
381
  if (targets.length) {
389
382
  if (this.creating.size >= 256)
390
383
  this.creating.delete(this.creating.keys().next().value ?? "");
391
- this.creating.set(decision.requestHash, {
392
- targets,
393
- approvedAt: Date.now(),
394
- });
384
+ this.creating.set(requestHash, { targets, approvedAt: Date.now() });
395
385
  }
396
386
  }
397
- // The scope label names paths, which audit records never contain.
398
- const { ai: classification, sessionScopeLabel: _label, ...safe } = decision;
387
+ // The scope label names paths, and rules and notes can, which audit records never contain.
388
+ const { ai: classification, sessionScopeLabel: _label, classifierNote: _note, userAllowRule, userRule, ...safe } = decision;
399
389
  audit(this.directory, {
400
390
  event: "decision",
401
391
  ...safe,
392
+ ...(userAllowRule ? { userAllowRule: redactText(userAllowRule, 200) } : {}),
393
+ ...(userRule ? { userRule: redactText(userRule, 200) } : {}),
402
394
  ...(classification
403
395
  ? {
404
396
  ai: {
@@ -411,6 +403,268 @@ export class PolicySession {
411
403
  });
412
404
  return decision;
413
405
  }
406
+ /** Records, once, that an ambiguous request entered classification (for review-classifications). */
407
+ noteRequested(request, decision) {
408
+ if (this.state(decision.requestHash)?.requested)
409
+ return;
410
+ this.remember(decision.requestHash, { requested: true });
411
+ audit(this.directory, {
412
+ event: "classification-requested",
413
+ requestHash: decision.requestHash,
414
+ tier: "ambiguous",
415
+ reason: decision.reason,
416
+ // A permissive profile keeps a redacted command for risk reviews, as before; the strict
417
+ // default keeps only the vocabulary summary every request record has.
418
+ redactedCommand: this.profile.mode === "permissive"
419
+ ? redactText(String(request.input.command ?? request.input.cmd ?? request.tool), 300)
420
+ : String(requestSummary(request).summary),
421
+ });
422
+ }
423
+ /** Runs (or joins) the classifier for a request, audits the run, and returns its result. */
424
+ runClassifier(request, decision) {
425
+ const requestHash = decision.requestHash;
426
+ const running = this.running.get(requestHash);
427
+ if (running)
428
+ return running;
429
+ const cli = request.harness;
430
+ const run = (async () => {
431
+ let outcome;
432
+ if (this.classifierMissing)
433
+ outcome = {
434
+ ok: false,
435
+ reason: "missing",
436
+ cli,
437
+ model: this.profile.classifier[cli].model,
438
+ latencyMs: 0,
439
+ };
440
+ else {
441
+ let prompt;
442
+ try {
443
+ prompt = withCreated(this.created, () => buildPrompt({
444
+ request,
445
+ reason: decision.reason,
446
+ scratchRoots: this.profile.scratchRoots,
447
+ }));
448
+ }
449
+ catch {
450
+ prompt = undefined;
451
+ }
452
+ try {
453
+ // A command over the length cap (no prompt) is never sent anywhere: the person decides.
454
+ outcome =
455
+ prompt === undefined
456
+ ? {
457
+ ok: false,
458
+ reason: "too-long",
459
+ cli,
460
+ model: this.profile.classifier[cli].model,
461
+ latencyMs: 0,
462
+ }
463
+ : await this.deps.classify(cli, prompt, this.profile);
464
+ }
465
+ catch {
466
+ outcome = {
467
+ ok: false,
468
+ reason: "exit",
469
+ cli,
470
+ model: this.profile.classifier[cli].model,
471
+ latencyMs: 0,
472
+ };
473
+ }
474
+ if (!outcome.ok && outcome.reason === "missing")
475
+ this.classifierMissing = true;
476
+ }
477
+ // Model, latency and verdict; never the prompt, which holds the command and paths.
478
+ audit(this.directory, {
479
+ event: "ai-classification",
480
+ requestHash,
481
+ cli: outcome.cli,
482
+ model: outcome.model,
483
+ latencyMs: outcome.latencyMs,
484
+ ...(outcome.ok
485
+ ? {
486
+ outcome: "verdict",
487
+ category: outcome.verdict.category,
488
+ confidence: outcome.verdict.confidence,
489
+ recoverable: outcome.verdict.recoverable,
490
+ }
491
+ : { outcome: "failure", failure: outcome.reason }),
492
+ });
493
+ return outcome;
494
+ })();
495
+ this.running.set(requestHash, run);
496
+ return run.finally(() => this.running.delete(requestHash));
497
+ }
498
+ /**
499
+ * The hook's decision. The deterministic engine approves what it can prove safe; otherwise the
500
+ * AI classifier is run synchronously and approves when `recoverable && confidence >= 0.95 &&
501
+ * category not in {sensitive, unknown}`; otherwise a person is asked. The user's own harness
502
+ * rules apply throughout: their deny or ask rule leaves the request to the harness (no
503
+ * decision), and their allow rule counts as the person's answer.
504
+ */
505
+ async decide(request, phase, toolUseId,
506
+ /** The harness's permission mode (Claude Code's `permission_mode`), when it reports one. */
507
+ permissionMode) {
508
+ // A command too long to check is asked at once, before any parsing.
509
+ const command = request.input.command ?? request.input.cmd;
510
+ if (typeof command === "string" && command.length > MAX_HOOK_COMMAND)
511
+ return this.conclude(request, {
512
+ ...result(request, "unknown", TOO_LONG_REASON),
513
+ needsClassification: false,
514
+ fallbackReason: "too-long",
515
+ });
516
+ let decision = this.judge(request, undefined, phase);
517
+ const native = decision.decision === "approve" || decision.decision === "human"
518
+ ? this.userRule(request)
519
+ : undefined;
520
+ if (native && native.verdict !== "allow")
521
+ return this.conclude(request, {
522
+ ...decision,
523
+ decision: "native",
524
+ needsClassification: false,
525
+ userRule: native.rule,
526
+ reason: `The user's own ${native.verdict} rule applies`,
527
+ });
528
+ // An allow rule is the person's answer, checked before the classifier so an allowed command
529
+ // never waits on a run. Never for the built-in guards on the policy manager's own approvals,
530
+ // and never for NO_ALLOW: credential reads, writes to what the harness allows, a force push.
531
+ const guarded = decision.reason === APPROVE_GUARD ||
532
+ decision.hard === "self-approve" ||
533
+ decision.hard === "foreign-classification-record";
534
+ if (decision.decision === "human" && native?.verdict === "allow" && !guarded) {
535
+ const kept = hardRules(request, decision, this.profile.scratchRoots).find((rule) => NO_ALLOW.has(rule));
536
+ if (kept) {
537
+ audit(this.directory, {
538
+ event: "user-rule-overridden",
539
+ requestHash: decision.requestHash,
540
+ rule: kept,
541
+ });
542
+ }
543
+ else {
544
+ audit(this.directory, {
545
+ event: "human-response",
546
+ requestHash: decision.requestHash,
547
+ response: "approved",
548
+ summary: "Allowed by the user's own permission rule",
549
+ });
550
+ return this.conclude(request, {
551
+ ...result(request, decision.category, "Allowed by the user's own permission rule", true),
552
+ userAllowRule: native.rule,
553
+ });
554
+ }
555
+ }
556
+ if (decision.decision === "human" && decision.needsClassification && !decision.ai) {
557
+ this.noteRequested(request, decision);
558
+ const outcome = await this.runClassifier(request, decision);
559
+ if (outcome.ok)
560
+ decision = this.judge(request, { ...outcome.verdict, requestHash: decision.requestHash }, phase, true);
561
+ else {
562
+ this.remember(decision.requestHash, { fallback: true, fallbackReason: outcome.reason });
563
+ audit(this.directory, {
564
+ event: "classification-fallback",
565
+ requestHash: decision.requestHash,
566
+ fallbackReason: outcome.reason,
567
+ });
568
+ decision = {
569
+ ...decision,
570
+ needsClassification: false,
571
+ classification: "fallback",
572
+ fallbackReason: outcome.reason,
573
+ };
574
+ }
575
+ }
576
+ decision = this.conclude(request, decision);
577
+ if (decision.decision === "human" && phase === "PreToolUse")
578
+ this.awaitAnswer(request, decision, toolUseId, permissionMode);
579
+ return decision;
580
+ }
581
+ /**
582
+ * Marks an existing file as created by this session, for `replay`, which rebuilds what a past
583
+ * session created from its transcript. The service never calls it.
584
+ */
585
+ noteCreated(path) {
586
+ const at = located(dirname(path), basename(path));
587
+ const now = at && stamp(at);
588
+ if (at && now)
589
+ this.created.set(pathKey(at), now);
590
+ }
591
+ userRule(request) {
592
+ try {
593
+ return this.deps.nativeRules(request);
594
+ }
595
+ catch {
596
+ return undefined;
597
+ }
598
+ }
599
+ /**
600
+ * The hook asked, so the harness prompts the person. Its PostToolUse for this exact tool call
601
+ * means they said yes, but only when the harness reports a permission mode in which an ask is
602
+ * really shown to a person: Claude Code's `default`, `acceptEdits` or `plan`. Under
603
+ * `bypassPermissions`, `dontAsk`, an auto mode, or with no mode reported (Copilot reports none,
604
+ * so `--allow-all`/`--yolo` cannot be told apart), nothing is remembered. Codex cannot ask.
605
+ */
606
+ awaitAnswer(request, decision, toolUseId, permissionMode) {
607
+ if (this.harness !== "claude")
608
+ return;
609
+ if (!permissionMode || !PROMPTING_MODES.has(permissionMode))
610
+ return;
611
+ if (!toolUseId || !/^[\w.:-]{1,200}$/.test(toolUseId))
612
+ return;
613
+ if (this.asks.size >= 256)
614
+ this.asks.delete(this.asks.keys().next().value ?? "");
615
+ this.asks.set(toolUseId, { request, decision, at: Date.now() });
616
+ }
617
+ /**
618
+ * PostToolUse (or PostToolUseFailure) for a tool call the harness asked the person about: they
619
+ * said yes. The answer is remembered like `approve --session`: the same rule for the same scope
620
+ * is approved for the rest of the session (a protected root, a humanPatterns entry, or the exact
621
+ * command for other rules); unknown, sensitive and destructive requests stay once-only.
622
+ */
623
+ answered(report) {
624
+ const key = this.harness === "claude"
625
+ ? report.toolUseId
626
+ : this.harness === "copilot"
627
+ ? `request:${report.requestHash}`
628
+ : undefined;
629
+ if (!key)
630
+ return undefined;
631
+ const ask = this.asks.get(key);
632
+ if (!ask || ask.decision.requestHash !== report.requestHash)
633
+ return undefined;
634
+ this.asks.delete(key);
635
+ if (Date.now() - ask.at > ASK_WINDOW_MS)
636
+ return undefined;
637
+ if (report.phase === "PostToolUseFailure" &&
638
+ (report.interrupted || REJECTED.test(report.error ?? ""))) {
639
+ audit(this.directory, {
640
+ event: "human-response",
641
+ requestHash: report.requestHash,
642
+ response: "denied",
643
+ summary: "The harness prompt did not run the tool",
644
+ });
645
+ return "rejected";
646
+ }
647
+ this.humanDecisions.delete(report.requestHash);
648
+ const scope = grantScope(ask.request, ask.decision, this.profile);
649
+ audit(this.directory, {
650
+ event: "human-response",
651
+ requestHash: report.requestHash,
652
+ response: "approved",
653
+ summary: "User approved the harness prompt",
654
+ });
655
+ if (scope === undefined)
656
+ return "once";
657
+ const scopeHash = this.addSessionGrant(ask.decision.reason, scope);
658
+ audit(this.directory, {
659
+ event: "human-grant",
660
+ requestHash: report.requestHash,
661
+ category: ask.decision.category,
662
+ scope: "session",
663
+ scopeHash,
664
+ summary: "User approved the harness prompt; the rule is remembered for this session",
665
+ });
666
+ return "session";
667
+ }
414
668
  record(report) {
415
669
  if (!report || !/^[a-f0-9]{64}$/.test(report.requestHash))
416
670
  throw new Error("A request hash is required");
@@ -461,20 +715,23 @@ export class PolicySession {
461
715
  else
462
716
  throw new Error("Invalid outcome event");
463
717
  }
718
+ /** The compatibility `classify` command: a recorded classification for a pending request. */
464
719
  classify(classification) {
465
720
  const request = this.pending.get(classification.requestHash);
466
721
  if (!request)
467
722
  throw new Error("No pending request matches the classification");
468
- // One classification per request: a verdict, deny or approve, cannot be replaced.
469
- if (this.state(classification.requestHash)?.ai)
723
+ // One classification per request: a verdict, deny or approve, cannot be replaced. A request
724
+ // the hook's classifier could not settle (too long, disabled, missing, failed) is a person's.
725
+ const known = this.state(classification.requestHash);
726
+ if (known?.ai)
470
727
  throw new Error("The request is already classified");
728
+ if (known?.fallback || known?.invalid)
729
+ throw new Error("The request is waiting for a person, not a classification");
471
730
  this.pending.delete(classification.requestHash);
472
731
  try {
473
732
  return this.review(request, classification);
474
733
  }
475
734
  catch (error) {
476
- // A malformed result is not an approval; the retry will fall back to a human, with the
477
- // reason recorded for the review.
478
735
  this.remember(classification.requestHash, { invalid: true });
479
736
  throw error;
480
737
  }
package/dist/shell.d.ts CHANGED
@@ -12,6 +12,8 @@ export interface SimpleCommand {
12
12
  subs: string[];
13
13
  /** For each argv word, whether it contains an unquoted unknown value (it could split). */
14
14
  loose?: boolean[];
15
+ /** For each argv word, whether it has an unquoted `*`, `?` or `[` the shell may expand. */
16
+ glob?: boolean[];
15
17
  /** Literal text fed to standard input by a heredoc or here-string, when there is one. */
16
18
  stdin?: string;
17
19
  }
package/dist/shell.js CHANGED
@@ -56,7 +56,7 @@ function plainSimple(command) {
56
56
  redirects.push(plain);
57
57
  subs.push(...(redir.target?.subs ?? []));
58
58
  }
59
- return { env, argv, redirects, subs, loose };
59
+ return { env, argv, redirects, subs, loose, glob: simple.argv.map((w) => w.glob === true) };
60
60
  }
61
61
  function flatten(andOr) {
62
62
  const pipelines = [];