@aaac/runtime 0.1.53 → 0.1.54

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 (36) hide show
  1. package/dist/adapters/adk-sdk.d.ts +1 -1
  2. package/dist/adapters/adk-sdk.js +1 -1
  3. package/dist/adapters/claude-agent-sdk.d.ts +1 -1
  4. package/dist/adapters/mock.d.ts +1 -1
  5. package/dist/adapters/openai-agents-sdk.d.ts +1 -1
  6. package/dist/{chunk-YZQRSVDZ.js → chunk-3H3PVPPF.js} +198 -4
  7. package/dist/chunk-3H3PVPPF.js.map +1 -0
  8. package/dist/chunk-LDCQZPDG.js +11 -0
  9. package/dist/chunk-LDCQZPDG.js.map +1 -0
  10. package/dist/{chunk-M3GJAHLX.js → chunk-N4KNGDYY.js} +343 -28
  11. package/dist/chunk-N4KNGDYY.js.map +1 -0
  12. package/dist/{chunk-EH5VFZYJ.js → chunk-NMX4C6LC.js} +6 -2
  13. package/dist/chunk-NMX4C6LC.js.map +1 -0
  14. package/dist/{chunk-KNYJV2Q6.js → chunk-QVH5KKBR.js} +5 -9
  15. package/dist/chunk-QVH5KKBR.js.map +1 -0
  16. package/dist/claude-bundles/full.js +223 -217
  17. package/dist/claude-bundles/lean.js +5 -5
  18. package/dist/generator/index.d.ts +2 -286
  19. package/dist/generator/index.js +1 -1
  20. package/dist/index-LqEvaRk-.d.ts +299 -0
  21. package/dist/index.d.ts +29 -17
  22. package/dist/index.js +75 -414
  23. package/dist/index.js.map +1 -1
  24. package/dist/lib/claude-native/hooks-lite.d.ts +18 -325
  25. package/dist/lib/claude-native/hooks-lite.js +8 -2
  26. package/dist/lib/claude-native/index.d.ts +153 -20
  27. package/dist/lib/claude-native/index.js +162 -37
  28. package/dist/lib/claude-native/index.js.map +1 -1
  29. package/dist/{navigation-context-xrReMkTn.d.ts → navigation-context-D_E1NIUf.d.ts} +11 -3
  30. package/dist/{task-runner-Sez_CXcD.d.ts → task-runner-CLc8iTzy.d.ts} +5 -8
  31. package/dist/workspace-pre-tool-use-C6nidc0q.d.ts +333 -0
  32. package/package.json +1 -1
  33. package/dist/chunk-EH5VFZYJ.js.map +0 -1
  34. package/dist/chunk-KNYJV2Q6.js.map +0 -1
  35. package/dist/chunk-M3GJAHLX.js.map +0 -1
  36. package/dist/chunk-YZQRSVDZ.js.map +0 -1
@@ -1,333 +1,26 @@
1
- import { a as GuardrailRuleData } from '../../guardrail-hooks-slK-z0Dz.js';
1
+ export { A as ArtifactMatch, C as CacheEntry, a as CacheStore, b as CacheStoreOptions, D as DegradeResult, H as HookEventName, c as HookInput, d as HookOutput, N as NavigationArtifact, P as PermissionDecision, e as PreToolUseHandlerConfig, f as PreToolUseInput, S as SessionStartInput, T as TimeoutError, U as UserPromptSubmitInput, W as WorkspaceMember, g as WorkspaceMemberPreToolUseConfig, h as WorkspacePreToolUseConfig, i as buildAllowResponse, j as buildContextResponse, k as buildDenyResponse, l as computeSourceHash, m as createCacheStore, n as createExclusiveLock, o as createPreToolUseHandler, p as createWorkspacePreToolUseHandler, q as emitHookOutput, r as isProtectedArtifact, s as listArtifacts, t as parseHookInput, u as readHookInput, v as resolvePathToArtifacts, w as routePathToMember, x as stripMemberPrefix, y as withDegrade, z as withTimeout } from '../../workspace-pre-tool-use-C6nidc0q.js';
2
+ import '../../guardrail-hooks-slK-z0Dz.js';
2
3
 
