@superdoc/sdk 2.13.0-next.9 → 2.13.0

package/dist/agent/actions.cjs

@@ -226,6 +226,53 @@ const ACTION_ARGS = {
     insert_page_break: ['selector'],
     add_hyperlink: ['text', 'url', 'tooltip'],
 };
+const ACTION_DISPOSITIONS = {
+    insert_paragraphs: 'tracked',
+    insert_heading: 'tracked',
+    replace_text: 'tracked',
+    delete_text: 'tracked',
+    delete_blocks: 'tracked',
+    append_list: 'tracked',
+    create_table: 'tracked',
+    comment_paragraphs: 'direct',
+    add_comments: 'direct',
+    resolve_comments: 'direct',
+    reply_to_comment: 'direct',
+    rewrite_block: 'tracked',
+    accept_tracked_changes: 'direct',
+    reject_tracked_changes: 'direct',
+    normalize_body_font_size: 'tracked',
+    set_font_family: 'tracked',
+    apply_letter_spacing: 'tracked',
+    fill_placeholders: 'tracked',
+    move_range: 'direct',
+    insert_toc: 'tracked',
+    insert_table_row: 'tracked',
+    insert_table_column: 'tracked',
+    delete_table_row: 'tracked',
+    delete_table_column: 'tracked',
+    split_table: 'tracked',
+    convert_list: 'tracked',
+    split_list: 'direct',
+    undo_changes: 'direct',
+    redo_changes: 'direct',
+    attach_numbering: 'tracked',
+    add_list_items: 'tracked',
+    format_text: 'tracked',
+    apply_style: 'direct',
+    format_paragraph: 'tracked',
+    move_text: 'tracked',
+    style_table: 'direct',
+    move_table: 'direct',
+    delete_table: 'tracked',
+    set_paragraph_spacing: 'direct',
+    insert_page_break: 'direct',
+    add_hyperlink: 'direct',
+};
+/** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
+function getActionDispositions() {
+    return { ...ACTION_DISPOSITIONS };
+}
 function isActionName(value) {
     return typeof value === 'string' && ACTION_NAMES.includes(value);
 }
@@ -641,8 +688,8 @@ function evaluateChecks(pre, post, checks) {
         else if (check.kind === 'tracked-change-count-delta') {
             results.push({
                 check,
-                passed: post.trackedChanges.length - pre.trackedChanges.length === check.delta,
-                detail: `pre=${pre.trackedChanges.length} post=${post.trackedChanges.length}`,
+                passed: post.counts.trackedChanges - pre.counts.trackedChanges === check.delta,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}`,
             });
         }
         else if (check.kind === 'revision-changed') {
@@ -1544,11 +1591,25 @@ async function runDeleteBlocks(doc, args) {
         const changeMode = parseChangeMode(args.changeMode);
         const executedOperations = [];
         const deleted = [];
+        const addressedTrackedChangeIds = new Set();
+        let allTrackedEffectsAddressed = true;
         for (const target of targets) {
             try {
                 const result = await deleteFn({ target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } }, changeMode ? { changeMode } : undefined);
                 executedOperations.push({ operationId: 'doc.blocks.delete', result: compactOpResult(result) });
                 deleted.push({ nodeId: target.nodeId, nodeType: target.nodeType });
+                if (changeMode === 'tracked') {
+                    // One block transaction can create multiple logical review entities
+                    // (for example, text plus its section break). Exact receipt refs let
+                    // us fail closed on missing entities. Older handles omit refs, and
+                    // adjacent deletions can coalesce into one review entity, so their
+                    // truthful fallback is the positive observed inventory delta rather
+                    // than one assumed entity per operation.
+                    const refIds = trackedChangeRefIds(result);
+                    allTrackedEffectsAddressed &&= refIds.size > 0;
+                    for (const entityId of refIds)
+                        addressedTrackedChangeIds.add(entityId);
+                }
             }
             catch (err) {
                 errors$1.push({
@@ -1562,14 +1623,37 @@ async function runDeleteBlocks(doc, args) {
         // Tracked deletions leave the block in place until the revision is decided,
         // so the block count cannot move — count the structural revisions instead.
         // Direct deletions must show one fewer block of each deleted node type.
+        const observedTrackedChangeDelta = post.counts.trackedChanges - pre.counts.trackedChanges;
+        // A later deletion can coalesce the batch and replace entity identities
+        // returned by earlier operation receipts. For a multi-operation batch the
+        // final inventory is therefore the authoritative count. A single operation
+        // keeps using its addressed refs so fan-out remains verifiable even when
+        // the inventory listing is capped.
+        const expectedTrackedChangeDelta = deleted.length > 1
+            ? observedTrackedChangeDelta
+            : allTrackedEffectsAddressed
+                ? addressedTrackedChangeIds.size
+                : Math.max(observedTrackedChangeDelta, addressedTrackedChangeIds.size);
         const checks = changeMode === 'tracked'
-            ? [{ kind: 'tracked-change-count-delta', delta: deleted.length }]
+            ? [
+                {
+                    kind: 'tracked-change-count-delta',
+                    delta: expectedTrackedChangeDelta,
+                },
+            ]
             : [...new Set(deleted.map((entry) => entry.nodeType))].map((nodeType) => ({
                 kind: 'block-count-delta',
                 nodeType,
                 delta: -deleted.filter((entry) => entry.nodeType === nodeType).length,
             }));
         const verification = evaluateChecks(pre, post, checks);
+        if (changeMode === 'tracked' && observedTrackedChangeDelta <= 0) {
+            verification[0] = {
+                ...verification[0],
+                passed: false,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}; no tracked review entity was created`,
+            };
+        }
         // Compare against the DEDUPED target list: two selectors naming the same
         // block are one deletion, and counting the raw selectors would report a
         // fully applied call as `partial` with no error to explain it. Selectors
@@ -4513,6 +4597,15 @@ function compactOpResult(result) {
         compact.stepCount = result.steps.length;
     return compact;
 }
+function trackedChangeRefIds(result) {
+    const refs = asRecord(result)?.trackedChangeRefs;
+    if (!Array.isArray(refs))
+        return new Set();
+    return new Set(refs.flatMap((entry) => {
+        const entityId = asString(asRecord(entry)?.entityId);
+        return entityId ? [entityId] : [];
+    }));
+}
 function parseScopedReplaceArgs(args, changeMode) {
     if (args.action !== 'replace_text')
         return null;
@@ -4817,10 +4910,24 @@ function leadInShapeOf(blockText, labelText, quote) {
         if (occurrence > 0)
             return { kind: 'inside', delimiter: inside, occurrence };
     }
+    // A single emphasised word followed by a space and plain prose: the token
+    // itself is the label ("WHEREAS the Party…"). Multi-word runs stay
+    // unrecognised — an emphasised opening clause is prose, not a label.
+    if (/^\S+\s$/.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText)) {
+        return { kind: 'word', label: labelText.trimEnd() };
+    }
     return null;
 }
 /** The span of `text` that carries the label look, or null when it has none. */
 function leadInSpanOf(text, shape) {
+    if (shape.kind === 'word') {
+        // Only the SAME token inherits the look — "WHEREAS the Parties…" does,
+        // "The Parties further agree…" does not (no guessing a label there).
+        const next = text.charAt(shape.label.length);
+        return text.startsWith(shape.label) && (next === '' || /\s/.test(next))
+            ? { start: 0, end: shape.label.length }
+            : null;
+    }
     if (shape.kind === 'quoted') {
         const opener = text.slice(0, 2).indexOf(shape.quote);
         if (opener < 0)
@@ -7303,8 +7410,10 @@ function parseSelector(value) {
 const ACTION_NAMES_LIST = ACTION_NAMES;
 
 exports.ACTION_ARGS = ACTION_ARGS;
+exports.ACTION_DISPOSITIONS = ACTION_DISPOSITIONS;
 exports.ACTION_GROUPS = ACTION_GROUPS;
 exports.ACTION_HINTS = ACTION_HINTS;
 exports.ACTION_NAMES_LIST = ACTION_NAMES_LIST;
+exports.getActionDispositions = getActionDispositions;
 exports.isActionName = isActionName;
 exports.superdocPerformAction = superdocPerformAction;

package/dist/agent/actions.d.ts

@@ -433,6 +433,25 @@ export declare const ACTION_GROUPS: ReadonlyArray<{
  * action at compile time.
  */
 export declare const ACTION_ARGS: Record<ActionName, readonly string[]>;
+/**
+ * What an action does with `changeMode`.
+ *
+ * - `tracked`: honors `changeMode: "tracked"` and records a reviewable tracked
+ *   change (a multi-step action may run a bookkeeping step directly on purpose —
+ *   insert_table_column fills the new cells directly so a column shows up as ONE
+ *   Word-style tracked change, not one per cell).
+ * - `direct`: edits the document directly whatever `changeMode` says. Either the
+ *   action never reads the argument (apply_style, insert_page_break, …), the
+ *   engine refuses the tracked form (move_range), or the action is a review /
+ *   comment operation that has no tracked form by nature.
+ *
+ * Source of truth for the tracked-only agent policy (`enforceChangeMode`):
+ * `direct` actions are hidden and refused unless a host allowlists them.
+ */
+export type ActionDisposition = 'tracked' | 'direct';
+export declare const ACTION_DISPOSITIONS: Record<ActionName, ActionDisposition>;
+/** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
+export declare function getActionDispositions(): Record<ActionName, ActionDisposition>;
 export declare function isActionName(value: unknown): value is ActionName;
 export type ResolveCommentsArgs = {
     action: 'resolve_comments';

package/dist/agent/actions.js

@@ -223,6 +223,53 @@ export const ACTION_ARGS = {
     insert_page_break: ['selector'],
     add_hyperlink: ['text', 'url', 'tooltip'],
 };
+export const ACTION_DISPOSITIONS = {
+    insert_paragraphs: 'tracked',
+    insert_heading: 'tracked',
+    replace_text: 'tracked',
+    delete_text: 'tracked',
+    delete_blocks: 'tracked',
+    append_list: 'tracked',
+    create_table: 'tracked',
+    comment_paragraphs: 'direct',
+    add_comments: 'direct',
+    resolve_comments: 'direct',
+    reply_to_comment: 'direct',
+    rewrite_block: 'tracked',
+    accept_tracked_changes: 'direct',
+    reject_tracked_changes: 'direct',
+    normalize_body_font_size: 'tracked',
+    set_font_family: 'tracked',
+    apply_letter_spacing: 'tracked',
+    fill_placeholders: 'tracked',
+    move_range: 'direct',
+    insert_toc: 'tracked',
+    insert_table_row: 'tracked',
+    insert_table_column: 'tracked',
+    delete_table_row: 'tracked',
+    delete_table_column: 'tracked',
+    split_table: 'tracked',
+    convert_list: 'tracked',
+    split_list: 'direct',
+    undo_changes: 'direct',
+    redo_changes: 'direct',
+    attach_numbering: 'tracked',
+    add_list_items: 'tracked',
+    format_text: 'tracked',
+    apply_style: 'direct',
+    format_paragraph: 'tracked',
+    move_text: 'tracked',
+    style_table: 'direct',
+    move_table: 'direct',
+    delete_table: 'tracked',
+    set_paragraph_spacing: 'direct',
+    insert_page_break: 'direct',
+    add_hyperlink: 'direct',
+};
+/** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
+export function getActionDispositions() {
+    return { ...ACTION_DISPOSITIONS };
+}
 export function isActionName(value) {
     return typeof value === 'string' && ACTION_NAMES.includes(value);
 }
@@ -638,8 +685,8 @@ function evaluateChecks(pre, post, checks) {
         else if (check.kind === 'tracked-change-count-delta') {
             results.push({
                 check,
-                passed: post.trackedChanges.length - pre.trackedChanges.length === check.delta,
-                detail: `pre=${pre.trackedChanges.length} post=${post.trackedChanges.length}`,
+                passed: post.counts.trackedChanges - pre.counts.trackedChanges === check.delta,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}`,
             });
         }
         else if (check.kind === 'revision-changed') {
@@ -1541,11 +1588,25 @@ async function runDeleteBlocks(doc, args) {
         const changeMode = parseChangeMode(args.changeMode);
         const executedOperations = [];
         const deleted = [];
+        const addressedTrackedChangeIds = new Set();
+        let allTrackedEffectsAddressed = true;
         for (const target of targets) {
             try {
                 const result = await deleteFn({ target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } }, changeMode ? { changeMode } : undefined);
                 executedOperations.push({ operationId: 'doc.blocks.delete', result: compactOpResult(result) });
                 deleted.push({ nodeId: target.nodeId, nodeType: target.nodeType });
+                if (changeMode === 'tracked') {
+                    // One block transaction can create multiple logical review entities
+                    // (for example, text plus its section break). Exact receipt refs let
+                    // us fail closed on missing entities. Older handles omit refs, and
+                    // adjacent deletions can coalesce into one review entity, so their
+                    // truthful fallback is the positive observed inventory delta rather
+                    // than one assumed entity per operation.
+                    const refIds = trackedChangeRefIds(result);
+                    allTrackedEffectsAddressed &&= refIds.size > 0;
+                    for (const entityId of refIds)
+                        addressedTrackedChangeIds.add(entityId);
+                }
             }
             catch (err) {
                 errors.push({
@@ -1559,14 +1620,37 @@ async function runDeleteBlocks(doc, args) {
         // Tracked deletions leave the block in place until the revision is decided,
         // so the block count cannot move — count the structural revisions instead.
         // Direct deletions must show one fewer block of each deleted node type.
+        const observedTrackedChangeDelta = post.counts.trackedChanges - pre.counts.trackedChanges;
+        // A later deletion can coalesce the batch and replace entity identities
+        // returned by earlier operation receipts. For a multi-operation batch the
+        // final inventory is therefore the authoritative count. A single operation
+        // keeps using its addressed refs so fan-out remains verifiable even when
+        // the inventory listing is capped.
+        const expectedTrackedChangeDelta = deleted.length > 1
+            ? observedTrackedChangeDelta
+            : allTrackedEffectsAddressed
+                ? addressedTrackedChangeIds.size
+                : Math.max(observedTrackedChangeDelta, addressedTrackedChangeIds.size);
         const checks = changeMode === 'tracked'
-            ? [{ kind: 'tracked-change-count-delta', delta: deleted.length }]
+            ? [
+                {
+                    kind: 'tracked-change-count-delta',
+                    delta: expectedTrackedChangeDelta,
+                },
+            ]
             : [...new Set(deleted.map((entry) => entry.nodeType))].map((nodeType) => ({
                 kind: 'block-count-delta',
                 nodeType,
                 delta: -deleted.filter((entry) => entry.nodeType === nodeType).length,
             }));
         const verification = evaluateChecks(pre, post, checks);
+        if (changeMode === 'tracked' && observedTrackedChangeDelta <= 0) {
+            verification[0] = {
+                ...verification[0],
+                passed: false,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}; no tracked review entity was created`,
+            };
+        }
         // Compare against the DEDUPED target list: two selectors naming the same
         // block are one deletion, and counting the raw selectors would report a
         // fully applied call as `partial` with no error to explain it. Selectors
@@ -4510,6 +4594,15 @@ function compactOpResult(result) {
         compact.stepCount = result.steps.length;
     return compact;
 }
+function trackedChangeRefIds(result) {
+    const refs = asRecord(result)?.trackedChangeRefs;
+    if (!Array.isArray(refs))
+        return new Set();
+    return new Set(refs.flatMap((entry) => {
+        const entityId = asString(asRecord(entry)?.entityId);
+        return entityId ? [entityId] : [];
+    }));
+}
 function parseScopedReplaceArgs(args, changeMode) {
     if (args.action !== 'replace_text')
         return null;
@@ -4814,10 +4907,24 @@ function leadInShapeOf(blockText, labelText, quote) {
         if (occurrence > 0)
             return { kind: 'inside', delimiter: inside, occurrence };
     }
+    // A single emphasised word followed by a space and plain prose: the token
+    // itself is the label ("WHEREAS the Party…"). Multi-word runs stay
+    // unrecognised — an emphasised opening clause is prose, not a label.
+    if (/^\S+\s$/.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText)) {
+        return { kind: 'word', label: labelText.trimEnd() };
+    }
     return null;
 }
 /** The span of `text` that carries the label look, or null when it has none. */
 function leadInSpanOf(text, shape) {
+    if (shape.kind === 'word') {
+        // Only the SAME token inherits the look — "WHEREAS the Parties…" does,
+        // "The Parties further agree…" does not (no guessing a label there).
+        const next = text.charAt(shape.label.length);
+        return text.startsWith(shape.label) && (next === '' || /\s/.test(next))
+            ? { start: 0, end: shape.label.length }
+            : null;
+    }
     if (shape.kind === 'quoted') {
         const opener = text.slice(0, 2).indexOf(shape.quote);
         if (opener < 0)

package/dist/agent/catalog.cjs

@@ -543,18 +543,61 @@ function toProviderTool(provider, definition) {
         return toVercelTool(definition);
     return toOpenAiTool(definition);
 }
-function validateExclusions(options) {
-    const excludedActions = new Set(options?.excludeActions ?? []);
-    const knownActions = new Set(actions.ACTION_NAMES_LIST);
-    for (const name of excludedActions) {
+/** Wildcard entry for `allowDirectActions`: keep every direct-only action callable. */
+const ALLOW_ALL_DIRECT_ACTIONS = '*';
+function assertKnownActions(option, names, knownActions) {
+    for (const name of names) {
         if (!knownActions.has(name)) {
-            throw new errors.SuperDocCliError(`excludeActions: unknown action "${name}".`, {
+            throw new errors.SuperDocCliError(`${option}: unknown action "${name}".`, {
                 code: 'INVALID_ARGUMENT',
                 details: { unknownAction: name, knownActions: [...knownActions] },
             });
         }
     }
-    return { excludedActions };
+}
+function resolveActionPolicy(options, resolveOptions) {
+    const knownActions = new Set(actions.ACTION_NAMES_LIST);
+    const ignoreUnknown = resolveOptions?.ignoreUnknownActions === true;
+    const configuredExclusions = new Set(options?.excludeActions ?? []);
+    if (!ignoreUnknown)
+        assertKnownActions('excludeActions', configuredExclusions, knownActions);
+    const enforceChangeMode = options?.enforceChangeMode;
+    if (enforceChangeMode !== undefined && enforceChangeMode !== 'tracked') {
+        throw new errors.SuperDocCliError(`enforceChangeMode: only "tracked" is supported; got ${JSON.stringify(enforceChangeMode)}.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { enforceChangeMode, supported: ['tracked'] },
+        });
+    }
+    if (options?.allowDirectActions !== undefined && enforceChangeMode === undefined) {
+        throw new errors.SuperDocCliError('allowDirectActions requires enforceChangeMode: "tracked"; without enforcement every action already runs as requested.', {
+            code: 'INVALID_ARGUMENT',
+            details: { allowDirectActions: [...options.allowDirectActions] },
+        });
+    }
+    // `'*'` is the "I accept every direct-only action" shortcut: tracked-capable
+    // actions are still forced tracked, the direct bucket just stays callable.
+    const requestedAllow = new Set(options?.allowDirectActions ?? []);
+    const allowAllDirect = requestedAllow.delete(ALLOW_ALL_DIRECT_ACTIONS);
+    if (!ignoreUnknown)
+        assertKnownActions('allowDirectActions', requestedAllow, knownActions);
+    const allowDirectActions = new Set((allowAllDirect ? [...actions.ACTION_NAMES_LIST] : [...requestedAllow]).filter((name) => actions.ACTION_DISPOSITIONS[name] === 'direct'));
+    const directOnlyExclusions = new Set();
+    if (enforceChangeMode === 'tracked') {
+        for (const name of actions.ACTION_NAMES_LIST) {
+            if (actions.ACTION_DISPOSITIONS[name] !== 'direct')
+                continue;
+            if (configuredExclusions.has(name) || allowDirectActions.has(name))
+                continue;
+            directOnlyExclusions.add(name);
+        }
+    }
+    return {
+        excludedActions: new Set([...configuredExclusions, ...directOnlyExclusions]),
+        configuredExclusions,
+        directOnlyExclusions,
+        enforceChangeMode,
+        allowDirectActions,
+    };
 }
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
@@ -566,7 +609,7 @@ function validateExclusions(options) {
  * don't want the model to see certain capabilities.
  */
 function listAgentTools(provider, options) {
-    const { excludedActions } = validateExclusions(options);
+    const { excludedActions } = resolveActionPolicy(options);
     const publicSet = new Set(PUBLIC_AGENT_TOOL_NAMES);
     const includedActions = actions.ACTION_NAMES_LIST.filter((name) => !excludedActions.has(name));
     return AGENT_TOOL_DEFINITIONS.filter((d) => publicSet.has(d.name))
@@ -587,6 +630,7 @@ function isAgentToolName(toolName) {
 exports.ACTION_ARG_SCHEMA = ACTION_ARG_SCHEMA;
 exports.AGENT_TOOL_DEFINITIONS = AGENT_TOOL_DEFINITIONS;
 exports.AGENT_TOOL_NAMES = AGENT_TOOL_NAMES;
+exports.ALLOW_ALL_DIRECT_ACTIONS = ALLOW_ALL_DIRECT_ACTIONS;
 exports.CELL_SCHEMA = CELL_SCHEMA;
 exports.LIST_ITEM_SCHEMA = LIST_ITEM_SCHEMA;
 exports.PUBLIC_AGENT_TOOL_NAMES = PUBLIC_AGENT_TOOL_NAMES;
@@ -595,4 +639,4 @@ exports.SELECTOR_SCHEMA = SELECTOR_SCHEMA;
 exports.buildPerformActionDefinition = buildPerformActionDefinition;
 exports.isAgentToolName = isAgentToolName;
 exports.listAgentTools = listAgentTools;
-exports.validateExclusions = validateExclusions;
+exports.resolveActionPolicy = resolveActionPolicy;

package/dist/agent/catalog.d.ts

@@ -326,7 +326,15 @@ export declare const ACTION_ARG_SCHEMA: Record<string, unknown>;
  */
 export declare function buildPerformActionDefinition(includedActions: readonly string[]): AgentToolDefinition;
 export declare const AGENT_TOOL_DEFINITIONS: readonly AgentToolDefinition[];
-/** Customer-facing narrowing of the advertised tool surface. */
+/** The only change mode a host can enforce today. */
+export type EnforceChangeMode = 'tracked';
+/** Wildcard entry for `allowDirectActions`: keep every direct-only action callable. */
+export declare const ALLOW_ALL_DIRECT_ACTIONS = "*";
+/**
+ * Customer-facing narrowing of the advertised tool surface. The same options
+ * shape the tool schema, the system prompt, and the dispatch guard so the
+ * three can never disagree.
+ */
 export interface ListAgentToolsOptions {
     /**
      * Action names to REMOVE from `superdoc_perform_action` — the enum, the
@@ -335,7 +343,52 @@ export interface ListAgentToolsOptions {
      * every action drops the tool entirely.
      */
     excludeActions?: readonly string[];
+    /**
+     * Fail-closed tracked-changes-only policy. With `'tracked'`, every action
+     * whose disposition is `direct` (see ACTION_DISPOSITIONS) is removed from the
+     * surface exactly like an excluded action, and every tracked-capable action
+     * is upgraded to `changeMode: "tracked"` at dispatch whatever the model
+     * asked for. Only `'tracked'` is accepted.
+     */
+    enforceChangeMode?: EnforceChangeMode;
+    /**
+     * Direct-only actions a host permits under `enforceChangeMode`. They stay in
+     * the enum and prompt and run directly at dispatch. `['*']` allows every
+     * direct-only action (tracked-capable ones are still forced tracked).
+     * Requires `enforceChangeMode`; unknown names throw; tracked-capable names
+     * are ignored so a list survives an action gaining tracked support.
+     */
+    allowDirectActions?: readonly string[];
+}
+/** The exclusion set a policy resolves to, split by why each action is out. */
+export interface ResolvedActionPolicy {
+    /** Every action removed from the enum, prompt, and dispatch. */
+    excludedActions: Set<string>;
+    /** Removed by `excludeActions`. Wins over `allowDirectActions`. */
+    configuredExclusions: Set<string>;
+    /** Removed because it is direct-only under `enforceChangeMode` and not allowlisted. */
+    directOnlyExclusions: Set<string>;
+    enforceChangeMode: EnforceChangeMode | undefined;
+    /** Direct-only actions the host allowlisted (validated, tracked names dropped). */
+    allowDirectActions: Set<string>;
+}
+/**
+ * Validate and resolve the surface-narrowing options into one exclusion set.
+ * Every layer (schema, prompt, dispatch) calls this so the policy is computed
+ * exactly one way.
+ */
+export interface ResolveActionPolicyOptions {
+    /**
+     * Skip the unknown-name check. A preset built on top of core (custom actions)
+     * forwards ONE exclusion list that mixes its own action names with core's, so
+     * at dispatch time a name core does not own is another layer's business, not
+     * a caller mistake. Configure-time entry points (getTools, getSystemPrompt)
+     * leave this off so a typo still fails loudly where it was written.
+     */
+    ignoreUnknownActions?: boolean;
 }
+export declare function resolveActionPolicy(options?: ListAgentToolsOptions, resolveOptions?: ResolveActionPolicyOptions): ResolvedActionPolicy;
+/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
 export declare function validateExclusions(options?: ListAgentToolsOptions): {
     excludedActions: Set<string>;
 };

package/dist/agent/catalog.js

@@ -1,5 +1,5 @@
 import { SuperDocCliError } from '../runtime/errors.js';
-import { ACTION_NAMES_LIST, ACTION_HINTS, ACTION_GROUPS, ACTION_ARGS } from './actions.js';
+import { ACTION_NAMES_LIST, ACTION_HINTS, ACTION_GROUPS, ACTION_ARGS, ACTION_DISPOSITIONS } from './actions.js';
 export const AGENT_TOOL_NAMES = [
     'superdoc_inspect',
     'superdoc_perform_action',
@@ -540,18 +540,65 @@ function toProviderTool(provider, definition) {
         return toVercelTool(definition);
     return toOpenAiTool(definition);
 }
-export function validateExclusions(options) {
-    const excludedActions = new Set(options?.excludeActions ?? []);
-    const knownActions = new Set(ACTION_NAMES_LIST);
-    for (const name of excludedActions) {
+/** Wildcard entry for `allowDirectActions`: keep every direct-only action callable. */
+export const ALLOW_ALL_DIRECT_ACTIONS = '*';
+function assertKnownActions(option, names, knownActions) {
+    for (const name of names) {
         if (!knownActions.has(name)) {
-            throw new SuperDocCliError(`excludeActions: unknown action "${name}".`, {
+            throw new SuperDocCliError(`${option}: unknown action "${name}".`, {
                 code: 'INVALID_ARGUMENT',
                 details: { unknownAction: name, knownActions: [...knownActions] },
             });
         }
     }
-    return { excludedActions };
+}
+export function resolveActionPolicy(options, resolveOptions) {
+    const knownActions = new Set(ACTION_NAMES_LIST);
+    const ignoreUnknown = resolveOptions?.ignoreUnknownActions === true;
+    const configuredExclusions = new Set(options?.excludeActions ?? []);
+    if (!ignoreUnknown)
+        assertKnownActions('excludeActions', configuredExclusions, knownActions);
+    const enforceChangeMode = options?.enforceChangeMode;
+    if (enforceChangeMode !== undefined && enforceChangeMode !== 'tracked') {
+        throw new SuperDocCliError(`enforceChangeMode: only "tracked" is supported; got ${JSON.stringify(enforceChangeMode)}.`, {
+            code: 'INVALID_ARGUMENT',
+            details: { enforceChangeMode, supported: ['tracked'] },
+        });
+    }
+    if (options?.allowDirectActions !== undefined && enforceChangeMode === undefined) {
+        throw new SuperDocCliError('allowDirectActions requires enforceChangeMode: "tracked"; without enforcement every action already runs as requested.', {
+            code: 'INVALID_ARGUMENT',
+            details: { allowDirectActions: [...options.allowDirectActions] },
+        });
+    }
+    // `'*'` is the "I accept every direct-only action" shortcut: tracked-capable
+    // actions are still forced tracked, the direct bucket just stays callable.
+    const requestedAllow = new Set(options?.allowDirectActions ?? []);
+    const allowAllDirect = requestedAllow.delete(ALLOW_ALL_DIRECT_ACTIONS);
+    if (!ignoreUnknown)
+        assertKnownActions('allowDirectActions', requestedAllow, knownActions);
+    const allowDirectActions = new Set((allowAllDirect ? [...ACTION_NAMES_LIST] : [...requestedAllow]).filter((name) => ACTION_DISPOSITIONS[name] === 'direct'));
+    const directOnlyExclusions = new Set();
+    if (enforceChangeMode === 'tracked') {
+        for (const name of ACTION_NAMES_LIST) {
+            if (ACTION_DISPOSITIONS[name] !== 'direct')
+                continue;
+            if (configuredExclusions.has(name) || allowDirectActions.has(name))
+                continue;
+            directOnlyExclusions.add(name);
+        }
+    }
+    return {
+        excludedActions: new Set([...configuredExclusions, ...directOnlyExclusions]),
+        configuredExclusions,
+        directOnlyExclusions,
+        enforceChangeMode,
+        allowDirectActions,
+    };
+}
+/** @deprecated Use {@link resolveActionPolicy}; kept for callers that only need the union. */
+export function validateExclusions(options) {
+    return { excludedActions: resolveActionPolicy(options).excludedActions };
 }
 /**
  * Tools advertised to the LLM. Only PUBLIC_AGENT_TOOL_NAMES (currently
@@ -563,7 +610,7 @@ export function validateExclusions(options) {
  * don't want the model to see certain capabilities.
  */
 export function listAgentTools(provider, options) {
-    const { excludedActions } = validateExclusions(options);
+    const { excludedActions } = resolveActionPolicy(options);
     const publicSet = new Set(PUBLIC_AGENT_TOOL_NAMES);
     const includedActions = ACTION_NAMES_LIST.filter((name) => !excludedActions.has(name));
     return AGENT_TOOL_DEFINITIONS.filter((d) => publicSet.has(d.name))