@aaac/runtime 0.1.44 → 0.1.49

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.
@@ -0,0 +1,314 @@
1
+ import { a as GuardrailRuleData } from '../../guardrail-hooks-slK-z0Dz.js';
2
+
3
+ /**
4
+ * Claude Code Hook Protocol — parse stdin JSON input and emit hook response JSON.
5
+ *
6
+ * Implements the protocol defined at https://code.claude.com/docs/en/hooks
7
+ * for SessionStart, UserPromptSubmit, and PreToolUse hook events.
8
+ */
9
+ type HookEventName = "SessionStart" | "UserPromptSubmit" | "PreToolUse";
10
+ interface SessionStartInput {
11
+ hookEventName: "SessionStart";
12
+ session_id?: string;
13
+ type?: "new" | "resume" | "clear" | "compact";
14
+ }
15
+ interface UserPromptSubmitInput {
16
+ hookEventName: "UserPromptSubmit";
17
+ session_id?: string;
18
+ prompt?: string;
19
+ }
20
+ interface PreToolUseInput {
21
+ hookEventName: "PreToolUse";
22
+ session_id?: string;
23
+ tool_name?: string;
24
+ tool_input?: {
25
+ file_path?: string;
26
+ path?: string;
27
+ command?: string;
28
+ content?: string;
29
+ [key: string]: unknown;
30
+ };
31
+ }
32
+ type HookInput = SessionStartInput | UserPromptSubmitInput | PreToolUseInput;
33
+ type PermissionDecision = "allow" | "deny" | "ask";
34
+ interface HookOutput {
35
+ /** Hook-specific output envelope. */
36
+ hookSpecificOutput?: {
37
+ hookEventName: HookEventName;
38
+ /** Additional context injected into the session. */
39
+ additionalContext?: string;
40
+ /** Permission decision for PreToolUse hooks. */
41
+ permissionDecision?: PermissionDecision;
42
+ /** Reason for the permission decision. */
43
+ permissionDecisionReason?: string;
44
+ };
45
+ }
46
+ /**
47
+ * Parse hook input from a raw JSON string (typically from stdin).
48
+ * Throws on invalid JSON but not on missing fields — callers handle defaults.
49
+ */
50
+ declare function parseHookInput(raw: string): HookInput;
51
+ /**
52
+ * Read all of stdin and parse as hook input JSON.
53
+ */
54
+ declare function readHookInput(): Promise<HookInput>;
55
+ /**
56
+ * Emit a hook response as JSON to stdout.
57
+ */
58
+ declare function emitHookOutput(output: HookOutput): void;
59
+ /**
60
+ * Build a response that injects additional context into the session.
61
+ */
62
+ declare function buildContextResponse(eventName: HookEventName, additionalContext: string): HookOutput;
63
+ /**
64
+ * Build a deny response for PreToolUse hooks.
65
+ */
66
+ declare function buildDenyResponse(reason: string): HookOutput;
67
+ /**
68
+ * Build an allow response (empty output = allow by default).
69
+ */
70
+ declare function buildAllowResponse(): HookOutput;
71
+
72
+ /**
73
+ * Cache Store — read/write `.claude/cache/` directory.
74
+ *
75
+ * Stores navigation-index.json and metadata for graph cache invalidation.
76
+ * Uses atomic write (write-to-temp + rename) for concurrent-access safety.
77
+ */
78
+ interface CacheEntry<T = unknown> {
79
+ data: T;
80
+ /** ISO timestamp of when the cache was written. */
81
+ writtenAt: string;
82
+ /** Hash of source inputs used for invalidation. */
83
+ sourceHash: string;
84
+ }
85
+ interface CacheStoreOptions {
86
+ /** Absolute path to the `.claude/cache/` directory. */
87
+ cacheDir: string;
88
+ }
89
+ interface CacheStore {
90
+ read<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
91
+ write<T = unknown>(key: string, data: T, sourceHash: string): Promise<void>;
92
+ /**
93
+ * Check if a cache entry is fresh by comparing its sourceHash.
94
+ * Returns the cached data if fresh, null if stale or missing.
95
+ */
96
+ readIfFresh<T = unknown>(key: string, currentHash: string): Promise<T | null>;
97
+ /** Get the mtime of a file (for invalidation checks). */
98
+ getFileMtime(filePath: string): Promise<number | null>;
99
+ }
100
+ declare function createCacheStore(options: CacheStoreOptions): CacheStore;
101
+ /**
102
+ * Compute a simple hash string from an array of file mtimes and content strings.
103
+ * Not cryptographic — used only for cache invalidation.
104
+ */
105
+ declare function computeSourceHash(inputs: Array<string | number>): string;
106
+
107
+ /**
108
+ * Latency utilities — timeout wrapper, graph build exclusion, degrade policy.
109
+ *
110
+ * Mirrors the Promise-sharing pattern from analyzer-bridge.ts for concurrent
111
+ * graph build exclusion.
112
+ */
113
+ declare class TimeoutError extends Error {
114
+ constructor(ms: number);
115
+ }
116
+ /**
117
+ * Race a promise against a timeout. Resolves with the promise result or
118
+ * rejects with TimeoutError.
119
+ */
120
+ declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
121
+ /**
122
+ * Creates an exclusive async lock that ensures only one invocation runs at a
123
+ * time. Subsequent callers await the same Promise (analyzer-bridge pattern).
124
+ */
125
+ declare function createExclusiveLock<T>(): {
126
+ run: (fn: () => Promise<T>) => Promise<T>;
127
+ };
128
+ interface DegradeResult<T> {
129
+ value: T;
130
+ degraded: boolean;
131
+ reason?: string;
132
+ }
133
+ /**
134
+ * Attempt an operation with timeout; if it fails or times out, return the
135
+ * fallback value with `degraded: true`.
136
+ */
137
+ declare function withDegrade<T>(operation: () => Promise<T>, fallback: T, timeoutMs: number): Promise<DegradeResult<T>>;
138
+
139
+ /**
140
+ * Artifact Resolver — reverse-lookup path to artifact_id using navigation-index.
141
+ *
142
+ * Uses glob matching from guardrail-hooks.ts to match file paths against
143
+ * artifact path_patterns defined in the navigation index.
144
+ */
145
+ /** Minimal shape of a navigation-index artifact node. */
146
+ interface NavigationArtifact {
147
+ properties?: {
148
+ type?: string;
149
+ authority?: string;
150
+ manual_edit?: string;
151
+ [key: string]: unknown;
152
+ };
153
+ files?: {
154
+ path_patterns?: string[];
155
+ [key: string]: unknown;
156
+ };
157
+ agents?: {
158
+ owners?: string[];
159
+ editors?: string[];
160
+ [key: string]: unknown;
161
+ };
162
+ routes?: {
163
+ regenerate?: string;
164
+ [key: string]: unknown;
165
+ };
166
+ relations?: {
167
+ derived_artifacts?: string[];
168
+ [key: string]: unknown;
169
+ };
170
+ }
171
+ interface ArtifactMatch {
172
+ artifactId: string;
173
+ artifact: NavigationArtifact;
174
+ /** The glob pattern that matched. */
175
+ matchedPattern: string;
176
+ }
177
+ /**
178
+ * Resolve a file path to its artifact(s) in the navigation index.
179
+ * Returns all matching artifacts (a file may belong to multiple artifacts).
180
+ */
181
+ declare function resolvePathToArtifacts(filePath: string, navigationIndex: Record<string, unknown>): ArtifactMatch[];
182
+ /**
183
+ * Check if a file path targets a protected artifact (generated or manual_edit: forbidden).
184
+ */
185
+ declare function isProtectedArtifact(match: ArtifactMatch): {
186
+ protected: boolean;
187
+ reason: string;
188
+ };
189
+ /**
190
+ * Get all artifact entries from a navigation index as a flat list.
191
+ */
192
+ declare function listArtifacts(navigationIndex: Record<string, unknown>): Array<{
193
+ id: string;
194
+ artifact: NavigationArtifact;
195
+ }>;
196
+
197
+ /**
198
+ * PreToolUse Hook Handler — artifact guardrail + DSL guardrail enforcement.
199
+ *
200
+ * Executed before tool use (Edit, Write, Bash, etc.). Checks:
201
+ * 1. Edit/Write tools: file path → artifact reverse lookup → deny if protected
202
+ * 2. Bash tool: apply DSL guardrail rules via GuardrailHooks
203
+ */
204
+
205
+ interface PreToolUseHandlerConfig {
206
+ /** Navigation index for artifact resolution. */
207
+ navigationIndex: Record<string, unknown>;
208
+ /** DSL guardrail rules for Bash command evaluation. */
209
+ guardrailRules?: GuardrailRuleData;
210
+ }
211
+ /**
212
+ * Create a PreToolUse hook handler.
213
+ */
214
+ declare function createPreToolUseHandler(config: PreToolUseHandlerConfig): (input: PreToolUseInput) => Promise<HookOutput>;
215
+
216
+ /**
217
+ * Workspace Router — route a file path to the owning workspace member.
218
+ *
219
+ * Pure path-manipulation module. No imports from navigation-context,
220
+ * agent-contracts, or any heavy dependency — safe for the lean hooks-lite
221
+ * entry point.
222
+ *
223
+ * Algorithm: longest-prefix match among member absolute root paths.
224
+ *
225
+ * C4 resolution: stripMemberPrefix converts a workspace-relative path
226
+ * (`aaac/packages/runtime/x.ts`) into a repo-relative path
227
+ * (`packages/runtime/x.ts`) so existing member DSL path_patterns work
228
+ * without modification.
229
+ */
230
+ interface WorkspaceMember {
231
+ /** Human-readable member name (e.g. `"aaac"`). */
232
+ name: string;
233
+ /** Absolute path to the member root directory. */
234
+ root: string;
235
+ }
236
+ /**
237
+ * Route a file path to the workspace member whose root is the longest
238
+ * matching prefix of that path.
239
+ *
240
+ * Generic over `T extends WorkspaceMember` so callers that pass a richer
241
+ * member type (e.g. `WorkspaceMemberPreToolUseConfig`) get back that type
242
+ * without a cast.
243
+ *
244
+ * @param filePath - Absolute or workspace-root-relative file path (as
245
+ * received from Claude Code's `tool_input.file_path`).
246
+ * @param members - Workspace members with **absolute** root paths.
247
+ * @param workspaceRoot - Absolute path to the workspace root directory.
248
+ * Used to resolve relative `filePath` values.
249
+ * @returns The owning member, or `null` when no member claims this path.
250
+ */
251
+ declare function routePathToMember<T extends WorkspaceMember>(filePath: string, members: T[], workspaceRoot: string): T | null;
252
+ /**
253
+ * Strip the member root prefix from `filePath` to obtain a repo-relative
254
+ * path that member DSL `path_patterns` can match against unchanged (C4).
255
+ *
256
+ * Example:
257
+ * filePath = "aaac/packages/runtime/x.ts" (workspace-relative)
258
+ * memberRoot = "/abs/workspace/aaac"
259
+ * workspaceRoot = "/abs/workspace"
260
+ * → returns "packages/runtime/x.ts"
261
+ *
262
+ * @param filePath - Absolute or workspace-root-relative path.
263
+ * @param memberRoot - Absolute path to the member root.
264
+ * @param workspaceRoot - Absolute path to the workspace root.
265
+ * @returns Repo-relative path (no leading slash/dot).
266
+ * Falls back to the original `filePath` when stripping is not possible.
267
+ */
268
+ declare function stripMemberPrefix(filePath: string, memberRoot: string, workspaceRoot: string): string;
269
+
270
+ /**
271
+ * Workspace PreToolUse Hook Handler — routes edits to the owning member
272
+ * and enforces that member's artifact guardrails.
273
+ *
274
+ * Hot-path module. Does NOT import navigation-context or agent-contracts —
275
+ * it only reads an already-built navigation index from the cache. Suitable
276
+ * for inclusion in the lean hooks-lite entry point.
277
+ *
278
+ * Flow (per PreToolUse invocation):
279
+ * 1. Extract file path from tool input.
280
+ * 2. Route to owning member via longest-prefix match (workspace-router).
281
+ * 3. Read member's navigation-index from cache (cache-store).
282
+ * 4. Strip member-root prefix → repo-relative path (C4 resolution).
283
+ * 5. Resolve path to artifacts; deny if protected.
284
+ */
285
+
286
+ interface WorkspaceMemberPreToolUseConfig extends WorkspaceMember {
287
+ /**
288
+ * Cache key for this member's navigation-index JSON.
289
+ * Format: `navigation-index.<name>` (e.g. `navigation-index.aaac`).
290
+ */
291
+ cacheKey: string;
292
+ }
293
+ interface WorkspacePreToolUseConfig {
294
+ /** Absolute path to the workspace root directory. */
295
+ workspaceRoot: string;
296
+ /** Absolute path to the shared `.claude/cache/` directory. */
297
+ cacheDir: string;
298
+ /** Workspace members to route edits to. */
299
+ members: WorkspaceMemberPreToolUseConfig[];
300
+ }
301
+ /**
302
+ * Create a workspace-aware PreToolUse hook handler.
303
+ *
304
+ * On each invocation the handler:
305
+ * - Skips non-edit tools (allow).
306
+ * - Routes the target path to the owning member by longest-prefix match.
307
+ * - Reads the member's cached navigation-index (allows if no cache yet).
308
+ * - Strips the member-root prefix so `resolvePathToArtifacts` receives the
309
+ * same repo-relative path the member DSL's `path_patterns` expect (C4).
310
+ * - Denies if any matched artifact is protected.
311
+ */
312
+ declare function createWorkspacePreToolUseHandler(config: WorkspacePreToolUseConfig): (input: PreToolUseInput) => Promise<HookOutput>;
313
+
314
+ export { type ArtifactMatch, type CacheEntry, type CacheStore, type CacheStoreOptions, type DegradeResult, type HookEventName, type HookInput, type HookOutput, type NavigationArtifact, type PermissionDecision, type PreToolUseHandlerConfig, type PreToolUseInput, type SessionStartInput, TimeoutError, type UserPromptSubmitInput, type WorkspaceMember, type WorkspaceMemberPreToolUseConfig, type WorkspacePreToolUseConfig, buildAllowResponse, buildContextResponse, buildDenyResponse, computeSourceHash, createCacheStore, createExclusiveLock, createPreToolUseHandler, createWorkspacePreToolUseHandler, emitHookOutput, isProtectedArtifact, listArtifacts, parseHookInput, readHookInput, resolvePathToArtifacts, routePathToMember, stripMemberPrefix, withDegrade, withTimeout };
@@ -0,0 +1,44 @@
1
+ import {
2
+ TimeoutError,
3
+ buildAllowResponse,
4
+ buildContextResponse,
5
+ buildDenyResponse,
6
+ computeSourceHash,
7
+ createCacheStore,
8
+ createExclusiveLock,
9
+ createPreToolUseHandler,
10
+ createWorkspacePreToolUseHandler,
11
+ emitHookOutput,
12
+ isProtectedArtifact,
13
+ listArtifacts,
14
+ parseHookInput,
15
+ readHookInput,
16
+ resolvePathToArtifacts,
17
+ routePathToMember,
18
+ stripMemberPrefix,
19
+ withDegrade,
20
+ withTimeout
21
+ } from "../../chunk-VMJPJ7B7.js";
22
+ import "../../chunk-EH5VFZYJ.js";
23
+ export {
24
+ TimeoutError,
25
+ buildAllowResponse,
26
+ buildContextResponse,
27
+ buildDenyResponse,
28
+ computeSourceHash,
29
+ createCacheStore,
30
+ createExclusiveLock,
31
+ createPreToolUseHandler,
32
+ createWorkspacePreToolUseHandler,
33
+ emitHookOutput,
34
+ isProtectedArtifact,
35
+ listArtifacts,
36
+ parseHookInput,
37
+ readHookInput,
38
+ resolvePathToArtifacts,
39
+ routePathToMember,
40
+ stripMemberPrefix,
41
+ withDegrade,
42
+ withTimeout
43
+ };
44
+ //# sourceMappingURL=hooks-lite.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
@@ -1,199 +1,7 @@
1
+ import { SessionStartInput, HookOutput, UserPromptSubmitInput } from './hooks-lite.js';
2
+ export { ArtifactMatch, CacheEntry, CacheStore, CacheStoreOptions, DegradeResult, HookEventName, HookInput, NavigationArtifact, PermissionDecision, PreToolUseHandlerConfig, PreToolUseInput, TimeoutError, WorkspaceMember, WorkspaceMemberPreToolUseConfig, WorkspacePreToolUseConfig, buildAllowResponse, buildContextResponse, buildDenyResponse, computeSourceHash, createCacheStore, createExclusiveLock, createPreToolUseHandler, createWorkspacePreToolUseHandler, emitHookOutput, isProtectedArtifact, listArtifacts, parseHookInput, readHookInput, resolvePathToArtifacts, routePathToMember, stripMemberPrefix, withDegrade, withTimeout } from './hooks-lite.js';
1
3
  import { N as NavigationContextOptions } from '../../navigation-context-BE1KHJ_8.js';
