@stratusagent/permissions 0.14.1 → 0.14.3

package/dist/index.js

@@ -6,6 +6,8 @@ import { sessionTaintedBy, sessionTrustOf } from '@stratusagent/core';
  */
 export { atLeastAsRisky } from '@stratusagent/core';
 import { downloadInsideWorkspace, gitInsideWorkspace, gitPushInsideWorkspace, readsInsideWorkspace } from "./workspace.js";
+import { builtInReviewRule, describeReviewRule, matchReviewRule, readReviewAnswer, ReviewFailure, } from "./review.js";
+export { builtInReviewRule, describeReviewRule, matchReviewRule, parseReviewRule, readReviewAnswer, REVIEW_CODES, ReviewFailure, } from "./review.js";
 export { downloadInsideWorkspace, gitInsideWorkspace, gitPushInsideWorkspace, readsInsideWorkspace } from "./workspace.js";
 import { analyzeCommand, describeCommandScope, findCoveringScopes, findMatchingScope, normalizeCommandScope, SAFE_COMMAND_SCOPES, } from "./commands.js";
 import { describeOriginScope, findMatchingOriginScope, originScopeFor, trustedDomainOf, } from "./origins.js";
@@ -77,6 +79,8 @@ const READ_ORIGIN_TOOL = 'web.fetch';
 const YES = new Set(['y', 'yes', 'always', 'a']);
 const ALWAYS = new Set(['always', 'a']);
 const ABORTED = Symbol('aborted');
+/** How long one review may take before it counts as failed (`approvals.review.timeoutMs`). */
+export const DEFAULT_REVIEW_TIMEOUT_MS = 20_000;
 /**
  * Waits for `work`, but gives up the moment the turn is cancelled.
  *
@@ -197,7 +201,9 @@ const awaitPrompt = async (context, ask, command, origin,
  * is the only place that knows. Offering a lifetime the engine will not
  * create is the same defect as hiding one it will.
  */
