@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/daemon/handlers/sessions-handlers.js

@@ -0,0 +1,31 @@
+import { defaultIndexDbPath } from "#mcp/tools/session-restore.js";
+import { listDaemonSessions } from "#daemon/domains/run-registry-interop.js";
+import { createSessionMemorySearchBackend, searchSessions, } from "#daemon/domains/sessions-search.js";
+import { asRecord, requireString } from "./shared.js";
+/**
+ * Build session-domain handlers scoped to `repoRoot`. `repoRoot` doubles as
+ * the dash run-registry cwd (sessions.list) and the session-memory index
+ * root (sessions.search) — both already resolve per-repo paths on their own.
+ */
+export function createSessionsHandlers(repoRoot) {
+    return {
+        "sessions.list": async (_session, params) => {
+            const record = asRecord(params);
+            const limit = typeof record.limit === "number" ? record.limit : undefined;
+            return listDaemonSessions({ cwd: repoRoot, limit });
+        },
+        "sessions.search": (_session, params) => {
+            const record = asRecord(params);
+            const query = requireString(record, "query");
+            const limit = typeof record.limit === "number" ? record.limit : undefined;
+            const backend = createSessionMemorySearchBackend(defaultIndexDbPath(repoRoot));
+            const hits = searchSessions(backend, { query, limit });
+            return { hits };
+        },
+        "launch.permissionState": () => ({
+            mode: "safe",
+            yoloPreference: false,
+            isolationWarning: "permission state is advisory until full permission UX lands",
+        }),
+    };
+}

package/dist/esm/daemon/handlers/shared.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared parameter-parsing helpers for daemon product-domain handlers.
+ */
+export declare function asRecord(params: unknown): Record<string, unknown>;
+export declare function requireString(record: Record<string, unknown>, key: string): string;

package/dist/esm/daemon/handlers/shared.js

@@ -0,0 +1,16 @@
+/**
+ * Shared parameter-parsing helpers for daemon product-domain handlers.
+ */
+export function asRecord(params) {
+    if (params === null || typeof params !== "object" || Array.isArray(params)) {
+        return {};
+    }
+    return params;
+}
+export function requireString(record, key) {
+    const v = record[key];
+    if (typeof v !== "string" || v.length === 0) {
+        throw new Error(`missing string param: ${key}`);
+    }
+    return v;
+}

package/dist/esm/daemon/methods.d.ts

@@ -92,6 +92,13 @@ export declare const DAEMON_METHOD_REGISTRY: {
         readonly requireHandshake: true;
         readonly uiFacing: true;
     };
