kimaki 1.2.0 → 1.3.0

package/skills/kimaki-tunnel/SKILL.md

@@ -5,26 +5,30 @@ description: Share a local dev server with the user through a public URL. Use wh
 
 # Dev servers with tunnel access
 
-Localhost URLs are useless from Discord. Wrap the dev server in `kimaki tunnel` to get a public URL, and run it in a named background `tuistory` session so you can wait for output, read logs and stop it later. Name the session descriptively (e.g. `projectname-dev`) and reuse it. Run `tuistory --help` first (or `bunx tuistory` when it is not installed). Invoke `kimaki` directly, not via `npx` or `bunx`.
+Localhost URLs are useless from Discord. Wrap the dev server in `kimaki tunnel` to get a public `https://<name>.<id>.opentunnel.xyz` URL, and run it in a named background `tuistory` session so you can wait for output, read logs and stop it later. Name the session descriptively (e.g. `projectname-dev`) and reuse it. Run `tuistory --help` first (or `bunx tuistory` when it is not installed). Invoke `kimaki` directly, not via `npx` or `bunx`.
 
-- Use random tunnel IDs by default. Pass `-t <id>` only for services that are safe to be publicly discoverable.
-- `kimaki tunnel` detects the local port from the child output. Pass `--port` only when the server prints no detectable localhost URL or port line.
-- `kimaki tunnel` injects `TRAFORO_URL` into the child process. Wire the app to it so OAuth callbacks, webhook URLs and absolute links use the public URL.
+- Use random names by default. Pass `-t <name>` only for services that are safe to be publicly discoverable.
+- `kimaki tunnel` detects the local port from the child output. Pass `--port` only when the server prints no detectable localhost URL.
+- `kimaki tunnel` injects `KIMAKI_TUNNEL_URL` into the child process. Wire the app to it so OAuth callbacks, webhook URLs and absolute links use the public URL.
+- TLS ends on this machine and the request reaches the app unchanged. Dev servers that check the `Host` header (Vite) must allow it, e.g. `server.allowedHosts: true` or `['.opentunnel.xyz']`.
+- The first run on a machine creates the tunnel and waits up to a minute for its certificate.
 
 ```bash
 # start in a named background session, wait for output, then read the tunnel URL
 tuistory launch "kimaki tunnel -- pnpm dev" -s myapp-dev
-tuistory -s myapp-dev wait "/ready|local|tunnel/i" --timeout 30000
+tuistory -s myapp-dev wait "/Tunnel: https/" --timeout 90000
 tuistory read -s myapp-dev
 
-# pass the public URL to the app (better-auth, Next.js, Vite; node reads process.env.TRAFORO_URL)
-tuistory launch "kimaki tunnel -- sh -c 'BETTER_AUTH_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
-tuistory launch "kimaki tunnel -- sh -c 'APP_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
-tuistory launch "kimaki tunnel -- sh -c 'VITE_BASE_URL=$TRAFORO_URL exec pnpm dev'" -s myapp-dev
+# pass the public URL to the app (better-auth, Next.js, Vite; node reads process.env.KIMAKI_TUNNEL_URL)
+tuistory launch "kimaki tunnel -- sh -c 'BETTER_AUTH_URL=\$KIMAKI_TUNNEL_URL exec pnpm dev'" -s myapp-dev
+tuistory launch "kimaki tunnel -- sh -c 'APP_URL=\$KIMAKI_TUNNEL_URL exec pnpm dev'" -s myapp-dev
 
-# custom tunnel ID (only for intentionally public-safe services)
+# fixed name (only for intentionally public-safe services)
 tuistory launch "kimaki tunnel -t holocron -- pnpm dev" -s holocron-dev
 
+# restart the server on a known port and keep the URL
+tuistory launch "kimaki tunnel -t holocron -p 5173 --kill -- pnpm dev --port 5173" -s holocron-dev
+
 # list sessions; stop with Ctrl+C, then close
 tuistory sessions
 tuistory -s myapp-dev press ctrl c

package/src/bot.ts

@@ -69,6 +69,8 @@ export type Bot = {
   allowAllUsers: boolean
   // Built-in skill ids (builtin-skills.ts) denied through the permissions of new sessions.
   disabledSkills: readonly string[]
+  // `kimaki --message-tool`: root sessions also reply through send_message; Discord hides their plain text.
+  messageTool: boolean
   features: BotFeatures
 }
 
@@ -134,6 +136,7 @@ export type SessionMarker = {
   fields: { readonly [key: string]: JsonValue }
   dataDir: string | null
   lockPort: number | null
+  messageTool: boolean
   // Explicit `kimaki send --parent-session`, so /resume keeps the instruction line.
   parentSessionId: string | null
   // The scheduled run stored at session.create, so /resume keeps the same instruction section.
@@ -147,7 +150,7 @@ function jsonObject(value: JsonValue | undefined): { readonly [key: string]: Jso
 export function readMarker(metadata: SessionMetadata | undefined): SessionMarker | null {
   const fields = jsonObject(metadata?.['kimaki'])
   if (!fields) return null
-  const { dataDir, lockPort, parentSessionId } = fields
+  const { dataDir, lockPort, messageTool, parentSessionId } = fields
   const task = jsonObject(fields['task'])
   const taskId = task?.['id']
   const cronExpr = task?.['cronExpr']
@@ -156,6 +159,7 @@ export function readMarker(metadata: SessionMetadata | undefined): SessionMarker
     fields,
     dataDir: typeof dataDir === 'string' ? dataDir : null,
     lockPort: typeof lockPort === 'number' ? lockPort : null,
+    messageTool: messageTool === true,
     parentSessionId: typeof parentSessionId === 'string' ? parentSessionId : null,
     task: typeof taskId === 'number'
       ? { id: taskId, cronExpr: typeof cronExpr === 'string' ? cronExpr : null, timezone: typeof timezone === 'string' ? timezone : null }
@@ -163,9 +167,15 @@ export function readMarker(metadata: SessionMetadata | undefined): SessionMarker
   }
 }
 
-// The marker fields that point the agent's `kimaki` calls at this bot.
-export function cliContext(bot: Bot) {
-  return { dataDir: bot.dataDir, lockPort: bot.lockPort }
+// The marker fields that follow this bot run: where the agent's `kimaki` calls
+// go, and whether the plugin gives the session send_message.
+export function cliContext(bot: Pick<Bot, 'dataDir' | 'lockPort' | 'messageTool'>) {
+  return { dataDir: bot.dataDir, lockPort: bot.lockPort, messageTool: bot.messageTool }
+}
+
+// False when the session marker was written by another bot run or with another --message-tool.
+export function markerIsCurrent(bot: Pick<Bot, 'dataDir' | 'lockPort' | 'messageTool'>, marker: SessionMarker): boolean {
+  return marker.dataDir === bot.dataDir && marker.lockPort === bot.lockPort && marker.messageTool === bot.messageTool
 }
 
 // Default model of new sessions in channels without their own (/model "All channels").

package/src/cli/bot.ts

@@ -1,6 +1,6 @@
 // Bot lifecycle and setup: the root command (start + onboarding), provider
 // login, tools (tunnel, tts), and bot status, logs, credentials and keys.
-// main.ts, onboarding.ts, traforo, SQLite and voice are loaded only by the
+// main.ts, onboarding.ts, tunnel.ts, SQLite and voice are loaded only by the
 // commands that run them (see the note in shared.ts).
 
 import { spawn, type ChildProcess } from 'node:child_process'
@@ -89,6 +89,7 @@ export function registerStartCommand(cli: Goke) {
     .option('--restart-onboarding', 'Choose credentials again')
     .option('--worktrees', 'Use a fresh Git worktree for new sessions unless the channel overrides it')
     .option('--allow-all-users', 'Every server member can use the bot (role "no-kimaki" still denies; provider login stays admin-only)')
+    .option('--message-tool', 'Discord shows only a concise reply the agent sends with a send_message tool; plain text stays visible in the OpenCode TUI')
     .option('--voice <name>', 'Voice of voice calls, saved for later starts (e.g. cove, juniper, sol). "default" resets it')
     .option('--disable-skills <list>', 'Built-in Kimaki skills to turn off: "all" or a comma separated list (kimaki-debug,kimaki-tunnel)')
     .option('--no-analytics', 'Disable anonymous usage analytics (same as KIMAKI_STRADA_ENABLED=0)')
@@ -219,6 +220,7 @@ export function registerStartCommand(cli: Goke) {
         autoWorktrees: Boolean(options.worktrees),
         allowAllUsers: Boolean(options.allowAllUsers),
         disabledSkills,
+        messageTool: Boolean(options.messageTool),
       })
       if (bot instanceof Error) failStartup(bot)
       // exit() keeps process.exitCode: the restart route sets RESTART_EXIT_CODE before its SIGTERM.
@@ -248,6 +250,7 @@ export function registerStartCommand(cli: Goke) {
           ...(options.worktrees ? ['--worktrees'] : []),
           ...(options.allowAllUsers ? ['--allow-all-users'] : []),
           ...(options.disableSkills ? ['--disable-skills', options.disableSkills] : []),
+          ...(options.messageTool ? ['--message-tool'] : []),
           ...(options.noAnalytics ? ['--no-analytics'] : []),
           ...(options.machineName ? ['--machine-name', options.machineName] : []),
         ] })
@@ -283,9 +286,9 @@ export function registerLoginCommands(cli: Goke) {
 
 // tunnel, tts
 export function registerToolCommands(cli: Goke) {
-  cli.command('tunnel', 'Run a command and expose its local port with a public URL. The child gets TRAFORO_URL')
+  cli.command('tunnel', 'Run a command and expose its local port with a public opentunnel.xyz URL. The child gets KIMAKI_TUNNEL_URL')
     .option('-p, --port <port>', 'Local port (default: read from the command output)')
-    .option('-t, --tunnel-id <id>', 'Fixed tunnel ID (default: random). Only for public-safe services')
+    .option('-t, --tunnel-id <id>', 'Fixed subdomain (default: random). Only for public-safe services')
     .option('--host <host>', 'Local host (default: localhost)')
     .option('-k, --kill', 'Kill the process on --port first')
     .example('kimaki tunnel -- pnpm dev')
@@ -294,8 +297,9 @@ export function registerToolCommands(cli: Goke) {
       const port = options.port ? Number(options.port) : undefined
       if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65_535)) fail(new Error(`Invalid --port ${options.port}`))
       if (!port && command.length === 0) fail(new Error('Pass a command after --, or --port <port>. Example: kimaki tunnel -- pnpm dev'))
-      const { runTunnel } = await import('traforo/run-tunnel')
-      await runTunnel({ port, command: command.length > 0 ? command : undefined, tunnelId: options.tunnelId, localHost: options.host, baseDomain: 'kimaki.dev', kill: options.kill })
+      const { runTunnel } = await import('../tunnel.ts')
+      const result = await runTunnel({ port, command: command.length > 0 ? command : undefined, name: options.tunnelId, host: options.host, kill: options.kill })
+      if (result instanceof Error) fail(result)
     })
 
   cli.command('tts [text]', 'Text to speech with OpenAI or Gemini. Reads stdin if no text is given')

package/src/cli-lock.e2e.test.ts

@@ -321,9 +321,9 @@ test('CLI help documents the supported P7 commands', async () => {
         -c, --channel <id>              Kimaki voice channel to post in (default in voice calls: KIMAKI_CHANNEL_ID)
 
       Tools:
-      tunnel                            Run a command and expose its local port with a public URL. The child gets TRAFORO_URL
+      tunnel                            Run a command and expose its local port with a public opentunnel.xyz URL. The child gets KIMAKI_TUNNEL_URL
         -p, --port <port>               Local port (default: read from the command output)
-        -t, --tunnel-id <id>            Fixed tunnel ID (default: random). Only for public-safe services
+        -t, --tunnel-id <id>            Fixed subdomain (default: random). Only for public-safe services
         --host <host>                   Local host (default: localhost)
         -k, --kill                      Kill the process on --port first
 
@@ -376,6 +376,7 @@ test('CLI help documents the supported P7 commands', async () => {
       --restart-onboarding          Choose credentials again
       --worktrees                   Use a fresh Git worktree for new sessions unless the channel overrides it
       --allow-all-users             Every server member can use the bot (role "no-kimaki" still denies; provider login stays admin-only)
+      --message-tool                Discord shows only a concise reply the agent sends with a send_message tool; plain text stays visible in the OpenCode TUI
       --voice <name>                Voice of voice calls, saved for later starts (e.g. cove, juniper, sol). "default" resets it
       --disable-skills <list>       Built-in Kimaki skills to turn off: "all" or a comma separated list (kimaki-debug,kimaki-tunnel)
       --no-analytics                Disable anonymous usage analytics (same as KIMAKI_STRADA_ENABLED=0)

package/src/event-loop.ts

@@ -67,6 +67,7 @@ export function createEventLoop({
   effects,
   recorder,
   analytics,
+  messageTool,
   onRunEnded,
   onTranscriptDue,
 }: {
@@ -76,6 +77,8 @@ export function createEventLoop({
   effects: EffectsRunner
   recorder: EventRecorder
   analytics: Analytics
+  // `kimaki --message-tool`: plain text of root sessions stays hidden (Prefs.messageTool).
+  messageTool: boolean
   // Every finished or failed run of a thread's root session (voice call notifications).
   onRunEnded: (run: RunEnded) => void
   // A root session stopped running (also after an interrupt): its transcript file is stale.
@@ -122,7 +125,7 @@ export function createEventLoop({
     if (!view) return
     const verbosity = state.verbosity[view.channelId] ?? verbosityFromV1(null)
     const contextLimits = modelLimits.get(view.directory)?.limits ?? {}
-    const result = reduce({ view, event, prefs: { verbosity, contextLimits } })
+    const result = reduce({ view, event, prefs: { verbosity, contextLimits, messageTool } })
     if (result.view !== view) store.setState((current) => ({ threads: { ...current.threads, [threadId]: result.view } }))
     effects.run(threadId, result.effects)
     if (event.type === 'session.moved' && event.data.sessionID === view.sessionId) void loadModelLimits(event.data.location.directory)

package/src/hello-thread.e2e.test.ts

@@ -177,6 +177,41 @@ test('message from a user without permission creates no thread', async () => {
   await expectNoNewThread({ channelId, before })
 })
 
+test('another bot needs the Kimaki role, and no-kimaki still denies it', async () => {
+  const { discord, channelId } = twin
+  const helperBotId = '200000000000000050'
+  const guildId = discord.guildId
+  await discord.prisma.user.create({ data: { id: helperBotId, username: 'helper-bot', bot: true } })
+  await discord.prisma.guildMember.create({ data: { guildId, userId: helperBotId } })
+  const member = { guildId_userId: { guildId, userId: helperBotId } }
+  const helper = discord.channel(channelId).user(helperBotId)
+
+  const before = (await discord.channel(channelId).getThreads()).length
+  await helper.sendMessage({ content: 'no role bot-marker hello-marker' })
+  await expectNoNewThread({ channelId, before })
+
+  const guild = await bot.discord.guilds.fetch(guildId)
+  const kimakiRole = await guild.roles.create({ name: 'Kimaki' })
+  const denyRole = await guild.roles.create({ name: 'no-kimaki' })
+  await discord.prisma.guildMember.update({ where: member, data: { roles: JSON.stringify([kimakiRole.id]) } })
+  await helper.sendMessage({ content: 'with role bot-marker hello-marker' })
+  const thread = await discord.channel(channelId).waitForThread({ predicate: (thread) => thread.name?.startsWith('with role bot-marker') ?? false })
+  await waitForFooter({ discord, threadId: thread.id })
+  expect(await discord.thread(thread.id).text()).toMatchInlineSnapshot(`
+    "--- from: assistant (helper-bot)
+    with role bot-marker hello-marker
+    --- from: assistant (TestBot)
+    -# *using deterministic-provider/deterministic-v2 ⋅ build*
+    Hello from the deterministic model.
+    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+  `)
+
+  const withRole = (await discord.channel(channelId).getThreads()).length
+  await discord.prisma.guildMember.update({ where: member, data: { roles: JSON.stringify([kimakiRole.id, denyRole.id]) } })
+  await helper.sendMessage({ content: 'denied bot-marker hello-marker' })
+  await expectNoNewThread({ channelId, before: withRole })
+})
+
 test('message in a channel without a project creates no thread', async () => {
   const { discord, unregisteredChannelId } = twin
   await discord.channel(unregisteredChannelId).user(TEST_USER_ID).sendMessage({ content: 'hello-marker' })

package/src/ingress.ts

@@ -1,6 +1,7 @@
 // Discord ingress (spec 4): gates every messageCreate, parses it into a Route
-// and calls actions. Gates, in order: bots (including ourselves), channel
-// ownership (only channels mapped in this machine's SQLite), permission.
+// and calls actions. Gates, in order: webhooks and our own messages (except
+// remote send envelopes), channel ownership (only channels mapped in this
+// machine's SQLite), permission (other bots need the Kimaki role).
 // Messages of one channel are handled in arrival order, after OpenCode is ready.
 //
 // Messages sent while the bot was offline are not fetched here: gateway-proxy
@@ -66,6 +67,8 @@ function authorCanUseKimaki(bot: Bot, message: Message<true>): Promise<boolean>
 function memberCanUseKimaki(bot: Pick<Bot, 'allowAllUsers'>, member: GuildMember): boolean {
   const roleNames = member.roles.cache.map((role) => role.name.toLowerCase())
   if (roleNames.includes('no-kimaki')) return false
+  // Other bots are opt-in: only the Kimaki role lets them in, never admin rights or --allow-all-users.
+  if (member.user.bot) return roleNames.includes('kimaki')
   if (bot.allowAllUsers) return true
   if (member.guild.ownerId === member.id) return true
   if (member.permissions.has(PermissionFlagsBits.Administrator)) return true
@@ -222,8 +225,7 @@ async function handleMessage(bot: Bot, message: Message) {
     })
     return
   }
-  if (message.author.bot) {
-    if (message.author.id !== bot.discord.user?.id) return
+  if (message.author.id === bot.discord.user?.id) {
     return handleRemoteEnvelope(bot, { message, channelId, threadId: thread?.id ?? null })
   }
   if (!(await authorCanUseKimaki(bot, message))) {
@@ -303,7 +305,9 @@ export function registerIngress(bot: Bot) {
   }
 
   bot.discord.on(Events.MessageCreate, (message) => {
-    if (message.author.bot && !message.embeds[0]?.footer?.text.startsWith(REMOTE_SEND_PREFIX)) return
+    // Webhooks have no member to check. Own messages only matter as remote send envelopes.
+    if (message.webhookId) return
+    if (message.author.id === bot.discord.user?.id && !message.embeds[0]?.footer?.text.startsWith(REMOTE_SEND_PREFIX)) return
     serialize(message.channelId, () => handleMessage(bot, message))
   })
   // Deleting a queued Discord message removes it from the queue.

package/src/main.ts

@@ -68,6 +68,8 @@ export type StartBotOptions = {
   allowAllUsers?: boolean
   // Built-in skill ids denied in new sessions (builtin-skills.ts).
   disabledSkills?: readonly string[]
+  // `kimaki --message-tool`: agents also reply through send_message; Discord hides their plain text.
+  messageTool?: boolean
 }
 
 export type BotHandle = Bot & {
@@ -146,7 +148,7 @@ export async function startBot(options: StartBotOptions): Promise<Error | BotHan
       if (result instanceof Error) logger.warn(`transcript of ${sessionId} not synced`, result)
     })
   }
-  const eventLoop = createEventLoop({ store, db, discord, effects, recorder, analytics: options.analytics, onRunEnded: voiceCalls.runEnded, onTranscriptDue })
+  const eventLoop = createEventLoop({ store, db, discord, effects, recorder, analytics: options.analytics, messageTool: options.messageTool ?? false, onRunEnded: voiceCalls.runEnded, onTranscriptDue })
   const loaded = await eventLoop.load()
   if (loaded instanceof Error) return loaded
   // Before the service is used, so a service started by ensure() loads it at once.
@@ -185,6 +187,7 @@ export async function startBot(options: StartBotOptions): Promise<Error | BotHan
     autoWorktrees: options.autoWorktrees ?? false,
     allowAllUsers: options.allowAllUsers ?? false,
     disabledSkills: options.disabledSkills ?? [],
+    messageTool: options.messageTool ?? false,
     features: { withSleepLock: createSleepLock(), waitForPlugin: createPluginWait({ opencode }), agentUi, voiceCalls },
   }
   const scheduler = createScheduler({

package/src/message-tool.e2e.test.ts

@@ -0,0 +1,45 @@
+// `kimaki --message-tool`: the plugin gives root sessions a send_message tool
+// and the thread shows only its text. The model's plain text stays hidden.
+
+import fs from 'node:fs'
+import { afterAll, beforeAll, expect, test } from 'vitest'
+
+import type { BotHandle } from './main.ts'
+import { scriptedTurn, seedProjectChannel, startOpencodeTestServer, startTestBot, startTwin, tempDataDir, TEST_USER_ID, waitForFooter, warmUp, type OpencodeTestServer, type TestTwin } from './test/harness.ts'
+
+const dataDir = tempDataDir()
+let server: OpencodeTestServer
+let twin: TestTwin
+let bot: BotHandle
+
+beforeAll(async () => {
+  const matchers = scriptedTurn({
+    marker: 'message-tool-marker',
+    steps: [{ id: 'message-call', tool: 'send_message', input: { text: 'Hello from **send_message**' } }],
+    finalText: 'hidden scratchpad text',
+  })
+  ;[server, twin] = await Promise.all([startOpencodeTestServer({ matchers }), startTwin()])
+  await seedProjectChannel({ dataDir, channelId: twin.channelId, guildId: twin.discord.guildId, directory: server.projectDirectory })
+  bot = await startTestBot({ dataDir, twin, server, messageTool: true })
+  await warmUp({ server })
+}, 60_000)
+
+afterAll(async () => {
+  await bot?.stop()
+  await Promise.all([server?.stop(), twin?.stop()])
+  fs.rmSync(dataDir, { recursive: true, force: true })
+})
+
+test('send_message text shows in Discord, plain text of the same turn does not', async () => {
+  await twin.discord.channel(twin.channelId).user(TEST_USER_ID).sendMessage({ content: 'message-tool-marker' })
+  const thread = await twin.discord.channel(twin.channelId).waitForThread({ timeout: 8_000 })
+  await waitForFooter({ discord: twin.discord, threadId: thread.id })
+  expect(await twin.discord.thread(thread.id).text()).toMatchInlineSnapshot(`
+    "--- from: user (tommy)
+    message-tool-marker
+    --- from: assistant (TestBot)
+    -# *using deterministic-provider/deterministic-v2 ⋅ build*
+    Hello from **send_message**
+    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+  `)
+})

package/src/plugin/index.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from '@opencode/client'
 import { Plugin, Skill } from '@opencode/plugin'
 import { Schema } from 'effect'
 import { execFile } from 'node:child_process'
@@ -7,7 +8,7 @@ import path from 'node:path'
 import { autostartBot } from '../autostart.ts'
 import { readBuiltinSkills } from '../builtin-skills.ts'
 import { fileEditTool, recordToolEdits } from '../file-edit-log.ts'
-import { turnContext } from '../system-prompt.ts'
+import { MESSAGE_MODE_INSTRUCTIONS, MESSAGE_TOOL, MESSAGE_TOOL_DESCRIPTION, MESSAGE_TOOL_INPUT, turnContext } from '../system-prompt.ts'
 
 const exec = promisify(execFile)
 
@@ -31,17 +32,32 @@ export default Plugin.define({
         }
       })
     }
-    async function marker(sessionID: string) {
+    // metadata.kimaki of the session, or of the thread's root for a subagent (`root: false`).
+    async function marker(sessionID: string): Promise<{ fields: Map<string, JsonValue>; root: boolean } | null> {
       const session = await ctx.session.get({ sessionID }).catch(() => null)
       const value: unknown = session?.metadata?.['kimaki']
       if (!value || typeof value !== 'object' || Array.isArray(value)) return null
       const current = new Map(Object.entries(value))
-      if (!session?.parentID) return current
+      if (!session?.parentID) return { fields: current, root: true }
       const parent = await ctx.session.get({ sessionID: session.parentID }).catch(() => null)
       const parentMarker = parent?.metadata?.['kimaki']
-      if (parentMarker && typeof parentMarker === 'object' && !Array.isArray(parentMarker) && parentMarker['threadId'] === current.get('threadId')) return marker(session.parentID)
-      return current
+      if (parentMarker && typeof parentMarker === 'object' && !Array.isArray(parentMarker) && parentMarker['threadId'] === current.get('threadId')) {
+        const root = await marker(session.parentID)
+        return root && { fields: root.fields, root: false }
+      }
+      return { fields: current, root: true }
     }
+    // Registered for every session; the context hook removes it outside message mode.
+    await ctx.tool.transform((editor) => {
+      editor.add({
+        name: MESSAGE_TOOL,
+        description: MESSAGE_TOOL_DESCRIPTION,
+        input: MESSAGE_TOOL_INPUT,
+        options: { codemode: false },
+        // Discord renders the call input (thread-reducer.ts); the tool itself does nothing.
+        execute: async () => ({ content: 'Message sent to the user.' }),
+      })
+    })
     // The git branch reaches the model as a synthetic message saved right before
     // the user prompt, only when it changed. Text in event.system would change the
     // cached prompt prefix on every branch switch. The prompt hook runs before
@@ -58,11 +74,28 @@ export default Plugin.define({
       if (last?.type === 'synthetic' && last.text === text) return
       await ctx.session.synthetic({ sessionID: event.sessionID, text, delivery: event.delivery, resume: false }).catch(() => undefined)
     })
+    // send_message only for root sessions of a bot started with --message-tool.
+    // Every request kind that carries the tool list gets the same tools and system
+    // text, so the prompt cache keeps hitting and no other session ever sees the tool.
+    async function applyMessageMode(event: { sessionID: string; tools: Record<string, unknown>; system: Array<{ type: 'text'; text: string }> }) {
+      const info = await marker(event.sessionID)
+      const messageMode = info?.root === true && info.fields.get('messageTool') === true
+      if (!messageMode) delete event.tools[MESSAGE_TOOL]
+      else event.system.push({ type: 'text', text: MESSAGE_MODE_INSTRUCTIONS })
+      return info
+    }
+    await ctx.session.hook('compaction', async (event) => {
+      await applyMessageMode(event)
+    })
+    await ctx.session.hook('generate', async (event) => {
+      await applyMessageMode(event)
+    })
     await ctx.session.hook('context', async (event) => {
       // The only prompt change for every session, TUI included. The ID never
       // changes in a session, so the cached prompt prefix stays stable.
       event.system.push({ type: 'text', text: `OpenCode session ID: ${event.sessionID}` })
-      if (!(await marker(event.sessionID))) return
+      const info = await applyMessageMode(event)
+      if (!info) return
       // The <discord-user> context of each prompt, built from its metadata, so the
       // stored text stays clean for the TUI and other clients. Same metadata, same
       // text on every request: the cached prompt prefix stays stable.
@@ -92,8 +125,8 @@ export default Plugin.define({
     await ctx.tool.hook('execute.before', async (event) => {
       if (event.tool !== 'shell' || !event.input || typeof event.input !== 'object' || Array.isArray(event.input)) return
       const info = await marker(event.sessionID)
-      const dataDir = info?.get('dataDir')
-      const lockPort = info?.get('lockPort')
+      const dataDir = info?.fields.get('dataDir')
+      const lockPort = info?.fields.get('lockPort')
       if (typeof dataDir !== 'string' || typeof lockPort !== 'number') return
       if (!('command' in event.input) || typeof event.input.command !== 'string') return
       const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`
