Skip to content

Claude's answers, rendered: Markdown, math, charts and diagrams drawn in the Claude Code terminal. Independent project, not affiliated with Anthropic.

TypeScript claude-code-mod
18.2 KB
Raw Blame
// The plan of plan mode: Intelligent UI's own approval flow for the main loop's
// ExitPlanMode, and the plan drawn as pictures in its transcript row.
//
// The engine's approval dialog cannot be drawn by a plugin, so the mod asks
// first: the `tool.call` hook on ExitPlanMode asks its own question (decidePlan)
// before the engine raises PermissionRequest, and keeps the verdict. The
// PermissionRequest hook then answers with it at once (decisionOf), so the
// engine's dialog never shows. An allow is honoured for this tool only with
// `updatedInput`, and its `setMode` ends plan mode. The rendered plan is in
// the ExitPlanMode ToolUse row, which the engine draws above the question.
// The question waits for the plan's pictures; with none, the mod gives no
// verdict and the engine's dialog (which shows the plan's text) asks.
import type { EngineInterface, PermissionRequestDecision, RenderComponent, RenderElement, RenderViewport, ResolveInput } from 'claude-code'

import { COMPILE_TIMEOUT_MS, GUTTER, bulletOf } from './settings'
import { S, writesLive } from './state'
import { firstLine } from './markdown'
import type { Drawing } from './answer'
import { drawPages, type ShownLink } from './draw'
import { delay, runCmd, getenv, cat, exec, send, abort, ask, toast, uiResolve } from './api'
import { OPEN_TIMEOUT_MS, pathsOf } from './open'

// The question's chip and its two wordings.
export const PLAN_HEADER = 'Plan'
export const PLAN_QUESTION = 'Approve this plan?'
export const PLAN_QUESTION_EDITED = 'Approve the edited plan?'
// The options, in order (4 is the most the dialog takes).
export const PLAN_AUTO = 'Yes, auto-accept edits'
export const PLAN_MANUAL = 'Yes, manually approve edits'
export const PLAN_CLEAR = 'Yes, clear context + auto-accept'
export const PLAN_EDIT = 'Edit the plan'
// The question while a Mac's text editor has the plan file open (`open`
// does not wait), and its options.
export const PLAN_EDITING = 'Save the plan in the editor, then choose Done editing.'
export const PLAN_DONE = 'Done editing'
export const PLAN_REOPEN = 'Open the plan file again'
// The line above Intelligent UI's question (the dialog takes 12 rows at most
// around it, so the plan itself is in the ToolUse row above).
export const PLAN_ASK_LINE = 'Intelligent UI: the rendered plan is above'
// The line in the ToolUse row while the plan's pictures compile.
export const PLAN_DRAWING = 'Intelligent UI: drawing the plan...'
// The toast when a plan asked again after an edit has no pictures.
export const PLAN_EDITED_UNDRAWN = "Intelligent UI: the edited plan's pictures did not draw; it is the text you saved"
// What the model reads when the person rejects the plan (Esc) or types changes.
export const PLAN_REJECTED = 'The user rejected the plan.'
export const PLAN_FEEDBACK = 'The user wants changes to the plan:'
// The prompt that starts the new context of "clear context".
export const PLAN_IMPLEMENT = 'Implement this plan:'
// How long an editor may keep the plan file open (10 minutes, process.run's most).
export const EDIT_TIMEOUT_MS = 600000
// How long the plan waits for a Write or Edit of its file still running.
export const PLAN_WRITE_WAIT_MS = 5000
export const PLAN_WRITE_POLL_MS = 25
// How long the question waits for the plan's pictures: a compile and its
// retry in safe mode, and a moment in the queue.
export const PLAN_DRAW_WAIT_MS = 2 * COMPILE_TIMEOUT_MS + 5000
// The delay before "clear context" acts: `$.command.run` rejects inside a hook
// the turn waits on, so it runs detached once the call has resolved.
export const CLEAR_DELAY_MS = 50

// ---- Pure helpers -------------------------------------------------------------

