@superdoc/sdk 2.13.0-next.9 → 2.13.1-next.1

package/dist/index.cjs

@@ -10,6 +10,7 @@ var skills = require('./skills.cjs');
 var tools = require('./tools.cjs');
 var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
 var v2PresetCompat = require('./agent/v2-preset-compat.cjs');
+var actions = require('./agent/actions.cjs');
 var define = require('./actions/define.cjs');
 var presets = require('./presets.cjs');
 
@@ -216,6 +217,7 @@ exports.getToolCatalog = tools.getToolCatalog;
 exports.listTools = tools.listTools;
 exports.dispatchIntentTool = intentDispatch_generated.dispatchIntentTool;
 exports.wrapV2PresetCompat = v2PresetCompat.wrapV2PresetCompat;
+exports.getActionDispositions = actions.getActionDispositions;
 exports.defineAction = define.defineAction;
 exports.DEFAULT_PRESET = presets.DEFAULT_PRESET;
 exports.getPreset = presets.getPreset;

package/dist/index.d.ts

@@ -93,7 +93,8 @@ export type { AnthropicSystemPrompt, CacheStrategy, SystemPromptForProviderResul
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { wrapV2PresetCompat } from './agent/v2-preset-compat.js';
 export type { BoundDocApi } from './generated/client.js';
-export type { ActionName } from './agent/actions.js';
+export type { ActionName, ActionDisposition } from './agent/actions.js';
+export { getActionDispositions } from './agent/actions.js';
 export type { AgentReceipt, AgentApplyArgs, AgentVerifyArgs, AgentInspectResult } from './agent/runtime.js';
 export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDescriptor } from './presets.js';
 export { createAgentToolkit } from './tools.js';

package/dist/index.js

@@ -196,6 +196,7 @@ export { getSkill, installSkill, listSkills } from './skills.js';
 export { chooseTools, dispatchSuperDocTool, getMcpPrompt, getSystemPrompt, getSystemPromptForProvider, getToolCatalog, listTools, DEFAULT_PRESET, getPreset, listPresets, registerPreset, unregisterPreset, } from './tools.js';
 export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { wrapV2PresetCompat } from './agent/v2-preset-compat.js';
+export { getActionDispositions } from './agent/actions.js';
 export { createAgentToolkit } from './tools.js';
 // Custom-action authoring kit: `defineAction` builds an ActionSpec (steps or
 // run tier); hand the specs to `createAgentToolkit({ actions })`.

package/dist/presets/core.cjs

