@yagni-app/code-staging 0.3.2-staging.1112.1 → 0.3.2-staging.1114.1

package/dist/extension/hooks.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Lifecycle hooks system — user-configurable event hooks (YAG-506).
+ *
+ * Reads hook config from `~/.yagni-code/config.json` (user) and
+ * `.yagni-code/config.json` (project), and fires user-defined shell commands
+ * at lifecycle events. The config format mirrors Claude Code's `settings.json`
+ * hooks shape so a user can copy-paste between them.
+ *
+ * Supported events (8): SessionStart, UserPromptSubmit, PreToolUse,
+ * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd.
+ *
+ * Exit code semantics (matching Claude Code / Codex):
+ *   0   = success; stdout parsed as JSON for structured decisions
+ *   2   = explicit block/deny (control events only); stderr = reason
+ *   other = hook failure; decision ignored, warning surfaced, normal flow
+ *
+ * Fail-soft: a broken hook degrades to "no hook," never to "broken session."
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** A single hook command entry, matching Claude Code's wire format. */
+export interface HookEntry {
+    type: "command";
+    command: string;
+}
+/** A configured hook group with an optional matcher and source tag. */
+export interface HookGroup {
+    matcher?: string;
+    hooks: HookEntry[];
+    /** Where this group was loaded from. Project-level groups are gated on workspace trust. */
+    _source?: "user" | "project";
+}
+/** The hooks section of config.json. */
+export type HooksConfig = Record<string, HookGroup[]>;
+/** Supported Claude Code event names. */
+export type HookEventName = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PermissionRequest" | "PreCompact" | "PostCompact" | "SessionEnd";
+declare const SUPPORTED_EVENTS: readonly HookEventName[];
+/** Result of a PreToolUse hook evaluation. */
+export type PreToolUseHookResult = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    reason: string;
+} | {
+    decision: "ask";
+} | null;
+/** Result of a PermissionRequest hook evaluation. */
+export type PermissionRequestHookResult = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    reason: string;
+} | null;
+/** Interface injected into the permission gate. */
+export interface HookRunner {
+    preToolUse(toolName: string, input: Record<string, unknown>, cwd: string, trusted?: boolean): Promise<PreToolUseHookResult>;
+    permissionRequest(toolName: string, input: Record<string, unknown>, cwd: string, trusted?: boolean): Promise<PermissionRequestHookResult>;
+}
+/** Read and merge hooks config from user and project files. Pure I/O, fail-soft. */
+export declare function loadHooksConfig(userHome?: string, cwd?: string, env?: NodeJS.ProcessEnv): HooksConfig;
+/**
+ * Check if a matcher matches a tool name. Matches Claude Code / Codex:
+ * - No matcher → matches everything
+ * - "*" → matches everything
+ * - Exact string or pipe-separated alternatives ("Edit|Write") → exact match
+ * - Contains regex chars → regex match
+ */
+export declare function matchesMatcher(matcher: string | undefined, input: string | undefined): boolean;
+interface ExecResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    error: string | null;
+    durationMs: number;
+}
+/** Execute a hook command with stdin JSON, timeout, and fail-soft. */
+declare function execHook(command: string, inputJson: string, cwd: string, timeoutMs?: number, env?: NodeJS.ProcessEnv): Promise<ExecResult>;
+/** Extract permissionDecision from PreToolUse stdout JSON. */
+export declare function parsePreToolUseOutput(stdout: string): PreToolUseHookResult;
+/** Extract decision from PermissionRequest stdout JSON. */
+export declare function parsePermissionRequestOutput(stdout: string): PermissionRequestHookResult;
+/** Extract additionalContext from stdout JSON (for SessionStart, UserPromptSubmit, PostToolUse). */
+export declare function parseAdditionalContext(stdout: string): string | null;
+/** Check if stdout JSON has continue: false (for PreCompact cancellation). */
+export declare function parseCompactCancel(stdout: string): boolean;
+interface HookExecutorOptions {
+    config: HooksConfig;
+    env?: NodeJS.ProcessEnv;
+    execImpl?: typeof execHook;
+    /** Returns true when the workspace is trusted (pi's project trust model). */
+    isTrusted?: () => boolean;
+}
+/**
+ * Create a HookRunner for injection into the permission gate. The `isTrusted`
+ * function is called per hook invocation to gate project-level hooks on
+ * workspace trust (pi's project trust model). Defaults to always-trusted.
+ */
+export declare function makeHookRunner(opts: HookExecutorOptions): HookRunner | null;
+export interface RegisterHooksDeps {
+    config?: HooksConfig;
+    env?: NodeJS.ProcessEnv;
+    execImpl?: typeof execHook;
+    /** Returns true when the workspace is trusted (pi's project trust model). */
+    isTrusted?: () => boolean;
+}
+/**
+ * Register pi event handlers for all configured lifecycle hooks.
+ * No-op if no hooks are configured or in eval mode.
+ */
+export declare function registerHooks(pi: ExtensionAPI, deps?: RegisterHooksDeps): void;
+export { SUPPORTED_EVENTS as HOOK_SUPPORTED_EVENTS };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/extension/hooks.js

