typeclaw 0.7.0 → 0.8.0

package/src/channels/router.ts

@@ -297,9 +297,30 @@ type LiveSession = {
   unsubProviderErrors: (() => void) | null
 }
 
+// `event` is null for command invocations that originated outside the inbound
+// pipeline (e.g. Discord native slash commands fired from listener.on
+// ('interaction_create')). Handlers that need a real inbound — for some
+// future hypothetical command like `/quote` — must guard on event !== null
+// instead of assuming it.
 type ChannelCommandContext = {
   live: LiveSession
-  event: InboundMessage
+  event: InboundMessage | null
+}
+
+export type ExecuteCommandResult =
+  | { kind: 'handled'; name: string }
+  | { kind: 'unknown-command'; name: string }
+  | { kind: 'no-live-session' }
+  | { kind: 'permission-denied' }
+  | { kind: 'ambiguous'; matchCount: number }
+
+// Identifies who invoked an adapter-driven command. Required so the router
+// can run the same channel.respond permission gate the text-prefix command
+// path runs (isChannelRespondDenied in route()). Without it, a guest user
+// in a public Slack channel could /stop an owner-created session that
+// happened to be live, bypassing role gating entirely.
+export type ExecuteCommandOptions = {
+  invokerId: string
 }
 
 export type SendSource = 'tool' | 'system'
