@cabane/companion 0.6.8 → 0.6.10

package/dist/cli.js

@@ -79,7 +79,20 @@ var prepareHookSchema = z.object({
   // Wall-clock cap for the hook. Provisioning is slow (minutes), so the
   // default is generous; a hook that hangs past this is killed and the turn
   // fails with a clear timeout message rather than pinning the companion.
-  timeoutMs: z.number().int().positive().optional()
+  timeoutMs: z.number().int().positive().optional(),
+  // CT943: re-invoke the hook on turns where a prepared result already exists,
+  // in VALIDATE mode — the cached result is handed back as `prepared` and the
+  // hook's stdout is ignored, so the cwd provably cannot move. Its only power
+  // is to exit non-zero and fail the turn.
+  //
+  // Why it exists: the hook runs exactly once per (conversation, agent), so a
+  // later message asking for a different environment can't be honoured. Without
+  // this, it is silently ignored — the host knows and says nothing, which is
+  // the worst available outcome. An opt-in hook can now refuse it out loud.
+  //
+  // Default OFF, and deliberately: an operator hook that provisions
+  // unconditionally must not start running on every turn because it upgraded.
+  validateCached: z.boolean().optional()
 }).strict();
 var DEFAULT_TIMEOUT_MS = 10 * 6e4;
 var prepareResultSchema = z.object({
@@ -143,7 +156,12 @@ var runPrepareHook = (hook, input) => {
           // CT317: newline-joined — workspace paths never contain a newline, so a
           // hook splits on `\n` unambiguously. Empty string when none.
           CABANE_TRIGGER_ENTRY_PATHS: input.triggerEntryPaths.join("\n"),
-          CABANE_CONVERSATION_TITLE: input.title ?? ""
+          CABANE_CONVERSATION_TITLE: input.title ?? "",
+          // CT943: the dispatching message's text, and — in validate mode only —
+          // the prepared result the hook is being asked to check this dispatch
+          // against. Both empty/absent on an ordinary first run.
+          CABANE_TRIGGER_MESSAGE: input.messageBody ?? "",
+          ...input.prepared ? { CABANE_PREPARED: JSON.stringify(input.prepared) } : {}
         }
       });
     } catch (err) {
@@ -181,6 +199,10 @@ var runPrepareHook = (hook, input) => {
           );
           return;
         }
