openvisio-agent 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.25.0] — 2026-09-18
+
+- Reduce Studio journal-processing CPU by caching unchanged files, refreshing every two seconds, and disconnecting hidden or paused views.
+- Add reviewed local agent removal in Studio: stop the watcher/service before deleting its local credentials, history, memory, and context; retain repositories and shared provider logins.
+- Instruct coding agents to reuse one task branch/worktree across retries and follow-ups and retire only clean, inactive, fully merged local work.
+- Resolve missing assignment slugs from verified ticket details; retain failed lookup context so “Try again” retries that same ticket lookup in its source thread, including after restart.
+- Answer model-status questions directly from current watcher settings so provider failures cannot prevent the status reply.
+- Recognize OpenCode provider errors including “Too many requests,” release stalled ACP sessions promptly, and report authentication/model failures with actionable guidance.
+- Persist OpenCode provider pauses separately: retry rate-limited tickets after a 30-minute cooldown, and resume provider-blocked tickets when their selected model changes while preserving ownership, review, and policy checks.
+- Add an isolated real-OpenCode smoke check: `node scripts/check-opencode.mjs` exercises successful MCP work, HTTP 429, and HTTP 401 against localhost fixtures.
+
+## [0.24.1] — 2026-09-10
+
+- Deliver agent-authored acknowledgements and short plans to the originating channel or thread when a request moves into a coding workspace.
+- Highlight the selected agent in Studio and show embedded avatars shared with the main app.
+
 ## [0.24.0] — 2026-09-10
 
 - Acknowledge accepted coding tasks with the agent's short native plan, then deliver its final response separately. Deduplicate plans through reconnects and use guarded source-thread delivery for every BYO runtime.

package/USER_GUIDE.md

@@ -78,6 +78,8 @@ Replies stay in their source thread. New completion messages use the agent’s d
 
 For accepted coding tasks, the agent starts by publishing a short plan. You receive one acknowledgement with up to three steps, followed later by its result. The agent can delegate independent pieces to native sub-agents and remains responsible for checking their work. Thinking, working, and typing indicators follow runtime activity; they expire after work stops. A reconnect does not repeat the plan or cancel healthy work.
 
+When a conversation turns into coding work, the agent includes its acknowledgement and two or three next steps in the workspace handoff. They are posted to the original channel thread before coding starts. Private continuation context stays internal, and the work session does not send a second pickup message.
+
 ## Open Agent Studio
 
 In the app, choose **Agents → Open Agent Studio**. Updated backend watchers start Studio automatically. Agent chat replies can also show this button and open the relevant agent’s settings directly.
@@ -169,6 +171,20 @@ Use `Tab` and `Shift+Tab` to move through controls, `Enter` to activate buttons
 
 ## Local history and privacy
 
