@nathapp/nax-agent 0.3.1 → 0.85.0

package/dist/native/session/session.js

@@ -10,6 +10,9 @@ import { NaxError } from "#src/infra/index";
 import { createSpinBreaker } from "#src/infra/spin-breaker/index";
 import { NATIVE_AGENT } from "../models.js";
 import { nativeSessionId } from "../session-affinity.js";
+import { instructionFileNameFor } from "./instruction-file-name.js";
+import { openRepositoryInstructions } from "./instruction-session.js";
+import { instructionTranscriptStore } from "./instruction-transcript.js";
 import { createFileTranscriptStore } from "./transcript-store.js";
 export function createNativeSessionState() {
     return {
@@ -20,11 +23,13 @@ export function createNativeSessionState() {
         streamHooks: new Map(),
         failed: new Set(),
         transcriptOwners: new Map(),
+        carryHistoryAcrossModels: new Set(),
         compaction: new Map(),
         transportRetry: new Map(),
         spinBreakers: new Map(),
         lastUsage: new Map(),
         systemPrompts: new Map(),
+        repositoryInstructions: new Map(),
     };
 }
 /**
@@ -86,23 +91,39 @@ function recordSystemPrompt(state, name, systemPrompt) {
 }
 /** The request field for the session's system prompt: `{ system }`, or `{}` when it has none. */
 export function systemFieldFor(state, sessionName) {
-    const system = state.systemPrompts.get(sessionName);
+    const base = state.systemPrompts.get(sessionName);
+    const repository = state.repositoryInstructions.get(sessionName)?.render();
+    const system = [base, repository].filter(Boolean).join("\n\n") || undefined;
     return system === undefined ? {} : { system };
 }
 export async function openNativeSession(state, name, opts) {
+    instructionFileNameFor(opts.instructionFileName);
     const store = openTranscriptStore(name, opts);
     if (opts.transcriptDir)
         state.transcriptDirs.set(name, opts.transcriptDir);
     else
         state.transcriptDirs.delete(name);
-    state.transcripts.set(name, { store, retainOnClose: opts.retainOnClose === true });
+    state.transcripts.set(name, {
+        store,
+        retainOnClose: opts.retainOnClose === true,
+    });
     state.timeouts.set(name, opts.timeoutSeconds);
     state.scratchpadRoots.set(name, opts.workdir);
     if (opts.transcriptOwner !== undefined)
         state.transcriptOwners.set(name, opts.transcriptOwner);
     else
         state.transcriptOwners.delete(name);
+    if (opts.carryHistoryAcrossModels === true)
+        state.carryHistoryAcrossModels.add(name);
+    else
+        state.carryHistoryAcrossModels.delete(name);
     recordSystemPrompt(state, name, opts.systemPrompt);
+    const instructions = await openRepositoryInstructions(name, opts, store);
+    state.repositoryInstructions.set(name, instructions);
+    state.transcripts.set(name, {
+        store: instructionTranscriptStore(store, instructions),
+        retainOnClose: opts.retainOnClose === true,
+    });
     // `resume` is SessionManager's "this name already has a descriptor in this
     // process" signal, and it had no consumer on this transport (nax#1877) — a
     // native session resumed whatever transcript happened to be on disk. Honouring
@@ -129,7 +150,10 @@ export async function openNativeSession(state, name, opts) {
         // native has no reconnect, so its logical and physical identity genuinely
         // coincide. `nativeSessionId` is a pure hash of the name and deliberately
         // not memoised, so this is exactly the id `sendTurn` later puts on the wire.
-        protocolIds: { recordId: nativeSessionId(name), sessionId: nativeSessionId(name) },
+        protocolIds: {
+            recordId: nativeSessionId(name),
+            sessionId: nativeSessionId(name),
+        },
         ...(opts.modelDef !== undefined ? { modelDef: opts.modelDef } : {}),
         ...(opts.modelTier !== undefined ? { modelTier: opts.modelTier } : {}),
     };
@@ -150,6 +174,7 @@ export function clearNativeSessionState(state, sessionName) {
     state.timeouts.delete(sessionName);
     state.scratchpadRoots.delete(sessionName);
     state.transcriptOwners.delete(sessionName);
+    state.carryHistoryAcrossModels.delete(sessionName);
     state.streamHooks.delete(sessionName);
     state.failed.delete(sessionName);
     state.compaction.delete(sessionName);
@@ -157,6 +182,7 @@ export function clearNativeSessionState(state, sessionName) {
     state.spinBreakers.delete(sessionName);
     state.lastUsage.delete(sessionName);
     state.systemPrompts.delete(sessionName);
+    state.repositoryInstructions.delete(sessionName);
 }
 /**
  * Kept on failure, deleted on success. Every Phase B op is lifetime "fresh", so

package/dist/native/session/transcript-identity.d.ts

@@ -14,6 +14,8 @@ import type { TranscriptDoc } from "./transcript-types.ts";
 export interface TranscriptIdentity {
     readonly owner?: string;
     readonly model?: string;
+    /** Keep a document written by another model (S5-3); `model` still names the current one. */
+    readonly carryAcrossModels?: boolean;
 }
 /**
  * The model half of `TranscriptIdentity`: the native `provider/model` id with

package/dist/native/session/transcript-identity.js

@@ -35,7 +35,7 @@ function isForeignTranscript(doc, identity, sessionName) {
         });
         return true;
     }
-    if (model !== undefined && doc.model !== undefined && doc.model !== model) {
+    if (identity.carryAcrossModels !== true && model !== undefined && doc.model !== undefined && doc.model !== model) {
         getLogger().debug("native-session", "Ignoring a transcript written by another model", {
             sessionName,
             storedModel: doc.model,

package/dist/native/session/transcript-store.js

@@ -6,9 +6,10 @@
  * nax stored nothing; SessionDescriptor still has no message field, and gains
  * none. See ADR-028 sections 2 and 3.
  */
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { getLogger, NaxError } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
 import { historyFromTranscript, transcriptDocFor } from "./transcript-identity.js";
 export { transcriptModelIdentity } from "./transcript-identity.js";
 export function transcriptPath(dir, sessionName) {
@@ -60,7 +61,8 @@ export async function readTranscriptDoc(dir, sessionName) {
 }
 async function writeTranscriptDoc(dir, sessionName, doc) {
     await mkdir(dir, { recursive: true });
-    await writeFile(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2), "utf8");
+    // Atomic (#3): a torn transcript is unrecoverable — every later load throws TRANSCRIPT_CORRUPT.
+    await writeFileAtomic(transcriptPath(dir, sessionName), JSON.stringify(doc, null, 2));
 }
 /**
  * The file store: `<dir>/<name>.transcript.json`, written as given (the loop's

package/dist/native/session/transcript-types.d.ts

@@ -39,6 +39,9 @@ export interface TranscriptDoc {
      * (S3 spec 5.5 write order: markTurn(running), turn, markTurn(ended)).
      */
     readonly turn?: TurnMarker;
+    /** Native instruction discovery audit, independent of compacted message history. */
+    readonly instructionSources?: readonly import("./repository-instructions.ts").InstructionSource[];
+    readonly instructionDirectories?: readonly string[];
 }
 export interface TranscriptStore {
     /** `null` when the session has no document yet. */

package/dist/native/session/turn-complete-step.js

@@ -65,8 +65,10 @@ export async function completeWithRecovery(args) {
         // caller's array, the one the turn-end transcript save persists — is returned untouched,
         // so the transcript stays the true record. `boundary` is this step's
         // overflow fact (`compacted`): true only on the post-compaction retry,
-        // where a prefix rewrite is free. A model change never reaches this step:
-        // the transcript store refuses another model's history (spec 8.3).
+        // where a prefix rewrite is free. A model change CAN reach this step under
+        // carryHistoryAcrossModels (S5-3): the transcript store no longer refuses
+        // another model's history, but the per-model compaction anchor is dropped
+        // on that mismatch, so applyHistoryPatch honours an undefined anchor.
         const transformed = await loopEvents.dispatch("transform_context", {
             messages: msgs,
             tools,

package/dist/native/session/turn-event-emitter.d.ts

@@ -45,4 +45,8 @@ export interface TurnEventEmitter {
     flushUnanswered(): void;
 }
 export declare function usageEvent(round: number, usage: TokenUsage, costUsd: number): TurnEvent;
+/** The masking and cap live `tool_call.input` gets; exported for ACP replay (S5-1). */
+export declare function displayToolInput(input: unknown): unknown;
+/** The masking and cap live `tool_result.preview` gets; exported for ACP replay (S5-1). */
+export declare function toolResultPreview(content: string): string;
 export declare function createTurnEventEmitter(sink: TurnEventSink | undefined): TurnEventEmitter;

package/dist/native/session/turn-event-emitter.js

@@ -43,7 +43,8 @@ export function usageEvent(round, usage, costUsd) {
         costUsd,
     };
 }
-function cappedInput(input) {
+/** The masking and cap live `tool_call.input` gets; exported for ACP replay (S5-1). */
+export function displayToolInput(input) {
     const redacted = redactSecrets(capStrings(input, REDACTION_SCAN_BYTES));
     let json;
     try {
@@ -56,7 +57,8 @@ function cappedInput(input) {
         return redacted;
     return { truncated: true, preview: cutToByteCap(json, TOOL_CALL_INPUT_BYTES) };
 }
-function previewOf(content) {
+/** The masking and cap live `tool_result.preview` gets; exported for ACP replay (S5-1). */
+export function toolResultPreview(content) {
     return cutToByteCap(redactSecrets(cutToByteCap(content, REDACTION_SCAN_BYTES)), TOOL_RESULT_PREVIEW_BYTES);
 }
 const NOOP_EMITTER = {
@@ -103,7 +105,7 @@ export function createTurnEventEmitter(sink) {
             // Capped BEFORE the count moves: a throwing input (a hostile getter or
             // proxy) must not leave an outstanding call the matching toolResult then
             // answers with no preceding tool_call.
-            const input = cappedInput(recordedInput ?? call.input);
+            const input = displayToolInput(recordedInput ?? call.input);
             outstanding.set(call.id, (outstanding.get(call.id) ?? 0) + 1);
             emit({ type: "tool_call", callId: call.id, name: call.name, input });
         },
@@ -119,7 +121,7 @@ export function createTurnEventEmitter(sink) {
                 type: "tool_result",
                 callId: result.toolCallId,
                 isError: result.isError === true,
-                preview: previewOf(result.content),
+                preview: toolResultPreview(result.content),
             });
         },
         flushUnanswered() {

package/dist/native/session/turn-loop-round-trip.js

@@ -33,6 +33,7 @@
  */
 import { inputClassTokens } from "#src/cost/core/index";
 import { getSafeLogger } from "#src/infra/index";
+import { parseModelSpec } from "../models.js";
 import { estimateContextTokens, shouldCompact, } from "./compaction.js";
 import { usageBeat } from "./turn-accumulator.js";
 import { runProactiveCompaction } from "./turn-compaction-step.js";
@@ -96,6 +97,21 @@ async function maybeCompact(state, params) {
     }
     return { summarizeFailed: step.summarizeFailed };
 }
+/**
+ * The catalog provider and model that answer for this handle: the
+ * "provider/model[effort]" string, effort stripped, split on the first "/".
+ * The same pair parseNativeModel hands client.model(); undefined, never a
+ * throw, when there is no usable model.
+ */
+function originOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    const spec = parseModelSpec(raw).model;
+    const slash = spec.indexOf("/");
+    if (slash <= 0 || slash === spec.length - 1)
+        return undefined;
+    return { provider: spec.slice(0, slash), model: spec.slice(slash + 1) };
+}
 /**
  * One model call and its bookkeeping: `completeWithRecovery`, the usage/anchor
  * updates, the activity beats, `after_response`, and pushing the settled
@@ -140,7 +156,6 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
     }
     state.roundTrips += 1;
     params.usage.add(res.usage, res.costUsd, res.rates);
-    state.output = res.text;
     // nax#1852: the anchor is the whole prompt the provider charged for, not
     // just its uncached portion. Under prompt caching (which the round trip
     // above always requests) the cached prefix arrives in the cache fields,
@@ -184,15 +199,19 @@ async function runModelRoundTrip(state, params, summarizeFailed) {
     // what it records: answering the ORIGINAL calls while recording patched
     // ones would desync the transcript from what actually executed.
     const assistantText = afterResponse.text ?? res.text;
+    // The recorded answer IS the patched one: transcript and TurnResult.output must agree (turn-event.ts).
+    state.output = assistantText;
     const assistantToolCalls = afterResponse.toolCalls ?? res.toolCalls;
     const assistantThinking = afterResponse.thinking ?? res.thinking;
     // Thinking blocks are appended, not merely representable: Anthropic needs
     // the exact block back to continue a thinking conversation (ADR-028 s8).
+    const origin = originOf(handle.modelDef?.model);
     state.messages.push({
         role: "assistant",
         content: assistantText,
         ...(assistantToolCalls !== undefined ? { toolCalls: assistantToolCalls } : {}),
         ...(assistantThinking !== undefined ? { thinking: assistantThinking } : {}),
+        ...(origin !== undefined ? { origin } : {}),
     });
     if (assistantToolCalls === undefined || assistantToolCalls.length === 0) {
         state.completedNormally = true;

package/dist/native/session/turn-loop.js

@@ -65,6 +65,7 @@ export async function runNativeTurn(handle, prompt, opts, deps) {
     const transcriptIdentity = {
         owner: deps.sessionState.transcriptOwners.get(handle.id),
         model: transcriptModelIdentity(handle.modelDef?.model),
+        ...(deps.sessionState.carryHistoryAcrossModels.has(handle.id) ? { carryAcrossModels: true } : {}),
     };
     let messages = [
         ...historyFromTranscript(await store.load(handle.id), transcriptIdentity, handle.id),

package/dist/native/session-adapter.js

@@ -16,6 +16,7 @@ import { _clientDeps, getNativeClient } from "./client.js";
 import { createSessionCredentialStore } from "./credentials/session-source.js";
 import { toAdapterFailure } from "./errors.js";
 import { buildRateCard, NATIVE_AGENT, parseNativeModel, resolveContextWindow, toThinkingLevel } from "./models.js";
+import { createInstructionInteraction } from "./session/instruction-interaction.js";
 import { closeNativeSession, createNativeSessionState, markNativeTurnOutcome, openNativeSession, systemFieldFor, } from "./session/session.js";
 import { buildNativeStreamEvent } from "./session/turn-events.js";
 import { runNativeTurn } from "./session/turn-loop.js";
@@ -140,6 +141,10 @@ export class NativeSessionAdapter {
         const thinking = toThinkingLevel(effort);
         const client = await this.client();
         const resolved = await client.model(provider, model);
+        const contextWindow = resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow);
+        this.state.repositoryInstructions
+            .get(handle.id)
+            ?.setContextBudget(contextWindow, this.state.systemPrompts.get(handle.id));
         const catalog = client.pricing(resolved);
         const { rates, source: pricingSource } = buildRateCard(catalog, handle.modelDef?.pricing);
         const storedTimeoutSeconds = this.state.timeouts.get(handle.id);
@@ -155,7 +160,7 @@ export class NativeSessionAdapter {
         const sessionId = nativeSessionId(handle.id);
         // S3-4: the session's system prompt (facade `instructions`), or `{}`.
         // Resolved here so the `complete` closure spreads it without a branch.
-        const systemField = systemFieldFor(this.state, handle.id);
+        const instructionInteraction = createInstructionInteraction(this.state.repositoryInstructions.get(handle.id), opts.interactionHandler);
         // One budget for the whole turn, not one per round-trip. Created here
         // because this is where `timeoutSeconds` is known; consulted by the loop.
         const deadline = createTurnDeadline(timeoutSeconds);
@@ -204,6 +209,7 @@ export class NativeSessionAdapter {
         if (opts.signal !== undefined)
             turnSignals.unshift(opts.signal);
         const turnSignal = AbortSignal.any(turnSignals);
+        const turnOpts = { ...opts, interactionHandler: instructionInteraction.handler };
         let result;
         try {
             // US-002: clear the deadline timer at turn settlement, no matter how
@@ -211,10 +217,10 @@ export class NativeSessionAdapter {
             // `AbortSignal.any` above holds a reference to `deadlineController.signal`,
             // so a settled turn must drop its timer to avoid keeping it armed past
             // the turn boundary.
-            result = await runNativeTurn(handle, prompt, opts, {
+            result = await runNativeTurn(handle, prompt, turnOpts, {
                 sessionState: this.state,
                 deadline,
-                contextWindow: resolveContextWindow(handle.modelDef?.contextWindow, resolved.contextWindow),
+                contextWindow,
                 ...(this.state.compaction.get(handle.id) !== undefined
                     ? { compaction: this.state.compaction.get(handle.id) }
                     : {}),
@@ -267,7 +273,12 @@ export class NativeSessionAdapter {
                         });
                         const summaryUsage = res.usage;
                         const { costUsd, resolvedRates } = priceCall(summaryUsage, rates);
-                        return { text: res.text, usage: summaryUsage, costUsd, rates: resolvedRates };
+                        return {
+                            text: res.text,
+                            usage: summaryUsage,
+                            costUsd,
+                            rates: resolvedRates,
+                        };
                     }
                     finally {
                         if (timer !== undefined)
@@ -293,11 +304,12 @@ export class NativeSessionAdapter {
                     // thinking LEVEL rather than a boolean, so normalize at this boundary.
                     const requestThinking = requestOptions?.thinking === false ? undefined : thinking;
                     try {
+                        instructionInteraction.acknowledge();
                         const res = await streamComplete(client, resolved, {
                             messages,
                             ...(tools.length > 0 ? { tools } : {}),
                             sessionId,
-                            ...systemField,
+                            ...systemFieldFor(this.state, handle.id),
                             signal,
                             ...(requestThinking !== undefined ? { thinking: requestThinking } : {}),
                             ...(requestOptions?.temperature !== undefined ? { temperature: requestOptions.temperature } : {}),
@@ -408,6 +420,9 @@ export class NativeSessionAdapter {
      * both carry, so clear by name rather than synthesising a handle.
      */
     async closePhysicalSession(handle, _workdir, _options) {
-        return closeNativeSession(this.state, { id: handle, agentName: NATIVE_AGENT });
+        return closeNativeSession(this.state, {
+            id: handle,
+            agentName: NATIVE_AGENT,
+        });
     }
 }

package/dist/permissions/approvals-store.d.ts

@@ -85,7 +85,7 @@ export declare function readApprovalsFileDetailed(path: string): Promise<Approva
  */
 export declare function readApprovalsFile(path: string): Promise<ApprovalsFile>;
 export declare function readApprovals(path: string): Promise<readonly ApprovalEntry[]>;
-/** Serialize the whole store. Callers hold the path lock. */
+/** Serialize the whole store, atomically (#16): a torn store would lose every remembered approval. Callers hold the path lock. */
 export declare function writeApprovalsFile(path: string, file: ApprovalsFile): Promise<void>;
 /**
  * Lock the read-modify-write. Worktree-isolated parallel stories share one
@@ -96,6 +96,8 @@ export declare function writeApprovalsFile(path: string, file: ApprovalsFile): P
  *
  * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
  * lands in a store that stays untrusted.
+ *
+ * An unparseable store is refused, never replaced (the removal path does the same).
  */
 export declare function appendApproval(path: string, entry: ApprovalEntry): Promise<void>;
 /**

package/dist/permissions/approvals-store.js

@@ -19,8 +19,10 @@
  * primitive that surface calls into.
  */
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { NaxError } from "#src/infra/index";
+import { writeFileAtomic } from "#src/internal/atomic-write";
 import { withPathFileLock } from "#src/internal/path-file-lock";
 const EMPTY_FILE = { entries: [], taint: undefined };
 /**
@@ -146,11 +148,11 @@ export async function readApprovalsFile(path) {
 export async function readApprovals(path) {
     return (await readApprovalsFile(path)).entries;
 }
-/** Serialize the whole store. Callers hold the path lock. */
+/** Serialize the whole store, atomically (#16): a torn store would lose every remembered approval. Callers hold the path lock. */
 export async function writeApprovalsFile(path, file) {
     const body = file.taint === undefined ? { entries: file.entries } : { taint: file.taint, entries: file.entries };
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+    await writeFileAtomic(path, `${JSON.stringify(body, null, 2)}\n`);
 }
 /**
  * Lock the read-modify-write. Worktree-isolated parallel stories share one
@@ -161,12 +163,23 @@ export async function writeApprovalsFile(path, file) {
  *
  * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
  * lands in a store that stays untrusted.
+ *
+ * An unparseable store is refused, never replaced (the removal path does the same).
  */
 export async function appendApproval(path, entry) {
     await mkdir(dirname(path), { recursive: true });
     await withPathFileLock(path, async () => {
-        const existing = await readApprovalsFile(path);
-        await writeApprovalsFile(path, { taint: existing.taint, entries: [...existing.entries, entry] });
+        // Detailed read, not readApprovalsFile: that one reads failure AS empty (right for a
+        // lookup), and writing "empty + this entry" back would destroy the store (#16). A read
+        // error propagates; the caller logs it and still allows the approved call.
+        const read = await readApprovalsFileDetailed(path);
+        if (read.state === "unparseable") {
+            throw new NaxError("approvals.json could not be parsed; not rewriting it", "APPROVALS_STORE_UNPARSEABLE", {
+                stage: "permissions",
+                path,
+            });
+        }
+        await writeApprovalsFile(path, { taint: read.file.taint, entries: [...read.file.entries, entry] });
     });
 }
 /**

package/dist/sandbox/session-tmp.js

@@ -12,9 +12,11 @@
  * The parent is `/tmp/nax`, one shared directory that is easier to find and
  * list than a flat `/tmp/nax-<runId>`. It is shared, so it cannot be created
  * once and trusted: a `/tmp/nax` made by one OS user is not writable by
- * another. The parent is therefore re-resolved on EVERY call from three host
- * facts the `_sessionTmpDeps` seam exposes, with no cache, and anything nax
- * cannot vouch for falls back to a per-user `/tmp/nax-<uid>`.
+ * another. The parent is therefore re-resolved on EVERY call from four host
+ * facts the `_sessionTmpDeps` seam exposes — including the uid that owns it,
+ * because a world-writable directory another user created is still theirs to
+ * plant symlinks in — with no cache, and anything nax cannot vouch for falls
+ * back to a per-user `/tmp/nax-<uid>`.
  *
  * The root is the literal `/tmp` (not `os.tmpdir()`): callers record and assert
  * this machine-stable location, and the OS inherits the rest.
@@ -38,16 +40,20 @@ export const _sessionTmpDeps = {
     uid: () => process.getuid?.() ?? 0,
 };
 /**
- * True when `/tmp/nax` is a real directory the current user can write and
- * search. Absence is NOT this case: an absent parent is a usable shared parent
- * (the launcher creates it), and every other failure means the path is there in
- * a shape nax cannot vouch for.
+ * True when `/tmp/nax` is a real directory the current user OWNS and can write
+ * and search. Absence is NOT this case: an absent parent is a usable shared
+ * parent (the launcher creates it), and every other failure means the path is
+ * there in a shape nax cannot vouch for.
  */
 function isUsableSharedParent() {
     try {
         const stats = _sessionTmpDeps.lstat(SHARED_TMP_PARENT);
         if (!stats.isDirectory() || stats.isSymbolicLink())
             return false;
+        // Writability is not trust: a 0777 /tmp/nax another user created lets that user
+        // pre-create the run directories or read what sandboxed commands write there.
+        if (stats.uid !== _sessionTmpDeps.uid())
+            return false;
     }
     catch (err) {
         // ENOENT is the one failure that means "create /tmp/nax".

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

@@ -117,6 +117,8 @@ export type SessionEventBody = {
     readonly command?: string;
     readonly reason: string;
     readonly expiresAt: string;
+    /** `false`: decided already (by the profile); informational. Absent: a person's answer is awaited. */
+    readonly answerable?: false;
 } | {
     readonly type: "approval_resolved";
     readonly requestId: string;
@@ -127,6 +129,8 @@ export type SessionEventBody = {
     readonly requestId: string;
     readonly text: string;
     readonly expiresAt: string;
+    /** `false`: informational (`noteQuestion`); `answer()` on it does nothing. Absent: an answer is awaited. */
+    readonly answerable?: false;
 } | {
     readonly type: "usage";
     readonly round: number;

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

@@ -5,12 +5,16 @@ import type { LoopHandlerSet } from "#src/native/session/loop-events/types";
 import type { AgentSessionHostPorts, AgentSessionProfile } from "./agent-session-types.ts";
 export interface NativeBackendOptions {
     readonly model: string;
+    /** Repository instruction basename; defaults to AGENTS.md. */
+    readonly instructionFileName?: string;
     readonly credentials?: CredentialSource;
     readonly catalogOverrides?: NativeCatalogOverrides;
     readonly loopHandlers?: LoopHandlerSet;
     readonly hostPorts?: AgentSessionHostPorts;
     readonly bashApproval?: BashApprovalMode;
     readonly allowUnsandboxed?: boolean;
+    /** Keep a resumed or continued conversation when the model differs (ACP server model switch, S5-3). */
+    readonly carryHistoryAcrossModels?: boolean;
 }
 export interface ResolvedNativeOptions {
     /** The caller's object, unchanged. */

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

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { parseNativeModel } from "#src/native/models";
+import { isInstructionFileName } from "#src/native/session/instruction-file-name";
 import { AgentSessionError } from "./agent-session-errors.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -16,6 +17,10 @@ function hasMethods(names) {
 const isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const OptionsSchema = z.strictObject({
     model: z.string().min(1),
+    instructionFileName: z
+        .string()
+        .refine(isInstructionFileName, "must be a nonhidden Markdown basename without path separators, colon or control characters")
+        .optional(),
     credentials: z
         .custom((value) => isRecord(value) && (value.kind === "memory" || value.kind === "exec"), "must be a memory or exec source")
         .optional(),
@@ -31,6 +36,7 @@ const OptionsSchema = z.strictObject({
         .optional(),
     bashApproval: z.enum(["raw", "gated", "escalate"]).optional(),
     allowUnsandboxed: z.boolean().optional(),
+    carryHistoryAcrossModels: z.boolean().optional(),
 });
 function invalid(message, context = {}) {
     return new AgentSessionError(`Invalid agent session options: ${message}`, "AGENT_SESSION_INVALID_OPTIONS", context);

package/dist/session/native-backend.js

@@ -15,7 +15,10 @@ import { createSessionInteractionHandler, embedderToolDescriptor } from "./sessi
 import { buildSessionToolSupport, defaultProtectedPaths, resolveSessionLauncher } 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 = { maxAttempts: 3, baseDelayMs: 2000 };
+const SESSION_TRANSPORT_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 2000,
+};
 function createAdapter(raw) {
     const overrides = raw.catalogOverrides ?? [];
     const owns = overrides.length > 0 || raw.credentials !== undefined;
@@ -32,10 +35,13 @@ function checkResumeModel(doc, sessionId, model) {
 }
 async function openNative(resolved, ctx) {
     const raw = resolved.raw;
-    if (ctx.resume !== undefined)
+    if (ctx.resume !== undefined && raw.carryHistoryAcrossModels !== true)
         checkResumeModel(ctx.resume.doc, ctx.sessionId, raw.model);
     const { bashApproval, allowUnsandboxed } = nativeProfileRules(ctx.profile, raw);
-    const protectedPaths = { ...defaultProtectedPaths(raw.credentials !== undefined), ...raw.hostPorts?.protectedPaths };
+    const protectedPaths = {
+        ...defaultProtectedPaths(raw.credentials !== undefined),
+        ...raw.hostPorts?.protectedPaths,
+    };
     const launcher = await resolveSessionLauncher({
         profile: ctx.profile,
         root: ctx.workdir,
@@ -68,6 +74,8 @@ async function openNative(resolved, ctx) {
     const handle = await adapter.openSession(ctx.sessionId, {
         agentName: NATIVE_AGENT,
         workdir: ctx.workdir,
+        instructionProtectedPaths: protectedPaths,
+        instructionFileName: raw.instructionFileName,
         resolvedPermissions: { mode: "default", toolGrants: grants, bashApproval },
         modelDef: { provider: resolved.provider, model: raw.model },
         timeoutSeconds: ctx.turnTimeoutSeconds,
@@ -76,6 +84,7 @@ async function openNative(resolved, ctx) {
         resume: ctx.resume !== undefined,
         spinBreaker: DEFAULT_SPIN_BREAKER_SETTINGS,
         transportRetry: SESSION_TRANSPORT_RETRY,
+        ...(raw.carryHistoryAcrossModels === true ? { carryHistoryAcrossModels: true } : {}),
         ...(ctx.instructions !== undefined && ctx.instructions !== "" ? { systemPrompt: ctx.instructions } : {}),
     });
     const codingTools = [...support.tools, ...ctx.tools.map(embedderToolDescriptor)];
@@ -102,5 +111,8 @@ async function openNative(resolved, ctx) {
 }
 export function nativeBackend(options) {
     const resolved = parseNativeBackendOptions(options);
-    return { kind: NATIVE_BACKEND_KIND, open: (ctx) => openNative(resolved, ctx) };
+    return {
+        kind: NATIVE_BACKEND_KIND,
+        open: (ctx) => openNative(resolved, ctx),
+    };
 }

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

@@ -41,6 +41,7 @@ export function createSessionAskPort(deps) {
                 summary: req.summary,
                 reason: req.reason,
                 expiresAt: now(),
+                answerable: false,
             });
             deps.emit({ type: "approval_resolved", requestId, decision, decidedBy: "profile" });
         },
@@ -58,7 +59,7 @@ export function createSessionAskPort(deps) {
             if (deps.turn() === undefined)
                 return;
             const { requestId } = deps.table.issue("question", ALREADY_ABORTED);
-            deps.emit({ type: "question", requestId, text, expiresAt: now() });
+            deps.emit({ type: "question", requestId, text, expiresAt: now(), answerable: false });
         },
     };
 }