3
4
  /**
4
- * Claude Code Hook Protocol — parse stdin JSON input and emit hook response JSON.
5
+ * Cache-key helpers shared between the heavy navigation-index warm path
6
+ * (`ensure-navigation-index.ts`) and the lean PreToolUse hot path
7
+ * (`workspace-pre-tool-use.ts`).
5
8
  *
6
- * Implements the protocol defined at https://code.claude.com/docs/en/hooks
7
- * for SessionStart, UserPromptSubmit, and PreToolUse hook events.
9
+ * This module is intentionally dependency-free (no `navigation-context` /
10
+ * `agent-contracts` imports) so it is safe to include in the lean
11
+ * `hooks-lite` entry point without pulling the heavy DSL loader.
8
12
  */
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
13
  /**
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
- * Cache key for this member's DSL guardrail rules (#238 / C5).
294
- *
295
- * Defaults to `guardrailCacheKey(cacheKey)` (i.e. `<cacheKey>.guardrails`)
296
- * when omitted, matching what `ensureNavigationIndex` persists during the
297
- * SessionStart warm-up. Provided explicitly only for tests / custom layouts.
298
- */
299
- guardrailCacheKey?: string;
300
- }
301
- interface WorkspacePreToolUseConfig {
302
- /** Absolute path to the workspace root directory. */
303
- workspaceRoot: string;
304
- /** Absolute path to the shared `.claude/cache/` directory. */
305
- cacheDir: string;
306
- /** Workspace members to route edits to. */
307
- members: WorkspaceMemberPreToolUseConfig[];
308
- }
309
- /**
310
- * Create a workspace-aware PreToolUse hook handler.
311
- *
312
- * On each invocation the handler:
313
- * - Edit/Write tools:
314
- * - Routes the target path to the owning member by longest-prefix match.
315
- * - Reads the member's cached navigation-index (allows if no cache yet).
316
- * - Strips the member-root prefix so `resolvePathToArtifacts` receives the
317
- * same repo-relative path the member DSL's `path_patterns` expect (C4).
318
- * - Denies if any matched artifact is protected (Phase 1).
319
- * - Bash tools (#238 / C5, Phase 3):
320
- * - Routes the command to the owning member via a path token in the command
321
- * (longest-prefix match); when no member path is present, evaluates the
322
- * command against every member's rules so safety guardrails are never
323
- * silently skipped.
324
- * - Loads that member's DSL guardrail rules from the companion cache entry
325
- * and denies blocking command violations.
14
+ * Cache-key suffix under which a member's DSL guardrail rules are persisted
15
+ * alongside its navigation-index (#238 / C5).
326
16
  *
327
- * Artifact protection (Phase 1) and Bash guardrails (Phase 3) are independent
328
- * and coexist: a member with only artifact rules keeps working unchanged, and
329
- * a member with only guardrail rules still enforces Bash safety.
17
+ * The navigation-index cache stays byte-identical to previous versions; the
18
+ * guardrail rules live in a companion entry (e.g.
19
+ * `navigation-index.aaac.guardrails.json`) so the lean PreToolUse hook can
20
+ * read them without importing the heavy `agent-contracts` DSL loader.
330
21
  */
331
- declare function createWorkspacePreToolUseHandler(config: WorkspacePreToolUseConfig): (input: PreToolUseInput) => Promise<HookOutput>;
22
+ declare const GUARDRAIL_CACHE_SUFFIX = ".guardrails";
23
+ /** Companion cache key for a navigation-index cache key's guardrail rules. */
24
+ declare function guardrailCacheKey(navigationCacheKey: string): string;
332
25
 
333
- 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 };
26
+ export { GUARDRAIL_CACHE_SUFFIX, guardrailCacheKey };
@@ -18,10 +18,15 @@ import {
18
18
  stripMemberPrefix,
19
19
  withDegrade,
20
20
  withTimeout
21
- } from "../../chunk-KNYJV2Q6.js";
22
- import "../../chunk-EH5VFZYJ.js";
21
+ } from "../../chunk-QVH5KKBR.js";
22
+ import {
23
+ GUARDRAIL_CACHE_SUFFIX,
24
+ guardrailCacheKey
25
+ } from "../../chunk-LDCQZPDG.js";
26
+ import "../../chunk-NMX4C6LC.js";
23
27
  import "../../chunk-BJ7B4R26.js";
