discoclaw 0.5.6 → 0.5.7

package/.context/voice.md

@@ -28,6 +28,7 @@ Two native npm packages power the Discord voice integration:
 | `src/voice/presence-handler.ts` | Auto-join/leave on `voiceStateUpdate` (allowlisted users only) |
 | `src/voice/transcript-mirror.ts` | Posts user transcriptions and bot responses to a text channel |
 | `src/voice/voice-action-flags.ts` | Restricted action subset for voice invocations (messaging + tasks + memory only) |
+| `src/voice/conversation-buffer.ts` | Per-guild conversation ring buffer (10 turns) — stores user/model exchanges in memory; backfills from voice-log channel on join |
 | `src/discord/actions-voice.ts` | Discord action types: `voiceJoin`, `voiceLeave`, `voiceStatus`, `voiceMute`, `voiceDeafen` |
 
 ## Audio Data Flow
@@ -52,6 +53,7 @@ User speaks in Discord voice channel
 - **Dual-flag voice actions** — Voice action execution requires both `VOICE_ENABLED` and `DISCORD_ACTIONS_VOICE`. The `buildVoiceActionFlags()` function intersects a voice-specific allowlist (messaging, tasks, memory) with env config; all other action categories are hard-disabled.
 - **Generation-based cancellation** — `VoiceResponder` increments a generation counter on each new transcription. If a newer transcription arrives mid-pipeline, the older one is silently abandoned.
 - **Barge-in** — Gated on a non-empty STT transcription result, not the raw VAD `speaking.start` event. Echo from the bot's own TTS leaking through the user's mic produces empty transcriptions and is ignored. Only when `VoiceResponder.handleTranscription()` receives a non-empty transcript while the player is active does it stop playback and advance the generation counter. This eliminates false positives from echo without relying on a static grace-period timeout.
+- **Conversation ring buffer** — `ConversationBuffer` maintains a per-guild 10-turn ring buffer of user/model exchanges that gets injected into the voice prompt as formatted conversation history. Turns are appended live during a session. On voice join, the buffer backfills from recent voice-log channel messages so context carries across disconnects. The buffer is cleared when the bot leaves the voice channel.
 - **Re-entrancy guard** — `AudioPipelineManager.startPipeline` uses a `starting` set because `VoiceConnection.subscribe()` synchronously fires a Ready state change.
 - **Error containment** — `VoiceConnectionManager` catches connection errors and destroys the connection to prevent process crashes (e.g. DAVE handshake failures).
 - **Deepgram TTS 2000-char limit** — Deepgram Aura REST TTS returns HTTP 413 (silent failure) for inputs exceeding ~2000 characters. `tts-deepgram.ts` truncates the input to 2000 chars before sending to prevent silent audio dropouts. If the AI response is unexpectedly long (e.g. from a missing `VOICE_STYLE_INSTRUCTION`), the user will still hear a truncated response rather than silence.

package/.env.example

@@ -74,10 +74,13 @@ DISCORD_GUILD_ID=
 # is the security boundary instead.
 #CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1
 
-# Gemini CLI adapter
-# Path to the Gemini CLI binary (default: gemini).
+# Gemini adapter
+# When GEMINI_API_KEY is set, the REST API adapter is used (zero startup overhead).
+# When unset, falls back to the Gemini CLI binary (requires `gemini` in PATH).
+#GEMINI_API_KEY=
+# Path to the Gemini CLI binary (default: gemini). Only used when GEMINI_API_KEY is unset.
 #GEMINI_BIN=gemini
-# Default model for the Gemini CLI adapter.
+# Default model for the Gemini adapter.
 #GEMINI_MODEL=gemini-2.5-pro
 
 # --- OpenAI-compatible HTTP adapter ---

package/.env.example.full

@@ -98,10 +98,13 @@ DISCORD_ALLOW_USER_IDS=
 # is the security boundary instead.
 #CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1
 