-alwaysMeans) => {
+alwaysMeans, 
+/** Why the review posture is asking, shown above the question. */
+note) => {
     const { call, risk, session } = context;
     // The command, when there is one: for a shell call the tool name is the
     // least interesting half of the question, and an approver shown only
@@ -218,7 +224,7 @@ alwaysMeans) => {
         : argumentSummary !== undefined
             ? `${acting} (${risk}): ${argumentSummary}`
             : `${acting} (${risk})`;
-    const pending = ask(`Allow ${what} for ${session.agent.name}? [y]es / [a]lways (${alwaysMeans}) / [N]o: `);
+    const pending = ask(`${note === undefined ? '' : `Review: ${note}\n`}Allow ${what} for ${session.agent.name}? [y]es / [a]lways (${alwaysMeans}) / [N]o: `);
     // The answer is never read after this point if the turn ends first,
     // so a late yes cannot execute a tool for work that no longer exists.
     pending.catch(() => undefined);
@@ -243,7 +249,7 @@ alwaysMeans) => {
  * its call was not approved and carry on, not crash on the machinery that
  * was supposed to ask.
  */
-const awaitRemote = async (context, request, origin, oneShot, always) => {
+const awaitRemote = async (context, request, origin, oneShot, always, note) => {
     const pending = request({
         session: context.session,
         call: context.call,
@@ -253,6 +259,7 @@ const awaitRemote = async (context, request, origin, oneShot, always) => {
         ...(oneShot ? { oneShot } : {}),
         ...(always !== undefined ? { always } : {}),
         ...(context.parkedAt ? { parkedAt: context.parkedAt } : {}),
+        ...(note !== undefined ? { reviewNote: note } : {}),
         ...(context.signal ? { signal: context.signal } : {}),
     }).then((outcome) => (typeof outcome === 'string' ? { answer: outcome } : outcome), () => ({ answer: 'deny' }));
     return untilAborted(pending, context.signal);
@@ -298,7 +305,7 @@ const commandNames = (analysis) => {
     return analysis.base;
 };
 export const createPermissionPolicy = (options) => {
-    const { mode, ask, request, onDecision, commands, destinations, origins, grants, gateExternalContent, openFor } = options;
+    const { mode, ask, request, onDecision, commands, destinations, origins, grants, gateExternalContent, openFor, review } = options;
     if (mode === 'interactive' && !ask) {
         throw new Error('interactive permission mode needs an `ask` function to reach a human.');
     }
@@ -329,6 +336,14 @@ export const createPermissionPolicy = (options) => {
     const rememberForProcess = (tier, agentId, grant) => {
         tier.set(agentId, [...(tier.get(agentId) ?? []), grant]);
     };
+    /**
+     * The review posture's bookkeeping, keyed by the call's context so the
+     * many `report` sites need no new arguments: which contexts are a shadow
+     * review (decisions marked `shadow`, nobody asked), and what a rule or
+     * the reviewer answered for a call that went on to a person.
+     */
+    const shadowContexts = new WeakSet();
+    const reviewNotes = new WeakMap();
     /** A site this agent may read without asking: trusted, or approved for `web.fetch`. */
     const readableSite = async (agentId, site) => {
         if (trustedDomainOf(site, origins?.trustedDomainsFor?.(agentId) ?? []) !== undefined) {
@@ -341,6 +356,13 @@ export const createPermissionPolicy = (options) => {
         return findMatchingOriginScope(site, granted, READ_ORIGIN_TOOL) !== undefined;
     };
     const report = (context, layer, allowed, reason, command, destination, origin, grant, destinationGrant) => {
+        const note = reviewNotes.get(context);
+        const shadow = shadowContexts.has(context);
+        const reviewed = {
+            ...(note === undefined ? {} : { verdict: note.verdict }),
+            ...(note?.reviewCode === undefined ? {} : { reviewCode: note.reviewCode }),
+            ...(shadow ? { shadow: true } : {}),
+        };
         onDecision?.({
             allowed,
             mode,
@@ -348,6 +370,7 @@ export const createPermissionPolicy = (options) => {
             toolName: context.call.toolName,
             sessionId: context.session.id,
             agentId: context.session.agent.id,
+            callId: context.call.id,
             reason,
             ...(command === undefined ? {} : { command }),
             ...(destination === undefined ? {} : { destination }),
@@ -355,21 +378,202 @@ export const createPermissionPolicy = (options) => {
             ...(grant === undefined ? {} : { grant }),
             ...(destinationGrant === undefined ? {} : { destinationGrant }),
             layer,
+            ...reviewed,
         });
-        return allowed;
+        // The same three fields the log gets, and nothing else: the runner's
+        // event carries no command, grant or destination record, so what a
+        // dashboard shows is a classification, never the call's input. The
+        // review fields are a verdict and a fixed code, never the reviewer's
+        // words.
+        context.decided?.({ allowed, layer, reason, ...reviewed });
+        // The reason is what the agent is told: it names the check that
+        // refused and what would cover the call, which is what lets the agent
+        // pick another way instead of trying the same call again.
+        return allowed ? true : { allowed: false, reason };
     };
-    return {
+    /**
+     * A refusal whose words for the agent differ from the log's: the
+     * reviewer's line can echo the call's input, so it goes to the agent
+     * (and, for an ask, the approver) and never into a decision.
+     */
+    const refuse = (context, layer, reason, told) => {
+        report(context, layer, false, reason);
+        return { allowed: false, reason: told };
+    };
+    /**
+     * Puts one call to the reviewer, bounded by `timeoutMs` and the turn's
+     * signal. Never throws: a review that couldn't run is a failure kind,
+     * which the caller turns into an ask.
+     */
+    const runReview = async (context, timeoutMs, resolved) => {
+        if (context.signal?.aborted) {
+            return ABORTED;
+        }
+        const reviewer = review?.reviewer;
+        if (reviewer === undefined) {
+            return { failed: 'no reviewer' };
+        }
+        const controller = new AbortController();
+        const onTurnAbort = () => controller.abort();
+        context.signal?.addEventListener('abort', onTurnAbort, { once: true });
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve({ failed: 'timeout' });
+            }, timeoutMs);
+        });
+        try {
+            // Inside a promise, so a reviewer that throws before it returns one
+            // is a failed review like any other, never a failed turn.
+            const asked = new Promise((resolve) => {
+                resolve(reviewer({
+                    session: context.session,
+                    call: context.call,
+                    tool: context.tool,
+                    risk: context.risk,
+                    ...resolved,
+                    signal: controller.signal,
+                }));
+            }).then((raw) => {
+                const answer = readReviewAnswer(raw);
+                return answer === undefined ? { failed: 'unparseable' } : { answer };
+            }, (error) => ({ failed: error instanceof ReviewFailure ? error.kind : 'error' }));
+            const settled = await untilAborted(Promise.race([asked, timedOut]), context.signal);
+            return settled;
+        }
+        finally {
+            clearTimeout(timer);
+            context.signal?.removeEventListener('abort', onTurnAbort);
+        }
+    };
+    const policy = {
         async approve(context) {
             const { call, risk, session } = context;
             if (risk === 'safe') {
                 return report(context, 'risk', true, `${call.toolName} is safe and runs without approval`);
             }
-            if (risk === 'gated' && openFor?.(session.agent.id) === true) {
+            // The review posture, for a gated call. A shadow review is this same
+            // method run again on a marked copy of the context, off the call
+            // path: it works the review out and asks nobody.
+            const reviewSettings = risk === 'gated' ? review?.settingsFor(session.agent.id) : undefined;
+            const shadowRun = shadowContexts.has(context);
+            const reviewing = reviewSettings !== undefined && (shadowRun || reviewSettings.shadow !== true);
+            if (reviewSettings?.shadow === true && !shadowRun && context.parkedAt === undefined) {
+                const shadowContext = { ...context };
+                shadowContexts.add(shadowContext);
+                void policy.approve(shadowContext).catch(() => undefined);
+            }
+            // A call parked before a restart is owed a person's answer: the fast
+            // path never takes it, whatever the posture has become since.
+            if (risk === 'gated' && !reviewing && context.parkedAt === undefined
+                && (openFor?.(session.agent.id) === true || reviewSettings?.shadow === true)) {
                 const closedByContent = sessionTrustOf(session) === 'external' && gateExternalContent?.(session.agent.id) === true;
                 if (!closedByContent) {
-                    return report(context, 'risk', true, `${call.toolName} runs without asking (approvals.posture is open)`);
+                    return report(context, 'risk', true, reviewSettings?.shadow === true
+                        ? `${call.toolName} runs without asking (approvals.review.shadow: reviewed off the call path, not enforced)`
+                        : `${call.toolName} runs without asking (approvals.posture is open)`);
                 }
             }
+            // Steps 3 to 5 of the review, before any grant is read: the
+            // operator's rules, the unreviewed run for a conversation that has
+            // read nothing from outside, and the built-in rules. An ask from any
+            // of them goes to a person and skips everything a grant could cover,
+            // since the first step that settles a call wins.
+            let reviewAsk;
+            const reviewHooks = [context.tool.commandFor, context.tool.destinationFor, context.tool.originFor]
+                .filter((hook) => hook !== undefined).length;
+            const reviewed = reviewing && reviewHooks <= 1
+                ? {
+                    command: context.tool.commandFor?.(call.input),
+                    destination: context.tool.destinationFor?.(call.input),
+                    origin: originScopeFor(context.tool.originFor?.(session, call.input) ?? '')?.origin,
+                }
+                : {};
+            const resolvedForReview = Object.fromEntries(Object.entries(reviewed).filter(([, value]) => value !== undefined));
+            // A call parked before a restart was waiting on a person, and goes
+            // back to one: nothing that would allow it now (a rule, the
+            // unreviewed path, a scope, the reviewer) may turn a pending ask into
+            // an allow. Only a block can still stop it first.
+            const resumed = reviewing && context.parkedAt !== undefined;
+            if (reviewing) {
+                const matched = matchReviewRule(reviewSettings.rules ?? [], { toolName: call.toolName, ...resolvedForReview });
+                if (matched !== undefined) {
+                    reviewNotes.set(context, { verdict: matched.verdict });
+                    const named = `the operator's rule (${describeReviewRule(matched)}) in approvals.rules`;
+                    if (matched.verdict === 'allow' && !resumed) {
+                        return report(context, 'rule', true, `${call.toolName} runs under ${named}`);
+                    }
+                    if (matched.verdict === 'block') {
+                        return report(context, 'rule', false, `${call.toolName} is blocked by ${named}; only the operator can change it, so a confirmation won't help`);
+                    }
+                    if (matched.verdict === 'ask') {
+                        reviewAsk = {
+                            layer: 'rule',
+                            reason: `${call.toolName} is asked about by ${named}`,
+                            told: `${call.toolName} is asked about by ${named}`,
+                            note: `asked about by the operator's rule (${describeReviewRule(matched)})`,
+                        };
+                    }
+                }
+                if (reviewAsk === undefined && !resumed && sessionTrustOf(session) !== 'external') {
+                    return report(context, 'risk', true, `${call.toolName} not reviewed: this conversation has read nothing from outside`);
+                }
+                // The stored values, for the rule against sending one out, read
+                // within the review's time and the turn. A store that can't be read
+                // (or doesn't answer) asks, like any other part of the review that
+                // couldn't run: never a failed turn, never an allow. The metadata
+                // and token rules need no stored value, so they still run first.
+                let secrets = [];
+                let secretsUnreadable = false;
+                if (reviewAsk === undefined) {
+                    secretsUnreadable = true;
+                    let timer;
+                    try {
+                        const lookup = Promise.resolve(review?.secretsFor?.(session.agent.id));
+                        const timedOut = new Promise((resolve) => {
+                            timer = setTimeout(() => resolve(ABORTED), reviewSettings.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS);
+                        });
+                        const read = await untilAborted(Promise.race([lookup, timedOut]), context.signal);
+                        if (read !== ABORTED) {
+                            secrets = read ?? [];
+                            secretsUnreadable = false;
+                        }
+                        else {
+                            lookup.catch(() => undefined);
+                        }
+                    }
+                    catch {
+                        // Unreadable: stays an ask below.
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                }
+                if (reviewAsk === undefined) {
+                    const hit = builtInReviewRule({ toolName: call.toolName, input: call.input, ...(resolvedForReview.command === undefined ? {} : { command: resolvedForReview.command }) }, secrets);
+                    if (hit !== undefined) {
+                        reviewNotes.set(context, { verdict: hit.verdict });
+                        if (hit.verdict === 'block') {
+                            return report(context, 'rule', false, `${hit.reason}; only the operator can change that (approvals.rules)`);
+                        }
+                        reviewAsk = { layer: 'rule', reason: hit.reason, told: hit.reason, note: hit.reason };
+                    }
+                }
+                if (reviewAsk === undefined && secretsUnreadable) {
+                    reviewNotes.set(context, { verdict: 'ask', reviewCode: 'review-failed' });
+                    const reason = `${call.toolName} needs a person's yes because the review couldn't run: secrets-unreadable`;
+                    reviewAsk = { layer: 'review', reason, told: reason, note: 'the review couldn\'t run: secrets-unreadable' };
+                }
+                if (reviewAsk === undefined && resumed) {
+                    reviewNotes.set(context, { verdict: 'ask' });
+                    const reason = `${call.toolName} was waiting for a person before a restart, and goes back to them without another review`;
+                    reviewAsk = { layer: 'review', reason, told: reason, note: 'waiting for you before a restart; not reviewed again' };
+                }
+            }
+            // Nothing a grant or a scope could cover applies to a call a review
+            // rule already sent to a person.
+            const grantsConsidered = reviewAsk === undefined;
             // What this *invocation* would run, for a tool whose danger lives in
             // its arguments. Resolved before anything else so that the tool-wide
             // "always" below can never apply to it: one yes to `git status` must
@@ -428,8 +632,11 @@ export const createPermissionPolicy = (options) => {
             // operator turns off, and then it guards nothing. A stranger's
             // message, the other common `unknown`, is what `principals.admit`
             // exists to refuse before the turn starts.
+            // The review posture includes the gate: after outside content, a
+            // grant answered a question about calls the agent chose, not calls a
+            // page might be choosing.
             const externalGate = sessionTrustOf(session) === 'external'
-                && gateExternalContent?.(session.agent.id) === true;
+                && (gateExternalContent?.(session.agent.id) === true || reviewing);
             /**
              * Workspace autonomy for one command in one directory: a read inside
              * it, local git, a plain download from a readable site, or a push of
@@ -451,7 +658,7 @@ export const createPermissionPolicy = (options) => {
                 // And not for an agent the gate is on for at all: the shell
                 // marks its output `unknown`, not `external`, so a page read
                 // this way would never close the gate it exists to close.
-                const gated = gateExternalContent?.(session.agent.id) === true;
+                const gated = gateExternalContent?.(session.agent.id) === true || reviewing;
                 const site = gated ? undefined : await downloadInsideWorkspace(stage, cwd, workspace);
                 if (site !== undefined && await readableSite(session.agent.id, site)) {
                     return true;
@@ -514,7 +721,7 @@ export const createPermissionPolicy = (options) => {
             // commands nothing covered.
             const grantRoot = analysis ? commands?.grantRootFor?.(session.agent.id) : undefined;
             let judgement;
-            if (analysis) {
+            if (analysis && grantsConsidered) {
                 if (!analysis.disqualifiedBy) {
                     // The built-in safe scopes survive the gate and granted ones do
                     // not: `git status` was judged safe for any caller, while a
@@ -614,14 +821,14 @@ export const createPermissionPolicy = (options) => {
                         return report(context, judgement.coveredBy, true, `${call.toolName} ran ${names.join(', ')}, each inside what ${session.agent.id} may run unattended`, command);
                     }
                 }
-                else if (analysis.disqualifiedBy && mode === 'headless') {
+                else if (analysis.disqualifiedBy && mode === 'headless' && !reviewing) {
                     // Never auto-approved, whatever the base command is: a safe scope
                     // in front of a backgrounding `&` is the exact shape this rule
                     // exists for.
                     return report(context, 'parse', false, `${call.toolName} cannot run unattended: ${analysis.disqualifiedBy}`, command);
                 }
             }
-            else if (risk === 'gated' && unscoped && !externalGate) {
+            else if (risk === 'gated' && unscoped && !externalGate && grantsConsidered) {
                 // The standing grant: this process's answers first, then the file.
                 // Read per call, never cached here, so a revocation through the
                 // store is the next call's answer — the reason a revoke needs no
@@ -636,17 +843,20 @@ export const createPermissionPolicy = (options) => {
             }
             else if (risk !== 'dangerous'
                 && !externalGate
+                && grantsConsidered
                 && !scopedByOrigin
                 && !multiplyScoped
                 && alwaysAllowed.has(sessionKey(session.id, call.toolName))) {
                 return report(context, 'grant', true, `${call.toolName} was approved for the rest of this session`);
             }
             // Which workspace this destination is in right now, for binding a
-            // grant to it (see `DestinationScopeOptions.accountFor`).
-            const account = destination !== undefined
+            // grant to it (see `DestinationScopeOptions.accountFor`). Only looked
+            // up when a grant could answer: a call an ask rule or the gate sends
+            // to a person doesn't wait on, or fail with, the lookup.
+            const account = destination !== undefined && !externalGate && grantsConsidered
                 ? await destinations?.accountFor?.(session.agent.id, destination)
                 : undefined;
-            if (destination !== undefined && !externalGate) {
+            if (destination !== undefined && !externalGate && grantsConsidered) {
                 // Read per call, never cached here, so a revoke is the next call's answer.
                 const standing = findMatchingDestinationGrant(call.toolName, destination, account, contributor, [
                     ...(processDestinations.get(session.agent.id) ?? []),
@@ -666,6 +876,7 @@ export const createPermissionPolicy = (options) => {
             // standing yes, so a page the conversation read cannot steer a post.
             if (destination !== undefined
                 && !externalGate
+                && grantsConsidered
                 && contributor === undefined
                 && context.tool.name === call.toolName
                 && STANDING_CHANNEL_TOOLS.includes(call.toolName)
@@ -673,7 +884,7 @@ export const createPermissionPolicy = (options) => {
                 && await destinations?.conversationKindFor?.(session.agent.id, destination) === 'channel') {
                 return report(context, 'grant', true, `${call.toolName} to ${destination} ran under the operator's standing channel authorization (approvals.channels)`, undefined, destination);
             }
-            if (origin !== undefined) {
+            if (origin !== undefined && grantsConsidered) {
                 const granted = findMatchingOriginScope(origin, grantedOrigins, call.toolName);
                 if (granted) {
                     return report(context, 'grant', true, `${call.toolName} acted on the approved site ${describeOriginScope(granted)}`, undefined, undefined, origin);
@@ -695,13 +906,63 @@ export const createPermissionPolicy = (options) => {
             // reports to a channel is the job such a schedule is approved for,
             // so withdrawing it would refuse every firing; and what the page can
             // steer is only the words, sent to the one place a person picked.
-            if (risk === 'gated' && singlyScoped && destinations) {
+            if (risk === 'gated' && singlyScoped && destinations && grantsConsidered) {
                 const destination = context.tool.destinationFor?.(call.input);
                 if (destination !== undefined
                     && await destinations.isPreauthorized(session, destination)) {
                     return report(context, 'grant', true, `${call.toolName} to ${destination} was pre-authorized when this schedule was approved`, undefined, destination);
                 }
             }
+            // Step 7: nothing above settled it, so the reviewer does. (A resumed
+            // call never gets here: it was sent back to its person above.)
+            if (reviewing && reviewAsk === undefined) {
+                const outcome = await runReview(context, reviewSettings.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS, resolvedForReview);
+                if (outcome === ABORTED) {
+                    return report(context, 'cancelled', false, `${call.toolName} was cancelled while it was being reviewed`);
+                }
+                if ('failed' in outcome) {
+                    reviewNotes.set(context, { verdict: 'ask', reviewCode: 'review-failed' });
+                    const reason = `${call.toolName} needs a person's yes because the review couldn't run: ${outcome.failed}`;
+                    reviewAsk = { layer: 'review', reason, told: reason, note: `the review couldn't run: ${outcome.failed}` };
+                }
+                else {
+                    const { answer } = outcome;
+                    reviewNotes.set(context, { verdict: answer.verdict, reviewCode: answer.code });
+                    if (answer.verdict === 'allow') {
+                        // The review took time, and a page can move in it: a yes given
+                        // for one site must not land a click on another. Same rule as
+                        // a person's yes (`allowUnlessMoved`).
+                        if (context.tool.originFor !== undefined && reviewHooks <= 1) {
+                            const settled = originScopeFor(context.tool.originFor(session, call.input) ?? '')?.origin;
+                            if (settled !== resolvedForReview.origin) {
+                                return report(context, 'review', false, `${call.toolName} was allowed by the reviewer on ${resolvedForReview.origin ?? 'a page with no origin'}, `
+                                    + `but the conversation is on ${settled ?? 'no page'} now — it did not run`);
+                            }
+                        }
+                        return report(context, 'review', true, `${call.toolName} was allowed by the reviewer (${answer.code})`);
+                    }
+                    if (answer.verdict === 'block') {
+                        // No flag the agent can set to escalate: an injected page could
+                        // tell it to set one. The person's confirmation in their next
+                        // message is part of what the reviewer sees next time.
+                        return refuse(context, 'review', `${call.toolName} was blocked by the reviewer (${answer.code})`, `${call.toolName} was blocked: ${answer.reason.replace(/[.\s]+$/, '')}. If the person you're working for really wants this, tell them what it would do and ask them to confirm.`);
+                    }
+                    reviewAsk = {
+                        layer: 'review',
+                        reason: `${call.toolName} was asked about by the reviewer (${answer.code})`,
+                        told: `${call.toolName} needs a person's yes: ${answer.reason.replace(/[.\s]+$/, '')}`,
+                        note: answer.reason,
+                    };
+                }
+            }
+            // A shadow review stops here: it reports what it would have asked,
+            // and asks nobody.
+            if (shadowRun) {
+                return report(context, reviewAsk?.layer ?? 'review', false, `${reviewAsk?.reason ?? `${call.toolName} would need a person`} (would ask)`);
+            }
+            if (mode === 'headless' && reviewAsk !== undefined) {
+                return refuse(context, reviewAsk.layer, `${reviewAsk.reason}; nobody is set up to approve this`, `${reviewAsk.told}; nobody is set up to approve this`);
+            }
             if (mode === 'headless') {
                 return report(context, 
                 // A `dangerous` tool before the gate: no grant covers one either
@@ -801,7 +1062,10 @@ export const createPermissionPolicy = (options) => {
             // front of the approver was composed after a page had its say, and
             // "always" there would let the page talk a person into exactly the
             // standing authority the gate withdrew.
+            // And under the review posture every ask is one-shot: an "always"
+            // there would promise a grant the policy then sets aside.
             const oneShot = risk === 'dangerous'
+                || reviewing
                 || externalGate
                 || multiplyScoped
                 || (scopedByOrigin && origin === undefined)
@@ -823,13 +1087,15 @@ export const createPermissionPolicy = (options) => {
             const alwaysMeans = oneShot
                 ? risk === 'dangerous'
                     ? 'not remembered — a dangerous tool asks every time'
-                    : externalGate
-                        ? 'not remembered — this conversation has read external content, so it asks every time'
-                        : multiplyScoped
-                            ? 'not remembered — this tool names more than one kind of scope'
-                            : analysis !== undefined
-                                ? 'not remembered — this command cannot be reduced to a scope'
-                                : 'not remembered — there is no page to grant'
+                    : reviewing
+                        ? 'not remembered — under the review posture an answer covers this call only'
+                        : externalGate
+                            ? 'not remembered — this conversation has read external content, so it asks every time'
+                            : multiplyScoped
+                                ? 'not remembered — this tool names more than one kind of scope'
+                                : analysis !== undefined
+                                    ? 'not remembered — this command cannot be reduced to a scope'
+                                    : 'not remembered — there is no page to grant'
                 : always === 'scope'
                     ? usePlan && plan !== undefined
                         ? `always ${[...plan.names, ...plan.scopes.map(describeCommandScope)].join(', ')} for ${session.agent.name}`
@@ -843,8 +1109,8 @@ export const createPermissionPolicy = (options) => {
                                 ? `always ${destination} for ${session.agent.name}, until revoked`
                                 : 'always this session';
             const outcome = mode === 'remote'
-                ? await awaitRemote(context, request, origin, oneShot, always)
-                : await awaitPrompt(context, ask, command, origin, alwaysMeans);
+                ? await awaitRemote(context, request, origin, oneShot, always, reviewAsk?.note)
+                : await awaitPrompt(context, ask, command, origin, alwaysMeans, reviewAsk?.note);
             if (outcome === ABORTED) {
                 return report(context, 'cancelled', false, `${call.toolName} was cancelled while awaiting approval`);
             }
@@ -893,12 +1159,14 @@ export const createPermissionPolicy = (options) => {
                         + ' — it did not run', undefined, undefined, origin);
             };
             if (answer === 'always') {
-                if (externalGate) {
+                if (externalGate || reviewing) {
                     // Before every branch that remembers something, because each of
                     // them would: `oneShot` told the transport not to offer this, and
                     // a prompt someone typed "always" into is not a transport that
                     // listened.
-                    return allowUnlessMoved(`${call.toolName} was approved once; this conversation has read external content, so nothing is remembered`, command);
+                    return allowUnlessMoved(reviewing
+                        ? `${call.toolName} was approved once; under the review posture nothing is remembered`
+                        : `${call.toolName} was approved once; this conversation has read external content, so nothing is remembered`, command);
                 }
                 if (scopedByOrigin) {
                     // The tool goes in with the site: a grant for one origin-scoped
@@ -1108,6 +1376,7 @@ export const createPermissionPolicy = (options) => {
             return allowUnlessMoved(`${call.toolName} was approved once`, command);
         },
     };
+    return policy;
 };
 export { assertDerivedStatePath, assertDerivedStatePathSync, linkedDerivedComponent, linkedDerivedComponentMessage, linkedDerivedComponentSync, isSymlinkedStatePath, isSymlinkedStatePathSync, symlinkedStateDirectoryMessage, symlinkedStateFileMessage, } from "./state-directory.js";
 //# sourceMappingURL=index.js.map