+Studio caches unchanged journals and refreshes live views every two seconds. A hidden tab or paused view disconnects live updates until you return. Watchers keep working.
+
+## Remove an agent from this computer
+
+Select an agent in Studio, choose **Remove from computer**, review the local data, and type its local name to confirm. Studio stops its watcher and background service before removing local connection credentials, logs, memory, and context caches. Removal cannot be undone.
+
+Repositories, branches, shared provider logins, and the team profile are retained. Context shared with another local connection is kept. Automatic removal supports macOS and Linux in the default `~/.openvisio` directory; custom state directories and Windows require manual management.
+
+## Reuse task branches
+
+Agents should use one branch and worktree per task in each repository, including retries and review fixes. Check for the existing branch and PR before creating either. Separate unrelated tasks and concurrent conflicting work. Retire only fully merged local agent branches with clean, inactive worktrees; preserve unmerged changes and the primary checkout. Remote branch deletion requires explicit authorization.
+
+## Recorded history
+
 Studio reads bounded journals in `~/.openvisio/observability`. It serves up to 500 recent events, subject to file and byte limits. Journals rotate, long text is shortened, and bursts may drop records. Use the team’s ticket and channel history for delivered results.
 
 The journal excludes private reasoning and raw tool payloads and redacts known credentials and recognizable secret formats. Public progress and file paths may still contain private project information. Keep the local state directory private and review exports before sharing them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {

package/scenarios/workspace.scenarios.mjs

@@ -192,12 +192,12 @@ scenario('known-thread-read-outage', 'Explicitly addressed message is routed eve
   const f = fixture({ task: false, threadError: true })
   try {
     await f.mention('@Alex what model are you running?'); await f.idle()
-    assert.equal(f.runs.length, 1, f.logs.join('\n'))
+    assert.equal(f.runs.length, 0, 'Model status is available without a provider call')
     assert.equal(f.posts.length, 0, 'Unavailable authoritative delivery read must not become an unchecked post')
     await f.watcher.close(); f.start()
     f.threadError = false
     await f.watcher.retryDeliveries()
-    assert.equal(f.runs.length, 1, 'Restart retries delivery without regenerating the answer')
+    assert.equal(f.runs.length, 0, 'Restart retries delivery without a model call')
     assert.equal(f.posts.length, 1)
     await f.watcher.retryDeliveries()
     assert.equal(f.posts.length, 1)
@@ -241,7 +241,7 @@ scenario('distinct-source-identical-text', 'Different human message ids with ide
   try {
     await f.mention('@Alex what model are you running?', { id: 200 }); await f.idle()
     await f.mention('@Alex what model are you running?', { id: 201 }); await f.idle()
-    assert.equal(f.runs.length, 2)
+    assert.equal(f.runs.length, 0, 'Both model-status answers are watcher-owned')
     assert.equal(f.posts.length, 2)
   } finally { await f.cleanup() }
 })
@@ -250,12 +250,12 @@ scenario('cancel-pending-then-reactivate', 'New request in a canceled thread can
   const f = fixture({ task: false, threadError: true })
   try {
     await f.mention('@Alex what model are you running?'); await f.idle()
-    assert.equal(f.runs.length, 1)
+    assert.equal(f.runs.length, 0, 'The pending model-status answer needs no provider')
     await f.mention('Stop working on this.', { id: 201 }); await f.idle()
     f.threadError = false
     await f.mention('@Alex check the current project details.', { id: 202 }); await f.idle()
     await f.watcher.retryDeliveries()
-    assert.equal(f.runs.length, 2)
+    assert.equal(f.runs.length, 1, 'Only the new project-details request calls the model')
     // Final response to the new question plus at most its stand-down confirmation.
     assert.equal(f.posts.filter((post) => !/standing down/.test(post.content)).length, 1)
   } finally { await f.cleanup() }

package/scripts/check-opencode.mjs

@@ -0,0 +1,73 @@
+// Opt-in real CLI check: node scripts/check-opencode.mjs
+// Uses only a localhost provider/MCP fixture and isolated OpenCode state.
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createServer } from 'node:http'
+import { AcpAgent } from '@mastra/acp'
+import { createMastraAcpRunner } from '../src/mastra-harness.mjs'
+
+for (const status of [200, 429, 401]) {
+  const dir = await mkdtemp(join(tmpdir(), 'openvisio-opencode-check-'))
+  for (const name of ['config', 'data', 'cache', 'state', 'repo']) await mkdir(join(dir, name))
+  let toolCalls = 0
+  const server = createServer(async (req, res) => {
+    try {
+      let raw = ''
+      for await (const chunk of req) raw += chunk
+      const body = JSON.parse(raw)
+      if (req.url === '/mcp') {
+        if (body.id == null) { res.writeHead(202); res.end(); return }
+        let result = {}
+        if (body.method === 'initialize') result = { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'fixture', version: '1' } }
+        if (body.method === 'tools/list') result = { tools: [{ name: 'get_ticket', description: 'Read a fixture ticket', inputSchema: { type: 'object', properties: { project_id: { type: 'number' }, ticket_id: { type: 'number' } }, required: ['project_id', 'ticket_id'] } }] }
+        if (body.method === 'tools/call') { toolCalls++; result = { content: [{ type: 'text', text: 'Fixture ticket' }] } }
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ jsonrpc: '2.0', id: body.id, result }))
+        return
+      }
+      // OpenCode's background title request must succeed independently.
+      if (body.tools && status !== 200) {
+        res.writeHead(status, { 'content-type': 'application/json', 'retry-after': '120' })
+        res.end(JSON.stringify({ error: { message: status === 429 ? 'Too many requests' : 'Invalid API key' } }))
+        return
+      }
+      const needsTool = body.tools?.some(t => t.function.name === 'openvisio-team-watcher_get_ticket') && !body.messages.some(m => m.role === 'tool')
+      const delta = needsTool ? { role: 'assistant', tool_calls: [{ index: 0, id: 'fixture-call', type: 'function', function: { name: 'openvisio-team-watcher_get_ticket', arguments: JSON.stringify({ project_id: 1, ticket_id: 2 }) } }] } : { role: 'assistant', content: 'Fixture response.' }
+      res.writeHead(200, { 'content-type': 'text/event-stream' })
+      res.write(`data: ${JSON.stringify({ id: 'fixture', object: 'chat.completion.chunk', created: 1, model: 'test', choices: [{ index: 0, delta, finish_reason: null }] })}\n\n`)
+      res.write(`data: ${JSON.stringify({ id: 'fixture', object: 'chat.completion.chunk', created: 1, model: 'test', choices: [{ index: 0, delta: {}, finish_reason: needsTool ? 'tool_calls' : 'stop' }], usage: { prompt_tokens: 10, completion_tokens: 3, total_tokens: 13 } })}\n\n`)
+      res.end('data: [DONE]\n\n')
+    } catch (error) { res.writeHead(500); res.end(String(error)) }
+  })
+  let runner
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve) })
+    const baseURL = `http://127.0.0.1:${server.address().port}`
+    class IsolatedAcp extends AcpAgent {
+      constructor(options) {
+        const config = { ...JSON.parse(options.env.OPENCODE_CONFIG_CONTENT), enabled_providers: ['fixture'], model: 'fixture/test', small_model: 'fixture/test', provider: { fixture: { npm: '@ai-sdk/openai-compatible', name: 'Fixture', options: { baseURL: `${baseURL}/v1`, apiKey: 'fixture' }, models: { test: { name: 'Test', limit: { context: 8192, output: 1024 } } } } } }
+        super({ ...options, env: { ...options.env, XDG_CONFIG_HOME: join(dir, 'config'), XDG_DATA_HOME: join(dir, 'data'), XDG_CACHE_HOME: join(dir, 'cache'), XDG_STATE_HOME: join(dir, 'state'), OPENCODE_CONFIG_CONTENT: JSON.stringify(config), OPENCODE_DISABLE_PROJECT_CONFIG: 'true', OPENCODE_DISABLE_DEFAULT_PLUGINS: 'true', OPENCODE_DISABLE_MODELS_FETCH: 'true' } })
+      }
+    }
+    runner = createMastraAcpRunner({ agent: 'opencode', mcpUrl: `${baseURL}/mcp`, mcpHeaders: { 'x-agent-api-key': 'fixture', 'x-agent-identifier': 'fixture-agent' }, workdir: join(dir, 'repo'), canCode: false, model: 'fixture/test', maxCycleMs: 20_000, AcpAgentClass: IsolatedAcp })
+    const start = performance.now()
+    const result = await runner.runCycle('Read the fixture ticket and reply.')
+    assert.equal(result.subtype, status === 200 ? 'ok' : status === 429 ? 'rate_limited' : 'authentication_error')
+    if (status === 200) {
+      assert.equal(result.outputText, 'Fixture response.')
+      assert.equal(result.didMcpTaskRead, true)
+      assert.equal(toolCalls, 1)
+    } else {
+      assert.ok(result.userMessage)
+      assert.equal(toolCalls, 0)
+    }
+    console.log(`PASS OpenCode HTTP ${status}: ${result.subtype} (${Math.round(performance.now() - start)} ms)`)
+  } finally {
+    runner?.close()
+    server.closeAllConnections()
+    await new Promise(resolve => server.close(resolve))
+    await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 })
+  }
+}

