@frontera-sdk/cli 1.46.6 → 1.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.46.6",
+  "version": "1.47.0",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,12 +38,15 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.46.6",
-    "@frontera-sdk/core": "1.46.6",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.251",
+    "@frontera-sdk/automation": "1.47.0",
+    "@frontera-sdk/core": "1.47.0",
+    "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@frontera-sdk/forge-contracts": "1.47.0",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/commands/forge/index-commands.ts

@@ -0,0 +1,4 @@
+import { forgeServe } from './serve'
+import type { Command } from '../types'
+
+export const forgeCommands: readonly Command[] = [forgeServe]

package/src/commands/forge/serve.ts

@@ -0,0 +1,144 @@
+import { randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { UsageError } from '../../errors'
+import { createLogger } from '../../forge/log'
+import { startForgeServer } from '../../forge/server'
+import { dataDir } from '../../paths'
+import { flagString, type Command, type CommandResult } from '../types'
+
+/**
+ * The Forge daemon. Started by the desktop shell with the platform origin and
+ * a token on a file descriptor; usable by hand for development with a printed
+ * token instead.
+ *
+ * Everything the shell needs is one JSON line on stdout — the port, the pid,
+ * the version — and nothing else ever goes there. Logs go to stderr and to
+ * `~/.local/share/frontera/forge/daemon.log`, so a "Forge stopped working"
+ * report can attach the file.
+ */
+
+const PARENT_CHECK_MS = 5_000
+
+async function cliVersion(): Promise<string> {
+  const stamped = process.env.FRONTERA_CLI_VERSION
+  if (stamped) return stamped
+  const pkg = await import('../../../package.json', { with: { type: 'json' } })
+  const version = (pkg.default as { version: string }).version
+  return import.meta.dir.includes('/node_modules/') ? version : `${version}-dev`
+}
+
+function readTokenFromFd(raw: string): string {
+  const fd = Number(raw)
+  if (!Number.isInteger(fd) || fd < 0) {
+    throw new UsageError(
+      '--token-fd must be a file descriptor number',
+      'the desktop shell passes `--token-fd 3`; omit the flag to have a token generated',
+    )
+  }
+  let token: string
+  try {
+    token = readFileSync(fd, 'utf8').trim()
+  } catch (err) {
+    throw new UsageError(
+      `could not read the token from fd ${fd}: ${err instanceof Error ? err.message : String(err)}`,
+      'the parent must open that descriptor, write the token and close it',
+    )
+  }
+  if (!token) throw new UsageError(`fd ${fd} carried no token`, 'the parent must write the token and close the descriptor')
+  return token
+}
+
+export const forgeServe: Command = {
+  meta: {
+    noun: 'forge',
+    verb: 'serve',
+    args: [],
+    flags: { port: 'string', origin: 'string', 'token-fd': 'string' },
+    summary: 'Run the Forge daemon the desktop app drives Claude Code and Codex through',
+    examples: [
+      'frontera forge serve',
+      'frontera forge serve --port 4820 --origin https://acme.frontera.example',
+    ],
+    // It is the thing other commands' credentials are resolved INSIDE of, per
+    // project directory, at turn time. Requiring one here would tie the
+    // daemon to whichever directory it happened to start in.
+    offline: true,
+  },
+
+  async run(ctx) {
+    const portRaw = flagString(ctx, 'port') ?? '0'
+    const port = Number(portRaw)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      throw new UsageError(
+        `--port must be a number between 0 and 65535, got ${portRaw}`,
+        'pass `--port 0` to let the OS choose one',
+      )
+    }
+
+    const originRaw = flagString(ctx, 'origin') ?? process.env.FRONTERA_FORGE_ORIGIN ?? null
+    const origin = originRaw ? originRaw.replace(/\/+$/, '') : null
+
+    const tokenFd = flagString(ctx, 'token-fd')
+    const token = tokenFd !== undefined ? readTokenFromFd(tokenFd) : randomBytes(32).toString('base64url')
+
+    const forgeDir = join(dataDir(), 'forge')
+    const log = createLogger(join(forgeDir, 'daemon.log'))
+    const version = await cliVersion()
+
+    const server = startForgeServer({
+      port,
+      token,
+      origin,
+      // Offline command: the dispatcher resolves no credential, so the origin
+      // the shell passed arrives as a flag, not on ctx.
+      apiUrl: flagString(ctx, 'api-url') ?? process.env.FRONTERA_API_URL ?? ctx.apiUrl,
+      version,
+      storePath: join(forgeDir, 'state.sqlite'),
+      log,
+    })
+
+    if (tokenFd === undefined) {
+      // A generated token has to be told to someone; stderr keeps stdout to
+      // its one line and keeps the secret out of the log file.
+      process.stderr.write(`[forge] token ${token}\n`)
+    }
+    if (!origin) log.warn('no --origin given: browsers cannot call this daemon (CORS); curl and the shell can')
+
+    process.stdout.write(`${JSON.stringify({ forge: { port: server.port, pid: process.pid, version } })}\n`)
+
+    let stopping = false
+    const shutdown = async (reason: string) => {
+      if (stopping) return
+      stopping = true
+      log.info(`stopping: ${reason}`)
+      try {
+        await server.stop()
+      } finally {
+        process.exit(0)
+      }
+    }
+
+    process.on('SIGTERM', () => void shutdown('SIGTERM'))
+    process.on('SIGINT', () => void shutdown('SIGINT'))
+
+    // With a token on an fd, a parent owns this process: its stdin closing is
+    // the parent going away, and a crash that closes nothing still shows up
+    // as a changed parent pid. Started by hand, stdin is often /dev/null and
+    // would "close" at once, so only the signals apply.
+    if (tokenFd !== undefined) {
+      process.stdin.on('end', () => void shutdown('stdin closed'))
+      process.stdin.on('error', () => void shutdown('stdin errored'))
+      process.stdin.resume()
+      const parent = process.ppid
+      setInterval(() => {
+        if (process.ppid !== parent) void shutdown('parent exited')
+      }, PARENT_CHECK_MS)
+    }
+
+    // The daemon ends by exiting, never by returning: a return would print a
+    // second line to stdout, and the contract is exactly one.
+    return new Promise<CommandResult>(() => {})
+  },
+}