// A path with `.`, `..` and repeated `/` resolved (no file system call).
export function normalPath(path: string): string {
  const isAbsolute = path.startsWith('/')
  const parts: string[] = []
  for (const part of path.split('/')) {
    if (part === '' || part === '.') continue
    if (part === '..') {
      if (parts.length && parts.at(-1) !== '..') parts.pop()
      else if (!isAbsolute) parts.push('..')
      continue
    }
    parts.push(part)
  }
  return (isAbsolute ? '/' : '') + parts.join('/')
}

// The plan an ExitPlanMode result shows, or null: none, an empty one, a
// subagent's or a teammate's (sent to its lead, not approved here).
export function planOf(output: unknown): string | null {
  if (!output || typeof output !== 'object') return null
  const o = output as { plan?: unknown; isAgent?: unknown; awaitingLeaderApproval?: unknown }
  if (o.isAgent === true || o.awaitingLeaderApproval === true) return null
  return typeof o.plan === 'string' && o.plan.trim() ? o.plan : null
}

// The plan an ExitPlanMode call carries (the engine adds it to the call, and
// to the row's input, before it asks), or '' when there is none.
export function planInputOf(input: unknown): string {
  const plan = input && typeof input === 'object' ? (input as { plan?: unknown }).plan : undefined
  return typeof plan === 'string' && plan.trim() ? plan : ''
}

// The plan file an ExitPlanMode call names, or ''.
export function planFileOf(input: unknown): string {
  const file = input && typeof input === 'object' ? (input as { planFilePath?: unknown }).planFilePath : undefined
  return typeof file === 'string' && file.startsWith('/') ? file : ''
}

// The plan a row of the call shows: '' for a subagent's or a teammate's
// result; else the result's (the approved text, also an edit in the
// engine's dialog), else the text the mod read or edited, else the call's.
export function planShownOf(edited: string | undefined, output: unknown, input: unknown): string {
  if (output && typeof output === 'object') {
    const o = output as { isAgent?: unknown; awaitingLeaderApproval?: unknown }
    if (o.isAgent === true || o.awaitingLeaderApproval === true) return ''
  }
  return planOf(output) ?? (edited?.trim() ? edited : planInputOf(input))
}

// A path as the person reads it: `~/...` under the home folder.
export function shortPath(path: string, home: string): string {
  const h = normalPath(home)
  return home && h !== '/' && path.startsWith(`${h}/`) ? `~${path.slice(h.length)}` : path
}

// The question's options: the edit option only when an editor can open the file.
export const planOptions = (canEdit: boolean): string[] => [PLAN_AUTO, PLAN_MANUAL, PLAN_CLEAR, ...(canEdit ? [PLAN_EDIT] : [])]

// What an answer means. Any other answer (the dialog's "Type something",
// "Chat about this") is the person's words about the plan.
export type PlanChoice = { kind: 'auto' | 'manual' | 'clear' | 'edit' } | { kind: 'feedback'; text: string }
export function choiceOf(answer: string, canEdit: boolean): PlanChoice {
  if (answer === PLAN_AUTO) return { kind: 'auto' }
  if (answer === PLAN_MANUAL) return { kind: 'manual' }
  if (answer === PLAN_CLEAR) return { kind: 'clear' }
  if (answer === PLAN_EDIT && canEdit) return { kind: 'edit' }
  return { kind: 'feedback', text: answer.trim() }
}

// The deny reason the model reads for the person's words: it stays in plan
// mode and revises.
export const feedbackOf = (text: string) => (text ? `${PLAN_FEEDBACK} ${text}` : `${PLAN_FEEDBACK.slice(0, -1)}.`)

// The verdict the mod's question gave, kept for the PermissionRequest that
// follows: approve (in a mode, with the plan, edited or not; `clear` starts a
// new context once the call resolves), or reject and stop the turn (Esc).
export type PlanVerdict =
  | { kind: 'allow'; mode: 'acceptEdits' | 'default'; plan: string; isEdited: boolean; clear: boolean }
  | { kind: 'deny'; message: string }

