cc-hooks-ts 2.0.76 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +20 -18
  2. package/dist/index.d.mts +24 -23
  3. package/dist/index.mjs +35 -27
  4. package/package.json +6 -6
package/README.md CHANGED
@@ -59,15 +59,15 @@ import { defineHook } from "cc-hooks-ts";
59
59
  const hook = defineHook({
60
60
  // Specify the event(s) that trigger this hook.
61
61
  trigger: {
62
- SessionStart: true
62
+ SessionStart: true,
63
63
  },
64
64
  // Implement what you want to do.
65
65
  run: (context) => {
66
66
  // Do something great here
67
67
  return context.success({
68
- messageForUser: "Welcome to your coding session!"
68
+ messageForUser: "Welcome to your coding session!",
69
69
  });
70
- }
70
+ },
71
71
  });
72
72
 
73
73
  // import.meta.main is available in Node.js 24.2+ and Bun and Deno
@@ -111,12 +111,12 @@ const preReadHook = defineHook({
111
111
  // context.input.tool_input is typed as { file_path: string; limit?: number; offset?: number; }
112
112
  const { file_path } = context.input.tool_input;
113
113
 
114
- if (file_path.includes('.env')) {
115
- return context.blockingError('Cannot read environment files');
114
+ if (file_path.includes(".env")) {
115
+ return context.blockingError("Cannot read environment files");
116
116
  }
117
117
 
118
118
  return context.success();
119
- }
119
+ },
120
120
  });
121
121
 
122
122
  if (import.meta.main) {
@@ -174,11 +174,11 @@ const deepWikiHook = defineHook({
174
174
  const { question, repoName } = context.input.tool_input;
175
175
 
176
176
  if (question.length > 500) {
177
- return context.blockingError('Question is too long');
177
+ return context.blockingError("Question is too long");
178
178
  }
179
179
 
180
180
  return context.success();
181
- }
181
+ },
182
182
  });
183
183
  ```
184
184
 
@@ -194,14 +194,14 @@ import { defineHook } from "cc-hooks-ts";
194
194
 
195
195
  const hook = defineHook({
196
196
  trigger: {
197
- Notification: true
197
+ Notification: true,
198
198
  },
199
199
  // Only run this hook on macOS
200
200
  shouldRun: () => process.platform === "darwin",
201
201
  run: (context) => {
202
202
  // Some macOS-specific logic like sending a notification using AppleScript
203
- return context.success()
204
- }
203
+ return context.success();
204
+ },
205
205
  });
206
206
  ```
207
207
 
@@ -221,9 +221,11 @@ For detailed information about available JSON fields and their behavior, see the
221
221
  >
222
222
  > You can enable it in Claude Code by going to `/config` and setting "verbose" to true.
223
223
 
224
- Claude Code also accepts async hook responses.
224
+ Async JSON output allows hooks to perform longer computations without blocking the Claude Code TUI.
225
+
226
+ You can use `context.defer()` to respond Claude Code immediately while performing longer computations in the background.
225
227
 
226
- Use `context.defer()` when you need extra time to compute hook output.
228
+ You should complete the async operation within a reasonable time (e.g. 15 seconds).
227
229
 
228
230
  ```ts
229
231
  import { defineHook } from "cc-hooks-ts";
@@ -239,14 +241,14 @@ const hook = defineHook({
239
241
  return {
240
242
  event: "PostToolUse",
241
243
  output: {
242
- systemMessage: "Read tool used successfully after async processing!"
243
- }
244
+ systemMessage: "Read tool used successfully after async processing!",
245
+ },
244
246
  };
245
247
  },
246
248
  {
247
- timeoutMs: 5000 // Optional timeout for the async operation.
248
- }
249
- )
249
+ timeoutMs: 5000, // Optional timeout for the async operation.
250
+ },
251
+ ),
250
252
  });
251
253
  ```
252
254
 
package/dist/index.d.mts CHANGED
@@ -104,7 +104,7 @@ declare const HookInputSchemas: {
104
104
  readonly hook_event_name: v.LiteralSchema<"PreCompact", undefined>;
105
105
  } & {
106
106
  custom_instructions: v.NullableSchema<v.StringSchema<undefined>, undefined>;
107
- trigger: v.UnionSchema<[v.LiteralSchema<"manual", undefined>, v.LiteralSchema<"auto", undefined>], undefined>;
107
+ trigger: v.PicklistSchema<["manual", "auto"], undefined>;
108
108
  }, undefined>;