package/src/commands/registry.ts

@@ -41,6 +41,7 @@ import { setupCommand } from './setup'
 import { authCommands } from './auth/index-commands'
 import { kitCommands } from './kit/index-commands'
 import { workspaceCommands } from './workspace/index-commands'
+import { forgeCommands } from './forge/index-commands'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -74,6 +75,7 @@ export const COMMANDS: readonly Command[] = [
   ...authCommands,
   ...kitCommands,
   ...workspaceCommands,
+  ...forgeCommands,
 
   appInit,
   appList,
@@ -149,6 +151,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   auth: 'Credential profiles — one per API key, selected by directory',
   kit: 'Optional project-local Frontera skills for Codex and Claude Code',
   workspace: 'Workspaces here — the ids --workspace takes',
+  forge: 'Forge — the local daemon the desktop app talks to',
 }
 
 export function nounSummary(noun: string): string {

package/src/flag-help.ts

@@ -54,6 +54,10 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   output: 'project-relative .ts path for generated output',
   check: 'verify generated output is current without writing it',
 
+  // Forge daemon
+  origin: 'browser origin allowed by CORS — the platform web origin; also FRONTERA_FORGE_ORIGIN',
+  'token-fd': 'file descriptor to read the bearer token from; omitted, a token is generated and printed',
+
   // Project resolution
   dir: 'project directory to act on (default: walk up from the working directory)',
 
@@ -66,7 +70,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
 
   // Apps
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
-  port: 'loopback port for the local App development server',
+  port: 'loopback port to listen on — the App development server, or the Forge daemon (0: any free port)',
   'no-open': 'start local development without opening a browser window',
   'no-install': 'scaffold without running `bun install` — for an offline machine or a sandbox',
   'no-git': 'scaffold without creating a repository and an initial commit',
@@ -171,6 +175,8 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   version: 'semver',
   framework: 'next|react',
   port: 'number',
+  origin: 'url',
+  'token-fd': 'fd',
   'expect-revision': 'hash',
   notes: 'text',
   description: 'text',

package/src/forge/adapter.ts

@@ -0,0 +1,108 @@
+import type { ForgeHostId, ForgeProject, ForgeThread, ForgeThreadStatus } from '@frontera-sdk/forge-contracts'
+import type { UIMessageChunk } from 'ai'
+
+/**
+ * The seam between the daemon and a coding host.
+ *
+ * T3's `ProviderAdapter` reduced to what the Forge surface uses: one turn in,
+ * a stream of AI SDK chunks out, an interrupt, and an answer to a permission
+ * prompt. Everything host-specific — the Agent SDK for Claude Code, the app
+ * server for Codex — stays behind this line, so the renderer never sees a
+ * native event and the run manager never learns a host's vocabulary.
+ */
+
+export type Emit = (chunk: UIMessageChunk) => void
+
+export type ApprovalDecision = 'approve' | 'deny'
+
+export interface TurnContext {
+  runId: string
+  threadId: string
+  /** Id of the assistant message this turn produces; the `start` chunk carries it. */
+  messageId: string
+  /** The user's text for this turn. */
+  text: string
+  project: ForgeProject
+  thread: ForgeThread
+  /** Platform API origin the daemon was started against; '' when unknown. */
+  apiUrl: string
+  /** Fires on cancel. */
+  signal: AbortSignal
+  /** The host's own session/thread id, once known — persisted for resume. */
+  setHostSessionId(id: string): void
+  setThreadStatus(status: ForgeThreadStatus): void
+}
+
+export interface TurnOutcome {
+  /** Null when the turn ended cleanly (including a user interrupt). */
+  error: string | null
+}
+
+export interface HostAdapter {
+  /** Resolves when the host's turn is over. Every chunk goes through `emit`. */
+  startTurn(ctx: TurnContext, emit: Emit): Promise<TurnOutcome>
+  interrupt(): Promise<void>
+  /** Answer a pending approval; false when the id is unknown to this adapter. */
+  respondApproval(approvalId: string, decision: ApprovalDecision): boolean
+}
+
+export type AdapterFactory = (host: ForgeHostId) => HostAdapter
+
+/** How long a permission prompt waits before it is treated as denied. */
+export const APPROVAL_TIMEOUT_MS = 10 * 60 * 1000
+
+interface PendingApproval {
+  resolve(decision: ApprovalDecision): void
+  timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * Parks a host's permission prompt until the person answers on the approvals
+ * route. Shared by adapters because the chunk it emits and the thread status
+ * it toggles are the same for every host — only the question differs.
+ */
+export class ApprovalBroker {
+  private readonly pending = new Map<string, PendingApproval>()
+
+  request(
+    ctx: Pick<TurnContext, 'setThreadStatus' | 'signal'>,
+    emit: Emit,
+    toolCallId: string,
+    timeoutMs = APPROVAL_TIMEOUT_MS,
+  ): Promise<ApprovalDecision> {
+    const approvalId = crypto.randomUUID()
+    return new Promise<ApprovalDecision>((resolve) => {
+      const settle = (decision: ApprovalDecision) => {
+        const entry = this.pending.get(approvalId)
+        if (!entry) return
+        clearTimeout(entry.timer)
+        this.pending.delete(approvalId)
+        ctx.signal.removeEventListener('abort', onAbort)
+        if (this.pending.size === 0) ctx.setThreadStatus('running')
+        resolve(decision)
+      }
+      const onAbort = () => settle('deny')
+      const timer = setTimeout(() => settle('deny'), timeoutMs)
+      this.pending.set(approvalId, { resolve: settle, timer })
+      ctx.signal.addEventListener('abort', onAbort, { once: true })
+      ctx.setThreadStatus('awaiting_approval')
+      emit({ type: 'tool-approval-request', approvalId, toolCallId } as UIMessageChunk)
+      if (ctx.signal.aborted) settle('deny')
+    })
+  }
+
+  respond(approvalId: string, decision: ApprovalDecision): boolean {
+    const entry = this.pending.get(approvalId)
+    if (!entry) return false
+    entry.resolve(decision)
+    return true
+  }
+
+  denyAll(): void {
+    for (const id of [...this.pending.keys()]) this.respond(id, 'deny')
+  }
+
+  get size(): number {
+    return this.pending.size
+  }
+}

package/src/forge/claude-adapter.ts

@@ -0,0 +1,205 @@
+import type { CanUseTool, Options, PermissionMode, Query } from '@anthropic-ai/claude-agent-sdk'
+
+import { resolveCredential } from '../config'
+import { ApprovalBroker, type ApprovalDecision, type Emit, type HostAdapter, type TurnContext, type TurnOutcome } from './adapter'
+import { ClaudeEventTranslator } from './claude-translator'
+import { forgeEnv, forgePath } from './env'
+import type { Logger } from './log'
+
+/**
+ * Claude Code as a Forge host, driven through `@anthropic-ai/claude-agent-sdk`.
+ *
+ * The SDK spawns the developer's own `claude` binary, so their login, settings
+ * and plugins (the Frontera plugin `frontera setup` installed) all apply. Two
+ * things make the spawned host a Frontera agent on top of that: the platform's
+ * MCP server injected with the profile's key, and `frontera` first on PATH.
+ *
+ * HOME is never overridden. T3 learnt that relocating HOME moves the macOS
+ * keychain lookup with it, and the spawned CLI then reports "not logged in"
+ * to a person who is. CLAUDE_CONFIG_DIR is inherited if the environment sets
+ * it, and otherwise left alone.
+ */
+
+const DENIED_MESSAGE = 'Denied by the user in Forge'
+
+/** The host's own file-editing tools; `acceptEdits` is named after these. */
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
+
+/** Effort levels the Agent SDK accepts. Anything else is dropped, not guessed. */
+const EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max'])
+
+/**
+ * Which prompts the mode answers on its own. The host already skips the
+ * prompts its `permissionMode` covers; this decides the ones that still reach
+ * us. Shell and platform tools stay behind a prompt under `acceptEdits`
+ * because both can write somewhere a file edit cannot, which is exactly what
+ * Claude Code itself means by "accept edits".
+ *
+ * `plan` is the SDK's own affair — it refuses the mutating tools upstream —
+ * so anything that arrives here under it is asked.
+ */
+export function autoAllows(mode: string, toolName: string): boolean {
+  if (mode === 'bypassPermissions') return true
+  if (mode === 'acceptEdits') return EDIT_TOOLS.has(toolName)
+  // `auto` is the SDK's own model classifier deciding. Anything it hands to
+  // the callback is a call it did NOT approve, so approving it here would
+  // quietly turn Auto into Full access.
+  return false
+}
+
+/** The thread's effort, when the SDK would accept it. */
+export function claudeEffort(effort: string | null): Options['effort'] | undefined {
+  if (!effort || !EFFORT_LEVELS.has(effort)) return undefined
+  return effort as NonNullable<Options['effort']>
+}
+
+/** A message that names the fix. The SDK's own errors rarely do. */
+export function describeClaudeFailure(err: unknown): string {
+  const raw = err instanceof Error ? err.message : String(err)
+  const lower = raw.toLowerCase()
+  if (lower.includes('enoent') || lower.includes('not found') || lower.includes('no such file')) {
+    return `Claude Code could not be started (${raw}). Install it from https://claude.com/claude-code, then run \`claude auth login\`.`
+  }
+  if (lower.includes('not logged in') || lower.includes('unauthori') || lower.includes('authentication') || lower.includes('401')) {
+    return `Claude Code is not signed in (${raw}). Run \`claude auth login\` and try again.`
+  }
+  return `Claude Code turn failed: ${raw}. If Claude Code is not signed in, run \`claude auth login\`.`
+}
+
+export interface ClaudeAdapterDeps {
+  log: Logger
+  /** Injected so a test never spawns the real binary. */
+  query?: (params: { prompt: string; options: Options }) => Query
+  which?: (bin: string) => string | null
+}
+
+export class ClaudeAdapter implements HostAdapter {
+  private readonly approvals = new ApprovalBroker()
+  private current: Query | null = null
+
+  constructor(private readonly deps: ClaudeAdapterDeps) {}
+
+  async startTurn(ctx: TurnContext, emit: Emit): Promise<TurnOutcome> {
+    const translator = new ClaudeEventTranslator(ctx.messageId)
+    const flush = (chunks: Iterable<import('ai').UIMessageChunk>) => {
+      for (const chunk of chunks) emit(chunk)
+    }
+
+    const which = this.deps.which ?? ((bin: string) => Bun.which(bin, { PATH: forgePath() }))
+    const claudePath = which('claude')
+    if (!claudePath) {
+      flush(translator.fail('Claude Code is not installed on this machine. Install it from https://claude.com/claude-code, then run `claude auth login`.'))
+      return { error: translator.errorText }
+    }
+
+    const mode = ctx.thread.mode
+    const canUseTool: CanUseTool = async (toolName, input, options) => {
+      if (autoAllows(mode, toolName)) return { behavior: 'allow', updatedInput: input }
+      const toolCallId = options.toolUseID ?? crypto.randomUUID()
+      flush(translator.ensureToolCall(toolCallId, toolName, input))
+      const decision = await this.approvals.request(ctx, emit, toolCallId)
+      if (decision === 'approve') return { behavior: 'allow', updatedInput: input }
+      return { behavior: 'deny', message: DENIED_MESSAGE }
+    }
+
+    const effort = claudeEffort(ctx.thread.effort)
+    const options: Options = {
+      cwd: ctx.project.root,
+      ...(ctx.thread.model ? { model: ctx.thread.model } : {}),
+      pathToClaudeCodeExecutable: claudePath,
+      systemPrompt: { type: 'preset', preset: 'claude_code' },
+      // The thread's mode IS the SDK's `permissionMode` — including `plan`,
+      // which passes straight through for the host to enforce.
+      permissionMode: mode as PermissionMode,
+      ...(effort ? { effort } : {}),
+      ...(mode === 'bypassPermissions' ? { allowDangerouslySkipPermissions: true } : {}),
+      ...(ctx.thread.hostSessionId ? { resume: ctx.thread.hostSessionId } : {}),
+      includePartialMessages: true,
+      settingSources: ['user', 'project', 'local'],
+      additionalDirectories: [ctx.project.root],
+      // Under bypassPermissions the SDK never consults the callback and warns
+      // loudly that it was given one.
+      ...(mode === 'bypassPermissions' ? {} : { canUseTool }),
+      env: forgeEnv(),
+      ...(await this.mcpServers(ctx)),
+    }
+
+    const query = this.deps.query ?? (await import('@anthropic-ai/claude-agent-sdk')).query
+    let q: Query
+    try {
+      q = query({ prompt: ctx.text, options })
+    } catch (err) {
+      flush(translator.fail(describeClaudeFailure(err)))
+      return { error: translator.errorText }
+    }
+    this.current = q
+
+    try {
+      for await (const message of q) {
+        if (ctx.signal.aborted && translator.isFinished) break
+        const chunks = translator.translate(message)
+        if (translator.sessionId && translator.sessionId !== ctx.thread.hostSessionId) {
+          ctx.setHostSessionId(translator.sessionId)
+        }
+        flush(chunks)
+        if (translator.isFinished) break
+      }
+      flush(translator.finish())
+    } catch (err) {
+      if (ctx.signal.aborted) {
+        flush(translator.finish())
+      } else {
+        this.deps.log.error(`claude turn ${ctx.runId} failed: ${err instanceof Error ? err.message : String(err)}`)
+        flush(translator.fail(describeClaudeFailure(err)))
+      }
+    } finally {
+      this.current = null
+      this.approvals.denyAll()
+    }
+
+    return { error: ctx.signal.aborted ? null : translator.errorText }
+  }
+
+  async interrupt(): Promise<void> {
+    this.approvals.denyAll()
+    const q = this.current
+    if (!q) return
+    try {
+      await q.interrupt()
+    } catch (err) {
+      this.deps.log.warn(`claude interrupt failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  respondApproval(approvalId: string, decision: ApprovalDecision): boolean {
+    return this.approvals.respond(approvalId, decision)
+  }
+
+  /**
+   * The platform's MCP server, with the key the project directory selects.
+   * No profile bound, or a profile for another deployment: the host still
+   * runs, just without platform tools — and the log says why.
+   */
+  private async mcpServers(ctx: TurnContext): Promise<Pick<Options, 'mcpServers'>> {
+    try {
+      const credential = await resolveCredential(
+        ctx.apiUrl ? { apiUrl: ctx.apiUrl } : {},
+        { cwd: ctx.project.root },
+      )
+      return {
+        mcpServers: {
+          frontera: {
+            type: 'http',
+            url: `${credential.apiUrl.replace(/\/+$/, '')}/v1/mcp/copilot`,
+            headers: { Authorization: `Bearer ${credential.token}` },
+          },
+        },
+      }
+    } catch (err) {
+      this.deps.log.warn(
+        `no platform MCP for ${ctx.project.root}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      return {}
+    }
+  }
+}

package/src/forge/claude-commands.ts

@@ -0,0 +1,136 @@
+/**
+ * The slash commands Claude Code advertises for a session.
+ *
+ * Follows T3 Code's `ClaudeProvider.ts`: start a `query()` whose prompt
+ * generator never yields, read `initializationResult()`, take the commands it
+ * advertises, then abort. Nothing reaches the model — the handshake is the
+ * whole point of the call.
+ *
+ * The seeded `compact` entry is theirs too, description included: it makes the
+ * list useful before any probe has returned, and on a machine where the probe
+ * fails there is still the one command everybody reaches for.
+ *
+ * `terminal_slash_commands` is filtered out on the SDK's own advice — it tags
+ * the commands whose behaviour is bound to the local terminal (`/exit`, the
+ * statusline) and says a non-terminal UI should hide them. Forge is one.
+ */
+import type { ForgeSlashCommand } from '@frontera-sdk/forge-contracts'
+
+import { forgeEnv } from './env'
+import type { Logger } from './log'
+
+const PROBE_TIMEOUT_MS = 15_000
+const CACHE_MS = 60_000
+
+/** T3 Code seeds this one so the menu is never empty. Same wording. */
+const SEEDED: ForgeSlashCommand[] = [
+  { name: 'compact', description: 'Summarize the conversation and reduce context usage' },
+]
+
+interface Probed {
+  at: number
+  commands: ForgeSlashCommand[]
+}
+
+const cache = new Map<string, Probed>()
+const inFlight = new Map<string, Promise<ForgeSlashCommand[]>>()
+
+function dedupe(commands: ForgeSlashCommand[]): ForgeSlashCommand[] {
+  const byName = new Map<string, ForgeSlashCommand>()
+  for (const command of commands) {
+    const name = command.name.trim().replace(/^\//, '')
+    if (!name || byName.has(name)) continue
+    byName.set(name, { ...command, name })
+  }
+  return [...byName.values()]
+}
+
+/**
+ * One handshake against the host, cancelled the moment it answers.
+ *
+ * Failure is not exceptional — the binary may be missing or logged out — and
+ * the caller still gets the seeded list, so a menu never breaks on it.
+ */
+async function probe(cwd: string, claudePath: string, log?: Logger): Promise<ForgeSlashCommand[]> {
+  const abort = new AbortController()
+  const timer = setTimeout(() => abort.abort(), PROBE_TIMEOUT_MS)
+  try {
+    const { query } = await import('@anthropic-ai/claude-agent-sdk')
+    const session = query({
+      // Never yields: the initialization response is all this call is for, and
+      // a prompt that resolved would send a turn to the model.
+      prompt: (async function* () {
+        await new Promise<void>((resolve) => {
+          if (abort.signal.aborted) resolve()
+          else abort.signal.addEventListener('abort', () => resolve(), { once: true })
+        })
+      })(),
+      options: {
+        cwd,
+        pathToClaudeCodeExecutable: claudePath,
+        abortController: abort,
+        env: forgeEnv(),
+      },
+    })
+
+    const init = (await session.initializationResult()) as {
+      commands?: Array<{ name?: string; description?: string; argumentHint?: string }>
+      terminal_slash_commands?: string[]
+    }
+    const terminalOnly = new Set(init.terminal_slash_commands ?? [])
+    const advertised = (init.commands ?? []).flatMap((command) => {
+      const name = command.name?.trim()
+      if (!name || terminalOnly.has(name)) return []
+      const description = command.description?.trim()
+      const hint = command.argumentHint?.trim()
+      return [
+        {
+          name,
+          ...(description ? { description } : {}),
+          ...(hint ? { argumentHint: hint } : {}),
+        } satisfies ForgeSlashCommand,
+      ]
+    })
+    return dedupe([...SEEDED, ...advertised])
+  } catch (error) {
+    log?.warn(`slash-command probe failed: ${error instanceof Error ? error.message : String(error)}`)
+    return dedupe(SEEDED)
+  } finally {
+    clearTimeout(timer)
+    if (!abort.signal.aborted) abort.abort()
+  }
+}
+
+/**
+ * What the composer lists, answered immediately.
+ *
+ * The seeded commands come back on the first call while the probe runs behind
+ * it; the richer list replaces them once the host has answered. A menu that
+ * waits on a subprocess is a menu that feels broken.
+ */
+export function commandsFor(cwd: string, claudePath: string | null, log?: Logger): ForgeSlashCommand[] {
+  if (!claudePath) return dedupe(SEEDED)
+
+  const hit = cache.get(cwd)
+  if (hit && Date.now() - hit.at < CACHE_MS) return hit.commands
+
+  if (!inFlight.has(cwd)) {
+    const pending = probe(cwd, claudePath, log)
+      .then((commands) => {
+        cache.set(cwd, { at: Date.now(), commands })
+        return commands
+      })
+      .finally(() => inFlight.delete(cwd))
+    inFlight.set(cwd, pending)
+  }
+
+  return hit?.commands ?? dedupe(SEEDED)
+}
+
+/** Exported for tests. */
+export function clearCommandCache(): void {
+  cache.clear()
+  inFlight.clear()
+}
+
+export { SEEDED as SEEDED_COMMANDS }