@hyperdrive.bot/paseo-server 0.3.40 → 0.3.42

package/dist/server/server/agent/agent-manager.d.ts

@@ -142,6 +142,14 @@ interface ManagedAgentBase {
     lastUsage?: AgentUsage;
     lastError?: string;
     attention: AttentionState;
+    /**
+     * How many times a "finished" attention event was suppressed on this agent
+     * because it still owned armed background work (see checkAndSetAttention).
+     * Diagnostic only — never persisted, never projected to clients. It exists so
+     * the deliberately-accepted gap (a prose question swallowed mid-monitor) can
+     * be MEASURED from real sessions instead of argued about.
+     */
+    suppressedAttentionCount?: number;
     foregroundTurnWaiters: Set<ForegroundTurnWaiter>;
     finalizedForegroundTurnIds: Set<string>;
     unsubscribeSession: (() => void) | null;
@@ -472,6 +480,13 @@ export declare class AgentManager {
     private recordTimeline;
     private emitState;
     private syncFeaturesFromSession;
+    /**
+     * Live background work owned by this agent: monitors, crons, and backgrounded
+     * shells the provider is still tracking. Mirrors what `agent-projections`
+     * publishes as `activeBackgroundTaskCount`, read through the same optional
+     * hook so providers that do not implement it simply report zero.
+     */
+    private getActiveBackgroundTaskCount;
     private checkAndSetAttention;
     private enqueueBackgroundPersist;
     private enqueueDurableTimelineAppend;

package/dist/server/server/agent/agent-manager.js

@@ -59,6 +59,20 @@ function buildStoredAgentConfig(record) {
     return stripInternalPaseoMcpServer(config);
 }
 export { AGENT_LIFECYCLE_STATUSES };
+/**
+ * Reject a create call that asks for a tool allowlist the chosen provider cannot
+ * enforce. Silently dropping it would hand the caller a guarantee that does not
+ * exist, so the failure is loud and names the provider.
+ */
+function requireToolAllowlistSupport(client, config) {
+    if (!config.allowedTools || config.allowedTools.length === 0)
+        return;
+    if (client.supportsToolAllowlist === true)
+        return;
+    throw new Error(`Provider '${config.provider}' cannot enforce a tool allowlist (allowedTools). ` +
+        "Only the claude provider (and providers derived from it) supports runtime tool " +
+        "enforcement. Re-run without --allowed-tools, or use a claude-based provider.");
+}
 function resolveInitialAttention(input) {
     if (input == null || !input.requiresAttention) {
         return { requiresAttention: false };
@@ -214,7 +228,10 @@ export class AgentManager {
         this.mcpAuthToken = options?.mcpAuthToken ?? null;
         this.configurePaseoTools(options);
         this.appendSystemPrompt = options.appendSystemPrompt ?? "";
-        this.logger = options.logger.child({ module: "agent", component: "agent-manager" });
+        this.logger = options.logger.child({
+            module: "agent",
+            component: "agent-manager",
+        });
         this.rescueTimeouts = {
             reloadSessionCloseMs: options.rescueTimeouts?.reloadSessionCloseMs ?? RELOAD_SESSION_CLOSE_TIMEOUT_MS,
             interruptSessionMs: options.rescueTimeouts?.interruptSessionMs ?? INTERRUPT_SESSION_TIMEOUT_MS,
@@ -453,7 +470,9 @@ export class AgentManager {
         }
     }
     async listDraftCommands(config) {
-        const normalizedConfig = await this.normalizeConfig(config, { resolveDefaultModel: false });
+        const normalizedConfig = await this.normalizeConfig(config, {
+            resolveDefaultModel: false,
+        });
         const client = this.requireClient(normalizedConfig.provider);
         if (!normalizedConfig.model) {
             return [];
@@ -482,7 +501,9 @@ export class AgentManager {
         }
     }
     async listDraftFeatures(config) {
-        const normalizedConfig = await this.normalizeConfig(config, { resolveDefaultModel: false });
+        const normalizedConfig = await this.normalizeConfig(config, {
+            resolveDefaultModel: false,
+        });
         const client = this.requireClient(normalizedConfig.provider);
         if (!normalizedConfig.model) {
             return [];
@@ -541,6 +562,7 @@ export class AgentManager {
         const client = await this.requireAvailableClient({
             provider: storedConfig.provider,
         });
+        requireToolAllowlistSupport(client, storedConfig);
         const launchContext = await this.buildLaunchContext(resolvedAgentId, client, options?.env);
         const providerLaunchConfig = this.resolveProviderLaunchConfig(launchConfig, launchContext);
         const createOptions = this.buildCreateSessionOptions(options);
@@ -585,7 +607,9 @@ export class AgentManager {
     async importProviderSession(input) {
         const resolvedAgentId = validateAgentId(this.idFactory(), "importProviderSession");
         this.requireEnabledProvider(input.provider);
-        const client = await this.requireAvailableClient({ provider: input.provider });
+        const client = await this.requireAvailableClient({
+            provider: input.provider,
+        });
         if (!client.importSession) {
             throw new Error(`Provider '${input.provider}' does not support importing sessions`);
         }
@@ -893,7 +917,10 @@ export class AgentManager {
     async markRecordArchived(record) {
         const registry = this.requireRegistry();
         const archivedAt = new Date().toISOString();
-        const archivedRecord = buildArchivedAgentRecord(record, { archivedAt, updatedAt: archivedAt });
+        const archivedRecord = buildArchivedAgentRecord(record, {
+            archivedAt,
+            updatedAt: archivedAt,
+        });
         await registry.upsert(archivedRecord);
         await this.archiveNativeSessionBestEffort(record.provider, record.persistence);
         if (this.agents.has(record.id)) {
@@ -1009,7 +1036,10 @@ export class AgentManager {
             throw new Error("Agent session does not support setting features");
         }
         await agent.session.setFeature(featureId, value);
-        agent.config.featureValues = { ...agent.config.featureValues, [featureId]: value };
+        agent.config.featureValues = {
+            ...agent.config.featureValues,
+            [featureId]: value,
+        };
         this.touchUpdatedAt(agent);
         this.emitState(agent);
     }
@@ -1057,7 +1087,9 @@ export class AgentManager {
         const priorColumn = touchesColumn && this.registry
             ? ((await this.registry.get(agentId))?.labels?.[KANBAN_LABEL_KEY] ?? null)
             : null;
-        const nextRecord = await this.writeStoredMetadata(agentId, { labels: patch });
+        const nextRecord = await this.writeStoredMetadata(agentId, {
+            labels: patch,
+        });
         if (touchesColumn) {
             this.cardMoveLog?.record(agentId, priorColumn, nextRecord.labels?.[KANBAN_LABEL_KEY] ?? null);
         }
@@ -1092,7 +1124,9 @@ export class AgentManager {
                 }
                 return { record, live: true, previousParentAgentId: null };
             }
-            const { record } = await this.writeLabels(agentId, { [PARENT_AGENT_ID_LABEL]: null });
+            const { record } = await this.writeLabels(agentId, {
+                [PARENT_AGENT_ID_LABEL]: null,
+            });
             if (!record) {
                 throw new Error(`Agent not found in storage after detach: ${agentId}`);
             }
@@ -1106,7 +1140,9 @@ export class AgentManager {
         if (!previousParentAgentId) {
             return { record, live: false, previousParentAgentId: null };
         }
-        const result = await this.writeLabels(agentId, { [PARENT_AGENT_ID_LABEL]: null });
+        const result = await this.writeLabels(agentId, {
+            [PARENT_AGENT_ID_LABEL]: null,
+        });
         if (!result.record) {
             throw new Error(`Agent not found in storage after detach: ${agentId}`);
         }
@@ -1277,7 +1313,9 @@ export class AgentManager {
                 });
                 return;
             }
-            this.dispatchStream(agent.id, event, { timestamp: new Date().toISOString() });
+            this.dispatchStream(agent.id, event, {
+                timestamp: new Date().toISOString(),
+            });
         };
         void (async () => {
             try {
@@ -1417,7 +1455,10 @@ export class AgentManager {
         mutableAgent.lifecycle = nextLifecycle;
         const persistenceHandle = mutableAgent.session.describePersistence() ??
             (mutableAgent.runtimeInfo?.sessionId
-                ? { provider: mutableAgent.provider, sessionId: mutableAgent.runtimeInfo.sessionId }
+                ? {
+                    provider: mutableAgent.provider,
+                    sessionId: mutableAgent.runtimeInfo.sessionId,
+                }
                 : null);
         if (persistenceHandle) {
             mutableAgent.persistence = attachPersistenceCwd(persistenceHandle, mutableAgent.cwd);
@@ -1574,7 +1615,9 @@ export class AgentManager {
             const bufferedResolution = agent.bufferedPermissionResolutions.get(requestId);
             if (bufferedResolution) {
                 agent.bufferedPermissionResolutions.delete(requestId);
-                this.dispatchStream(agent.id, bufferedResolution, { timestamp: new Date().toISOString() });
+                this.dispatchStream(agent.id, bufferedResolution, {
+                    timestamp: new Date().toISOString(),
+                });
             }
             return result;
         }
@@ -1611,7 +1654,11 @@ export class AgentManager {
                 continue;
             }
             for (const task of agent.session.listBackgroundTasks()) {
-                rows.push({ agentId: agent.id, agentTitle: agent.config.title ?? null, task });
+                rows.push({
+                    agentId: agent.id,
+                    agentTitle: agent.config.title ?? null,
+                    task,
+                });
             }
         }
         return rows;
@@ -1752,7 +1799,10 @@ export class AgentManager {
             this.logger.info({ agentId, provider: agent.provider, messageId, mode }, "agent.rewind.start");
             await invokeRewindCapability(agent.session, { messageId, mode });
             if (mode !== "files") {
-                await this.hydrateTimelineFromProvider(agentId, { force: true, broadcast: true });
+                await this.hydrateTimelineFromProvider(agentId, {
+                    force: true,
+                    broadcast: true,
+                });
             }
             await this.refreshRuntimeInfo(agent);
             await this.persistSnapshot(agent);
@@ -1998,14 +2048,18 @@ export class AgentManager {
         this.agents.set(resolvedAgentId, managed);
         // Initialize previousStatus to track transitions
         this.previousStatuses.set(resolvedAgentId, managed.lifecycle);
-        await this.refreshRuntimeInfo(managed, { emit: !options?.publishWhenReady });
+        await this.refreshRuntimeInfo(managed, {
+            emit: !options?.publishWhenReady,
+        });
         await this.persistSnapshot(managed, {
             title: initialPersistedTitle,
         });
         if (!options?.publishWhenReady) {
             this.emitState(managed, { persist: false });
         }
-        await this.refreshSessionState(managed, { emit: !options?.publishWhenReady });
+        await this.refreshSessionState(managed, {
+            emit: !options?.publishWhenReady,
+        });
         managed.lifecycle = "idle";
         await this.persistSnapshot(managed);
         this.emitState(managed, { persist: false });
@@ -2265,7 +2319,9 @@ export class AgentManager {
             this.agentStreamCoalescer.flushAndDiscard(agent.id);
             await this.deleteCommittedTimeline(agent.id);
             this.timelineStore.delete(agent.id);
-            this.timelineStore.initialize(agent.id, { timestamp: new Date().toISOString() });
+            this.timelineStore.initialize(agent.id, {
+                timestamp: new Date().toISOString(),
+            });
             agent.historyPrimed = true;
             for (const event of historyEvents) {
                 const row = this.recordTimeline(agent.id, event.item, event.timestamp ? { timestamp: event.timestamp } : undefined);
@@ -2333,7 +2389,10 @@ export class AgentManager {
             }
             this.agentStreamCoalescer.flushFor(agent.id);
         }
-        const flags = { shouldDispatchEvent: true, shouldNotifyWaiters: true };
+        const flags = {
+            shouldDispatchEvent: true,
+            shouldNotifyWaiters: true,
+        };
         const dispatchPromise = this.dispatchStreamEventByType({
             agent,
             event,
@@ -2349,7 +2408,9 @@ export class AgentManager {
             this.finalizeForegroundTurn(agent, eventTurnId);
         }
         if (!options?.fromHistory && flags.shouldDispatchEvent) {
-            this.dispatchStream(agent.id, event, { timestamp: new Date().toISOString() });
+            this.dispatchStream(agent.id, event, {
+                timestamp: new Date().toISOString(),
+            });
         }
         this.traceHandleStreamEventEnd(agent, event, eventTurnId, flags);
         return flags.shouldNotifyWaiters;
@@ -2402,7 +2463,10 @@ export class AgentManager {
                 agent.currentModeId = event.currentModeId;
                 agent.availableModes = event.availableModes;
                 if (agent.runtimeInfo) {
-                    agent.runtimeInfo = { ...agent.runtimeInfo, modeId: event.currentModeId };
+                    agent.runtimeInfo = {
+                        ...agent.runtimeInfo,
+                        modeId: event.currentModeId,
+                    };
                 }
                 flags.shouldDispatchEvent = false;
                 this.emitState(agent);
@@ -2410,7 +2474,10 @@ export class AgentManager {
             case "model_changed":
                 agent.runtimeInfo = event.runtimeInfo;
                 if (!agent.persistence && event.runtimeInfo.sessionId) {
-                    agent.persistence = attachPersistenceCwd({ provider: agent.provider, sessionId: event.runtimeInfo.sessionId }, agent.cwd);
+                    agent.persistence = attachPersistenceCwd({
+                        provider: agent.provider,
+                        sessionId: event.runtimeInfo.sessionId,
+                    }, agent.cwd);
                 }
                 agent.currentModeId = event.runtimeInfo.modeId ?? agent.currentModeId;
                 flags.shouldDispatchEvent = false;
@@ -2427,9 +2494,20 @@ export class AgentManager {
                 this.emitState(agent);
                 return undefined;
             case "timeline":
-                return this.onStreamTimelineEvent({ agent, event, options, isForegroundEvent, flags });
+                return this.onStreamTimelineEvent({
+                    agent,
+                    event,
+                    options,
+                    isForegroundEvent,
+                    flags,
+                });
             case "turn_completed":
-                this.onStreamTurnCompleted({ agent, event, eventTurnId, isForegroundEvent });
+                this.onStreamTurnCompleted({
+                    agent,
+                    event,
+                    eventTurnId,
+                    isForegroundEvent,
+                });
                 return undefined;
             case "turn_failed":
                 return this.onStreamTurnFailed({
@@ -2440,7 +2518,13 @@ export class AgentManager {
                     options,
                 });
             case "turn_canceled":
-                this.onStreamTurnCanceled({ agent, event, eventTurnId, isForegroundEvent, options });
+                this.onStreamTurnCanceled({
+                    agent,
+                    event,
+                    eventTurnId,
+                    isForegroundEvent,
+                    options,
+                });
                 return undefined;
             case "turn_started":
                 this.onStreamTurnStarted({ agent, eventTurnId, isForegroundEvent });
@@ -2689,6 +2773,18 @@ export class AgentManager {
             agent.features = agent.session.features;
         }
     }
+    /**
+     * Live background work owned by this agent: monitors, crons, and backgrounded
+     * shells the provider is still tracking. Mirrors what `agent-projections`
+     * publishes as `activeBackgroundTaskCount`, read through the same optional
+     * hook so providers that do not implement it simply report zero.
+     */
+    getActiveBackgroundTaskCount(agent) {
+        if (!("session" in agent)) {
+            return 0;
+        }
+        return agent.session?.getActiveBackgroundTaskCount?.() ?? 0;
+    }
     checkAndSetAttention(agent) {
         const previousStatus = this.previousStatuses.get(agent.id);
         const currentStatus = agent.lifecycle;
@@ -2704,6 +2800,40 @@ export class AgentManager {
         }
         // Check if agent transitioned from running to idle (finished)
         if (previousStatus === "running" && currentStatus === "idle") {
+            // ...but "the lifecycle went running -> idle" is NOT the same fact as
+            // "this agent is finished and wants you".
+            //
+            // A monitor tick, a cron firing, or a background shell reporting progress
+            // all WAKE the session: status goes idle -> running, the agent prints a
+            // progress line ("1/12 done, I'll let you know"), the turn ends, and the
+            // lifecycle settles back to idle. Under the old rule that transition set
+            // requiresAttention="finished" on EVERY tick, which lit the Unread chip,
+            // the dock badge and a push notification for output nobody needs to act
+            // on. With several sessions in parallel that made Unread — the one chip
+            // you actually watch — useless.
+            //
+            // So: if the agent still owns armed background work, the turn ending is a
+            // progress beat, not a handoff. Stay quiet and let the bucket derivation
+            // surface it as "pending" (alive, will come back on its own) instead.
+            //
+            // KNOWN GAP, deliberately named rather than silently accepted: a turn that
+            // ends with the agent asking a real question in PROSE (not a permission
+            // request, which still routes through needs_input and is unaffected) is
+            // also suppressed while background work is armed. Prose questions are not
+            // machine-detectable here. The counter below exists so that gap is
+            // MEASURED rather than assumed — feed it to the Jarvis judge in shadow
+            // mode (PASEO_JARVIS_SHADOW=1) to size the real distribution before
+            // deciding whether it needs rescuing.
+            const activeBackgroundTaskCount = this.getActiveBackgroundTaskCount(agent);
+            if (activeBackgroundTaskCount > 0) {
+                agent.suppressedAttentionCount = (agent.suppressedAttentionCount ?? 0) + 1;
+                this.logger.debug({
+                    agentId: agent.id,
+                    activeBackgroundTaskCount,
+                    suppressedAttentionCount: agent.suppressedAttentionCount,
+                }, "Suppressed finished-attention: agent still owns armed background work");
+                return;
+            }
             agent.attention = {
                 requiresAttention: true,
                 attentionReason: "finished",
@@ -2923,7 +3053,9 @@ export class AgentManager {
         if (this.paseoToolsEnabled &&
             client.capabilities.supportsNativePaseoTools &&
             this.paseoToolCatalogFactory) {
-            context.paseoTools = await this.paseoToolCatalogFactory({ callerAgentId: agentId });
+            context.paseoTools = await this.paseoToolCatalogFactory({
+                callerAgentId: agentId,
+            });
         }
         return context;
     }

package/dist/server/server/agent/agent-projections.js

@@ -263,6 +263,9 @@ function buildSerializableConfig(config) {
     if (config.mcpServers) {
         serializable.mcpServers = config.mcpServers;
     }
+    if (config.allowedTools?.length) {
+        serializable.allowedTools = [...config.allowedTools];
+    }
     return Object.keys(serializable).length ? serializable : null;
 }
 function sanitizePendingPermissions(pending) {

package/dist/server/server/agent/agent-sdk-types.d.ts

@@ -521,6 +521,17 @@ export interface AgentSessionConfig {
         claude?: Partial<ClaudeAgentOptions>;
     };
     mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-run tool allowlist in Claude Code permission-rule syntax, e.g.
+     * ["Read", "Bash(git:*)", "mcp__playwright__browser_navigate"].
+     *
+     * When present, a tool absent from the list is blocked BEFORE it executes and
+     * the model is told why. Undefined or empty means no allowlist. Enforced only
+     * by clients that set `AgentClient.supportsToolAllowlist`; a create call that
+     * asks any other provider for an allowlist is rejected rather than run
+     * unenforced.
+     */
+    allowedTools?: string[];
     /**
      * Internal agents are hidden from listings and don't trigger notifications.
      * They are used for ephemeral system tasks like commit/PR generation.
@@ -673,6 +684,18 @@ export interface ProviderCatalog {
 export interface AgentClient {
     readonly provider: AgentProvider;
     readonly capabilities: AgentCapabilityFlags;
+    /**
+     * True when this client can ENFORCE `AgentSessionConfig.allowedTools` at
+     * runtime (block a tool outside the list before it executes), not merely
+     * accept the field.
+     *
+     * Absent/false means the create call is rejected when an allowlist is set. A
+     * tool allowlist that is quietly dropped is worse than no allowlist: the
+     * caller believes a restriction is in force that is not, so this fails loudly
+     * instead. Derived providers (`pool` extends `claude`, and so on) reuse the
+     * base client class and therefore inherit the correct answer.
+     */
+    readonly supportsToolAllowlist?: boolean;
     createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext, options?: AgentCreateSessionOptions): Promise<AgentSession>;
     resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
     /**

package/dist/server/server/agent/agent-storage.d.ts

@@ -62,6 +62,7 @@ declare const STORED_AGENT_SCHEMA: z.ZodObject<{
         extra: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
         systemPrompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         mcpServers: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+        allowedTools: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>>;
     runtimeInfo: z.ZodOptional<z.ZodObject<{
         provider: z.ZodString;
@@ -112,7 +113,7 @@ declare const STORED_AGENT_SCHEMA: z.ZodObject<{
     internal: z.ZodOptional<z.ZodBoolean>;
     archivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
-export type SerializableAgentConfig = Pick<AgentSessionConfig, "modeId" | "model" | "thinkingOptionId" | "featureValues" | "extra" | "systemPrompt" | "mcpServers">;
+export type SerializableAgentConfig = Pick<AgentSessionConfig, "modeId" | "model" | "thinkingOptionId" | "featureValues" | "extra" | "systemPrompt" | "mcpServers" | "allowedTools">;
 export type StoredAgentRecord = z.infer<typeof STORED_AGENT_SCHEMA>;
 export declare function parseStoredAgentRecord(value: unknown): StoredAgentRecord;
 export declare class AgentStorage {

package/dist/server/server/agent/agent-storage.js

@@ -13,6 +13,10 @@ const SERIALIZABLE_CONFIG_SCHEMA = z
     extra: z.record(z.string(), z.any()).nullable().optional(),
     systemPrompt: z.string().nullable().optional(),
     mcpServers: z.record(z.string(), z.any()).nullable().optional(),
+    // Persisted so a daemon restart or session resume rebuilds the SAME
+    // restriction. An allowlist that silently evaporates on resume is worse than
+    // none: the operator still believes the run is fenced.
+    allowedTools: z.array(z.string()).nullable().optional(),
 })
     .nullable()
     .optional();

package/dist/server/server/agent/mcp-shared.js

@@ -168,7 +168,7 @@ export function parseDurationString(input) {
     }
     let totalMs = 0;
     let hasMatch = false;
-    const regex = /(\d+)([smh])/g;
+    const regex = /(\d+)([smhd])/g;
     let match;
     while ((match = regex.exec(trimmed)) !== null) {
         hasMatch = true;
@@ -183,10 +183,13 @@ export function parseDurationString(input) {
             case "h":
                 totalMs += value * 60 * 60 * 1000;
                 break;
+            case "d":
+                totalMs += value * 24 * 60 * 60 * 1000;
+                break;
         }
     }
     if (!hasMatch) {
-        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m`);
+        throw new Error(`Invalid duration format: ${input}. Use formats like: 5m, 30s, 1h, 2h30m, 1d`);
     }
     return totalMs;
 }

package/dist/server/server/agent/providers/claude/agent.d.ts

@@ -50,6 +50,7 @@ export declare function readEventIdentifiers(message: SDKMessage): EventIdentifi
 export declare class ClaudeAgentClient implements AgentClient {
     readonly provider: "claude";
     readonly capabilities: AgentCapabilityFlags;
+    readonly supportsToolAllowlist = true;
     private readonly defaults?;
     private readonly logger;
     private readonly runtimeSettings?;
@@ -133,6 +134,13 @@ export declare class ClaudeAgentSession implements AgentSession {
     private readonly emittedUserMessageIds;
     private readonly rewindTurnAnchors;
     private pendingFreshSessionId;
+    /**
+     * Parsed per-run tool allowlist. Empty array = no allowlist configured, which
+     * is the historical behaviour (everything the permission mode permits runs).
+     */
+    private readonly toolAllowRules;
+    /** PTY-transport guard files for the current session; removed on teardown. */
+    private toolAllowGuard;
     private cumulativeImageBase64Bytes;
     private cumulativeImageWarnEmitted;
     private recentStderr;
@@ -240,6 +248,32 @@ export declare class ClaudeAgentSession implements AgentSession {
     private buildAppendedSystemPrompt;
     private buildSdkEnv;
     private buildOptions;
+    /**
+     * Install the per-run tool allowlist as a `PreToolUse` hook on the SDK options.
+     *
+     * Deliberately NOT `options.allowedTools`: that field is a permission ALLOW rule
+     * (pre-approve, do not prompt), and this session also sets
+     * allowDangerouslySkipPermissions, under which permission rules are moot. A
+     * PreToolUse hook is the only gate that still fires; the SDK says so outright
+     * ("PreToolUse hook denies bypass canUseTool"). Applied last so an
+     * `extra.claude.hooks` override cannot displace it.
+     */
+    private applyToolAllowlistHook;
+    /**
+     * PTY-transport half of allowlist enforcement: (re)generate the hook script and
+     * the `--settings` file that registers it.
+     *
+     * Returns a spreadable fragment (`{}` when no allowlist is configured) so the
+     * caller stays branch-free. Regenerated per spawn because a session can restart
+     * (mode swap, model swap, rewind) and the artifacts are keyed to the session id.
+     */
+    private refreshToolAllowGuard;
+    /**
+     * SDK-transport half of allowlist enforcement. The PTY transport enforces the
+     * same rules through a generated hook script (see tool-allowlist-guard.ts);
+     * both call `isToolAllowed`, so the two transports cannot diverge.
+     */
+    private enforceToolAllowlistHook;
     private buildSettingsOptions;
     private resolveFastModeSetting;
     private normalizeMcpServers;