109
109
  readonly SessionStart: v.ObjectSchema<{
110
110
  readonly cwd: v.StringSchema<undefined>;
@@ -113,7 +113,8 @@ declare const HookInputSchemas: {
113
113
  readonly transcript_path: v.StringSchema<undefined>;
114
114
  readonly hook_event_name: v.LiteralSchema<"SessionStart", undefined>;
115
115
  } & {
116
- source: v.UnionSchema<[v.LiteralSchema<"startup", undefined>, v.LiteralSchema<"resume", undefined>, v.LiteralSchema<"clear", undefined>, v.LiteralSchema<"compact", undefined>], undefined>;
116
+ agent_type: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
117
+ source: v.PicklistSchema<["startup", "resume", "clear", "compact"], undefined>;
117
118
  }, undefined>;
118
119
  readonly SessionEnd: v.ObjectSchema<{
119
120
  readonly cwd: v.StringSchema<undefined>;
@@ -122,7 +123,7 @@ declare const HookInputSchemas: {
122
123
  readonly transcript_path: v.StringSchema<undefined>;
123
124
  readonly hook_event_name: v.LiteralSchema<"SessionEnd", undefined>;
124
125
  } & {
125
- reason: v.StringSchema<undefined>;
126
+ reason: v.PicklistSchema<["clear", "logout", "prompt_input_exit", "other", "bypass_permissions_disabled"], undefined>;
126
127
  }, undefined>;
127
128
  readonly PermissionRequest: v.ObjectSchema<{
128
129
  readonly cwd: v.StringSchema<undefined>;
@@ -132,39 +133,39 @@ declare const HookInputSchemas: {
132
133
  readonly hook_event_name: v.LiteralSchema<"PermissionRequest", undefined>;
133
134
  } & {
134
135
  permission_suggestions: v.ExactOptionalSchema<v.ArraySchema<v.VariantSchema<"type", [v.ObjectSchema<{
135
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
136
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
136
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
137
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
137
138
  readonly rules: v.ArraySchema<v.ObjectSchema<{
138
139
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
139
140
  readonly toolName: v.StringSchema<undefined>;
140
141
  }, undefined>, undefined>;
141
142
  readonly type: v.LiteralSchema<"addRules", undefined>;
142
143
  }, undefined>, v.ObjectSchema<{
143
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
144
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
144
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
145
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
145
146
  readonly rules: v.ArraySchema<v.ObjectSchema<{
146
147
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
147
148
  readonly toolName: v.StringSchema<undefined>;
148
149
  }, undefined>, undefined>;
149
150
  readonly type: v.LiteralSchema<"replaceRules", undefined>;
150
151
  }, undefined>, v.ObjectSchema<{
151
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
152
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
152
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
153
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
153
154
  readonly rules: v.ArraySchema<v.ObjectSchema<{
154
155
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
155
156
  readonly toolName: v.StringSchema<undefined>;
156
157
  }, undefined>, undefined>;
157
158
  readonly type: v.LiteralSchema<"removeRules", undefined>;
158
159
  }, undefined>, v.ObjectSchema<{
159
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
160
- readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"delegate", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
160
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
161
+ readonly mode: v.PicklistSchema<["acceptEdits", "bypassPermissions", "default", "dontAsk", "delegate", "plan"], undefined>;
161
162
  readonly type: v.LiteralSchema<"setMode", undefined>;
162
163
  }, undefined>, v.ObjectSchema<{
163
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
164
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
164
165
  readonly directories: v.ArraySchema<v.StringSchema<undefined>, undefined>;
165
166
  readonly type: v.LiteralSchema<"addDirectories", undefined>;
166
167
  }, undefined>, v.ObjectSchema<{
167
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
168
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
168
169
  readonly directories: v.ArraySchema<v.StringSchema<undefined>, undefined>;
169
170
  readonly type: v.LiteralSchema<"removeDirectories", undefined>;
170
171
  }, undefined>], undefined>, undefined>, undefined>;
@@ -265,39 +266,39 @@ type ToolSpecificPostToolUseFailureInput = { [K in keyof ToolSchema]: Omit<BaseH
265
266
  * @package
266
267
  */
267
268
  declare const permissionUpdateSchema: v.VariantSchema<"type", [v.ObjectSchema<{
268
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
269
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
269
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
270
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
270
271
  readonly rules: v.ArraySchema<v.ObjectSchema<{
271
272
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
272
273
  readonly toolName: v.StringSchema<undefined>;
273
274
  }, undefined>, undefined>;
274
275
  readonly type: v.LiteralSchema<"addRules", undefined>;
275
276
  }, undefined>, v.ObjectSchema<{
276
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
277
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
277
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
278
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
278
279
  readonly rules: v.ArraySchema<v.ObjectSchema<{
279
280
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
280
281
  readonly toolName: v.StringSchema<undefined>;
281
282
  }, undefined>, undefined>;
282
283
  readonly type: v.LiteralSchema<"replaceRules", undefined>;
283
284
  }, undefined>, v.ObjectSchema<{
284
- readonly behavior: v.UnionSchema<[v.LiteralSchema<"allow", undefined>, v.LiteralSchema<"deny", undefined>, v.LiteralSchema<"ask", undefined>], undefined>;
285
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
285
+ readonly behavior: v.PicklistSchema<["allow", "deny", "ask"], undefined>;
286
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
286
287
  readonly rules: v.ArraySchema<v.ObjectSchema<{
287
288
  readonly ruleContent: v.ExactOptionalSchema<v.StringSchema<undefined>, undefined>;
288
289
  readonly toolName: v.StringSchema<undefined>;
289
290
  }, undefined>, undefined>;
290
291
  readonly type: v.LiteralSchema<"removeRules", undefined>;
291
292
  }, undefined>, v.ObjectSchema<{
292
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
293
- readonly mode: v.UnionSchema<[v.LiteralSchema<"acceptEdits", undefined>, v.LiteralSchema<"bypassPermissions", undefined>, v.LiteralSchema<"default", undefined>, v.LiteralSchema<"dontAsk", undefined>, v.LiteralSchema<"delegate", undefined>, v.LiteralSchema<"plan", undefined>], undefined>;
293
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
294
+ readonly mode: v.PicklistSchema<["acceptEdits", "bypassPermissions", "default", "dontAsk", "delegate", "plan"], undefined>;
294
295
  readonly type: v.LiteralSchema<"setMode", undefined>;
295
296
  }, undefined>, v.ObjectSchema<{
296
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
297
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
297
298
  readonly directories: v.ArraySchema<v.StringSchema<undefined>, undefined>;
298
299
  readonly type: v.LiteralSchema<"addDirectories", undefined>;
299
300
  }, undefined>, v.ObjectSchema<{
300
- readonly destination: v.UnionSchema<[v.LiteralSchema<"userSettings", undefined>, v.LiteralSchema<"projectSettings", undefined>, v.LiteralSchema<"localSettings", undefined>, v.LiteralSchema<"session", undefined>, v.LiteralSchema<"cliArg", undefined>], undefined>;
301
+ readonly destination: v.PicklistSchema<["userSettings", "projectSettings", "localSettings", "session", "cliArg"], undefined>;
301
302
  readonly directories: v.ArraySchema<v.StringSchema<undefined>, undefined>;
302
303
  readonly type: v.LiteralSchema<"removeDirectories", undefined>;
303
304
  }, undefined>], undefined>;
package/dist/index.mjs CHANGED
@@ -33,17 +33,17 @@ function createContext(input) {
33
33
  })
34
34
  };
35
35
  }
36
- const permissionBehaviorSchema = v.union([
37
- v.literal("allow"),
38
- v.literal("deny"),
39
- v.literal("ask")
36
+ const permissionBehaviorSchema = v.picklist([
37
+ "allow",
38
+ "deny",
39
+ "ask"
40
40
  ]);
41
- const permissionUpdateDestinationSchema = v.union([
42
- v.literal("userSettings"),
43
- v.literal("projectSettings"),
44
- v.literal("localSettings"),
45
- v.literal("session"),
46
- v.literal("cliArg")
41
+ const permissionUpdateDestinationSchema = v.picklist([
42
+ "userSettings",
43
+ "projectSettings",
44
+ "localSettings",
45
+ "session",
46
+ "cliArg"
47
47
  ]);
48
48
  const permissionRuleValueSchema = v.object({
49
49
  ruleContent: v.exactOptional(v.string()),
@@ -70,13 +70,13 @@ const permissionUpdateSchema = v.variant("type", [
70
70
  }),
71
71
  v.object({
72
72
  destination: permissionUpdateDestinationSchema,
73
- mode: v.union([
74
- v.literal("acceptEdits"),
75
- v.literal("bypassPermissions"),
76
- v.literal("default"),
77
- v.literal("dontAsk"),
78
- v.literal("delegate"),
79
- v.literal("plan")
73
+ mode: v.picklist([
74
+ "acceptEdits",
75
+ "bypassPermissions",
76
+ "default",
77
+ "dontAsk",
78
+ "delegate",
79
+ "plan"
80
80
  ]),
81
81
  type: v.literal("setMode")
82
82
  }),
@@ -141,15 +141,24 @@ const HookInputSchemas = {
141
141
  }),
142
142
  PreCompact: buildHookInputSchema("PreCompact", {
143
143
  custom_instructions: v.nullable(v.string()),
144
- trigger: v.union([v.literal("manual"), v.literal("auto")])
144
+ trigger: v.picklist(["manual", "auto"])
145
145
  }),
146
- SessionStart: buildHookInputSchema("SessionStart", { source: v.union([
147
- v.literal("startup"),
148
- v.literal("resume"),
149
- v.literal("clear"),
150
- v.literal("compact")
146
+ SessionStart: buildHookInputSchema("SessionStart", {
147
+ agent_type: v.exactOptional(v.string()),
148
+ source: v.picklist([
149
+ "startup",
150
+ "resume",
151
+ "clear",
152
+ "compact"
153
+ ])
154
+ }),
155
+ SessionEnd: buildHookInputSchema("SessionEnd", { reason: v.picklist([
156
+ "clear",
157
+ "logout",
158
+ "prompt_input_exit",
159
+ "other",
160
+ "bypass_permissions_disabled"
151
161
  ]) }),
152
- SessionEnd: buildHookInputSchema("SessionEnd", { reason: v.string() }),
153
162
  PermissionRequest: buildHookInputSchema("PermissionRequest", {
154
163
  permission_suggestions: v.exactOptional(v.array(permissionUpdateSchema)),
155
164
  tool_input: v.unknown(),
@@ -187,11 +196,10 @@ async function handleHookResult(eventName, hookResult) {
187
196
  return process.exit(2);
188
197
  case "json-async": {
189
198
  const userTimeout = hookResult.timeoutMs;
190
- const startAsync = {
199
+ console.log(JSON.stringify({
191
200
  async: true,
192
201
  asyncTimeout: userTimeout ?? void 0
193
- };
194
- console.log(JSON.stringify(startAsync));
202
+ }));
195
203
  const safeInvokeDeferredHook = async () => {
196
204
  try {
197
205
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cc-hooks-ts",
3
- "version": "2.0.76",
3
+ "version": "2.1.2",
4
4
  "type": "module",
5
5
  "description": "Write claude code hooks with type safety",
6
6
  "sideEffects": false,
@@ -49,20 +49,20 @@
49
49
  "@virtual-live-lab/tsconfig": "2.1.21",
50
50
  "eslint": "9.39.2",
51
51
  "eslint-plugin-import-access": "3.1.0",
52
- "oxfmt": "0.19.0",
52
+ "oxfmt": "0.22.0",
53
53
  "pkg-pr-new": "0.0.62",
54
54
  "publint": "0.3.16",
55
- "release-it": "19.1.0",
55
+ "release-it": "19.2.2",
56
56
  "release-it-pnpm": "4.6.6",
57
- "tsdown": "0.18.1",
57
+ "tsdown": "0.18.4",
58
58
  "type-fest": "5.3.1",
59
59
  "typescript": "5.9.3",
60
- "typescript-eslint": "8.50.0",
60
+ "typescript-eslint": "8.52.0",
61
61
  "unplugin-unused": "0.5.6",
62
62
  "vitest": "4.0.16"
63
63
  },
64
64
  "dependencies": {
65
- "@anthropic-ai/claude-agent-sdk": "0.1.76",
65
+ "@anthropic-ai/claude-agent-sdk": "0.2.2",
66
66
  "valibot": "^1.1.0"
67
67
  },
68
68
  "scripts": {