+    readonly "sessions.search": {
+        readonly privileged: true;
+        readonly requiresConfirmation: false;
+        readonly mutates: false;
+        readonly requireHandshake: true;
+        readonly uiFacing: true;
+    };
     readonly "git.diff": {
         readonly privileged: true;
         readonly requiresConfirmation: false;
@@ -164,7 +171,7 @@ export type UiRpcMethod = {
     [M in DaemonRpcMethod]: (typeof DAEMON_METHOD_REGISTRY)[M]["uiFacing"] extends true ? M : never;
 }[DaemonRpcMethod];
 export declare const UI_RPC_METHODS: UiRpcMethod[];
-export declare const DESTRUCTIVE_METHODS: ("auth.issueNonce" | "blueprints.exec" | "blueprints.list" | "daemon.envMap.push" | "deploy.run" | "fleet.status" | "git.commit" | "git.createPr" | "git.diff" | "handshake" | "launch.claim" | "launch.permissionState" | "launch.prepare" | "ping" | "sessions.list" | "worktrees.list")[];
+export declare const DESTRUCTIVE_METHODS: ("auth.issueNonce" | "blueprints.exec" | "blueprints.list" | "daemon.envMap.push" | "deploy.run" | "fleet.status" | "git.commit" | "git.createPr" | "git.diff" | "handshake" | "launch.claim" | "launch.permissionState" | "launch.prepare" | "ping" | "sessions.list" | "sessions.search" | "worktrees.list")[];
 export declare function getMethodCapability(method: string): MethodCapability | null;
 export declare function isDaemonRpcMethod(method: string): method is DaemonRpcMethod;
 export declare function isUiRpcMethod(method: string): method is UiRpcMethod;

package/dist/esm/daemon/methods.js

@@ -60,6 +60,13 @@ export const DAEMON_METHOD_REGISTRY = {
         requireHandshake: true,
         uiFacing: true,
     },
+    "sessions.search": {
+        privileged: true,
+        requiresConfirmation: false,
+        mutates: false,
+        requireHandshake: true,
+        uiFacing: true,
+    },
     "git.diff": {
         privileged: true,
         requiresConfirmation: false,

package/dist/esm/daemon/protocol/contract.d.ts

@@ -92,6 +92,7 @@ export declare const daemonRpcMethodSchema: z.ZodEnum<{
     "launch.prepare": "launch.prepare";
     ping: "ping";
     "sessions.list": "sessions.list";
+    "sessions.search": "sessions.search";
     "worktrees.list": "worktrees.list";
 }>;
 export declare const uiRpcMethodSchema: z.ZodEnum<{
@@ -108,6 +109,7 @@ export declare const uiRpcMethodSchema: z.ZodEnum<{
     "launch.prepare": "launch.prepare";
     ping: "ping";
     "sessions.list": "sessions.list";
+    "sessions.search": "sessions.search";
     "worktrees.list": "worktrees.list";
 }>;
 export declare const pingParamsSchema: z.ZodObject<{}, z.core.$strict>;
@@ -212,6 +214,32 @@ export declare const sessionsListResultSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type SessionsListResult = z.infer<typeof sessionsListResultSchema>;
+/**
+ * No db-path override fields: path safety requires the daemon resolve its
+ * own index db path from its configured repoRoot, never from a
+ * webview-supplied param.
+ */
+export declare const sessionsSearchParamsSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SessionsSearchParams = z.infer<typeof sessionsSearchParamsSchema>;
+export declare const sessionSearchHitSchema: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodString;
+    text: z.ZodString;
+    score: z.ZodNumber;
+}, z.core.$strict>;
+export type SessionSearchHitResult = z.infer<typeof sessionSearchHitSchema>;
+export declare const sessionsSearchResultSchema: z.ZodObject<{
+    hits: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source: z.ZodString;
+        text: z.ZodString;
+        score: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SessionsSearchResult = z.infer<typeof sessionsSearchResultSchema>;
 export declare const gitDiffParamsSchema: z.ZodObject<{
     cwd: z.ZodString;
 }, z.core.$strict>;
@@ -255,6 +283,7 @@ export declare const fleetStatusResultSchema: z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export type FleetStatusResult = z.infer<typeof fleetStatusResultSchema>;
 export declare const worktreesListParamsSchema: z.ZodObject<{
     repoRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -387,6 +416,20 @@ export declare const UI_METHOD_SCHEMAS: {
             }, z.core.$strict>>;
         }, z.core.$strict>;
     };
+    readonly "sessions.search": {
+        readonly params: z.ZodObject<{
+            query: z.ZodString;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            hits: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                source: z.ZodString;
+                text: z.ZodString;
+                score: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    };
     readonly "git.diff": {
         readonly params: z.ZodObject<{
             cwd: z.ZodString;

package/dist/esm/daemon/protocol/contract.js

@@ -189,6 +189,31 @@ export const sessionsListResultSchema = z
     sessions: z.array(sessionSummarySchema),
 })
     .strict();
+// --- sessions.search ---
+/**
+ * No db-path override fields: path safety requires the daemon resolve its
+ * own index db path from its configured repoRoot, never from a
+ * webview-supplied param.
+ */
+export const sessionsSearchParamsSchema = z
+    .object({
+    query: z.string().min(1).max(4_096),
+    limit: z.number().int().positive().max(100).optional(),
+})
+    .strict();
+export const sessionSearchHitSchema = z
+    .object({
+    id: z.string().min(1),
+    source: z.string().min(1),
+    text: z.string(),
+    score: z.number(),
+})
+    .strict();
+export const sessionsSearchResultSchema = z
+    .object({
+    hits: z.array(sessionSearchHitSchema),
+})
+    .strict();
 // --- git (stubs) ---
 export const gitDiffParamsSchema = z
     .object({
@@ -311,6 +336,7 @@ export const UI_METHOD_SCHEMAS = {
         result: launchPermissionStateResultSchema,
     },
     "sessions.list": { params: sessionsListParamsSchema, result: sessionsListResultSchema },
+    "sessions.search": { params: sessionsSearchParamsSchema, result: sessionsSearchResultSchema },
     "git.diff": { params: gitDiffParamsSchema, result: gitDiffResultSchema },
     "git.commit": { params: gitCommitParamsSchema, result: gitCommitResultSchema },
     "git.createPr": { params: gitCreatePrParamsSchema, result: gitCreatePrResultSchema },

package/dist/esm/daemon/protocol/index.d.ts

@@ -5,4 +5,4 @@
  * - `#daemon/protocol` (repo-internal package imports)
  * - `@webpresso/agent-kit/daemon/protocol` (published subpath)
  */
-export { DAEMON_PROTOCOL_VERSION, DAEMON_SESSION_MEMORY_SCHEMA_VERSION, DAEMON_RPC_METHODS, RUST_CHANNEL_METHODS, FORBIDDEN_UI_PAYLOAD_KEYS, UI_METHOD_SCHEMAS, opaqueHandleSchema, permissionModeSchema, providerIdSchema, peerRoleSchema, daemonRpcMethodSchema, handshakeParamsSchema, handshakeResultSchema, pingParamsSchema, pingResultSchema, launchPrepareParamsSchema, launchPrepareResultSchema, launchPermissionStateParamsSchema, launchPermissionStateResultSchema, sessionsListParamsSchema, sessionSummarySchema, sessionsListResultSchema, gitDiffParamsSchema, gitDiffResultSchema, gitCommitParamsSchema, gitCommitResultSchema, gitCreatePrParamsSchema, gitCreatePrResultSchema, fleetStatusParamsSchema, fleetStatusResultSchema, worktreesListParamsSchema, worktreesListResultSchema, blueprintsListParamsSchema, blueprintsListResultSchema, blueprintsExecParamsSchema, blueprintsExecResultSchema, deployRunParamsSchema, deployRunResultSchema, rustSpawnEnvMapSchema, rustSpawnEnvDeliverySchema, sessionExitNotificationSchema, jsonRpcIdSchema, jsonRpcRequestSchema, jsonRpcErrorObjectSchema, jsonRpcSuccessResponseSchema, jsonRpcErrorResponseSchema, jsonRpcResponseSchema, isDaemonRpcMethod, isUiRpcMethod, isRustChannelMethod, UI_RPC_METHODS, parseUiMethodParams, parseUiMethodResult, safeParseUiMethodParams, safeParseUiMethodResult, buildHandshakeResult, payloadHasForbiddenUiKeys, type OpaqueHandle, type PermissionMode, type ProviderId, type PeerRole, type ForbiddenUiPayloadKey, type HandshakeParams, type HandshakeResult, type DaemonRpcMethod, type PingParams, type PingResult, type LaunchPrepareParams, type LaunchPrepareResult, type LaunchPermissionStateParams, type LaunchPermissionStateResult, type SessionsListParams, type SessionSummary, type SessionsListResult, type GitDiffParams, type GitDiffResult, type GitCommitParams, type GitCommitResult, type GitCreatePrParams, type GitCreatePrResult, type RustSpawnEnvMap, type RustSpawnEnvDelivery, type RustChannelMethod, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse, type MethodSchemaPair, type UiMethodSchemas, } from "./contract.js";
+export { DAEMON_PROTOCOL_VERSION, DAEMON_SESSION_MEMORY_SCHEMA_VERSION, DAEMON_RPC_METHODS, RUST_CHANNEL_METHODS, FORBIDDEN_UI_PAYLOAD_KEYS, UI_METHOD_SCHEMAS, opaqueHandleSchema, permissionModeSchema, providerIdSchema, peerRoleSchema, daemonRpcMethodSchema, handshakeParamsSchema, handshakeResultSchema, pingParamsSchema, pingResultSchema, launchPrepareParamsSchema, launchPrepareResultSchema, launchPermissionStateParamsSchema, launchPermissionStateResultSchema, sessionsListParamsSchema, sessionSummarySchema, sessionsListResultSchema, sessionsSearchParamsSchema, sessionSearchHitSchema, sessionsSearchResultSchema, gitDiffParamsSchema, gitDiffResultSchema, gitCommitParamsSchema, gitCommitResultSchema, gitCreatePrParamsSchema, gitCreatePrResultSchema, fleetStatusParamsSchema, fleetStatusResultSchema, worktreesListParamsSchema, worktreesListResultSchema, blueprintsListParamsSchema, blueprintsListResultSchema, blueprintsExecParamsSchema, blueprintsExecResultSchema, deployRunParamsSchema, deployRunResultSchema, rustSpawnEnvMapSchema, rustSpawnEnvDeliverySchema, sessionExitNotificationSchema, jsonRpcIdSchema, jsonRpcRequestSchema, jsonRpcErrorObjectSchema, jsonRpcSuccessResponseSchema, jsonRpcErrorResponseSchema, jsonRpcResponseSchema, isDaemonRpcMethod, isUiRpcMethod, isRustChannelMethod, UI_RPC_METHODS, parseUiMethodParams, parseUiMethodResult, safeParseUiMethodParams, safeParseUiMethodResult, buildHandshakeResult, payloadHasForbiddenUiKeys, type OpaqueHandle, type PermissionMode, type ProviderId, type PeerRole, type ForbiddenUiPayloadKey, type HandshakeParams, type HandshakeResult, type DaemonRpcMethod, type PingParams, type PingResult, type LaunchPrepareParams, type LaunchPrepareResult, type LaunchPermissionStateParams, type LaunchPermissionStateResult, type SessionsListParams, type SessionSummary, type SessionsListResult, type SessionsSearchParams, type SessionSearchHitResult, type SessionsSearchResult, type GitDiffParams, type GitDiffResult, type GitCommitParams, type GitCommitResult, type GitCreatePrParams, type GitCreatePrResult, type FleetStatusResult, type RustSpawnEnvMap, type RustSpawnEnvDelivery, type RustChannelMethod, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse, type MethodSchemaPair, type UiMethodSchemas, } from "./contract.js";

package/dist/esm/daemon/protocol/index.js

@@ -5,4 +5,4 @@
  * - `#daemon/protocol` (repo-internal package imports)
  * - `@webpresso/agent-kit/daemon/protocol` (published subpath)
  */
-export { DAEMON_PROTOCOL_VERSION, DAEMON_SESSION_MEMORY_SCHEMA_VERSION, DAEMON_RPC_METHODS, RUST_CHANNEL_METHODS, FORBIDDEN_UI_PAYLOAD_KEYS, UI_METHOD_SCHEMAS, opaqueHandleSchema, permissionModeSchema, providerIdSchema, peerRoleSchema, daemonRpcMethodSchema, handshakeParamsSchema, handshakeResultSchema, pingParamsSchema, pingResultSchema, launchPrepareParamsSchema, launchPrepareResultSchema, launchPermissionStateParamsSchema, launchPermissionStateResultSchema, sessionsListParamsSchema, sessionSummarySchema, sessionsListResultSchema, gitDiffParamsSchema, gitDiffResultSchema, gitCommitParamsSchema, gitCommitResultSchema, gitCreatePrParamsSchema, gitCreatePrResultSchema, fleetStatusParamsSchema, fleetStatusResultSchema, worktreesListParamsSchema, worktreesListResultSchema, blueprintsListParamsSchema, blueprintsListResultSchema, blueprintsExecParamsSchema, blueprintsExecResultSchema, deployRunParamsSchema, deployRunResultSchema, rustSpawnEnvMapSchema, rustSpawnEnvDeliverySchema, sessionExitNotificationSchema, jsonRpcIdSchema, jsonRpcRequestSchema, jsonRpcErrorObjectSchema, jsonRpcSuccessResponseSchema, jsonRpcErrorResponseSchema, jsonRpcResponseSchema, isDaemonRpcMethod, isUiRpcMethod, isRustChannelMethod, UI_RPC_METHODS, parseUiMethodParams, parseUiMethodResult, safeParseUiMethodParams, safeParseUiMethodResult, buildHandshakeResult, payloadHasForbiddenUiKeys, } from "./contract.js";
+export { DAEMON_PROTOCOL_VERSION, DAEMON_SESSION_MEMORY_SCHEMA_VERSION, DAEMON_RPC_METHODS, RUST_CHANNEL_METHODS, FORBIDDEN_UI_PAYLOAD_KEYS, UI_METHOD_SCHEMAS, opaqueHandleSchema, permissionModeSchema, providerIdSchema, peerRoleSchema, daemonRpcMethodSchema, handshakeParamsSchema, handshakeResultSchema, pingParamsSchema, pingResultSchema, launchPrepareParamsSchema, launchPrepareResultSchema, launchPermissionStateParamsSchema, launchPermissionStateResultSchema, sessionsListParamsSchema, sessionSummarySchema, sessionsListResultSchema, sessionsSearchParamsSchema, sessionSearchHitSchema, sessionsSearchResultSchema, gitDiffParamsSchema, gitDiffResultSchema, gitCommitParamsSchema, gitCommitResultSchema, gitCreatePrParamsSchema, gitCreatePrResultSchema, fleetStatusParamsSchema, fleetStatusResultSchema, worktreesListParamsSchema, worktreesListResultSchema, blueprintsListParamsSchema, blueprintsListResultSchema, blueprintsExecParamsSchema, blueprintsExecResultSchema, deployRunParamsSchema, deployRunResultSchema, rustSpawnEnvMapSchema, rustSpawnEnvDeliverySchema, sessionExitNotificationSchema, jsonRpcIdSchema, jsonRpcRequestSchema, jsonRpcErrorObjectSchema, jsonRpcSuccessResponseSchema, jsonRpcErrorResponseSchema, jsonRpcResponseSchema, isDaemonRpcMethod, isUiRpcMethod, isRustChannelMethod, UI_RPC_METHODS, parseUiMethodParams, parseUiMethodResult, safeParseUiMethodParams, safeParseUiMethodResult, buildHandshakeResult, payloadHasForbiddenUiKeys, } from "./contract.js";

package/dist/esm/hooks/__conformance__/matrix.d.ts

@@ -24,6 +24,12 @@ export type WebpressoHookBin = (typeof WEBPRESSO_HOOK_BINS)[number];
 export type HookRunResult = {
     readonly stdout: string;
     readonly exitCode: number | null;
+    /**
+     * Captured stderr, when the runner provides it. Claude reads stderr as the
+     * blocking feedback on an exit-2 PreToolUse deny, so the coded reason is
+     * asserted here when the stdout envelope carries none.
+     */
+    readonly stderr?: string;
 };
 type BaseRow = {
     readonly name: string;

package/dist/esm/hooks/__conformance__/matrix.js

@@ -110,6 +110,96 @@ function denyDecision(obj) {
         return "deny";
     return null;
 }
+/** Extract the host-displayed deny reason from either envelope shape. */
+function denyReasonText(obj) {
+    const hookSpecific = obj?.hookSpecificOutput;
+    if (hookSpecific && typeof hookSpecific === "object") {
+        const reason = hookSpecific.permissionDecisionReason;
+        if (typeof reason === "string")
+            return reason;
+    }
+    // Grok dual envelope carries a top-level reason.
+    if (typeof obj?.reason === "string")
+        return obj.reason;
+    return null;
+}
+const GUARD_CODED_REASON_RE = /^GUARD_[A-Z0-9_]+: /u;
+/**
+ * Every PreToolUse deny reason on a parseable stdout envelope carries a stable
+ * `GUARD_<CODE>: ` prefix within the 80-char permissionDecisionReason budget.
+ * The code is the cross-host contract; the prose is truncated to fit.
+ *
+ * This reads `result.stdout` directly (NOT the decision-path `obj`, which is
+ * null for a Claude exit-2 deny) so the coded reason is asserted on BOTH hosts —
+ * pretool-guard always prints the deny envelope to stdout (dual for claude/grok,
+ * hookSpecificOutput-only for codex) even when Claude reads the exit code for the
+ * decision itself. Non-JSON stdout (the synthetic "stdout is ignored" fixture)
+ * and the empty-stdout exit-code-deny convention carry no reason and are skipped.
+ */
+/** Parse an optional deny reason out of a JSON stdout deny envelope. */
+function stdoutDenyReason(stdout) {
+    const text = stdout.trim();
+    if (text === "")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    return denyReasonText(parsed);
+}
+/** First GUARD_-coded line in a captured stderr blob (Claude's exit-2 channel). */
+function stderrCodedReason(stderr) {
+    if (!stderr)
+        return null;
+    for (const line of stderr.split("\n")) {
+        if (GUARD_CODED_REASON_RE.test(line.trim()))
+            return line.trim();
+    }
+    return null;
+}
+/** Assert a single reason is GUARD_-coded and within the 80-code-point budget. */
+function assertCodedWithinBudget(row, label, reason) {
+    if (!GUARD_CODED_REASON_RE.test(reason)) {
+        throw new Error(`[${row.name}] ${label} must start with a GUARD_ code prefix, got ${JSON.stringify(reason)}`);
+    }
+    const points = [...reason].length;
+    if (points > 80) {
+        throw new Error(`[${row.name}] ${label} exceeds the 80-code-point budget (${points}): ${JSON.stringify(reason)}`);
+    }
+}
+function assertGuardCodedDenyReason(row, result) {
+    // The coded reason must reach the host on the channel it reads: the stdout
+    // deny envelope (Codex/Grok) or stderr (Claude reads stderr on an exit-2
+    // PreToolUse deny). Single-spawn tests capture the host boundary directly;
+    // the batch runner installs a row-scoped intentional-stderr capture so this
+    // same assertion also applies to source/compiled parity.
+    const reason = stdoutDenyReason(result.stdout) ?? stderrCodedReason(result.stderr);
+    if (reason === null) {
+        throw new Error(`[${row.name}] a PreToolUse deny must carry a GUARD_-coded reason on the stdout envelope or stderr; found none`);
+    }
+    assertCodedWithinBudget(row, "deny reason", reason);
+}
+function assertCodexExitTwoBlockingReason(row, result) {
+    if (row.host !== "codex" ||
+        row.event !== "PreToolUse" ||
+        result.exitCode !== 2 ||
+        result.stderr === undefined) {
+        return;
+    }
+    const stderrReason = stderrCodedReason(result.stderr);
+    if (stderrReason === null) {
+        throw new Error(`[${row.name}] Codex exit-2 PreToolUse deny must write a GUARD_-coded blocking reason to stderr`);
+    }
+    const stdoutReason = stdoutDenyReason(result.stdout);
+    if (stdoutReason !== null && stderrReason !== stdoutReason) {
+        throw new Error(`[${row.name}] Codex stdout and stderr deny reasons must match exactly`);
+    }
+}
 /** PermissionRequest golden wire: hookSpecificOutput.decision.behavior allow|deny. */
 function permissionRequestBehavior(obj) {
     const hookSpecific = obj?.hookSpecificOutput;
@@ -121,6 +211,45 @@ function permissionRequestBehavior(obj) {
     const behavior = decision.behavior;
     return typeof behavior === "string" ? behavior : null;
 }
+/** PermissionRequest golden wire message: hookSpecificOutput.decision.message. */
+function permissionRequestMessage(obj) {
+    const hookSpecific = obj?.hookSpecificOutput;
+    if (!hookSpecific || typeof hookSpecific !== "object")
+        return null;
+    const decision = hookSpecific.decision;
+    if (!decision || typeof decision !== "object")
+        return null;
+    const message = decision.message;
+    return typeof message === "string" ? message : null;
+}
+/**
+ * A PermissionRequest allow/deny message on a parseable envelope carries the
+ * same `GUARD_<CODE>: ` prefix within the 80-char budget as PreToolUse denies —
+ * the vocabulary is central, not PreToolUse-only. Skipped when there is no
+ * envelope message (e.g. a pure exit-2 deny with no stdout).
+ */
+function assertGuardCodedPermissionMessage(row, result, expect) {
+    let stdoutMessage = null;
+    const text = result.stdout.trim();
+    if (text !== "") {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed !== null && typeof parsed === "object") {
+                stdoutMessage = permissionRequestMessage(parsed);
+            }
+        }
+        catch {
+            stdoutMessage = null;
+        }
+    }
+    // A deny exits 2 and also carries the coded message on stderr; an allow exits 0
+    // with the coded message on the stdout envelope.
+    const message = stdoutMessage ?? stderrCodedReason(result.stderr);
+    if (message === null) {
+        throw new Error(`[${row.name}] PermissionRequest ${expect} must carry a GUARD_-coded message on the stdout envelope or stderr; found none`);
+    }
+    assertCodedWithinBudget(row, "PermissionRequest message", message);
+}
 function assertNoCodexUnsupportedFields(row, obj) {
     if (row.host !== "codex" || obj === null)
         return;
@@ -170,6 +299,11 @@ export function assertConformance(row, result) {
                 // exit-code deny convention). A deny envelope printed just before the hook
                 // crashes (exit 1) is not a valid decision.
                 assertExitCode(row, result, true);
+                // Every deny reason is GUARD_-coded and within the 80-char budget on
+                // both Tier-1 hosts (read from stdout, which carries the envelope even
+                // when Claude uses the exit code for the decision).
+                assertGuardCodedDenyReason(row, result);
+                assertCodexExitTwoBlockingReason(row, result);
             }
             else {
                 if (decision === "deny") {
@@ -196,6 +330,8 @@ export function assertConformance(row, result) {
                 if (result.exitCode !== 2) {
                     throw new Error(`[${row.name}] expected PermissionRequest deny via exit 2, got exit ${result.exitCode ?? "null"}`);
                 }
+                // The deny message carries the central GUARD_ code contract too.
+                assertGuardCodedPermissionMessage(row, result, "deny");
                 return;
             }
             if (row.expect === "allow") {
@@ -203,6 +339,7 @@ export function assertConformance(row, result) {
                     throw new Error(`[${row.name}] expected PermissionRequest allow envelope, got behavior=${behavior ?? "none"} (stdout: ${result.stdout.slice(0, 160)})`);
                 }
                 assertExitCode(row, result, false);
+                assertGuardCodedPermissionMessage(row, result, "allow");
                 return;
             }
             // pass-through: host default UI — empty object (or empty stdout), no decision, exit 0.

package/dist/esm/hooks/conformance/batch.js

@@ -85,6 +85,7 @@ export async function runHookConformanceBatch() {
     }
     const raw = await readBatchStdin();
     const { isHookName, runHookCommand } = await import("#cli/commands/hook.js");
+    const { installGuardStderrCapture } = await import("#hooks/shared/hook-bootstrap");
     const payload = parseBatchPayload(raw, isHookName);
     const protocolWrite = process.stdout.write.bind(process.stdout);
     for (const row of payload.rows) {
@@ -92,6 +93,9 @@ export async function runHookConformanceBatch() {
         let stdout = "";
         let stderr = "";
         const restoreEnv = setRowEnvironment(row);
+        const restoreGuardStderrCapture = installGuardStderrCapture((text) => {
+            stderr += text;
+        });
         const originalStdoutWrite = process.stdout.write;
         const originalStderrWrite = process.stderr.write;
         process.stdout.write = (chunk) => {
@@ -112,6 +116,7 @@ export async function runHookConformanceBatch() {
         finally {
             process.stdout.write = originalStdoutWrite;
             process.stderr.write = originalStderrWrite;
+            restoreGuardStderrCapture();
             restoreEnv();
         }
         protocolWrite(`${JSON.stringify({ type: "result", id: row.id, stdout, stderr, exitCode })}\n`);

package/dist/esm/hooks/doctor.d.ts

@@ -124,9 +124,9 @@ export interface ClaudeMcpDuplicateRegistrationOptions {
 /**
  * `claude-mcp-duplicate-registration` — advisory. A machine can register the
  * webpresso MCP server twice for the same Claude Code session: a manual
- * `claude mcp add webpresso` entry in `~/.claude.json` (user scope or a
- * project scope) plus the agent-kit marketplace plugin's bundled server
- * (plugin cache under `~/.claude/plugins/`). Both spawn `wp mcp`, so affected
+ * `claude mcp add webpresso` entry in Claude Code's home JSON config (user
+ * scope or a project scope) plus the agent-kit marketplace plugin's bundled
+ * server from the Claude plugin cache. Both spawn `wp mcp`, so affected
  * sessions run two server processes and carry a duplicated wp_* tool list.
  * Degrades to ok on missing/unreadable config — loud only on real duplication.
  */

package/dist/esm/hooks/doctor.js

@@ -658,11 +658,15 @@ function probeDecisionRow(wpCli, row) {
             detached: process.platform !== "win32",
         });
         let stdout = "";
+        let stderr = "";
         const timeoutMs = hookProbeTimeoutMs();
         const settle = createOwnedProbeSettler(child, timeoutMs, () => ({ ok: false, detail: `decision probe timed out after ${timeoutMs}ms` }), resolve);
         child.stdout.on("data", (chunk) => {
             stdout += String(chunk);
         });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
         child.stdin.on?.("error", (err) => {
             settle({ ok: false, detail: `stdin write failed: ${err.message}` });
         });
@@ -674,7 +678,7 @@ function probeDecisionRow(wpCli, row) {
         });
         child.on("close", (code) => {
             try {
-                assertConformance(row, { stdout, exitCode: code });
+                assertConformance(row, { stdout, stderr, exitCode: code });
                 settle({ ok: true });
             }
             catch (error) {
@@ -1256,13 +1260,15 @@ async function checkClaudeHost() {
 }
 async function checkGrokHost(cwd = process.cwd()) {
     const available = await runCommand("grok", ["--version"]);
-    const hooksPath = join(cwd, ".grok", "hooks.json");
+    const hooksPath = join(cwd, ".grok", "hooks", "webpresso.json");
     let hooksPresent = false;
     let hostLabeled = false;
     try {
         const body = readFileSync(hooksPath, "utf8");
         hooksPresent = true;
-        hostLabeled = body.includes("WP_HOOK_HOST=grok");
+        // The generated launcher chain shell-quotes the value (WP_HOOK_HOST='grok');
+        // accept any quoting variant so the doctor recognizes its own output.
+        hostLabeled = /WP_HOOK_HOST=(['"]?)grok\1/u.test(body);
     }
     catch {
         // Missing project hooks is advisory when binary absent; fail when binary present.
@@ -1273,8 +1279,8 @@ async function checkGrokHost(cwd = process.cwd()) {
             ok: true,
             detail: hooksPresent
                 ? hostLabeled
-                    ? "skipped (grok not on PATH); native .grok/hooks.json present with WP_HOOK_HOST=grok"
-                    : "skipped (grok not on PATH); .grok/hooks.json present but missing WP_HOOK_HOST=grok"
+                    ? "skipped (grok not on PATH); native .grok/hooks/webpresso.json present with WP_HOOK_HOST=grok"
+                    : "skipped (grok not on PATH); .grok/hooks/webpresso.json present but missing WP_HOOK_HOST=grok"
                 : "skipped (grok not on PATH)",
         };
     }
@@ -1282,20 +1288,20 @@ async function checkGrokHost(cwd = process.cwd()) {
         return {
             name: "Grok host integration",
             ok: false,
-            detail: "grok on PATH but missing project .grok/hooks.json — run wp setup to scaffold native hooks",
+            detail: "grok on PATH but missing project .grok/hooks/webpresso.json — run wp setup to scaffold native hooks, then run /hooks-trust once in Grok",
         };
     }
     if (!hostLabeled) {
         return {
             name: "Grok host integration",
             ok: false,
-            detail: ".grok/hooks.json present but managed commands lack WP_HOOK_HOST=grok",
+            detail: ".grok/hooks/webpresso.json present but managed commands lack WP_HOOK_HOST=grok",
         };
     }
     return {
         name: "Grok host integration",
         ok: true,
-        detail: "native .grok/hooks.json with WP_HOOK_HOST=grok (PreToolUse fail-open residual applies)",
+        detail: "native .grok/hooks/webpresso.json with WP_HOOK_HOST=grok (trust-gated: run /hooks-trust once; PreToolUse fail-open residual applies)",
     };
 }
 // Markers for the direct hook commands `wp setup` writes into
@@ -1793,9 +1799,9 @@ export function checkProjectMcpPins(cwd = process.cwd(), deps = {}) {
 /**
  * `claude-mcp-duplicate-registration` — advisory. A machine can register the
  * webpresso MCP server twice for the same Claude Code session: a manual
- * `claude mcp add webpresso` entry in `~/.claude.json` (user scope or a
- * project scope) plus the agent-kit marketplace plugin's bundled server
- * (plugin cache under `~/.claude/plugins/`). Both spawn `wp mcp`, so affected
+ * `claude mcp add webpresso` entry in Claude Code's home JSON config (user
+ * scope or a project scope) plus the agent-kit marketplace plugin's bundled
+ * server from the Claude plugin cache. Both spawn `wp mcp`, so affected
  * sessions run two server processes and carry a duplicated wp_* tool list.
  * Degrades to ok on missing/unreadable config — loud only on real duplication.
  */
@@ -1810,17 +1816,17 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
     }
     const claudeJsonPath = join(home, ".claude.json");
     if (!exists(claudeJsonPath)) {
-        return { name, ok: true, detail: "skipped (no ~/.claude.json)" };
+        return { name, ok: true, detail: "skipped (no Claude Code home JSON config)" };
     }
     let parsed;
     try {
         parsed = JSON.parse(readFile(claudeJsonPath));
     }
     catch {
-        return { name, ok: true, detail: "skipped (~/.claude.json unreadable)" };
+        return { name, ok: true, detail: "skipped (Claude Code home JSON config unreadable)" };
     }
     if (parsed === null || typeof parsed !== "object") {
-        return { name, ok: true, detail: "skipped (~/.claude.json is not an object)" };
+        return { name, ok: true, detail: "skipped (Claude Code home JSON config is not an object)" };
     }
     const config = parsed;
     const manualSources = [];
@@ -1839,7 +1845,7 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
         name,
         ok: false,
         advisory: true,
-        detail: `the agent-kit Claude plugin bundles the webpresso MCP server, but ~/.claude.json also ` +
+        detail: `the agent-kit Claude plugin bundles the webpresso MCP server, but Claude Code's home JSON config also ` +
             `registers "webpresso" manually (${manualSources.join(", ")}). Affected sessions run two ` +
             `wp mcp processes with a duplicated wp_* tool list. Remove the manual entry: ` +
             `claude mcp remove webpresso (run inside the project directory for project-scope entries).`,
@@ -2142,6 +2148,15 @@ export async function runHooksDoctor(opts = {}) {
                         detail: "claude required but not on PATH",
                     });
             }
+            if (host === "grok") {
+                const available = await runCommand("grok", ["--version"]);
+                if (!available.ok)
+                    checks.push({
+                        name: "Grok host integration",
+                        ok: false,
+                        detail: "grok required but not on PATH",
+                    });
+            }
         }
     }
     checks.push(checkHooksManifest(opts.cwd));

package/dist/esm/hooks/permission-request/index.js

@@ -9,7 +9,8 @@
  * Stdin: uses shared `readStdinJson` so conformance-batch can inject payloads via
  * `WP_CONFORMANCE_STDIN` (same contract as other managed hooks).
  */
-import { readStdinJson, writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { formatGuardReason } from "#hooks/shared/guard-outcome";
+import { readStdinJson, writeGuardStderr, writeHookOutput } from "#hooks/shared/hook-bootstrap";
 import { buildPermissionRequestEnvelope } from "./envelope.js";
 import { evaluatePermissionRequest } from "./policy.js";
 function isRecord(value) {
@@ -53,9 +54,14 @@ export async function main() {
         return;
     }
     // Claude + Codex share the golden PermissionRequest wire shape
-    // (hookSpecificOutput.hookEventName + decision.behavior).
-    writeHookOutput(JSON.stringify(buildPermissionRequestEnvelope(result.decision, result.reason)));
+    // (hookSpecificOutput.hookEventName + decision.behavior). The wire message
+    // carries the GUARD_* code so allow/deny decisions are keyable across hosts.
+    const codedMessage = formatGuardReason(result.code, result.reason);
+    writeHookOutput(JSON.stringify(buildPermissionRequestEnvelope(result.decision, codedMessage)));
     if (result.decision === "deny") {
+        // A deny exits 2; deliver the coded message to the real stderr too so it is
+        // observable even when a host prefers the exit-code channel.
+        writeGuardStderr(`${codedMessage}\n`);
         // Must use process.exit so runHookCommand's synthetic-exit trap records exit 2.
         process.exit(2);
     }

package/dist/esm/hooks/permission-request/policy.d.ts

@@ -5,6 +5,7 @@
  * authoritative when policy is uncertain. Explicit deny only for high-confidence
  * unsafe escalations; explicit allow only for clearly safe read-only escalations.
  */
+import type { GuardReasonCode } from "#hooks/shared/guard-outcome";
 export type PermissionRequestDecision = "allow" | "deny";
 export type PermissionRequestPolicyInput = {
     readonly toolName?: string;
@@ -15,13 +16,21 @@ export type PermissionRequestPolicyInput = {
 export type PermissionRequestPolicyResult = {
     readonly decision: "allow";
     readonly reason: string;
+    readonly code: GuardReasonCode;
 } | {
     readonly decision: "deny";
     readonly reason: string;
+    readonly code: GuardReasonCode;
 } | {
     readonly decision: undefined;
     readonly reason: string;
+    readonly code: GuardReasonCode;
 };
+/**
+ * Every GUARD_* code the permission-request policy can emit. Consumed by the
+ * guard-outcome registry-completeness test.
+ */
+export declare const PERMISSION_GUARD_CODES: readonly ["GUARD_PERMISSION_ALLOWED", "GUARD_PERMISSION_DENIED", "GUARD_HOST_DEFAULT"];
 /**
  * Decide allow / deny / pass-through for a PermissionRequest payload.
  */