export function verdictOf(choice: PlanChoice, plan: string, isEdited: boolean): PlanVerdict | null {
  if (choice.kind === 'auto' || choice.kind === 'clear') return { kind: 'allow', mode: 'acceptEdits', plan, isEdited, clear: choice.kind === 'clear' }
  if (choice.kind === 'manual') return { kind: 'allow', mode: 'default', plan, isEdited, clear: false }
  return null
}

// The PermissionRequest decision of a verdict. An allow carries the input
// (the engine honours an allow of this tool only with `updatedInput`), the
// edited plan in it, and the mode that ends plan mode.
export function decisionOf(verdict: PlanVerdict, toolInput: unknown): PermissionRequestDecision {
  if (verdict.kind === 'deny') return { behavior: 'deny', message: verdict.message, interrupt: true }
  const input = toolInput && typeof toolInput === 'object' ? { ...(toolInput as Record<string, unknown>) } : {}
  if (verdict.isEdited) input.plan = verdict.plan
  return { behavior: 'allow', updatedInput: input, updatedPermissions: [{ type: 'setMode', mode: verdict.mode, destination: 'session' }] }
}

// The editor that opens the plan file: VS Code (`code --wait`) when it is on
// the PATH, else on a Mac the default text editor (`open -t`: it does not
// wait, as `open -W` waits until the whole app quits, not the window; the
// person says when they are done, PLAN_EDITING), else on Linux a GUI editor
// that waits (`gui`: its path and flag, LINUX_EDITORS). Not over ssh, where
// that editor is the remote computer's. A mod has no terminal, so no
// terminal editor; xdg-open does not wait, so it is not used.
export function editorArgv(o: { code: string; isMac: boolean; isRemote: boolean; gui?: readonly string[] }, file: string): string[] | null {
  if (o.code) return [o.code, '--wait', file]
  if (o.isMac && !o.isRemote) return ['open', '-t', file]
  if (!o.isMac && !o.isRemote && o.gui?.length) return [...o.gui, file]
  return null
}

// Whether the editor's command returns only once the file is closed (not `open`).
export const editorWaits = (argv: readonly string[]) => argv[0] !== 'open'

// The GUI editors on Linux that can wait until the file is closed, in the
// order they are looked for, with the flag that makes them wait.
export const LINUX_EDITORS: readonly (readonly [string, string])[] = [
  ['codium', '--wait'], ['zed', '--wait'], ['zeditor', '--wait'], ['subl', '--wait'], ['kate', '--block'], ['gedit', '--wait'], ['gvim', '-f'],
]
// Prints `name path` for the first editor of LINUX_EDITORS on the PATH.
const GUI_EDITOR_SH = `for c in ${LINUX_EDITORS.map(([name]) => name).join(' ')}; do p=$(command -v "$c" 2>/dev/null) && { echo "$c $p"; break; }; done`

// The editor of GUI_EDITOR_SH's output: its path and its flag; [] for none.
export function guiEditorOf(stdout: string): string[] {
  const m = /^(\S+) (\/.*)$/.exec(firstLine(stdout))
  const flag = m ? LINUX_EDITORS.find(([name]) => name === m[1])?.[1] : undefined
  return m && flag ? [m[2]!, flag] : []
}

// ---- The flow -----------------------------------------------------------------

// The `code` command's path ('' when none), looked up once per load.
async function findCode($: EngineInterface): Promise<string> {
  if (S.planCode !== null) return S.planCode
  S.planCode = (await pathsOf($, ['code'])).get('code') ?? ''
  return S.planCode
}

// On Linux with a display (X11 or Wayland), a GUI editor that waits
// ([] when none), looked up once per load.
async function findGuiEditor($: EngineInterface): Promise<string[]> {
  if (S.planGui !== null) return S.planGui
  let found: string[] = []
  if ((await getenv($, 'WAYLAND_DISPLAY')) || (await getenv($, 'DISPLAY'))) {
    for (const flag of ['-lc', '-c']) {
      const got = await exec($, ['sh', flag, GUI_EDITOR_SH], { timeoutMs: 5000 }).catch(() => null)
      found = got?.exitCode === 0 ? guiEditorOf(got.stdout) : []
      if (found.length) break
    }
  }
  S.planGui = found
  return found
}