2
- import { a as GuardrailRuleData } from '../../guardrail-hooks-slK-z0Dz.js';
3
-
4
- /**
5
- * Claude Code Hook Protocol — parse stdin JSON input and emit hook response JSON.
6
- *
7
- * Implements the protocol defined at https://code.claude.com/docs/en/hooks
8
- * for SessionStart, UserPromptSubmit, and PreToolUse hook events.
9
- */
10
- type HookEventName = "SessionStart" | "UserPromptSubmit" | "PreToolUse";
11
- interface SessionStartInput {
12
- hookEventName: "SessionStart";
13
- session_id?: string;
14
- type?: "new" | "resume" | "clear" | "compact";
15
- }
16
- interface UserPromptSubmitInput {
17
- hookEventName: "UserPromptSubmit";
18
- session_id?: string;
19
- prompt?: string;
20
- }
21
- interface PreToolUseInput {
22
- hookEventName: "PreToolUse";
23
- session_id?: string;
24
- tool_name?: string;
25
- tool_input?: {
26
- file_path?: string;
27
- path?: string;
28
- command?: string;
29
- content?: string;
30
- [key: string]: unknown;
31
- };
32
- }
33
- type HookInput = SessionStartInput | UserPromptSubmitInput | PreToolUseInput;
34
- type PermissionDecision = "allow" | "deny" | "ask";
35
- interface HookOutput {
36
- /** Hook-specific output envelope. */
37
- hookSpecificOutput?: {
38
- hookEventName: HookEventName;
39
- /** Additional context injected into the session. */
40
- additionalContext?: string;
41
- /** Permission decision for PreToolUse hooks. */
42
- permissionDecision?: PermissionDecision;
43
- /** Reason for the permission decision. */
44
- permissionDecisionReason?: string;
45
- };
46
- }
47
- /**
48
- * Parse hook input from a raw JSON string (typically from stdin).
49
- * Throws on invalid JSON but not on missing fields — callers handle defaults.
50
- */
51
- declare function parseHookInput(raw: string): HookInput;
52
- /**
53
- * Read all of stdin and parse as hook input JSON.
54
- */
55
- declare function readHookInput(): Promise<HookInput>;
56
- /**
57
- * Emit a hook response as JSON to stdout.
58
- */
59
- declare function emitHookOutput(output: HookOutput): void;
60
- /**
61
- * Build a response that injects additional context into the session.
62
- */
63
- declare function buildContextResponse(eventName: HookEventName, additionalContext: string): HookOutput;
64
- /**
65
- * Build a deny response for PreToolUse hooks.
66
- */
67
- declare function buildDenyResponse(reason: string): HookOutput;
68
- /**
69
- * Build an allow response (empty output = allow by default).
70
- */
71
- declare function buildAllowResponse(): HookOutput;
72
-
73
- /**
74
- * Cache Store — read/write `.claude/cache/` directory.
75
- *
76
- * Stores navigation-index.json and metadata for graph cache invalidation.
77
- * Uses atomic write (write-to-temp + rename) for concurrent-access safety.
78
- */
79
- interface CacheEntry<T = unknown> {
80
- data: T;
81
- /** ISO timestamp of when the cache was written. */
82
- writtenAt: string;
83
- /** Hash of source inputs used for invalidation. */
84
- sourceHash: string;
85
- }
86
- interface CacheStoreOptions {
87
- /** Absolute path to the `.claude/cache/` directory. */
88
- cacheDir: string;
89
- }
90
- interface CacheStore {
91
- read<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
92
- write<T = unknown>(key: string, data: T, sourceHash: string): Promise<void>;
93
- /**
94
- * Check if a cache entry is fresh by comparing its sourceHash.
95
- * Returns the cached data if fresh, null if stale or missing.
96
- */
97
- readIfFresh<T = unknown>(key: string, currentHash: string): Promise<T | null>;
98
- /** Get the mtime of a file (for invalidation checks). */
99
- getFileMtime(filePath: string): Promise<number | null>;
100
- }
101
- declare function createCacheStore(options: CacheStoreOptions): CacheStore;
102
- /**
103
- * Compute a simple hash string from an array of file mtimes and content strings.
104
- * Not cryptographic — used only for cache invalidation.
105
- */
106
- declare function computeSourceHash(inputs: Array<string | number>): string;
107
-
108
- /**
109
- * Latency utilities — timeout wrapper, graph build exclusion, degrade policy.
110
- *
111
- * Mirrors the Promise-sharing pattern from analyzer-bridge.ts for concurrent
112
- * graph build exclusion.
113
- */
114
- declare class TimeoutError extends Error {
115
- constructor(ms: number);
116
- }
117
- /**
118
- * Race a promise against a timeout. Resolves with the promise result or
119
- * rejects with TimeoutError.
120
- */
121
- declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
122
- /**
123
- * Creates an exclusive async lock that ensures only one invocation runs at a
124
- * time. Subsequent callers await the same Promise (analyzer-bridge pattern).
125
- */
126
- declare function createExclusiveLock<T>(): {
127
- run: (fn: () => Promise<T>) => Promise<T>;
128
- };
129
- interface DegradeResult<T> {
130
- value: T;
131
- degraded: boolean;
132
- reason?: string;
133
- }
134
- /**
135
- * Attempt an operation with timeout; if it fails or times out, return the
136
- * fallback value with `degraded: true`.
137
- */
138
- declare function withDegrade<T>(operation: () => Promise<T>, fallback: T, timeoutMs: number): Promise<DegradeResult<T>>;
139
-
140
- /**
141
- * Artifact Resolver — reverse-lookup path to artifact_id using navigation-index.
142
- *
143
- * Uses glob matching from guardrail-hooks.ts to match file paths against
144
- * artifact path_patterns defined in the navigation index.
145
- */
146
- /** Minimal shape of a navigation-index artifact node. */
147
- interface NavigationArtifact {
148
- properties?: {
149
- type?: string;
150
- authority?: string;
151
- manual_edit?: string;
152
- [key: string]: unknown;
153
- };
154
- files?: {
155
- path_patterns?: string[];
156
- [key: string]: unknown;
157
- };
158
- agents?: {
159
- owners?: string[];
160
- editors?: string[];
161
- [key: string]: unknown;
162
- };
163
- routes?: {
164
- regenerate?: string;
165
- [key: string]: unknown;
166
- };
167
- relations?: {
168
- derived_artifacts?: string[];
169
- [key: string]: unknown;
170
- };
171
- }
172
- interface ArtifactMatch {
173
- artifactId: string;
174
- artifact: NavigationArtifact;
175
- /** The glob pattern that matched. */
176
- matchedPattern: string;
177
- }
178
- /**
179
- * Resolve a file path to its artifact(s) in the navigation index.
180
- * Returns all matching artifacts (a file may belong to multiple artifacts).
181
- */
182
- declare function resolvePathToArtifacts(filePath: string, navigationIndex: Record<string, unknown>): ArtifactMatch[];
183
- /**
184
- * Check if a file path targets a protected artifact (generated or manual_edit: forbidden).
185
- */
186
- declare function isProtectedArtifact(match: ArtifactMatch): {
187
- protected: boolean;
188
- reason: string;
189
- };
190
- /**
191
- * Get all artifact entries from a navigation index as a flat list.
192
- */
193
- declare function listArtifacts(navigationIndex: Record<string, unknown>): Array<{
194
- id: string;
195
- artifact: NavigationArtifact;
196
- }>;
4
+ import '../../guardrail-hooks-slK-z0Dz.js';
197
5
 