@@ -102,7 +135,7 @@ export default Plugin.define({
     // File edits feed `kimaki session editors` (v1-compatible JSONL index).
     await ctx.tool.hook('execute.after', async (event) => {
       if (event.status !== 'completed' || !fileEditTool(event.tool)) return
-      const dataDir = (await marker(event.sessionID))?.get('dataDir')
+      const dataDir = (await marker(event.sessionID))?.fields.get('dataDir')
       if (typeof dataDir !== 'string') return
       // Plugins stay silent: a failed append only loses one index entry.
       const recorded = await recordToolEdits({ dataDir, directory: ctx.location.directory, sessionId: event.sessionID, tool: event.tool, input: event.input })

package/src/sessions.ts

@@ -12,6 +12,7 @@ import * as orm from 'drizzle-orm'
 import {
   cliContext,
   globalModel,
+  markerIsCurrent,
   oc,
   parseModel,
   projectOf,
@@ -273,7 +274,7 @@ export async function ensureSessionMarker(
   const info = await oc(bot, `get session ${sessionId}`, (client) => client.session.get({ sessionID: sessionId }))
   if (info instanceof Error) return info
   const marker = readMarker(info.metadata)
-  if (marker && marker.dataDir === bot.dataDir && marker.lockPort === bot.lockPort) return
+  if (marker && markerIsCurrent(bot, marker)) return
   // Instructions first: the marker means "set up", so a failure here is retried on the next input.
   if (!marker) {
     logger.log(`adopting legacy session ${sessionId} of thread ${thread.id}`)
@@ -303,7 +304,7 @@ export async function refreshCliContext(bot: Bot) {
     }
     const marker = readMarker(info.metadata)
     if (!marker) continue
-    if (marker.dataDir === bot.dataDir && marker.lockPort === bot.lockPort) continue
+    if (markerIsCurrent(bot, marker)) continue
     const metadata = { ...info.metadata, kimaki: { ...marker.fields, ...cliContext(bot) } }
     const result = await oc(bot, 'refresh Kimaki CLI context', (client) => client.session.update({ sessionID: sessionId, metadata }))
     if (result instanceof Error) return result

package/src/system-prompt.ts

@@ -645,6 +645,44 @@ export function turnContext(metadata: Readonly<Record<string, unknown>> | undefi
   return `${files}<discord-user name="${escapeAttribute(username)}" user-id="${userId}" message-id="${messageId}" thread-id="${threadId}" thread-name="${escapeAttribute(threadName)}" />`
 }
 
+// `kimaki --message-tool`: root sessions get this tool. Discord shows only its text;
+// plain text parts stay visible in the OpenCode TUI and other clients.
+// Wording adapted from Grok Bot's SendMessage tool.
+export const MESSAGE_TOOL = 'send_message'
+
+export const MESSAGE_TOOL_DESCRIPTION = dedent`
+  Send a concise reply to the user in the Discord thread. Discord shows only the text of send_message calls, not your plain text. Keep writing your normal plain text replies: they stay visible in the OpenCode terminal UI. Then repeat the part the Discord user needs as a short send_message, also for short replies like "Done" or "Yes, it does".
+
+  If you end a turn where the user waits on you without calling send_message, Discord shows silence.
+
+  Be very concise. Send meaningful beats only: a real result, a decision, a blocker, a change of plan. Do not narrate routine steps, retries or minor snags. Prefer fewer, higher-signal messages over a play-by-play, but never vanish into a long silent run.
+
+  An opening acknowledgement does not deliver the result. If you ran something for the user, send the actual result before you end the turn.
+
+  \`text\` is Discord markdown, shown like a normal message: headings, lists, code blocks, tables and <callout> blocks work. Send files with \`kimaki upload-to-discord\`, never through this tool. After your final send_message, end the turn.
+`
+
+export const MESSAGE_TOOL_INPUT = {
+  type: 'object',
+  properties: { text: { type: 'string', description: 'Markdown shown to the user in Discord. Keep it short.' } },
+  required: ['text'],
+  additionalProperties: false,
+}
+
+// Same text for the whole session (the prompt cache keeps hitting). It overrides
+// the "Discord output" rules of the instruction entry, which assume Discord shows text parts.
+export const MESSAGE_MODE_INSTRUCTIONS = dedent`
+  ## Discord shows only send_message
+
+  This overrides every rule above about what Discord shows: Discord does NOT show your plain text. Only the \`text\` of \`send_message\` tool calls reaches the Discord thread. The same session can also be open in the OpenCode terminal UI, which shows your plain text normally.
+
+  - Write your plain text replies as usual, in full. They are for the terminal UI.
+  - Then repeat a concise version as send_message, in Discord markdown: every reply, question and final answer, even one word of small talk.
+  - Where these instructions say "write the text first" before \`kimaki buttons\`, \`kimaki upload-request\` or \`kimaki sleep\`, call send_message with that text first.
+  - Never end a turn with a reply only in plain text.
+  - Never mention send_message, tool names or this rule to the user.
+`
+
 export type VoiceCallUser = { id: string; username: string }
 export type VoiceCallProject = { channelId: string; channelName: string; directory: string }
 // skill.list entry of OpenCode's global location; path is the absolute SKILL.md.

package/src/test/harness.ts

@@ -499,6 +499,7 @@ export async function startTestBot({
   analytics,
   clock,
   schedulerIntervalMs,
+  messageTool,
 }: {
   dataDir: string
   twin: TestTwin
@@ -519,6 +520,7 @@ export async function startTestBot({
   // Scheduling tests pass manualClock() and null, then call bot.scheduler.runDueTasks().
   clock?: Clock
   schedulerIntervalMs?: number | null
+  messageTool?: boolean
 }): Promise<BotHandle> {
   // What credential resolution saves in production; `kimaki project add` reads it.
   const credentials: Credentials = twin.discord.botToken.includes(':')
@@ -547,6 +549,7 @@ export async function startTestBot({
     analytics: analytics ?? disabledAnalytics,
     ...(clock && { clock }),
     ...(schedulerIntervalMs !== undefined && { schedulerIntervalMs }),
+    ...(messageTool && { messageTool }),
     ...(realtimeBaseUrls && { realtimeBaseUrls }),
     transcriptionBaseUrls: {
       ...(geminiBaseUrl && { gemini: geminiBaseUrl }),

package/src/test/replay.ts

@@ -28,6 +28,7 @@ export function rootSessionId(events: V2Event[]): string {
 export const DEFAULT_PREFS: Prefs = {
   verbosity: 'tools',
   contextLimits: { 'openai/gpt-6-luna': 400_000 },
+  messageTool: false,
 }
 
 export function replay({

package/src/thread-reducer.fixtures.test.ts

@@ -31,7 +31,7 @@ test('tools: names from tool.input.started, failed tool lines, read-only tools h
 test('tools at text verbosity: text, edits and errors only', () => {
   const { effects } = replay({
     events: loadFixture('tools.events.jsonl'),
-    prefs: { verbosity: 'text', contextLimits: {} },
+    prefs: { verbosity: 'text', contextLimits: {}, messageTool: false },
   })
   expect(effectLines(effects)).toMatchInlineSnapshot(`
     [
@@ -324,7 +324,7 @@ test('permission: two requests, the rejected one fails its tool call', () => {
 test('shell-background: background shell line even without side effects, finished line when its job ends', () => {
   const events = loadFixture('shell-background.events.jsonl')
   const view = emptyView({ sessionId: 'ses_ee56d6caeffech0rMI5NTnkky1', channelId: 'channel', directory: '/project', isNew: false })
-  const { effects, view: end } = replay({ events, view, prefs: { verbosity: 'tools', contextLimits: {} } })
+  const { effects, view: end } = replay({ events, view, prefs: { verbosity: 'tools', contextLimits: {}, messageTool: false } })
   expect(effectLines(effects)).toMatchInlineSnapshot(`
     [
       "» **user:** start a task in background that runs sleep 100",

package/src/thread-reducer.test.ts

@@ -55,6 +55,37 @@ test('text-only turn: banner, text, typing, footer with context percent', () =>
   expect(view.turn).toBe(null)
 })
 
+test('message mode: send_message shows as markdown, plain text only when the turn sent nothing', () => {
+  const turn = loadFixture('tools.events.jsonl').filter((event) => !event.type.startsWith('session.tool.'))
+  const prefs = { ...DEFAULT_PREFS, messageTool: true }
+  const textIndex = turn.findIndex((event) => event.type === 'session.text.ended')
+  const text = turn[textIndex]!
+  if (text.type !== 'session.text.ended') throw new Error('Expected text')
+  const call = { sessionID: text.data.sessionID, assistantMessageID: text.data.assistantMessageID, id: 'call_message' }
+  const durable = { aggregateID: text.data.sessionID, seq: 1, version: 1 as const }
+  const message: V2Event[] = [
+    { id: 'evt_message_input', created: text.created, durable, type: 'session.tool.input.started', data: { ...call, name: 'send_message' } },
+    { id: 'evt_message_called', created: text.created, durable, type: 'session.tool.called', data: { ...call, executed: false, input: { text: 'Visible **reply**' } } },
+  ]
+  const sent = replay({ prefs, events: [...turn.slice(0, textIndex), ...message, ...turn.slice(textIndex)] })
+  const silent = replay({ prefs, events: turn })
+  const lines = (effects: typeof sent.effects) => effectLines(effects).filter((line) => !line.startsWith('»') && !line.startsWith('[typing'))
+  expect({ sent: lines(sent.effects), silent: lines(silent.effects) }).toMatchInlineSnapshot(`
+    {
+      "sent": [
+        "-# *using openai/gpt-6-luna low ⋅ build*",
+        "Visible **reply**",
+        "-# *project ⋅ main ⋅ 17s ⋅ 6% ⋅ gpt-6-luna*",
+      ],
+      "silent": [
+        "-# *using openai/gpt-6-luna low ⋅ build*",
+        "Done. \`tmp-events/hello.txt\` contains \`hello world\`.",
+        "-# *project ⋅ main ⋅ 17s ⋅ 6% ⋅ gpt-6-luna*",
+      ],
+    }
+  `)
+})
+
 test('kimaki sleep in a turn makes its footer silent, the next turn notifies again', () => {
   const turn = loadFixture('tools.events.jsonl').filter((event) => !event.type.startsWith('session.tool.'))
   const end = turn.findIndex((event) => event.type === 'session.execution.succeeded')