package/src/agent-removal.mjs

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, open, readdir, readFile, rm } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { OV_DIR, slugify } from './lib.mjs'
+
+const exec = promisify(execFile)
+const hash = value => createHash('sha256').update(value).digest('hex')
+const problem = (message, status = 409) => Object.assign(new Error(message), { status })
+const validSlug = value => typeof value === 'string' && /^[a-z0-9][a-z0-9_-]{0,79}$/i.test(value)
+
+async function readConfig(stateDir, slug) {
+  if (!validSlug(slug)) throw problem('Agent not found.', 404)
+  const root = await lstat(stateDir)
+  if (!root.isDirectory() || root.isSymbolicLink()) throw problem('Agent storage must be a real local directory.')
+  const file = await open(join(stateDir, `${slug}.json`), constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+  try {
+    const stat = await file.stat()
+    if (!stat.isFile() || stat.size > 65536) throw problem('Agent configuration is invalid.')
+    const raw = await file.readFile('utf8')
+    const config = JSON.parse(raw)
+    if (config.slug !== slug || !(config.mode === 'backend' && config.identifier && config.apiKey || config.host && config.key)) throw problem('Agent configuration is invalid.')
+    return { config, version: hash(raw) }
+  } finally { await file.close() }
+}
+
+async function realDirectory(path) {
+  const stat = await lstat(path).catch(() => null)
+  return stat?.isDirectory() && !stat.isSymbolicLink()
+}
+
+export async function planAgentRemoval({ stateDir, slug }) {
+  const { config, version } = await readConfig(stateDir, slug)
+  const identifier = config.mode === 'backend' ? config.identifier : slug
+  const names = new Set([`${slug}.json`, `${slug}.env`, `${slug}.log`, `${slug}-team.mcp.json`, `${slug}-watch.mjs`, `${slug}-watch.sh`, `${slug}-cycle.sh`, `${slug}-cycle.sh.bak`, `watch-${slug}.lock`, `watch-${slug}-memory.json`, `watch-${slug}-replay.json`, `watch-${slug}-mastra.db`, `watch-${slug}-mastra.db-wal`, `watch-${slug}-mastra.db-shm`])
+  const entries = await readdir(stateDir)
+  // Configurations sharing an identity also share context. Keep that data until
+  // the last local connection is removed, regardless of its provider choice.
+  let shared = false
+  for (const name of entries.filter(name => name.endsWith('.json') && name !== `${slug}.json`)) {
+    try {
+      const other = (await readConfig(stateDir, name.slice(0, -5))).config
+      if ((other.identifier || other.slug) === identifier) shared = true
+    } catch { /* unrelated local file */ }
+  }
+  if (!shared) {
+    if (validSlug(identifier)) { names.add(`intro-${identifier}.done`); names.add(`sweep-${identifier}.at`) }
+    const key = slugify(identifier)
+    for (const name of entries) if (name === `opencode-${key}` || name.startsWith(`opencode-${key}-reply-`) || name.startsWith(`opencode-${key}-work-`)) names.add(name)
+    if (config.mode === 'backend') {
+      const backend = new URL(config.backend || config.mcpUrl || 'http://local.invalid')
+      const scope = hash(`${backend.origin}${backend.pathname.replace(/\/$/, '')}:${identifier}`).slice(0, 24)
+      for (const suffix of ['json', 'db', 'db-wal', 'db-shm']) names.add(`context-${scope}.${suffix}`)
+      names.add(`embeddings-${scope}`)
+    }
+  }
+  const files = []
+  for (const name of names) if (await lstat(join(stateDir, name)).catch(() => null)) files.push(name)
+  if (await realDirectory(join(stateDir, 'observability'))) {
+    // The stem contains this setup's slug and the exact provider/identity hash.
+    const stems = [...new Set(['claude', 'codex', 'opencode', config.agent || 'claude'])].map(provider => `${slug.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 60)}-${hash(`${identifier}:${provider}`).slice(0, 12)}`)
+    for (const name of await readdir(join(stateDir, 'observability'))) {
+      if (stems.some(stem => [`${stem}.jsonl`, `${stem}.1.jsonl`, `${stem}.2.jsonl`].includes(name))) files.push(`observability/${name}`)
+    }
+  }
+  return { slug, name: config.name || slug, version, files: files.sort(), sharedContextRetained: shared }
+}
+
+async function stopLocalAgent({ stateDir, slug }) {
+  if (resolve(stateDir) !== resolve(OV_DIR)) throw problem('Stopping agents is supported only in this computer’s agent storage.')
+  if (slugify(slug) !== slug) throw problem('This legacy local name cannot be stopped safely from Studio.')
+  if (process.platform === 'win32') throw problem('Stop the watcher manually before removal on Windows; automatic removal is not supported yet.')
+  const lock = await readFile(join(stateDir, `watch-${slug}.lock`), 'utf8').catch(() => '')
+  const pid = /^\d+\s*$/.test(lock) ? Number(lock.trim()) : null
+  const service = process.platform === 'darwin'
+    ? join(homedir(), 'Library', 'LaunchAgents', `io.openvisio.${slug}.plist`)
+    : join(homedir(), '.config', 'systemd', 'user', `openvisio-${slug}.service`)
+  if (process.platform !== 'darwin' && await lstat(service).catch(() => null)) {
+    await exec('systemctl', ['--user', 'disable', '--now', `openvisio-${slug}.service`], { timeout: 15000 })
+  }
+  await exec(process.execPath, [fileURLToPath(new URL('../bin/cli.mjs', import.meta.url)), 'stop', '--name', slug], { timeout: 20000, maxBuffer: 65536 })
+  if (Number.isSafeInteger(pid) && pid > 0) {
+    let alive = false
+    try { process.kill(pid, 0); alive = true } catch (error) { alive = error.code === 'EPERM' }
+    if (alive) throw problem('The recorded watcher process is still running. Stop it before removing its data.')
+  }
+  if (process.platform === 'darwin') {
+    const loaded = await exec('launchctl', ['print', `gui/${process.getuid()}/io.openvisio.${slug}`], { timeout: 5000 }).then(() => true, () => false)
+    if (loaded) throw problem('The background service is still loaded. Stop it before removing the agent.')
+  }
+  await rm(service, { force: true })
+}
+
+export async function removeLocalAgent({ stateDir, slug, version, confirmation, stop = stopLocalAgent }) {
+  const plan = await planAgentRemoval({ stateDir, slug })
+  if (confirmation !== slug) throw problem('Enter the agent’s local name to confirm removal.', 400)
+  if (version !== plan.version) throw problem('Agent settings changed. Review removal again.')
+  // Stop first: removing SQLite files while their watcher is running corrupts
+  // state and an installed service could immediately recreate it.
+  await stop({ stateDir, slug })
+  const current = await planAgentRemoval({ stateDir, slug })
+  if (current.version !== version) throw problem('Agent settings changed while stopping. Review removal again.')
+  // Remove config last so an interrupted cleanup remains retryable in Studio.
+  const files = current.files.filter(name => name !== `${slug}.json`)
+  for (const name of files) {
+    if (name.startsWith('observability/') && !await realDirectory(join(stateDir, 'observability'))) throw problem('Journal directory changed during removal.')
+    await rm(join(stateDir, name), { recursive: true, force: true })
+  }
+  await rm(join(stateDir, `${slug}.json`), { force: true })
+  return { removed: true, slug, filesRemoved: files.length + 1, sharedContextRetained: current.sharedContextRetained }
+}

package/src/assignment-routing.mjs

@@ -23,9 +23,9 @@ export async function routeAssignments({ request, loadTickets, handleTask, isCan
   const selected = tickets.filter((ticket) => ticket && (!request.slugs.length || request.slugs.includes(ticketDisplaySlug(ticket))))
   // A project-scoped slug must resolve uniquely before any work is started.
   for (const slug of request.slugs) {
-    if (selected.filter((ticket) => ticketDisplaySlug(ticket) === slug).length !== 1) {
-      throw new Error(`I couldn't uniquely resolve ${slug} among my open assignments.`)
-    }
+    const matches = selected.filter((ticket) => ticketDisplaySlug(ticket) === slug)
+    if (!matches.length) throw new Error(`I couldn't find ${slug} among my open assignments. Check that it is assigned to me and still open, then ask me to try again.`)
+    if (matches.length > 1) throw new Error(`I found multiple open assignments named ${slug}. Please specify the project so I can uniquely resolve the ticket.`)
   }
   const actionable = selected.filter((ticket) => !ticket.awaitingReview && !taskIsAwaitingReview(ticket) && !taskIsCompleted(ticket))
   if (isCancelled()) return 0

package/src/mastra-harness.mjs

@@ -8,6 +8,7 @@ import { codexPolicyBlock } from './events.mjs'
 import { WORK_SESSION_TOOL, workSessionRequest } from './runtime-control.mjs'
 import { contextToolNames } from './context-tools.mjs'
 import { buildOpencodeConfig } from './opencode-config.mjs'
+import { opencodeProviderFailure } from './opencode-failure.mjs'
 import { isTransportInterruption } from './transport-recovery.mjs'
 
 const MCP_TOOL_NAMES = [
@@ -259,25 +260,29 @@ export function createMastraAcpRunner({
     let stderrOffset = String(acp.connection.stderr || '').length
     let stderrPending = ''
     let providerFailure = null
-    const diagnosticTimer = agent === 'opencode' ? setInterval(() => {
+    const inspectDiagnostics = (flush = false) => {
+      if (agent !== 'opencode' || providerFailure) return
       const stderr = String(acp.connection.stderr || '')
       if (stderr.length < stderrOffset) stderrOffset = 0
       stderrPending += stderr.slice(stderrOffset)
       stderrOffset = stderr.length
       const lines = stderrPending.split('\n')
       stderrPending = lines.pop().slice(-8000)
+      if (flush && stderrPending) { lines.push(stderrPending); stderrPending = '' }
       const sessionId = acp.connection.sessionId
       for (const line of lines) {
         if (!sessionId || !line.includes(`session.id=${sessionId} `) ||
             !line.includes('level=ERROR ') || !line.includes('message="stream error"') ||
-            !line.includes('small=false ') || !/Rate limit exceeded/i.test(line)) continue
-        providerFailure = 'OpenCode’s model provider is rate-limiting this request. Retry after the provider limit resets, or select a model with available quota using --chat-model (replies) or --model (coding).'
-        log(providerFailure)
-        controller.abort(new Error(providerFailure))
+            !line.includes('small=false ')) continue
+        providerFailure = opencodeProviderFailure(line.slice(line.indexOf('error.error=')))
+        if (!providerFailure) continue
+        log(providerFailure.userMessage)
+        controller.abort(new Error(providerFailure.userMessage))
         invalidate()
         break
       }
-    }, 250) : null
+    }
+    const diagnosticTimer = agent === 'opencode' ? setInterval(inspectDiagnostics, 250) : null
     const requestedModel = cycleModel || model || ''
     let selectedModel = ''
     try {
@@ -353,6 +358,7 @@ export function createMastraAcpRunner({
           else if (merged.status === 'completed') errors.delete(name)
         }
       }
+      inspectDiagnostics(true)
       controller.signal.throwIfAborted()
       // Only final, completed tool states are evidence. Started/failed edits and
       // board mutations cannot stand in for completed repository work.
@@ -389,8 +395,12 @@ export function createMastraAcpRunner({
         didMcpTaskRead, didMcpTaskUpdate,
       }
     } catch (error) {
+      if (!controller.signal.aborted) {
+        inspectDiagnostics(true)
+        if (agent === 'opencode') providerFailure ||= opencodeProviderFailure(error?.message)
+      }
       const canceled = controller.signal.aborted
-      const subtype = providerFailure ? 'rate_limited' : timedOut ? 'timeout' : canceled ? 'canceled' : 'error'
+      const subtype = providerFailure?.subtype || (timedOut ? 'timeout' : canceled ? 'canceled' : 'error')
       const errorDetail = [error?.message, error?.data ? json(error.data) : ''].filter(Boolean).join(': ')
       const safeError = redact(errorDetail)
       flushProgress()
@@ -399,7 +409,7 @@ export function createMastraAcpRunner({
       log(`${agent} cycle done via Mastra ACP (${subtype}${!canceled && safeError ? ': ' + clean(safeError, 1200) : ''})`)
       invalidate()
       return {
-        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure?.userMessage || null, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
         mcpCalls: [...calls], mcpErrors: [...errors.keys()], mcpErrorDetails: Object.fromEntries(errors),
         didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage,
         didMcpTaskRead, didMcpTaskUpdate,

package/src/opencode-failure.mjs

@@ -0,0 +1,14 @@
+// Classify runtime diagnostics only, never assistant prose or tool output.
+export function opencodeProviderFailure(value) {
+  const text = String(value || '').split('ACP agent stderr:')[0]
+  if (/rate[_ -]?limit|too many requests|\b(?:HTTP|status(?: code)?)\s*[:=]?\s*429\b/i.test(text)) {
+    return { subtype: 'rate_limited', userMessage: 'OpenCode’s model provider is rate-limiting this request. Retry after the provider limit resets, or select a model with available quota in Agent Studio.' }
+  }
+  if (/invalid[ _-]api[ _-]key|incorrect API key|authentication[_ -]error|unauthorized|\b(?:HTTP|status(?: code)?)\s*[:=]?\s*401\b/i.test(text)) {
+    return { subtype: 'authentication_error', userMessage: 'OpenCode’s model provider rejected its credentials. Update that provider’s credentials with opencode auth login, then retry, or select an authenticated provider in Agent Studio.' }
+  }
+  if (/Configured model .+ is unavailable|model[_ -]not[_ -]found|ProviderModelNotFoundError/i.test(text)) {
+    return { subtype: 'model_unavailable', userMessage: 'The configured OpenCode model is unavailable. Select an available model from the intended provider in Agent Studio, then retry.' }
+  }
+  return null
+}

package/src/runtime-control.mjs

@@ -4,18 +4,25 @@ export function runtimeControlTools({ canCode = false, workspaceAvailable = fals
   if (canCode || !workspaceAvailable) return []
   return [{
     name: WORK_SESSION_TOOL,
-    description: 'Continue this same request in your configured coding workspace. Use when investigation reveals that local execution or edits are needed. You remain the same agent and retain the original task, recipient, and permissions. Supply the context worth carrying forward, then end this turn; the watcher starts your work session and delivers its eventual response. Do not ask the user to reassign the task.',
-    inputSchema: { type: 'object', properties: { context: { type: 'string', minLength: 1, maxLength: 12000, description: 'Relevant findings, decisions, remaining work, and context for your continuation.' } }, required: ['context'], additionalProperties: false },
+    description: 'Continue this same request in your configured coding workspace. Use when investigation reveals that local execution or edits are needed. You remain the same agent and retain the original task, recipient, and permissions. Supply private continuation context plus a teammate-facing acknowledgement and 2-3 concrete plan steps. The watcher posts that acknowledgement and plan in the original channel/thread before starting your work session, then delivers your eventual result separately. End this turn after requesting continuation; do not repeat the acknowledgement or ask for reassignment.',
+    inputSchema: { type: 'object', properties: {
+      context: { type: 'string', minLength: 1, maxLength: 12000, description: 'Private findings, decisions, remaining work, and context for your continuation. This field is not posted to chat.' },
+      acknowledgement: { type: 'string', minLength: 1, maxLength: 1200, description: 'A short, natural first-person acknowledgement for the teammate. Say what you have accepted; do not claim completion.' },
+      plan: { type: 'array', minItems: 2, maxItems: 3, items: { type: 'string', minLength: 1, maxLength: 240 }, description: '2-3 concrete next steps to post alongside your acknowledgement before doing the work.' },
+    }, required: ['context', 'acknowledgement', 'plan'], additionalProperties: false },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   }]
 }
 
 export function requestWorkSession(args, capabilities) {
   if (!runtimeControlTools(capabilities).length) throw new Error('No additional coding workspace is available in this session')
-  if (!args || Object.keys(args).some((key) => key !== 'context') || typeof args.context !== 'string' || !args.context.trim() || args.context.length > 12000) throw new Error('Provide only a nonempty context string of at most 12000 characters')
-  return { content: [{ type: 'text', text: JSON.stringify({ openvisioControl: { action: 'request_work_session', context: args.context.trim() } }) }] }
+  if (!args || Object.keys(args).some((key) => !['context', 'acknowledgement', 'plan'].includes(key)) || typeof args.context !== 'string' || !args.context.trim() || args.context.length > 12000) throw new Error('Provide a nonempty context string of at most 12000 characters and only the advertised acknowledgement and plan fields')
+  if (typeof args.acknowledgement !== 'string' || !args.acknowledgement.trim() || args.acknowledgement.length > 1200 || !validPlan(args.plan)) throw new Error('Include a short acknowledgement and 2-3 nonempty plan steps of at most 240 characters each for delivery to the original conversation')
+  return { content: [{ type: 'text', text: JSON.stringify({ openvisioControl: { action: 'request_work_session', context: args.context.trim(), acknowledgement: args.acknowledgement.trim(), plan: args.plan.map(step => step.trim()) } }) }] }
 }
 
+const validPlan = (plan) => Array.isArray(plan) && plan.length >= 2 && plan.length <= 3 && plan.every(step => typeof step === 'string' && step.trim() && step.length <= 240)
+
 // Only inspect outputs of our named local control tool, never arbitrary model
 // prose, commands, ticket text, or repository content.
 export function workSessionRequest(output, depth = 0) {
@@ -28,7 +35,11 @@ export function workSessionRequest(output, depth = 0) {
     return null
   }
   const request = output.openvisioControl
-  if (request?.action === 'request_work_session' && typeof request.context === 'string' && request.context.trim() && request.context.length <= 12000) return { context: request.context.trim() }
+  if (request?.action === 'request_work_session' && typeof request.context === 'string' && request.context.trim() && request.context.length <= 12000) return {
+    context: request.context.trim(),
+    ...(typeof request.acknowledgement === 'string' && request.acknowledgement.trim() && request.acknowledgement.length <= 1200 ? { acknowledgement: request.acknowledgement.trim() } : {}),
+    ...(validPlan(request.plan) ? { plan: request.plan.map(step => step.trim()) } : {}),
+  }
   for (const key of ['content', 'text', 'result', 'structuredContent']) {
     const nested = workSessionRequest(output[key], depth + 1)
     if (nested) return nested