198
6
  /**
199
7
  * Ensure Navigation Index — cache warm / invalidation.
@@ -212,6 +20,15 @@ interface EnsureNavigationIndexOptions {
212
20
  sourceFiles: string[];
213
21
  /** Options for buildNavigationContext() when cache is stale. */
214
22
  navigationOptions: NavigationContextOptions;
23
+ /**
24
+ * Cache key for the stored JSON file (default: `"navigation-index"`).
25
+ *
26
+ * In workspace mode each member uses its own key, e.g.
27
+ * `"navigation-index.aaac"`, so their caches remain isolated.
28
+ * Single-component callers omit this field and the default preserves
29
+ * byte-identical behaviour with previous versions.
30
+ */
31
+ cacheKey?: string;
215
32
  }
216
33
  interface NavigationIndexResult {
217
34
  navigationIndex: Record<string, unknown>;
@@ -221,6 +38,10 @@ interface NavigationIndexResult {
221
38
  /**
222
39
  * Ensure the navigation index is available and fresh. Returns the index
223
40
  * data, building + caching if necessary.
41
+ *
42
+ * In workspace mode, pass a unique `cacheKey` per member (e.g.
43
+ * `"navigation-index.aaac"`) so each member's index is stored and
44
+ * invalidated independently.
224
45
  */
225
46
  declare function ensureNavigationIndex(options: EnsureNavigationIndexOptions): Promise<NavigationIndexResult>;
226
47
 
@@ -312,22 +133,45 @@ interface UserPromptSubmitHandlerConfig {
312
133
  declare function createUserPromptSubmitHandler(config: UserPromptSubmitHandlerConfig): (input: UserPromptSubmitInput) => Promise<HookOutput>;
313
134
 
314
135
  /**
315
- * PreToolUse Hook Handler — artifact guardrail + DSL guardrail enforcement.
136
+ * Workspace SessionStart Hook Handler — per-member navigation-index warm-up.
137
+ *
138
+ * Builds (or validates) a cached navigation-index for each declared workspace
139
+ * member in parallel, then returns a combined summary as `additionalContext`.
316
140
  *
317
- * Executed before tool use (Edit, Write, Bash, etc.). Checks:
318
- * 1. Edit/Write tools: file path → artifact reverse lookup → deny if protected
319
- * 2. Bash tool: apply DSL guardrail rules via GuardrailHooks
141
+ * This module is in the **heavy** path (imports ensureNavigationIndex →
142
+ * navigation-context → agent-contracts) and is therefore NOT included in the
143
+ * lean hooks-lite entry point. SessionStart fires only once per session, so
144
+ * the higher import cost is acceptable.
320
145
  */
321
146
 
322
- interface PreToolUseHandlerConfig {
323
- /** Navigation index for artifact resolution. */
324
- navigationIndex: Record<string, unknown>;
325
- /** DSL guardrail rules for Bash command evaluation. */
326
- guardrailRules?: GuardrailRuleData;
147
+ interface WorkspaceMemberSessionConfig {
148
+ /** Human-readable member name (e.g. `"aaac"`). */
149
+ name: string;
150
+ /** Absolute path to member root directory. */
151
+ root: string;
152
+ /**
153
+ * Unique cache key for this member's navigation-index JSON.
154
+ * Format: `navigation-index.<name>`.
155
+ */
156
+ cacheKey: string;
157
+ /** Source files for mtime-based cache invalidation. */
158
+ sourceFiles: string[];
159
+ /** Options passed to `buildNavigationContext()` on cache miss. */
160
+ navigationOptions: EnsureNavigationIndexOptions["navigationOptions"];
161
+ }
162
+ interface WorkspaceSessionStartConfig {
163
+ /** Absolute path to the shared `.claude/cache/` directory. */
164
+ cacheDir: string;
165
+ /** Workspace members to build/validate indices for. */
166
+ members: WorkspaceMemberSessionConfig[];
327
167
  }
328
168
  /**
329
- * Create a PreToolUse hook handler.
169
+ * Create a workspace-aware SessionStart hook handler.
170
+ *
171
+ * All member navigation-indices are built in **parallel** (each key has its
172
+ * own exclusive lock so concurrent calls for the same member deduplicate
173
+ * rather than queue behind other members).
330
174
  */
331
- declare function createPreToolUseHandler(config: PreToolUseHandlerConfig): (input: PreToolUseInput) => Promise<HookOutput>;
175
+ declare function createWorkspaceSessionStartHandler(config: WorkspaceSessionStartConfig): (_input: SessionStartInput) => Promise<HookOutput>;
332
176
 
333
- export { type ArtifactMatch, type CacheEntry, type CacheStore, type CacheStoreOptions, type DegradeResult, type EnsureNavigationIndexOptions, type FileSuggestionCandidate, type FileSuggestionOptions, type HookEventName, type HookInput, type HookOutput, type NavigationArtifact, type NavigationIndexResult, type PermissionDecision, type PreToolUseHandlerConfig, type PreToolUseInput, type SessionStartHandlerConfig, type SessionStartInput, TimeoutError, type UserPromptSubmitHandlerConfig, type UserPromptSubmitInput, buildAllowResponse, buildContextResponse, buildDenyResponse, computeSourceHash, createCacheStore, createExclusiveLock, createPreToolUseHandler, createSessionStartHandler, createUserPromptSubmitHandler, emitHookOutput, ensureNavigationIndex, formatNdjson, generateCandidates, handleFileSuggestion, isProtectedArtifact, listArtifacts, parseHookInput, readHookInput, resolvePathToArtifacts, withDegrade, withTimeout };
177
+ export { type EnsureNavigationIndexOptions, type FileSuggestionCandidate, type FileSuggestionOptions, HookOutput, type NavigationIndexResult, type SessionStartHandlerConfig, SessionStartInput, type UserPromptSubmitHandlerConfig, UserPromptSubmitInput, type WorkspaceMemberSessionConfig, type WorkspaceSessionStartConfig, createSessionStartHandler, createUserPromptSubmitHandler, createWorkspaceSessionStartHandler, ensureNavigationIndex, formatNdjson, generateCandidates, handleFileSuggestion };