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

package/dist/sandbox/launcher.js

@@ -137,6 +137,9 @@ export function createCommandLauncher(opts) {
         state,
         async run(req) {
             const tmpDir = env.tmpDir !== undefined && (await ensureTmpDir(env.tmpDir)) ? env.tmpDir : undefined;
+            if (req.unwrapped === true) {
+                return runUnwrapped(req, { backend: "none", wrapped: false, reason: "requested" }, { ...env, tmpDir });
+            }
             if (state.kind === "disabled")
                 return runUnwrapped(req, { backend: "none", wrapped: false }, { ...env, tmpDir });
             if (state.kind === "unavailable") {

package/dist/sandbox/types.d.ts

@@ -112,6 +112,8 @@ export interface LaunchRequest {
     readonly stripEnvVars: readonly string[];
     /** The CALLER's own overlay (Exec's Yarn no-scripts env). Never the backend's. */
     readonly env?: Readonly<Record<string, string>>;
+    /** Explicitly run this command outside the sandbox without changing launcher state. */
+    readonly unwrapped?: true;
     /** Aborts the run: forwarded to runArgv, which SIGKILLs the process group. US-001. */
     readonly signal?: AbortSignal;
 }

package/dist/session/agent-session-command.d.ts

@@ -0,0 +1,19 @@
+import type { ClaimedTurn, LiveTurn, TurnRunContext } from "./agent-session-turn.ts";
+import type { CommandRunResult, SessionEvent } from "./agent-session-types.ts";
+import type { OpenedBackend } from "./session-backend.ts";
+interface CommandHooks {
+    onStart(live: LiveTurn): void;
+    onSettle(): void;
+}
+export interface ClaimedCommand extends Pick<ClaimedTurn, "turnId" | "settled" | "cancel"> {
+    readonly result: Promise<CommandRunResult>;
+}
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export declare function claimCommand(options: {
+    ctx: TurnRunContext;
+    run: NonNullable<OpenedBackend["runCommand"]>;
+    command: string;
+    onEvent(event: SessionEvent): void;
+    hooks: CommandHooks;
+}): ClaimedCommand;
+export {};

package/dist/session/agent-session-command.js

@@ -0,0 +1,38 @@
+import { NaxError } from "#src/infra/nax-error";
+import { displayToolInput, toolResultPreview } from "#src/native/session/turn-event-emitter";
+import { _agentSessionDeps } from "./agent-session-deps.js";
+/** Claim synchronously, but invoke callbacks only after the facade installs the claim. */
+export function claimCommand(options) {
+    const { ctx, run, command, onEvent, hooks } = options;
+    const turnId = _agentSessionDeps.randomUUID();
+    const callId = _agentSessionDeps.randomUUID();
+    const controller = new AbortController();
+    const emit = (body) => onEvent({
+        sessionId: ctx.sessionId,
+        turnId,
+        at: new Date(_agentSessionDeps.now()).toISOString(),
+        metadata: ctx.metadata,
+        ...body,
+    });
+    const abort = (code, reason) => controller.abort(new NaxError(reason, code, { stage: "agent-session" }));
+    const result = Promise.resolve().then(async () => {
+        const timer = _agentSessionDeps.setTimeout(() => abort("AGENT_SESSION_TURN_TIMEOUT", "turn deadline"), ctx.turnTimeoutSeconds * 1000);
+        try {
+            hooks.onStart({ turnId, signal: controller.signal, emit });
+            emit({ type: "tool_call", name: "Bash", input: displayToolInput({ command }), callId });
+            const outcome = await run({ command, callId, signal: controller.signal });
+            emit({ type: "tool_result", callId, isError: outcome.isError, preview: toolResultPreview(outcome.content) });
+            return outcome;
+        }
+        finally {
+            _agentSessionDeps.clearTimeout(timer);
+            hooks.onSettle();
+        }
+    });
+    return {
+        turnId,
+        result,
+        settled: result.then(() => { }, () => { }),
+        cancel: (reason) => abort("AGENT_SESSION_CANCELLED", reason),
+    };
+}

package/dist/session/agent-session-types.d.ts

@@ -117,6 +117,8 @@ export type SessionEventBody = {
     readonly command?: string;
     readonly reason: string;
     readonly expiresAt: string;
+    /** US-004: the call wants to run outside the OS sandbox. Absent on every ordinary ask. */
+    readonly unsandboxed?: true;
     /** `false`: decided already (by the profile); informational. Absent: a person's answer is awaited. */
     readonly answerable?: false;
 } | {
@@ -167,7 +169,14 @@ export type AnswerReply = {
     readonly text: string;
 };
 export type AnswerStatus = "accepted" | "expired" | "cancelled" | "unknown";
+export interface CommandRunResult {
+    /** The Bash tool's result text as the model would see it (capped by the tool runtime). */
+    readonly content: string;
+    readonly isError: boolean;
+}
 export interface AgentSession {
+    /** Run through the session's Bash tool without a model turn. The facade always provides this method. */
+    runCommand?(command: string, onEvent: (event: SessionEvent) => void): Promise<CommandRunResult>;
     readonly id: string;
     /** The backend that opened this session (`kind` and its capability summary). */
     readonly backend: BackendInfo;

package/dist/session/agent-session.js

@@ -1,3 +1,4 @@
+import { claimCommand } from "./agent-session-command.js";
 import { _agentSessionDeps } from "./agent-session-deps.js";
 import { AgentSessionError } from "./agent-session-errors.js";
 import { resolveAgentSessionOptions } from "./agent-session-options.js";
@@ -7,6 +8,17 @@ import { createPendingAskTable } from "./pending-asks.js";
 import { createSessionAskPort } from "./session-ask-port.js";
 /** The handler's turn signal between turns: never aborts. */
 const IDLE_SIGNAL = new AbortController().signal;
+/**
+ * The sandbox state as the embedder sees it: a frozen COPY, down to the
+ * `network` list an `available` state carries. Copying keeps the backend's own
+ * record out of the embedder's reach; freezing keeps the embedder from editing
+ * the record of what its commands ran under (US-001).
+ */
+function frozenSandbox(state) {
+    if (state.kind !== "available" || typeof state.network === "string")
+        return Object.freeze({ ...state });
+    return Object.freeze({ ...state, network: Object.freeze([...state.network]) });
+}
 class FacadeAgentSession {
     parts;
     active;
@@ -21,7 +33,13 @@ class FacadeAgentSession {
     }
     get backend() {
         const info = this.parts.opened.info;
-        return Object.freeze({ kind: info.kind, capabilities: Object.freeze({ ...info.capabilities }) });
+        // US-001: the sandbox state rides through the facade frozen, so an embedder
+        // cannot edit the record of what its commands ran under.
+        return Object.freeze({
+            kind: info.kind,
+            capabilities: Object.freeze({ ...info.capabilities }),
+            ...(info.sandbox !== undefined ? { sandbox: frozenSandbox(info.sandbox) } : {}),
+        });
     }
     get lastTurn() {
         return this.last;
@@ -49,6 +67,36 @@ class FacadeAgentSession {
         this.active = turn;
         return turn.iterable;
     }
+    async runCommand(command, onEvent) {
+        const code = this.closing !== undefined
+            ? "AGENT_SESSION_CLOSED"
+            : this.active !== undefined
+                ? "AGENT_SESSION_BUSY"
+                : this.parts.opened.runCommand === undefined
+                    ? "AGENT_SESSION_CAPABILITY_UNSUPPORTED"
+                    : undefined;
+        const run = this.parts.opened.runCommand;
+        if (code !== undefined || run === undefined) {
+            throw new AgentSessionError(`Session "${this.id}" cannot run a command`, code ?? "AGENT_SESSION_CAPABILITY_UNSUPPORTED", { sessionId: this.id });
+        }
+        const claim = claimCommand({
+            ctx: this.parts.ctx,
+            command,
+            onEvent,
+            run: (request) => run.call(this.parts.opened, request),
+            hooks: {
+                onStart: (live) => {
+                    this.parts.slot.turn = live;
+                },
+                onSettle: () => {
+                    this.parts.slot.turn = undefined;
+                    this.active = undefined;
+                },
+            },
+        });
+        this.active = claim;
+        return claim.result;
+    }
     answer(requestId, reply) {
         return this.parts.table.answer(requestId, reply);
     }

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

@@ -2,17 +2,30 @@ import type { BashApprovalMode } from "#src/config/bash-approval";
 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;
     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 +47,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

@@ -18,6 +18,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,6 +35,7 @@ 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
@@ -37,6 +46,8 @@ const OptionsSchema = z.strictObject({
         .optional(),
     bashApproval: z.enum(["raw", "gated", "escalate"]).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 +89,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,19 @@
  * with built-in and embedder tools, the NativeSessionAdapter, loop handlers
  * and the resume model check.
  */
+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 { 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,28 +41,44 @@ 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, allowUnsandboxed, allowUnsandboxedCommands } = nativeProfileRules(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,
         allowUnsandboxed,
     });
+    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,
+        // 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,
@@ -77,6 +96,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 +115,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/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 } 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,12 @@ export interface BackendOpenContext {
     readonly providerInstructions?: string;
 }
 export interface OpenedBackend {
+    /** 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-tool-support.d.ts

@@ -2,8 +2,9 @@ import { type CodingToolSupport } from "#src/coding-tools/coding-tool-support";
 import type { CommandInterceptor } from "#src/command-interceptor/index";
 import type { BashApprovalMode } from "#src/config/bash-approval";
 import type { AskResolver } from "#src/permissions/index";
-import type { CommandLauncher } from "#src/sandbox/index";
+import type { CommandLauncher, SandboxState } from "#src/sandbox/index";
 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 +27,28 @@ 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;
 }
-/** 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 +58,25 @@ export interface SessionToolSupportArgs {
     readonly launcher: CommandLauncher | undefined;
     readonly askResolver: AskResolver;
     readonly interceptor: CommandInterceptor | undefined;
+    /**
+     * 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 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[];