@astrosheep/keiyaku 4.5.7 → 4.5.9

package/build/src/akuma/projection.js

@@ -1,4 +1,196 @@
+/* eslint-disable max-lines -- Akuma owns one coherent activity projection and strict boundary schema. */
 import { decodeAgentEvent } from "./provider.js";
+import { projectTell } from "./heart/facts.js";
+import { z } from "zod";
+const nonblankTextSchema = z.string().refine((value) => value.trim() !== "");
+const countSchema = z.number().int().nonnegative();
+const timestampSchema = z.string().refine((value) => Number.isFinite(Date.parse(value)), "expected timestamp");
+const diffstatSchema = z.object({ added: countSchema, removed: countSchema }).strict();
+const fileChangeSchema = z
+    .object({
+    op: z.enum(["add", "update", "delete", "unspecified"]),
+    path: z.string(),
+    diffstat: diffstatSchema.optional(),
+})
+    .strict();
+const toolCallSchema = z.union([
+    z.object({ kind: z.literal("run"), command: z.string() }).strict(),
+    z
+        .object({
+        kind: z.literal("read"),
+        path: z.string(),
+        offset: countSchema.optional(),
+        limit: countSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("search"),
+        query: z.string(),
+        scope: z.enum(["content", "files", "web"]).optional(),
+        path: z.string().optional(),
+        glob: z.string().optional(),
+    })
+        .strict(),
+    z.object({ kind: z.literal("fileChange"), changes: z.array(fileChangeSchema).readonly() }).strict(),
+    z.object({ kind: z.literal("other"), display: z.string() }).strict(),
+]);
+const toolResultSchema = z
+    .object({ status: z.enum(["ok", "error"]), message: z.string().optional(), exitCode: z.number().int().optional() })
+    .strict();
+const tellDeliverySchema = z
+    .object({
+    deliveredAt: timestampSchema,
+    route: z.enum(["launch", "live"]),
+    turnSequence: countSchema,
+    receipt: z.enum(["unavailable", "required"]).optional(),
+})
+    .strict()
+    .transform(({ receipt, ...delivery }) => (receipt === undefined ? delivery : { ...delivery, receipt }));
+const turnRowSchema = z
+    .object({
+    kind: z.literal("turn"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    bodySequence: countSchema,
+    at: timestampSchema,
+})
+    .strict();
+const callRowSchema = z
+    .object({
+    kind: z.literal("call"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    text: z.string(),
+})
+    .strict();
+const textRowSchema = (kind) => z
+    .object({
+    kind: z.literal(kind),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    text: z.string(),
+    truncated: z.literal(true).optional(),
+})
+    .strict();
+export const tellRowSchema = z
+    .object({
+    kind: z.literal("tell"),
+    sequence: countSchema,
+    at: timestampSchema,
+    tellId: nonblankTextSchema,
+    text: z.string(),
+    state: z.enum(["pending", "told"]),
+    deliveries: z.array(tellDeliverySchema).readonly(),
+})
+    .strict();
+const outcomeSchema = z.union([
+    z.object({ kind: z.literal("answered"), historyId: nonblankTextSchema, answer: z.string() }).strict(),
+    z.object({ kind: z.literal("failed"), historyId: nonblankTextSchema, diagnostic: z.string() }).strict(),
+]);
+const outcomeRowSchema = z
+    .object({
+    kind: z.literal("outcome"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    outcome: outcomeSchema,
+})
+    .strict();
+const activeToolRowSchema = z
+    .object({
+    kind: z.literal("tool"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    name: nonblankTextSchema,
+    call: toolCallSchema,
+    state: z.literal("active"),
+    truncated: z.literal(true).optional(),
+})
+    .strict();
+const completedToolRowSchema = z
+    .object({
+    kind: z.literal("tool"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    completedAt: timestampSchema.optional(),
+    durationMs: z.number().finite().nonnegative().optional(),
+    name: nonblankTextSchema,
+    call: toolCallSchema,
+    state: toolResultSchema,
+    truncated: z.literal(true).optional(),
+})
+    .strict();
+const unsettledToolRowSchema = z
+    .object({
+    kind: z.literal("tool"),
+    sequence: countSchema,
+    turnSequence: countSchema,
+    at: timestampSchema,
+    name: nonblankTextSchema,
+    call: toolCallSchema,
+    state: z.literal("unsettled"),
+    truncated: z.literal(true).optional(),
+})
+    .strict();
+const snapshotFactRowSchema = z.union([
+    callRowSchema,
+    textRowSchema("said"),
+    textRowSchema("thought"),
+    textRowSchema("note"),
+    tellRowSchema,
+]);
+const openSnapshotRowSchema = z.union([snapshotFactRowSchema, activeToolRowSchema, completedToolRowSchema]);
+const idleSnapshotRowSchema = z.union([snapshotFactRowSchema, completedToolRowSchema]);
+const snapshotEntrySchema = (row) => z.union([
+    z.object({ kind: z.literal("gap"), count: countSchema }).strict(),
+    z.object({ kind: z.literal("row"), row }).strict(),
+]);
+const reportedFileChangeSchema = z
+    .object({
+    sequence: countSchema,
+    at: timestampSchema,
+    op: z.enum(["add", "update", "delete", "unspecified"]),
+    path: z.string(),
+    diffstat: diffstatSchema.optional(),
+})
+    .strict();
+const reportedChangeFields = {
+    reportedChanges: z.array(reportedFileChangeSchema).readonly(),
+    reportedChangesOmitted: countSchema,
+};
+export const activitySnapshotSchema = z.union([
+    z
+        .object({
+        kind: z.literal("unborn"),
+        entries: z.tuple([]).readonly(),
+        omitted: z.literal(0),
+        ...reportedChangeFields,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("open"),
+        turn: turnRowSchema,
+        entries: z.array(snapshotEntrySchema(openSnapshotRowSchema)).readonly(),
+        omitted: countSchema,
+        ...reportedChangeFields,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("idle"),
+        outcome: outcomeRowSchema.optional(),
+        entries: z.array(snapshotEntrySchema(idleSnapshotRowSchema)).readonly(),
+        omitted: countSchema,
+        ...reportedChangeFields,
+    })
+        .strict(),
+]);
 function publicOutcome(turnSequence, outcome) {
     const historyId = `turn/${turnSequence}`;
     return outcome.kind === "answered"
@@ -207,15 +399,7 @@ export function projectTurns(facts, retained = {
                 turn.rows.push(row);
         }
         else if (fact.kind === "tell") {
-            state.tells.push({
-                kind: "tell",
-                sequence: fact.sequence,
-                at: fact.recordedAt,
-                tellId: fact.id,
-                text: fact.body,
-                state: fact.state,
-                deliveries: fact.deliveries,
-            });
+            state.tells.push(projectTell(fact));
         }
         else {
             projectActivityEvent(state, fact);

package/build/src/akuma/provider.d.ts

@@ -130,6 +130,33 @@ export type Session = Readonly<{
         text: string;
     }>): Promise<TellSubmission>;
 }>;
+/**
+ * Synchronous custody for one provider establishment or fork attempt.
+ * `closed` is the sole proof that every resource created by the attempt retired.
+ */
+export type ProviderAttempt<Result> = Readonly<{
+    result: Promise<Result>;
+    closed: Promise<void>;
+    abort(): Promise<void>;
+    forceDispose(): Promise<void>;
+}>;
+export type AttemptResource = Readonly<{
+    /** Resolves only when this physical resource has retired. */
+    closed: Promise<void>;
+    abort?(): Promise<void>;
+    forceDispose(): Promise<void>;
+}>;
+export type AttemptCustody = Readonly<{
+    signal: AbortSignal;
+    /** Register a resource in the attempt before awaiting further setup work. */
+    own(resource: AttemptResource): void;
+}>;
+/**
+ * Starts provider work after its caller has received custody.  The input signal
+ * remains a cancellation notification; this attempt owns its own controller
+ * and any resulting native resource controls.
+ */
+export declare function createProviderAttempt<Result>(parentSignal: AbortSignal | undefined, establish: (custody: AttemptCustody) => Promise<Result>): ProviderAttempt<Result>;
 export type DriveInput = Readonly<{
     body: string;
     launchTells: readonly Readonly<{
@@ -157,18 +184,18 @@ export type ProviderAdapter = Readonly<{
         session: ResumeCoordinate;
         at: string;
         cwd: string;
-    }>): Promise<Readonly<{
+    }>): ProviderAttempt<Readonly<{
         session: ResumeCoordinate;
     }>>;
     start(input: DriveInput & Readonly<{
         session: Readonly<{
             kind: "fresh";
         }>;
-    }>): Promise<Session>;
+    }>): ProviderAttempt<Session>;
     resume?(input: DriveInput & Readonly<{
         session: Readonly<{
             kind: "resume";
             coordinate: ResumeCoordinate;
         }>;
-    }>): Promise<Session>;
+    }>): ProviderAttempt<Session>;
 }>;

package/build/src/akuma/provider.js

@@ -344,3 +344,114 @@ export class AgentEventChannel {
         };
     }
 }
