feat(server): in-app project hooks — live config, fail-closed, in-app approvals

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );

apps/server/src/hooks/T3HookRunner.test.ts

@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Logger from "effect/Logger";
 import * as Path from "effect/Path";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
@@ -28,6 +30,18 @@ const successfulOutput = (stdout: string): ProcessRunOutput => ({
  stderrInvalidUtf8: false,
 });
 
+function writeHooksConfig(root: string, hooks: unknown) {
+ return Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, encodeJson({ hooks }));
+ return configPath;
+ });
+}
+
 function testLayer(run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput>) {
  return Layer.effect(T3HookRunner.T3HookRunner, T3HookRunner.make()).pipe(
  Layer.provide(
@@ -195,4 +209,209 @@ describe("T3HookRunner", () => {
  }),
  );
  });
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed({
+ ...successfulOutput(""),
+ code: 2 as ProcessRunOutput["code"],
+ stderr: "Hook added while the session was running.",
+ }),
+ ),
+ )("picks up a config created after prepare", (it) => {
+ it.effect("reports live hooks and evaluates them", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.equal(plan.configPath, undefined);
+ assert.isFalse(plan.hasPreToolUseHooks);
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ const decision = yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-created",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ });
+
+ assert.deepEqual(decision, {
+ decision: "deny",
+ reason: "Hook added while the session was running.",
+ });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("a deleted config must not run a hook")))(
+ "picks up a config deleted after prepare",
+ (it) => {
+ it.effect("reports no live hooks and allows the tool call", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isTrue(plan.hasPreToolUseHooks);
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+
+ yield* fileSystem.remove(configPath);
+
+ assert.isFalse(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "claudeAgent",
+ threadId: "thread-deleted",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ { decision: "allow" },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(
+ successfulOutput(encodeJson({ decision: "ask", reason: "Bash needs confirmation." })),
+ ),
+ ),
+ )("applies an edited matcher without preparing again", (it) => {
+ it.effect("re-reads the config before each evaluation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ const bashCall = {
+ provider: "claudeAgent",
+ threadId: "thread-edited",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), {
+ decision: "ask",
+ reason: "Bash needs confirmation.",
+ });
+
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "policy" }] }],
+ });
+
+ assert.deepEqual(yield* plan.evaluatePreToolUse(bashCall), { decision: "allow" });
+ }),
+ );
+ });
+
+ it.layer(testLayer(() => Effect.die("an unreadable config must not run a hook")))(
+ "fails closed when the config becomes invalid mid-session",
+ (it) => {
+ it.effect("reports live hooks and asks for confirmation", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const plan = yield* runner.prepare(root);
+ assert.isFalse(plan.hasPreToolUseHooks);
+
+ const configDirectory = path.join(root, ".t3code");
+ yield* fileSystem.makeDirectory(configDirectory, { recursive: true });
+ const configPath = path.join(configDirectory, "hooks.json");
+ yield* fileSystem.writeFileString(configPath, "{ not json");
+
+ assert.isTrue(yield* plan.hasPreToolUseHooksNow);
+ assert.deepEqual(
+ yield* plan.evaluatePreToolUse({
+ provider: "codex",
+ threadId: "thread-invalid",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ }),
+ {
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${configPath}.`,
+ },
+ );
+ }),
+ );
+ },
+ );
+
+ it.layer(
+ testLayer(() =>
+ Effect.succeed(successfulOutput(encodeJson({ decision: "ask", reason: "Reviewed." }))),
+ ),
+ )("warns about hook events it does not implement", (it) => {
+ it.effect("warns once and still runs PreToolUse", () =>
+ Effect.gen(function* () {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-hook-runner-" });
+ const configPath = yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ PostToolUse: [{ hooks: [{ type: "command", command: "after" }] }],
+ Stop: [{ hooks: [{ type: "command", command: "stop" }] }],
+ });
+
+ const runner = yield* T3HookRunner.T3HookRunner;
+ const records: Array<{ readonly logLevel: LogLevel.LogLevel; readonly message: unknown }> =
+ [];
+ const logger = Logger.make<unknown, void>(({ logLevel, message }) => {
+ records.push({ logLevel, message });
+ });
+
+ const decisions = yield* Effect.gen(function* () {
+ const plan = yield* runner.prepare(root);
+ const call = {
+ provider: "claudeAgent",
+ threadId: "thread-unsupported",
+ toolName: "Bash",
+ toolInput: { command: "git push" },
+ };
+ const initialDecisions = [
+ yield* plan.evaluatePreToolUse(call),
+ yield* plan.evaluatePreToolUse(call),
+ ];
+ yield* writeHooksConfig(root, {
+ PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "policy" }] }],
+ "PostToolUse,Stop": [{ hooks: [{ type: "command", command: "combined" }] }],
+ });
+ return [...initialDecisions, yield* plan.evaluatePreToolUse(call)];
+ }).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
+
+ const warnings = records.filter((record) => record.logLevel === "Warn");
+ assert.equal(warnings.length, 2);
+ const rendered = encodeJson(warnings[0]?.message);
+ assert.match(rendered, /PostToolUse/);
+ assert.match(rendered, /Stop/);
+ assert.include(rendered, encodeJson(configPath));
+ assert.match(encodeJson(warnings[1]?.message), /PostToolUse,Stop/);
+ assert.deepEqual(decisions, [
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ { decision: "ask", reason: "Reviewed." },
+ ]);
+ }),
+ );
+ });
 });

apps/server/src/hooks/T3HookRunner.ts

@@ -35,6 +35,15 @@ const HooksConfig = Schema.Struct({
 const HooksConfigJson = fromLenientJson(HooksConfig);
 const decodeHooksConfigJson = Schema.decodeUnknownEffect(HooksConfigJson);
 
+const HooksConfigEventKeys = Schema.Struct({
+ hooks: Schema.Record(Schema.String, Schema.Unknown),
+});
+const decodeHooksConfigEventKeysJson = Schema.decodeUnknownEffect(
+ fromLenientJson(HooksConfigEventKeys),
+);
+
+const SUPPORTED_HOOK_EVENTS = ["PreToolUse"] as const;
+
 const HookSpecificOutput = Schema.Struct({
  hookEventName: Schema.optional(Schema.String),
  permissionDecision: Schema.optional(Schema.Literals(["allow", "ask", "deny"])),
@@ -87,6 +96,7 @@ export interface T3PreToolUseInput {
 export interface T3HookPlan {
  readonly configPath: string | undefined;
  readonly hasPreToolUseHooks: boolean;
+ readonly hasPreToolUseHooksNow: Effect.Effect<boolean>;
  readonly evaluatePreToolUse: (
  input: Omit<T3PreToolUseInput, "cwd">,
  ) => Effect.Effect<T3HookDecision, T3HookCommandError>;
@@ -139,6 +149,14 @@ function normalizedDecision(output: typeof HookCommandOutput.Type): T3HookDecisi
  };
 }
 
+function logConfigFailure(error: T3HookConfigError) {
+ return Effect.logWarning("T3 project hooks could not be loaded", {
+ path: error.configPath,
+ operation: error.operation,
+ cause: error.cause,
+ });
+}
+
 function expandProjectDirectory(command: string, projectDirectory: string): string {
  return command
  .replaceAll("${T3_PROJECT_DIR}", projectDirectory)
@@ -182,6 +200,7 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  const path = yield* Path.Path;
  const processRunner = yield* ProcessRunner;
  const platform = yield* HostProcessPlatform;
+ const warnedUnsupportedEvents = new Set<string>();
 
  const findConfigPath = Effect.fn("T3HookRunner.findConfigPath")(function* (cwd: string) {
  let current = cwd;
@@ -242,6 +261,28 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  });
  }
  }
+
+ const declaredEvents = yield* decodeHooksConfigEventKeysJson(raw).pipe(
+ Effect.map((decoded) => Object.keys(decoded.hooks)),
+ Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+ );
+ const unsupportedEvents = declaredEvents
+ .filter((event) => !SUPPORTED_HOOK_EVENTS.some((supported) => supported === event))
+ .sort();
+ if (unsupportedEvents.length > 0) {
+ const warningKey = [configPath, ...unsupportedEvents]
+ .map((part) => `${part.length}:${part}`)
+ .join("");
+ if (!warnedUnsupportedEvents.has(warningKey)) {
+ warnedUnsupportedEvents.add(warningKey);
+ yield* Effect.logWarning("ignoring unsupported T3 hook events", {
+ path: configPath,
+ unsupportedEvents,
+ supportedEvents: SUPPORTED_HOOK_EVENTS,
+ });
+ }
+ }
+
  return config;
  });
 
@@ -342,31 +383,61 @@ export const make = Effect.fn("T3HookRunner.make")(function* () {
  return { decision: "allow" } satisfies T3HookDecision;
  });
 
+ const resolvePlanState = Effect.fn("T3HookRunner.resolvePlanState")(function* (cwd: string) {
+ const configPathOption = yield* findConfigPath(cwd);
+ if (Option.isNone(configPathOption)) {
+ return {
+ configPath: undefined,
+ entries: [] as ReadonlyArray<HookMatcherConfig>,
+ projectDirectory: undefined,
+ };
+ }
+
+ const configPath = configPathOption.value;
+ const config = yield* readConfig(configPath);
+ return {
+ configPath,
+ entries: config.hooks.PreToolUse ?? ([] as ReadonlyArray<HookMatcherConfig>),
+ projectDirectory: path.dirname(path.dirname(configPath)),
+ };
+ });
+
  const prepare: T3HookRunner["Service"]["prepare"] = Effect.fn("T3HookRunner.prepare")(
  function* (cwd) {
- const configPathOption = yield* findConfigPath(cwd);
- if (Option.isNone(configPathOption)) {
- return {
- configPath: undefined,
- hasPreToolUseHooks: false,
- evaluatePreToolUse: () => Effect.succeed({ decision: "allow" as const }),
- } satisfies T3HookPlan;
- }
-
- const configPath = configPathOption.value;
- const config = yield* readConfig(configPath);
- const entries = config.hooks.PreToolUse ?? [];
- const projectDirectory = path.dirname(path.dirname(configPath));
+ const snapshot = yield* resolvePlanState(cwd);
+ const snapshotHasHooks = snapshot.entries.length > 0;
  return {
- configPath,
- hasPreToolUseHooks: entries.length > 0,
+ configPath: snapshot.configPath,
+ hasPreToolUseHooks: snapshotHasHooks,
+ hasPreToolUseHooksNow: resolvePlanState(cwd).pipe(
+ Effect.map((state) => state.entries.length > 0),
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(Effect.as(true)),
+ ),
+ ),
  evaluatePreToolUse: (input) =>
- evaluateEntries({
- entries,
- configPath,
- projectDirectory,
- payload: { ...input, cwd },
- }),
+ Effect.gen(function* () {
+ const state = yield* resolvePlanState(cwd);
+ if (state.configPath === undefined) {
+ return { decision: "allow" } satisfies T3HookDecision;
+ }
+ return yield* evaluateEntries({
+ entries: state.entries,
+ configPath: state.configPath,
+ projectDirectory: state.projectDirectory,
+ payload: { ...input, cwd },
+ });
+ }).pipe(
+ Effect.catchTag("T3HookConfigError", (error) =>
+ logConfigFailure(error).pipe(
+ Effect.as({
+ decision: "ask",
+ title: "T3 hook config failed",
+ reason: `T3 project hooks could not be loaded from ${error.configPath}.`,
+ } satisfies T3HookDecision),
+ ),
+ ),
+ ),
  } satisfies T3HookPlan;
  },
  );