@@ -0,0 +1,666 @@
+/**
+ * Lifecycle hooks system — user-configurable event hooks (YAG-506).
+ *
+ * Reads hook config from `~/.yagni-code/config.json` (user) and
+ * `.yagni-code/config.json` (project), and fires user-defined shell commands
+ * at lifecycle events. The config format mirrors Claude Code's `settings.json`
+ * hooks shape so a user can copy-paste between them.
+ *
+ * Supported events (8): SessionStart, UserPromptSubmit, PreToolUse,
+ * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd.
+ *
+ * Exit code semantics (matching Claude Code / Codex):
+ *   0   = success; stdout parsed as JSON for structured decisions
+ *   2   = explicit block/deny (control events only); stderr = reason
+ *   other = hook failure; decision ignored, warning surfaced, normal flow
+ *
+ * Fail-soft: a broken hook degrades to "no hook," never to "broken session."
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, appendFileSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { codeStateHome } from "./stateHome.js";
+import { isDebug } from "./diagnostics.js";
+const SUPPORTED_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+    "PreCompact",
+    "PostCompact",
+    "SessionEnd",
+];
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+/** Read and merge hooks config from user and project files. Pure I/O, fail-soft. */
+export function loadHooksConfig(userHome = homedir(), cwd = process.cwd(), env = process.env) {
+    if (env.YAGNI_CODE_EVAL_MODE === "1")
+        return {};
+    const merged = {};
+    // User-level: ~/.yagni-code/config.json — always trusted (the user's own file)
+    const userPath = join(codeStateHome(null, env, userHome), "config.json");
+    mergeHooksFromFile(merged, userPath, "user");
+    // Project-level: .yagni-code/config.json — tagged for trust gating at execution time
+    const projectPath = join(cwd, ".yagni-code", "config.json");
+    mergeHooksFromFile(merged, projectPath, "project");
+    return merged;
+}
+function mergeHooksFromFile(merged, path, source) {
+    try {
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        const hooks = parsed?.hooks;
+        if (!hooks || typeof hooks !== "object")
+            return;
+        for (const [event, groups] of Object.entries(hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            if (!merged[event])
+                merged[event] = [];
+            for (const g of groups.filter(isValidHookGroup)) {
+                merged[event].push({ ...g, _source: source });
+            }
+        }
+    }
+    catch {
+        // Fail-soft: missing or malformed config is logged and skipped.
+    }
+}
+function isValidHookGroup(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (!Array.isArray(v.hooks))
+        return false;
+    return v.hooks.every((h) => h && typeof h === "object" && h.type === "command" && typeof h.command === "string");
+}
+// ---------------------------------------------------------------------------
+// Matcher
+// ---------------------------------------------------------------------------
+/**
+ * Check if a matcher matches a tool name. Matches Claude Code / Codex:
+ * - No matcher → matches everything
+ * - "*" → matches everything
+ * - Exact string or pipe-separated alternatives ("Edit|Write") → exact match
+ * - Contains regex chars → regex match
+ */
+export function matchesMatcher(matcher, input) {
+    if (!matcher || matcher === "*" || matcher === "")
+        return true;
+    if (input === undefined)
+        return false;
+    // If the matcher is alphanumeric + pipe only, treat as case-insensitive exact match
+    // (Claude Code uses PascalCase tool names like "Bash"; pi uses lowercase "bash")
+    if (/^[A-Za-z0-9_|]+$/.test(matcher)) {
+        const lower = input.toLowerCase();
+        return matcher.split("|").some((m) => m.toLowerCase() === lower);
+    }
+    try {
+        return new RegExp(matcher).test(input);
+    }
+    catch {
+        return false;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** Execute a hook command with stdin JSON, timeout, and fail-soft. */
+function execHook(command, inputJson, cwd, timeoutMs = DEFAULT_TIMEOUT_MS, env) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        let child;
+        try {
+            child = spawn("sh", ["-c", command], {
+                cwd,
+                stdio: ["pipe", "pipe", "pipe"],
+                env: { ...process.env, ...env },
+                timeout: 0, // we handle timeout ourselves for kill semantics
+            });
+        }
+        catch (err) {
+            resolve({
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                error: `spawn failed: ${err instanceof Error ? err.message : String(err)}`,
+                durationMs: Date.now() - started,
+            });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { }
+        }, timeoutMs);
+        child.stdout?.on("data", (d) => { stdout += d.toString(); });
+        child.stderr?.on("data", (d) => { stderr += d.toString(); });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: null,
+                stdout,
+                stderr,
+                error: `spawn error: ${err.message}`,
+                durationMs: Date.now() - started,
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: code,
+                stdout,
+                stderr,
+                error: timedOut ? `hook timed out after ${Math.round(timeoutMs / 1000)}s` : null,
+                durationMs: Date.now() - started,
+            });
+        });
+        // Write stdin
+        try {
+            child.stdin?.write(inputJson);
+            child.stdin?.end();
+        }
+        catch {
+            // stdin write failed — let the process finish (it may handle it)
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Output parsing
+// ---------------------------------------------------------------------------
+function looksLikeJson(stdout) {
+    const trimmed = stdout.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+function tryParseJson(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const value = JSON.parse(trimmed);
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract permissionDecision from PreToolUse stdout JSON. */
+export function parsePreToolUseOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    if (!looksLikeJson(trimmed))
+        return null;
+    const parsed = tryParseJson(trimmed);
+    if (!parsed)
+        return null;
+    const hso = parsed.hookSpecificOutput;
+    if (!hso)
+        return null;
+    const decision = hso.permissionDecision;
+    if (decision === "allow")
+        return { decision: "allow" };
+    if (decision === "deny") {
+        const reason = typeof hso.permissionDecisionReason === "string"
+            ? hso.permissionDecisionReason.trim()
+            : "";
+        return { decision: "deny", reason: reason || "blocked by PreToolUse hook" };
+    }
+    if (decision === "ask")
+        return { decision: "ask" };
+    return null;
+}
+/** Extract decision from PermissionRequest stdout JSON. */
+export function parsePermissionRequestOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    if (!looksLikeJson(trimmed))
+        return null;
+    const parsed = tryParseJson(trimmed);
+    if (!parsed)
+        return null;
+    const hso = parsed.hookSpecificOutput;
+    if (!hso)
+        return null;
+    const decision = hso.decision;
+    if (!decision)
+        return null;
+    const behavior = decision.behavior;
+    if (behavior === "allow")
+        return { decision: "allow" };
+    if (behavior === "deny") {
+        const message = typeof decision.message === "string" ? decision.message.trim() : "";
+        return { decision: "deny", reason: message || "denied by PermissionRequest hook" };
+    }
+    return null;
+}
+/** Extract additionalContext from stdout JSON (for SessionStart, UserPromptSubmit, PostToolUse). */
+export function parseAdditionalContext(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    // Try JSON parse first
+    if (looksLikeJson(trimmed)) {
+        const parsed = tryParseJson(trimmed);
+        if (parsed) {
+            const hso = parsed.hookSpecificOutput;
+            if (hso && typeof hso.additionalContext === "string" && hso.additionalContext.trim()) {
+                return hso.additionalContext.trim();
+            }
+            // Also check top-level continue/stopReason for compact
+            if (parsed.continue === false) {
+                return null; // handled by compact-specific parsing
+            }
+            return null;
+        }
+        // Looks like JSON but failed to parse — invalid output, ignore
+        return null;
+    }
+    // Plain text stdout → context
+    return trimmed;
+}
+/** Check if stdout JSON has continue: false (for PreCompact cancellation). */
+export function parseCompactCancel(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed || !looksLikeJson(trimmed))
+        return false;
+    const parsed = tryParseJson(trimmed);
+    if (!parsed)
+        return false;
+    return parsed.continue === false;
+}
+// ---------------------------------------------------------------------------
+// Diagnostic logging
+// ---------------------------------------------------------------------------
+function logHookEvent(env, payload) {
+    if (!isDebug(env))
+        return;
+    try {
+        if (process.env.NODE_TEST_CONTEXT)
+            return;
+        const logPath = join(codeStateHome(null, env), "logs", "hooks.log");
+        mkdirSync(dirname(logPath), { recursive: true });
+        appendFileSync(logPath, JSON.stringify({ ts: new Date().toISOString(), ...payload }) + "\n", "utf8");
+    }
+    catch {
+        // logging must never break the session
+    }
+}
+/** Filter hook groups by workspace trust: project-level groups are skipped when untrusted. */
+function filterByTrust(groups, isTrusted) {
+    if (isTrusted)
+        return groups;
+    return groups.filter((g) => g._source !== "project");
+}
+/**
+ * Create a HookRunner for injection into the permission gate. The `isTrusted`
+ * function is called per hook invocation to gate project-level hooks on
+ * workspace trust (pi's project trust model). Defaults to always-trusted.
+ */
+export function makeHookRunner(opts) {
+    const { config, env = process.env, execImpl = execHook } = opts;
+    const isTrusted = opts.isTrusted ?? (() => true);
+    const preToolUseGroups = config["PreToolUse"] ?? [];
+    const permissionRequestGroups = config["PermissionRequest"] ?? [];
+    if (preToolUseGroups.length === 0 && permissionRequestGroups.length === 0)
+        return null;
+    async function runPreToolUseHooks(toolName, input, cwd, trusted) {
+        const sessionId = env.YAGNI_SESSION_ID ?? "";
+        const inputJson = JSON.stringify({
+            session_id: sessionId,
+            cwd,
+            tool_name: toolName,
+            tool_input: input,
+            hook_event_name: "PreToolUse",
+        });
+        for (const group of filterByTrust(preToolUseGroups, trusted ?? isTrusted())) {
+            if (!matchesMatcher(group.matcher, toolName))
+                continue;
+            for (const entry of group.hooks) {
+                const result = await execImpl(entry.command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+                    YAGNI_HOOK_EVENT: "PreToolUse",
+                    YAGNI_HOOK_CWD: cwd,
+                    YAGNI_HOOK_SESSION_ID: sessionId,
+                });
+                logHookEvent(env, {
+                    event: "PreToolUse",
+                    command: entry.command,
+                    status: result.error ? "failed" : "completed",
+                    exit_code: result.exitCode,
+                    duration_ms: result.durationMs,
+                    ...(result.error ? { error: result.error } : {}),
+                    ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
+                });
+                if (result.error) {
+                    // Spawn error / timeout → hook failure, continue
+                    continue;
+                }
+                if (result.exitCode === 2) {
+                    const reason = result.stderr.trim() || "blocked by PreToolUse hook";
+                    return { decision: "deny", reason };
+                }
+                if (result.exitCode !== 0) {
+                    // Other non-zero → hook failure, continue to next hook
+                    continue;
+                }
+                // Exit 0 → parse stdout
+                const parsed = parsePreToolUseOutput(result.stdout);
+                if (parsed)
+                    return parsed;
+                // No structured output → fall through to next hook
+            }
+        }
+        return null;
+    }
+    async function runPermissionRequestHooks(toolName, input, cwd, trusted) {
+        const sessionId = env.YAGNI_SESSION_ID ?? "";
+        const inputJson = JSON.stringify({
+            session_id: sessionId,
+            cwd,
+            tool_name: toolName,
+            tool_input: input,
+            hook_event_name: "PermissionRequest",
+        });
+        for (const group of filterByTrust(permissionRequestGroups, trusted ?? isTrusted())) {
+            if (!matchesMatcher(group.matcher, toolName))
+                continue;
+            for (const entry of group.hooks) {
+                const result = await execImpl(entry.command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+                    YAGNI_HOOK_EVENT: "PermissionRequest",
+                    YAGNI_HOOK_CWD: cwd,
+                    YAGNI_HOOK_SESSION_ID: sessionId,
+                });
+                logHookEvent(env, {
+                    event: "PermissionRequest",
+                    command: entry.command,
+                    status: result.error ? "failed" : "completed",
+                    exit_code: result.exitCode,
+                    duration_ms: result.durationMs,
+                    ...(result.error ? { error: result.error } : {}),
+                    ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
+                });
+                if (result.error)
+                    continue;
+                if (result.exitCode === 2) {
+                    const reason = result.stderr.trim() || "denied by PermissionRequest hook";
+                    return { decision: "deny", reason };
+                }
+                if (result.exitCode !== 0)
+                    continue;
+                const parsed = parsePermissionRequestOutput(result.stdout);
+                if (parsed)
+                    return parsed;
+            }
+        }
+        return null;
+    }
+    return {
+        preToolUse: runPreToolUseHooks,
+        permissionRequest: runPermissionRequestHooks,
+    };
+}
+/**
+ * Register pi event handlers for all configured lifecycle hooks.
+ * No-op if no hooks are configured or in eval mode.
+ */
+export function registerHooks(pi, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (env.YAGNI_CODE_EVAL_MODE === "1")
+        return;
+    const config = deps.config ?? loadHooksConfig();
+    const execImpl = deps.execImpl ?? execHook;
+    const sessionId = env.YAGNI_SESSION_ID ?? "";
+    // Fallback trust check for test environments where ctx.isProjectTrusted is unavailable.
+    const defaultTrusted = deps.isTrusted ?? (() => true);
+    const trusted = (ctx) => {
+        try {
+            return ctx.isProjectTrusted();
+        }
+        catch {
+            return defaultTrusted();
+        }
+    };
+    // --- SessionStart ---
+    const sessionStartGroups = config["SessionStart"] ?? [];
+    if (sessionStartGroups.length > 0) {
+        pi.on("session_start", async (event, ctx) => {
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({ session_id: sessionId, cwd, hook_event_name: "SessionStart" });
+            // The matcher for SessionStart hooks matches against pi's session start
+            // reason ("startup" | "reload" | "new" | "resume" | "fork"), matching
+            // Codex's SessionStart matcher input ("startup" | "resume" | "clear").
+            // A hook with no matcher or "*" runs on every session start.
+            for (const group of filterByTrust(sessionStartGroups, trusted(ctx))) {
+                if (!matchesMatcher(group.matcher, event.reason))
+                    continue;
+                for (const entry of group.hooks) {
+                    await runSideEffectHook(entry.command, inputJson, cwd, "SessionStart", ctx, env, execImpl);
+                }
+            }
+        });
+    }
+    // --- UserPromptSubmit (via "input" event, filtered to interactive + non-streaming) ---
+    const userPromptSubmitGroups = config["UserPromptSubmit"] ?? [];
+    if (userPromptSubmitGroups.length > 0) {
+        pi.on("input", async (event, ctx) => {
+            // Only fire on initial interactive prompts, not steering messages
+            if (event.source !== "interactive")
+                return { action: "continue" };
+            if (event.streamingBehavior !== undefined)
+                return { action: "continue" };
+            const cwd = process.cwd();
+            const inputJson = JSON.stringify({
+                session_id: sessionId,
+                cwd,
+                prompt: event.text,
+                hook_event_name: "UserPromptSubmit",
+            });
+            let combinedContext = "";
+            for (const group of filterByTrust(userPromptSubmitGroups, trusted(ctx))) {
+                for (const entry of group.hooks) {
+                    const result = await execImpl(entry.command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+                        YAGNI_HOOK_EVENT: "UserPromptSubmit",
+                        YAGNI_HOOK_CWD: cwd,
+                        YAGNI_HOOK_SESSION_ID: sessionId,
+                    });
+                    logHookEvent(env, {
+                        event: "UserPromptSubmit",
+                        command: entry.command,
+                        status: result.error ? "failed" : "completed",
+                        exit_code: result.exitCode,
+                        duration_ms: result.durationMs,
+                        ...(result.error ? { error: result.error } : {}),
+                        ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
+                    });
+                    if (result.error)
+                        continue;
+                    if (result.exitCode === 2) {
+                        // Block the prompt — surface the reason to the user
+                        const reason = result.stderr.trim() || "blocked by UserPromptSubmit hook";
+                        if (ctx.hasUI) {
+                            ctx.ui.notify(`Prompt blocked by hook: ${reason}`, "warning");
+                        }
+                        logHookEvent(env, {
+                            event: "UserPromptSubmit",
+                            command: entry.command,
+                            status: "blocked",
+                            exit_code: 2,
+                            stderr: reason.slice(0, 512),
+                            duration_ms: result.durationMs,
+                        });
+                        return { action: "handled" };
+                    }
+                    if (result.exitCode !== 0)
+                        continue;
+                    // Exit 0 → parse stdout for context
+                    const context = parseAdditionalContext(result.stdout);
+                    if (context)
+                        combinedContext += (combinedContext ? "\n\n" : "") + context;
+                }
+            }
+            if (combinedContext) {
+                return { action: "transform", text: combinedContext + "\n\n" + event.text };
+            }
+            return { action: "continue" };
+        });
+    }
+    // --- PostToolUse (via "tool_result" event) ---
+    const postToolUseGroups = config["PostToolUse"] ?? [];
+    if (postToolUseGroups.length > 0) {
+        pi.on("tool_result", async (event, ctx) => {
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({
+                session_id: sessionId,
+                cwd,
+                tool_name: event.toolName,
+                tool_input: event.input,
+                tool_response: event.content,
+                hook_event_name: "PostToolUse",
+            });
+            let combinedContext = "";
+            for (const group of filterByTrust(postToolUseGroups, trusted(ctx))) {
+                if (!matchesMatcher(group.matcher, event.toolName))
+                    continue;
+                for (const entry of group.hooks) {
+                    const result = await execImpl(entry.command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+                        YAGNI_HOOK_EVENT: "PostToolUse",
+                        YAGNI_HOOK_CWD: cwd,
+                        YAGNI_HOOK_SESSION_ID: sessionId,
+                    });
+                    logHookEvent(env, {
+                        event: "PostToolUse",
+                        command: entry.command,
+                        status: result.error ? "failed" : "completed",
+                        exit_code: result.exitCode,
+                        duration_ms: result.durationMs,
+                        ...(result.error ? { error: result.error } : {}),
+                        ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
+                    });
+                    if (result.error)
+                        continue;
+                    if (result.exitCode === 2) {
+                        // Exit 2 on PostToolUse → feedback to model via stderr
+                        const feedback = result.stderr.trim();
+                        if (feedback)
+                            combinedContext += (combinedContext ? "\n\n" : "") + feedback;
+                        continue;
+                    }
+                    if (result.exitCode !== 0)
+                        continue;
+                    const context = parseAdditionalContext(result.stdout);
+                    if (context)
+                        combinedContext += (combinedContext ? "\n\n" : "") + context;
+                }
+            }
+            if (combinedContext) {
+                // Append to event.content, preserving modifications from prior tool_result
+                // handlers (recall.ts). Guard against undefined/non-array content.
+                const content = Array.isArray(event.content) ? event.content : [];
+                return { content: [...content, { type: "text", text: `\n\n${combinedContext}` }] };
+            }
+            return undefined;
+        });
+    }
+    // --- PreCompact (via "session_before_compact") ---
+    const preCompactGroups = config["PreCompact"] ?? [];
+    if (preCompactGroups.length > 0) {
+        pi.on("session_before_compact", async (_event, ctx) => {
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({ session_id: sessionId, cwd, hook_event_name: "PreCompact" });
+            for (const group of filterByTrust(preCompactGroups, trusted(ctx))) {
+                for (const entry of group.hooks) {
+                    const result = await execImpl(entry.command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+                        YAGNI_HOOK_EVENT: "PreCompact",
+                        YAGNI_HOOK_CWD: cwd,
+                        YAGNI_HOOK_SESSION_ID: sessionId,
+                    });
+                    logHookEvent(env, {
+                        event: "PreCompact",
+                        command: entry.command,
+                        status: result.error ? "failed" : "completed",
+                        exit_code: result.exitCode,
+                        duration_ms: result.durationMs,
+                        ...(result.error ? { error: result.error } : {}),
+                    });
+                    if (result.error)
+                        continue;
+                    if (result.exitCode !== 0)
+                        continue;
+                    if (parseCompactCancel(result.stdout)) {
+                        return { cancel: true };
+                    }
+                }
+            }
+            return undefined;
+        });
+    }
+    // --- PostCompact (via "session_compact") ---
+    const postCompactGroups = config["PostCompact"] ?? [];
+    if (postCompactGroups.length > 0) {
+        pi.on("session_compact", async (_event, ctx) => {
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({ session_id: sessionId, cwd, hook_event_name: "PostCompact" });
+            for (const group of filterByTrust(postCompactGroups, trusted(ctx))) {
+                for (const entry of group.hooks) {
+                    await runSideEffectHook(entry.command, inputJson, cwd, "PostCompact", ctx, env, execImpl);
+                }
+            }
+        });
+    }
+    // --- SessionEnd (via "session_shutdown") ---
+    const sessionEndGroups = config["SessionEnd"] ?? [];
+    if (sessionEndGroups.length > 0) {
+        pi.on("session_shutdown", async (_event, ctx) => {
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({ session_id: sessionId, cwd, hook_event_name: "SessionEnd" });
+            for (const group of filterByTrust(sessionEndGroups, trusted(ctx))) {
+                for (const entry of group.hooks) {
+                    await runSideEffectHook(entry.command, inputJson, cwd, "SessionEnd", ctx, env, execImpl);
+                }
+            }
+        });
+    }
+}
+/** Run a side-effect-only hook (no control effects, output ignored). */
+async function runSideEffectHook(command, inputJson, cwd, eventName, ctx, env, execImpl) {
+    try {
+        const result = await execImpl(command, inputJson, cwd, DEFAULT_TIMEOUT_MS, {
+            YAGNI_HOOK_EVENT: eventName,
+            YAGNI_HOOK_CWD: cwd,
+            YAGNI_HOOK_SESSION_ID: env.YAGNI_SESSION_ID ?? "",
+        });
+        logHookEvent(env, {
+            event: eventName,
+            command,
+            status: result.error ? "failed" : "completed",
+            exit_code: result.exitCode,
+            duration_ms: result.durationMs,
+            ...(result.error ? { error: result.error } : {}),
+            ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
+        });
+        if (result.error || (result.exitCode !== 0 && result.exitCode !== null)) {
+            if (ctx.hasUI && result.stderr.trim()) {
+                ctx.ui.notify(`Hook '${eventName}' exited with code ${result.exitCode}: ${result.stderr.trim().slice(0, 200)}`, "warning");
+            }
+        }
+    }
+    catch {
+        // Fail-soft: a hook error never breaks the session
+    }
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { SUPPORTED_EVENTS as HOOK_SUPPORTED_EVENTS };
+//# sourceMappingURL=hooks.js.map

package/dist/extension/index.d.ts

@@ -138,6 +138,8 @@ export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace,
 export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutcome, RepoIntake, RepoIntakeFs, EngineeringDraft, DraftTeam, } from "./initPass.js";
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA, BRAND_NAME } from "./branding.js";
+export { loadHooksConfig, makeHookRunner, registerHooks, matchesMatcher, parsePreToolUseOutput, parsePermissionRequestOutput, parseAdditionalContext, parseCompactCancel, HOOK_SUPPORTED_EVENTS, } from "./hooks.js";
+export type { HookEntry, HookGroup, HooksConfig, HookEventName, HookRunner, PreToolUseHookResult, PermissionRequestHookResult, RegisterHooksDeps, } from "./hooks.js";
 export { createUltraHolder, registerUltraCommand } from "./ultra.js";
 export type { UltraHolder } from "./ultra.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";