+/**
+ * Starts provider work after its caller has received custody.  The input signal
+ * remains a cancellation notification; this attempt owns its own controller
+ * and any resulting native resource controls.
+ */
+export function createProviderAttempt(parentSignal, establish) {
+    const parent = parentSignal ?? new AbortController().signal;
+    const controller = new AbortController();
+    const resources = [];
+    const ownedResources = new Map();
+    const cleanupFailures = [];
+    const cleanupOperations = [];
+    let setupComplete;
+    const setupSettled = new Promise((resolve) => {
+        setupComplete = resolve;
+    });
+    let establishmentSettled = false;
+    let retiring;
+    const remember = (operation, reportFailure) => {
+        const observed = operation.catch((error) => {
+            if (reportFailure)
+                cleanupFailures.push(error);
+        });
+        cleanupOperations.push(observed);
+        return operation;
+    };
+    const observeBackgroundRetirement = (operation) => {
+        void operation.catch(() => undefined);
+    };
+    const startRetirement = (owned, kind) => {
+        if (kind === "abort" && owned.resource.abort === undefined) {
+            const force = startRetirement(owned, "forceDispose");
+            owned.abort = force;
+            return force;
+        }
+        const existing = owned[kind];
+        if (existing !== undefined)
+            return existing;
+        const graceful = kind === "abort";
+        const dispose = graceful ? owned.resource.abort : owned.resource.forceDispose;
+        const operation = remember(Promise.resolve().then(() => dispose()), !graceful);
+        owned[kind] = operation;
+        return operation;
+    };
+    const retire = (kind) => {
+        if (kind === "forceDispose" || retiring === undefined)
+            retiring = kind;
+        const pending = resources.map((resource) => startRetirement(resource, kind));
+        return Promise.all(pending).then(() => undefined);
+    };
+    const own = (resource) => {
+        if (establishmentSettled)
+            throw new Error("cannot own a resource after provider establishment settles");
+        if (ownedResources.has(resource))
+            return;
+        const owned = { resource };
+        resources.push(owned);
+        ownedResources.set(resource, owned);
+        void resource.closed.catch((error) => {
+            cleanupFailures.push(error);
+        });
+        if (retiring !== undefined)
+            observeBackgroundRetirement(startRetirement(owned, retiring));
+    };
+    const cancelFromParent = () => {
+        if (!controller.signal.aborted)
+            controller.abort(parent.reason);
+        void retire("abort").catch(() => {
+            observeBackgroundRetirement(retire("forceDispose"));
+        });
+    };
+    parent.addEventListener("abort", cancelFromParent, { once: true });
+    if (parent.aborted)
+        cancelFromParent();
+    const result = Promise.resolve()
+        .then(() => establish({ signal: controller.signal, own }))
+        .catch((error) => {
+        if (!controller.signal.aborted)
+            observeBackgroundRetirement(retire("forceDispose"));
+        throw error;
+    })
+        .finally(() => {
+        establishmentSettled = true;
+        parent.removeEventListener("abort", cancelFromParent);
+    });
+    void result.then(() => setupComplete(), () => setupComplete());
+    const closed = (async () => {
+        await setupSettled;
+        for (;;) {
+            const operations = [...cleanupOperations];
+            const retired = resources.map((resource) => resource.resource.closed);
+            await Promise.allSettled([...operations, ...retired]);
+            if (operations.length === cleanupOperations.length)
+                break;
+        }
+        if (cleanupFailures.length > 0)
+            throw cleanupFailures[0];
+    })();
+    void closed.catch(() => undefined);
+    const control = async (operation) => {
+        if (!controller.signal.aborted)
+            controller.abort(new Error("provider attempt retired"));
+        await retire(operation);
+    };
+    return {
+        result,
+        closed,
+        abort: async () => await control("abort"),
+        forceDispose: async () => await control("forceDispose"),
+    };
+}