-# --- Gemini CLI adapter ---
-# Path to the Gemini CLI binary (default: gemini).
+# --- Gemini adapter ---
+# When GEMINI_API_KEY is set, the REST API adapter is used (zero startup overhead).
+# When unset, falls back to the Gemini CLI binary (requires `gemini` in PATH).
+#GEMINI_API_KEY=
+# Path to the Gemini CLI binary (default: gemini). Only used when GEMINI_API_KEY is unset.
 #GEMINI_BIN=gemini
-# Default model for the Gemini CLI adapter.
+# Default model for the Gemini adapter.
 #GEMINI_MODEL=gemini-2.5-pro
 
 # Log level: trace | debug | info | warn | error | fatal

package/dist/config.js

@@ -285,7 +285,7 @@ export function parseConfig(env) {
         warnings.push('DISCOCLAW_VOICE_ENABLED=1 with TTS provider "openai" but OPENAI_API_KEY is not set; voice TTS will fail at runtime.');
     }
     if (voiceEnabled && !voiceHomeChannel) {
-        warnings.push('DISCOCLAW_VOICE_ENABLED=1 but DISCOCLAW_VOICE_HOME_CHANNEL is not set; voice will run without channel context, durable memory, and actions.');
+        warnings.push('DISCOCLAW_VOICE_ENABLED=1 but DISCOCLAW_VOICE_HOME_CHANNEL is not set; voice actions will be disabled (no target channel for action execution).');
     }
     const openrouterApiKey = parseTrimmedString(env, 'OPENROUTER_API_KEY');
     const openrouterBaseUrl = parseTrimmedString(env, 'OPENROUTER_BASE_URL');