24
28
  export {
29
+ GUARDRAIL_CACHE_SUFFIX,
25
30
  TimeoutError,
26
31
  buildAllowResponse,
27
32
  buildContextResponse,
@@ -32,6 +37,7 @@ export {
32
37
  createPreToolUseHandler,
33
38
  createWorkspacePreToolUseHandler,
34
39
  emitHookOutput,
40
+ guardrailCacheKey,
35
41
  isProtectedArtifact,
36
42
  listArtifacts,
37
43
  parseHookInput,
@@ -1,8 +1,61 @@
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';
3
- import { N as NavigationContextOptions } from '../../navigation-context-xrReMkTn.js';
1
+ import { S as SessionStartInput, d as HookOutput, U as UserPromptSubmitInput } from '../../workspace-pre-tool-use-C6nidc0q.js';
2
+ export { A as ArtifactMatch, C as CacheEntry, a as CacheStore, b as CacheStoreOptions, D as DegradeResult, H as HookEventName, c as HookInput, N as NavigationArtifact, P as PermissionDecision, e as PreToolUseHandlerConfig, f as PreToolUseInput, T as TimeoutError, W as WorkspaceMember, g as WorkspaceMemberPreToolUseConfig, h as WorkspacePreToolUseConfig, i as buildAllowResponse, j as buildContextResponse, k as buildDenyResponse, l as computeSourceHash, m as createCacheStore, n as createExclusiveLock, o as createPreToolUseHandler, p as createWorkspacePreToolUseHandler, q as emitHookOutput, r as isProtectedArtifact, s as listArtifacts, t as parseHookInput, u as readHookInput, v as resolvePathToArtifacts, w as routePathToMember, x as stripMemberPrefix, y as withDegrade, z as withTimeout } from '../../workspace-pre-tool-use-C6nidc0q.js';
3
+ import { N as NavigationContextOptions } from '../../navigation-context-D_E1NIUf.js';
4
4
  import '../../guardrail-hooks-slK-z0Dz.js';
5
5
 
6
+ /**
7
+ * Navigation sources — resolve the project manifest into the inputs the
8
+ * navigation-index hooks need (which DSL to overlay, which artifact registry to
9
+ * bind, which files invalidate the cache).
10
+ *
11
+ * The generated `.claude/bin/*` nav hooks bake only what cannot be read from
12
+ * disk at hook time: the component's bundled `/$embedded/` DSL. Everything the
13
+ * project manifest declares (`agents:`, `artifacts:`) is resolved HERE, at hook
14
+ * runtime, through the same `loadProjectConfig` loader the CLI uses — so a
15
+ * manifest edit takes effect without re-running `claude sync`, and the hooks
16
+ * cannot drift from the CLI's view of the project
17
+ * (docs/proposal/workspace-subproject-guardrail.md §3.2).
18
+ */
19
+
20
+ interface ResolveNavigationSourcesOptions {
21
+ /**
22
+ * Root of the project whose navigation-index is being built: the directory
23
+ * that owns `project.yaml` (in workspace mode, the member root).
24
+ */
25
+ projectRoot: string;
26
+ /**
27
+ * The component's bundled `/$embedded/` DSL, baked into the hook bin by
28
+ * `claude sync`. Undefined for `aaac generate` output, where the bin resolves
29
+ * `dslPath` directly.
30
+ */
31
+ embeddedDsl?: Record<string, unknown>;
32
+ /**
33
+ * Project-root-relative agents DSL path used ONLY when `projectRoot` has no
34
+ * `project.yaml` (a bare component checkout). With a manifest present the
35
+ * manifest's `agents:` wins.
36
+ */
37
+ dslPath: string;
38
+ }
39
+ interface NavigationSources {
40
+ navigationOptions: NavigationContextOptions;
41
+ /** Files whose mtime invalidates the navigation-index cache. */
42
+ sourceFiles: string[];
43
+ }
44
+ /**
45
+ * Resolve the navigation-index inputs for one project root.
46
+ *
47
+ * With a `project.yaml` present, the manifest is authoritative:
48
+ * - `agents:` → the DSL overlaid on `embeddedDsl` (omitted = embedded as-is),
49
+ * - `artifacts:` → the artifact-contracts registry bound onto the DSL
50
+ * artifacts, so path_patterns / authority / manual_edit reflect the project
51
+ * rather than the component's built-in defaults,
52
+ * - `bindings.guardrail` + `active_guardrail_policy` → the guardrail checks the
53
+ * PreToolUse hook enforces, resolved by the same code as the CLI (#267).
54
+ * All resolved files feed `sourceFiles`, so editing any of them rebuilds the
55
+ * index on the next hook invocation.
56
+ */
57
+ declare function resolveNavigationSources(options: ResolveNavigationSourcesOptions): Promise<NavigationSources>;
58
+
6
59
  /**
7
60
  * Ensure Navigation Index — cache warm / invalidation.
8
61
  *
@@ -34,7 +87,26 @@ interface NavigationIndexResult {
34
87
  navigationIndex: Record<string, unknown>;
35
88
  /** Whether the result was loaded from cache (true) or freshly built (false). */
36
89
  fromCache: boolean;
90
+ /**
91
+ * Diagnostics from the build that produced this index — artifact-binding
92
+ * findings (`unbound-artifact` / `orphan-binding` / `type-mismatch`) and
93
+ * schema validation issues. Present only on a fresh build: they describe the
94
+ * DSL/registry the index was built from, so a caller that hit the cache has
95
+ * already been told once. Callers MUST surface them (a dropped
96
+ * `orphan-binding` is exactly how a project's artifact registry silently
97
+ * fails to reach the hooks — #260).
98
+ */
99
+ diagnostics?: Array<{
100
+ path: string;
101
+ message: string;
102
+ severity: string;
103
+ }>;
37
104
  }
105
+ /**
106
+ * Render build diagnostics as hook context lines. Returns undefined when there
107
+ * is nothing to report, so callers can skip the section entirely.
108
+ */
109
+ declare function renderNavigationDiagnostics(diagnostics: NavigationIndexResult["diagnostics"], label?: string): string | undefined;
38
110
  /**
39
111
  * Ensure the navigation index is available and fresh. Returns the index
40
112
  * data, building + caching if necessary.
@@ -69,6 +141,13 @@ interface FileSuggestionOptions {
69
141
  navigationIndex: Record<string, unknown>;
70
142
  /** Maximum number of candidates to return. */
71
143
  maxCandidates?: number;
144
+ /**
145
+ * Prefix prepended to every emitted path (#266). Artifact `path_patterns` are
146
+ * project-root relative, so in a workspace — where Claude Code's cwd is the
147
+ * workspace root — a member's candidates must be re-rooted under the member
148
+ * directory. The mirror image of `stripMemberPrefix` on the PreToolUse side.
149
+ */
150
+ pathPrefix?: string;
72
151
  }
