@cleocode/core 2026.3.74 → 2026.4.0

package/dist/engine-result.d.ts

@@ -8,7 +8,7 @@
  * @task T5715
  * @epic T5701
  */
-import type { LAFSPage } from '@cleocode/lafs-protocol';
+import type { LAFSPage } from '@cleocode/lafs';
 /**
  * Canonical EngineResult type used by all engines and core engine-compat modules.
  */

package/dist/engine-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-result.d.ts","sourceRoot":"","sources":["../src/engine-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC3D,CAAC;CACH"}
+{"version":3,"file":"engine-result.d.ts","sourceRoot":"","sources":["../src/engine-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC3D,CAAC;CACH"}

package/dist/error-catalog.d.ts

@@ -8,7 +8,7 @@
  *
  * @task T5240
  */
-import type { LAFSErrorCategory } from '@cleocode/lafs-protocol';
+import type { LAFSErrorCategory } from '@cleocode/lafs';
 /**
  * A single entry in the unified error catalog.
  */

package/dist/error-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-catalog.d.ts","sourceRoot":"","sources":["../src/error-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAeD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAijC9D,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE5E;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAK1F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,EAAE,CAE1D"}
+{"version":3,"file":"error-catalog.d.ts","sourceRoot":"","sources":["../src/error-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAeD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAijC9D,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE5E;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAK1F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,EAAE,CAE1D"}

package/dist/error-registry.d.ts

@@ -12,7 +12,7 @@
  * @epic T4663
  */
 import { ExitCode } from '@cleocode/contracts';
-import type { LAFSErrorCategory } from '@cleocode/lafs-protocol';
+import type { LAFSErrorCategory } from '@cleocode/lafs';
 /**
  * Entry in the CLEO-to-LAFS error registry.
  *

package/dist/error-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../src/error-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,GAAG,SAAS,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,EAAE,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D"}
+{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../src/error-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,GAAG,SAAS,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,EAAE,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D"}

package/dist/errors.d.ts

@@ -7,7 +7,7 @@
  * @task T5240
  */
 import { ExitCode } from '@cleocode/contracts';
-import type { LAFSError } from '@cleocode/lafs-protocol';
+import type { LAFSError } from '@cleocode/lafs';
 /**
  * RFC 9457 Problem Details object.
  * Structured error representation for API/MCP responses.

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAsC,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,yBAAyB,CAAC;AAG5E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAqDD;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAGjE,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IASH;;;;OAIG;IACH,WAAW,IAAI,SAAS;IAgBxB;;;;OAIG;IACH,gBAAgB,IAAI,cAAc;IAmBlC,4EAA4E;IAC5E,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAajC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAetB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAsC,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,gBAAgB,CAAC;AAGnE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAqDD;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAGjE,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IASH;;;;OAIG;IACH,WAAW,IAAI,SAAS;IAgBxB;;;;OAIG;IACH,gBAAgB,IAAI,cAAc;IAmBlC,4EAA4E;IAC5E,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAajC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAetB"}

package/dist/hooks/handlers/agent-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/agent-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAoC7E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"agent-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/agent-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAO7E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/hooks/handlers/agent-hooks.js

@@ -0,0 +1,106 @@
+/**
+ * Agent (Subagent) Lifecycle Hook Handlers
+ *
+ * Captures SubagentStart and SubagentStop events to BRAIN so that
+ * multi-agent orchestration runs leave an auditable trail of which
+ * subagents were spawned, what tasks they were assigned, and how
+ * they completed.
+ *
+ * Gated behind brain.autoCapture config. Never throws — all errors are
+ * swallowed so that brain capture never blocks agent orchestration.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T166
+ * @epic T134
+ */
+import { hooks } from '../registry.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+/**
+ * Handle SubagentStart — log subagent spawn as a BRAIN observation.
+ *
+ * Records the agent ID, role, and task assignment so orchestrators can
+ * trace which agents were active in a given session.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStart event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handleSubagentStart(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const rolePart = payload.role ? ` role=${payload.role}` : '';
+    const taskPart = payload.taskId ? ` task=${payload.taskId}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Subagent spawned: ${payload.agentId}${rolePart}${taskPart}`,
+            title: `Subagent start: ${payload.agentId}`,
+            type: 'discovery',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+/**
+ * Handle SubagentStop — log subagent completion result as a BRAIN observation.
+ *
+ * Records the agent ID, completion status, assigned task, and optional
+ * summary reference so orchestrators can audit subagent outcomes.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStop event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handleSubagentStop(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const statusPart = payload.status ? ` status=${payload.status}` : '';
+    const taskPart = payload.taskId ? ` task=${payload.taskId}` : '';
+    const summaryPart = payload.summary ? `\nSummary: ${payload.summary}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Subagent completed: ${payload.agentId}${statusPart}${taskPart}${summaryPart}`,
+            title: `Subagent stop: ${payload.agentId}`,
+            type: 'change',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+hooks.register({
+    id: 'brain-subagent-start',
+    event: 'SubagentStart',
+    handler: handleSubagentStart,
+    priority: 100,
+});
+hooks.register({
+    id: 'brain-subagent-stop',
+    event: 'SubagentStop',
+    handler: handleSubagentStop,
+    priority: 100,
+});
+//# sourceMappingURL=agent-hooks.js.map

package/dist/hooks/handlers/agent-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/agent-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAmB,EACnB,OAA6B;IAE7B,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO;IAEvD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjE,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,qBAAqB,OAAO,CAAC,OAAO,GAAG,QAAQ,GAAG,QAAQ,EAAE;YAClE,KAAK,EAAE,mBAAmB,OAAO,CAAC,OAAO,EAAE;YAC3C,IAAI,EAAE,WAAW;YACjB,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,OAA4B;IAE5B,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO;IAEvD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE3E,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,uBAAuB,OAAO,CAAC,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,EAAE;YACpF,KAAK,EAAE,kBAAkB,OAAO,CAAC,OAAO,EAAE;YAC1C,IAAI,EAAE,QAAQ;YACd,eAAe,EAAE,OAAO,CAAC,SAAS;YAClC,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;IACjD,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,sBAAsB;IAC1B,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC;AAEH,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC"}

package/dist/hooks/handlers/context-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/context-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAoCzE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAsBf"}
+{"version":3,"file":"context-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/context-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOzE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/hooks/handlers/context-hooks.js

@@ -0,0 +1,111 @@
+/**
+ * Context Compaction Hook Handlers
+ *
+ * Captures PreCompact and PostCompact events to BRAIN so that agents
+ * can later observe when context compactions occurred and what state
+ * preceded them. This is especially useful for long sessions where
+ * context is compacted multiple times.
+ *
+ * PreCompact saves a session context snapshot before compaction begins.
+ * PostCompact records that compaction occurred and the resulting token counts.
+ *
+ * Gated behind brain.autoCapture config. Never throws — all errors are
+ * swallowed so brain capture never blocks context compaction.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T166
+ * @epic T134
+ */
+import { hooks } from '../registry.js';
+import { isAutoCaptureEnabled, isMissingBrainSchemaError } from './handler-helpers.js';
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+/**
+ * Handle PreCompact — snapshot current session memory context to BRAIN.
+ *
+ * Fires immediately before context compaction begins. Records the token
+ * count and compaction reason so the brain retains context about what
+ * was in scope before compaction.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PreCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePreCompact(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const tokensPart = payload.tokensBefore != null ? ` (~${payload.tokensBefore.toLocaleString()} tokens)` : '';
+    const reasonPart = payload.reason ? ` Reason: ${payload.reason}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Context compaction about to begin${tokensPart}.${reasonPart}`,
+            title: 'Pre-compaction context snapshot',
+            type: 'discovery',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+/**
+ * Handle PostCompact — record compaction completion to BRAIN.
+ *
+ * Fires immediately after context compaction completes. Records the
+ * before/after token counts so agents can correlate observations made
+ * before compaction with those made after.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePostCompact(projectRoot, payload) {
+    if (!(await isAutoCaptureEnabled(projectRoot)))
+        return;
+    const { observeBrain } = await import('../../memory/brain-retrieval.js');
+    const statusPart = payload.success ? 'succeeded' : 'failed';
+    const beforePart = payload.tokensBefore != null ? ` before=${payload.tokensBefore.toLocaleString()}` : '';
+    const afterPart = payload.tokensAfter != null ? ` after=${payload.tokensAfter.toLocaleString()}` : '';
+    try {
+        await observeBrain(projectRoot, {
+            text: `Context compaction ${statusPart}${beforePart}${afterPart}`,
+            title: 'Post-compaction record',
+            type: 'change',
+            sourceSessionId: payload.sessionId,
+            sourceType: 'agent',
+        });
+    }
+    catch (err) {
+        if (!isMissingBrainSchemaError(err))
+            throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+hooks.register({
+    id: 'brain-pre-compact',
+    event: 'PreCompact',
+    handler: handlePreCompact,
+    priority: 100,
+});
+hooks.register({
+    id: 'brain-post-compact',
+    event: 'PostCompact',
+    handler: handlePostCompact,
+    priority: 100,
+});
+//# sourceMappingURL=context-hooks.js.map

package/dist/hooks/handlers/context-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/context-hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks/handlers/error-hooks.d.ts

@@ -7,12 +7,21 @@
  */
 import type { PostToolUseFailurePayload } from '../types.js';
 /**
- * Handle PostToolUseFailure - capture operation errors to BRAIN
+ * Handle PostToolUseFailure — capture operation errors to BRAIN.
  *
- * Includes infinite-loop guard: if the payload has _fromHook marker,
- * the handler skips to prevent PostToolUseFailure -> observeBrain -> PostToolUseFailure loops.
- * Additionally, ALL observeBrain errors are silently suppressed to prevent
- * re-entrant hook firing.
+ * Includes an infinite-loop guard: if the payload carries a `_fromHook`
+ * metadata marker the handler skips immediately to prevent the cycle
+ * `PostToolUseFailure → observeBrain → PostToolUseFailure`. All
+ * `observeBrain` errors are also silently suppressed for the same reason.
+ *
+ * Never throws. All brain-write errors are swallowed so error hooks
+ * never block the original error path.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostToolUseFailure event payload.
+ *
+ * @task T166
+ * @epic T134
  */
 export declare function handleError(projectRoot: string, payload: PostToolUseFailurePayload): Promise<void>;
 //# sourceMappingURL=error-hooks.d.ts.map

package/dist/hooks/handlers/error-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"error-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/hooks/handlers/error-hooks.js

@@ -7,12 +7,21 @@
  */
 import { hooks } from '../registry.js';
 /**
- * Handle onError - capture operation errors to BRAIN
+ * Handle PostToolUseFailure — capture operation errors to BRAIN.
  *
- * Includes infinite-loop guard: if the payload has _fromHook marker,
- * the handler skips to prevent onError -> observeBrain -> onError loops.
- * Additionally, ALL observeBrain errors are silently suppressed to prevent
- * re-entrant hook firing.
+ * Includes an infinite-loop guard: if the payload carries a `_fromHook`
+ * metadata marker the handler skips immediately to prevent the cycle
+ * `PostToolUseFailure → observeBrain → PostToolUseFailure`. All
+ * `observeBrain` errors are also silently suppressed for the same reason.
+ *
+ * Never throws. All brain-write errors are swallowed so error hooks
+ * never block the original error path.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostToolUseFailure event payload.
+ *
+ * @task T166
+ * @epic T134
  */
 export async function handleError(projectRoot, payload) {
     // Infinite-loop guard: skip if this error originated from a hook
@@ -36,7 +45,7 @@ export async function handleError(projectRoot, payload) {
 // Register handler on module load
 hooks.register({
     id: 'brain-error',
-    event: 'onError',
+    event: 'PostToolUseFailure',
     handler: handleError,
     priority: 100,
 });

package/dist/hooks/handlers/error-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,WAAmB,EAAE,OAAuB;IAC5E,iEAAiE;IACjE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC;QAAE,OAAO;IAE5C,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,QAAQ,GACZ,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7F,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,YAAY,QAAQ,KAAK,OAAO,CAAC,OAAO,WAAW,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;YACrI,KAAK,EAAE,UAAU,QAAQ,EAAE;YAC3B,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,IAAI,EAAE,CAAC;QACd,4DAA4D;QAC5D,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED,kCAAkC;AAClC,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC"}
+{"version":3,"file":"error-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,OAAkC;IAElC,iEAAiE;IACjE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC;QAAE,OAAO;IAE5C,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAEzE,MAAM,QAAQ,GACZ,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAE7F,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,YAAY,QAAQ,KAAK,OAAO,CAAC,OAAO,WAAW,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;YACrI,KAAK,EAAE,UAAU,QAAQ,EAAE;YAC3B,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,IAAI,EAAE,CAAC;QACd,4DAA4D;QAC5D,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED,kCAAkC;AAClC,KAAK,CAAC,QAAQ,CAAC;IACb,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC"}

package/dist/hooks/handlers/file-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAoDvD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAgCf"}
+{"version":3,"file":"file-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA+CvD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/hooks/handlers/file-hooks.js

@@ -5,16 +5,13 @@
  * Includes 5-second dedup and path-based filtering to avoid noisy writes.
  * Auto-registers on module load.
  *
- * Disabled by default. Set CLEO_BRAIN_CAPTURE_FILES=true to enable.
+ * Disabled by default. Enable via:
+ *   - Config: brain.captureFiles = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_FILES=true  (overrides config)
  */
 import { isAbsolute, relative } from 'node:path';
 import { hooks } from '../registry.js';
-function isMissingBrainSchemaError(err) {
-    if (!(err instanceof Error))
-        return false;
-    const message = String(err.message || '').toLowerCase();
-    return message.includes('no such table') && message.includes('brain_');
-}
+import { isMissingBrainSchemaError } from './handler-helpers.js';
 /** 5-second dedup map: filePath -> last dispatch timestamp */
 const recentWrites = new Map();
 const DEDUP_INTERVAL_MS = 5_000;
@@ -34,16 +31,43 @@ function shouldSkipPath(relativePath) {
     return SKIP_PATTERNS.some((pattern) => pattern.test(relativePath));
 }
 /**
- * Handle onFileChange - capture file changes to BRAIN
+ * Check whether file-change capture is enabled.
  *
- * Gated behind CLEO_BRAIN_CAPTURE_FILES=true env var.
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_FILES env var (explicit override)
+ *   2. brain.captureFiles project config value
+ *
+ * Defaults to false when neither is set.
+ */
+async function isFileCaptureEnabled(projectRoot) {
+    const envOverride = process.env['CLEO_BRAIN_CAPTURE_FILES'];
+    if (envOverride !== undefined) {
+        return envOverride === 'true';
+    }
+    try {
+        const { loadConfig } = await import('../../config.js');
+        const config = await loadConfig(projectRoot);
+        return config.brain?.captureFiles ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Handle Notification (file-change variant) - capture file changes to BRAIN
+ *
+ * Gated behind brain.captureFiles config or CLEO_BRAIN_CAPTURE_FILES env var.
+ * Env var takes precedence over config for backward compatibility.
  * Deduplicates rapid writes to the same file within a 5-second window.
  * Filters out .cleo/ internal files and test temp directories.
  * Converts absolute paths to project-relative paths.
  */
 export async function handleFileChange(projectRoot, payload) {
+    // Only handle file-change notifications
+    if (!payload.filePath || !payload.changeType)
+        return;
     // Opt-in gate: disabled by default to prevent observation noise
-    if (process.env['CLEO_BRAIN_CAPTURE_FILES'] !== 'true')
+    if (!(await isFileCaptureEnabled(projectRoot)))
         return;
     // 5-second dedup
     const now = Date.now();
@@ -73,7 +97,7 @@ export async function handleFileChange(projectRoot, payload) {
 // Register handler on module load
 hooks.register({
     id: 'brain-file-change',
-    event: 'onFileChange',
+    event: 'Notification',
     handler: handleFileChange,
     priority: 100,
 });

package/dist/hooks/handlers/file-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-hooks.js","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks/handlers/handler-helpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared helpers for hook handler modules.
+ *
+ * Centralises the two patterns repeated across all brain-capture handlers:
+ *
+ * 1. `isMissingBrainSchemaError` — detects the "no such table: brain_*" error
+ *    thrown when brain.db has not been migrated yet, so handlers can swallow
+ *    it silently instead of crashing agent workflows.
+ *
+ * 2. `isAutoCaptureEnabled` — reads `brain.autoCapture` from the cascaded
+ *    project config and returns false when the config is unreadable.
+ *
+ * Import these instead of redefining them in each handler file.
+ *
+ * @task T166
+ * @epic T134
+ */
+/**
+ * Return true when the error is the "no such table: brain_*" SQLite error
+ * thrown before brain.db has been migrated.
+ *
+ * Hook handlers use this to swallow migration-lag errors without hiding
+ * genuine failures: if the error is NOT a missing-schema error it is
+ * re-thrown so it propagates normally.
+ *
+ * @param err - The caught error value (may be any type).
+ */
+export declare function isMissingBrainSchemaError(err: unknown): boolean;
+/**
+ * Return true when `brain.autoCapture` is enabled for the given project.
+ *
+ * Resolution order (first truthy wins):
+ *   1. `brain.autoCapture` project config value (via `loadConfig` cascade)
+ *
+ * Defaults to `false` when the config is unreadable or the key is absent,
+ * so handlers are safely disabled in environments where brain.db is not set up.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export declare function isAutoCaptureEnabled(projectRoot: string): Promise<boolean>;
+//# sourceMappingURL=handler-helpers.d.ts.map

package/dist/hooks/handlers/handler-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-helpers.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/handler-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI/D;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhF"}

package/dist/hooks/handlers/handler-helpers.js

@@ -0,0 +1,61 @@
+/**
+ * Shared helpers for hook handler modules.
+ *
+ * Centralises the two patterns repeated across all brain-capture handlers:
+ *
+ * 1. `isMissingBrainSchemaError` — detects the "no such table: brain_*" error
+ *    thrown when brain.db has not been migrated yet, so handlers can swallow
+ *    it silently instead of crashing agent workflows.
+ *
+ * 2. `isAutoCaptureEnabled` — reads `brain.autoCapture` from the cascaded
+ *    project config and returns false when the config is unreadable.
+ *
+ * Import these instead of redefining them in each handler file.
+ *
+ * @task T166
+ * @epic T134
+ */
+// ---------------------------------------------------------------------------
+// Brain schema error guard
+// ---------------------------------------------------------------------------
+/**
+ * Return true when the error is the "no such table: brain_*" SQLite error
+ * thrown before brain.db has been migrated.
+ *
+ * Hook handlers use this to swallow migration-lag errors without hiding
+ * genuine failures: if the error is NOT a missing-schema error it is
+ * re-thrown so it propagates normally.
+ *
+ * @param err - The caught error value (may be any type).
+ */
+export function isMissingBrainSchemaError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const message = String(err.message || '').toLowerCase();
+    return message.includes('no such table') && message.includes('brain_');
+}
+// ---------------------------------------------------------------------------
+// Auto-capture config gate
+// ---------------------------------------------------------------------------
+/**
+ * Return true when `brain.autoCapture` is enabled for the given project.
+ *
+ * Resolution order (first truthy wins):
+ *   1. `brain.autoCapture` project config value (via `loadConfig` cascade)
+ *
+ * Defaults to `false` when the config is unreadable or the key is absent,
+ * so handlers are safely disabled in environments where brain.db is not set up.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export async function isAutoCaptureEnabled(projectRoot) {
+    try {
+        const { loadConfig } = await import('../../config.js');
+        const config = await loadConfig(projectRoot);
+        return config.brain?.autoCapture ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=handler-helpers.js.map

package/dist/hooks/handlers/handler-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-helpers.js","sourceRoot":"","sources":["../../../src/hooks/handlers/handler-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAY;IACpD,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,OAAO,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAmB;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,KAAK,EAAE,WAAW,IAAI,KAAK,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/hooks/handlers/index.js

@@ -3,6 +3,9 @@
  *
  * Barrel export for all hook handlers. Importing this module will
  * auto-register all handlers with the hook registry.
+ *
+ * @task T166
+ * @epic T134
  */
 // Import handlers to trigger auto-registration on module load
 import './session-hooks.js';
@@ -10,10 +13,16 @@ import './task-hooks.js';
 import './error-hooks.js';
 import './file-hooks.js';
 import './mcp-hooks.js';
+import './work-capture-hooks.js';
+import './agent-hooks.js';
+import './context-hooks.js';
+export { handleSubagentStart, handleSubagentStop } from './agent-hooks.js';
+export { handlePostCompact, handlePreCompact } from './context-hooks.js';
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';
-export { handlePromptSubmit, handleResponseComplete } from './mcp-hooks.js';
+export { handlePromptSubmit, handleResponseComplete, handleSystemNotification, } from './mcp-hooks.js';
 // Re-export handler functions for explicit use
 export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
 export { handleToolComplete, handleToolStart } from './task-hooks.js';
+export { handleWorkPromptSubmit, handleWorkResponseComplete } from './work-capture-hooks.js';
 //# sourceMappingURL=index.js.map

package/dist/hooks/handlers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,iBAAiB,CAAC;AACzB,OAAO,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,+CAA+C;AAC/C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8DAA8D;AAC9D,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,iBAAiB,CAAC;AACzB,OAAO,gBAAgB,CAAC;AACxB,OAAO,yBAAyB,CAAC;AACjC,OAAO,kBAAkB,CAAC;AAC1B,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,+CAA+C;AAC/C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC"}