@cabane/companion 0.6.21 → 0.6.23

package/README.md

@@ -142,7 +142,7 @@ A `coding` agent needs a directory to run in — a path that only exists on your
   "agents": {
     "my-coding-agent": {
       "cwd": "/Users/you/code/project", // working directory the agent runs in
-      "prepareHook": "git -C /Users/you/code/project pull --ff-only", // optional: runs before each turn
+      "prepareHook": { "command": "/Users/you/bin/prepare-turn" }, // optional: resolves the cwd before each turn
     },
   },
 }
@@ -150,6 +150,19 @@ A `coding` agent needs a directory to run in — a path that only exists on your
 
 A malformed `agents` block fails `cabane-companion start` immediately with a message pointing at the exact field — it won't silently fall back.
 
+**A hook that is the same for every agent goes at the top level instead.** If your hook works out the directory itself — from the conversation and agent ids the Companion hands it — then listing every agent by name is a roster you have to remember to update, and an agent you forget gets no hook at all and starts its turn wherever the Companion happens to be. So `prepareHook` can sit beside `agents` rather than inside it:
+
+```jsonc
+{
+  "prepareHook": { "command": "/Users/you/bin/prepare-turn" }, // every agent on this device
+  "agents": {
+    "special-case": { "prepareHook": { "command": "/Users/you/bin/other-hook" } }, // wins for this one
+  },
+}
+```
+
+The agent's own entry wins when it names a hook; otherwise the device-level one applies. It survives a re-pair along with the rest of your local settings, and `cabane-companion status` prints it. A hook that fails still fails the turn loudly either way.
+
 ### Auto-memory (off by default)
 
 Claude Code's **auto-memory** — where the agent writes notes to a local `~/.claude` memory directory and recalls them on later turns — is **off by default** on every Companion. The stance is that memory-shaped things belong in your Cabane workspace (a shared, versioned `ABOUT.md`-style file or doc), not a private local directory that no one else can see. If you run your own Companion and want your normal Claude Code memory workflow back, set `claudeCode.autoMemory: true` on the agent — the Companion then stops overriding it and your own `~/.claude/settings.json` governs auto-memory as usual (this bites in `coding` mode, where your project settings are read):

package/dist/cli.js