73
152
  /**
74
153
  * Generate file suggestion candidates from the navigation index.
@@ -84,6 +163,24 @@ declare function formatNdjson(candidates: FileSuggestionCandidate[]): string;
84
163
  * Reads prefix from stdin, returns NDJSON candidates to stdout.
85
164
  */
86
165
  declare function handleFileSuggestion(navigationIndex: Record<string, unknown>, stdinData: string): Promise<string>;
166
+ /** One workspace member's cached index, as the file-suggestion bin knows it. */
167
+ interface WorkspaceFileSuggestionMember {
168
+ /** Member name (for diagnostics only). */
169
+ name: string;
170
+ /** Workspace-relative member path — prepended to every candidate path. */
171
+ memberPath: string;
172
+ /** Cache key of this member's navigation-index. */
173
+ cacheKey: string;
174
+ }
175
+ /**
176
+ * Workspace variant (#266): merge candidates from every member's own index.
177
+ *
178
+ * The single-component handler reads the lone `navigation-index` cache entry,
179
+ * which workspace mode never writes (each member has its own key) — so `@`
180
+ * completion returned nothing at all. Members whose index has not been built yet
181
+ * are skipped rather than failing the hook: SessionStart warms them.
182
+ */
183
+ declare function handleWorkspaceFileSuggestion(cacheDir: string, members: WorkspaceFileSuggestionMember[], stdinData: string, maxCandidates?: number): Promise<string>;
87
184
 
88
185
  /**
89
186
  * SessionStart Hook Handler — cache warm + navigation-index summary injection.
@@ -118,8 +215,6 @@ declare function createSessionStartHandler(config: SessionStartHandlerConfig): (
118
215
  */
119
216
 
