@margay/ccl-core 1.5.0-alpha.4 → 1.5.1-alpha.3

package/dist/sdk/operations/store.js

@@ -0,0 +1,300 @@
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { OperationError } from './types.js';
+import { operationClone, operationDigest, operationFreeze, operationJson } from './json.js';
+let Sqlite;
+function database(path, options) {
+    Sqlite ??= createRequire(import.meta.url)('node:sqlite').DatabaseSync;
+    return new Sqlite(path, options);
+}
+function durableDirectory(path) {
+    if (existsSync(path))
+        return;
+    const parent = dirname(path);
+    durableDirectory(parent);
+    try {
+        mkdirSync(path, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+    }
+    syncDirectory(path);
+    syncDirectory(parent);
+}
+function syncDirectory(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function sqlError(error) {
+    if (error instanceof OperationError)
+        throw error;
+    // SQLite may return an extended code (e.g. SQLITE_READONLY_ROLLBACK=776).
+    // Its low byte is the primary code used by these recovery decisions.
+    const rawCode = error.errcode;
+    const code = typeof rawCode === 'number' ? rawCode & 0xff : undefined;
+    if (code === 5 || code === 6)
+        throw new OperationError('busy', 'Operation storage is busy; query the original operation before trying again');
+    if (code === 8 || code === 14)
+        throw new OperationError('recovery_required', 'Operation storage requires writable recovery under its execution lock');
+    throw new OperationError('history_unavailable', 'Operation storage is unavailable or corrupt; this does not establish whether an earlier operation was dispatched');
+}
+function privateFile(path) { const fd = openSync(path, 'wx', 0o600); closeSync(fd); }
+/** One authoritative transaction journal per operation; the separate database is only an OS lock. */
+export class OperationStore {
+    storeDir;
+    scope;
+    root;
+    constructor(storeDir, scope) {
+        this.storeDir = storeDir;
+        this.scope = scope;
+        if (!scope)
+            throw new Error('Operation scope must be nonempty');
+        this.root = join(resolve(storeDir), operationDigest(scope));
+    }
+    idFor(requestKey) {
+        if (!requestKey)
+            throw new Error('requestKey must be nonempty');
+        return `op_${operationDigest([this.scope, requestKey])}`;
+    }
+    directory(operationId) {
+        if (!/^op_[a-f0-9]{64}$/.test(operationId))
+            throw new OperationError('not_found', 'Invalid operation identity');
+        const dir = join(this.root, operationId);
+        if (existsSync(dir) && (!lstatSync(dir).isDirectory() || lstatSync(dir).isSymbolicLink()))
+            throw new OperationError('history_unavailable', 'Operation directory is not a private directory');
+        return dir;
+    }
+    open(operationId, writable = false) {
+        const dir = this.directory(operationId), path = join(dir, 'journal.sqlite');
+        if (!existsSync(dir))
+            throw new OperationError('not_found', 'No operation history found; this does not prove an earlier external action never ran');
+        if (!existsSync(path) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())
+            throw new OperationError('history_unavailable', 'Operation journal is missing or invalid');
+        let db;
+        try {
+            db = database(path, { readOnly: !writable, timeout: 0, allowExtension: false });
+            if (Number(db.prepare('PRAGMA user_version').get()?.user_version) !== 1)
+                throw new OperationError('unsupported_version', 'Unknown operation schema; refusing to replace history');
+            if (writable)
+                db.exec('PRAGMA synchronous=FULL');
+            return db;
+        }
+        catch (e) {
+            db?.close();
+            return sqlError(e);
+        }
+    }
+    create(initial) {
+        const dir = this.directory(initial.operationId);
+        durableDirectory(this.root);
+        try {
+            mkdirSync(dir, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                return sqlError(error);
+            const existing = this.read(initial.operationId);
+            if (existing.requestKey !== initial.requestKey || existing.inputDigest !== initial.inputDigest || existing.adapterRef !== initial.adapterRef || operationDigest(existing.binding) !== operationDigest(initial.binding))
+                throw new OperationError('conflict', 'requestKey is already bound to different input or adapter');
+            return existing;
+        }
+        let db;
+        try {
+            privateFile(join(dir, 'executor.sqlite'));
+            const guard = database(join(dir, 'executor.sqlite'), { timeout: 0, allowExtension: false });
+            try {
+                guard.exec('PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; CREATE TABLE mutex (value INTEGER)');
+            }
+            finally {
+                guard.close();
+            }
+            privateFile(join(dir, 'journal.sqlite'));
+            db = database(join(dir, 'journal.sqlite'), { timeout: 0, allowExtension: false });
+            db.exec(`PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL;
+        BEGIN IMMEDIATE;
+        CREATE TABLE events (sequence INTEGER PRIMARY KEY, body TEXT NOT NULL, checksum TEXT NOT NULL);
+        CREATE TABLE results (ref TEXT PRIMARY KEY, body TEXT NOT NULL, checksum TEXT NOT NULL);
+        PRAGMA user_version=1;`);
+            const state = { ...operationClone(initial), schemaVersion: 1, revision: 1, generation: randomUUID() };
+            this.append(db, state, 'accepted', '');
+            db.exec('COMMIT');
+            syncDirectory(dir);
+            syncDirectory(this.root);
+            return this.view(db, state);
+        }
+        catch (e) {
+            return sqlError(e);
+        }
+        finally {
+            db?.close();
+        }
+    }
+    append(db, state, event, previousHash) {
+        const frame = { schemaVersion: 1, operationId: state.operationId, sequence: state.revision, previousHash, event, state };
+        const body = operationJson(frame), checksum = operationDigest(frame);
+        db.prepare('INSERT INTO events(sequence,body,checksum) VALUES(?,?,?)').run(state.revision, body, checksum);
+    }
+    frames(db, operationId) {
+        const rows = db.prepare('SELECT sequence,body,checksum FROM events ORDER BY sequence').all();
+        if (rows.length === 0)
+            throw new OperationError('history_unavailable', 'Operation has no committed acceptance record');
+        let previousHash = '', sequence = 0;
+        return rows.map(row => {
+            const frame = JSON.parse(String(row.body));
+            if (frame.schemaVersion !== 1 || frame.operationId !== operationId || frame.state?.scope !== this.scope || frame.state?.operationId !== operationId || frame.state.schemaVersion !== 1 || frame.state.revision !== frame.sequence || frame.sequence !== ++sequence || frame.sequence !== row.sequence || frame.previousHash !== previousHash || operationDigest(frame) !== row.checksum)
+                throw new OperationError('history_unavailable', 'Operation event chain is corrupt; refusing recovery');
+            previousHash = String(row.checksum);
+            return { ...frame, checksum: previousHash };
+        });
+    }
+    result(db, ref) {
+        if (!ref)
+            return;
+        const row = db.prepare('SELECT body,checksum FROM results WHERE ref=?').get(ref);
+        if (!row)
+            throw new OperationError('history_unavailable', 'Operation result is missing');
+        const value = JSON.parse(String(row.body));
+        if (operationDigest(value) !== row.checksum)
+            throw new OperationError('history_unavailable', 'Operation result is corrupt');
+        return value;
+    }
+    view(db, state) {
+        const allowedActions = ['get', 'events'];
+        if (state.capabilities.query && state.effect !== 'confirmed')
+            allowedActions.push('reconcile');
+        if (state.effect === 'not_dispatched' && ['accepted', 'waiting_permission', 'failed', 'interrupted'].includes(state.execution) && state.cancellation === 'none')
+            allowedActions.push('execute');
+        if (state.effect === 'confirmed')
+            allowedActions.push('accept_verified_result');
+        else if (state.cancellation === 'none' && state.attempts.some(x => x.kind !== 'query')) {
+            const contract = state.capabilities.idempotency;
+            const replayable = state.capabilities.replay === 'read_only' || (state.capabilities.replay === 'idempotent'
+                && contract && contract.scope && Number.isFinite(contract.retentionMs) && contract.retentionMs > 0
+                && Date.now() - state.createdAt < contract.retentionMs);
+            if (replayable)
+                allowedActions.push('retry');
+        }
+        if (!['succeeded', 'cancelled'].includes(state.execution))
+            allowedActions.push('cancel');
+        return operationFreeze({ ...state, allowedActions, ...(state.resultRef ? { result: this.result(db, state.resultRef) } : {}), ...(state.receiptRef ? { receipt: this.result(db, state.receiptRef) } : {}) });
+    }
+    read(operationId) {
+        let db;
+        try {
+            db = this.open(operationId);
+            const frames = this.frames(db, operationId);
+            return this.view(db, frames.at(-1).state);
+        }
+        catch (e) {
+            return sqlError(e);
+        }
+        finally {
+            db?.close();
+        }
+    }
+    /** Mutator runs synchronously under the journal transaction; never awaits external work. */
+    update(operationId, event, mutate) {
+        let db;
+        try {
+            db = this.open(operationId, true);
+            db.exec('BEGIN IMMEDIATE');
+            const frames = this.frames(db, operationId), last = frames.at(-1);
+            const state = operationClone(last.state);
+            const putResult = (value) => {
+                const ref = randomUUID(), body = operationJson(value);
+                db.prepare('INSERT INTO results(ref,body,checksum) VALUES(?,?,?)').run(ref, body, operationDigest(value));
+                return ref;
+            };
+            mutate(state, putResult);
+            // Identity and accepted input are immutable across attempts and recovery actions.
+            for (const key of ['operationId', 'requestKey', 'scope', 'inputDigest', 'createdAt', 'generation', 'adapterRef']) {
+                if (state[key] !== last.state[key])
+                    throw new OperationError('conflict', 'Operation identity cannot be changed');
+            }
+            if (operationDigest(state.input) !== state.inputDigest || operationDigest(state.binding) !== operationDigest(last.state.binding) || operationDigest(state.capabilities) !== operationDigest(last.state.capabilities) || operationDigest(state.links) !== operationDigest(last.state.links))
+                throw new OperationError('conflict', 'Operation binding cannot be changed');
+            state.revision = last.sequence + 1;
+            state.updatedAt = Date.now();
+            this.append(db, state, event, last.checksum);
+            db.exec('COMMIT');
+            return this.view(db, state);
+        }
+        catch (e) {
+            try {
+                db?.exec('ROLLBACK');
+            }
+            catch { }
+            return sqlError(e);
+        }
+        finally {
+            db?.close();
+        }
+    }
+    /** Only the lock holder may perform writable journal recovery after a crash. */
+    acquire(operationId) {
+        const dir = this.directory(operationId), path = join(dir, 'executor.sqlite');
+        if (!existsSync(path) || lstatSync(path).isSymbolicLink())
+            throw new OperationError('history_unavailable', 'Operation execution lock is missing');
+        let db;
+        try {
+            db = database(path, { timeout: 0, allowExtension: false });
+            db.exec('BEGIN IMMEDIATE');
+            const journal = this.open(operationId, true);
+            try {
+                this.frames(journal, operationId);
+            }
+            finally {
+                journal.close();
+            }
+            let released = false;
+            return () => { if (!released) {
+                released = true;
+                try {
+                    db.exec('ROLLBACK');
+                }
+                finally {
+                    db.close();
+                }
+            } };
+        }
+        catch (e) {
+            db?.close();
+            return sqlError(e);
+        }
+    }
+    events(operationId, cursor) {
+        let db;
+        try {
+            db = this.open(operationId);
+            const frames = this.frames(db, operationId), state = frames.at(-1).state;
+            let sequence = 0;
+            if (cursor) {
+                let decoded;
+                try {
+                    decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+                }
+                catch {
+                    throw new OperationError('invalid_cursor', 'Invalid operation event cursor');
+                }
+                if (decoded.scope !== this.scope || decoded.operationId !== operationId || decoded.generation !== state.generation || !Number.isSafeInteger(decoded.sequence) || decoded.sequence < 0 || decoded.sequence > state.revision)
+                    throw new OperationError('invalid_cursor', 'Cursor does not belong to this operation history');
+                sequence = decoded.sequence;
+            }
+            return { events: operationFreeze(frames.filter(f => f.sequence > sequence)), nextCursor: Buffer.from(JSON.stringify({ scope: this.scope, operationId, generation: state.generation, sequence: state.revision })).toString('base64url') };
+        }
+        catch (e) {
+            return sqlError(e);
+        }
+        finally {
+            db?.close();
+        }
+    }
+}

package/dist/sdk/operations/types.d.ts

@@ -0,0 +1,171 @@
+import type { JsonValue, CommandOutcome } from '../commandAdapter.js';
+export type OperationBinding = Readonly<{
+    adapterId: string;
+    adapterVersion: string;
+    targetIdentity: string;
+    definitionDigest: string;
+}>;
+export type OperationCapabilities = Readonly<{
+    replay: 'never' | 'read_only' | 'idempotent';
+    query: boolean;
+    idempotency?: {
+        scope: string;
+        retentionMs: number;
+    };
+}>;
+export type OperationContext = Readonly<{
+    operationId: string;
+    requestKey: string;
+    scope: string;
+    input: JsonValue;
+    inputDigest: string;
+    createdAt: number;
+    binding: OperationBinding;
+    capabilities: OperationCapabilities;
+    /** Handle returned by the trusted adapter for the original remote task. */
+    remoteHandle?: string;
+}>;
+export type OperationAdapterResult = {
+    outcome: CommandOutcome;
+    result?: JsonValue;
+    process?: JsonValue;
+    /** Only an actual pre-dispatch failure can assert this. */
+    dispatch?: 'not_dispatched' | 'dispatched';
+    /** Returning an opaque tool result need not verify its business effects. */
+    execution?: 'succeeded' | 'failed';
+};
+export type OperationInvocation = {
+    operation: OperationContext;
+    attemptId: string;
+    signal: AbortSignal;
+    recovering: boolean;
+    previouslyDispatched: boolean;
+    /** Commit each actual transport dispatch before sending, including internal retries. */
+    recordDispatch?: (dispatchId: string) => void;
+};
+export type OperationAdapter = {
+    binding: OperationBinding;
+    capabilities: OperationCapabilities;
+    execute(invocation: OperationInvocation): Promise<OperationAdapterResult>;
+    queryOutcome?(invocation: OperationInvocation): Promise<OperationAdapterResult>;
+    verifyIdentity?(operation: OperationContext, signal: AbortSignal): Promise<{
+        targetIdentity: string;
+        adapterVersion: string;
+    } | null>;
+};
+export type OperationExecution = 'accepted' | 'dispatching' | 'running' | 'waiting_permission' | 'succeeded' | 'failed' | 'interrupted' | 'cancelled';
+export type OperationOwner = {
+    pid: number;
+    token: string;
+    processStartedAt: number;
+};
+export type OperationAttempt = {
+    attemptId: string;
+    kind: 'execute' | 'retry' | 'query';
+    startedAt: number;
+    endedAt?: number;
+    status: 'dispatching' | 'returned' | 'unknown';
+    owner: OperationOwner;
+    dispatches?: Array<{
+        dispatchId: string;
+        at: number;
+    }>;
+};
+export type OperationAction = {
+    actionId: string;
+    fingerprint: string;
+    action: 'retry' | 'accept_verified_result' | 'reconcile' | 'cancel';
+    state: 'accepted' | 'waiting_permission' | 'finished' | 'unknown';
+    resultRevision?: number;
+};
+export type OperationState = Omit<OperationContext, 'remoteHandle'> & {
+    remoteHandle?: string;
+    schemaVersion: 1;
+    generation: string;
+    adapterRef: string;
+    revision: number;
+    execution: OperationExecution;
+    effect: 'not_dispatched' | 'unknown' | 'confirmed';
+    cancellation: 'none' | 'requested' | 'confirmed';
+    links: {
+        sessionId?: string;
+        toolUseId?: string;
+        taskId?: string;
+        toolInputDigest?: string;
+    };
+    attempts: OperationAttempt[];
+    actions: OperationAction[];
+    resultRef?: string;
+    receiptRef?: string;
+    owner?: OperationOwner;
+    reason?: string;
+    updatedAt: number;
+};
+export type OperationView = OperationState & {
+    result?: JsonValue;
+    receipt?: JsonValue;
+    allowedActions: Array<'execute' | 'get' | 'events' | 'reconcile' | 'retry' | 'accept_verified_result' | 'cancel'>;
+};
+export type OperationEvent = {
+    schemaVersion: 1;
+    operationId: string;
+    sequence: number;
+    previousHash: string;
+    checksum: string;
+    event: string;
+    state: OperationState;
+};
+export type OperationErrorCode = 'not_found' | 'history_unavailable' | 'unsupported_version' | 'recovery_required' | 'busy' | 'conflict' | 'invalid_cursor' | 'authorization_required' | 'permission_denied' | 'capability_changed' | 'unsupported' | 'cancelled';
+export declare class OperationError extends Error {
+    readonly code: OperationErrorCode;
+    constructor(code: OperationErrorCode, message: string);
+}
+export type OperationPermissionRequest = {
+    operation: OperationContext;
+    action: 'read' | 'execute' | 'query' | 'retry' | 'cancel';
+    signal?: AbortSignal;
+};
+export type OperationPermissionDecision = {
+    behavior: 'allow' | 'deny' | 'ask';
+    reason?: string;
+};
+export type OperationHostOptions = {
+    storeDir: string;
+    scope: string;
+    resolveAdapter: (adapterRef: string) => Promise<OperationAdapter | undefined>;
+    authorize: (request: OperationPermissionRequest) => Promise<OperationPermissionDecision>;
+    /** Bounds host callbacks as well as adapter invocations. */
+    timeoutMs?: number;
+};
+export type OperationIdentity = {
+    operationId: string;
+};
+export type OperationMutation = OperationIdentity & {
+    expectedRevision: number;
+    actionId: string;
+    signal?: AbortSignal;
+};
+export interface OperationHost {
+    submitOperation(input: {
+        requestKey: string;
+        adapterRef: string;
+        input: JsonValue;
+        links?: OperationState['links'];
+    }): Promise<OperationView>;
+    executeOperation(input: OperationIdentity & {
+        expectedRevision: number;
+        signal?: AbortSignal;
+    }): Promise<OperationView>;
+    getOperation(input: OperationIdentity): Promise<OperationView>;
+    readOperationEvents(input: OperationIdentity & {
+        cursor?: string;
+    }): Promise<{
+        events: OperationEvent[];
+        nextCursor: string;
+    }>;
+    reconcileOperation(input: OperationMutation): Promise<OperationView>;
+    resumeOperation(input: OperationMutation & {
+        action: 'retry' | 'accept_verified_result';
+    }): Promise<OperationView>;
+    cancelOperation(input: OperationMutation): Promise<OperationView>;
+}

package/dist/sdk/operations/types.js

@@ -0,0 +1,8 @@
+export class OperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OperationError';
+    }
+}

package/dist/sdk/pendingApprovalIdentity.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod/v4';
+import type { PendingApproval } from './types.js';
+export declare const pendingApprovalIdentitySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    toolUseId: z.ZodString;
+    toolName: z.ZodString;
+    inputDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const pendingApprovalSuspensionResponseSchema: z.ZodObject<{
+    suspended: z.ZodLiteral<true>;
+    approval: z.ZodObject<{
+        sessionId: z.ZodString;
+        requestId: z.ZodString;
+        toolUseId: z.ZodString;
+        toolName: z.ZodString;
+        inputDigest: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const pendingApprovalConflictSchema: z.ZodObject<{
+    code: z.ZodLiteral<"resume_approval_mismatch">;
+    approval: z.ZodObject<{
+        sessionId: z.ZodString;
+        requestId: z.ZodString;
+        toolUseId: z.ZodString;
+        toolName: z.ZodString;
+        inputDigest: z.ZodString;
+    }, z.core.$strict>;
+    originalNotExecuted: z.ZodBoolean;
+}, z.core.$strict>;
+export type PendingApprovalIdentity = z.infer<typeof pendingApprovalIdentitySchema>;
+/** JSON wire equality: object order is irrelevant; array order and every value matter. */
+export declare function approvalInputDigest(input: Record<string, unknown>): string;
+export declare function pendingApprovalIdentity(pending: PendingApproval): PendingApprovalIdentity;
+export declare function samePendingApproval(expected: PendingApprovalIdentity, pending: PendingApproval): boolean;

package/dist/sdk/pendingApprovalIdentity.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod/v4';
+export const pendingApprovalIdentitySchema = z.strictObject({
+    sessionId: z.string().min(1), requestId: z.string().min(1), toolUseId: z.string().min(1),
+    toolName: z.string().min(1), inputDigest: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export const pendingApprovalSuspensionResponseSchema = z.strictObject({
+    suspended: z.literal(true), approval: pendingApprovalIdentitySchema,
+});
+export const pendingApprovalConflictSchema = z.strictObject({
+    code: z.literal('resume_approval_mismatch'), approval: pendingApprovalIdentitySchema, originalNotExecuted: z.boolean(),
+});
+/** JSON wire equality: object order is irrelevant; array order and every value matter. */
+export function approvalInputDigest(input) {
+    const json = JSON.parse(JSON.stringify(input));
+    const canonical = (value) => Array.isArray(value) ? value.map(canonical)
+        : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, child]) => [key, canonical(child)])) : value;
+    return createHash('sha256').update(JSON.stringify(canonical(json))).digest('hex');
+}
+export function pendingApprovalIdentity(pending) {
+    return { sessionId: pending.sessionId, requestId: pending.requestId, toolUseId: pending.toolUseId,
+        toolName: pending.toolName, inputDigest: approvalInputDigest(pending.input) };
+}
+export function samePendingApproval(expected, pending) {
+    const actual = pendingApprovalIdentity(pending);
+    return Object.keys(actual).every(key => actual[key] === expected[key]);
+}

package/dist/sdk/permissionDelegation.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod/v4';
+/** Serializable task-scoped grants. Persistent settings are reloaded by the CLI. */
+export declare const permissionDelegationSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    mode: z.ZodEnum<{
+        plan: "plan";
+        default: "default";
+        auto: "auto";
+        acceptEdits: "acceptEdits";
+        dontAsk: "dontAsk";
+        bypassPermissions: "bypassPermissions";
+    }>;
+    allow: z.ZodArray<z.ZodString>;
+    deny: z.ZodArray<z.ZodString>;
+    ask: z.ZodArray<z.ZodString>;
+    additionalDirectories: z.ZodArray<z.ZodString>;
+    omittedSources: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type PermissionDelegation = z.infer<typeof permissionDelegationSchema>;

package/dist/sdk/permissionDelegation.js

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4';
+/** Serializable task-scoped grants. Persistent settings are reloaded by the CLI. */
+export const permissionDelegationSchema = z.strictObject({
+    version: z.literal(1),
+    mode: z.enum(['default', 'acceptEdits', 'dontAsk', 'bypassPermissions', 'plan', 'auto']),
+    allow: z.array(z.string()),
+    deny: z.array(z.string()),
+    ask: z.array(z.string()),
+    additionalDirectories: z.array(z.string()),
+    omittedSources: z.array(z.string()),
+});

package/dist/sdk/query.d.ts

@@ -20,6 +20,7 @@ type PermissionDecisionWire = {
     message: string;
     interaction?: InteractionResponse;
     interrupt?: boolean;
+    cancellation?: import('./cancellation.js').HostCancellation;
     toolUseID: string;
 };
 type CallbackOutcome = {
@@ -59,7 +60,8 @@ export declare function query(prompt: string, options?: QueryOptions): AsyncGene
  *
  * On allow, the suspended tool executes with exactly the recorded input (or
  * decision.updatedInput if the owner amended it); on deny the model receives
- * the denial and the session continues.
+ * the denial and the session continues. With expectedApproval, both the saved
+ * identity and regenerated input must match; substitution is not permitted.
  */
 export declare function resumeWithDecision(sessionId: string, decision: PendingDecision, options?: QueryOptions): AsyncGenerator<SDKEvent>;
 /** P1-7: accumulated usage for a session, across all queries that ran it. */