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

package/dist/sdk/query.js

@@ -1,3 +1,7 @@
+import { randomUUID } from 'node:crypto';
+import { approvalInputDigest, pendingApprovalIdentity, pendingApprovalSuspensionResponseSchema, pendingApprovalIdentitySchema, pendingApprovalConflictSchema, samePendingApproval } from './pendingApprovalIdentity.js';
+import { QueryLifecycleObservationSchema } from './queryLifecycleTypes.js';
+import { readOperationReference } from './operations/reference.js';
 import { sanitizeRequestProgress } from './requestProgress.js';
 /**
  * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
@@ -73,8 +77,17 @@ export function buildCliArgs(options) {
         args.push('--max-turns', String(options.maxTurns));
     if (options.maxBudgetUsd !== undefined)
         args.push('--max-budget-usd', String(options.maxBudgetUsd));
-    if (options.permissionMode)
-        args.push('--permission-mode', options.permissionMode);
+    const permissionMode = options.permissionDelegation?.mode ?? options.permissionMode;
+    if (permissionMode)
+        args.push('--permission-mode', permissionMode);
+    if (options.permissionCallbackMode)
+        args.push('--permission-callback-mode', options.permissionCallbackMode);
+    if (options.permissionDelegation)
+        args.push('--require-permission-delegation');
+    if (options.pendingDecision)
+        args.push('--resume-pending-approval');
+    if (options.pendingDecision?.expectedApproval)
+        args.push('--strict-pending-resume');
     for (const dir of options.pluginDirs ?? [])
         args.push('--plugin-dir', dir);
     if (options.addDirs?.length)
@@ -282,6 +295,9 @@ export async function* queryWithTransport(prompt, options, transport) {
     let turn = 0;
     let sawResult = false;
     let sessionEnded = false;
+    let suspension;
+    let suspensionTimer;
+    let suspensionTimedOut = false;
     const streamingInput = isAsyncInput(prompt);
     const inputState = { finished: false };
     let resolveProvenanceSupport;
@@ -310,11 +326,27 @@ export async function* queryWithTransport(prompt, options, transport) {
         if (!options.resume) {
             throw new Error('ccl-sdk: pendingDecision requires options.resume');
         }
-        pendingApproval = await store.loadPendingApproval(options.resume);
-        if (!pendingApproval) {
-            throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+        try {
+            pendingApproval = await store.loadPendingApproval(options.resume);
+            if (!pendingApproval)
+                throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+            if (pendingApproval.suspension && pendingApproval.suspension !== 'confirmed')
+                throw new Error('permission_suspension_unconfirmed: the CLI did not confirm a durable suspension; execution status must be checked before resuming');
+            if (pendingDecision.expectedApproval) {
+                const expected = pendingApprovalIdentitySchema.parse(pendingDecision.expectedApproval);
+                if (!samePendingApproval(expected, pendingApproval) || expected.sessionId !== options.resume)
+                    throw new Error('resume_approval_mismatch: saved approval does not match the decision identity');
+                if (pendingDecision.behavior === 'allow' && pendingDecision.updatedInput && approvalInputDigest(pendingDecision.updatedInput) !== expected.inputDigest)
+                    throw new Error('resume_approval_mismatch: strict approval cannot substitute different input');
+                pendingDecision = { ...pendingDecision, expectedApproval: expected };
+            }
+        }
+        catch (error) {
+            await transport.close();
+            throw error;
         }
     }
+    const strictApprovalEvidence = pendingDecision?.expectedApproval ? pendingApproval : null;
     const onAbort = () => { resolveProvenanceSupport(false); void transport.close(); };
     options.signal?.addEventListener('abort', onAbort, { once: true });
     if (options.signal?.aborted)
@@ -342,6 +374,9 @@ export async function* queryWithTransport(prompt, options, transport) {
             request_id: initId,
             request: {
                 subtype: 'initialize',
+                ...(pendingApproval ? { pendingResumeApproval: { approval: pendingApprovalIdentity(pendingApproval), confirmed: pendingApproval.suspension === 'confirmed' } } : {}),
+                ...(options.permissionDelegation ? { permissionDelegation: options.permissionDelegation } : {}),
+                ...(pendingDecision?.expectedApproval ? { strictPendingApproval: pendingDecision.expectedApproval } : {}),
                 ...(options.systemPrompt !== undefined && {
                     systemPrompt: options.systemPrompt,
                 }),
@@ -385,7 +420,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     await runHook(hooks.onUserPromptSubmit && (() => hooks.onUserPromptSubmit({ prompt: text, sessionId: lastSessionId })));
             })
             : transport.read();
-        for await (const rawMessage of messages) {
+        permissionWire: for await (const rawMessage of messages) {
             let attribution = rawMessage.input_uuid === null
                 ? { origin: 'background' } : typeof rawMessage.input_uuid === 'string'
                 ? { origin: 'user', turnId: rawMessage.input_uuid }
@@ -416,6 +451,13 @@ export async function* queryWithTransport(prompt, options, transport) {
                 yield { ...attribution, type: 'raw', message };
             switch (message.type) {
                 case 'system': {
+                    if (message.subtype === 'query_lifecycle') {
+                        const parsed = QueryLifecycleObservationSchema.safeParse(message.lifecycle);
+                        if (parsed.success && parsed.data.record.session_id === message.session_id && parsed.data.record.event_id === message.uuid)
+                            yield {
+                                ...attribution, type: 'query_lifecycle', lifecycle: parsed.data, sessionId: parsed.data.record.session_id,
+                            };
+                    }
                     if (message.subtype === 'request_progress' && progress)
                         yield { ...attribution,
                             type: 'request_progress', progress,
@@ -463,6 +505,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     for (const block of contentBlocks(message.message)) {
                         if (block.type === 'tool_result') {
                             const toolUseId = String(block.tool_use_id ?? '');
+                            const operationReference = readOperationReference(message.operation_reference, toolUseId);
                             const isError = block.is_error === true;
                             const resultContent = isError
                                 ? typeof block.content === 'string' ? sanitizeErrorText(block.content)
@@ -473,6 +516,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                 type: 'tool_result',
                                 toolUseId,
                                 content: resultContent,
+                                ...(operationReference ? { operationReference } : {}),
                                 isError,
                                 sessionId,
                             };
@@ -481,6 +525,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     toolUseId,
                                     toolName: toolNamesById.get(toolUseId),
                                     content: resultContent,
+                                    ...(operationReference ? { operationReference } : {}),
                                     isError,
                                     sessionId,
                                 })));
@@ -491,6 +536,10 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'control_request': {
+                    // Suspension stops the whole query; never answer another concurrent
+                    // tool while waiting for the targeted CLI acknowledgement.
+                    if (suspension)
+                        break;
                     const requestId = String(message.request_id ?? '');
                     const request = (message.request ?? {});
                     // slice sdk-in-process-mcp-server: route MCP tool calls to host in-process servers.
@@ -535,9 +584,14 @@ export async function* queryWithTransport(prompt, options, transport) {
                         agentId,
                     };
                     // Resume path: settle the recorded approval on its matching call.
-                    // Match by toolName — on allow the tool runs with the RECORDED
-                    // input (or the host's explicit updatedInput), never the model's
-                    // re-generated one, so what the owner approved is what executes.
+                    // Strict callers require the same tool and structured input. Legacy
+                    // callers retain name-only matching and recorded-input substitution.
+                    if (pendingDecision?.expectedApproval && (toolName !== pendingDecision.expectedApproval.toolName || approvalInputDigest(input) !== pendingDecision.expectedApproval.inputDigest)) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true, message: 'Regenerated tool/input differs from the original approved invocation' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     if (pendingDecision && pendingApproval?.toolName === toolName) {
                         const decision = pendingDecision.behavior === 'allow'
                             ? {
@@ -620,28 +674,16 @@ export async function* queryWithTransport(prompt, options, transport) {
                             toolName,
                             input,
                             createdAt: new Date().toISOString(),
+                            suspension: 'requested',
                         };
                         await store.savePendingApproval(record);
-                        // Deliberately NO control_response: the tool must not run and
-                        // the model must not see a denial. Terminating here leaves the
-                        // transcript ending at the unresolved tool_use, which the
-                        // resume path drops and re-drives.
-                        yield { ...attribution,
-                            type: 'suspended',
-                            sessionId,
-                            requestId,
-                            toolUseId,
-                            toolName,
-                            input,
-                        };
-                        sessionEnded = true;
-                        await runHook(hooks.onSessionEnd &&
-                            (() => hooks.onSessionEnd({
-                                sessionId,
-                                subtype: 'suspended',
-                                isError: false,
-                            })));
-                        return;
+                        // A saved SDK record alone does not prove the CLI stopped without
+                        // converting EOF into a denial. Ask it to freeze and persist first.
+                        suspension = { requestId: randomUUID(), record, attribution, confirmed: false };
+                        suspensionTimer = setTimeout(() => { suspensionTimedOut = true; void transport.close(); }, 10000);
+                        await transport.write({ type: 'control_request', request_id: suspension.requestId,
+                            request: { subtype: 'suspend_permission', approval: pendingApprovalIdentity(record) } });
+                        break;
                     }
                     await transport.write({
                         type: 'control_response',
@@ -667,6 +709,20 @@ export async function* queryWithTransport(prompt, options, transport) {
                 case 'control_response': {
                     const response = (message.response ?? {});
                     const requestId = String(response.request_id ?? '');
+                    if (suspension?.requestId === requestId) {
+                        const ack = pendingApprovalSuspensionResponseSchema.safeParse(response.response);
+                        if (response.subtype !== 'success' || !ack.success || !samePendingApproval(ack.data.approval, suspension.record)) {
+                            yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                                message: `CLI did not confirm pending approval suspension: ${String(response.error ?? 'invalid acknowledgement')}` };
+                            return;
+                        }
+                        suspension.record = { ...suspension.record, suspension: 'confirmed' };
+                        await store.savePendingApproval(suspension.record);
+                        suspension.confirmed = true;
+                        if (suspensionTimer)
+                            clearTimeout(suspensionTimer);
+                        break permissionWire;
+                    }
                     if (ownRequestIds.has(requestId)) {
                         ownRequestIds.delete(requestId);
                         const capability = response.response?.input_provenance;
@@ -683,6 +739,34 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'result': {
+                    if (suspension && !suspension.confirmed) {
+                        yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                            message: 'CLI ended its turn before confirming permission suspension; inspect execution status' };
+                        return;
+                    }
+                    const conflict = pendingApprovalConflictSchema.safeParse(message.permission_resume_conflict);
+                    if (strictApprovalEvidence && conflict.success && samePendingApproval(conflict.data.approval, strictApprovalEvidence) && message.session_id === strictApprovalEvidence.sessionId) {
+                        if (conflict.data.originalNotExecuted) {
+                            // The CLI guard proves this invocation never reached execution. Restore
+                            // evidence removed on response; never overwrite a newer pending request.
+                            const current = await store.loadPendingApproval(strictApprovalEvidence.sessionId);
+                            if (!current)
+                                await store.savePendingApproval(strictApprovalEvidence);
+                        }
+                        yield { ...attribution, type: 'error', code: conflict.data.code, fatal: true,
+                            message: errorDetailsList(message.errors).join('; ') || 'Strict approval conflict before execution' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
+                    if (pendingDecision?.expectedApproval) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true,
+                            message: 'Strict resume ended without settling the original approval',
+                        };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     sawResult = true;
                     const sessionId = message.session_id;
                     const usage = message.usage;
@@ -756,6 +840,22 @@ export async function* queryWithTransport(prompt, options, transport) {
             if (sawResult && !streamingInput)
                 break;
         }
+        if (suspension) {
+            if (!suspension.confirmed) {
+                yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                    message: suspensionTimedOut ? 'Timed out waiting for CLI permission suspension acknowledgement' : 'CLI exited without confirming permission suspension' };
+                return;
+            }
+            // The read iterator has unwound. Stop the original process before exposing
+            // a resumable event, so a consumer can immediately resume in a fresh CLI.
+            await transport.close();
+            const record = suspension.record;
+            yield { ...suspension.attribution, type: 'suspended', sessionId: record.sessionId,
+                requestId: record.requestId, toolUseId: record.toolUseId, toolName: record.toolName, input: record.input };
+            sessionEnded = true;
+            await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({ sessionId: record.sessionId, subtype: 'suspended', isError: false })));
+            return;
+        }
         if (streamingInput && inputState.finished) {
             await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({
                 sessionId: lastSessionId, subtype: 'input_complete', isError: false,
@@ -783,6 +883,8 @@ export async function* queryWithTransport(prompt, options, transport) {
         }
     }
     finally {
+        if (suspensionTimer)
+            clearTimeout(suspensionTimer);
         resolveProvenanceSupport(false);
         options.signal?.removeEventListener('abort', onAbort);
         await sdkMcpRegistry?.close();
@@ -858,7 +960,8 @@ export function query(prompt, options = {}) {
  *
  * 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 function resumeWithDecision(sessionId, decision, options = {}) {
     const merged = {

package/dist/sdk/queryLifecycle.d.ts

@@ -0,0 +1,19 @@
+import { type QueryLifecycleRecord } from './queryLifecycleTypes.js';
+export type QueryLifecycleRead = {
+    state: 'found';
+    completeness: 'complete' | 'incomplete';
+    records: QueryLifecycleRecord[];
+    terminal?: QueryLifecycleRecord;
+} | {
+    state: 'not_found';
+} | {
+    state: 'unavailable';
+    reason: 'file_unavailable' | 'invalid_record' | 'truncated_tail' | 'record_too_large' | 'conflicting_events';
+};
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export declare function readQueryLifecycle(input: {
+    transcriptPath: string;
+    sessionId: string;
+    queryId: string;
+}): Promise<QueryLifecycleRead>;

package/dist/sdk/queryLifecycle.js

@@ -0,0 +1,93 @@
+import { createReadStream } from 'node:fs';
+import { QueryLifecycleSchema } from './queryLifecycleTypes.js';
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export async function readQueryLifecycle(input) {
+    const records = [];
+    const events = new Map();
+    let failure;
+    let pending = '';
+    const stream = createReadStream(input.transcriptPath, { encoding: 'utf8', highWaterMark: 64 * 1024 });
+    const consume = (line) => {
+        if (!line.trim())
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const entry = raw;
+        if (entry.type !== 'query_lifecycle')
+            return;
+        if (entry.record?.session_id !== input.sessionId || entry.record?.query_id !== input.queryId)
+            return;
+        const parsed = QueryLifecycleSchema.safeParse(entry.record);
+        if (!parsed.success) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const record = parsed.data;
+        const serialized = JSON.stringify(record);
+        const duplicate = events.get(record.event_id);
+        if (duplicate !== undefined) {
+            if (duplicate !== serialized)
+                failure = { state: 'unavailable', reason: 'conflicting_events' };
+            return;
+        }
+        events.set(record.event_id, serialized);
+        records.push(record);
+    };
+    try {
+        for await (const chunk of stream) {
+            pending += chunk;
+            let index;
+            while ((index = pending.indexOf('\n')) !== -1) {
+                if (index > 32 * 1024 * 1024)
+                    return { state: 'unavailable', reason: 'record_too_large' };
+                consume(pending.slice(0, index));
+                if (failure)
+                    return failure;
+                pending = pending.slice(index + 1);
+            }
+            // Protect against an unbounded unterminated line, including ordinary
+            // conversation records. Large files remain streamed rather than loaded.
+            if (pending.length > 32 * 1024 * 1024)
+                return { state: 'unavailable', reason: 'record_too_large' };
+        }
+        if (pending.trim())
+            return { state: 'unavailable', reason: 'truncated_tail' };
+    }
+    catch {
+        return { state: 'unavailable', reason: 'file_unavailable' };
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!records.length)
+        return { state: 'not_found' };
+    let previous;
+    let completeSequence = records[0].phase === 'start';
+    for (const record of records) {
+        if (previous) {
+            if (previous.phase === 'terminal' || record.sequence <= previous.sequence || record.phase === 'start'
+                || record.scope !== previous.scope || record.agent_id !== previous.agent_id
+                || previous.accepted_inputs.some(p => !record.accepted_inputs.some(n => n.message_id === p.message_id && JSON.stringify(n) === JSON.stringify(p)))
+                || previous.input_message_ids.some(id => !record.input_message_ids.includes(id))) {
+                return { state: 'unavailable', reason: 'conflicting_events' };
+            }
+            if (record.sequence !== previous.sequence + 1)
+                completeSequence = false;
+        }
+        previous = record;
+    }
+    const terminal = previous?.phase === 'terminal' ? previous : undefined;
+    return { state: 'found', completeness: terminal && completeSequence ? 'complete' : 'incomplete', records,
+        ...(terminal && completeSequence ? { terminal } : {}) };
+}

package/dist/sdk/queryLifecycleTypes.d.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod/v4';
+/** Host observations of one query loop. Neither an authorization nor a business result. */
+export declare const QueryLifecycleSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    event_id: z.ZodString;
+    query_id: z.ZodString;
+    session_id: z.ZodString;
+    sequence: z.ZodNumber;
+    timestamp: z.ZodString;
+    scope: z.ZodEnum<{
+        main: "main";
+        subagent: "subagent";
+        auxiliary: "auxiliary";
+    }>;
+    agent_id: z.ZodNullable<z.ZodString>;
+    phase: z.ZodEnum<{
+        start: "start";
+        stop_attempt: "stop_attempt";
+        stop_failure: "stop_failure";
+        terminal: "terminal";
+    }>;
+    attempt: z.ZodNumber;
+    accepted_inputs: z.ZodArray<z.ZodObject<{
+        message_id: z.ZodString;
+        origin: z.ZodString;
+        provenance: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            actor: z.ZodEnum<{
+                unknown: "unknown";
+                agent: "agent";
+                human: "human";
+                host: "host";
+            }>;
+            source: z.ZodString;
+            session_id: z.ZodOptional<z.ZodString>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    input_message_ids: z.ZodArray<z.ZodString>;
+    input_association: z.ZodEnum<{
+        unknown: "unknown";
+        known: "known";
+    }>;
+    last_assistant_message_id: z.ZodNullable<z.ZodString>;
+    status: z.ZodNullable<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        interrupted: "interrupted";
+        stopped: "stopped";
+    }>>;
+    terminal_reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type QueryLifecycleRecord = z.infer<typeof QueryLifecycleSchema>;
+export type QueryLifecycleWrite = {
+    state: 'saved';
+} | {
+    state: 'unavailable';
+    reason: 'persistence_disabled' | 'no_transcript';
+} | {
+    state: 'failed';
+    reason: 'write_failed';
+} | {
+    state: 'unknown';
+    reason: 'write_timeout';
+};
+export declare const QueryLifecycleWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
+    state: z.ZodLiteral<"saved">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+    reason: z.ZodEnum<{
+        persistence_disabled: "persistence_disabled";
+        no_transcript: "no_transcript";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"failed">;
+    reason: z.ZodLiteral<"write_failed">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unknown">;
+    reason: z.ZodLiteral<"write_timeout">;
+}, z.core.$strip>]>;
+export type QueryLifecycleObservation = {
+    record: QueryLifecycleRecord;
+    persistence: QueryLifecycleWrite;
+    transcript_path: string | null;
+};
+export declare const QueryLifecycleObservationSchema: z.ZodObject<{
+    record: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        event_id: z.ZodString;
+        query_id: z.ZodString;
+        session_id: z.ZodString;
+        sequence: z.ZodNumber;
+        timestamp: z.ZodString;
+        scope: z.ZodEnum<{
+            main: "main";
+            subagent: "subagent";
+            auxiliary: "auxiliary";
+        }>;
+        agent_id: z.ZodNullable<z.ZodString>;
+        phase: z.ZodEnum<{
+            start: "start";
+            stop_attempt: "stop_attempt";
+            stop_failure: "stop_failure";
+            terminal: "terminal";
+        }>;
+        attempt: z.ZodNumber;
+        accepted_inputs: z.ZodArray<z.ZodObject<{
+            message_id: z.ZodString;
+            origin: z.ZodString;
+            provenance: z.ZodOptional<z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                actor: z.ZodEnum<{
+                    unknown: "unknown";
+                    agent: "agent";
+                    human: "human";
+                    host: "host";
+                }>;
+                source: z.ZodString;
+                session_id: z.ZodOptional<z.ZodString>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        input_message_ids: z.ZodArray<z.ZodString>;
+        input_association: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        last_assistant_message_id: z.ZodNullable<z.ZodString>;
+        status: z.ZodNullable<z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            cancelled: "cancelled";
+            interrupted: "interrupted";
+            stopped: "stopped";
+        }>>;
+        terminal_reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    persistence: z.ZodUnion<readonly [z.ZodObject<{
+        state: z.ZodLiteral<"saved">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodEnum<{
+            persistence_disabled: "persistence_disabled";
+            no_transcript: "no_transcript";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"failed">;
+        reason: z.ZodLiteral<"write_failed">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+        reason: z.ZodLiteral<"write_timeout">;
+    }, z.core.$strip>]>;
+    transcript_path: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Metadata entry deliberately has no conversation uuid/parentUuid chain fields. */
+export type QueryLifecycleEntry = {
+    type: 'query_lifecycle';
+    record: QueryLifecycleRecord;
+};

package/dist/sdk/queryLifecycleTypes.js

@@ -0,0 +1,47 @@
+import { z } from 'zod/v4';
+const identity = z.string().min(1).max(256);
+const provenance = z.object({
+    version: z.literal(1), actor: z.enum(['human', 'host', 'agent', 'unknown']),
+    source: z.string(), session_id: z.string().optional(), request_id: z.string().optional(),
+});
+/** Host observations of one query loop. Neither an authorization nor a business result. */
+export const QueryLifecycleSchema = z.object({
+    version: z.literal(1), event_id: identity, query_id: identity, session_id: identity,
+    sequence: z.number().int().nonnegative(), timestamp: z.string(),
+    scope: z.enum(['main', 'subagent', 'auxiliary']), agent_id: identity.nullable(),
+    phase: z.enum(['start', 'stop_attempt', 'stop_failure', 'terminal']),
+    attempt: z.number().int().nonnegative(),
+    accepted_inputs: z.array(z.object({ message_id: identity, origin: z.string(), provenance: provenance.optional() })),
+    // Handed to the host model adapter, not proof of server receipt or understanding.
+    input_message_ids: z.array(identity), input_association: z.enum(['known', 'unknown']),
+    last_assistant_message_id: identity.nullable(),
+    status: z.enum(['completed', 'failed', 'cancelled', 'stopped', 'interrupted']).nullable(),
+    terminal_reason: z.string().nullable(),
+}).superRefine((event, ctx) => {
+    const invalid = (message) => ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+    if ((event.phase === 'terminal') !== (event.status !== null))
+        invalid('Only terminal events have a status');
+    if (event.phase !== 'terminal' && event.terminal_reason !== null)
+        invalid('Only terminal events have a terminal reason');
+    const accepted = event.accepted_inputs.map(input => input.message_id);
+    if (new Set(accepted).size !== accepted.length)
+        invalid('Duplicate accepted input');
+    if (new Set(event.input_message_ids).size !== event.input_message_ids.length)
+        invalid('Duplicate dispatched input');
+    if (event.input_message_ids.some(id => !accepted.includes(id)))
+        invalid('Dispatched input was not accepted');
+    if (event.phase === 'start' && (event.sequence !== 0 || event.attempt !== 0 || event.input_message_ids.length !== 0))
+        invalid('Invalid query start');
+    if (event.scope === 'subagent' && event.agent_id === null)
+        invalid('Subagent identity missing');
+});
+export const QueryLifecycleWriteSchema = z.union([
+    z.object({ state: z.literal('saved') }),
+    z.object({ state: z.literal('unavailable'), reason: z.enum(['persistence_disabled', 'no_transcript']) }),
+    z.object({ state: z.literal('failed'), reason: z.literal('write_failed') }),
+    z.object({ state: z.literal('unknown'), reason: z.literal('write_timeout') }),
+]);
+export const QueryLifecycleObservationSchema = z.object({
+    record: QueryLifecycleSchema, persistence: QueryLifecycleWriteSchema,
+    transcript_path: z.string().nullable(),
+});