gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -465,6 +465,13 @@ export interface SessionShutdownEvent {
 	type: "session_shutdown";
 }
 
+/** Fired when the in-process session ends (distinct from process shutdown). */
+export interface SessionEndEvent {
+	type: "session_end";
+	reason: "user" | "idle" | "error" | "programmatic";
+	sessionFile?: string;
+}
+
 /** Preparation data for tree navigation */
 export interface TreePreparation {
 	targetId: string;
@@ -506,6 +513,7 @@ export type SessionEvent =
 	| SessionBeforeCompactEvent
 	| SessionCompactEvent
 	| SessionShutdownEvent
+	| SessionEndEvent
 	| SessionBeforeTreeEvent
 	| SessionTreeEvent;
 
@@ -523,8 +531,8 @@ export interface ContextEvent {
 export interface BeforeProviderRequestEvent {
 	type: "before_provider_request";
 	payload: unknown;
-	/** The resolved model for this request (provider, id, etc.) */
-	model?: { provider: string; id: string };
+	/** The resolved model for this request (provider, id, api, etc.) */
+	model?: { provider: string; id: string; api?: string };
 }
 
 /** Fired after user submits prompt but before agent loop. */
@@ -546,6 +554,199 @@ export interface AgentEndEvent {
 	messages: AgentMessage[];
 }
 
+/**
+ * Fired when the agent has truly stopped — no follow-up, no steering, no pending turn.
+ * Distinct from `agent_end`, which fires on every loop exit (including those that resume).
+ * Use this for "the agent is idle and waiting for the user" signals.
+ */
+export interface StopEvent {
+	type: "stop";
+	reason: "completed" | "cancelled" | "error" | "blocked";
+	lastMessage?: AgentMessage;
+}
+
+/**
+ * Fired when the agent needs user attention (blocked on a question, idle, milestone ready).
+ * Consumed by the Layer 0 shell-hook runner to dispatch `Notification` / `Blocked` hooks.
+ */
+export interface NotificationEvent {
+	type: "notification";
+	kind: "blocked" | "input_needed" | "milestone_ready" | "idle" | "error";
+	message: string;
+	details?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Git Lifecycle Events
+// ============================================================================
+
+/** Fired before a commit is created. Handlers can veto or rewrite the message. */
+export interface BeforeCommitEvent {
+	type: "before_commit";
+	message: string;
+	files: string[];
+	cwd: string;
+	author?: string;
+}
+
+/** Result from before_commit event handler. */
+export interface BeforeCommitEventResult {
+	cancel?: boolean;
+	reason?: string;
+	message?: string;
+}
+
+/** Fired after a commit lands. */
+export interface CommitEvent {
+	type: "commit";
+	sha: string;
+	message: string;
+	files: string[];
+	cwd: string;
+}
+
+/** Fired before a git push. Handlers can veto. */
+export interface BeforePushEvent {
+	type: "before_push";
+	remote: string;
+	branch: string;
+	cwd: string;
+}
+
+/** Result from before_push event handler. */
+export interface BeforePushEventResult {
+	cancel?: boolean;
+	reason?: string;
+}
+
+/** Fired after a push completes. */
+export interface PushEvent {
+	type: "push";
+	remote: string;
+	branch: string;
+	cwd: string;
+}
+
+/** Fired before a pull request is opened. Handlers can veto or rewrite title/body. */
+export interface BeforePrEvent {
+	type: "before_pr";
+	branch: string;
+	targetBranch: string;
+	title: string;
+	body: string;
+	cwd: string;
+}
+
+/** Result from before_pr event handler. */
+export interface BeforePrEventResult {
+	cancel?: boolean;
+	reason?: string;
+	title?: string;
+	body?: string;
+}
+
+/** Fired after a pull request is opened. */
+export interface PrOpenedEvent {
+	type: "pr_opened";
+	url: string;
+	branch: string;
+	targetBranch: string;
+	cwd: string;
+}
+
+// ============================================================================
+// Verification Events
+// ============================================================================
+
+/** Fired before verification runs (tests, diagnostics, gates). */
+export interface BeforeVerifyEvent {
+	type: "before_verify";
+	unitType?: string;
+	unitId?: string;
+	cwd: string;
+}
+
+/** Result from before_verify event handler. */
+export interface BeforeVerifyEventResult {
+	cancel?: boolean;
+	reason?: string;
+}
+
+/** A single verification failure. */
+export interface VerifyFailure {
+	kind: "type" | "lint" | "test" | "diagnostic" | "gate" | "other";
+	file?: string;
+	line?: number;
+	message: string;
+}
+
+/** Fired when verification completes. */
+export interface VerifyResultEvent {
+	type: "verify_result";
+	passed: boolean;
+	failures: VerifyFailure[];
+	unitType?: string;
+	unitId?: string;
+	cwd: string;
+}
+
+// ============================================================================
+// Budget Events
+// ============================================================================
+
+/** Fired when the tracked cost crosses a configured fraction of the budget. */
+export interface BudgetThresholdEvent {
+	type: "budget_threshold";
+	fraction: number;
+	spent: number;
+	limit: number;
+	currency: "USD";
+}
+
+/** Result from budget_threshold event handler. */
+export interface BudgetThresholdEventResult {
+	action?: "pause" | "downgrade" | "continue";
+}
+
+// ============================================================================
+// Orchestrator Events (milestone / unit boundaries)
+// ============================================================================
+
+/** Fired at the start of an orchestrator milestone. */
+export interface MilestoneStartEvent {
+	type: "milestone_start";
+	milestoneId: string;
+	title?: string;
+	cwd: string;
+}
+
+/** Fired when a milestone ends. */
+export interface MilestoneEndEvent {
+	type: "milestone_end";
+	milestoneId: string;
+	status: "completed" | "failed" | "cancelled";
+	cwd: string;
+}
+
+/** Fired at the start of an orchestrator unit (sub-task within a milestone). */
+export interface UnitStartEvent {
+	type: "unit_start";
+	unitType: string;
+	unitId: string;
+	milestoneId?: string;
+	cwd: string;
+}
+
+/** Fired when a unit ends. */
+export interface UnitEndEvent {
+	type: "unit_end";
+	unitType: string;
+	unitId: string;
+	milestoneId?: string;
+	status: "completed" | "failed" | "cancelled" | "blocked";
+	cwd: string;
+}
+
 /** Fired at the start of each turn */
 export interface TurnStartEvent {
 	type: "turn_start";
@@ -913,6 +1114,21 @@ export type ExtensionEvent =
 	| BeforeAgentStartEvent
 	| AgentStartEvent
 	| AgentEndEvent
+	| StopEvent
+	| NotificationEvent
+	| BeforeCommitEvent
+	| CommitEvent
+	| BeforePushEvent
+	| PushEvent
+	| BeforePrEvent
+	| PrOpenedEvent
+	| BeforeVerifyEvent
+	| VerifyResultEvent
+	| BudgetThresholdEvent
+	| MilestoneStartEvent
+	| MilestoneEndEvent
+	| UnitStartEvent
+	| UnitEndEvent
 	| TurnStartEvent
 	| TurnEndEvent
 	| MessageStartEvent
@@ -1085,6 +1301,7 @@ export interface ExtensionAPI {
 	): void;
 	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
 	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_end", handler: ExtensionHandler<SessionEndEvent>): void;
 	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
 	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
 	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
@@ -1095,6 +1312,21 @@ export interface ExtensionAPI {
 	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
 	on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
 	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
+	on(event: "stop", handler: ExtensionHandler<StopEvent>): void;
+	on(event: "notification", handler: ExtensionHandler<NotificationEvent>): void;
+	on(event: "before_commit", handler: ExtensionHandler<BeforeCommitEvent, BeforeCommitEventResult>): void;
+	on(event: "commit", handler: ExtensionHandler<CommitEvent>): void;
+	on(event: "before_push", handler: ExtensionHandler<BeforePushEvent, BeforePushEventResult>): void;
+	on(event: "push", handler: ExtensionHandler<PushEvent>): void;
+	on(event: "before_pr", handler: ExtensionHandler<BeforePrEvent, BeforePrEventResult>): void;
+	on(event: "pr_opened", handler: ExtensionHandler<PrOpenedEvent>): void;
+	on(event: "before_verify", handler: ExtensionHandler<BeforeVerifyEvent, BeforeVerifyEventResult>): void;
+	on(event: "verify_result", handler: ExtensionHandler<VerifyResultEvent>): void;
+	on(event: "budget_threshold", handler: ExtensionHandler<BudgetThresholdEvent, BudgetThresholdEventResult>): void;
+	on(event: "milestone_start", handler: ExtensionHandler<MilestoneStartEvent>): void;
+	on(event: "milestone_end", handler: ExtensionHandler<MilestoneEndEvent>): void;
+	on(event: "unit_start", handler: ExtensionHandler<UnitStartEvent>): void;
+	on(event: "unit_end", handler: ExtensionHandler<UnitEndEvent>): void;
 	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
 	on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
@@ -1122,6 +1354,18 @@ export interface ExtensionAPI {
 	/** Emit adjust_tool_set event (ADR-005). Returns override tool names or undefined. */
 	emitAdjustToolSet(event: Omit<AdjustToolSetEvent, "type">): Promise<AdjustToolSetResult | undefined>;
 
+	/**
+	 * Emit a Layer 2 extension event from an extension. Supports the
+	 * post-plan additions: `notification`, `stop`, `session_end`,
+	 * `before_commit` / `commit`, `before_push` / `push`, `before_pr` /
+	 * `pr_opened`, `before_verify` / `verify_result`, `budget_threshold`,
+	 * `milestone_start` / `milestone_end`, `unit_start` / `unit_end`.
+	 *
+	 * The returned value is the aggregate handler result where meaningful
+	 * (e.g. `{ cancel: true, reason }` from `before_commit`).
+	 */
+	emitExtensionEvent(event: ExtensionEvent): Promise<unknown>;
+
 	// =========================================================================
 	// Tool Registration
 	// =========================================================================
@@ -1442,6 +1686,13 @@ export interface ExtensionRuntimeState {
 	emitBeforeModelSelect: (event: Omit<BeforeModelSelectEvent, "type">) => Promise<BeforeModelSelectResult | undefined>;
 	/** Emit adjust_tool_set event to all registered handlers. Bound by ExtensionRunner (ADR-005). */
 	emitAdjustToolSet: (event: Omit<AdjustToolSetEvent, "type">) => Promise<AdjustToolSetResult | undefined>;
+	/**
+	 * Emit a Layer 2 extension event from an extension. Supports the
+	 * post-plan additions (notification, stop, git lifecycle, verify,
+	 * budget, milestone, unit, session_end). Returns the handler chain's
+	 * aggregate result for events that support vetoes / mutations.
+	 */
+	emitExtensionEvent: (event: ExtensionEvent) => Promise<unknown>;
 }
 
 /**

package/packages/pi-coding-agent/src/core/hooks-runner.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { CONFIG_DIR_NAME } from "../config.js";
+import { ExtensionRunner } from "./extensions/runner.js";
+import { createHooksRunner, isProjectHooksTrusted } from "./hooks-runner.js";
+import type { ExtensionRuntime } from "./extensions/types.js";
+import type { Settings } from "./settings-manager.js";
+
+function makeTempProject() {
+  const base = mkdtempSync(join(tmpdir(), "hooks-runner-test-"));
+  mkdirSync(join(base, CONFIG_DIR_NAME), { recursive: true });
+  return base;
+}
+
+function trust(cwd: string) {
+  writeFileSync(join(cwd, CONFIG_DIR_NAME, "hooks.trusted"), "");
+}
+
+function stubRuntime(): ExtensionRuntime {
+  return {
+    flagValues: new Map(),
+    pendingProviderRegistrations: [],
+    registerProvider: () => {},
+    unregisterProvider: () => {},
+    emitBeforeModelSelect: async () => undefined,
+    emitAdjustToolSet: async () => undefined,
+    emitExtensionEvent: async () => undefined,
+    sendMessage: () => {},
+    sendUserMessage: () => {},
+    retryLastTurn: () => {},
+    appendEntry: () => {},
+    setSessionName: () => {},
+    getSessionName: () => undefined,
+    setLabel: () => {},
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools: () => {},
+    refreshTools: () => {},
+    getCommands: () => [],
+    setModel: async () => false,
+    getThinkingLevel: () => "off",
+    setThinkingLevel: () => {},
+  };
+}
+
+function makeRunner(cwd: string): ExtensionRunner {
+  return new ExtensionRunner(
+    [],
+    stubRuntime(),
+    cwd,
+    {} as never,
+    {} as never,
+  );
+}
+
+describe("isProjectHooksTrusted", () => {
+  let tmpCwd: string | undefined;
+  afterEach(() => {
+    if (tmpCwd) rmSync(tmpCwd, { recursive: true, force: true });
+    tmpCwd = undefined;
+  });
+
+  it("returns false when the marker is missing", () => {
+    tmpCwd = makeTempProject();
+    assert.equal(isProjectHooksTrusted(tmpCwd), false);
+  });
+
+  it("returns true after the marker is written", () => {
+    tmpCwd = makeTempProject();
+    trust(tmpCwd);
+    assert.equal(isProjectHooksTrusted(tmpCwd), true);
+  });
+});
+
+describe("createHooksRunner — trust gate", () => {
+  let tmpCwd: string | undefined;
+  afterEach(() => {
+    if (tmpCwd) rmSync(tmpCwd, { recursive: true, force: true });
+    tmpCwd = undefined;
+  });
+
+  it("ignores project hooks when the trust marker is absent", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+    const invocations: string[] = [];
+
+    const hooks = createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({}),
+      getProjectSettings: (): Settings => ({
+        hooks: {
+          SessionStart: [
+            { command: `node -e "process.stdout.write('{}')"` },
+          ],
+        },
+      }),
+      cwd: tmpCwd,
+      onInvocation: (i) => invocations.push(i.command),
+    });
+
+    await hooks.fireSessionStart();
+    assert.deepEqual(invocations, []);
+    hooks.dispose();
+  });
+
+  it("runs project hooks when the trust marker is present", async () => {
+    tmpCwd = makeTempProject();
+    trust(tmpCwd);
+    const runner = makeRunner(tmpCwd);
+    const invocations: string[] = [];
+
+    const hooks = createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({}),
+      getProjectSettings: (): Settings => ({
+        hooks: {
+          SessionStart: [{ command: `node -e "process.exit(0)"` }],
+        },
+      }),
+      cwd: tmpCwd,
+      onInvocation: (i) => invocations.push(i.command),
+    });
+
+    await hooks.fireSessionStart();
+    assert.deepEqual(invocations, [`node -e "process.exit(0)"`]);
+    hooks.dispose();
+  });
+
+  it("runs global hooks unconditionally", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+    const invocations: string[] = [];
+
+    const hooks = createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({
+        hooks: { SessionStart: [{ command: `node -e "process.exit(0)"` }] },
+      }),
+      getProjectSettings: (): Settings => ({}),
+      cwd: tmpCwd,
+      onInvocation: (i) => invocations.push(i.command),
+    });
+
+    await hooks.fireSessionStart();
+    assert.deepEqual(invocations, [`node -e "process.exit(0)"`]);
+    hooks.dispose();
+  });
+});
+
+describe("createHooksRunner — PreToolUse bridges to tool_call", () => {
+  let tmpCwd: string | undefined;
+  afterEach(() => {
+    if (tmpCwd) rmSync(tmpCwd, { recursive: true, force: true });
+    tmpCwd = undefined;
+  });
+
+  it("blocks a tool call when the PreToolUse hook returns { block: true }", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+
+    createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({
+        hooks: {
+          PreToolUse: [
+            {
+              command: `node -e "process.stdout.write(JSON.stringify({block:true,reason:'nope'}))"`,
+            },
+          ],
+        },
+      }),
+      getProjectSettings: (): Settings => ({}),
+      cwd: tmpCwd,
+    });
+
+    const result = await runner.emitToolCall({
+      type: "tool_call",
+      toolCallId: "t1",
+      toolName: "bash",
+      input: { command: "ls" },
+    });
+    assert.equal(result?.block, true);
+    assert.equal(result?.reason, "nope");
+  });
+
+  it("applies filter.tool to scope the hook", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+
+    createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({
+        hooks: {
+          PreToolUse: [
+            {
+              match: { tool: "bash" },
+              command: `node -e "process.stdout.write(JSON.stringify({block:true,reason:'bash-only'}))"`,
+            },
+          ],
+        },
+      }),
+      getProjectSettings: (): Settings => ({}),
+      cwd: tmpCwd,
+    });
+
+    const readResult = await runner.emitToolCall({
+      type: "tool_call",
+      toolCallId: "t2",
+      toolName: "read",
+      input: { path: "/tmp/x" },
+    });
+    assert.equal(readResult?.block, undefined);
+
+    const bashResult = await runner.emitToolCall({
+      type: "tool_call",
+      toolCallId: "t3",
+      toolName: "bash",
+      input: { command: "rm -rf /" },
+    });
+    assert.equal(bashResult?.block, true);
+  });
+
+  it("treats a non-zero exit as a block when blocking is not disabled", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+
+    createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({
+        hooks: { PreToolUse: [{ command: `node -e "process.exit(1)"` }] },
+      }),
+      getProjectSettings: (): Settings => ({}),
+      cwd: tmpCwd,
+    });
+
+    const result = await runner.emitToolCall({
+      type: "tool_call",
+      toolCallId: "t4",
+      toolName: "bash",
+      input: { command: "ls" },
+    });
+    assert.equal(result?.block, true);
+  });
+
+  it("does not block when blocking: false and exit is non-zero", async () => {
+    tmpCwd = makeTempProject();
+    const runner = makeRunner(tmpCwd);
+
+    createHooksRunner({
+      extensionRunner: runner,
+      getGlobalSettings: (): Settings => ({
+        hooks: { PreToolUse: [{ command: `node -e "process.exit(1)"`, blocking: false }] },
+      }),
+      getProjectSettings: (): Settings => ({}),
+      cwd: tmpCwd,
+    });
+
+    const result = await runner.emitToolCall({
+      type: "tool_call",
+      toolCallId: "t5",
+      toolName: "bash",
+      input: { command: "ls" },
+    });
+    assert.equal(result?.block, undefined);
+  });
+});