@cabane/companion 0.6.218 → 0.6.220

package/dist/cli.js

@@ -1730,7 +1730,7 @@ var init_api = __esm({
           `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/turn-intent?${q}`
         );
       }
-      // Commit one outgoing act (ask, withdraw_ask, wake_me, cancel_wake) at
+      // Commit one outgoing act (open_exchange, withdraw_exchange, wake_me, cancel_wake) at
       // invocation. The server records the effect and receipt in one transaction;
       // an ok:false response is a recorded refusal for the tool to report.
       // Retries retain the caller's callId and recover the same receipt, even
@@ -2277,7 +2277,7 @@ var init_turn_request = __esm({
         bearer: z8.string(),
         activeConversationId: z8.string(),
         // Scoped turn-control MCP URL. Codex and opencode mount it as `cabane_companion` with the bearer
-        // and active-conversation header, for ask, withdraw_ask, wake_me, cancel_wake and skip_turn.
+        // and active-conversation header, for the turn-control tools (`TURN_CONTROL_TOOLS`).
         // Claude Code mounts the companion's in-process instance instead. Optional; the companion
         // populates it.
         turnControlUrl: z8.string().optional(),
@@ -2572,13 +2572,18 @@ var init_transcript_sink = __esm({
 });
 
 // packages/agent-runtime/src/turn-control/descriptions.ts
-var MAX_ASK_QUESTION_BYTES, MAX_ASK_HEADLINE_BYTES, MAX_ASK_ITEMS, MAX_ASK_OPTION_BYTES, ASK_OPTION_NOT_A_STRING, MIN_ASK_OPTIONS, MAX_ASK_OPTIONS, ASK_TARGET_PATTERN, ASK_TARGET_INVALID, MAX_WAKE_NOTE_BYTES, MAX_WITHDRAW_REASON_BYTES, MAX_SKIP_REASON_BYTES, TURN_CONTROL_MCP_SERVER, TURN_CONTROL_TOOLS, TURN_CONTROL_TOOL_DESCRIPTIONS, TURN_CONTROL_FIELD_DESCRIPTIONS;
+var MAX_ASK_QUESTION_BYTES, MAX_ASK_HEADLINE_BYTES, MAX_ASK_ITEMS, EXCHANGE_KINDS, APPROVAL_OPTIONS, REQUEST_OPTIONS, MAX_EXCHANGE_FILES, MAX_REQUEST_BODY_BYTES, MAX_ASK_OPTION_BYTES, ASK_OPTION_NOT_A_STRING, MIN_ASK_OPTIONS, MAX_ASK_OPTIONS, ASK_TARGET_PATTERN, ASK_TARGET_INVALID, MAX_WAKE_NOTE_BYTES, MAX_WITHDRAW_REASON_BYTES, MAX_SKIP_REASON_BYTES, TURN_CONTROL_MCP_SERVER, TURN_CONTROL_TOOLS, TURN_CONTROL_TOOL_DESCRIPTIONS, TURN_CONTROL_FIELD_DESCRIPTIONS;
 var init_descriptions = __esm({
   "packages/agent-runtime/src/turn-control/descriptions.ts"() {
     "use strict";
     MAX_ASK_QUESTION_BYTES = 400;
     MAX_ASK_HEADLINE_BYTES = 120;
     MAX_ASK_ITEMS = 20;
+    EXCHANGE_KINDS = ["question", "approval", "request"];
+    APPROVAL_OPTIONS = ["Yes", "No"];
+    REQUEST_OPTIONS = ["Done", "Couldn't"];
+    MAX_EXCHANGE_FILES = 5;
+    MAX_REQUEST_BODY_BYTES = 2e3;
     MAX_ASK_OPTION_BYTES = 200;
     ASK_OPTION_NOT_A_STRING = "An ask option is a plain string label.";
     MIN_ASK_OPTIONS = 2;
@@ -2591,41 +2596,44 @@ var init_descriptions = __esm({
     TURN_CONTROL_MCP_SERVER = "cabane_companion";
     TURN_CONTROL_TOOLS = [
       "answer",
-      "ask",
       "cancel_wake",
+      "open_exchange",
       "skip_turn",
       "wake_me",
-      "withdraw_ask"
+      "withdraw_exchange"
     ];
     TURN_CONTROL_TOOL_DESCRIPTIONS = {
       answer: `Call this just before you write your answer: the text you write next is what the conversation keeps as your message. Call it once.`,
-      ask: `Ask a person a structured question you need answered to continue, then end your turn; don't wait for the reply. \`targetUserId\` is a person on your roster, by their \`@handle\`; to bring in an agent, name them with \`@handle\` in your reply.
-- Form: one question (\`headline\`, optional \`question\` body, \`options\`) or \`questions\`, 1\u2013${MAX_ASK_ITEMS} \`{ headline, body?, options? }\`; never both. Decisions that arise together go in ONE call, in the order you want them answered. A second \`ask\` is a separate item, never an edit; raise one only for a genuinely new question.
-- \`headline\`: one sentence ending in \`?\`. Body (\`question\` or each item's \`body\`): a sentence or two of framing, not a report; inline Markdown only, no lists or headings. \`options\`: ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers (always for a yes/no go-ahead), each a distinct course of action you can carry out without asking back.
-- Voice, in headline, body and options: "I" for yourself, never your own name; name everyone else who decides or acts, as on your roster. Never "you", "your", "we", "us", "our" or their contractions, nor "he", "she" or "they" for a named actor. Each option reads correctly alone. A quotation stays accurate: say who said it.
-- It must stand alone, since it can arrive first: the reply carries the findings, the ask the question; don't repeat the reply in it.
-- Recorded when you call this; delivered when your turn ends, or after 3 minutes if it is still running. Ask as soon as you know. The answer reaches you on a later turn.
-- The person sends one response; unanswered questions end as Unanswered. A person can dismiss an ask; you aren't told and nothing wakes you. Check an ask's status before raising it again.
-- To replace a stale ask (yours or anyone's here), pass \`replaces: { askId, reason }\`: both land in one write and the person sees the reason. To withdraw without a replacement, use \`withdraw_ask\`.`,
+      open_exchange: `Put something in front of one person that comes back with a recorded outcome, then end your turn; don't wait for it. \`targetUserId\` is a person on your roster, by their \`@handle\`; to bring in an agent, name them with \`@handle\` in your reply.
+- \`kind\`: \`question\` for a choice among courses of action (two included) or free text; \`approval\` for a yes/no on one action you propose; \`request\` for something only the person can do, reported back.
+- A question is one item (\`headline\`, optional \`question\` body, \`options\`) or \`questions\`, 1\u2013${MAX_ASK_ITEMS} items; never both. An approval or request is \`headline\` and an optional \`question\` body only: its answers are fixed (${APPROVAL_OPTIONS.join(" / ")}; ${REQUEST_OPTIONS.join(" / ")}, output in the note or attachments). A request's body carries the steps and may hold a list and code blocks; every other body is a sentence or two of framing, inline Markdown only.
+- Decisions that arise together go in ONE call, in the order you want them answered. A second call is a separate exchange, never an edit.
+- Voice, in headline, body and options: "I" for yourself, never your own name; name everyone else who decides or acts, as on your roster. Never "you", "your", "we", "us", "our" or their contractions, nor "he", "she" or "they" for a named actor. A quotation stays accurate: say who said it.
+- It must stand alone, since it can arrive first: the reply carries the findings, the exchange the question; don't repeat the reply in it.
+- Recorded when you call this; delivered when your turn ends, or after 3 minutes if it is still running. Open it as soon as you know. The outcome reaches you on a later turn.
+- The person sends one response; unanswered items end as Unanswered. A person can dismiss an exchange; you aren't told and nothing wakes you. Check its status before raising it again.
+- To replace a stale exchange (yours or anyone's here), pass \`replaces: { askId, reason }\`: both land in one write and the person sees the reason. To withdraw without a replacement, use \`withdraw_exchange\`.`,
       cancel_wake: `Stand down the wake you have armed in this conversation, now, when you call it. No arguments. Use it when what the wake was to check has already happened or the work it watched is over; an unneeded wake fires into a turn with nothing to do. Your turn context prints the armed wake ("Wake armed: \u2026"); one no longer printed has fired or been dismissed. Nothing armed is a clean no-op. Calls act in order: \`cancel_wake\` then \`wake_me\` leaves the new wake armed. It reaches only your own wake here, never a peer's and never a recurring schedule (\`schedules.*\`).`,
       skip_turn: `End your current turn WITHOUT posting a reply. Call this when you've been woken to read a message that genuinely doesn't need a response from you \u2014 a thanks/aside, a question already answered, chatter outside your lane, or something another participant clearly owns. Your turn ends silently: no message bubble is posted. The \`reason\` is a short free-text note for telemetry (e.g. "already answered by cabane", "thanks, nothing to add"). Prefer this over posting a low-value "ok!"/"got it" reply. Don't also write a reply when you skip \u2014 skipping IS the whole turn.`,
-      wake_me: `Wake yourself later: end this turn now and be re-dispatched at a time you pick, with a note to yourself. Use it to wait for a condition you can name (a PR merging, a session limit resetting, an answer landing): arm, end the turn, and you're woken to CHECK and either act or re-arm. Most wakes are short, seconds to a couple of hours. Reach past a few hours only when a person asked for that timing or the wait is pinned to a real external event (a report that runs Mondays); if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it: finish now, or raise an \`ask\`. Pass EXACTLY ONE of \`afterSeconds\` (\`300\` for five minutes) or \`at\` (an ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\`, which YOU compute; nothing parses natural-language time). \`note\` becomes the body of the message that re-dispatches you: write the condition to re-check. The wake arms NOW, when you call this; a later \`wake_me\` in the same turn replaces it, \`cancel_wake\` stands it down, and one that comes due mid-turn is delivered after your reply. This is the ONLY way to schedule your own continuation; never a host cron or scheduler. Floor 60s, horizon 14 days, enforced here so you can recompute. Widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026); after many re-arms with no other activity you'll be steered to an \`ask\` instead.`,
-      withdraw_ask: `Withdraw an open ask \u2014 yours or anyone's in this conversation \u2014 because the question is moot, was wrong, or has been overtaken. \`reason\` is required and is shown to the person and, if it wasn't your ask, to the agent who asked it. If there is a current question to put in its place, don't call this \u2014 call \`ask\` with \`replaces\` so the two land as one and the person never sees neither or both. Never withdraw to hurry an answer; to act on a deadline, arm a \`wake_me\` and decide then.`
+      wake_me: `Wake yourself later: end this turn now and be re-dispatched at a time you pick, with a note to yourself. Use it to wait for a condition you can name (a PR merging, a session limit resetting, an answer landing): arm, end the turn, and you're woken to CHECK and either act or re-arm. Most wakes are short, seconds to a couple of hours. Reach past a few hours only when a person asked for that timing or the wait is pinned to a real external event (a report that runs Mondays); if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it: finish now, or open an exchange. Pass EXACTLY ONE of \`afterSeconds\` (\`300\` for five minutes) or \`at\` (an ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\`, which YOU compute; nothing parses natural-language time). \`note\` becomes the body of the message that re-dispatches you: write the condition to re-check. The wake arms NOW, when you call this; a later \`wake_me\` in the same turn replaces it, \`cancel_wake\` stands it down, and one that comes due mid-turn is delivered after your reply. This is the ONLY way to schedule your own continuation; never a host cron or scheduler. Floor 60s, horizon 14 days, enforced here so you can recompute. Widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026); after many re-arms with no other activity you'll be steered to an exchange instead.`,
+      withdraw_exchange: `Withdraw an open exchange \u2014 yours or anyone's in this conversation \u2014 because it is moot, was wrong, or has been overtaken. \`reason\` is required and is shown to the person and, if it wasn't yours, to the agent who opened it. If there is a current one to put in its place, don't call this \u2014 call \`open_exchange\` with \`replaces\` so the two land as one and the person never sees neither or both. Never withdraw to hurry an answer; to act on a deadline, arm a \`wake_me\` and decide then.`
     };
     TURN_CONTROL_FIELD_DESCRIPTIONS = {
       answer: {},
-      ask: {
-        targetUserId: "The person to ask: their `@handle` from your turn context's roster (preferred), or their user id.",
-        question: `SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only). Provide EITHER this or \`questions\`, not both. Put the crisp one-sentence question in \`headline\`.`,
-        headline: `SINGLE-question form: the question itself as ONE clear, capitalized sentence ending in \`?\` ("Should Ledger deploy once Mia approves?"), up to ${MAX_ASK_HEADLINE_BYTES} characters. What the person reads first in For you and on the chip \u2014 one scannable question, no elaboration (that goes in \`question\`). Strongly encouraged.`,
-        options: `SINGLE-question form: optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own.`,
-        questions: `MULTI-question form: 1\u2013${MAX_ASK_ITEMS} questions to ask at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
+      open_exchange: {
+        targetUserId: "The person: their `@handle` from your turn context's roster (preferred), or their user id.",
+        kind: `What the exchange is for; default \`question\`. \`question\`: the person picks among courses of action or types an answer. \`approval\`: a yes/no on one proposed action \u2014 the person answers ${APPROVAL_OPTIONS.join(" or ")}. \`request\`: something only the person can do \u2014 they report ${REQUEST_OPTIONS.join(" or ")}.`,
+        question: `The body beneath the headline \u2014 for a question or approval one or two sentences of framing, NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only); for a request the steps, with lists and code blocks allowed (up to ${MAX_REQUEST_BODY_BYTES} characters). With \`questions\`, leave it out.`,
+        headline: `ONE clear, capitalized sentence, up to ${MAX_ASK_HEADLINE_BYTES} characters: for a question or approval, the question ending in \`?\` ("Should Ledger deploy once Mia approves?"); for a request, what to do ("Run these and send me the output"). What the person reads first in For you. Required for an approval or request.`,
+        files: `1\u2013${MAX_EXCHANGE_FILES} workspace paths, drawn as file chips above the body; the person must be able to read each.`,
+        options: `A question's single form only: ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own. Refused on an approval or request.`,
+        questions: `A question only, MULTI form: 1\u2013${MAX_ASK_ITEMS} items at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
         "questions.headline": `The one-sentence question ("Should Ledger deploy once Mia approves?") \u2014 required for each item, up to ${MAX_ASK_HEADLINE_BYTES} characters.`,
         "questions.body": `Optional short framing beneath the headline, up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only. NOT a report.`,
         "questions.options": `Optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own.`,
-        replaces: "Withdraw a stale ask in this conversation as part of raising this one. Both land in a single write, so the person goes from the old question to the new one and never sees neither or both.",
-        "replaces.askId": "The id of the open ask to withdraw.",
-        "replaces.reason": `Why the old question is no longer the question \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
+        replaces: "Withdraw a stale exchange in this conversation as part of opening this one. Both land in a single write, so the person goes from the old one to the new one and never sees neither or both.",
+        "replaces.askId": "The id of the open exchange to withdraw.",
+        "replaces.reason": `Why the old one no longer stands \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
       },
       cancel_wake: {},
       skip_turn: {
@@ -2636,9 +2644,9 @@ var init_descriptions = __esm({
         at: "Absolute ISO-8601 timestamp WITH a zone (`Z` or `\xB1HH:MM`), e.g. `2026-07-16T09:00:00-07:00`. YOU compute it from a natural-language phrase using the current datetime in your turn context. Provide EITHER this or `afterSeconds`, not both.",
         note: `A note to your future self \u2014 becomes the body of the wake message that re-dispatches you, up to ${MAX_WAKE_NOTE_BYTES} characters. Write the condition to re-check in a sentence or two ("check whether the PR merged"), not a plan. You never need to name yourself: the wake reaches you on its own.`
       },
-      withdraw_ask: {
-        askId: "The open ask to withdraw. Ask ids ride the conversation's message rows (`ask: { id, status, items }`), and your turn context lists the ones you have open.",
-        reason: `Why this question is no longer the question ("merged via GitHub #1551"). Required, and shown to the person on their Done row \u2014 a bare "withdrawn" tells them nothing. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
+      withdraw_exchange: {
+        askId: "The open exchange to withdraw. Its id rides the conversation's message rows (`ask: { id, status, items }`), and your turn context lists the ones open here.",
+        reason: `Why it no longer stands ("merged via GitHub #1551"). Required, and shown to the person on their Done row \u2014 a bare "withdrawn" tells them nothing. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
       }
     };
   }
@@ -2820,11 +2828,11 @@ var init_prompt_guidance = __esm({
     init_descriptions();
     MEANINGS = {
       answer: "declare the text you write next as your answer",
-      ask: "put a structured question to a person",
+      open_exchange: "put a question, go-ahead or request to a person",
       cancel_wake: "cancel your own armed wake in this conversation",
       skip_turn: "end without posting a reply",
       wake_me: "schedule your own return; when it fires, say what you came back to check",
-      withdraw_ask: "withdraw an open ask in this conversation with a reason"
+      withdraw_exchange: "withdraw an open exchange in this conversation with a reason"
     };
   }
 });
@@ -6224,37 +6232,57 @@ function createTurnControlMcpServer(acts, skipState) {
         )
       ] : [],
       tool(
-        ASK_TOOL,
-        TURN_CONTROL_TOOL_DESCRIPTIONS.ask,
+        OPEN_EXCHANGE_TOOL,
+        TURN_CONTROL_TOOL_DESCRIPTIONS.open_exchange,
         {
-          targetUserId: z15.string().regex(ASK_TARGET_PATTERN, { error: ASK_TARGET_INVALID }).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.targetUserId),
-          question: z15.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.question),
-          headline: z15.string().min(1).max(MAX_ASK_HEADLINE_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.headline),
-          options: z15.array(z15.string({ error: ASK_OPTION_NOT_A_STRING }).min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.options),
+          targetUserId: z15.string().regex(ASK_TARGET_PATTERN, { error: ASK_TARGET_INVALID }).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.targetUserId),
+          kind: z15.enum(EXCHANGE_KINDS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.kind),
+          // The request's cap; the server holds every other kind to its own.
+          question: z15.string().min(1).max(MAX_REQUEST_BODY_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.question),
+          headline: z15.string().min(1).max(MAX_ASK_HEADLINE_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.headline),
+          options: z15.array(z15.string({ error: ASK_OPTION_NOT_A_STRING }).min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.options),
           questions: z15.array(
             z15.object({
-              headline: z15.string().min(1).max(MAX_ASK_HEADLINE_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.headline"]),
-              body: z15.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.body"]),
+              headline: z15.string().min(1).max(MAX_ASK_HEADLINE_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange["questions.headline"]),
+              body: z15.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange["questions.body"]),
               options: z15.array(
                 z15.string({ error: ASK_OPTION_NOT_A_STRING }).min(1).max(MAX_ASK_OPTION_BYTES)
-              ).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.options"])
+              ).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange["questions.options"])
             })
-          ).min(1).max(MAX_ASK_ITEMS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.questions),
+          ).min(1).max(MAX_ASK_ITEMS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.questions),
+          files: z15.array(z15.string().min(1).max(1024)).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.files),
           replaces: z15.object({
-            askId: z15.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["replaces.askId"]),
-            reason: z15.string().min(1).max(MAX_WITHDRAW_REASON_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["replaces.reason"])
-          }).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.replaces)
+            askId: z15.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange["replaces.askId"]),
+            reason: z15.string().min(1).max(MAX_WITHDRAW_REASON_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange["replaces.reason"])
+          }).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.open_exchange.replaces)
         },
         async (args) => {
+          const kind = args.kind ?? "question";
           const hasSingle = args.question !== void 0;
           const hasArray = args.questions !== void 0 && args.questions.length > 0;
+          if (kind !== "question") {
+            return performAct(acts, {
+              kind: "ask",
+              callId: randomUUID3(),
+              ...args.replaces ? { replaces: args.replaces } : {},
+              ask: {
+                targetUserId: args.targetUserId,
+                kind,
+                ...args.headline ? { headline: args.headline } : {},
+                ...args.question ? { question: args.question } : {},
+                ...args.options ? { options: args.options } : {},
+                ...args.questions ? { questions: args.questions } : {},
+                ...args.files ? { files: args.files } : {}
+              }
+            });
+          }
           if (hasSingle && hasArray) {
             return toolError(
               "Provide either `question` (single) or `questions` (array), not both."
             );
           }
-          if (!hasSingle && !hasArray) {
-            return toolError("Provide `question` (single) or `questions` (array).");
+          if (!hasSingle && !hasArray && args.headline === void 0) {
+            return toolError("Provide `headline` (single) or `questions` (array).");
           }
           return performAct(acts, {
             kind: "ask",
@@ -6268,12 +6296,14 @@ function createTurnControlMcpServer(acts, skipState) {
                 headline: q.headline,
                 ...q.body ? { body: q.body } : {},
                 ...q.options && q.options.length > 0 ? { options: q.options } : {}
-              }))
+              })),
+              ...args.files ? { files: args.files } : {}
             } : {
               targetUserId: args.targetUserId,
-              question: args.question,
+              ...args.question ? { question: args.question } : {},
               ...args.headline ? { headline: args.headline } : {},
-              ...args.options && args.options.length > 0 ? { options: args.options } : {}
+              ...args.options && args.options.length > 0 ? { options: args.options } : {},
+              ...args.files ? { files: args.files } : {}
             }
           });
         },
@@ -6316,11 +6346,11 @@ function createTurnControlMcpServer(acts, skipState) {
       // reasoning). Not idempotent either: a second call with the same id is
       // refused with `ask_not_open`, which is information, not a no-op.
       tool(
-        WITHDRAW_ASK_TOOL,
-        TURN_CONTROL_TOOL_DESCRIPTIONS.withdraw_ask,
+        WITHDRAW_EXCHANGE_TOOL,
+        TURN_CONTROL_TOOL_DESCRIPTIONS.withdraw_exchange,
         {
-          askId: z15.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.withdraw_ask.askId),
-          reason: z15.string().min(1).max(MAX_WITHDRAW_REASON_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.withdraw_ask.reason)
+          askId: z15.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.withdraw_exchange.askId),
+          reason: z15.string().min(1).max(MAX_WITHDRAW_REASON_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.withdraw_exchange.reason)
         },
         async (args) => performAct(acts, {
           kind: "withdraw_ask",
@@ -6348,7 +6378,7 @@ function createTurnControlMcpServer(acts, skipState) {
     ]
   });
 }
-var COMPANION_LOCAL_MCP_SERVER, COMPANION_LOCAL_TOOL_GLOB, SKIP_TURN_TOOL, ASK_TOOL, ASK_TOOL_NAME, WITHDRAW_ASK_TOOL, WITHDRAW_ASK_TOOL_NAME, ANSWER_TOOL2, WAKE_ME_TOOL, WAKE_ME_TOOL_NAME, CANCEL_WAKE_TOOL, CANCEL_WAKE_TOOL_NAME, TURN_ACT_TIMEOUT_MS;
+var COMPANION_LOCAL_MCP_SERVER, COMPANION_LOCAL_TOOL_GLOB, SKIP_TURN_TOOL, OPEN_EXCHANGE_TOOL, OPEN_EXCHANGE_TOOL_NAME, WITHDRAW_EXCHANGE_TOOL, WITHDRAW_EXCHANGE_TOOL_NAME, ANSWER_TOOL2, WAKE_ME_TOOL, WAKE_ME_TOOL_NAME, CANCEL_WAKE_TOOL, CANCEL_WAKE_TOOL_NAME, TURN_ACT_TIMEOUT_MS;
 var init_turn_control_tools = __esm({
   "src/turn-control-tools.ts"() {
     "use strict";
@@ -6359,10 +6389,10 @@ var init_turn_control_tools = __esm({
     COMPANION_LOCAL_MCP_SERVER = TURN_CONTROL_MCP_SERVER;
     COMPANION_LOCAL_TOOL_GLOB = `mcp__${COMPANION_LOCAL_MCP_SERVER}__*`;
     SKIP_TURN_TOOL = "skip_turn";
-    ASK_TOOL = "ask";
-    ASK_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${ASK_TOOL}`;
-    WITHDRAW_ASK_TOOL = "withdraw_ask";
-    WITHDRAW_ASK_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WITHDRAW_ASK_TOOL}`;
+    OPEN_EXCHANGE_TOOL = "open_exchange";
+    OPEN_EXCHANGE_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${OPEN_EXCHANGE_TOOL}`;
+    WITHDRAW_EXCHANGE_TOOL = "withdraw_exchange";
+    WITHDRAW_EXCHANGE_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WITHDRAW_EXCHANGE_TOOL}`;
     ANSWER_TOOL2 = "answer";
     WAKE_ME_TOOL = "wake_me";
     WAKE_ME_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WAKE_ME_TOOL}`;

package/dist/runtime.js

@@ -1932,7 +1932,7 @@ var CabaneApi = class {
       `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/turn-intent?${q}`
     );
   }
-  // Commit one outgoing act (ask, withdraw_ask, wake_me, cancel_wake) at
+  // Commit one outgoing act (open_exchange, withdraw_exchange, wake_me, cancel_wake) at
   // invocation. The server records the effect and receipt in one transaction;
   // an ok:false response is a recorded refusal for the tool to report.
   // Retries retain the caller's callId and recover the same receipt, even
@@ -2751,7 +2751,7 @@ var turnRequestSchema = z8.object({
     bearer: z8.string(),
     activeConversationId: z8.string(),
     // Scoped turn-control MCP URL. Codex and opencode mount it as `cabane_companion` with the bearer
-    // and active-conversation header, for ask, withdraw_ask, wake_me, cancel_wake and skip_turn.
+    // and active-conversation header, for the turn-control tools (`TURN_CONTROL_TOOLS`).
     // Claude Code mounts the companion's in-process instance instead. Optional; the companion
     // populates it.
     turnControlUrl: z8.string().optional(),
@@ -2937,6 +2937,10 @@ function truncate(s, max) {
 var MAX_ASK_QUESTION_BYTES = 400;
 var MAX_ASK_HEADLINE_BYTES = 120;
 var MAX_ASK_ITEMS = 20;
+var APPROVAL_OPTIONS = ["Yes", "No"];
+var REQUEST_OPTIONS = ["Done", "Couldn't"];
+var MAX_EXCHANGE_FILES = 5;
+var MAX_REQUEST_BODY_BYTES = 2e3;
 var MAX_ASK_OPTION_BYTES = 200;
 var MIN_ASK_OPTIONS = 2;
 var MAX_ASK_OPTIONS = 4;
@@ -2946,41 +2950,44 @@ var MAX_SKIP_REASON_BYTES = 500;
 var TURN_CONTROL_MCP_SERVER = "cabane_companion";
 var TURN_CONTROL_TOOLS = [
   "answer",
-  "ask",
   "cancel_wake",
+  "open_exchange",
   "skip_turn",
   "wake_me",
-  "withdraw_ask"
+  "withdraw_exchange"
 ];
 var TURN_CONTROL_TOOL_DESCRIPTIONS = {
   answer: `Call this just before you write your answer: the text you write next is what the conversation keeps as your message. Call it once.`,
-  ask: `Ask a person a structured question you need answered to continue, then end your turn; don't wait for the reply. \`targetUserId\` is a person on your roster, by their \`@handle\`; to bring in an agent, name them with \`@handle\` in your reply.
-- Form: one question (\`headline\`, optional \`question\` body, \`options\`) or \`questions\`, 1\u2013${MAX_ASK_ITEMS} \`{ headline, body?, options? }\`; never both. Decisions that arise together go in ONE call, in the order you want them answered. A second \`ask\` is a separate item, never an edit; raise one only for a genuinely new question.
-- \`headline\`: one sentence ending in \`?\`. Body (\`question\` or each item's \`body\`): a sentence or two of framing, not a report; inline Markdown only, no lists or headings. \`options\`: ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers (always for a yes/no go-ahead), each a distinct course of action you can carry out without asking back.
-- Voice, in headline, body and options: "I" for yourself, never your own name; name everyone else who decides or acts, as on your roster. Never "you", "your", "we", "us", "our" or their contractions, nor "he", "she" or "they" for a named actor. Each option reads correctly alone. A quotation stays accurate: say who said it.
-- It must stand alone, since it can arrive first: the reply carries the findings, the ask the question; don't repeat the reply in it.
-- Recorded when you call this; delivered when your turn ends, or after 3 minutes if it is still running. Ask as soon as you know. The answer reaches you on a later turn.
-- The person sends one response; unanswered questions end as Unanswered. A person can dismiss an ask; you aren't told and nothing wakes you. Check an ask's status before raising it again.
-- To replace a stale ask (yours or anyone's here), pass \`replaces: { askId, reason }\`: both land in one write and the person sees the reason. To withdraw without a replacement, use \`withdraw_ask\`.`,
+  open_exchange: `Put something in front of one person that comes back with a recorded outcome, then end your turn; don't wait for it. \`targetUserId\` is a person on your roster, by their \`@handle\`; to bring in an agent, name them with \`@handle\` in your reply.
+- \`kind\`: \`question\` for a choice among courses of action (two included) or free text; \`approval\` for a yes/no on one action you propose; \`request\` for something only the person can do, reported back.
+- A question is one item (\`headline\`, optional \`question\` body, \`options\`) or \`questions\`, 1\u2013${MAX_ASK_ITEMS} items; never both. An approval or request is \`headline\` and an optional \`question\` body only: its answers are fixed (${APPROVAL_OPTIONS.join(" / ")}; ${REQUEST_OPTIONS.join(" / ")}, output in the note or attachments). A request's body carries the steps and may hold a list and code blocks; every other body is a sentence or two of framing, inline Markdown only.
+- Decisions that arise together go in ONE call, in the order you want them answered. A second call is a separate exchange, never an edit.
+- Voice, in headline, body and options: "I" for yourself, never your own name; name everyone else who decides or acts, as on your roster. Never "you", "your", "we", "us", "our" or their contractions, nor "he", "she" or "they" for a named actor. A quotation stays accurate: say who said it.
+- It must stand alone, since it can arrive first: the reply carries the findings, the exchange the question; don't repeat the reply in it.
+- Recorded when you call this; delivered when your turn ends, or after 3 minutes if it is still running. Open it as soon as you know. The outcome reaches you on a later turn.
+- The person sends one response; unanswered items end as Unanswered. A person can dismiss an exchange; you aren't told and nothing wakes you. Check its status before raising it again.
+- To replace a stale exchange (yours or anyone's here), pass \`replaces: { askId, reason }\`: both land in one write and the person sees the reason. To withdraw without a replacement, use \`withdraw_exchange\`.`,
   cancel_wake: `Stand down the wake you have armed in this conversation, now, when you call it. No arguments. Use it when what the wake was to check has already happened or the work it watched is over; an unneeded wake fires into a turn with nothing to do. Your turn context prints the armed wake ("Wake armed: \u2026"); one no longer printed has fired or been dismissed. Nothing armed is a clean no-op. Calls act in order: \`cancel_wake\` then \`wake_me\` leaves the new wake armed. It reaches only your own wake here, never a peer's and never a recurring schedule (\`schedules.*\`).`,
   skip_turn: `End your current turn WITHOUT posting a reply. Call this when you've been woken to read a message that genuinely doesn't need a response from you \u2014 a thanks/aside, a question already answered, chatter outside your lane, or something another participant clearly owns. Your turn ends silently: no message bubble is posted. The \`reason\` is a short free-text note for telemetry (e.g. "already answered by cabane", "thanks, nothing to add"). Prefer this over posting a low-value "ok!"/"got it" reply. Don't also write a reply when you skip \u2014 skipping IS the whole turn.`,
-  wake_me: `Wake yourself later: end this turn now and be re-dispatched at a time you pick, with a note to yourself. Use it to wait for a condition you can name (a PR merging, a session limit resetting, an answer landing): arm, end the turn, and you're woken to CHECK and either act or re-arm. Most wakes are short, seconds to a couple of hours. Reach past a few hours only when a person asked for that timing or the wait is pinned to a real external event (a report that runs Mondays); if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it: finish now, or raise an \`ask\`. Pass EXACTLY ONE of \`afterSeconds\` (\`300\` for five minutes) or \`at\` (an ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\`, which YOU compute; nothing parses natural-language time). \`note\` becomes the body of the message that re-dispatches you: write the condition to re-check. The wake arms NOW, when you call this; a later \`wake_me\` in the same turn replaces it, \`cancel_wake\` stands it down, and one that comes due mid-turn is delivered after your reply. This is the ONLY way to schedule your own continuation; never a host cron or scheduler. Floor 60s, horizon 14 days, enforced here so you can recompute. Widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026); after many re-arms with no other activity you'll be steered to an \`ask\` instead.`,
-  withdraw_ask: `Withdraw an open ask \u2014 yours or anyone's in this conversation \u2014 because the question is moot, was wrong, or has been overtaken. \`reason\` is required and is shown to the person and, if it wasn't your ask, to the agent who asked it. If there is a current question to put in its place, don't call this \u2014 call \`ask\` with \`replaces\` so the two land as one and the person never sees neither or both. Never withdraw to hurry an answer; to act on a deadline, arm a \`wake_me\` and decide then.`
+  wake_me: `Wake yourself later: end this turn now and be re-dispatched at a time you pick, with a note to yourself. Use it to wait for a condition you can name (a PR merging, a session limit resetting, an answer landing): arm, end the turn, and you're woken to CHECK and either act or re-arm. Most wakes are short, seconds to a couple of hours. Reach past a few hours only when a person asked for that timing or the wait is pinned to a real external event (a report that runs Mondays); if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it: finish now, or open an exchange. Pass EXACTLY ONE of \`afterSeconds\` (\`300\` for five minutes) or \`at\` (an ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\`, which YOU compute; nothing parses natural-language time). \`note\` becomes the body of the message that re-dispatches you: write the condition to re-check. The wake arms NOW, when you call this; a later \`wake_me\` in the same turn replaces it, \`cancel_wake\` stands it down, and one that comes due mid-turn is delivered after your reply. This is the ONLY way to schedule your own continuation; never a host cron or scheduler. Floor 60s, horizon 14 days, enforced here so you can recompute. Widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026); after many re-arms with no other activity you'll be steered to an exchange instead.`,
+  withdraw_exchange: `Withdraw an open exchange \u2014 yours or anyone's in this conversation \u2014 because it is moot, was wrong, or has been overtaken. \`reason\` is required and is shown to the person and, if it wasn't yours, to the agent who opened it. If there is a current one to put in its place, don't call this \u2014 call \`open_exchange\` with \`replaces\` so the two land as one and the person never sees neither or both. Never withdraw to hurry an answer; to act on a deadline, arm a \`wake_me\` and decide then.`
 };
 var TURN_CONTROL_FIELD_DESCRIPTIONS = {
   answer: {},
-  ask: {
-    targetUserId: "The person to ask: their `@handle` from your turn context's roster (preferred), or their user id.",
-    question: `SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only). Provide EITHER this or \`questions\`, not both. Put the crisp one-sentence question in \`headline\`.`,
-    headline: `SINGLE-question form: the question itself as ONE clear, capitalized sentence ending in \`?\` ("Should Ledger deploy once Mia approves?"), up to ${MAX_ASK_HEADLINE_BYTES} characters. What the person reads first in For you and on the chip \u2014 one scannable question, no elaboration (that goes in \`question\`). Strongly encouraged.`,
-    options: `SINGLE-question form: optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own.`,
-    questions: `MULTI-question form: 1\u2013${MAX_ASK_ITEMS} questions to ask at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
+  open_exchange: {
+    targetUserId: "The person: their `@handle` from your turn context's roster (preferred), or their user id.",
+    kind: `What the exchange is for; default \`question\`. \`question\`: the person picks among courses of action or types an answer. \`approval\`: a yes/no on one proposed action \u2014 the person answers ${APPROVAL_OPTIONS.join(" or ")}. \`request\`: something only the person can do \u2014 they report ${REQUEST_OPTIONS.join(" or ")}.`,
+    question: `The body beneath the headline \u2014 for a question or approval one or two sentences of framing, NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only); for a request the steps, with lists and code blocks allowed (up to ${MAX_REQUEST_BODY_BYTES} characters). With \`questions\`, leave it out.`,
+    headline: `ONE clear, capitalized sentence, up to ${MAX_ASK_HEADLINE_BYTES} characters: for a question or approval, the question ending in \`?\` ("Should Ledger deploy once Mia approves?"); for a request, what to do ("Run these and send me the output"). What the person reads first in For you. Required for an approval or request.`,
+    files: `1\u2013${MAX_EXCHANGE_FILES} workspace paths, drawn as file chips above the body; the person must be able to read each.`,
+    options: `A question's single form only: ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own. Refused on an approval or request.`,
+    questions: `A question only, MULTI form: 1\u2013${MAX_ASK_ITEMS} items at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
     "questions.headline": `The one-sentence question ("Should Ledger deploy once Mia approves?") \u2014 required for each item, up to ${MAX_ASK_HEADLINE_BYTES} characters.`,
     "questions.body": `Optional short framing beneath the headline, up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only. NOT a report.`,
     "questions.options": `Optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each. Each option must make sense on its own.`,
-    replaces: "Withdraw a stale ask in this conversation as part of raising this one. Both land in a single write, so the person goes from the old question to the new one and never sees neither or both.",
-    "replaces.askId": "The id of the open ask to withdraw.",
-    "replaces.reason": `Why the old question is no longer the question \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
+    replaces: "Withdraw a stale exchange in this conversation as part of opening this one. Both land in a single write, so the person goes from the old one to the new one and never sees neither or both.",
+    "replaces.askId": "The id of the open exchange to withdraw.",
+    "replaces.reason": `Why the old one no longer stands \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
   },
   cancel_wake: {},
   skip_turn: {
@@ -2991,9 +2998,9 @@ var TURN_CONTROL_FIELD_DESCRIPTIONS = {
     at: "Absolute ISO-8601 timestamp WITH a zone (`Z` or `\xB1HH:MM`), e.g. `2026-07-16T09:00:00-07:00`. YOU compute it from a natural-language phrase using the current datetime in your turn context. Provide EITHER this or `afterSeconds`, not both.",
     note: `A note to your future self \u2014 becomes the body of the wake message that re-dispatches you, up to ${MAX_WAKE_NOTE_BYTES} characters. Write the condition to re-check in a sentence or two ("check whether the PR merged"), not a plan. You never need to name yourself: the wake reaches you on its own.`
   },
-  withdraw_ask: {
-    askId: "The open ask to withdraw. Ask ids ride the conversation's message rows (`ask: { id, status, items }`), and your turn context lists the ones you have open.",
-    reason: `Why this question is no longer the question ("merged via GitHub #1551"). Required, and shown to the person on their Done row \u2014 a bare "withdrawn" tells them nothing. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
+  withdraw_exchange: {
+    askId: "The open exchange to withdraw. Its id rides the conversation's message rows (`ask: { id, status, items }`), and your turn context lists the ones open here.",
+    reason: `Why it no longer stands ("merged via GitHub #1551"). Required, and shown to the person on their Done row \u2014 a bare "withdrawn" tells them nothing. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
   }
 };
 
@@ -3005,11 +3012,11 @@ import {
 // packages/agent-runtime/src/turn-control/prompt-guidance.ts
 var MEANINGS = {
   answer: "declare the text you write next as your answer",
-  ask: "put a structured question to a person",
+  open_exchange: "put a question, go-ahead or request to a person",
   cancel_wake: "cancel your own armed wake in this conversation",
   skip_turn: "end without posting a reply",
   wake_me: "schedule your own return; when it fires, say what you came back to check",
-  withdraw_ask: "withdraw an open ask in this conversation with a reason"
+  withdraw_exchange: "withdraw an open exchange in this conversation with a reason"
 };
 function turnControlPromptGuidance(prefix) {
   const controls = TURN_CONTROL_TOOLS.map((name) => `\`${prefix}${name}\` (${MEANINGS[name]})`);
@@ -6116,10 +6123,10 @@ import { randomUUID as randomUUID3 } from "crypto";
 import { z as z15 } from "zod";
 var COMPANION_LOCAL_MCP_SERVER = TURN_CONTROL_MCP_SERVER;
 var COMPANION_LOCAL_TOOL_GLOB = `mcp__${COMPANION_LOCAL_MCP_SERVER}__*`;
-var ASK_TOOL = "ask";
-var ASK_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${ASK_TOOL}`;
-var WITHDRAW_ASK_TOOL = "withdraw_ask";
-var WITHDRAW_ASK_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WITHDRAW_ASK_TOOL}`;
+var OPEN_EXCHANGE_TOOL = "open_exchange";
+var OPEN_EXCHANGE_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${OPEN_EXCHANGE_TOOL}`;
+var WITHDRAW_EXCHANGE_TOOL = "withdraw_exchange";
+var WITHDRAW_EXCHANGE_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WITHDRAW_EXCHANGE_TOOL}`;
 var WAKE_ME_TOOL = "wake_me";
 var WAKE_ME_TOOL_NAME = `mcp__${COMPANION_LOCAL_MCP_SERVER}__${WAKE_ME_TOOL}`;
 var CANCEL_WAKE_TOOL = "cancel_wake";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.218",
+  "version": "0.6.220",
   "type": "module",
   "description": "The Cabane Companion (headless): connect an 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",