@nathapp/nax-agent 0.91.6 → 0.91.7-canary.10

package/dist/session/native-backend-options.d.ts

@@ -1,18 +1,50 @@
+/**
+ * nativeBackend's options (S4 spec 5.2): the native half of the facade's
+ * createAgentSession options, validated here rather than by the facade. zod
+ * checks the shape; the caller's own object is kept as `raw` (zod returns
+ * copies, which would break identity for handlers the caller owns).
+ */
+import { z } from "zod";
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import { SandboxConfigSchema } from "#src/config/schemas-sandbox";
 import type { NativeCatalogOverrides } from "#src/native/client";
 import type { CredentialSource } from "#src/native/credentials/session-source";
 import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
+import type { ToolProvider } from "#src/tools/provider-types";
 import type { AgentSessionHostPorts, AgentSessionProfile } from "./agent-session-types.ts";
 export interface NativeBackendOptions {
     readonly model: string;
+    /** Static or discovered tool providers attached to this session's profile and stage. */
+    readonly toolProviders?: readonly ToolProvider[];
     /** Repository instruction basename; defaults to AGENTS.md. */
     readonly instructionFileName?: string;
     readonly credentials?: CredentialSource;
     readonly catalogOverrides?: NativeCatalogOverrides;
     readonly loopHandlers?: LoopHandlerSet;
+    /** Copied into every turn's loop-handler context as `role` (for example "tui"). */
+    readonly loopHandlerRole?: string;
     readonly hostPorts?: AgentSessionHostPorts;
     readonly bashApproval?: BashApprovalMode;
+    /** Ask before a per-call sandbox escape, including under raw; requires allowUnsandboxedCommands. */
+    readonly askOnUnsandboxed?: boolean;
+    /** Gate Bash when the sandbox is disabled or unavailable at session open. */
+    readonly askWhenSandboxDown?: boolean;
+    /** Keep provider-designated mutating tool asks outside the ask profile too. */
+    readonly askDiscoveredTools?: boolean;
+    /** Rule overlays appended to the profile's own permission rules. */
+    readonly askRules?: readonly string[];
+    readonly denyRules?: readonly string[];
+    /** Partial sandbox input, validated here and default-filled at posture resolution. */
+    readonly sandbox?: z.input<typeof SandboxConfigSchema>;
     readonly allowUnsandboxed?: boolean;
+    /** Narrow the declared tools to these names (built-in names, `<provider>__<tool>`, or `<provider>__*`); scratchpad tools are always kept. */
+    readonly allowedTools?: readonly string[];
+    /**
+     * US-001: offer the Bash/Exec tools' `unsandboxed` argument, so a model can ask
+     * for one command to run outside the OS sandbox. Refused by the tool-less
+     * profiles, which have no shell to unwrap.
+     */
+    readonly allowUnsandboxedCommands?: boolean;
     /** Keep a resumed or continued conversation when the model differs (ACP server model switch, S5-3). */
     readonly carryHistoryAcrossModels?: boolean;
     /**
@@ -34,7 +66,10 @@ export interface ResolvedNativeOptions {
     readonly provider: string;
 }
 export declare function parseNativeBackendOptions(input: unknown): ResolvedNativeOptions;
-export declare function nativeProfileRules(profile: AgentSessionProfile, raw: NativeBackendOptions): {
+/** The profile's resolved knobs: the validator's answer, consumed as data. */
+export interface ResolvedProfileRules {
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
-};
+    readonly allowUnsandboxedCommands: boolean;
+}
+export declare function nativeProfileRules(profile: AgentSessionProfile, raw: NativeBackendOptions): ResolvedProfileRules;

package/dist/session/native-backend-options.js

@@ -5,6 +5,7 @@
  * copies, which would break identity for handlers the caller owns).
  */
 import { z } from "zod";
+import { SandboxConfigSchema } from "#src/config/schemas-sandbox";
 import { parseNativeModel } from "#src/native/models";
 import { compactionSettingsSchema } from "#src/native/session/compaction-settings";
 import { isInstructionFileName } from "#src/native/session/instruction-file-name";