package/build/src/akuma/providers/acp/core.d.ts

@@ -1,6 +1,6 @@
 import type * as AcpSdk from "@agentclientprotocol/sdk";
 import { spawnStdioProcess } from "../../../runtime/proc/stdio.js";
-import { type ProviderAdapter, type Session } from "../../provider.js";
+import { type AttemptCustody, type ProviderAdapter, type Session } from "../../provider.js";
 import { type AcpToolInterpreter, type AcpToolUpdate } from "./events.js";
 export type { AcpToolInterpreter, AcpToolUpdate };
 export type AcpStartInput = Parameters<ProviderAdapter["start"]>[0] | Parameters<NonNullable<ProviderAdapter["resume"]>>[0];
@@ -21,4 +21,4 @@ type AcpLaunch = Readonly<{
     argv: readonly [string, ...string[]];
     env?: Readonly<Record<string, string>>;
 }>;
-export declare function startAcpSession(launch: AcpLaunch, input: AcpStartInput, dependencies?: AcpDependencies): Promise<AcpLiveSession>;
+export declare function startAcpSession(launch: AcpLaunch, input: AcpStartInput, dependencies?: AcpDependencies, custody?: AttemptCustody): Promise<AcpLiveSession>;

package/build/src/akuma/providers/acp/core.js