package/dist/extension/index.js

@@ -28,6 +28,7 @@ import { fetchMcpServers as defaultFetchMcpServers, registerMcpCommand, register
 import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission.js";
+import { loadHooksConfig, makeHookRunner, registerHooks } from "./hooks.js";
 import { registerSubagents } from "./subagents.js";
 import { createUltraHolder, registerUltraCommand } from "./ultra.js";
 import { registerTodos } from "./todos.js";
@@ -280,6 +281,12 @@ export async function registerYagni(pi, deps = {}) {
     // rejected as a same-session self-authorization path, PR #1698).
     const sessionGrants = evalMode ? [] : loadGrants();
     const GUARDIAN_EVENT_TIMEOUT_MS = 5_000;
+    // YAG-506: load user-configurable lifecycle hooks config and create the
+    // hook runner for the permission gate. Skipped in eval mode.
+    const hooksConfig = evalMode ? {} : loadHooksConfig();
+    const hookRunner = evalMode ? null : makeHookRunner({ config: hooksConfig });
+    if (!evalMode)
+        registerHooks(pi, { config: hooksConfig });
     registerPermissionGate(pi, {
         modeHolder,
         guardianState,
@@ -362,6 +369,7 @@ export async function registerYagni(pi, deps = {}) {
         onBlessRemember: decisionCapture
             ? (ctx, info) => decisionCapture.captureFromBless(ctx, info)
             : undefined,
+        ...(hookRunner ? { hookRunner } : {}),
     });
     // P2/YAG-383: /cost prefers the server-authoritative session spend (covers
     // subagents and advisor consults directly, since they bill under this same
@@ -859,6 +867,8 @@ export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace,
 // Onramp Door B (F2a): the one-time init-pass idempotency marker.
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA, BRAND_NAME } from "./branding.js";
+// YAG-506: user-configurable lifecycle hooks.
+export { loadHooksConfig, makeHookRunner, registerHooks, matchesMatcher, parsePreToolUseOutput, parsePermissionRequestOutput, parseAdditionalContext, parseCompactCancel, HOOK_SUPPORTED_EVENTS, } from "./hooks.js";
 // Ultra mode (/ultra): the aggressive fan-out/verify/synthesize dial.
 export { createUltraHolder, registerUltraCommand } from "./ultra.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";

package/dist/extension/permission.d.ts

@@ -28,6 +28,7 @@
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
+import type { HookRunner } from "./hooks.js";
 import { type BlessStore } from "./bless.js";
 import { type ExecPolicy } from "./execPolicy.js";
 import { type GuardianError, type GuardianRiskLevel } from "./guardian.js";
@@ -179,6 +180,12 @@ export interface RegisterPermissionDeps {
      * Fail-soft; never blocks.
      */
     onGuardianEvent?: (event: GuardianGateEvent) => void;
+    /**
+     * User-configurable lifecycle hooks (YAG-506). When present, PreToolUse
+     * hooks run before decideGate and can short-circuit (allow/deny/ask),
+     * and PermissionRequest hooks run before the confirm dialog.
+     */
+    hookRunner?: HookRunner;
 }
 /** The customType tag on injected mode-context messages (filterable later). */
 export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";

package/dist/extension/permission.js

@@ -296,6 +296,7 @@ export function registerPermissionGate(pi, deps = {}) {
     const basePolicy = deps.policy ?? DEFAULT_PERMISSION_POLICY;
     let mode = deps.mode ?? "auto";
     const makeStore = deps.makeBlessStore ?? defaultMakeBlessStore;
+    const hookRunner = deps.hookRunner;
     deps.modeHolder?.onSet((m) => {
         if (m !== mode)
             approvedCommands.clear();
@@ -422,7 +423,48 @@ export function registerPermissionGate(pi, deps = {}) {
         const modeAtEntry = mode;
         try {
             const input = event.input ?? {};
-            const decision = decideGate(event.toolName, input, modeAtEntry, effectivePolicy);
+            // YAG-506: PreToolUse hooks run BEFORE decideGate. They can short-circuit
+            // (allow/deny/ask) or fall through to the normal gate logic. The result
+            // is cached in preToolUseResult so the "ask" check below does NOT
+            // re-invoke the hook (hooks have side effects — notifications etc.).
+            let preToolUseResult;
+            if (hookRunner) {
+                const cwd = ctx?.cwd ?? ".";
+                try {
+                    preToolUseResult = await hookRunner.preToolUse(event.toolName, input, cwd, ctx?.isProjectTrusted()) ?? undefined;
+                    if (preToolUseResult) {
+                        if (preToolUseResult.decision === "deny") {
+                            return { block: true, reason: preToolUseResult.reason };
+                        }
+                        if (preToolUseResult.decision === "allow") {
+                            // Allow bypasses Guardian/confirm, but the exec policy's forbidden
+                            // band still runs as a hard safety floor (deliberate deviation
+                            // from Claude Code: we don't let a hook auto-allow a forbidden cmd).
+                            if (event.toolName === "bash") {
+                                const cmdRaw = input.command;
+                                const command = typeof cmdRaw === "string" ? cmdRaw.trim() : "";
+                                if (command) {
+                                    const execPolicy = effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY;
+                                    const classification = classifyCommand(command, execPolicy);
+                                    if (classification.decision === "forbidden") {
+                                        return {
+                                            block: true,
+                                            reason: `${classification.justification}. Do not attempt the same outcome via a workaround or indirect execution — use a materially safer alternative, or ask the user.`,
+                                        };
+                                    }
+                                }
+                            }
+                            return {};
+                        }
+                        // "ask" → force confirm by overriding the gate decision
+                        // Falls through to decision.confirm logic below
+                    }
+                }
+                catch {
+                    // Fail-soft: a hook error never blocks or allows; fall through to gate
+                }
+            }
+            let decision = decideGate(event.toolName, input, modeAtEntry, effectivePolicy);
             if (decision.block)
                 return { block: true, reason: decision.reason };
             // Prompt band (YAG-510 order): grants → exact-command cache → cap/
@@ -587,6 +629,41 @@ export function registerPermissionGate(pi, deps = {}) {
                                 reason: `Guardian needs user approval: ${verdict.rationale} No UI available — the command was held. Find a safer alternative or leave this step for the user.`,
                             };
                         }
+                        // YAG-506: PermissionRequest hooks fire before the confirm dialog.
+                        // Only when a UI is present (headless path already failed closed above).
+                        if (hookRunner && ctx?.hasUI) {
+                            try {
+                                const hookResult = await hookRunner.permissionRequest(event.toolName, input, cwd, ctx?.isProjectTrusted());
+                                if (hookResult) {
+                                    if (hookResult.decision === "allow") {
+                                        rememberApproved(cwd, command);
+                                        emitGateEvent({
+                                            ...eventBase,
+                                            outcome: "ask_approved",
+                                            riskLevel: verdict.riskLevel,
+                                            rationale: verdict.rationale,
+                                            durationMs,
+                                            consulted: true,
+                                        });
+                                        return {};
+                                    }
+                                    if (hookResult.decision === "deny") {
+                                        emitGateEvent({
+                                            ...eventBase,
+                                            outcome: "ask_denied",
+                                            riskLevel: verdict.riskLevel,
+                                            rationale: verdict.rationale,
+                                            durationMs,
+                                            consulted: true,
+                                        });
+                                        return { block: true, reason: hookResult.reason };
+                                    }
+                                }
+                            }
+                            catch {
+                                // Fail-soft: hook error → dialog proceeds normally
+                            }
+                        }
                         // Offer "don't ask again" only when the grant would actually
                         // cover this command (grant-time validation).
                         const grantCandidate = validateGrant(command, effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY, resolveRepoKeyFor(cwd));
@@ -725,7 +802,29 @@ export function registerPermissionGate(pi, deps = {}) {
                 }
                 // review mode with Guardian disabled/capped: fall through to confirm.
             }
+            // YAG-506: PreToolUse "ask" forces confirmation even in auto mode.
+            // Uses the cached result from the top of the handler — no re-invocation.
+            if (preToolUseResult?.decision === "ask") {
+                decision = { block: false, confirm: true };
+            }
             if (decision.confirm) {
+                // YAG-506: PermissionRequest hooks run before the confirm dialog.
+                if (hookRunner) {
+                    try {
+                        const cwd = ctx?.cwd ?? ".";
+                        const hookResult = await hookRunner.permissionRequest(event.toolName, input, cwd, ctx?.isProjectTrusted());
+                        if (hookResult) {
+                            if (hookResult.decision === "allow")
+                                return {};
+                            if (hookResult.decision === "deny") {
+                                return { block: true, reason: hookResult.reason };
+                            }
+                        }
+                    }
+                    catch {
+                        // Fail-soft: hook error → dialog proceeds normally
+                    }
+                }
                 // Review mode needs a confirmation. With no dialog-capable UI (headless),
                 // fail CLOSED: the user explicitly chose a stricter mode, so a write we
                 // cannot get consent for is held rather than silently auto-applied (this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.3.2-staging.1112.1",
+  "version": "0.3.2-staging.1114.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -39,5 +39,5 @@
     "smol-toml": "^1.8.0",
     "typebox": "^1.3.11"
   },
-  "yagniSourceSha": "792a9033a5199d4129ba1a53605b23881956e4ce"
+  "yagniSourceSha": "489e57a1ae86dfa2b4461015e21e1661c128b7aa"
 }