@@ -278,6 +278,22 @@ var companionConfigSchema = z2.object({
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
   agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+  // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
+  // assigned to this device, unless that agent's own `agents` row names a hook of
+  // its own.
+  //
+  // Until now `prepareHook` existed only under `agents[<id>]`, which made the
+  // config a second silent roster: a device whose provisioning is genuinely
+  // per-device (ours resolves a directory from the conversation and agent ids the
+  // companion already hands the hook) still had to list every agent by id, and an
+  // agent nobody remembered to add got no hook at all — no error, no log, just a
+  // turn that started in the operator's `$HOME`. That is how @dale woke in
+  // `/home/joshed` on 2026-08-17 with a perfectly correct dispatch.
+  //
+  // Absent → nothing changes for anyone, which is why this can land inert: a
+  // device with no device-level entry behaves exactly as it did before. A hook
+  // that fails still fails the dispatch loudly, as now.
+  prepareHook: prepareHookSchema.optional(),
   // Dashboard settings (all optional). dashboardPort: preferred bind port (next
   // free one if taken); autoOpen: whether `start` opens the browser (the
   // `--no-open` flag / `COMPANION_NO_OPEN=1` override per-run); logLevel: pino
@@ -340,7 +356,9 @@ function migrateConnectedHarnesses(cfg, claudeOnPath2) {
 }
 function localAgentConfig(cfg, agent) {
   const map = cfg.agents ?? {};
-  return map[agent.agentId] ?? map[agent.agentUsername] ?? map[`${agent.workspaceSlug}/${agent.agentUsername}`] ?? {};
+  const row = map[agent.agentId] ?? map[agent.agentUsername] ?? map[`${agent.workspaceSlug}/${agent.agentUsername}`] ?? {};
+  if (!cfg.prepareHook || row.prepareHook) return row;
+  return { ...row, prepareHook: cfg.prepareHook };
 }
 function loadConfig() {
   const path = configPath();
@@ -400,10 +418,11 @@ function loadConfigTolerant() {
   }
   const strict = companionConfigSchema.safeParse(parsed);
   if (strict.success) {
-    const { agents: agents2, dashboardPort, autoOpen, logLevel, claudeCode: claudeCode2 } = strict.data;
+    const { agents: agents2, prepareHook: prepareHook2, dashboardPort, autoOpen, logLevel, claudeCode: claudeCode2 } = strict.data;
     return {
       local: {
         ...agents2 !== void 0 ? { agents: agents2 } : {},
+        ...prepareHook2 !== void 0 ? { prepareHook: prepareHook2 } : {},
         ...dashboardPort !== void 0 ? { dashboardPort } : {},
         ...autoOpen !== void 0 ? { autoOpen } : {},
         ...logLevel !== void 0 ? { logLevel } : {},
@@ -417,6 +436,8 @@ function loadConfigTolerant() {
   const local = {};
   const agents = z2.record(z2.string(), localAgentConfigSchema).safeParse(obj.agents);
   if (agents.success) local.agents = agents.data;
+  const prepareHook = prepareHookSchema.safeParse(obj.prepareHook);
+  if (prepareHook.success) local.prepareHook = prepareHook.data;
   if (typeof obj.dashboardPort === "number") local.dashboardPort = obj.dashboardPort;
   if (typeof obj.autoOpen === "boolean") local.autoOpen = obj.autoOpen;
   if (obj.logLevel === "warn" || obj.logLevel === "info" || obj.logLevel === "debug") {
@@ -6834,10 +6855,11 @@ function describeSubAgentError(status2, body) {
 var Dispatcher = class {
   constructor(opts) {
     this.opts = opts;
+    this.aborts = opts.aborts ?? /* @__PURE__ */ new Map();
   }
   opts;
   // SJ383: per-(conversation, agent) abort registry.
-  aborts = /* @__PURE__ */ new Map();
+  aborts;
   notifyStart(info) {
     try {
       this.opts.observer?.onStart(info);
@@ -8587,6 +8609,7 @@ var CompanionSupervisor = class {
       outbox,
       log: this.log
     });
+    const aborts = /* @__PURE__ */ new Map();
     const dispatcher = this.buildDispatcher({
       api,
       baseUrl: this.config.baseUrl,
@@ -8595,7 +8618,8 @@ var CompanionSupervisor = class {
       agentId: it.agentId,
       agentUsername: it.agentUsername,
       credential,
-      runConfig
+      runConfig,
+      aborts
     });
     const drain2 = this.makeDrain(api, it.agentId);
     wr.agents.set(it.agentId, {
@@ -8605,6 +8629,7 @@ var CompanionSupervisor = class {
       credential,
       runConfig,
       api,
+      aborts,
       dispatcher,
       cancelDrain: drain2.cancel,
       kickDrain: drain2.kick
@@ -8640,7 +8665,12 @@ var CompanionSupervisor = class {
     return isClaudeCodeConnected(this.config) && this.claudeCodePresent();
   }
   buildDispatcher(ctx) {
-    if (this.dispatcherFactory) return this.dispatcherFactory(ctx);
+    const local = localAgentConfig(this.config, {
+      agentId: ctx.agentId,
+      agentUsername: ctx.agentUsername,
+      workspaceSlug: ctx.workspaceSlug
+    });
+    if (this.dispatcherFactory) return this.dispatcherFactory({ ...ctx, local });
     return new Dispatcher({
       api: ctx.api,
       baseUrl: ctx.baseUrl,
@@ -8649,11 +8679,8 @@ var CompanionSupervisor = class {
       agentId: ctx.agentId,
       agentUsername: ctx.agentUsername,
       credential: ctx.credential,
-      local: localAgentConfig(this.config, {
-        agentId: ctx.agentId,
-        agentUsername: ctx.agentUsername,
-        workspaceSlug: ctx.workspaceSlug
-      }),
+      local,
+      aborts: ctx.aborts,
       runConfig: ctx.runConfig,
       log: this.log,
       // CT833: register the claude-code adapter only when this device actually
@@ -8923,6 +8950,7 @@ var CompanionSupervisor = class {
     if (!next) return;
     this.config = next;
     this.log.level = next.logLevel ?? "debug";
+    this.rebuildDispatchers();
     void this.refreshAssignments();
   }
   // The dashboard "refresh assignments" control — an immediate pull.
@@ -9020,8 +9048,8 @@ var CompanionSupervisor = class {
   }
   // Re-create every running agent's Dispatcher from the CURRENT config, keeping
   // the runner (its api/outbox/chains/SSE) intact. Used after a runtime-enabling
-  // config change so the adapter registry — rebuilt per turn from the dispatcher's
-  // constructor opts — picks up the new opencode/codex adapter.
+  // config change so constructor-captured options — per-agent cwd/prepareHook and
+  // the adapter registry — pick up their new values without an app restart.
   rebuildDispatchers() {
     for (const wr of this.workspaces.values()) {
       for (const runner of wr.agents.values()) {
@@ -9033,7 +9061,8 @@ var CompanionSupervisor = class {
           agentId: runner.agentId,
           agentUsername: runner.username,
           credential: runner.credential,
-          runConfig: runner.runConfig
+          runConfig: runner.runConfig,
+          aborts: runner.aborts
         });
       }
     }
@@ -9441,6 +9470,10 @@ async function status() {
     names.length > 0 ? `secrets:      ${names.length} declared (${names.join(", ")})
 ` : "secrets:      none declared \u2014 add `${VAR}` values to ~/.cabane/secrets.json for MCP servers that need them\n"
   );
+  if (cfg.prepareHook) {
+    process.stdout.write(`prepare hook: ${cfg.prepareHook.command} (device-level, all agents)
+`);
+  }
   const overrides = Object.keys(cfg.agents ?? {});
   if (overrides.length > 0) {
     process.stdout.write(`local overrides for: ${overrides.join(", ")}

package/dist/pairing-config.js

@@ -144,6 +144,22 @@ var companionConfigSchema = z2.object({
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
   agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+  // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
+  // assigned to this device, unless that agent's own `agents` row names a hook of
+  // its own.
+  //
+  // Until now `prepareHook` existed only under `agents[<id>]`, which made the
+  // config a second silent roster: a device whose provisioning is genuinely
+  // per-device (ours resolves a directory from the conversation and agent ids the
+  // companion already hands the hook) still had to list every agent by id, and an
+  // agent nobody remembered to add got no hook at all — no error, no log, just a
+  // turn that started in the operator's `$HOME`. That is how @dale woke in
+  // `/home/joshed` on 2026-08-17 with a perfectly correct dispatch.
+  //
+  // Absent → nothing changes for anyone, which is why this can land inert: a
+  // device with no device-level entry behaves exactly as it did before. A hook
+  // that fails still fails the dispatch loudly, as now.
+  prepareHook: prepareHookSchema.optional(),
   // Dashboard settings (all optional). dashboardPort: preferred bind port (next
   // free one if taken); autoOpen: whether `start` opens the browser (the
   // `--no-open` flag / `COMPANION_NO_OPEN=1` override per-run); logLevel: pino
@@ -252,10 +268,11 @@ function loadConfigTolerant() {
   }
   const strict = companionConfigSchema.safeParse(parsed);
   if (strict.success) {
-    const { agents: agents2, dashboardPort, autoOpen, logLevel, claudeCode: claudeCode2 } = strict.data;
+    const { agents: agents2, prepareHook: prepareHook2, dashboardPort, autoOpen, logLevel, claudeCode: claudeCode2 } = strict.data;
     return {
       local: {
         ...agents2 !== void 0 ? { agents: agents2 } : {},
+        ...prepareHook2 !== void 0 ? { prepareHook: prepareHook2 } : {},
         ...dashboardPort !== void 0 ? { dashboardPort } : {},
         ...autoOpen !== void 0 ? { autoOpen } : {},
         ...logLevel !== void 0 ? { logLevel } : {},
@@ -269,6 +286,8 @@ function loadConfigTolerant() {
   const local = {};
   const agents = z2.record(z2.string(), localAgentConfigSchema).safeParse(obj.agents);
   if (agents.success) local.agents = agents.data;
+  const prepareHook = prepareHookSchema.safeParse(obj.prepareHook);
+  if (prepareHook.success) local.prepareHook = prepareHook.data;
   if (typeof obj.dashboardPort === "number") local.dashboardPort = obj.dashboardPort;
   if (typeof obj.autoOpen === "boolean") local.autoOpen = obj.autoOpen;
   if (obj.logLevel === "warn" || obj.logLevel === "info" || obj.logLevel === "debug") {

package/dist/runtime.js

@@ -271,6 +271,22 @@ var companionConfigSchema = z2.object({
   // agentId / username / `slug/username`. Hand-added by the operator; the companion
   // never writes this (it only persists credentials + the device, elsewhere).
   agents: z2.record(z2.string(), localAgentConfigSchema).optional(),
+  // CT1095: the DEVICE-LEVEL prepare hook — one entry that applies to every agent
+  // assigned to this device, unless that agent's own `agents` row names a hook of
+  // its own.
+  //
+  // Until now `prepareHook` existed only under `agents[<id>]`, which made the
+  // config a second silent roster: a device whose provisioning is genuinely
+  // per-device (ours resolves a directory from the conversation and agent ids the
+  // companion already hands the hook) still had to list every agent by id, and an
+  // agent nobody remembered to add got no hook at all — no error, no log, just a
+  // turn that started in the operator's `$HOME`. That is how @dale woke in
+  // `/home/joshed` on 2026-08-17 with a perfectly correct dispatch.
+  //
+  // Absent → nothing changes for anyone, which is why this can land inert: a
+  // device with no device-level entry behaves exactly as it did before. A hook
+  // that fails still fails the dispatch loudly, as now.
+  prepareHook: prepareHookSchema.optional(),
   // Dashboard settings (all optional). dashboardPort: preferred bind port (next
   // free one if taken); autoOpen: whether `start` opens the browser (the
   // `--no-open` flag / `COMPANION_NO_OPEN=1` override per-run); logLevel: pino
@@ -333,7 +349,9 @@ function migrateConnectedHarnesses(cfg, claudeOnPath2) {
 }
 function localAgentConfig(cfg, agent) {
   const map = cfg.agents ?? {};
-  return map[agent.agentId] ?? map[agent.agentUsername] ?? map[`${agent.workspaceSlug}/${agent.agentUsername}`] ?? {};
+  const row = map[agent.agentId] ?? map[agent.agentUsername] ?? map[`${agent.workspaceSlug}/${agent.agentUsername}`] ?? {};
+  if (!cfg.prepareHook || row.prepareHook) return row;
+  return { ...row, prepareHook: cfg.prepareHook };
 }
 function loadConfig() {
   const path = configPath();
@@ -6456,10 +6474,11 @@ function describeSubAgentError(status, body) {
 var Dispatcher = class {
   constructor(opts) {
     this.opts = opts;
+    this.aborts = opts.aborts ?? /* @__PURE__ */ new Map();
   }
   opts;
   // SJ383: per-(conversation, agent) abort registry.
-  aborts = /* @__PURE__ */ new Map();
+  aborts;
   notifyStart(info) {
     try {
       this.opts.observer?.onStart(info);
@@ -8209,6 +8228,7 @@ var CompanionSupervisor = class {
       outbox,
       log: this.log
     });
+    const aborts = /* @__PURE__ */ new Map();
     const dispatcher = this.buildDispatcher({
       api,
       baseUrl: this.config.baseUrl,
@@ -8217,7 +8237,8 @@ var CompanionSupervisor = class {
       agentId: it.agentId,
       agentUsername: it.agentUsername,
       credential,
-      runConfig
+      runConfig,
+      aborts
     });
     const drain2 = this.makeDrain(api, it.agentId);
     wr.agents.set(it.agentId, {
@@ -8227,6 +8248,7 @@ var CompanionSupervisor = class {
       credential,
       runConfig,
       api,
+      aborts,
       dispatcher,
       cancelDrain: drain2.cancel,
       kickDrain: drain2.kick
@@ -8262,7 +8284,12 @@ var CompanionSupervisor = class {
     return isClaudeCodeConnected(this.config) && this.claudeCodePresent();
   }
   buildDispatcher(ctx) {
-    if (this.dispatcherFactory) return this.dispatcherFactory(ctx);
+    const local = localAgentConfig(this.config, {
+      agentId: ctx.agentId,
+      agentUsername: ctx.agentUsername,
+      workspaceSlug: ctx.workspaceSlug
+    });
+    if (this.dispatcherFactory) return this.dispatcherFactory({ ...ctx, local });
     return new Dispatcher({
       api: ctx.api,
       baseUrl: ctx.baseUrl,
@@ -8271,11 +8298,8 @@ var CompanionSupervisor = class {
       agentId: ctx.agentId,
       agentUsername: ctx.agentUsername,
       credential: ctx.credential,
-      local: localAgentConfig(this.config, {
-        agentId: ctx.agentId,
-        agentUsername: ctx.agentUsername,
-        workspaceSlug: ctx.workspaceSlug
-      }),
+      local,
+      aborts: ctx.aborts,
       runConfig: ctx.runConfig,
       log: this.log,
       // CT833: register the claude-code adapter only when this device actually
@@ -8545,6 +8569,7 @@ var CompanionSupervisor = class {
     if (!next) return;
     this.config = next;
     this.log.level = next.logLevel ?? "debug";
+    this.rebuildDispatchers();
     void this.refreshAssignments();
   }
   // The dashboard "refresh assignments" control — an immediate pull.
@@ -8642,8 +8667,8 @@ var CompanionSupervisor = class {
   }
   // Re-create every running agent's Dispatcher from the CURRENT config, keeping
   // the runner (its api/outbox/chains/SSE) intact. Used after a runtime-enabling
-  // config change so the adapter registry — rebuilt per turn from the dispatcher's
-  // constructor opts — picks up the new opencode/codex adapter.
+  // config change so constructor-captured options — per-agent cwd/prepareHook and
+  // the adapter registry — pick up their new values without an app restart.
   rebuildDispatchers() {
     for (const wr of this.workspaces.values()) {
       for (const runner of wr.agents.values()) {
@@ -8655,7 +8680,8 @@ var CompanionSupervisor = class {
           agentId: runner.agentId,
           agentUsername: runner.username,
           credential: runner.credential,
-          runConfig: runner.runConfig
+          runConfig: runner.runConfig,
+          aborts: runner.aborts
         });
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "type": "module",
   "description": "The Cabane Companion (headless): connect a coding agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",