@@ -370,8 +370,15 @@ function applyCacheMarkers(tools, provider, cacheRequested) {
 // ---------------------------------------------------------------------------
 // PresetDescriptor surface
 // ---------------------------------------------------------------------------
+function policyOptionsOf(options) {
+    return {
+        excludeActions: options?.excludeActions,
+        enforceChangeMode: options?.enforceChangeMode,
+        allowDirectActions: options?.allowDirectActions,
+    };
+}
 async function coreGetTools(provider, options) {
-    const tools = catalog.listAgentTools(provider, { excludeActions: options?.excludeActions });
+    const tools = catalog.listAgentTools(provider, policyOptionsOf(options));
     return applyCacheMarkers(tools, provider, options?.cache === true);
 }
 async function coreGetCatalog() {
@@ -389,6 +396,7 @@ async function coreGetCatalog() {
         generatedAt: null,
         toolCount: tools.length,
         tools,
+        dispositions: { ...actions.ACTION_DISPOSITIONS },
     };
 }
 /**
@@ -467,7 +475,7 @@ function stripExcludedActionLines(prompt, excludedActions) {
         .join('\n');
 }
 async function coreGetSystemPrompt(options) {
-    const { excludedActions } = catalog.validateExclusions({ excludeActions: options?.excludeActions });
+    const { excludedActions } = catalog.resolveActionPolicy(policyOptionsOf(options));
     // The core preset is ACTIONS-ONLY: superdoc_execute_code is WIP and not
     // advertised, and the prompt documents only the action surface (this exact
     // prompt is what the eval suite validates). Code-execution guidance will be
@@ -483,6 +491,17 @@ async function coreGetMcpPrompt() {
     }
     return _mcpPromptCache;
 }
+/**
+ * Dispatchable-but-unadvertised tools that route around the action layer and
+ * therefore around the tracked-changes policy. Refused outright while
+ * enforcement is on; a tracked-aware agent_apply may lift this later.
+ */
+const ENFORCEMENT_SIDE_DOORS = new Set([
+    'agent_apply',
+    'agent_operation',
+    'superdoc_execute_code',
+]);
+const POLICY_OPTION_KEYS = ['excludeActions', 'enforceChangeMode', 'allowDirectActions'];
 async function coreDispatch(documentHandle, toolName, args, invokeOptions) {
     if (!isRecord(args)) {
         throw new errors.SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
@@ -497,26 +516,69 @@ async function coreDispatch(documentHandle, toolName, args, invokeOptions) {
             details: { toolName },
         });
     }
-    // Defense-in-depth for exclusion configs: a host that narrowed the advertised
-    // surface (getTools excludeActions) can pass the same list here so a
-    // guessed/injected call to an excluded action is refused, not run.
-    const exclusionOptions = invokeOptions;
-    if (toolName === 'superdoc_perform_action' &&
-        typeof sanitizedArgs.action === 'string' &&
-        exclusionOptions?.excludeActions?.includes(sanitizedArgs.action)) {
-        throw new errors.SuperDocCliError(`Action ${sanitizedArgs.action} is excluded by configuration.`, {
+    // Defense-in-depth for narrowed surfaces: a host that narrowed the advertised
+    // tools (excludeActions / enforceChangeMode) passes the same options here so
+    // a guessed or injected call to a hidden action is refused, not run.
+    const policyOptions = invokeOptions;
+    // Unknown names are tolerated here: a preset that extends core (custom
+    // actions) forwards one merged exclusion list, and its own action names are
+    // not core's to validate. getTools/getSystemPrompt still validate.
+    const policy = catalog.resolveActionPolicy(policyOptionsOf(policyOptions), { ignoreUnknownActions: true });
+    const enforcing = policy.enforceChangeMode === 'tracked';
+    if (enforcing && ENFORCEMENT_SIDE_DOORS.has(toolName)) {
+        throw new errors.SuperDocCliError(`${toolName} bypasses the tracked-changes policy and is refused under enforceChangeMode: "tracked".`, {
             code: 'INVALID_ARGUMENT',
-            details: { toolName, action: sanitizedArgs.action, excluded: true },
+            details: { toolName, reason: 'enforce-change-mode' },
         });
     }
+    let dispatchArgs = sanitizedArgs;
+    let changeModeForced = false;
+    if (toolName === 'superdoc_perform_action' && typeof sanitizedArgs.action === 'string') {
+        const action = sanitizedArgs.action;
+        if (policy.configuredExclusions.has(action)) {
+            throw new errors.SuperDocCliError(`Action ${action} is excluded by configuration.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { toolName, action, excluded: true, reason: 'excluded' },
+            });
+        }
+        if (policy.directOnlyExclusions.has(action)) {
+            throw new errors.SuperDocCliError(`Action ${action} edits the document directly and is refused under enforceChangeMode: "tracked". Pass it in allowDirectActions to permit it.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { toolName, action, excluded: true, reason: 'direct-only' },
+            });
+        }
+        if (enforcing && actions.isActionName(action)) {
+            if (actions.ACTION_DISPOSITIONS[action] === 'tracked') {
+                // Omitted or explicit "direct" both upgrade: the policy decides the
+                // mode, the model only picks the verb.
+                changeModeForced = sanitizedArgs.changeMode !== 'tracked';
+                dispatchArgs = { ...sanitizedArgs, changeMode: 'tracked' };
+            }
+            else {
+                // An allowlisted direct-only action runs direct by definition. A stray
+                // changeMode:"tracked" from the model would make move_range fail (it
+                // refuses tracked) and the receipt lie, so normalize it away.
+                changeModeForced = sanitizedArgs.changeMode === 'tracked';
+                const { changeMode: _requested, ...rest } = sanitizedArgs;
+                dispatchArgs = rest;
+            }
+        }
+    }
     let forwardOptions = invokeOptions;
-    if (exclusionOptions && 'excludeActions' in exclusionOptions) {
-        const { excludeActions: _ea, ...rest } = exclusionOptions;
+    if (policyOptions && POLICY_OPTION_KEYS.some((key) => key in policyOptions)) {
+        const { excludeActions: _ea, enforceChangeMode: _ecm, allowDirectActions: _ada, ...rest } = policyOptions;
         forwardOptions = rest;
     }
     if (catalog.isAgentToolName(toolName)) {
-        validateAgentToolArgs(toolName, sanitizedArgs);
-        return dispatchAgentTool(documentHandle, toolName, sanitizedArgs, forwardOptions);
+        validateAgentToolArgs(toolName, dispatchArgs);
+        const result = await dispatchAgentTool(documentHandle, toolName, dispatchArgs, forwardOptions);
+        if (enforcing && toolName === 'superdoc_perform_action' && isRecord(result)) {
+            // Receipts under enforcement state the mode that actually ran, so a host
+            // can audit "was this edit tracked?" without re-deriving the policy.
+            const changeMode = dispatchArgs.changeMode === 'tracked' ? 'tracked' : 'direct';
+            return { ...result, changeMode, changeModeForced };
+        }
+        return result;
     }
     throw new errors.SuperDocCliError(`Unknown tool: ${toolName}`, {
         code: 'TOOL_DISPATCH_NOT_FOUND',

package/dist/presets/core.js

@@ -18,9 +18,9 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { SuperDocCliError } from '../runtime/errors.js';
 import { writeSdkDebugTrace } from '../runtime/debug-trace.js';
-import { AGENT_TOOL_DEFINITIONS, isAgentToolName, listAgentTools, validateExclusions, PUBLIC_AGENT_TOOL_NAMES, } from '../agent/catalog.js';
+import { AGENT_TOOL_DEFINITIONS, isAgentToolName, listAgentTools, resolveActionPolicy, PUBLIC_AGENT_TOOL_NAMES, } from '../agent/catalog.js';
 import { agentApply, agentInspect, agentOperation, agentVerify } from '../agent/runtime.js';
-import { superdocPerformAction } from '../agent/actions.js';
+import { ACTION_DISPOSITIONS, isActionName, superdocPerformAction } from '../agent/actions.js';
 import { EMBEDDED_PROMPTS } from '../embedded-prompts.generated.js';
 // Prompts ship as <dist>/prompts/*.md. Resolve relative to the compiled
 // module, but the module's depth differs by build: in the SDK package this
@@ -366,8 +366,15 @@ function applyCacheMarkers(tools, provider, cacheRequested) {
 // ---------------------------------------------------------------------------
 // PresetDescriptor surface
 // ---------------------------------------------------------------------------
+function policyOptionsOf(options) {
+    return {
+        excludeActions: options?.excludeActions,
+        enforceChangeMode: options?.enforceChangeMode,
+        allowDirectActions: options?.allowDirectActions,
+    };
+}
 async function coreGetTools(provider, options) {
-    const tools = listAgentTools(provider, { excludeActions: options?.excludeActions });
+    const tools = listAgentTools(provider, policyOptionsOf(options));
     return applyCacheMarkers(tools, provider, options?.cache === true);
 }
 async function coreGetCatalog() {
@@ -385,6 +392,7 @@ async function coreGetCatalog() {
         generatedAt: null,
         toolCount: tools.length,
         tools,
+        dispositions: { ...ACTION_DISPOSITIONS },
     };
 }
 /**
@@ -463,7 +471,7 @@ function stripExcludedActionLines(prompt, excludedActions) {
         .join('\n');
 }
 async function coreGetSystemPrompt(options) {
-    const { excludedActions } = validateExclusions({ excludeActions: options?.excludeActions });
+    const { excludedActions } = resolveActionPolicy(policyOptionsOf(options));
     // The core preset is ACTIONS-ONLY: superdoc_execute_code is WIP and not
     // advertised, and the prompt documents only the action surface (this exact
     // prompt is what the eval suite validates). Code-execution guidance will be
@@ -479,6 +487,17 @@ async function coreGetMcpPrompt() {
     }
     return _mcpPromptCache;
 }
+/**
+ * Dispatchable-but-unadvertised tools that route around the action layer and
+ * therefore around the tracked-changes policy. Refused outright while
+ * enforcement is on; a tracked-aware agent_apply may lift this later.
+ */
+const ENFORCEMENT_SIDE_DOORS = new Set([
+    'agent_apply',
+    'agent_operation',
+    'superdoc_execute_code',
+]);
+const POLICY_OPTION_KEYS = ['excludeActions', 'enforceChangeMode', 'allowDirectActions'];
 async function coreDispatch(documentHandle, toolName, args, invokeOptions) {
     if (!isRecord(args)) {
         throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
@@ -493,26 +512,69 @@ async function coreDispatch(documentHandle, toolName, args, invokeOptions) {
             details: { toolName },
         });
     }
-    // Defense-in-depth for exclusion configs: a host that narrowed the advertised
-    // surface (getTools excludeActions) can pass the same list here so a
-    // guessed/injected call to an excluded action is refused, not run.
-    const exclusionOptions = invokeOptions;
-    if (toolName === 'superdoc_perform_action' &&
-        typeof sanitizedArgs.action === 'string' &&
-        exclusionOptions?.excludeActions?.includes(sanitizedArgs.action)) {
-        throw new SuperDocCliError(`Action ${sanitizedArgs.action} is excluded by configuration.`, {
+    // Defense-in-depth for narrowed surfaces: a host that narrowed the advertised
+    // tools (excludeActions / enforceChangeMode) passes the same options here so
+    // a guessed or injected call to a hidden action is refused, not run.
+    const policyOptions = invokeOptions;
+    // Unknown names are tolerated here: a preset that extends core (custom
+    // actions) forwards one merged exclusion list, and its own action names are
+    // not core's to validate. getTools/getSystemPrompt still validate.
+    const policy = resolveActionPolicy(policyOptionsOf(policyOptions), { ignoreUnknownActions: true });
+    const enforcing = policy.enforceChangeMode === 'tracked';
+    if (enforcing && ENFORCEMENT_SIDE_DOORS.has(toolName)) {
+        throw new SuperDocCliError(`${toolName} bypasses the tracked-changes policy and is refused under enforceChangeMode: "tracked".`, {
             code: 'INVALID_ARGUMENT',
-            details: { toolName, action: sanitizedArgs.action, excluded: true },
+            details: { toolName, reason: 'enforce-change-mode' },
         });
     }
+    let dispatchArgs = sanitizedArgs;
+    let changeModeForced = false;
+    if (toolName === 'superdoc_perform_action' && typeof sanitizedArgs.action === 'string') {
+        const action = sanitizedArgs.action;
+        if (policy.configuredExclusions.has(action)) {
+            throw new SuperDocCliError(`Action ${action} is excluded by configuration.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { toolName, action, excluded: true, reason: 'excluded' },
+            });
+        }
+        if (policy.directOnlyExclusions.has(action)) {
+            throw new SuperDocCliError(`Action ${action} edits the document directly and is refused under enforceChangeMode: "tracked". Pass it in allowDirectActions to permit it.`, {
+                code: 'INVALID_ARGUMENT',
+                details: { toolName, action, excluded: true, reason: 'direct-only' },
+            });
+        }
+        if (enforcing && isActionName(action)) {
+            if (ACTION_DISPOSITIONS[action] === 'tracked') {
+                // Omitted or explicit "direct" both upgrade: the policy decides the
+                // mode, the model only picks the verb.
+                changeModeForced = sanitizedArgs.changeMode !== 'tracked';
+                dispatchArgs = { ...sanitizedArgs, changeMode: 'tracked' };
+            }
+            else {
+                // An allowlisted direct-only action runs direct by definition. A stray
+                // changeMode:"tracked" from the model would make move_range fail (it
+                // refuses tracked) and the receipt lie, so normalize it away.
+                changeModeForced = sanitizedArgs.changeMode === 'tracked';
+                const { changeMode: _requested, ...rest } = sanitizedArgs;
+                dispatchArgs = rest;
+            }
+        }
+    }
     let forwardOptions = invokeOptions;
-    if (exclusionOptions && 'excludeActions' in exclusionOptions) {
-        const { excludeActions: _ea, ...rest } = exclusionOptions;
+    if (policyOptions && POLICY_OPTION_KEYS.some((key) => key in policyOptions)) {
+        const { excludeActions: _ea, enforceChangeMode: _ecm, allowDirectActions: _ada, ...rest } = policyOptions;
         forwardOptions = rest;
     }
     if (isAgentToolName(toolName)) {
-        validateAgentToolArgs(toolName, sanitizedArgs);
-        return dispatchAgentTool(documentHandle, toolName, sanitizedArgs, forwardOptions);
+        validateAgentToolArgs(toolName, dispatchArgs);
+        const result = await dispatchAgentTool(documentHandle, toolName, dispatchArgs, forwardOptions);
+        if (enforcing && toolName === 'superdoc_perform_action' && isRecord(result)) {
+            // Receipts under enforcement state the mode that actually ran, so a host
+            // can audit "was this edit tracked?" without re-deriving the policy.
+            const changeMode = dispatchArgs.changeMode === 'tracked' ? 'tracked' : 'direct';
+            return { ...result, changeMode, changeModeForced };
+        }
+        return result;
     }
     throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
         code: 'TOOL_DISPATCH_NOT_FOUND',

package/dist/presets.d.ts

@@ -72,6 +72,12 @@ export type ToolCatalog = {
     generatedAt: string | null;
     toolCount: number;
     tools: ToolCatalogEntry[];
+    /**
+     * Per-action `changeMode` disposition (core preset only): `tracked` actions
+     * honor `changeMode: "tracked"`; `direct` actions always edit directly and
+     * are hidden under `enforceChangeMode` unless allowlisted.
+     */
+    dispositions?: Record<string, 'tracked' | 'direct'>;
 };
 export interface GetToolsOptions {
     /**
@@ -87,6 +93,19 @@ export interface GetToolsOptions {
      * ignore this option.
      */
     excludeActions?: readonly string[];
+    /**
+     * Tracked-changes-only policy (core preset). `'tracked'` removes every
+     * direct-only action from the surface (unless allowlisted) exactly like
+     * `excludeActions`; dispatch then upgrades tracked-capable actions to
+     * `changeMode: "tracked"`. Only `'tracked'` is accepted.
+     */
+    enforceChangeMode?: 'tracked';
+    /**
+     * Direct-only actions to keep callable under `enforceChangeMode` (`['*']` =
+     * all of them). Requires `enforceChangeMode`; unknown names throw;
+     * tracked-capable names are ignored.
+     */
+    allowDirectActions?: readonly string[];
 }
 /**
  * Options for {@link PresetDescriptor.getSystemPrompt}. Mirrors the exclusion
@@ -97,6 +116,10 @@ export interface GetToolsOptions {
 export interface GetSystemPromptOptions {
     /** Drop the per-action documentation lines for these actions (core preset). */
     excludeActions?: readonly string[];
+    /** Same policy as {@link GetToolsOptions.enforceChangeMode}: direct-only actions leave the prompt too. */
+    enforceChangeMode?: 'tracked';
+    /** Same allowlist as {@link GetToolsOptions.allowDirectActions}. */
+    allowDirectActions?: readonly string[];
 }
 export interface GetToolsResult {
     tools: unknown[];

package/dist/runtime/host.cjs

@@ -1,7 +1,6 @@
 'use strict';
 
 var node_child_process = require('node:child_process');
-var node_readline = require('node:readline');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
 var documentEvidence = require('./document-evidence.cjs');
@@ -96,7 +95,8 @@ class HostTransport {
     user;
     documentRpcEnabled;
     child = null;
-    stdoutReader = null;
+    stdoutBuffer = '';
+    stdoutDataListener = null;
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
@@ -418,14 +418,12 @@ class HostTransport {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.child = child;
-        const stdoutReader = node_readline.createInterface({
-            input: child.stdout,
-            crlfDelay: Number.POSITIVE_INFINITY,
-        });
-        this.stdoutReader = stdoutReader;
-        stdoutReader.on('line', (line) => {
-            this.onStdoutLine(line);
-        });
+        // JSON-RPC is framed by ASCII LF; Node 24 readline also splits on a raw
+        // U+2028 inside otherwise valid JSON string data.
+        child.stdout.setEncoding('utf8');
+        const stdoutDataListener = (chunk) => this.onStdoutChunk(chunk);
+        this.stdoutDataListener = stdoutDataListener;
+        child.stdout.on('data', stdoutDataListener);
         child.stderr.on('data', (chunk) => {
             if (!FORWARD_HOST_STDERR) {
                 return;
@@ -672,6 +670,18 @@ class HostTransport {
         }
         pending.resolve(record.result);
     }
+    onStdoutChunk(chunk) {
+        this.stdoutBuffer += chunk;
+        let newlineIndex = this.stdoutBuffer.indexOf('\n');
+        while (newlineIndex !== -1) {
+            let line = this.stdoutBuffer.slice(0, newlineIndex);
+            this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+            if (line.endsWith('\r'))
+                line = line.slice(0, -1);
+            this.onStdoutLine(line);
+            newlineIndex = this.stdoutBuffer.indexOf('\n');
+        }
+    }
     mapJsonRpcError(rawError) {
         if (typeof rawError !== 'object' || rawError == null || Array.isArray(rawError)) {
             return new errors.SuperDocCliError('Host returned an unknown JSON-RPC error.', {
@@ -730,15 +740,14 @@ class HostTransport {
         this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
+            if (this.stdoutDataListener)
+                child.stdout.off('data', this.stdoutDataListener);
             child.removeAllListeners();
             child.kill('SIGKILL');
         }
         this.child = null;
-        if (this.stdoutReader) {
-            this.stdoutReader.removeAllListeners();
-            this.stdoutReader.close();
-            this.stdoutReader = null;
-        }
+        this.stdoutBuffer = '';
+        this.stdoutDataListener = null;
         const pendingEntries = Array.from(this.pending.values());
         this.pending.clear();
         const rejection = error ??

package/dist/runtime/host.d.ts

@@ -43,7 +43,8 @@ export declare class HostTransport {
     private readonly user?;
     private readonly documentRpcEnabled;
     private child;
-    private stdoutReader;
+    private stdoutBuffer;
+    private stdoutDataListener;
     private readonly pending;
     private nextRequestId;
     private connecting;
@@ -82,6 +83,7 @@ export declare class HostTransport {
     private reconcileIndeterminateDiscardCloses;
     private sendJsonRpcRequest;
     private onStdoutLine;
+    private onStdoutChunk;
     private mapJsonRpcError;
     private handleDisconnect;
     private cleanupProcess;

package/dist/runtime/host.js

@@ -1,5 +1,4 @@
 import { spawn } from 'node:child_process';
-import { createInterface } from 'node:readline';
 import { buildOperationArgv, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
 import { registerMutationRevision } from './document-evidence.js';
@@ -93,7 +92,8 @@ export class HostTransport {
     user;
     documentRpcEnabled;
     child = null;
-    stdoutReader = null;
+    stdoutBuffer = '';
+    stdoutDataListener = null;
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
@@ -415,14 +415,12 @@ export class HostTransport {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         this.child = child;
-        const stdoutReader = createInterface({
-            input: child.stdout,
-            crlfDelay: Number.POSITIVE_INFINITY,
-        });
-        this.stdoutReader = stdoutReader;
-        stdoutReader.on('line', (line) => {
-            this.onStdoutLine(line);
-        });
+        // JSON-RPC is framed by ASCII LF; Node 24 readline also splits on a raw
+        // U+2028 inside otherwise valid JSON string data.
+        child.stdout.setEncoding('utf8');
+        const stdoutDataListener = (chunk) => this.onStdoutChunk(chunk);
+        this.stdoutDataListener = stdoutDataListener;
+        child.stdout.on('data', stdoutDataListener);
         child.stderr.on('data', (chunk) => {
             if (!FORWARD_HOST_STDERR) {
                 return;
@@ -669,6 +667,18 @@ export class HostTransport {
         }
         pending.resolve(record.result);
     }
+    onStdoutChunk(chunk) {
+        this.stdoutBuffer += chunk;
+        let newlineIndex = this.stdoutBuffer.indexOf('\n');
+        while (newlineIndex !== -1) {
+            let line = this.stdoutBuffer.slice(0, newlineIndex);
+            this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+            if (line.endsWith('\r'))
+                line = line.slice(0, -1);
+            this.onStdoutLine(line);
+            newlineIndex = this.stdoutBuffer.indexOf('\n');
+        }
+    }
     mapJsonRpcError(rawError) {
         if (typeof rawError !== 'object' || rawError == null || Array.isArray(rawError)) {
             return new SuperDocCliError('Host returned an unknown JSON-RPC error.', {
@@ -727,15 +737,14 @@ export class HostTransport {
         this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
+            if (this.stdoutDataListener)
+                child.stdout.off('data', this.stdoutDataListener);
             child.removeAllListeners();
             child.kill('SIGKILL');
         }
         this.child = null;
-        if (this.stdoutReader) {
-            this.stdoutReader.removeAllListeners();
-            this.stdoutReader.close();
-            this.stdoutReader = null;
-        }
+        this.stdoutBuffer = '';
+        this.stdoutDataListener = null;
         const pendingEntries = Array.from(this.pending.values());
         this.pending.clear();
         const rejection = error ??

package/dist/runtime/sdk-version.generated.cjs

@@ -3,6 +3,6 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-const SDK_VERSION = '2.13.0-next.9';
+const SDK_VERSION = '2.13.1-next.1';
 
 exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.13.0-next.9";
+export declare const SDK_VERSION = "2.13.1-next.1";

package/dist/runtime/sdk-version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
 // Source of truth: package.json. Regenerated on every SDK build so the
 // SDK retains its own version identity when bundled into another package.
-export const SDK_VERSION = '2.13.0-next.9';
+export const SDK_VERSION = '2.13.1-next.1';

package/dist/tools.cjs

@@ -34,6 +34,8 @@ async function chooseTools(input) {
     const { tools, cacheStrategy } = await preset.getTools(input.provider, {
         cache: input.cache === true,
         excludeActions: input.excludeActions,
+        enforceChangeMode: input.enforceChangeMode,
+        allowDirectActions: input.allowDirectActions,
     });
     return {
         tools,
@@ -102,16 +104,25 @@ const CUSTOM_TOOLKIT_PRESET_ID = 'custom_superdoc_preset';
 const TOOL_PROVIDERS = new Set(['openai', 'anthropic', 'vercel', 'generic']);
 /**
  * One-call agent surface: tools, system prompt, and a pre-bound dispatcher
- * that are coherent BY CONSTRUCTION — the same preset and `excludeActions`
- * apply to all three, so an action can never linger in the prompt after
- * being excluded from the tool array (or vice versa).
+ * that are coherent BY CONSTRUCTION — the same preset, `excludeActions`,
+ * `enforceChangeMode`, and `allowDirectActions` apply to all three, so an
+ * action can never linger in the prompt after being excluded from the tool
+ * array (or vice versa).
  *
  * The legacy preset ignores exclusion options everywhere (it has no action
  * surface); passing `excludeActions` with `preset: 'legacy'` is a no-op,
  * matching the standalone functions.
  */
 async function createAgentToolkit(input) {
-    const excludeActions = input.excludeActions ? [...input.excludeActions] : undefined;
+    // Copy the lists so later caller mutation cannot desync dispatch from the
+    // tools and prompt that were generated here.
+    const policy = {
+        ...(input.excludeActions ? { excludeActions: [...input.excludeActions] } : {}),
+        ...(input.enforceChangeMode !== undefined ? { enforceChangeMode: input.enforceChangeMode } : {}),
+        ...(input.allowDirectActions ? { allowDirectActions: [...input.allowDirectActions] } : {}),
+    };
+    const hasPolicy = Object.keys(policy).length > 0;
+    const excludeActions = policy.excludeActions;
     // One-call custom-actions path: define your actions, hand them here as
     // `customActions`, use the
     // returned toolkit. We build an ephemeral extended/composed preset over
@@ -122,6 +133,16 @@ async function createAgentToolkit(input) {
     // otherwise `{ base: 'core', customActions: [] }` would silently fall through to
     // the default (legacy) preset, a different tool family than the one named.
     if ((input.customActions && input.customActions.length > 0) || input.includeActions != null || input.base != null) {
+        // A custom action runs its own step list through runCustomAction, which
+        // never passes the core dispatch guard, so the tracked-only policy cannot
+        // cover it. Enforcing built-ins while custom actions edit directly would be
+        // a policy that silently does not hold — refuse the combination instead.
+        if (input.enforceChangeMode !== undefined) {
+            throw new errors.SuperDocCliError('enforceChangeMode is not supported together with custom actions; a custom action bypasses the tracked-changes guard.', {
+                code: 'INVALID_ARGUMENT',
+                details: { enforceChangeMode: input.enforceChangeMode, reason: 'custom-actions-unsupported' },
+            });
+        }
         // This path builds tools directly (no chooseTools), so it must validate
         // the provider itself; an unknown value would otherwise yield a silently
         // mixed-dialect tool list. Mirrors the Python `create_agent_toolkit` guard.
@@ -156,12 +177,12 @@ async function createAgentToolkit(input) {
         };
     }
     const presetId = input.preset ?? presets.DEFAULT_PRESET;
-    const { tools, meta } = await chooseTools({ ...input, preset: presetId, excludeActions });
-    const systemPrompt = await getSystemPrompt(presetId, excludeActions ? { excludeActions } : undefined);
+    const { tools, meta } = await chooseTools({ ...input, preset: presetId, ...policy });
+    const systemPrompt = await getSystemPrompt(presetId, hasPolicy ? policy : undefined);
     const dispatch = (documentHandle, toolName, args = {}, invokeOptions) => dispatchSuperDocTool(documentHandle, toolName, args, {
         ...invokeOptions,
         preset: presetId,
-        ...(excludeActions ? { excludeActions } : {}),
+        ...policy,
     });
     return { tools, meta, systemPrompt, dispatch };
 }
@@ -202,7 +223,12 @@ async function getMcpPrompt(preset) {
  * ```
  */
 async function getSystemPromptForProvider(input) {
-    const text = await getSystemPrompt(input.preset, input.excludeActions ? { excludeActions: input.excludeActions } : undefined);
+    const promptOptions = {
+        ...(input.excludeActions ? { excludeActions: input.excludeActions } : {}),
+        ...(input.enforceChangeMode !== undefined ? { enforceChangeMode: input.enforceChangeMode } : {}),
+        ...(input.allowDirectActions ? { allowDirectActions: input.allowDirectActions } : {}),
+    };
+    const text = await getSystemPrompt(input.preset, Object.keys(promptOptions).length > 0 ? promptOptions : undefined);
     const cacheRequested = input.cache === true;
     if (input.provider === 'anthropic') {
         const block = { type: 'text', text };