+        if (input.prepared) {
+          resolve(input.prepared);
+          return;
+        }
         try {
           resolve(parsePrepareOutput(stdout));
         } catch (err) {
@@ -3857,7 +3879,7 @@ var OPENCODE_HOST_TOOLS = [
 var OPENCODE_WEB_TOOLS = ["webfetch"];
 var OPENCODE_SUBAGENT_TOOLS = ["task"];
 var OPENCODE_SCHEDULING_TOOLS = [];
-var OPENCODE_UI_PROMPT_TOOLS = [];
+var OPENCODE_UI_PROMPT_TOOLS = ["question"];
 function opencodeToolPolicy(policy) {
   const tools = {};
   const deny = (names) => {
@@ -6292,9 +6314,11 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
     tools: [
       tool(
         SUMMON_AGENT_TOOL,
-        "Summon another agent into THIS conversation \u2014 dispatch a peer to reply here on your turn. Use it to hand part of the work to a teammate, or pull in an expert, without leaving the conversation. Pass the peer's `agentId` (discover handles + ids via `list_agents`). The peer is dispatched on your turn's final reply, so write the context/ask into that reply first \u2014 it receives your message + this conversation to work from. Writing `@handle` in your prose does NOT summon anyone (agent prose never dispatches); this tool is the only in-thread lever. Single target \u2014 the last call wins. Summoning yourself is a no-op. Reach for it when the human wants the peer's answer right HERE, in front of them \u2014 the reply lands in this thread, so there's no return to wire (a return is for work YOU consume, never a courtesy notification). A handoff to a DIFFERENT conversation is `create_conversation` / `post_message` with their `dispatch` field instead.",
+        "Summon another agent into THIS conversation \u2014 dispatch a peer to reply here on your turn. Use it to hand part of the work to a teammate, or pull in an expert, without leaving the conversation. Pass the peer's `agentId` \u2014 every agent's handle and id is on the roster in your turn context. The peer is dispatched on your turn's final reply, so write the context/ask into that reply first \u2014 it receives your message + this conversation to work from. Writing `@handle` in your prose does NOT summon anyone (agent prose never dispatches); this tool is the only in-thread lever. Single target \u2014 the last call wins. Summoning yourself is a no-op. Reach for it when the human wants the peer's answer right HERE, in front of them \u2014 the reply lands in this thread, so there's no return to wire (a return is for work YOU consume, never a courtesy notification). A handoff to a DIFFERENT conversation is `cabane.conversations.create` / `cabane.conversations.post` with their `dispatch` field instead.",
         {
-          agentId: z12.string().uuid().describe("The peer agent to summon \u2014 a workspace agent id from `list_agents`.")
+          agentId: z12.string().uuid().describe(
+            "The peer agent to summon \u2014 a workspace agent id, from your turn context's roster."
+          )
         },
         async (args) => {
           summonState.agentId = args.agentId;
@@ -6324,9 +6348,11 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
       ...askState ? [
         tool(
           ASK_TOOL,
-          "Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass `targetUserId` (a workspace member's user id \u2014 get it from `mcp__cabane__list_members`). Two forms: a SINGLE question \u2014 a `headline` (the actual question as one clear, capitalized sentence ending in `?`, \"Do we go to prod?\") plus a short `question` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a `questions` array of 1\u20135 items, each `{ headline, body?, options? }`. **Prefer the list over cramming the extra decisions into prose or dropping them** \u2014 end the turn with one ask carrying every question, never pick one and bury the rest. Each question keeps the same form rules: a one-sentence `headline`, a short `body` frame (NOT a report \u2014 your status, links, and detail go in your REPLY, and the body renders inline markdown only: links/emphasis/inline code, no bulleted lists or headings), and 2\u20134 `options` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. An option can be a short button label or a whole sentence. Provide EITHER `question` (single) or `questions` (array), never both. The ask is a first-class attention item aimed at that person; your final reply carries the surrounding CONTEXT (what you found, why you're stuck), the ask carries the QUESTION(S). An open ask marks you as blocked until EVERY question is answered, so raise one only when you truly can't proceed \u2014 never ceremonially. One ask per turn (last call wins). After asking, stop \u2014 when the person replies addressed to you, the ask resolves and you resume; other people's or agents' messages may wake you but leave it open. Targets a human only; to hand work to another AGENT use summon/dispatch instead.",
+          "Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass `targetUserId` (a workspace member's user id \u2014 every person's id is on the roster in your turn context). Two forms: a SINGLE question \u2014 a `headline` (the actual question as one clear, capitalized sentence ending in `?`, \"Do we go to prod?\") plus a short `question` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a `questions` array of 1\u20135 items, each `{ headline, body?, options? }`. **Prefer the list over cramming the extra decisions into prose or dropping them** \u2014 end the turn with one ask carrying every question, never pick one and bury the rest. Each question keeps the same form rules: a one-sentence `headline`, a short `body` frame (NOT a report \u2014 your status, links, and detail go in your REPLY, and the body renders inline markdown only: links/emphasis/inline code, no bulleted lists or headings), and 2\u20134 `options` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. An option can be a short button label or a whole sentence. Provide EITHER `question` (single) or `questions` (array), never both. The ask is a first-class attention item aimed at that person; your final reply carries the surrounding CONTEXT (what you found, why you're stuck), the ask carries the QUESTION(S). An open ask marks you as blocked until EVERY question is answered, so raise one only when you truly can't proceed \u2014 never ceremonially. One ask per turn (last call wins). After asking, stop \u2014 when the person replies addressed to you, the ask resolves and you resume; other people's or agents' messages may wake you but leave it open. Targets a human only; to hand work to another AGENT use summon/dispatch instead.",
           {
-            targetUserId: z12.string().uuid().describe("The workspace member (human) to ask \u2014 a user id from `list_members`."),
+            targetUserId: z12.string().uuid().describe(
+              "The workspace member (human) to ask \u2014 a user id, from your turn context's roster."
+            ),
             question: z12.string().min(1).max(400).optional().describe(
               "SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (capped, inline markdown only). Provide EITHER this or `questions`, not both. Put the crisp one-sentence question in `headline`."
             ),
@@ -6401,7 +6427,7 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
               "The sub-agent's opening instruction \u2014 self-contained (it starts with a fresh context window; only this prompt + the thread it lands in)."
             ),
             agentId: z12.string().uuid().optional().describe(
-              "Optional peer to run the sub-agent as (a workspace agent id from `list_agents`); omit to spawn yourself with a fresh context window."
+              "Optional peer to run the sub-agent as (a workspace agent id, from your turn context's roster); omit to spawn yourself with a fresh context window."
             ),
             title: z12.string().max(200).optional().describe("Optional title for the child thread (result chips link it).")
           },
@@ -7065,7 +7091,7 @@ function describeSubAgentError(status2, body) {
     case "callout_depth_exceeded":
       return "sub_agent: this would nest sub-agents too deep (max 3 levels). Have the current worker report back rather than spawning another layer.";
     case "dispatch_agent_not_found":
-      return "sub_agent: no live agent in this workspace matches that `agentId`. Check `list_agents`, or omit `agentId` to spawn yourself.";
+      return "sub_agent: no live agent in this workspace matches that `agentId`. Check the roster in your turn context, or omit `agentId` to spawn yourself.";
     case "dispatch_return_requires_turn":
     case "dispatch_return_requires_agent":
     case "dispatch_return_requires_dispatch":
@@ -7225,6 +7251,41 @@ var Dispatcher = class {
       if (cached2) {
         effectiveCwd = cached2.cwd;
         hookEnv = cached2.env;
+        if (prepareHook.validateCached) {
+          const runHook = this.opts.prepareHookRunner ?? runPrepareHook;
+          try {
+            await runHook(prepareHook, {
+              workspaceId,
+              conversationId: payload.conversationId,
+              agentId: payload.agentId,
+              agentUsername: this.opts.agentUsername,
+              runtime: turnContext.runtime,
+              triggerEntryPaths: turnContext.conversation.triggerEntryPaths ?? [],
+              title: turnContext.conversation.title,
+              messageBody: message.body,
+              prepared: cached2
+            });
+          } catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            turnLog.error({ err: reason }, "dispatcher: prepare hook rejected a prepared turn");
+            try {
+              await this.opts.api.postTurnMessage(workspaceId, payload.conversationId, {
+                body: `${PREPARE_FAILED_PREFIX}
+
+${reason}`,
+                kind: "final",
+                turnId,
+                parentMessageId: payload.messageId
+              });
+            } catch (postErr) {
+              turnLog.warn(
+                { err: postErr instanceof Error ? postErr.message : String(postErr) },
+                "dispatcher: prepare-rejection post failed"
+              );
+            }
+            return this.concludeBeforeRun(payload, turnLog, startedAt, `prepare_failed: ${reason}`);
+          }
+        }
       } else {
         const delayMs = this.opts.preparingRowDelayMs ?? DEFAULT_PREPARING_ROW_DELAY_MS;
         let preparingStarted = false;
@@ -7263,7 +7324,12 @@ var Dispatcher = class {
             // tasker prepare hook keys its per-task env off. Defaults to `[]` for
             // an older API. The conversation anchor is gone (CT319).
             triggerEntryPaths: turnContext.conversation.triggerEntryPaths ?? [],
-            title: turnContext.conversation.title
+            title: turnContext.conversation.title,
+            // CT943: the dispatching message's text — where an `env:` directive
+            // rides. The server has always sent the trigger body on the turn
+            // context (for the live feed); this is the first thing to read it as
+            // an INPUT, so a dispatch can ask for its environment in words.
+            messageBody: message.body
           });
           clearTimeout(preparingTimer);
           if (preparingStarted) reportPreparing("done");

package/dist/pairing-config.js

@@ -63,7 +63,20 @@ var prepareHookSchema = z.object({
   // Wall-clock cap for the hook. Provisioning is slow (minutes), so the
   // default is generous; a hook that hangs past this is killed and the turn
   // fails with a clear timeout message rather than pinning the companion.
-  timeoutMs: z.number().int().positive().optional()
+  timeoutMs: z.number().int().positive().optional(),
+  // CT943: re-invoke the hook on turns where a prepared result already exists,
+  // in VALIDATE mode — the cached result is handed back as `prepared` and the
+  // hook's stdout is ignored, so the cwd provably cannot move. Its only power
+  // is to exit non-zero and fail the turn.
+  //
+  // Why it exists: the hook runs exactly once per (conversation, agent), so a
+  // later message asking for a different environment can't be honoured. Without
+  // this, it is silently ignored — the host knows and says nothing, which is
+  // the worst available outcome. An opt-in hook can now refuse it out loud.
+  //
+  // Default OFF, and deliberately: an operator hook that provisions
+  // unconditionally must not start running on every turn because it upgraded.
+  validateCached: z.boolean().optional()
 }).strict();
 var DEFAULT_TIMEOUT_MS = 10 * 6e4;
 var prepareResultSchema = z.object({

package/dist/runtime.js

@@ -72,7 +72,20 @@ var prepareHookSchema = z.object({
   // Wall-clock cap for the hook. Provisioning is slow (minutes), so the
   // default is generous; a hook that hangs past this is killed and the turn
   // fails with a clear timeout message rather than pinning the companion.
-  timeoutMs: z.number().int().positive().optional()
+  timeoutMs: z.number().int().positive().optional(),
+  // CT943: re-invoke the hook on turns where a prepared result already exists,
+  // in VALIDATE mode — the cached result is handed back as `prepared` and the
+  // hook's stdout is ignored, so the cwd provably cannot move. Its only power
+  // is to exit non-zero and fail the turn.
+  //
+  // Why it exists: the hook runs exactly once per (conversation, agent), so a
+  // later message asking for a different environment can't be honoured. Without
+  // this, it is silently ignored — the host knows and says nothing, which is
+  // the worst available outcome. An opt-in hook can now refuse it out loud.
+  //
+  // Default OFF, and deliberately: an operator hook that provisions
+  // unconditionally must not start running on every turn because it upgraded.
+  validateCached: z.boolean().optional()
 }).strict();
 var DEFAULT_TIMEOUT_MS = 10 * 6e4;
 var prepareResultSchema = z.object({
@@ -136,7 +149,12 @@ var runPrepareHook = (hook, input) => {
           // CT317: newline-joined — workspace paths never contain a newline, so a
           // hook splits on `\n` unambiguously. Empty string when none.
           CABANE_TRIGGER_ENTRY_PATHS: input.triggerEntryPaths.join("\n"),
-          CABANE_CONVERSATION_TITLE: input.title ?? ""
+          CABANE_CONVERSATION_TITLE: input.title ?? "",
+          // CT943: the dispatching message's text, and — in validate mode only —
+          // the prepared result the hook is being asked to check this dispatch
+          // against. Both empty/absent on an ordinary first run.
+          CABANE_TRIGGER_MESSAGE: input.messageBody ?? "",
+          ...input.prepared ? { CABANE_PREPARED: JSON.stringify(input.prepared) } : {}
         }
       });
     } catch (err) {
@@ -174,6 +192,10 @@ var runPrepareHook = (hook, input) => {
           );
           return;
         }
+        if (input.prepared) {
+          resolve(input.prepared);
+          return;
+        }
         try {
           resolve(parsePrepareOutput(stdout));
         } catch (err) {
@@ -3510,7 +3532,7 @@ var OPENCODE_HOST_TOOLS = [
 var OPENCODE_WEB_TOOLS = ["webfetch"];
 var OPENCODE_SUBAGENT_TOOLS = ["task"];
 var OPENCODE_SCHEDULING_TOOLS = [];
-var OPENCODE_UI_PROMPT_TOOLS = [];
+var OPENCODE_UI_PROMPT_TOOLS = ["question"];
 function opencodeToolPolicy(policy) {
   const tools = {};
   const deny = (names) => {
@@ -5945,9 +5967,11 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
     tools: [
       tool(
         SUMMON_AGENT_TOOL,
-        "Summon another agent into THIS conversation \u2014 dispatch a peer to reply here on your turn. Use it to hand part of the work to a teammate, or pull in an expert, without leaving the conversation. Pass the peer's `agentId` (discover handles + ids via `list_agents`). The peer is dispatched on your turn's final reply, so write the context/ask into that reply first \u2014 it receives your message + this conversation to work from. Writing `@handle` in your prose does NOT summon anyone (agent prose never dispatches); this tool is the only in-thread lever. Single target \u2014 the last call wins. Summoning yourself is a no-op. Reach for it when the human wants the peer's answer right HERE, in front of them \u2014 the reply lands in this thread, so there's no return to wire (a return is for work YOU consume, never a courtesy notification). A handoff to a DIFFERENT conversation is `create_conversation` / `post_message` with their `dispatch` field instead.",
+        "Summon another agent into THIS conversation \u2014 dispatch a peer to reply here on your turn. Use it to hand part of the work to a teammate, or pull in an expert, without leaving the conversation. Pass the peer's `agentId` \u2014 every agent's handle and id is on the roster in your turn context. The peer is dispatched on your turn's final reply, so write the context/ask into that reply first \u2014 it receives your message + this conversation to work from. Writing `@handle` in your prose does NOT summon anyone (agent prose never dispatches); this tool is the only in-thread lever. Single target \u2014 the last call wins. Summoning yourself is a no-op. Reach for it when the human wants the peer's answer right HERE, in front of them \u2014 the reply lands in this thread, so there's no return to wire (a return is for work YOU consume, never a courtesy notification). A handoff to a DIFFERENT conversation is `cabane.conversations.create` / `cabane.conversations.post` with their `dispatch` field instead.",
         {
-          agentId: z12.string().uuid().describe("The peer agent to summon \u2014 a workspace agent id from `list_agents`.")
+          agentId: z12.string().uuid().describe(
+            "The peer agent to summon \u2014 a workspace agent id, from your turn context's roster."
+          )
         },
         async (args) => {
           summonState.agentId = args.agentId;
@@ -5977,9 +6001,11 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
       ...askState ? [
         tool(
           ASK_TOOL,
-          "Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass `targetUserId` (a workspace member's user id \u2014 get it from `mcp__cabane__list_members`). Two forms: a SINGLE question \u2014 a `headline` (the actual question as one clear, capitalized sentence ending in `?`, \"Do we go to prod?\") plus a short `question` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a `questions` array of 1\u20135 items, each `{ headline, body?, options? }`. **Prefer the list over cramming the extra decisions into prose or dropping them** \u2014 end the turn with one ask carrying every question, never pick one and bury the rest. Each question keeps the same form rules: a one-sentence `headline`, a short `body` frame (NOT a report \u2014 your status, links, and detail go in your REPLY, and the body renders inline markdown only: links/emphasis/inline code, no bulleted lists or headings), and 2\u20134 `options` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. An option can be a short button label or a whole sentence. Provide EITHER `question` (single) or `questions` (array), never both. The ask is a first-class attention item aimed at that person; your final reply carries the surrounding CONTEXT (what you found, why you're stuck), the ask carries the QUESTION(S). An open ask marks you as blocked until EVERY question is answered, so raise one only when you truly can't proceed \u2014 never ceremonially. One ask per turn (last call wins). After asking, stop \u2014 when the person replies addressed to you, the ask resolves and you resume; other people's or agents' messages may wake you but leave it open. Targets a human only; to hand work to another AGENT use summon/dispatch instead.",
+          "Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass `targetUserId` (a workspace member's user id \u2014 every person's id is on the roster in your turn context). Two forms: a SINGLE question \u2014 a `headline` (the actual question as one clear, capitalized sentence ending in `?`, \"Do we go to prod?\") plus a short `question` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a `questions` array of 1\u20135 items, each `{ headline, body?, options? }`. **Prefer the list over cramming the extra decisions into prose or dropping them** \u2014 end the turn with one ask carrying every question, never pick one and bury the rest. Each question keeps the same form rules: a one-sentence `headline`, a short `body` frame (NOT a report \u2014 your status, links, and detail go in your REPLY, and the body renders inline markdown only: links/emphasis/inline code, no bulleted lists or headings), and 2\u20134 `options` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. An option can be a short button label or a whole sentence. Provide EITHER `question` (single) or `questions` (array), never both. The ask is a first-class attention item aimed at that person; your final reply carries the surrounding CONTEXT (what you found, why you're stuck), the ask carries the QUESTION(S). An open ask marks you as blocked until EVERY question is answered, so raise one only when you truly can't proceed \u2014 never ceremonially. One ask per turn (last call wins). After asking, stop \u2014 when the person replies addressed to you, the ask resolves and you resume; other people's or agents' messages may wake you but leave it open. Targets a human only; to hand work to another AGENT use summon/dispatch instead.",
           {
-            targetUserId: z12.string().uuid().describe("The workspace member (human) to ask \u2014 a user id from `list_members`."),
+            targetUserId: z12.string().uuid().describe(
+              "The workspace member (human) to ask \u2014 a user id, from your turn context's roster."
+            ),
             question: z12.string().min(1).max(400).optional().describe(
               "SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (capped, inline markdown only). Provide EITHER this or `questions`, not both. Put the crisp one-sentence question in `headline`."
             ),
@@ -6054,7 +6080,7 @@ function createSummonMcpServer(summonState, skipState, askState, subAgentCreate,
               "The sub-agent's opening instruction \u2014 self-contained (it starts with a fresh context window; only this prompt + the thread it lands in)."
             ),
             agentId: z12.string().uuid().optional().describe(
-              "Optional peer to run the sub-agent as (a workspace agent id from `list_agents`); omit to spawn yourself with a fresh context window."
+              "Optional peer to run the sub-agent as (a workspace agent id, from your turn context's roster); omit to spawn yourself with a fresh context window."
             ),
             title: z12.string().max(200).optional().describe("Optional title for the child thread (result chips link it).")
           },
@@ -6718,7 +6744,7 @@ function describeSubAgentError(status, body) {
     case "callout_depth_exceeded":
       return "sub_agent: this would nest sub-agents too deep (max 3 levels). Have the current worker report back rather than spawning another layer.";
     case "dispatch_agent_not_found":
-      return "sub_agent: no live agent in this workspace matches that `agentId`. Check `list_agents`, or omit `agentId` to spawn yourself.";
+      return "sub_agent: no live agent in this workspace matches that `agentId`. Check the roster in your turn context, or omit `agentId` to spawn yourself.";
     case "dispatch_return_requires_turn":
     case "dispatch_return_requires_agent":
     case "dispatch_return_requires_dispatch":
@@ -6878,6 +6904,41 @@ var Dispatcher = class {
       if (cached2) {
         effectiveCwd = cached2.cwd;
         hookEnv = cached2.env;
+        if (prepareHook.validateCached) {
+          const runHook = this.opts.prepareHookRunner ?? runPrepareHook;
+          try {
+            await runHook(prepareHook, {
+              workspaceId,
+              conversationId: payload.conversationId,
+              agentId: payload.agentId,
+              agentUsername: this.opts.agentUsername,
+              runtime: turnContext.runtime,
+              triggerEntryPaths: turnContext.conversation.triggerEntryPaths ?? [],
+              title: turnContext.conversation.title,
+              messageBody: message.body,
+              prepared: cached2
+            });
+          } catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            turnLog.error({ err: reason }, "dispatcher: prepare hook rejected a prepared turn");
+            try {
+              await this.opts.api.postTurnMessage(workspaceId, payload.conversationId, {
+                body: `${PREPARE_FAILED_PREFIX}
+
+${reason}`,
+                kind: "final",
+                turnId,
+                parentMessageId: payload.messageId
+              });
+            } catch (postErr) {
+              turnLog.warn(
+                { err: postErr instanceof Error ? postErr.message : String(postErr) },
+                "dispatcher: prepare-rejection post failed"
+              );
+            }
+            return this.concludeBeforeRun(payload, turnLog, startedAt, `prepare_failed: ${reason}`);
+          }
+        }
       } else {
         const delayMs = this.opts.preparingRowDelayMs ?? DEFAULT_PREPARING_ROW_DELAY_MS;
         let preparingStarted = false;
@@ -6916,7 +6977,12 @@ var Dispatcher = class {
             // tasker prepare hook keys its per-task env off. Defaults to `[]` for
             // an older API. The conversation anchor is gone (CT319).
             triggerEntryPaths: turnContext.conversation.triggerEntryPaths ?? [],
-            title: turnContext.conversation.title
+            title: turnContext.conversation.title,
+            // CT943: the dispatching message's text — where an `env:` directive
+            // rides. The server has always sent the trigger body on the turn
+            // context (for the live feed); this is the first thing to read it as
+            // an INPUT, so a dispatch can ask for its environment in words.
+            messageBody: message.body
           });
           clearTimeout(preparingTimer);
           if (preparingStarted) reportPreparing("done");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "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",