@@ -18,6 +19,14 @@ function hasMethods(names) {
 const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const OptionsSchema = z.strictObject({
     model: z.string().min(1),
+    toolProviders: z
+        .custom((value) => Array.isArray(value) &&
+        value.every((provider) => isRecord(provider) &&
+            typeof provider.id === "string" &&
+            (provider.kind === "static" || provider.kind === "discovered") &&
+            isStringArray(provider.stages) &&
+            typeof provider.tools === "function"), "must be an array of tool providers with id, kind, stages and tools()")
+        .optional(),
     instructionFileName: z
         .string()
         .refine(isInstructionFileName, "must be a nonhidden Markdown basename without path separators, colon or control characters")
@@ -27,16 +36,31 @@ const OptionsSchema = z.strictObject({
         .optional(),
     catalogOverrides: z.array(z.custom(isRecord, "must be a catalog override object")).optional(),
     loopHandlers: z.array(z.custom(isRecord, "must be a loop handler entry")).optional(),
+    loopHandlerRole: z.string().min(1).optional(),
     hostPorts: z
         .strictObject({
         protectedPaths: z
             .custom((value) => isRecord(value) && isStringArray(value.gitExcludePathspecs) && isStringArray(value.gitIgnorePatterns), "must be a protected-paths policy with gitExcludePathspecs and gitIgnorePatterns string arrays")
             .optional(),
+        commandShadow: z
+            .custom(hasMethods(["observe", "settle", "drain"]), "must implement observe, settle and drain")
+            .optional(),
+        backgroundCommands: z
+            .custom(hasMethods(["adopt", "foreground"]), "must implement adopt and foreground")
+            .optional(),
         commandInterceptor: z.custom(hasMethods(["intercept"]), "must implement intercept").optional(),
     })
         .optional(),
     bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
+    askOnUnsandboxed: z.boolean().optional(),
+    askWhenSandboxDown: z.boolean().optional(),
+    askDiscoveredTools: z.boolean().optional(),
+    askRules: z.array(z.string().min(1)).optional(),
+    denyRules: z.array(z.string().min(1)).optional(),
+    sandbox: SandboxConfigSchema.optional(),
     allowUnsandboxed: z.boolean().optional(),
+    allowedTools: z.array(z.string().min(1)).optional(),
+    allowUnsandboxedCommands: z.boolean().optional(),
     carryHistoryAcrossModels: z.boolean().optional(),
     compaction: compactionSettingsSchema.optional(),
 });
@@ -78,14 +102,26 @@ export function nativeProfileRules(profile, raw) {
             path: "backend.allowUnsandboxed",
         });
     }
+    if (!tools && raw.allowUnsandboxedCommands !== undefined) {
+        throw invalid('allowUnsandboxedCommands applies to profiles "ask", "full" and "review" only', {
+            path: "backend.allowUnsandboxedCommands",
+        });
+    }
     const bashApproval = raw.bashApproval ?? "gated";
     if (profile === "ask" && bashApproval !== "gated") {
         throw invalid('profile "ask" requires bashApproval "gated" (other modes run Bash without asking)', {
             path: "backend.bashApproval",
         });
     }
-    if (raw.allowUnsandboxed === true && bashApproval !== "gated") {
-        throw invalid('allowUnsandboxed requires bashApproval "gated"', { path: "backend.allowUnsandboxed" });
+    // Raw never asks, so an unsandboxed fallback under it is the person's own standing
+    // decision; escalate has no one to fall back to. Gated and raw are the two that may.
+    const fallbackAllowed = bashApproval === "gated" || bashApproval === "raw";
+    if (raw.allowUnsandboxed === true && !fallbackAllowed) {
+        throw invalid('allowUnsandboxed requires bashApproval "gated" or "raw"', { path: "backend.allowUnsandboxed" });
     }
-    return { bashApproval, allowUnsandboxed: raw.allowUnsandboxed === true };
+    return {
+        bashApproval,
+        allowUnsandboxed: raw.allowUnsandboxed === true,
+        allowUnsandboxedCommands: raw.allowUnsandboxedCommands === true,
+    };
 }

package/dist/session/native-backend.js

@@ -4,16 +4,21 @@
  * with built-in and embedder tools, the NativeSessionAdapter, loop handlers
  * and the resume model check.
  */
+import { backgroundToolOptions } from "#src/coding-tools/coding-tool-extras";
+import { getLogger } from "#src/infra/agent-logger";
+import { errorMessage } from "#src/infra/errors";
 import { DEFAULT_SPIN_BREAKER_SETTINGS } from "#src/infra/spin-breaker/index";
 import { NATIVE_AGENT } from "#src/native/models";
 import { resolveCompaction } from "#src/native/session/compaction-settings";
 import { transcriptModelIdentity } from "#src/native/session/transcript-identity";
 import { NativeSessionAdapter } from "#src/native/session-adapter";
+import { resolveProviderTools } from "#src/tools/provider-advertise";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { nativeProfileRules, parseNativeBackendOptions, } from "./native-backend-options.js";
+import { effectiveBashApproval, nativePostureRules } from "./native-posture-rules.js";
 import { createSessionAskLink, createSessionAskResolver } from "./session-ask-link.js";
 import { createSessionInteractionHandler, embedderToolDescriptor } from "./session-interaction.js";
-import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } from "./session-tool-support.js";
+import { buildSessionToolSupport, defaultProtectedPaths, providerAdmits, resolveSessionLauncher, SESSION_STAGE, } from "./session-tool-support.js";
 export const NATIVE_BACKEND_KIND = "native";
 /** nax's agent.native.transportRetry default (S3 spec 5.3). */
 const SESSION_TRANSPORT_RETRY = {
@@ -38,32 +43,58 @@ async function openNative(resolved, ctx) {
     const raw = resolved.raw;
     if (ctx.resume !== undefined && raw.carryHistoryAcrossModels !== true)
         checkResumeModel(ctx.resume.doc, ctx.sessionId, raw.model);
-    const { bashApproval, allowUnsandboxed } = nativeProfileRules(ctx.profile, raw);
+    const { bashApproval: profileMode, allowUnsandboxed, allowUnsandboxedCommands, } = nativeProfileRules(ctx.profile, raw);
+    const posture = nativePostureRules(ctx.profile, raw);
     const protectedPaths = {
         ...defaultProtectedPaths(raw.credentials !== undefined),
         ...raw.hostPorts?.protectedPaths,
     };
-    const launcher = await resolveSessionLauncher({
+    const { launcher, sandbox } = await resolveSessionLauncher({
         profile: ctx.profile,
         root: ctx.workdir,
         protectedPaths,
-        bashApproval,
+        bashApproval: profileMode,
         allowUnsandboxed,
+        config: posture.sandbox,
     });
+    const bashApproval = effectiveBashApproval(profileMode, posture.askWhenSandboxDown, sandbox.kind);
+    const providerTools = ctx.profile === "none" || raw.toolProviders === undefined
+        ? undefined
+        : await resolveProviderTools(raw.toolProviders, SESSION_STAGE, ctx.workdir, raw.allowedTools !== undefined ? { admits: providerAdmits(raw.allowedTools) } : undefined);
+    for (const failure of providerTools?.failures ?? []) {
+        getLogger().warn("session", "Tool provider skipped", { sessionId: ctx.sessionId, ...failure });
+    }
+    for (const tool of ctx.tools) {
+        if (providerTools?.providerIdByTool.has(tool.name)) {
+            throw new AgentSessionError(`Embedder tool "${tool.name}" conflicts with a provider tool`, "AGENT_SESSION_TOOL_NAME_RESERVED", { tool: tool.name });
+        }
+    }
     let callId;
     const { support, grants } = buildSessionToolSupport({
         profile: ctx.profile,
         root: ctx.workdir,
         sessionName: ctx.sessionId,
+        ...(providerTools !== undefined ? { providerTools } : {}),
+        ...(raw.allowedTools !== undefined ? { allowedTools: raw.allowedTools } : {}),
         protectedPaths,
         bashApproval,
         launcher,
         askResolver: createSessionAskResolver(createSessionAskLink({ port: ctx.asks, currentCallId: () => callId })),
         interceptor: raw.hostPorts?.commandInterceptor,
+        askRules: posture.askRules,
+        denyRules: posture.denyRules,
+        askOnUnsandboxed: posture.askOnUnsandboxed,
+        askDiscoveredTools: posture.askDiscoveredTools,
+        commandShadow: raw.hostPorts?.commandShadow,
+        ...backgroundToolOptions(raw.hostPorts),
+        // US-003: the profile's validated opt-in, so an interactive "full" session
+        // can offer Bash's per-call escape without turning the sandbox off.
+        ...(allowUnsandboxedCommands ? { unsandboxedCommands: true } : {}),
     });
     const interactionHandler = createSessionInteractionHandler({
         sessionId: ctx.sessionId,
         runtime: support.runtime,
+        unavailableTools: new Set((support.declaredTools ?? []).filter((name) => !support.tools.some((tool) => tool.name === name))),
         embedderTools: new Map(ctx.tools.map((tool) => [tool.name, tool])),
         asks: ctx.asks,
         turnSignal: ctx.turnSignal,
@@ -77,6 +108,7 @@ async function openNative(resolved, ctx) {
         workdir: ctx.workdir,
         instructionProtectedPaths: protectedPaths,
         instructionFileName: raw.instructionFileName,
+        ...(support.providerInstructions !== undefined ? { providerInstructions: support.providerInstructions } : {}),
         resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval },
         modelDef: { provider: resolved.provider, model: raw.model },
         timeoutSeconds: ctx.turnTimeoutSeconds,
@@ -95,11 +127,29 @@ async function openNative(resolved, ctx) {
         workdir: ctx.workdir,
         model: raw.model,
         provider: resolved.provider,
+        ...(raw.loopHandlerRole !== undefined ? { role: raw.loopHandlerRole } : {}),
     };
     return {
         adapter,
         handle,
-        info: { kind: NATIVE_BACKEND_KIND, capabilities: {} },
+        runCommand: async ({ command, callId, signal }) => {
+            try {
+                const response = await interactionHandler.onInteraction({
+                    kind: "coding-tool",
+                    name: "Bash",
+                    input: { command },
+                    toolCallId: callId,
+                    signal,
+                });
+                if (response === null)
+                    return { content: "Bash is not available in this session", isError: true };
+                return { content: response.answer, isError: response.denied !== undefined };
+            }
+            catch (error) {
+                return { content: errorMessage(error), isError: true };
+            }
+        },
+        info: { kind: NATIVE_BACKEND_KIND, capabilities: {}, sandbox },
         turnOpts: () => ({
             interactionHandler,
             codingTools,

package/dist/session/native-posture-rules.d.ts

@@ -0,0 +1,18 @@
+/** Optional native-session overlays, separate from the existing profile defaults. */
+import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type SandboxConfig } from "#src/config/schemas-sandbox";
+import type { SandboxState } from "#src/sandbox/index";
+import type { ToolGrant } from "#src/tools/types";
+import type { AgentSessionProfile } from "./agent-session-types.ts";
+import type { NativeBackendOptions } from "./native-backend-options.ts";
+export interface ResolvedPostureRules {
+    readonly askRules: readonly ToolGrant[];
+    readonly denyRules: readonly ToolGrant[];
+    readonly sandbox: SandboxConfig;
+    readonly askOnUnsandboxed: boolean;
+    readonly askWhenSandboxDown: boolean;
+    readonly askDiscoveredTools: boolean;
+}
+export declare function nativePostureRules(profile: AgentSessionProfile, raw: NativeBackendOptions): ResolvedPostureRules;
+/** Snapshot the sandbox posture at open; a running session never silently changes modes. */
+export declare function effectiveBashApproval(profileMode: BashApprovalMode, askWhenSandboxDown: boolean, sandboxKind: SandboxState["kind"]): BashApprovalMode;

package/dist/session/native-posture-rules.js

@@ -0,0 +1,33 @@
+import { DEFAULT_SANDBOX_CONFIG, SandboxConfigSchema } from "#src/config/schemas-sandbox";
+import { parseRuleList } from "#src/permissions/grammar";
+import { AgentSessionError } from "./agent-session-errors.js";
+export function nativePostureRules(profile, raw) {
+    const toolOnlyOptions = [
+        "askRules",
+        "denyRules",
+        "askOnUnsandboxed",
+        "askWhenSandboxDown",
+        "askDiscoveredTools",
+    ];
+    for (const name of toolOnlyOptions) {
+        if ((profile === "none" || profile === "read") && raw[name] !== undefined) {
+            const path = `backend.${name}`;
+            throw new AgentSessionError(`Invalid agent session options: ${path} applies to profiles "ask", "full" and "review" only`, "AGENT_SESSION_INVALID_OPTIONS", { path });
+        }
+    }
+    if (raw.askOnUnsandboxed === true && raw.allowUnsandboxedCommands !== true) {
+        throw new AgentSessionError("Invalid agent session options: backend.askOnUnsandboxed requires backend.allowUnsandboxedCommands: true", "AGENT_SESSION_INVALID_OPTIONS", { path: "backend.askOnUnsandboxed" });
+    }
+    return {
+        askOnUnsandboxed: raw.askOnUnsandboxed === true,
+        askWhenSandboxDown: raw.askWhenSandboxDown === true,
+        askDiscoveredTools: raw.askDiscoveredTools === true,
+        askRules: parseRuleList(raw.askRules ?? []),
+        denyRules: parseRuleList(raw.denyRules ?? []),
+        sandbox: raw.sandbox === undefined ? DEFAULT_SANDBOX_CONFIG : SandboxConfigSchema.parse(raw.sandbox),
+    };
+}
+/** Snapshot the sandbox posture at open; a running session never silently changes modes. */
+export function effectiveBashApproval(profileMode, askWhenSandboxDown, sandboxKind) {
+    return askWhenSandboxDown && sandboxKind !== "available" ? "gated" : profileMode;
+}

package/dist/session/session-ask-link.d.ts

@@ -19,6 +19,12 @@ export interface ApprovalAsk {
     readonly command?: string;
     readonly reason: string;
     readonly callId?: string;
+    /**
+     * US-004: the call wants to run OUTSIDE the OS sandbox. Forwarded verbatim
+     * from `AskRequest` onto the `approval_requested` event; a host that does not
+     * recognise it shows the same prompt it always did.
+     */
+    readonly unsandboxed?: true;
 }
 export declare function askPerson(deps: SessionAskDeps, ask: ApprovalAsk, signal: AbortSignal | undefined): Promise<{
     readonly decision: "allow" | "deny";

package/dist/session/session-ask-link.js

@@ -15,6 +15,7 @@ export async function askPerson(deps, ask, signal) {
         summary: ask.summary,
         ...(ask.command !== undefined ? { command: ask.command } : {}),
         reason: ask.reason,
+        ...(ask.unsandboxed !== undefined ? { unsandboxed: ask.unsandboxed } : {}),
         expiresAt,
     });
     const settlement = await settled;
@@ -42,6 +43,10 @@ export function createSessionAskLink(deps) {
                 ...(masked !== undefined ? { command: masked.masked } : {}),
                 reason: req.reason ?? `matched ${req.rule}`,
                 ...(callId !== undefined ? { callId } : {}),
+                // US-004: carried through untouched, so a host that offers a distinct
+                // unsandboxed decision sees it on the port; a host that ignores it
+                // keeps the one approval prompt it has.
+                ...(req.unsandboxed !== undefined ? { unsandboxed: req.unsandboxed } : {}),
                 ...(control?.signal !== undefined ? { signal: control.signal } : {}),
             });
         },

package/dist/session/session-ask-port.js

@@ -40,6 +40,10 @@ export function createSessionAskPort(deps) {
                 tool: req.tool,
                 summary: req.summary,
                 reason: req.reason,
+                // US-004: an auto-decision carries whatever the request carried. No
+                // caller sets this today (an unsandboxed ask is never auto-decided),
+                // so it rides along rather than being silently dropped.
+                ...(req.unsandboxed !== undefined ? { unsandboxed: req.unsandboxed } : {}),
                 expiresAt: now(),
                 answerable: false,
             });

package/dist/session/session-backend.d.ts

@@ -6,13 +6,21 @@
  * satisfy this contract; nothing here is backend-specific.
  */
 import type { TranscriptDoc, TranscriptStore } from "#src/native/session/transcript-types";
-import type { AgentSessionProfile, ApprovalDecidedBy, EmbedderTool } from "./agent-session-types.ts";
+import type { SandboxState } from "#src/sandbox/types";
+import type { AgentSessionProfile, ApprovalDecidedBy, CommandRunResult, EmbedderTool, SessionConfigureInput } from "./agent-session-types.ts";
 import type { AgentSessionAdapter, SendTurnOpts, SessionHandle } from "./session-types.ts";
 export interface BackendInfo {
     /** "native" or "acp:<agent>"; recorded in the transcript document. */
     readonly kind: string;
     /** Read-only, JSON-safe capability summary. `{}` for native. */
     readonly capabilities: Readonly<Record<string, unknown>>;
+    /**
+     * US-001: the sandbox this backend resolved when it opened, so the embedder can
+     * say what the session's commands actually run under. Reported once at open — a
+     * sandbox that stops working mid-session is not re-probed. Absent for a backend
+     * that runs no shell of its own (the ACP backend leaves it out).
+     */
+    readonly sandbox?: SandboxState;
 }
 export interface ApprovalRequest {
     readonly callId?: string;
@@ -20,6 +28,12 @@ export interface ApprovalRequest {
     readonly summary: string;
     readonly command?: string;
     readonly reason: string;
+    /**
+     * US-004: the ask is for a run OUTSIDE the OS sandbox. Copied from the
+     * `AskRequest` by `createSessionAskLink` and forwarded onto the
+     * `approval_requested` event by `askPerson`; absent on every ordinary ask.
+     */
+    readonly unsandboxed?: true;
     /** Extra abort source, combined with the turn signal (for example a tool-level abort). */
     readonly signal?: AbortSignal;
 }
@@ -75,6 +89,14 @@ export interface BackendOpenContext {
     readonly providerInstructions?: string;
 }
 export interface OpenedBackend {
+    /** Absent on a backend that cannot change model or effort on a live session. The facade validates `input` first. */
+    configure?(input: SessionConfigureInput): Promise<void>;
+    /** Absent on a backend that cannot run a host-side command (ACP). */
+    runCommand?(request: {
+        command: string;
+        callId: string;
+        signal: AbortSignal;
+    }): Promise<CommandRunResult>;
     readonly adapter: AgentSessionAdapter;
     readonly handle: SessionHandle;
     readonly info: BackendInfo;

package/dist/session/session-interaction.d.ts

@@ -9,6 +9,8 @@ export interface SessionInteractionDeps {
     readonly sessionId: string;
     readonly runtime: CodingToolRuntime;
     readonly embedderTools: ReadonlyMap<string, EmbedderTool>;
+    /** Declared coding tools withheld by the runtime's advertisement policy. Never execute these calls. */
+    readonly unavailableTools?: ReadonlySet<string>;
     readonly asks: SessionAskPort;
     /** The running turn's signal (a never-aborting one between turns). */
     readonly turnSignal: () => AbortSignal;

package/dist/session/session-interaction.js

@@ -168,8 +168,15 @@ export function createSessionInteractionHandler(deps) {
         async onInteraction(request) {
             if (request.kind === "question")
                 return answerQuestion(deps, request.text);
-            if (request.kind === "context-tool")
+            if (request.kind === "context-tool") {
+                // A model may still call a denied tool it remembers from earlier turns.
+                // Keep it hidden, but distinguish a policy refusal from an unknown name.
+                if (deps.unavailableTools?.has(request.name)) {
+                    const reason = `Tool "${request.name}" is not available under the session policy`;
+                    return { answer: `Denied: ${reason}`, denied: { reason, breach: false } };
+                }
                 throw toolError(`Unknown tool "${request.name}"`, request.name);
+            }
             const tool = deps.embedderTools.get(request.name);
             return tool !== undefined ? runEmbedderTool(deps, tool, request) : runCodingTool(deps, request);
         },

package/dist/session/session-tool-support.d.ts

@@ -1,9 +1,13 @@
 import { type CodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import type { CommandInterceptor } from "#src/command-interceptor/index";
+import type { CommandShadow } from "#src/command-safety/types";
 import type { BashApprovalMode } from "#src/config/bash-approval";
+import { type SandboxConfig } from "#src/config/schemas-sandbox";
 import type { AskResolver } from "#src/permissions/index";
-import type { CommandLauncher } from "#src/sandbox/index";
+import type { CommandLauncher, SandboxState } from "#src/sandbox/index";
+import type { BackgroundCommandPort } from "#src/tools/bash-background";
 import type { ProtectedPathsPolicy } from "#src/tools/protected-paths";
+import type { ResolvedProviderTools } from "#src/tools/provider-advertise";
 import type { CodingToolName, ToolGrant } from "#src/tools/types";
 import type { AgentSessionProfile } from "./agent-session-types.ts";
 /** The pipeline stage the facade's tool calls and asks carry. */
@@ -26,11 +30,29 @@ export interface SessionLauncherArgs {
     readonly profile: AgentSessionProfile;
     readonly root: string;
     readonly protectedPaths: ProtectedPathsPolicy;
+    /**
+     * The resolved mode. Since US-001 the floor itself no longer keys on it —
+     * `nativeProfileRules` has already validated which mode may pair with
+     * `allowUnsandboxed` — but it stays part of the call so the caller declares
+     * the session's posture in one place.
+     */
     readonly bashApproval: BashApprovalMode;
     readonly allowUnsandboxed: boolean;
+    readonly config?: SandboxConfig;
 }
-/** The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox unless gated + allowUnsandboxed. */
-export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<CommandLauncher | undefined>;
+/** What the floor decided: the launcher to run under (if any), and the state to report. */
+export interface ResolvedSessionLauncher {
+    readonly launcher: CommandLauncher | undefined;
+    readonly sandbox: SandboxState;
+}
+/**
+ * The sandbox floor (spec 6.3): "ask", "full" and "review" need a usable sandbox,
+ * unless the session explicitly allows running without one — under `gated` (every
+ * call still goes to the person) or under `raw` (the person's own standing choice).
+ * The resolved state rides back beside the launcher, so the session can report
+ * what its commands actually run under.
+ */
+export declare function resolveSessionLauncher(args: SessionLauncherArgs): Promise<ResolvedSessionLauncher>;
 export interface SessionToolSupportArgs {
     readonly profile: AgentSessionProfile;
     readonly root: string;
@@ -40,7 +62,31 @@ export interface SessionToolSupportArgs {
     readonly launcher: CommandLauncher | undefined;
     readonly askResolver: AskResolver;
     readonly interceptor: CommandInterceptor | undefined;
+    readonly askRules?: readonly ToolGrant[];
+    readonly denyRules?: readonly ToolGrant[];
+    readonly askOnUnsandboxed?: boolean;
+    readonly askDiscoveredTools?: boolean;
+    readonly commandShadow?: CommandShadow;
+    /**
+     * US-003: offer Bash's per-call `unsandboxed` argument for this session
+     * (from `nativeProfileRules(...).allowUnsandboxedCommands`). Optional and
+     * defaulting to off, so every existing caller keeps today's tool surface.
+     */
+    readonly unsandboxedCommands?: boolean;
+    readonly backgroundCommands?: BackgroundCommandPort;
+    readonly providerTools?: ResolvedProviderTools;
+    /**
+     * Narrow the profile's built-in tools to these names; the universal scratchpad
+     * tools are always kept. ABSENT keeps every profile tool. Never adds a tool.
+     * Provider tools are narrowed earlier, by `providerAdmits` at resolution.
+     */
+    readonly allowedTools?: readonly string[];
 }
+/**
+ * The `admits` predicate for `resolveProviderTools`: a tool `<id>__<local>` is
+ * admitted when `allowedTools` names it exactly or names `<id>__*`.
+ */
+export declare function providerAdmits(allowedTools: readonly string[]): (providerId: string, localName: string) => boolean;
 export interface SessionToolSupport {
     readonly support: CodingToolSupport;
     readonly grants: readonly ToolGrant[];