// What the mod's question decided: a verdict for the PermissionRequest, the
// person's words (a deny of the call: Claude revises the plan), or nothing
// (`engine`: the plan's pictures did not draw, so the engine's dialog asks).
export type PlanOutcome = { kind: 'verdict'; verdict: PlanVerdict } | { kind: 'feedback'; message: string } | { kind: 'engine' }

// Asks the mod's question about the plan, as often as the person edits it.
// `plan` is the text to ask about, `callPlan` the one the call carried (an
// approval sends `plan` when they differ). `onEdited` gets each edited text
// (the ToolUse row draws it). `isDrawn` waits for a text's pictures: the
// first ask needs them (else the engine's dialog asks); an ask after an edit
// does not, as the engine's dialog would show the call's text and drop the
// edit (the person wrote it; a toast says so). Esc (the ask rejects; in a
// terminal session that is a dismissal) rejects the plan.
export async function decidePlan(
  $: EngineInterface,
  o: {
    plan: string; callPlan: string; file: string; isMac: boolean; isRemote: boolean
    onEdited: (plan: string) => void; isDrawn: (plan: string) => Promise<boolean>
  },
): Promise<PlanOutcome> {
  const code = o.file ? await findCode($) : ''
  const gui = o.file && !code && !o.isMac && !o.isRemote ? await findGuiEditor($) : []
  const argv = o.file ? editorArgv({ code, isMac: o.isMac, isRemote: o.isRemote, gui }, o.file) : null
  const canEdit = !!argv
  let plan = o.plan
  let isEdited = false
  for (let isFirst = true; ; isFirst = false) {
    // No pictures (a failed compile, a page too big over ssh, none in time): the engine's dialog shows the text.
    if (!(await o.isDrawn(plan))) {
      if (isFirst) return { kind: 'engine' }
      try {
        toast($, PLAN_EDITED_UNDRAWN, { timeoutMs: 8000 })
      } catch {}
    }
    const question = isEdited ? PLAN_QUESTION_EDITED : PLAN_QUESTION
    let answer: string
    S.planAsking = question
    try {
      answer = await ask($, question, { header: PLAN_HEADER, options: planOptions(canEdit) })
    } catch {
      return { kind: 'verdict', verdict: { kind: 'deny', message: PLAN_REJECTED } }
    } finally {
      S.planAsking = ''
    }
    const choice = choiceOf(answer, canEdit)
    if (choice.kind === 'feedback') return { kind: 'feedback', message: feedbackOf(choice.text) }
    if (choice.kind !== 'edit') return { kind: 'verdict', verdict: verdictOf(choice, plan, plan !== o.callPlan)! }
    const waits = editorWaits(argv!)
    await exec($, argv!, { timeoutMs: waits ? EDIT_TIMEOUT_MS : OPEN_TIMEOUT_MS }).catch(() => null)
    // `open` returns at once: the file is read when the person is done (Esc too).
    while (!waits) {
      const done = await ask($, PLAN_EDITING, { header: PLAN_HEADER, options: [PLAN_DONE, PLAN_REOPEN] }).catch(() => PLAN_DONE)
      if (done !== PLAN_REOPEN) break
      await exec($, argv!, { timeoutMs: OPEN_TIMEOUT_MS }).catch(() => null)
    }
    const text = await cat($, o.file).catch(() => null)
    if (typeof text === 'string' && text.trim() && text !== plan) {
      plan = text
      isEdited = text !== o.plan
      o.onEdited(plan)
    }
  }
}