@@ -423,6 +423,7 @@ export function parseConfig(env) {
             openrouterApiKey,
             openrouterBaseUrl,
             openrouterModel,
+            geminiApiKey: parseTrimmedString(env, 'GEMINI_API_KEY'),
             geminiBin: parseTrimmedString(env, 'GEMINI_BIN') ?? 'gemini',
             geminiModel: parseTrimmedString(env, 'GEMINI_MODEL') ?? 'gemini-2.5-pro',
             codexBin: parseTrimmedString(env, 'CODEX_BIN') ?? 'codex',

package/dist/discord/actions-config.js

@@ -1,4 +1,4 @@
-import { resolveModel } from '../runtime/model-tiers.js';
+import { resolveModel, findRuntimeForModel } from '../runtime/model-tiers.js';
 import { resolveDefaultModel, resolveProvider } from './actions-imagegen.js';
 const CONFIG_TYPE_MAP = {
     modelSet: true,
@@ -137,8 +137,54 @@ export function executeConfigAction(action, configCtx) {
                     break;
                 case 'voice':
                     if (bp.voiceModelCtx) {
-                        bp.voiceModelCtx.model = model;
-                        changes.push(`voice → ${model}`);
+                        // Check if the model string is actually a runtime name.
+                        const voiceNormalized = model.toLowerCase();
+                        const voiceNewRuntime = configCtx.runtimeRegistry?.get(voiceNormalized);
+                        if (voiceNewRuntime) {
+                            skipPersist = true;
+                            const voiceRuntimeModel = voiceNewRuntime.defaultModel ?? '';
+                            bp.voiceModelCtx.runtime = voiceNewRuntime;
+                            bp.voiceModelCtx.runtimeName = voiceNormalized;
+                            bp.voiceModelCtx.model = voiceRuntimeModel;
+                            configCtx.voiceRuntimeName = voiceNormalized;
+                            configCtx.persistVoiceRuntime?.(voiceNormalized);
+                            changes.push(`voice runtime → ${voiceNormalized}`);
+                            if (voiceRuntimeModel)
+                                changes.push(`voice → ${voiceRuntimeModel} (adapter default)`);
+                        }
+                        else {
+                            bp.voiceModelCtx.model = model;
+                            changes.push(`voice → ${model}`);
+                            // Auto-switch voice runtime if the model belongs to a different provider.
+                            if (configCtx.runtimeRegistry) {
+                                const owningRuntimeId = findRuntimeForModel(model);
+                                const currentVoiceRuntimeId = bp.voiceModelCtx.runtime?.id ?? configCtx.runtime.id;
+                                if (owningRuntimeId && owningRuntimeId !== currentVoiceRuntimeId) {
+                                    // Tier-map keys (e.g. 'claude_code') may differ from registry keys (e.g. 'claude').
+                                    // Scan registry entries by adapter.id to find the matching key.
+                                    let matchedKey;
+                                    let matchedAdapter;
+                                    for (const registryKey of configCtx.runtimeRegistry.list()) {
+                                        const adapter = configCtx.runtimeRegistry.get(registryKey);
+                                        if (adapter && adapter.id === owningRuntimeId) {
+                                            matchedKey = registryKey;
+                                            matchedAdapter = adapter;
+                                            break;
+                                        }
+                                    }
+                                    if (matchedAdapter && matchedKey) {
+                                        bp.voiceModelCtx.runtime = matchedAdapter;
+                                        bp.voiceModelCtx.runtimeName = matchedKey;
+                                        configCtx.voiceRuntimeName = matchedKey;
+                                        configCtx.persistVoiceRuntime?.(matchedKey);
+                                        changes.push(`voice runtime → ${matchedKey} (auto-switched)`);
+                                    }
+                                    else {
+                                        return { ok: false, error: `Model "${model}" belongs to runtime "${owningRuntimeId}" which is not configured in the registry` };
+                                    }
+                                }
+                            }
+                        }
                     }
                     else {
                         return { ok: false, error: 'Voice subsystem not configured' };
@@ -153,7 +199,10 @@ export function executeConfigAction(action, configCtx) {
             if (configCtx.overrideSources) {
                 configCtx.overrideSources[action.role] = true;
             }
-            const resolvedDisplay = resolveModel(model, configCtx.runtime.id);
+            const resolveRid = action.role === 'voice' && bp.voiceModelCtx?.runtime
+                ? bp.voiceModelCtx.runtime.id
+                : configCtx.runtime.id;
+            const resolvedDisplay = resolveModel(model, resolveRid);
             const resolvedNote = resolvedDisplay && resolvedDisplay !== model ? ` (resolves to ${resolvedDisplay})` : '';
             return { ok: true, summary: `Model updated: ${changes.join(', ')}${resolvedNote}` };
         }
@@ -215,6 +264,10 @@ export function executeConfigAction(action, configCtx) {
                         case 'voice':
                             if (bp.voiceModelCtx) {
                                 bp.voiceModelCtx.model = defaultModel;
+                                bp.voiceModelCtx.runtime = undefined;
+                                bp.voiceModelCtx.runtimeName = undefined;
+                                configCtx.voiceRuntimeName = undefined;
+                                configCtx.clearVoiceRuntime?.();
                                 resetChanges.push(`voice → ${defaultModel}`);
                             }
                             break;
@@ -261,9 +314,6 @@ export function executeConfigAction(action, configCtx) {
                 const igProvider = resolveProvider(igModel);
                 rows.push(['imagegen', igModel, `Image generation (${igProvider})`, '']);
             }
-            if (bp.voiceModelCtx) {
-                rows.push(['voice', bp.voiceModelCtx.model || `${bp.runtimeModel} (follows chat)`, ROLE_DESCRIPTIONS.voice, ovr('voice')]);
-            }
             const adapterDefault = configCtx.runtime.defaultModel;
             const lines = rows.map(([role, model, desc, overrideMarker]) => {
                 const resolved = resolveModel(model, rid);
@@ -276,6 +326,24 @@ export function executeConfigAction(action, configCtx) {
                 }
                 return `**${role}**: \`${display}\`${overrideMarker} — ${desc}`;
             });
+            if (bp.voiceModelCtx) {
+                const voiceRid = bp.voiceModelCtx.runtime?.id ?? rid;
+                const voiceModel = bp.voiceModelCtx.model || `${bp.runtimeModel} (follows chat)`;
+                const voiceRtLabel = bp.voiceModelCtx.runtimeName && bp.voiceModelCtx.runtimeName !== (configCtx.runtimeName ?? rid)
+                    ? ` [runtime: ${bp.voiceModelCtx.runtimeName}]`
+                    : '';
+                // Voice row uses its own runtime ID for tier resolution.
+                const voiceResolved = resolveModel(voiceModel, voiceRid);
+                let voiceDisplay;
+                if (voiceModel) {
+                    voiceDisplay = voiceResolved && voiceResolved !== voiceModel ? `${voiceModel} → ${voiceResolved}` : voiceModel;
+                }
+                else {
+                    const voiceAdapterDefault = bp.voiceModelCtx.runtime?.defaultModel ?? adapterDefault;
+                    voiceDisplay = voiceAdapterDefault || '(adapter default)';
+                }
+                lines.push(`**voice**: \`${voiceDisplay}\`${ovr('voice')}${voiceRtLabel} — ${ROLE_DESCRIPTIONS.voice}`);
+            }
             return { ok: true, summary: lines.join('\n') };
         }
     }
@@ -297,7 +365,7 @@ export function configActionsPromptSection() {
 <discord-action>{"type":"modelSet","role":"fast","model":"haiku"}</discord-action>
 \`\`\`
 - \`role\` (required): One of \`chat\`, \`fast\`, \`forge-drafter\`, \`forge-auditor\`, \`summary\`, \`cron\`, \`cron-exec\`, \`voice\`.
-- \`model\` (required): Model tier (\`fast\`, \`capable\`, \`deep\`), concrete model name (\`haiku\`, \`sonnet\`, \`opus\`), runtime name (\`openrouter\`, \`gemini\` — for \`chat\` role, swaps the active runtime adapter), or \`default\` (for cron-exec only, to revert to the env-configured default (Sonnet by default)).
+- \`model\` (required): Model tier (\`fast\`, \`capable\`, \`deep\`), concrete model name (\`haiku\`, \`sonnet\`, \`opus\`), runtime name (\`openrouter\`, \`gemini\` — for \`chat\` and \`voice\` roles, swaps the active runtime adapter independently), or \`default\` (for cron-exec only, to revert to the env-configured default (Sonnet by default)). For the \`voice\` role, setting a model name that belongs to a different provider's tier map (e.g. \`sonnet\` while voice is on Gemini) will auto-switch the voice runtime to match.
 
 **Roles:**
 | Role | What it controls |

package/dist/discord/actions-config.test.js

@@ -15,6 +15,12 @@ const openrouterRuntime = {
     defaultModel: 'anthropic/claude-sonnet-4',
     async *invoke() { },
 };
+const geminiRuntime = {
+    id: 'gemini',
+    capabilities: new Set(),
+    defaultModel: 'gemini-2.5-flash',
+    async *invoke() { },
+};
 function makeRegistry(...entries) {
     const reg = new RuntimeRegistry();
     for (const [name, adapter] of entries) {
@@ -538,6 +544,125 @@ describe('modelShow runtime line', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// modelSet — voice runtime swap
+// ---------------------------------------------------------------------------
+describe('modelSet voice runtime swap', () => {
+    it('swaps voiceModelCtx.runtime and sets adapter default model', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'fast' } });
+        ctx.runtimeRegistry = makeRegistry(['gemini', geminiRuntime]);
+        const result = executeConfigAction({ type: 'modelSet', role: 'voice', model: 'gemini' }, ctx);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(ctx.botParams.voiceModelCtx.runtime).toBe(geminiRuntime);
+        expect(ctx.botParams.voiceModelCtx.runtimeName).toBe('gemini');
+        expect(ctx.botParams.voiceModelCtx.model).toBe('gemini-2.5-flash');
+        expect(ctx.voiceRuntimeName).toBe('gemini');
+        expect(result.summary).toContain('voice runtime → gemini');
+        expect(result.summary).toContain('adapter default');
+    });
+    it('does not swap runtime for a plain model name', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'fast' } });
+        ctx.runtimeRegistry = makeRegistry(['gemini', geminiRuntime]);
+        const result = executeConfigAction({ type: 'modelSet', role: 'voice', model: 'sonnet' }, ctx);
+        expect(result.ok).toBe(true);
+        expect(ctx.botParams.voiceModelCtx.runtime).toBeUndefined();
+        expect(ctx.botParams.voiceModelCtx.runtimeName).toBeUndefined();
+        expect(ctx.botParams.voiceModelCtx.model).toBe('sonnet');
+    });
+    it('calls persistVoiceRuntime (not persistOverride) for runtime swaps', () => {
+        let persistOverrideCalled = false;
+        let persistVoiceRuntimeName;
+        const ctx = makeCtx({ voiceModelCtx: { model: 'fast' } });
+        ctx.runtimeRegistry = makeRegistry(['gemini', geminiRuntime]);
+        ctx.persistOverride = () => { persistOverrideCalled = true; };
+        ctx.persistVoiceRuntime = (name) => { persistVoiceRuntimeName = name; };
+        const result = executeConfigAction({ type: 'modelSet', role: 'voice', model: 'gemini' }, ctx);
+        expect(result.ok).toBe(true);
+        expect(persistOverrideCalled).toBe(false);
+        expect(persistVoiceRuntimeName).toBe('gemini');
+    });
+    it('chat runtime swap does not affect voiceModelCtx.runtime', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'fast' } });
+        ctx.runtimeRegistry = makeRegistry(['openrouter', openrouterRuntime]);
+        ctx.botParams.planCtx = { model: 'capable', runtime: stubRuntime };
+        ctx.botParams.deferOpts = { runtime: stubRuntime };
+        executeConfigAction({ type: 'modelSet', role: 'chat', model: 'openrouter' }, ctx);
+        // Chat runtime swapped but voice stays untouched
+        expect(ctx.botParams.runtime).toBe(openrouterRuntime);
+        expect(ctx.botParams.voiceModelCtx.runtime).toBeUndefined();
+        expect(ctx.botParams.voiceModelCtx.model).toBe('fast');
+    });
+    it('case-insensitive matching — Gemini matches gemini', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'fast' } });
+        ctx.runtimeRegistry = makeRegistry(['gemini', geminiRuntime]);
+        const result = executeConfigAction({ type: 'modelSet', role: 'voice', model: 'Gemini' }, ctx);
+        expect(result.ok).toBe(true);
+        expect(ctx.botParams.voiceModelCtx.runtime).toBe(geminiRuntime);
+        expect(ctx.botParams.voiceModelCtx.runtimeName).toBe('gemini');
+    });
+});
+// ---------------------------------------------------------------------------
+// modelReset — voice runtime clear
+// ---------------------------------------------------------------------------
+describe('modelReset voice runtime', () => {
+    it('clears voiceModelCtx.runtime and runtimeName back to undefined', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'gemini-2.5-flash', runtime: geminiRuntime, runtimeName: 'gemini' } });
+        ctx.voiceRuntimeName = 'gemini';
+        ctx.envDefaults = { voice: 'fast' };
+        let clearVoiceRuntimeCalled = false;
+        ctx.clearVoiceRuntime = () => { clearVoiceRuntimeCalled = true; };
+        const result = executeConfigAction({ type: 'modelReset', role: 'voice' }, ctx);
+        expect(result.ok).toBe(true);
+        expect(ctx.botParams.voiceModelCtx.model).toBe('fast');
+        expect(ctx.botParams.voiceModelCtx.runtime).toBeUndefined();
+        expect(ctx.botParams.voiceModelCtx.runtimeName).toBeUndefined();
+        expect(ctx.voiceRuntimeName).toBeUndefined();
+        expect(clearVoiceRuntimeCalled).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// modelShow — voice runtime display
+// ---------------------------------------------------------------------------
+describe('modelShow voice runtime display', () => {
+    it('displays voice runtime name when it differs from chat', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'gemini-2.5-flash', runtime: geminiRuntime, runtimeName: 'gemini' } });
+        ctx.voiceRuntimeName = 'gemini';
+        const result = executeConfigAction({ type: 'modelShow' }, ctx);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const lines = result.summary.split('\n');
+        const voiceLine = lines.find(l => l.includes('**voice**'));
+        expect(voiceLine).toContain('[runtime: gemini]');
+        expect(voiceLine).toContain('gemini-2.5-flash');
+    });
+    it('does not annotate voice runtime when it matches chat', () => {
+        const ctx = makeCtx({ voiceModelCtx: { model: 'sonnet' } });
+        const result = executeConfigAction({ type: 'modelShow' }, ctx);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const lines = result.summary.split('\n');
+        const voiceLine = lines.find(l => l.includes('**voice**'));
+        expect(voiceLine).toBeDefined();
+        expect(voiceLine).not.toContain('[runtime:');
+    });
+    it('resolves tier names against voice runtime ID, not chat runtime', () => {
+        // Voice on gemini with tier 'capable' should resolve to gemini-2.5-pro, not sonnet
+        const ctx = makeCtx({ voiceModelCtx: { model: 'capable', runtime: geminiRuntime, runtimeName: 'gemini' } });
+        ctx.voiceRuntimeName = 'gemini';
+        const result = executeConfigAction({ type: 'modelShow' }, ctx);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const lines = result.summary.split('\n');
+        const voiceLine = lines.find(l => l.includes('**voice**'));
+        expect(voiceLine).toContain('gemini-2.5-pro');
+        expect(voiceLine).not.toContain('sonnet');
+    });
+});
+// ---------------------------------------------------------------------------
 // configActionsPromptSection
 // ---------------------------------------------------------------------------
 describe('configActionsPromptSection', () => {

package/dist/discord/actions-spawn.js

@@ -114,5 +114,6 @@ export function spawnActionsPromptSection() {
 - Multiple spawnAgent actions in a single response are run in parallel for efficiency.
 - Spawned agents run at recursion depth 1 and cannot themselves spawn further agents.
 - The spawned agent runs fire-and-forget: it posts its output directly to the target channel.
-- Keep prompts focused — each agent handles a single well-defined task.`;
+- Keep prompts focused — each agent handles a single well-defined task.
+- **Context isolation:** The spawned agent has **no conversation history** — it receives only the \`prompt\` string. The prompt must be fully self-contained: include all entity IDs, channel names, file paths, and relevant state. Do not reference "the above," "this task," or anything from the current conversation — the spawned agent cannot see it.`;
 }

package/dist/discord/actions-spawn.test.js

@@ -377,6 +377,10 @@ describe('spawnActionsPromptSection', () => {
         const section = spawnActionsPromptSection();
         expect(section).toContain('recursion');
     });
+    it('warns about no conversation history (context isolation)', () => {
+        const section = spawnActionsPromptSection();
+        expect(section).toContain('no conversation history');
+    });
     it('includes a usage example block', () => {
         const section = spawnActionsPromptSection();
         expect(section).toContain('<discord-action>');

package/dist/discord/actions.js

@@ -681,7 +681,9 @@ If an action fails with a "Missing Permissions" or "Missing Access" error, tell
 4. The bot may need to be re-invited with the "moderator" permission profile if the role wasn't granted at invite time.`);
     if (flags.defer) {
         sections.push(`### Deferred self-invocation
-Use a <discord-action>{"type":"defer","channel":"general","delaySeconds":600,"prompt":"Check on the forge run"}</discord-action> block to schedule a follow-up run inside the requested channel without another user prompt. You must specify the channel by name or ID; delaySeconds is how long to wait (capped by DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DELAY_SECONDS) and prompt becomes the user message when the deferred invocation runs. The scheduler enforces DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_CONCURRENT pending jobs, respects the same channel permissions as this response, automatically posts the follow-up output, and allows nested defers up to the configured depth limit (DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DEPTH, default 4); once the limit is reached, \`defer\` is disabled for that run. If a guard rail rejects the request (too long, too many active defers, missing permissions, or the channel becomes invalid) the action fails with an explanatory message.`);
+Use a <discord-action>{"type":"defer","channel":"general","delaySeconds":600,"prompt":"Check on the forge run"}</discord-action> block to schedule a follow-up run inside the requested channel without another user prompt. You must specify the channel by name or ID; delaySeconds is how long to wait (capped by DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DELAY_SECONDS) and prompt becomes the user message when the deferred invocation runs. The scheduler enforces DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_CONCURRENT pending jobs, respects the same channel permissions as this response, automatically posts the follow-up output, and allows nested defers up to the configured depth limit (DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DEPTH, default 4); once the limit is reached, \`defer\` is disabled for that run. If a guard rail rejects the request (too long, too many active defers, missing permissions, or the channel becomes invalid) the action fails with an explanatory message.
+
+**Context isolation warning:** The deferred invocation runs with no conversation history — the \`prompt\` string is the **only** context the AI receives. It must include all relevant IDs, file paths, channel references, and state needed to act. Vague prompts like "check on that" will fail because the AI has no memory of what "that" refers to. Write every deferred prompt as a fully self-contained instruction.`);
     }
     return sections.join('\n\n');
 }

package/dist/discord/actions.test.js

@@ -627,6 +627,7 @@ describe('discordActionsPromptSection', () => {
         expect(prompt).toContain('DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DELAY_SECONDS');
         expect(prompt).toContain('DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_CONCURRENT');
         expect(prompt).toContain('DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DEPTH');
+        expect(prompt).toContain('no conversation history');
     });
 });
 // ---------------------------------------------------------------------------

package/dist/discord/models-command.js

@@ -54,8 +54,8 @@ export function handleModelsCommand(cmd, opts) {
             '',
             '**Roles:** `chat`, `fast`, `forge-drafter`, `forge-auditor`, `summary`, `cron`, `cron-exec`, `voice`',
             '',
-            '**Runtime switching (chat role only):**',
-            'Setting the `chat` role to a runtime name (`openrouter`, `openai`, `gemini`, `codex`, `claude`) switches the active runtime adapter so invocations route through that provider.',
+            '**Runtime switching (chat and voice roles):**',
+            'Setting the `chat` or `voice` role to a runtime name (`openrouter`, `openai`, `gemini`, `codex`, `claude`) switches the active runtime adapter so invocations route through that provider.',
             '',
             '**Examples:**',
             '- `!models set chat sonnet`',
@@ -65,6 +65,7 @@ export function handleModelsCommand(cmd, opts) {
             '- `!models set forge-drafter opus`',
             '- `!models set cron-exec haiku` — run crons on a cheaper model',
             '- `!models set cron-exec default` — revert to env default (Sonnet by default)',
+            '- `!models set voice gemini` — switch voice to the Gemini runtime',
             '- `!models set voice sonnet` — use a specific model for voice responses',
             '- `!models reset` — clear all overrides and revert to env defaults',
             '- `!models reset chat` — revert only the chat model to its env default',

package/dist/discord/reaction-prompts.js

@@ -118,5 +118,7 @@ export function reactionPromptSection() {
 
 The action returns immediately with a confirmation that the prompt was sent. When the user reacts with a valid choice, a follow-up invocation is triggered automatically so you can act on the decision.
 
+**Context warning:** The follow-up AI invocation receives *only* the \`question\` text and the chosen emoji — no conversation history or prior context is included. Write questions that are specific and self-contained so the follow-up AI knows exactly what action to take for each choice. For example, use "Deploy commit abc123 to staging?" instead of "Should I proceed?" — the follow-up invocation won't know what "proceed" refers to.
+
 Use this for binary confirmations (✅/❌) or short option lists — not for open-ended text input.`;
 }

package/dist/discord/reaction-prompts.test.js

@@ -242,6 +242,11 @@ describe('reactionPromptSection', () => {
     it('mentions choice count limits', () => {
         expect(reactionPromptSection()).toContain('2–9');
     });
+    it('warns about no conversation history in follow-up invocation', () => {
+        const section = reactionPromptSection();
+        expect(section).toContain('no conversation history');
+        expect(section).toContain('self-contained');
+    });
 });
 // ---------------------------------------------------------------------------
 // QUERY_ACTION_TYPES regression guard