@@ -149,7 +149,7 @@ function beginAcpPrompt(context, child, turn, sessionId, input) {
         },
     };
 }
-export async function startAcpSession(launch, input, dependencies = {}) {
+export async function startAcpSession(launch, input, dependencies = {}, custody) {
     const acp = await import("@agentclientprotocol/sdk");
     const signal = input.signal ?? new AbortController().signal;
     signal.throwIfAborted();
@@ -162,6 +162,11 @@ export async function startAcpSession(launch, input, dependencies = {}) {
             ...(input.requests === undefined ? {} : { [AKUMA_REQUESTS_ENV]: input.requests.dir }),
         },
     });
+    custody?.own({
+        closed: child.exited.then(() => undefined),
+        abort: async () => await child.close(true),
+        forceDispose: async () => await child.close(true),
+    });
     let sessionId;
     let turn;
     const connection = createAcpClient(acp, (notification) => {
@@ -177,11 +182,13 @@ export async function startAcpSession(launch, input, dependencies = {}) {
     }
     catch (error) {
         connection.close(error);
-        try {
-            await child.close(true);
-        }
-        catch (cleanup) {
-            throw new Error(`${diagnostic(acp, error)}; ACP cleanup failed: ${diagnostic(acp, cleanup)}`, { cause: error });
+        if (custody === undefined) {
+            try {
+                await child.close(true);
+            }
+            catch (cleanup) {
+                throw new Error(`${diagnostic(acp, error)}; ACP cleanup failed: ${diagnostic(acp, cleanup)}`, { cause: error });
+            }
         }
         turn.events.end();
         throw error;

package/build/src/akuma/providers/acp/index.js

@@ -1,3 +1,4 @@
+import { createProviderAttempt } from "../../provider.js";
 import { decodeAcpConfig } from "./config.js";
 import { startAcpSession } from "./core.js";
 export { decodeAcpConfig } from "./config.js";
@@ -53,16 +54,16 @@ export function createAcpProvider(execution, dependencies = {}) {
     if (execution.executable === undefined)
         throw new TypeError("ACP provider execution requires executable");
     const config = decodeAcpConfig(execution.config);
-    const drive = async (input) => {
+    const drive = async (input, custody) => {
         const launch = {
             argv: argv(execution, config, input.options),
             ...(execution.env === undefined ? {} : { env: execution.env }),
         };
-        return (await startAcpSession(launch, input, dependencies)).session;
+        return (await startAcpSession(launch, input, dependencies, custody)).session;
     };
     return {
         admitOptions: (options) => optionAdmission(options, config),
-        start: async (input) => await drive(input),
-        resume: async (input) => await drive(input),
+        start: (input) => createProviderAttempt(input.signal, async (custody) => await drive({ ...input, signal: custody.signal }, custody)),
+        resume: (input) => createProviderAttempt(input.signal, async (custody) => await drive({ ...input, signal: custody.signal }, custody)),
     };
 }

package/build/src/akuma/providers/claude/events.d.ts

@@ -28,8 +28,8 @@ export declare const CLAUDE_SYSTEM_DISPOSITIONS: {
     readonly elicitation_complete: "drop";
     readonly files_persisted: "note";
     readonly hook_progress: "drop";
-    readonly hook_response: "drop";
-    readonly hook_started: "note";
+    readonly hook_response: "hook-response";
+    readonly hook_started: "drop";
     readonly informational: "note";
     readonly init: "drop";
     readonly local_command_output: "drop";

package/build/src/akuma/providers/claude/events.js

@@ -21,8 +21,8 @@ export const CLAUDE_SYSTEM_DISPOSITIONS = {
     elicitation_complete: "drop",
     files_persisted: "note",
     hook_progress: "drop",
-    hook_response: "drop",
-    hook_started: "note",
+    hook_response: "hook-response",
+    hook_started: "drop",
     informational: "note",
     init: "drop",
     local_command_output: "drop",
@@ -89,7 +89,6 @@ const CLAUDE_SYSTEM_NOTES = {
         const failed = Array.isArray(message.failed) ? message.failed.length : 0;
         return failed === 0 ? `Persisted ${files} files` : `Persisted ${files} files; ${failed} failed`;
     },
-    hook_started: (message) => `Hook ${nonblank(message.hook_name) ?? "unknown"} started`,
     informational: (message) => nonblank(message.content) ?? "Informational notice",
     mirror_error: (message) => `Transcript mirror warning: ${nonblank(message.error) ?? nonblank(message.message) ?? "unknown error"}`,
     model_refusal_fallback: () => "Model refusal; using fallback",
@@ -253,6 +252,14 @@ function toolResultEvents(message, events, state) {
         });
     }
 }
+function hookResponseNote(value) {
+    const outcome = nonblank(value.outcome);
+    if (outcome !== "error" && outcome !== "cancelled")
+        return undefined;
+    const hook = nonblank(value.hook_name) ?? "unknown";
+    const exitCode = number(value.exit_code);
+    return `Hook ${hook} ${outcome}${exitCode === undefined ? "" : ` (exit ${exitCode})`}`;
+}
 function emitSystemMessage(value, events) {
     const subtype = nonblank(value?.subtype) ?? "unknown";
     if (!Object.hasOwn(CLAUDE_SYSTEM_DISPOSITIONS, subtype)) {
@@ -262,6 +269,12 @@ function emitSystemMessage(value, events) {
     const systemDisposition = CLAUDE_SYSTEM_DISPOSITIONS[subtype];
     if (systemDisposition === "drop")
         return;
+    if (systemDisposition === "hook-response") {
+        const note = hookResponseNote(value);
+        if (note !== undefined)
+            events.emit(noteEvent(note));
+        return;
+    }
     if (systemDisposition === "control-progress" && value?.status !== "api_retry")
         return;
     const note = CLAUDE_SYSTEM_NOTES[subtype];

package/build/src/akuma/providers/claude/index.d.ts

@@ -27,18 +27,18 @@ export declare const claudeProvider: Readonly<{
         session: ResumeCoordinate;
         at: string;
         cwd: string;
-    }>): Promise<Readonly<{
+    }>): import("../../provider.js").ProviderAttempt<Readonly<{
         session: ResumeCoordinate;
     }>>;
     start(input: import("../../provider.js").DriveInput & Readonly<{
         session: Readonly<{
             kind: "fresh";
         }>;
-    }>): Promise<Session>;
+    }>): import("../../provider.js").ProviderAttempt<Session>;
     resume?(input: import("../../provider.js").DriveInput & Readonly<{
         session: Readonly<{
             kind: "resume";
             coordinate: ResumeCoordinate;
         }>;
-    }>): Promise<Session>;
+    }>): import("../../provider.js").ProviderAttempt<Session>;
 }>;