// The plan file's text once no Write or Edit of it is still running (at most
// PLAN_WRITE_WAIT_MS): Claude may write the plan and call ExitPlanMode in one
// message, and the call then carries the file as it was before the write.
// 2.1.306 reads it again for the call, but the row's input stays the streamed copy.
// `fallback` when the file can't be read.
export async function currentPlan($: EngineInterface, file: string, fallback: string): Promise<string> {
  if (!file) return fallback
  for (let waited = 0; (writesLive.get(file) ?? 0) > 0 && waited < PLAN_WRITE_WAIT_MS; waited += PLAN_WRITE_POLL_MS) {
    await new Promise<void>(resolve => delay($, PLAN_WRITE_POLL_MS, resolve))
  }
  const text = await cat($, file).catch(() => null)
  return typeof text === 'string' && text.trim() ? text : fallback
}

// "Clear context": once the approved call has resolved, ends the turn, runs
// /clear and sends the plan as the new context's first prompt. Detached, as
// `$.command.run` rejects inside a hook the turn waits on.
export function scheduleClear($: EngineInterface, plan: string, turnId: string) {
  delay($, CLEAR_DELAY_MS, async () => {
    if (turnId) await abort($, { turnId }).catch(() => undefined)
    await runCmd($, { command: 'clear' }).catch(() => undefined)
    await send($, { text: `${PLAN_IMPLEMENT}\n\n${plan}`, asUser: true }).catch(() => undefined)
  })
}

// ---- Drawing ------------------------------------------------------------------

type Terminal = ResolveInput<RenderComponent, 'terminal'> & { viewport?: RenderViewport }

// The ExitPlanMode ToolUse row: the engine's row, then the plan's pages and
// their link rows (a dim line while they compile; the engine's row alone
// when they fail). `id`: the drawing's (picture select).
export function drawPlanUse($: EngineInterface, e: Terminal, row: RenderElement, drawing: Drawing, links: readonly ShownLink[] = [], id?: string): RenderElement {
  if (drawing.kind === 'text') return row
  const { Box, Text } = uiResolve($, e)
  return (
    <Box flexDirection="column">
      {row}
      {drawing.kind === 'pages' ? (
        drawPages($, e, drawing.result, drawing.bytes, { bullet: true, links, ...(id ? { id } : {}) })
      ) : (
        <Box marginTop={1} marginLeft={GUTTER}>
          <Text dimColor>{PLAN_DRAWING}</Text>
        </Box>
      )}
    </Box>
  )
}

// The approved plan's result row without the plan (the ToolUse row above
// draws it): the engine's header and the plan file's path.
export function drawPlanResult($: EngineInterface, e: Terminal, filePath?: string): RenderElement {
  const { Box, Text } = uiResolve($, e)
  const saved = filePath ? shortPath(filePath, S.env?.home ?? '') : ''
  return (
    <Box flexDirection="column" marginTop={1}>
      <Box flexDirection="row">
        <Box width={GUTTER} flexShrink={0}>
          <Text>{bulletOf(S.env?.isMac ?? true)}</Text>
        </Box>
        <Text>User approved Claude's plan</Text>
      </Box>
      {saved ? (
        <Box marginLeft={GUTTER}>
          <Text dimColor wrap="truncate-end">{`Plan saved to: ${saved} · /plan to edit`}</Text>
        </Box>
      ) : null}
    </Box>
  )
}

// The line Intelligent UI adds above its own question.
export function drawAskLine($: EngineInterface, e: ResolveInput<'AskUserQuestion', 'terminal'>, dialog: RenderElement): RenderElement {
  const { Box, Text } = uiResolve($, e)
  return (
    <Box flexDirection="column">
      <Text dimColor wrap="truncate-end">{PLAN_ASK_LINE}</Text>
      {dialog}
    </Box>
  )
}

// Whether an AskUserQuestion dialog is the mod's plan question now asked.
export function isPlanQuestion(questions: unknown, asking: string): boolean {
  if (!asking || !Array.isArray(questions) || questions.length !== 1) return false
  const q = questions[0] as { question?: unknown; header?: unknown } | null
  return !!q && q.question === asking && q.header === PLAN_HEADER
}