120
217
  interface UserPromptSubmitHandlerConfig {
121
- /** Absolute path to the project root. */
122
- projectRoot: string;
123
218
  /** Absolute path to .claude/cache/ directory. */
124
219
  cacheDir: string;
125
220
  /** Source files for cache invalidation. */
@@ -133,18 +228,15 @@ interface UserPromptSubmitHandlerConfig {
133
228
  declare function createUserPromptSubmitHandler(config: UserPromptSubmitHandlerConfig): (input: UserPromptSubmitInput) => Promise<HookOutput>;
134
229
 
135
230
  /**
136
- * Workspace SessionStart Hook Handler — per-member navigation-index warm-up.
231
+ * Workspace member navigation — the shared warm-up + rendering used by every
232
+ * workspace hook that needs per-member navigation indices (SessionStart and
233
+ * UserPromptSubmit). One member = one navigation-index cache entry.
137
234
  *
138
- * Builds (or validates) a cached navigation-index for each declared workspace
139
- * member in parallel, then returns a combined summary as `additionalContext`.
140
- *
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.
235
+ * Heavy path (pulls ensureNavigationIndex → navigation-context → agent-contracts);
236
+ * never import from the lean `hooks-lite` entry.
145
237
  */
146
238
 
147
- interface WorkspaceMemberSessionConfig {
239
+ interface WorkspaceMemberNavConfig {
148
240
  /** Human-readable member name (e.g. `"aaac"`). */
149
241
  name: string;
150
242
  /** Absolute path to member root directory. */
@@ -159,19 +251,60 @@ interface WorkspaceMemberSessionConfig {
159
251
  /** Options passed to `buildNavigationContext()` on cache miss. */
160
252
  navigationOptions: EnsureNavigationIndexOptions["navigationOptions"];
161
253
  }
254
+ interface WorkspaceMemberNavResult {
255
+ member: WorkspaceMemberNavConfig;
256
+ result: NavigationIndexResult;
257
+ }
258
+ /**
259
+ * Build (or validate) every member's navigation-index in **parallel** — each
260
+ * cache key has its own exclusive lock, so concurrent calls for the same member
261
+ * deduplicate rather than queue behind other members.
262
+ */
263
+ declare function ensureMemberIndices(cacheDir: string, members: WorkspaceMemberNavConfig[]): Promise<WorkspaceMemberNavResult[]>;
264
+ /** One member's context section: index summary + freshness + build diagnostics. */
265
+ declare function renderMemberSection({ member, result }: WorkspaceMemberNavResult): string;
266
+
267
+ /**
268
+ * Workspace SessionStart Hook Handler — per-member navigation-index warm-up.
269
+ *
270
+ * Builds (or validates) a cached navigation-index for each declared workspace
271
+ * member in parallel, then returns a combined summary as `additionalContext`.
272
+ *
273
+ * This module is in the **heavy** path (imports ensureNavigationIndex →
274
+ * navigation-context → agent-contracts) and is therefore NOT included in the
275
+ * lean hooks-lite entry point. SessionStart fires only once per session, so
276
+ * the higher import cost is acceptable.
277
+ */
278
+
162
279
  interface WorkspaceSessionStartConfig {
163
280
  /** Absolute path to the shared `.claude/cache/` directory. */
164
281
  cacheDir: string;
165
282
  /** Workspace members to build/validate indices for. */
166
- members: WorkspaceMemberSessionConfig[];
283
+ members: WorkspaceMemberNavConfig[];
167
284
  }
168
285
  /**
169
286
  * 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).
174
287
  */
175
288
  declare function createWorkspaceSessionStartHandler(config: WorkspaceSessionStartConfig): (_input: SessionStartInput) => Promise<HookOutput>;
176
289
 
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 };
290
+ /**
291
+ * Workspace UserPromptSubmit Hook Handler — per-member navigation context.
292
+ *
293
+ * The workspace hook set previously emitted the SINGLE-component ContextPack bin
294
+ * at the workspace root (#263): SessionStart and PreToolUse were member-aware
295
+ * while prompt submission saw only the root manifest, so no member's artifacts
296
+ * reached the prompt. This mirrors the SessionStart handler — one index per
297
+ * member — and adds prompt-keyword candidates per member.
298
+ *
299
+ * Heavy path (ensureNavigationIndex → agent-contracts); not part of hooks-lite.
300
+ */
301
+
302
+ interface WorkspaceUserPromptSubmitConfig {
303
+ /** Absolute path to the shared `.claude/cache/` directory. */
304
+ cacheDir: string;
305
+ /** Workspace members whose indices feed the prompt context. */
306
+ members: WorkspaceMemberNavConfig[];
307
+ }
308
+ declare function createWorkspaceUserPromptSubmitHandler(config: WorkspaceUserPromptSubmitConfig): (input: UserPromptSubmitInput) => Promise<HookOutput>;
309
+
310
+ export { type EnsureNavigationIndexOptions, type FileSuggestionCandidate, type FileSuggestionOptions, HookOutput, type NavigationIndexResult, type NavigationSources, type ResolveNavigationSourcesOptions, type SessionStartHandlerConfig, SessionStartInput, type UserPromptSubmitHandlerConfig, UserPromptSubmitInput, type WorkspaceFileSuggestionMember, type WorkspaceMemberNavConfig, type WorkspaceMemberNavResult, type WorkspaceSessionStartConfig, type WorkspaceUserPromptSubmitConfig, createSessionStartHandler, createUserPromptSubmitHandler, createWorkspaceSessionStartHandler, createWorkspaceUserPromptSubmitHandler, ensureMemberIndices, ensureNavigationIndex, formatNdjson, generateCandidates, handleFileSuggestion, handleWorkspaceFileSuggestion, renderMemberSection, renderNavigationDiagnostics, resolveNavigationSources };