@@ -345,6 +366,22 @@ export type ChannelRouter = {
   registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+  // Execute a command by name against an existing live session, bypassing
+  // the inbound classifier, engagement gate, debounce, and prompt queue.
+  // Used by adapters that receive commands through a native surface
+  // (Discord application-command interactions) rather than text. Gates
+  // the invoker on channel.respond — same permission gate the text-prefix
+  // command path runs — so a guest user cannot abort an owner's session
+  // by clicking the slash-command picker. Adapters MUST forward the
+  // invoker's platform-specific user id; without it the gate cannot
+  // identify the actor and resolves to 'guest' which denies. Returns:
+  //   - handled: command ran
+  //   - permission-denied: invoker lacks channel.respond
+  //   - no-live-session: channel has no active session
+  //   - ambiguous: multiple thread-keyed sessions in same chat (Slack);
+  //     caller should refuse to act rather than abort an arbitrary one
+  //   - unknown-command: name is not registered
+  executeCommand: (key: ChannelKey, name: string, options: ExecuteCommandOptions) => Promise<ExecuteCommandResult>
   // Lowered self-aliases (configured + implicit dir-name). Adapters use
   // this to anchor outbound threading on alias-only inbounds — see
   // slack-bot-classify.ts. Read live so a reload of `alias` propagates
@@ -1733,6 +1770,48 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const executeCommand = async (
+    key: ChannelKey,
+    name: string,
+    options: ExecuteCommandOptions,
+  ): Promise<ExecuteCommandResult> => {
+    const lowered = name.toLowerCase()
+    if (!commands.has(lowered)) {
+      return { kind: 'unknown-command', name: lowered }
+    }
+    // Permission gate runs BEFORE the live-session lookup so a guest user
+    // invoking /stop on a non-existent session gets 'permission-denied'
+    // (consistent answer regardless of session state) rather than leaking
+    // session presence via the 'no-live-session' vs 'permission-denied'
+    // distinction.
+    const partial: SessionOrigin = {
+      kind: 'channel',
+      adapter: key.adapter,
+      workspace: key.workspace,
+      chat: key.chat,
+      thread: key.thread,
+      lastInboundAuthorId: options.invokerId,
+    }
+    if (!permissions.has(partial, CORE_PERMISSIONS.channelRespond)) {
+      return { kind: 'permission-denied' }
+    }
+    const resolved = resolveLiveSessionForCommand(liveSessions, key)
+    if (resolved.kind === 'none') {
+      return { kind: 'no-live-session' }
+    }
+    if (resolved.kind === 'ambiguous') {
+      return { kind: 'ambiguous', matchCount: resolved.count }
+    }
+    const result = await commands.execute(`/${lowered}`, { live: resolved.session, event: null })
+    if (result.kind === 'handled') {
+      return { kind: 'handled', name: result.name }
+    }
+    // commands.execute can only return not-command (impossible — we pass a
+    // leading slash), unknown-command (impossible — we just checked has()),
+    // or handled. Any other outcome is a bug.
+    return { kind: 'unknown-command', name: lowered }
+  }
+
   return {
     route,
     send,
@@ -1752,6 +1831,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerFetchAttachment,
     unregisterFetchAttachment,
     fetchAttachment,
+    executeCommand,
     getSelfAliases: computeSelfAliases,
     stop,
     liveCount: () => liveSessions.size,
@@ -1912,6 +1992,52 @@ function consecutiveSendKey(chat: string, thread: string | null | undefined): st
   return `${chat}:${thread ?? ''}`
 }
 
+export type ResolveLiveSessionResult =
+  | { kind: 'found'; session: LiveSession }
+  | { kind: 'none' }
+  | { kind: 'ambiguous'; count: number }
+
+// Lookup policy for adapter-driven commands. Exact-key match always wins.
+// On miss, fall back to (adapter, workspace, chat) without thread — but
+// only when EXACTLY ONE non-destroyed candidate exists. Ambiguous matches
+// return 'ambiguous' so the caller can refuse to act rather than abort an
+// arbitrary session.
+//
+// Why the fallback: Slack slash commands carry channel_id but no thread_ts,
+// so a slash invocation from a thread-keyed live session would otherwise
+// report no-live-session. Discord doesn't hit this — Discord treats threads
+// as channels, so the exact-key path already resolves.
+//
+// Why ambiguity-rejection: "first match wins" map-iteration semantics would
+// abort an arbitrary thread when multiple thread-keyed sessions coexist in
+// one channel (plausible on Slack: bot mentioned in multiple threads). The
+// user's slash command picker doesn't know about threads; we don't know
+// which they meant; refusing is safer than guessing.
+export function resolveLiveSessionForCommand(
+  liveSessions: ReadonlyMap<string, LiveSession>,
+  key: ChannelKey,
+): ResolveLiveSessionResult {
+  const exact = liveSessions.get(channelKeyId(key))
+  if (exact && !exact.destroyed) return { kind: 'found', session: exact }
+
+  const matches: LiveSession[] = []
+  for (const candidate of liveSessions.values()) {
+    if (candidate.destroyed) continue
+    if (
+      candidate.key.adapter === key.adapter &&
+      candidate.key.workspace === key.workspace &&
+      candidate.key.chat === key.chat
+    ) {
+      matches.push(candidate)
+      if (matches.length > 1) {
+        return { kind: 'ambiguous', count: matches.length }
+      }
+    }
+  }
+  if (matches.length === 1) return { kind: 'found', session: matches[0]! }
+  return { kind: 'none' }
+}
+
 function normalizeSendText(text: string | undefined): string | undefined {
   if (text === undefined) return undefined
   if (text === '') return undefined

package/src/cli/role.ts

@@ -95,8 +95,13 @@ const listSub = defineCommand({
   },
   async run() {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
-    const { loadConfigSync } = await import('@/config')
-    const config = loadConfigSync(cwd)
+    // Diagnostic command: route through `loadConfigSyncOrDefaults` (same
+    // soft-fail pattern as PR #288's `status`/`doctor` and the follow-up for
+    // `model list`) so a broken `typeclaw.json` doesn't crash the very
+    // command users reach for to see which roles the agent thinks it has.
+    // Defaults have no `roles` block, so the empty-state hint fires next.
+    const { loadConfigSyncOrDefaults } = await import('@/config')
+    const config = loadConfigSyncOrDefaults(cwd)
     if (!config.roles || Object.keys(config.roles).length === 0) {
       console.log(c.dim('No roles declared. Run `typeclaw role claim` to add one, or edit typeclaw.json by hand.'))
       return

package/src/cli/tunnel.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { select, text, isCancel, cancel, log } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
-import { loadConfigSync } from '@/config'
+import { loadConfigSync, validateConfig } from '@/config'
 import { resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 import type { ClientMessage, ServerMessage, TunnelLogsServerMessage, TunnelSnapshot } from '@/shared'
@@ -168,6 +168,15 @@ export async function runTunnelAddFlow(
   args: AddArgs,
   prompts: TunnelPrompts = defaultPrompts,
 ): Promise<LiveResult<TunnelConfig>> {
+  // Strict gate before any read: a malformed or schema-invalid `typeclaw.json`
+  // would otherwise throw out of the subsequent `loadConfigSync` and surface
+  // as an uncaught exception instead of the clean exit-1-with-reason that
+  // every other LiveResult consumer expects. Same fence PR #288 documented
+  // for the `start`/`restart`/`reload` path: destructive paths route through
+  // `validateConfig` so the file's invariants are checked once, up front,
+  // and the rest of the flow can lean on them.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   if (config.tunnels.some((entry) => entry.name === args.name))
     return { ok: false, reason: `tunnel "${args.name}" already exists` }
@@ -206,6 +215,9 @@ export async function runTunnelAddFlow(
 }
 
 export function runTunnelRemoveFlow(cwd: string, args: RemoveArgs): LiveResult<{ removed: TunnelConfig }> {
+  // Same strict gate as `runTunnelAddFlow`. See the comment there for why.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   const tunnel = config.tunnels.find((entry) => entry.name === args.name)
   if (tunnel === undefined) return { ok: false, reason: `unknown tunnel: ${args.name}` }

package/src/cli/ui.ts

@@ -142,6 +142,27 @@ export const SLACK_APP_MANIFEST = {
       messages_tab_enabled: true,
       messages_tab_read_only_enabled: false,
     },
+    // Slash commands listed here appear in Slack's compose-box picker with
+    // their description as a tooltip. `url` is required by Slack's manifest
+    // schema even for Socket Mode bots, but is ignored at runtime when the
+    // app is in Socket Mode — Slack delivers `slash_commands` envelopes
+    // over the same WebSocket as message events. We point it at a
+    // deliberately-invalid placeholder (RFC 6761 reserved .invalid TLD)
+    // so a misconfigured (non-Socket-Mode) deployment fails fast rather
+    // than silently routing real slash invocations to a third-party URL.
+    slash_commands: [
+      {
+        command: '/stop',
+        description: 'Abort the current turn in this channel',
+        // usage_hint is intentionally omitted. Slack's manifest validator
+        // rejects an empty string ("Must be more than 0 characters") but
+        // the field is optional, so the cleanest answer is to leave it out
+        // rather than invent placeholder text for a command that takes no
+        // arguments.
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
+    ],
   },
   oauth_config: {
     scopes: {
@@ -150,13 +171,16 @@ export const SLACK_APP_MANIFEST = {
       // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
       // agent post replies, upload attachments, open DMs, pin messages, and
       // react to messages. `channels:join` lets the bot self-join public
-      // channels it's invited to discuss in.
+      // channels it's invited to discuss in. `commands` is required for
+      // Slack to deliver `slash_commands` envelopes — without it, slash
+      // commands registered in `features` would silently fail to route.
       bot: [
         'app_mentions:read',
         'channels:history',
         'channels:join',
         'channels:read',
         'chat:write',
+        'commands',
         'emoji:read',
         'files:read',
         'files:write',

package/src/config/index.ts

@@ -10,6 +10,7 @@ export {
   gitSchema,
   gitignoreSchema,
   loadConfigSync,
+  loadConfigSyncOrDefaults,
   loadPluginConfigsSync,
   migrateLegacyConfigShape,
   modelsSchema,

package/src/config/models-mutation.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 
 import { commitSystemFileSync } from '@/git/system-commit'
 
-import { configSchema, loadConfigSync, validateConfig } from './config'
+import { configSchema, loadConfigSyncOrDefaults, validateConfig } from './config'
 import {
   KNOWN_PROVIDERS,
   listKnownModelRefs,
@@ -33,8 +33,16 @@ export type ModelProfileEntry = {
 
 export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 
+// `listModelProfiles` is the read-only path behind `typeclaw model list`, a
+// diagnostic command. It routes through `loadConfigSyncOrDefaults` (same
+// soft-fail pattern as `typeclaw status` / `doctor`, PR #288) so a broken
+// `typeclaw.json` doesn't crash the command users reach for to see what
+// model config the agent thinks it has. Mutation paths (`setProfile`,
+// `addProfile`, `removeProfile`) stay on the strict gate via `validateConfig`
+// in `writeModels`, because writing through a broken-on-disk file would
+// silently land schema-invalid bytes.
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
-  const models = loadConfigSync(cwd).models
+  const models = loadConfigSyncOrDefaults(cwd).models
   const out: ModelProfileEntry[] = []
   for (const [profile, refs] of Object.entries(models)) {
     const headRef = refs[0]!

package/src/init/dockerfile.ts

@@ -394,14 +394,101 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
 // `~/.local/bin/claude` shim, which itself dereferences to the versioned
 // binary under `~/.local/share/claude/versions/<ver>/`, so upgrades via
 // `claude update` keep working without re-running this layer.
+// `~/.claude.json` is Claude Code's internal state file (NOT
+// `~/.claude/settings.json`, which is user-facing). On first run with an
+// empty or missing file, `claude` enters a TTY-only theme picker:
+// "Welcome to Claude Code … Choose the text style that looks best with
+// your terminal" with 7 options. The picker is unskippable via CLI
+// flags or env vars (no `--skip-onboarding`, no `--theme=dark`;
+// `IS_DEMO=1` exists but has documented side effects). The single
+// official escape hatch is writing `{"hasCompletedOnboarding": true,
+// "theme": "dark"}` to `~/.claude.json` before the first launch —
+// confirmed by Anthropic in multiple GitHub issues
+// (anthropics/claude-code#4714, #8938, #13827) and the empirical
+// answer used by metabase/metabase's `bin/claude-dangerous`, the
+// `claudeCodeAlDevContainer` feature, and dozens of other Docker
+// integrations.
+//
+// Without the pre-seed, the very first agent-driven `tmux new-session …
+// claude` invocation hangs on the theme picker: the agent's
+// `send-keys "<prompt>" Enter` arrives at the picker, gets interpreted
+// as picker input, and never reaches claude's actual prompt. The
+// `typeclaw-claude-code` skill is structured around a `Stop`-hook
+// sentinel, which never fires while the picker is up, so the polling
+// loop only learns of the hang at the 10-minute wall-clock budget.
+// Pre-seeding here costs ~85 bytes on disk and zero runtime overhead.
+//
+// SCOPE: this seed is NECESSARY but not SUFFICIENT for a fully
+// no-questions-asked first launch. Claude Code also shows two
+// post-seed modal dialogs that this file deliberately does NOT
+// pre-clear:
+//   1. "Detected a custom API key from environment. Do you want to use
+//      this API key?" — fires when ANTHROPIC_API_KEY is set. Options
+//      `[No (recommended), Yes]`, focus on No, picker does NOT wrap.
+//   2. Workspace trust ("Do you trust the files in this folder?") —
+//      fires on every new cwd. Options `[Yes, proceed, No, exit]`,
+//      focus on Yes.
+// Both are kept as runtime decisions handled by the
+// `typeclaw-claude-code` skill (see its "Driving the session" section,
+// "Clear startup dialogs" step, which uses dialog-specific keystrokes
+// because the picker doesn't wrap). Pre-seeding
+// `hasTrustDialogAccepted` or `customApiKeyResponses.approved` here
+// would silently widen the trust surface in ways the operator hasn't
+// consented to — the seed's job is strictly cosmetic-wizard removal,
+// not trust/permission preemption.
+//
+// `theme: "dark"` matches typeclaw's default TUI theme so the visual
+// transition between the typeclaw TUI and a tmux-attached claude pane
+// is consistent. Users on light terminals can override by editing
+// `~/.claude.json` (which persists across container restarts only if
+// they mount it; in the default container-ephemeral state it resets
+// to this default on every rebuild, which is fine — `claude` reads
+// the file at startup and the theme has no behavioral impact).
+//
+// `lastOnboardingVersion` is INTENTIONALLY OMITTED. ii-agent and a
+// few other templates ship `lastOnboardingVersion: "1.0.30"`, but
+// that value is version-coupled and goes stale on every Claude Code
+// release. Empirically against Claude Code 2.1.146, the current
+// `hasCompletedOnboarding: true` alone is honored without a version
+// pin. If a future Claude version starts re-triggering the picker
+// when the field is missing, capture `claude --version` output at
+// build time and inject it then — don't hardcode a stale value.
+//
+// `installMethod: "native"` and `numStartups: 1` match the shape
+// Claude Code itself writes after a clean first launch; keeping them
+// makes our seed indistinguishable from a real post-onboarding state,
+// which minimizes the chance of a future "if the file looks like
+// agent-pre-seed, redo onboarding" detection heuristic landing on us.
+//
+// Built via `JSON.stringify` rather than a hand-written string
+// literal so quote/escape bugs surface as TS errors at compile time,
+// not as a corrupt `~/.claude.json` discovered only when the build
+// runs. The `printf '%s\\n' '<JSON>'` shell pattern relies on the
+// JSON containing no single quotes (true by construction — JSON.
+// stringify only emits double quotes); a regression test parses the
+// emitted JSON back to confirm.
+const CLAUDE_CODE_ONBOARDING_SEED = JSON.stringify({
+  hasCompletedOnboarding: true,
+  theme: 'dark',
+  installMethod: 'native',
+  numStartups: 1,
+})
+
 function renderClaudeCodeInstallLayer(enabled: boolean): string {
   if (!enabled) return ''
   return `# Layer 5.6 (toggle): install Anthropic's Claude Code CLI. Opt-in via
 # typeclaw.json#docker.file.claudeCode. The skill \`typeclaw-claude-code\`
-# documents the auth + usage flow.
+# documents the auth + usage flow. Pre-seed ~/.claude.json so the first
+# launch skips the TTY-only theme picker; see CLAUDE_CODE_ONBOARDING_SEED
+# above for the rationale and what the seed deliberately does NOT cover.
+# The seed write runs LAST in the chain so the final layer state is
+# exactly the seeded config — independent of whether any earlier command
+# (or a future Claude version's \`--version\` smoke test) writes a
+# default \`~/.claude.json\` partway through the layer.
 RUN curl -fsSL https://claude.ai/install.sh | bash \\
  && ln -sf "$HOME/.local/bin/claude" /usr/local/bin/claude \\
- && claude --version > /dev/null`
+ && claude --version > /dev/null \\
+ && printf '%s\\n' '${CLAUDE_CODE_ONBOARDING_SEED}' > "$HOME/.claude.json"`
 }
 
 // Shared-library runtime deps Chrome for Testing needs to launch on amd64

package/src/shared/index.ts

@@ -21,4 +21,4 @@ export {
   type TunnelSnapshot,
 } from './protocol'
 
-export { formatLocalDate, formatLocalDateTime } from './local-time'
+export { formatLocalDate, formatLocalDateTime, resolveLocalTimezoneName } from './local-time'

package/src/shared/local-time.ts

@@ -19,3 +19,20 @@ function formatTimezoneOffset(date: Date): string {
   const abs = Math.abs(offsetMinutes)
   return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`
 }
+
+// IANA timezone name of the process (e.g. `Asia/Seoul`). Reads the resolved
+// zone from Intl, falling back to `UTC` if the runtime cannot resolve one —
+// this should never happen on Bun + tzdata-equipped containers, but the
+// fallback keeps the prompt renderable rather than throwing during session
+// creation. The returned name is what the agent shows the user when asked
+// "what time is it" — pairing the wall clock with a recognizable zone name
+// is what disambiguates "15:31 +09:00" from "15:31 KST" for a non-technical
+// reader.
+export function resolveLocalTimezoneName(): string {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    return zone && zone.length > 0 ? zone : 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}

package/src/skills/typeclaw-claude-code/SKILL.md

@@ -9,6 +9,12 @@ You can delegate work to Claude Code, Anthropic's official coding agent. The age
 
 This skill is for the case where Claude Code is the right tool: hard architecture work, multi-file refactors, deep code analysis, a second-opinion read on something you wrote. It is **not** for trivial edits — the round-trip cost (worktree setup + process spawn + auth check + TUI init + at least one full Claude turn) is 15–45 seconds and several thousand tokens of someone else's context window. Do trivial edits yourself.
 
+## Run the delegation inside `operator`, not inline
+
+Once you've decided Claude Code is the right tool, spawn the bundled `operator` subagent to do the actual driving — don't run the worktree setup, the tmux session, the polling loop, the multi-turn decision loop, and the cleanup inline in your own context. The whole loop typically takes several minutes and produces large amounts of intermediate output (TUI buffer captures, Stop sentinels per turn, JSONL transcript references); running it inline blocks the user from talking to you and burns through your context window before you ever get to the synthesis step. `operator` is write-capable and runs the same loop, then returns a clean final report (what claude produced, what `git diff main..cc-<id>` shows, what you should review). You ship the worktree, the prompt, and the safety constraints to operator; operator ships you back the diff and the summary.
+
+Exception: a quick sanity ping (`claude --version` to check the binary exists, `env | grep ANTHROPIC` to check auth). Those are single fast bash calls — do them inline. The "spawn through operator" rule applies to anything that runs `claude` itself as an interactive TUI.
+
 ## When to delegate to Claude Code
 
 Use Claude Code for:
@@ -79,6 +85,7 @@ Before you spawn `claude` for any real work:
 - **`docker.file.claudeCode: true`** in `typeclaw.json`. Verify with `which claude`; if missing, the toggle isn't on. Tell the user to enable it and `typeclaw start --build`.
 - **`docker.file.tmux: true`** (default `true`, but check). Verify with `which tmux`.
 - **Auth set up** — see above. Verify with `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='`.
+- **Onboarding pre-seeded.** The Dockerfile layer writes `~/.claude.json` with `hasCompletedOnboarding: true` and `theme: "dark"` so the first `claude` invocation skips the TTY-only theme picker / welcome wizard. **This is necessary but not sufficient** — even with the seed, Claude Code can still land on two other pre-prompt modals: the "Detected a custom API key from environment. Do you want to use this API key?" confirmation (when `ANTHROPIC_API_KEY` is set in env — default focus is **No**, so `Down Enter` is needed to accept) and the workspace trust dialog ("Do you trust the files in this folder?", default focus already on **Yes**, so a bare `Enter` accepts). The "Driving the session" section below clears them as a loop. If `~/.claude.json` is empty or missing entirely (custom mount, manual `rm`, a `CLAUDE_CONFIG_DIR` pointing at a fresh directory), the theme picker also reappears. Self-heal: `printf '%s\n' '{"hasCompletedOnboarding":true,"theme":"dark","installMethod":"native","numStartups":1}' > "$HOME/.claude.json"` before spawning, then retry.
 - **Agent folder is a git repo.** Verify with `git -C /agent rev-parse --is-inside-work-tree`. The worktree model below requires it. If the user's agent folder somehow isn't a repo (rare — `typeclaw init` scaffolds one), tell them to `git init && git add -A && git commit -m "initial"` first.
 - **No uncommitted changes that you care about.** `git -C /agent status --porcelain` should be clean, or you should be willing to set the working tree aside before delegating. The worktree is a separate checkout, so claude can't see your uncommitted changes — meaning claude operates on the last committed state. If the user wants claude to work with in-progress edits, commit them first (even on a WIP branch).
 
@@ -165,11 +172,29 @@ The minimum protocol — translate to your actual tool calls:
 1. Create the worktree, write the hook config (above).
 2. `tmux new-session -d -s cc-<id> -c /tmp/cc-<id> claude`.
 3. Wait ~3 seconds for the TUI to initialize.
-4. `tmux send-keys -t cc-<id> "<your prompt>" Enter`.
-5. **Poll** for `/tmp/cc-<id>/.done` in a 500ms-cadence loop with a wall-clock budget (default 10 minutes). On every iteration, also check `tmux has-session -t cc-<id>` — if the session died, claude crashed or auth failed.
-6. When `.done` exists: `rm .done`, read `sentinel.json`, examine `last_assistant_message`.
-7. Decide using the multi-turn loop below.
-8. When done: `tmux send-keys -t cc-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cc-<id>`.
+4. **Clear startup dialogs (BEFORE sending the task prompt).** Even with `~/.claude.json` pre-seeded, claude can land on one or both pre-prompt modals. Run this as a **loop**, not a one-shot: clearing one dialog can immediately reveal the next, and you must keep polling until claude's actual input prompt is visible (it renders a bottom-of-pane input box with a `╭` / `╰` border).
+
+   The two known modals, with the exact keystrokes for each (Claude Code's select widget does NOT wrap — pressing `Up` from the first option is a no-op, so the direction must match the dialog's option order):
+   - **Custom API key confirmation** — "Detected a custom API key from environment. Do you want to use this API key?" Fires when `ANTHROPIC_API_KEY` is set (exactly typeclaw's auth path). Options are `[No (recommended), Yes]` with focus initialized on **No**. Resolution: `tmux send-keys -t cc-<id> Down Enter` to advance to **Yes** and submit. Sending `Up Enter` would submit the **No** answer, which can persist as a rejection in `customApiKeyResponses.rejected` and break subsequent launches — never do that here.
+
+   - **Workspace trust** — "Do you trust the files in this folder?" Fires on first launch in any new cwd, so every fresh `/tmp/cc-<id>/` worktree triggers it. Options are `[Yes, proceed, No, exit]` with focus on the first option (**Yes**) by default. Resolution: bare `tmux send-keys -t cc-<id> Enter` — no arrow key needed. Always verify the pane text matches the trust dialog before pressing Enter; a misidentified modal would submit a different default.
+
+   Loop shape (translate to your tool calls):
+   1. Capture the last ~15 lines: `tmux capture-pane -t cc-<id> -p -S -15`.
+   2. If the capture contains the API key dialog text → `send-keys Down Enter`, sleep 500ms, goto 1.
+   3. If the capture contains the trust dialog text → `send-keys Enter`, sleep 500ms, goto 1.
+   4. If the capture shows the input box (`╭` border on a bottom line, no dialog text above it) → ready; exit the loop.
+   5. Otherwise sleep 500ms, goto 1. Apply a wall-clock budget of ~10 seconds; if the loop hasn't reached step 4 by then, abort with `/exit` and surface to the user — claude is in a state this skill doesn't model.
+
+   Do not use a fixed 2-second wait then send the prompt — cold-start and slow-disk cases can deliver a dialog at 2.5s+, and sending the task prompt into a modal corrupts the session.
+
+   **Safety note**: accepting workspace trust on a fresh `/tmp/cc-<id>/` worktree is the right call **only when its `HEAD` is the intended clean state** — typically the agent folder's last good commit on a branch the user controls. If the user just merged a third-party PR, pulled a remote branch, or checked out an untrusted ref, the worktree carries that content too and "trusting" it gives claude tool access on potentially hostile code. Before auto-accepting trust, sanity-check: if the user hasn't said something equivalent to "delegate this to Claude Code", or if you're not confident the current `HEAD` is one the user authored or reviewed, surface the trust dialog to them instead. Do NOT extend even a legitimate trust acceptance to in-session permission prompts (Bash, Edit, etc.) — those still need per-turn judgment per the multi-turn decision loop below.
+
+5. `tmux send-keys -t cc-<id> "<your prompt>" Enter`.
+6. **Poll** for `/tmp/cc-<id>/.done` in a 500ms-cadence loop with a wall-clock budget (default 10 minutes). On every iteration, also check `tmux has-session -t cc-<id>` — if the session died, claude crashed or auth failed.
+7. When `.done` exists: `rm .done`, read `sentinel.json`, examine `last_assistant_message`.
+8. Decide using the multi-turn loop below.
+9. When done: `tmux send-keys -t cc-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cc-<id>`.
 
 The full polling implementation, the ANSI-handling rules for `capture-pane` fallbacks, and the "tmux session died unexpectedly" recovery path are in `references/tmux-driving.md`.