package/build/src/akuma/providers/claude/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { abortable } from "../../abort.js";
-import { AKUMA_REQUESTS_ENV, AgentEventChannel, } from "../../provider.js";
+import { AKUMA_REQUESTS_ENV, AgentEventChannel, createProviderAttempt, } from "../../provider.js";
 import { emitClaudeMessage } from "./events.js";
 import { claudeUserMessage, createClaudeInput, isClaudeTurnEnded } from "./input.js";
 export { CLAUDE_MESSAGE_DISPOSITIONS, CLAUDE_SYSTEM_DISPOSITIONS } from "./events.js";
@@ -282,7 +282,7 @@ function observeClaudeQuery(context) {
         settleReceipts,
     };
 }
-async function driveClaude(load, execution, drive) {
+async function driveClaude(load, execution, drive, custody) {
     if (drive.session.kind === "resume")
         claudeSessionId(drive.session.coordinate);
     const signal = drive.signal ?? new AbortController().signal;
@@ -324,6 +324,17 @@ async function driveClaude(load, execution, drive) {
             },
         },
     });
+    custody.own({
+        closed: observed.completion.then(() => undefined),
+        abort: async () => {
+            shutDown(new Error("Claude query aborted"));
+            await observed.completion;
+        },
+        forceDispose: async () => {
+            shutDown(new Error("Claude query force-disposed"));
+            await observed.completion;
+        },
+    });
     if (signal.aborted)
         abortSetup();
     try {
@@ -356,9 +367,9 @@ export function createClaudeProvider(loadOrExecution = async () => (await import
     const selectedExecution = typeof loadOrExecution === "function" ? execution : loadOrExecution;
     return {
         admitOptions: admitClaudeOptions,
-        fork: (input) => forkClaude(load, selectedExecution, input),
-        start: (input) => driveClaude(load, selectedExecution, input),
-        resume: (input) => driveClaude(load, selectedExecution, input),
+        fork: (input) => createProviderAttempt(new AbortController().signal, async () => await forkClaude(load, selectedExecution, input)),
+        start: (input) => createProviderAttempt(input.signal, async (custody) => await driveClaude(load, selectedExecution, { ...input, signal: custody.signal }, custody)),
+        resume: (input) => createProviderAttempt(input.signal, async (custody) => await driveClaude(load, selectedExecution, { ...input, signal: custody.signal }, custody)),
     };
 }
 export const claudeProvider = createClaudeProvider(async () => (await import("@anthropic-ai/claude-agent-sdk")));

package/build/src/akuma/providers/codex-app-server/events.d.ts

@@ -26,8 +26,8 @@ export declare const CODEX_NOTIFICATION_DISPOSITIONS: {
     readonly "fuzzyFileSearch/sessionCompleted": "drop";
     readonly "fuzzyFileSearch/sessionUpdated": "drop";
     readonly guardianWarning: "note";
-    readonly "hook/completed": "drop";
-    readonly "hook/started": "note";
+    readonly "hook/completed": "hook-completed";
+    readonly "hook/started": "drop";
     readonly "item/agentMessage/delta": "drop";
     readonly "item/autoApprovalReview/completed": "note";
     readonly "item/autoApprovalReview/started": "note";

package/build/src/akuma/providers/codex-app-server/events.js

@@ -15,8 +15,8 @@ export const CODEX_NOTIFICATION_DISPOSITIONS = {
     "fuzzyFileSearch/sessionCompleted": "drop",
     "fuzzyFileSearch/sessionUpdated": "drop",
     guardianWarning: "note",
-    "hook/completed": "drop",
-    "hook/started": "note",
+    "hook/completed": "hook-completed",
+    "hook/started": "drop",
     "item/agentMessage/delta": "drop",
     "item/autoApprovalReview/completed": "note",
     "item/autoApprovalReview/started": "note",
@@ -273,8 +273,6 @@ function notificationAction(method, params) {
             return "Filesystem changed";
         case "guardianWarning":
             return `Guardian warning: ${message ?? "action warned"}`;
-        case "hook/started":
-            return `Hook ${codexText(params.name) ?? codexText(params.hookName) ?? "unknown"} started`;
         case "item/autoApprovalReview/completed":
             return "Action approval review completed";
         case "item/autoApprovalReview/started":
@@ -299,6 +297,23 @@ function notificationAction(method, params) {
             return method;
     }
 }
+function hookCompletionNote(params) {
+    const run = codexObject(params.run);
+    const status = codexText(run?.status);
+    const issue = Array.isArray(run?.entries)
+        ? run.entries.map(codexObject).find((entry) => {
+            const kind = codexText(entry?.kind);
+            return kind === "warning" || kind === "error" || kind === "stop";
+        })
+        : undefined;
+    const issueKind = codexText(issue?.kind);
+    if (status !== "failed" && status !== "blocked" && status !== "stopped" && issueKind === undefined)
+        return undefined;
+    const eventName = codexText(run?.eventName) ?? "unknown";
+    const label = status === "failed" || status === "blocked" || status === "stopped" ? status : issueKind;
+    const diagnostic = codexText(run?.statusMessage) ?? codexText(issue?.text);
+    return `Hook ${eventName} ${label}${diagnostic === undefined ? "" : `: ${diagnostic}`}`;
+}
 function observeError(params, state, events) {
     const detail = turnError(params.error) ?? codexText(params.message) ?? "codex app-server error";
     state.error = detail;
@@ -328,6 +343,12 @@ export function codexNotificationResult(notification, state, events) {
     switch (disposition) {
         case "drop":
             return undefined;
+        case "hook-completed": {
+            const note = hookCompletionNote(params);
+            if (note !== undefined)
+                events.emit(noteEvent(note));
+            return undefined;
+        }
         case "note":
             events.emit(noteEvent(notificationAction(method, params)));
             return undefined;