@superdoc/sdk 2.13.0-next.8 → 2.13.0

package/dist/agent/actions.js

@@ -62,7 +62,7 @@ export const ACTION_HINTS = {
     delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:"tracked" makes the table insertion itself a tracked change',
-    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text; the block's intra-paragraph run pattern is preserved best-effort over the unchanged prefix/suffix. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
+    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text using the document API's formatting preservation. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
     fill_placeholders: 'values[] and/or fields[{label?,value}], changeMode?',
     move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
     comment_paragraphs: 'commentText, scope?: all|body, excludeBlockQuotes?',
@@ -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') {
@@ -1146,11 +1193,6 @@ async function runReplaceTextUnchecked(doc, args) {
         let skippedEdits = [];
         let steps;
         let applyExpectedRevision;
-        // Blocks whose text this call rewrites, with their pre-mutation run layout:
-        // the engine replace lane renders the replaced range as uniform runs, so a
-        // whole-paragraph find/replace flattens intra-paragraph formatting (bold
-        // lead-ins). Restore it positionally after the mutation.
-        const preserveTargets = [];
         if (args.selector) {
             const target = selectorToBlockTarget(args.selector, pre);
             if (!target) {
@@ -1189,13 +1231,6 @@ async function runReplaceTextUnchecked(doc, args) {
             ];
             applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
-            preserveTargets.push({
-                nodeId: target.nodeId,
-                nodeType: target.nodeType ?? 'paragraph',
-                oldText: target.text,
-                newText: rewrittenText,
-                runs: await captureBlockRuns(doc, target.nodeId, target.text),
-            });
         }
         else {
             let candidates = args.edits.map((edit, editIndex) => ({
@@ -1253,12 +1288,6 @@ async function runReplaceTextUnchecked(doc, args) {
             steps = candidates.map((candidate) => candidate.step);
         }
         const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
-        const preserved = [];
-        for (const entry of preserveTargets) {
-            const restored = await preserveRunPatternAfterRewrite(doc, entry.nodeId, entry.oldText, entry.runs, entry.newText);
-            if (restored)
-                preserved.push({ nodeId: entry.nodeId, ...restored });
-        }
         if (args.selector && selectedTargets[0]) {
             const post = await buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
             const blockId = selectedTargets[0].matched[0];
@@ -1287,10 +1316,7 @@ async function runReplaceTextUnchecked(doc, args) {
                 preSnapshot: { revision: pre.revision, counts: pre.counts },
                 postSnapshot: { revision: post.revision, counts: post.counts },
                 selectedTargets,
-                executedOperations: [
-                    { operationId: 'doc.mutations.apply', result },
-                    ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
-                ],
+                executedOperations: [{ operationId: 'doc.mutations.apply', result }],
                 verification,
             };
         }
@@ -1314,7 +1340,6 @@ async function runReplaceTextUnchecked(doc, args) {
                     ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
                     result,
                 },
-                ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
             ],
             verification,
         };
@@ -1563,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({
@@ -1581,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
@@ -2587,7 +2649,6 @@ async function runRewriteBlock(doc, args) {
             throw new Error('selector did not resolve to a body block');
         context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
         const text = normalizeTitleLikeRewriteText(target.text, args.text);
-        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
         await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
@@ -2596,7 +2657,6 @@ async function runRewriteBlock(doc, args) {
                 args: { replacement: { text }, style: preserveRewriteStyle() },
             },
         ], args.changeMode, pre.revision);
-        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
         const post = await context.finish();
         const rewritten = await post.block(target.nodeId);
         const verification = [
@@ -2669,23 +2729,8 @@ async function captureBlockRuns(doc, nodeId, text) {
     }
 }
 /**
- * Re-apply a block's pre-rewrite run pattern after a whole-block text.rewrite.
- * The engine renders the rewritten block as a single uniform run, which both
- * drops intra-paragraph formatting AND can smear the first run's marks over
- * everything. Marks are restored positionally over the parts of the text the
- * rewrite did NOT change (the common prefix and suffix of old vs new text),
- * and the changed middle takes the marks of the run it continues from —
- * Word's "typing continues formatting" rule. Best-effort: never fails the
- * rewrite.
- */
-/**
- * Span-aware run-pattern restore for scoped replaces. The generic
- * preserveRunPatternAfterRewrite diffs prefix/suffix and treats everything
- * between the FIRST and LAST change as one modified middle — with two
- * separated replacements that flattens independently-styled runs between
- * them. Here the exact spans are known, so every untouched interval keeps its
- * original run formatting at the offset-mapped position, and each replacement
- * inherits the marks of the run it starts in.
+ * Restore scoped replacements from their known spans: each untouched interval
+ * keeps its run formatting, and replacements inherit the marks at their start.
  * `spans` are FULL-TEXT coordinates, ascending, non-overlapping.
  */
 async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
@@ -2778,74 +2823,6 @@ async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
         return { skipped: reasonOf(err) };
     }
 }
-async function preserveRunPatternAfterRewrite(doc, nodeId, oldText, oldRuns, newText) {
-    // Nothing to restore when the block was uniformly plain; a single STYLED run
-    // still needs restoring (whole-block replaces drop even uniform marks).
-    if (!oldRuns || oldRuns.length === 0)
-        return null;
-    if (!oldRuns.some((run) => Object.keys(inlineFromSnapshotRun(run, new Set())).length > 0))
-        return null;
-    const formatFn = maybeMethod(doc, ['format', 'apply']);
-    if (!formatFn)
-        return null;
-    // Boolean marks any old run carried: plain ranges must explicitly clear
-    // these, because the rewritten single run may have smeared them everywhere.
-    const normalize = new Set(RUN_BOOL_MARKS.filter((key) => oldRuns.some((run) => run[key])));
-    // query.match run offsets are relative to the trimmed text used to match.
-    const oldTrim = oldText.trim();
-    const newTrimStart = newText.length - newText.trimStart().length;
-    const newTrim = newText.trim();
-    let prefix = 0;
-    const maxCommon = Math.min(oldTrim.length, newTrim.length);
-    while (prefix < maxCommon && oldTrim[prefix] === newTrim[prefix])
-        prefix += 1;
-    let suffix = 0;
-    while (suffix < maxCommon - prefix && oldTrim[oldTrim.length - 1 - suffix] === newTrim[newTrim.length - 1 - suffix])
-        suffix += 1;
-    const delta = newTrim.length - oldTrim.length;
-    let applied = 0;
-    const applyRange = async (start, end, inline) => {
-        if (end <= start || Object.keys(inline).length === 0)
-            return;
-        // Always direct, even under tracked mode. This pass RESTORES the marks the
-        // rewrite flattened; it is not new authorial formatting, and the text
-        // revision already owns the span's accept/reject fate. Applying it tracked
-        // adds a second reviewable change per rewrite (SD-4309's conformance matrix
-        // counts one per action), and rejecting that change alone would strand the
-        // text in the flattened look the rewrite produced.
-        const changed = await applyInlineQuiet(formatFn, {
-            blockId: nodeId,
-            start: newTrimStart + start,
-            end: newTrimStart + end,
-            inline,
-        });
-        if (changed)
-            applied += 1;
-    };
-    try {
-        for (const run of oldRuns) {
-            const inline = inlineFromSnapshotRun(run, normalize);
-            // Portion of the run inside the unchanged prefix.
-            await applyRange(run.start, Math.min(run.end, prefix), inline);
-            // Portion inside the unchanged suffix, shifted by the length delta.
-            const sufStart = Math.max(run.start, oldTrim.length - suffix);
-            if (run.end > sufStart)
-                await applyRange(sufStart + delta, run.end + delta, inline);
-        }
-        // The CHANGED middle keeps whatever the engine smeared; give it the marks
-        // of the run the change continues from (the one containing the last
-        // unchanged prefix character).
-        const middleEnd = newTrim.length - suffix;
-        if (middleEnd > prefix) {
-            const anchorRun = oldRuns.find((run) => prefix > run.start && prefix <= run.end) ?? oldRuns[oldRuns.length - 1];
-            await applyRange(prefix, middleEnd, inlineFromSnapshotRun(anchorRun, normalize));
-        }
-        return applied > 0 ? { restoredRunRanges: applied } : null;
-    }
-    catch (err) {
-        return { skipped: reasonOf(err) };
-    }
-}
 const NAMED_COLORS = {
     black: '000000',
     blue: '0000FF',
@@ -4617,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;
@@ -4730,9 +4716,8 @@ async function runScopedReplaceUnchecked(doc, args) {
             },
             args: { replacement: { text: span.replace } },
         }));
-        // Select rewrites flatten the block's runs, so the tracked lane needs the
-        // same restoration the whole-block lane below performs. The preserve pass
-        // applies directly, so restoring marks adds no second reviewable change.
+        // Restore the known edit spans directly so the formatting pass adds no
+        // separate tracked change.
         const trackedPreRuns = await captureBlockRuns(doc, nodeId, block.text);
         try {
             result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
@@ -4922,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))