@cmodjs/core 4.0.2 → 4.1.0

package/src/runtime/widgets.ts

@@ -1,21 +1,22 @@
-import type { ElementTable, RenderElement } from 'claude-code'
-import { isObject, widgetsPath } from '../records.js'
+import type { ElementTable, MarkdownProps, RenderElement } from 'claude-code'
+import { isObject, storeChangedPath, widgetsPath } from '../records.js'
 import type { TurnData } from '../session/conversation.js'
 import { AbovePrompt, areas, BelowPrompt, TurnEnd, Working, type Area } from '../ui/areas.js'
 import { Box, drawWith } from '../ui/elements.js'
+import type { StyledAt } from '../ui/styles.js'
 import { ifMissing } from '../utils/paths.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import { cmodPluginName } from './dependencies.js'
 import type { DrawnParts } from './parts.js'
 import type { Router } from './router.js'
-import { partMethods, type PartsUpdate, type WidgetDeclaration } from './ui.js'
+import { partMethods, styledAt, viewportColumns, type PartsUpdate, type WidgetDeclaration } from './ui.js'
 
 export type WidgetRow = { readonly left: readonly string[]; readonly right: readonly string[] }
 
 export type WidgetLayout = { readonly areas: Readonly<Record<Area, readonly WidgetRow[]>>; readonly hidden: readonly string[] }
 
-export type PlacedWidget = { readonly key: string; readonly mod: string; readonly title: string; readonly areas: readonly Area[] }
+export type PlacedWidget = { readonly key: string; readonly mod: string; readonly title: string; readonly areas: readonly Area[] } & Pick<WidgetDeclaration, 'place'>
 
 export type Move = 'up' | 'down' | 'left' | 'right'
 
@@ -32,7 +33,8 @@ const promptIndent = 4
 
 const transcriptIndent = 2
 
-const terminalColumns = 80
+const widgetSizes = { fit: { flexShrink: 0 }, fill: { flexGrow: 1, flexShrink: 1, minWidth: 0 } } as const
+
 
 const separator = ''
 
@@ -44,7 +46,7 @@ export type Widgets = {
   reload(): Promise<void>
   recheck(): Promise<void>
   rows(area: Area, columns: number): RenderElement[]
-  draw(area: Area, table: ElementTable, columns: number, turn?: TurnData): Promise<RenderElement[]>
+  draw(area: Area, table: ElementTable, at: StyledAt, turn?: TurnData): Promise<RenderElement[]>
 }
 
 export function layoutOf(value: unknown): WidgetLayout {
@@ -99,7 +101,9 @@ function declarationsOf(input: unknown): WidgetDeclaration[] {
   const listed = isObject(input) && Array.isArray(input['widgets']) ? (input['widgets'] as unknown[]) : []
   return listed.filter(isObject).flatMap((each) => {
     const known = Array.isArray(each['areas']) ? (each['areas'] as unknown[]).filter((area): area is Area => (areas as readonly unknown[]).includes(area)) : []
-    return typeof each['id'] === 'string' && typeof each['title'] === 'string' && known.length > 0 ? [{ id: each['id'], title: each['title'], areas: known }] : []
+    const { side, size }: Record<string, unknown> = isObject(each['place']) ? each['place'] : {}
+    const place: NonNullable<WidgetDeclaration['place']> = { ...(side === 'left' || side === 'right' ? { side } : {}), ...(size === 'fit' || size === 'fill' ? { size } : {}) }
+    return typeof each['id'] === 'string' && typeof each['title'] === 'string' && known.length > 0 ? [{ id: each['id'], title: each['title'], areas: known, place }] : []
   })
 }
 
@@ -110,6 +114,7 @@ export function serveWidgets({
   report,
   turnClosedBy,
   parts,
+  markdownIn,
 }: {
   readonly claude: Claude
   readonly router: Router
@@ -117,6 +122,7 @@ export function serveWidgets({
   readonly report: (id: string, message: string, error: unknown) => void
   readonly turnClosedBy: (rowId: string) => TurnData | undefined
   readonly parts: DrawnParts
+  readonly markdownIn: (table: ElementTable, at: StyledAt) => ((props: MarkdownProps) => RenderElement) | undefined
 }): Widgets {
   const path = widgetsPath(store)
   const declared = new Map<string, readonly WidgetDeclaration[]>()
@@ -136,7 +142,7 @@ export function serveWidgets({
 
   const redraw = () => claude.ui.invalidate('ui.render')
 
-  const placed = (): PlacedWidget[] => [...builtInWidgets, ...[...declared].flatMap(([mod, list]) => list.map(({ id, title, areas: listed }) => ({ key: `${mod}/${id}`, mod, title, areas: listed })))]
+  const placed = (): PlacedWidget[] => [...builtInWidgets, ...[...declared].flatMap(([mod, list]) => list.map(({ id, title, areas: listed, place }) => ({ key: `${mod}/${id}`, mod, title, areas: listed, ...(place === undefined ? {} : { place }) })))]
 
   const change = (edit: (current: WidgetLayout) => WidgetLayout) => {
     saving = saving
@@ -148,6 +154,7 @@ export function serveWidgets({
         if (next !== current) {
           const kept = isObject(file) ? file : {}
           await claude.fs.write(path, `${JSON.stringify({ ...kept, ...next, areas: { ...(isObject(kept['areas']) ? kept['areas'] : {}), ...next.areas } }, null, 2)}\n`)
+          await claude.fs.write(storeChangedPath(store), '')
           stored = next
         }
         place()
@@ -164,9 +171,11 @@ export function serveWidgets({
   const withNewWidgets = (current: WidgetLayout) =>
     placed()
       .filter(({ key, mod }) => mod !== 'claude' && placedIn(current, key) === undefined && !placedKeys.has(key))
-      .reduce((next, { key, areas: [area = AbovePrompt] }) => {
+      .reduce((next, { key, areas: [area = AbovePrompt], place }) => {
         const [first, ...rest] = next.areas[area]
-        return { ...next, areas: { ...next.areas, [area]: [{ ...first, left: [...(first?.left ?? []), key], right: first?.right ?? [] }, ...rest] } }
+        const row = { ...first, left: first?.left ?? [], right: first?.right ?? [] }
+        const side = place?.side ?? 'left'
+        return { ...next, areas: { ...next.areas, [area]: [{ ...row, [side]: [...row[side], key] }, ...rest] } }
       }, current)
 
   const ask = async (mod: string) => {
@@ -215,7 +224,9 @@ export function serveWidgets({
 
   const elementFor = (key: string, area: Area, columns: number, turn: TurnData | undefined): RenderElement | undefined => {
     const widget = widgetOf(key)
-    return widget === undefined ? undefined : parts.element(widget.mod, cacheKey(key, area, columns, turn), `${key}:`, nameOf(widget), `widget:${key}`)
+    if (widget === undefined) return undefined
+    const element = parts.element(widget.mod, cacheKey(key, area, columns, turn), `${key}:`, nameOf(widget), `widget:${key}`)
+    return element === undefined ? undefined : Box({ ...widgetSizes[widget.place?.size ?? 'fit'], children: element })
   }
 
   const isHidden = (key: string) => layout.hidden.includes(key)
@@ -227,19 +238,20 @@ export function serveWidgets({
       const side = (keys: readonly string[]) => shown(keys).map((key) => elementFor(key, area, columns, turn)).filter((each) => each !== undefined)
       const left = side(row.left)
       const right = side(row.right)
-      return left.length + right.length === 0 ? [] : [Box({ justifyContent: 'space-between', width: columns, children: [Box({ gap: 2, children: left }), Box({ gap: 2, children: right })] })]
+      const group = (keys: readonly string[], children: readonly RenderElement[]) => Box({ flexShrink: shown(keys).some((key) => widgetOf(key)?.place?.size === 'fill') ? 1 : 0, minWidth: 0, columnGap: 2, children })
+      return left.length + right.length === 0 ? [] : [Box({ justifyContent: 'space-between', width: columns, columnGap: 2, children: [group(row.left, left), group(row.right, right)] })]
     })
 
   const keysIn = (area: Area) => layout.areas[area].flatMap((row) => shown([...row.left, ...row.right]))
 
-  const draw = async (area: Area, table: ElementTable, columns: number, turn?: TurnData): Promise<RenderElement[]> => {
-    await Promise.all(keysIn(area).map((key) => fill(key, area, columns, turn)))
-    return drawWith(table, () => rowsNow(area, columns, turn))
+  const draw = async (area: Area, table: ElementTable, at: StyledAt, turn?: TurnData): Promise<RenderElement[]> => {
+    await Promise.all(keysIn(area).map((key) => fill(key, area, at.columns, turn)))
+    return drawWith(table, () => rowsNow(area, at.columns, turn), markdownIn(table, at))
   }
 
   const rows = (area: Area, columns: number): RenderElement[] => {
     const started = keysIn(area).flatMap((key) => fill(key, area, columns, undefined) ?? [])
-    if (started.length > 0) void Promise.all(started).then(() => claude.ui.invalidate('ui.render'))
+    if (started.length > 0) void Promise.all(started).then(redraw)
     return rowsNow(area, columns, undefined)
   }
 
@@ -249,17 +261,17 @@ export function serveWidgets({
 
   router.add('ui.render', async (e, next) => {
     const table = claude.ui.resolve(e)
-    const columns = (e.viewport?.columns ?? terminalColumns) - transcriptIndent
-    if (e.component === 'AbovePrompt') return e.props.hasSurvey ? next(e) : below(table, await next(e), await draw(AbovePrompt, table, e.props.bodyColumns))
+    const inTranscript = styledAt(e, viewportColumns(e) - transcriptIndent)
+    if (e.component === 'AbovePrompt') return e.props.hasSurvey ? next(e) : below(table, await next(e), await draw(AbovePrompt, table, styledAt(e, e.props.bodyColumns)))
     if (e.component === 'PromptHint') {
-      const added = await draw(BelowPrompt, table, (e.viewport?.columns ?? terminalColumns) - promptIndent)
+      const added = await draw(BelowPrompt, table, styledAt(e, viewportColumns(e) - promptIndent))
       return isHidden(claudeHint) ? column(table, added) : below(table, await next(e), added)
     }
     if (e.component === 'SessionMode') return isHidden(claudeModes) ? column(table, []) : next(e)
-    if (e.component === 'Spinner') return below(table, await next(e), await draw(Working, table, columns))
+    if (e.component === 'Spinner') return below(table, await next(e), await draw(Working, table, inTranscript))
     if (e.component === 'TurnDuration') {
       const turn = turnClosedBy(e.requestId)
-      return below(table, await next(e), turn === undefined ? [] : await draw(TurnEnd, table, columns, turn))
+      return below(table, await next(e), turn === undefined ? [] : await draw(TurnEnd, table, inTranscript, turn))
     }
     return next(e)
   })
@@ -272,7 +284,7 @@ export function serveWidgets({
         const listed = declarationsOf(listing)
         const isNewList = JSON.stringify(listed) !== JSON.stringify(declared.get(mod) ?? [])
         declared.set(mod, listed)
-        if (isNewList) place()
+        if (isNewList) return place()
       }
       claude.ui.invalidate('ui.render')
     },

package/src/session/context/turn/message/attached-file.ts

@@ -0,0 +1,36 @@
+import type { MessageOf } from './message.js'
+
+export const AttachedFile = 'attachedFile'
+
+export type AttachmentType = 'contents' | 'reference' | 'change'
+
+export type AttachedFile = MessageOf<typeof AttachedFile> & {
+  readonly path: string
+  readonly attachmentType: AttachmentType
+  readonly text: string
+}
+
+export const attachmentTypes: Readonly<Record<string, AttachmentType>> = {
+  file: 'contents',
+  compact_file_reference: 'reference',
+  edited_text_file: 'change',
+}
+
+export function attachmentTypeOf(name: string | undefined): AttachmentType | undefined {
+  return name !== undefined && Object.hasOwn(attachmentTypes, name) ? attachmentTypes[name] : undefined
+}
+
+export function attachmentNameOf(type: AttachmentType): string {
+  const name = Object.keys(attachmentTypes).find((each) => attachmentTypes[each] === type)
+  if (name === undefined) throw new Error(`Claude Code writes no attachment row for a ${type} file.`)
+  return name
+}
+
+const readPath = /^Called the Read tool with the following input: \{.*?"file_path":\s*("(?:[^"\\]|\\["\\/bfnrt]|\\u[0-9a-fA-F]{4})*")/m
+
+const noted = /^Note: (.+?) (?:was read before the last conversation was summarized|changed on disk since you last read it)/m
+
+export function attachedPathOf(text: string): string {
+  const read = readPath.exec(text)?.[1]
+  return read === undefined ? (noted.exec(text)?.[1] ?? '') : (JSON.parse(read) as string)
+}

package/src/session/context/turn/message/message.ts

@@ -1,5 +1,6 @@
 import { isObject } from '../../../../records.js'
 import { Task } from '../../../goal/task.js'
+import { AttachedFile, attachedPathOf, attachmentTypeOf } from './attached-file.js'
 import { InstructionFile, isRulePath } from './instruction-file.js'
 import { modNote, modNoteBlock, modNotesIn, Note } from './note.js'
 import { Notice } from './notice.js'
@@ -12,7 +13,7 @@ import { ToolResult } from './tool-result.js'
 
 export const Message = 'message'
 
-export type MessageType = typeof Prompt | typeof Note | typeof Reply | typeof ToolCall | typeof ToolResult | typeof Skill | typeof InstructionFile | typeof Notice
+export type MessageType = typeof Prompt | typeof Note | typeof Reply | typeof ToolCall | typeof ToolResult | typeof Skill | typeof InstructionFile | typeof AttachedFile | typeof Notice
 
 export type MessageOf<Type extends MessageType> = {
   readonly id: string
@@ -24,7 +25,7 @@ export type MessageOf<Type extends MessageType> = {
   readonly task?: string
 }
 
-export type Message = Prompt | Note | Reply | ToolCall | ToolResult | Skill | InstructionFile | Notice
+export type Message = Prompt | Note | Reply | ToolCall | ToolResult | Skill | InstructionFile | AttachedFile | Notice
 
 export type Placed = 'session' | 'context' | 'turn' | 'task'
 
@@ -44,7 +45,7 @@ export type Row = {
   readonly model?: string
 }
 
-export const messageTypes: readonly MessageType[] = [Prompt, Note, Reply, ToolCall, ToolResult, Skill, InstructionFile, Notice]
+export const messageTypes: readonly MessageType[] = [Prompt, Note, Reply, ToolCall, ToolResult, Skill, InstructionFile, AttachedFile, Notice]
 
 export const skillPrefix = 'Base directory for this skill:'
 
@@ -63,8 +64,9 @@ export function rowOfLine(row: Readonly<Record<string, unknown>>): Row | undefin
   if (typeof uuid !== 'string' || typeof timestamp !== 'string' || typeof type !== 'string' || !rowTypes.includes(type)) return undefined
   const message = isObject(row['message']) ? row['message'] : {}
   const attachment = isObject(row['attachment']) ? row['attachment'] : {}
-  const content = type === 'attachment' ? attachment['content'] : type === 'system' ? row['content'] : message['content']
   const name = type === 'attachment' ? attachment['type'] : row['subtype']
+  const content = type === 'attachment' ? attachedContentOf(attachment) : type === 'system' ? row['content'] : message['content']
+  const path = attachment['path'] ?? attachment['filename']
   return {
     id: uuid,
     at: timestamp,
@@ -75,15 +77,21 @@ export function rowOfLine(row: Readonly<Record<string, unknown>>): Row | undefin
     content: blocksOf(content),
     ...(row['origin'] === undefined ? {} : { origin: row['origin'] }),
     ...(typeof row['cwd'] === 'string' ? { cwd: row['cwd'] } : {}),
-    ...(typeof attachment['path'] === 'string' ? { path: attachment['path'] } : {}),
+    ...(typeof path === 'string' ? { path } : {}),
     ...(typeof message['model'] === 'string' ? { model: message['model'] } : {}),
   }
 }
 
+function attachedContentOf(attachment: Readonly<Record<string, unknown>>): unknown {
+  if (attachment['type'] === 'edited_text_file') return attachment['snippet']
+  const file = isObject(attachment['content']) ? attachment['content']['file'] : undefined
+  return attachment['type'] === 'file' && isObject(file) ? file['content'] : attachment['content']
+}
+
 export function rowOfAppend(append: { readonly uuid: string; readonly door: string; readonly origin: unknown; readonly message: { readonly type: Row['type']; readonly name?: string; readonly isMeta?: true; readonly content: readonly unknown[] } }, at: string, cwd: string): Row {
   const { message, origin } = append
   const text = textOf(message.content)
-  const path = message.type === 'attachment' ? instructionPathOf(text) || undefined : undefined
+  const path = message.type === 'attachment' ? (attachmentTypeOf(message.name) !== undefined ? attachedPathOf(text) : instructionPathOf(text)) || undefined : undefined
   const model = isObject(origin) && origin['kind'] === 'model' && typeof origin['model'] === 'string' ? origin['model'] : undefined
   return {
     id: append.uuid,
@@ -113,7 +121,11 @@ function unplacedOf(row: Row, isInTask: boolean): Unplaced[] {
   const notesFrom = (each: readonly { readonly mod: string; readonly text: string }[]): Unplaced[] => each.map((note) => ({ ...base, type: Note, text: note.text, from: { type: Mod, name: note.mod } }))
   if (row.type === 'system') return row.name === 'turn_duration' || row.name === 'compact_boundary' || text === '' ? [] : [{ ...base, type: Notice, text }]
   if (row.type === 'attachment' && row.name === 'hook_additional_context') return notesFrom(row.content.flatMap((entry) => modNotesIn(typeof entry === 'string' ? entry : textOf([entry]))))
-  if (row.type === 'attachment') return row.name === 'nested_memory' ? [{ ...base, type: InstructionFile, path: row.path ?? '', text, isRule: isRulePath(row.path ?? '') }] : []
+  if (row.type === 'attachment' && row.name === 'nested_memory') return [{ ...base, type: InstructionFile, path: row.path ?? '', text, isRule: isRulePath(row.path ?? '') }]
+  if (row.type === 'attachment') {
+    const attachmentType = attachmentTypeOf(row.name)
+    return attachmentType === undefined ? [] : [{ ...base, type: AttachedFile, path: row.path ?? '', attachmentType, text }]
+  }
   if (isModNotesRow(row)) return notesFrom(modNotesIn(text))
   if (row.type === 'assistant') {
     return row.content.filter(isObject).flatMap((block): Unplaced[] => {
@@ -212,6 +224,7 @@ export function searchText(message: Unplaced): string {
   if (message.type === ToolCall) return [message.name, ...stringsIn(message.input).map((value) => value.slice(0, toolValueChars))].join('\n')
   if (message.type === ToolResult) return ''
   if (message.type === InstructionFile) return `${message.path}\n${message.text}`
+  if (message.type === AttachedFile) return message.path
   return message.text
 }
 

package/src/session/conversation.ts

@@ -6,7 +6,7 @@ import { ToolCall } from './context/turn/message/tool-call.js'
 import { ToolResult } from './context/turn/message/tool-result.js'
 import { TurnEnd, TurnStart, type Turn } from './context/turn/turn.js'
 import { GoalChange } from './goal/goal.js'
-import { Task, TaskEnd, TaskStart } from './goal/task.js'
+import { Task, TaskEnd, TaskStart, type TaskStatus } from './goal/task.js'
 import type { UsageChange, Usage } from './session.js'
 
 export type SessionData = {
@@ -28,7 +28,23 @@ export type TurnData = Pick<Turn, 'prompt' | 'context' | 'openedAt' | 'closedAt'
 
 export type TurnEnding = Pick<Turn, 'answer' | 'reason' | 'failure'>
 
-export type TaskData = Pick<Task, 'id' | 'title' | 'openedBy' | 'openedAt' | 'closedAt'> & { readonly agentType: string; readonly model?: string; readonly parent?: string }
+export type TaskData = Pick<Task, 'id' | 'title' | 'openedBy' | 'openedAt' | 'closedAt' | 'status' | 'name' | 'spawnedBy' | 'isBackground'> & { readonly agentType?: string; readonly model?: string; readonly parent?: string; readonly forkedFrom?: string }
+
+export const forkAgentType = 'fork'
+
+export function ownerOfSpawn(agentType: string | undefined, session: string): Pick<TaskData, 'agentType' | 'forkedFrom'> {
+  return agentType === forkAgentType ? { forkedFrom: session } : { agentType: agentType ?? 'general-purpose' }
+}
+
+type Agent = { readonly id: string; readonly status: TaskStatus; readonly name?: string; readonly spawnedBy?: string }
+
+export function tasksWithAgents(tasks: readonly TaskData[], agents: readonly Agent[]): TaskData[] {
+  const byId = new Map(agents.map((agent) => [agent.id, agent]))
+  return tasks.map((task) => {
+    const agent = byId.get(task.id)
+    return agent === undefined ? task : { ...task, status: agent.status, ...(agent.name === undefined ? {} : { name: agent.name }), ...(agent.spawnedBy === undefined ? {} : { spawnedBy: agent.spawnedBy }) }
+  })
+}
 
 export type RunningTask = TaskData & { readonly context: number; readonly contextOpenedAt?: string }
 
@@ -60,6 +76,7 @@ type OpenCall = Pick<ToolCall, 'name' | 'input' | 'cwd'>
 export type Conversation = {
   add(row: Row, task?: string): SessionChange[]
   startTask(task: TaskData): SessionChange[]
+  endTask(task: TaskData, at: string): SessionChange[]
   startContext(at: string): SessionChange[]
   endTurn(at: string, ending: TurnEnding, task?: string): SessionChange[]
   changeGoal(text: string): SessionChange[]
@@ -117,7 +134,7 @@ export function createConversation(start: ConversationState): Conversation {
     return [{ type: TurnEnd, turn: ended }]
   }
 
-  const endTask = (call: string, at: string, only?: string): SessionChange[] => {
+  const endCall = (call: string, at: string, only?: string): SessionChange[] => {
     const opened = [...tasks.values()].filter((each) => each.openedBy === call && (only === undefined || each.id === only))
     if (opened.length === 0) {
       if (agentCalls.has(call)) endedCalls.set(call, at)
@@ -168,10 +185,10 @@ export function createConversation(start: ConversationState): Conversation {
         } as Message
         changes.push({ type: Message, message: placed })
         if (placed.type === ToolCall && agentTools.includes(placed.name)) agentCalls.add(placed.callId)
-        if (placed.type === ToolResult && agentCalls.has(placed.callId) && !String(placed.output).startsWith(asyncLaunch)) changes.push(...endTask(placed.callId, row.at))
+        if (placed.type === ToolResult && agentCalls.has(placed.callId) && !String(placed.output).startsWith(asyncLaunch)) changes.push(...endCall(placed.callId, row.at))
         if (placed.type === Note && placed.from.type === Task) {
           const call = tagOf(textOf(row.content), 'tool-use-id')
-          if (call !== undefined && agentCalls.has(call)) changes.push(...endTask(call, row.at, tagOf(textOf(row.content), 'task-id')))
+          if (call !== undefined && agentCalls.has(call)) changes.push(...endCall(call, row.at, tagOf(textOf(row.content), 'task-id')))
         }
       }
       return changes
@@ -183,9 +200,16 @@ export function createConversation(start: ConversationState): Conversation {
       agentCalls.add(data.openedBy)
       const changes: SessionChange[] = [{ type: TaskStart, task: started }]
       const endedAt = endedCalls.get(data.openedBy)
-      if (endedAt !== undefined) changes.push(...endTask(data.openedBy, endedAt, data.id))
+      if (endedAt !== undefined) changes.push(...endCall(data.openedBy, endedAt, data.id))
       return changes
     },
+    endTask(data, at) {
+      const open = tasks.get(data.id) ?? { ...data, context }
+      if (open.closedAt !== undefined) return []
+      const ended = { ...open, closedAt: at }
+      tasks.set(data.id, ended)
+      return [...endTaskTurn(data.id, at), { type: TaskEnd, task: ended }]
+    },
     startContext,
     endTurn: (at, ending, task) => (task === undefined ? endTurn(at, ending) : endTaskTurn(task, at, ending)),
     changeGoal,

package/src/session/goal/task.ts

@@ -7,6 +7,8 @@ export const TaskStart = 'taskStart'
 
 export const TaskEnd = 'taskEnd'
 
+export type TaskStatus = 'pending' | 'running' | 'waiting' | 'idle' | 'completed' | 'failed' | 'killed'
+
 export type Task = RecordPart & {
   readonly id: string
   readonly title: string
@@ -14,6 +16,10 @@ export type Task = RecordPart & {
   readonly openedBy: string
   readonly openedAt: string
   readonly closedAt?: string
+  readonly status?: TaskStatus
+  readonly name?: string
+  readonly spawnedBy?: string
+  readonly isBackground?: true
   tasks(): Promise<Task[]>
   messages(): Promise<Message[]>
 }

package/src/session/session.ts

@@ -2,6 +2,7 @@ import type { Subscription } from '../utils/subscription.js'
 import type { Matcher } from '../utils/matcher.js'
 import type { Sender } from './context/turn/message/sender.js'
 import type { Context, ContextEnd, ContextStart } from './context/context.js'
+import type { AttachedFile } from './context/turn/message/attached-file.js'
 import type { InstructionFile } from './context/turn/message/instruction-file.js'
 import type { Message, MessageType } from './context/turn/message/message.js'
 import type { Note } from './context/turn/message/note.js'
@@ -31,6 +32,7 @@ export type SessionPayload = {
   readonly toolResult: ToolResult
   readonly skill: Skill
   readonly instructionFile: InstructionFile
+  readonly attachedFile: AttachedFile
   readonly notice: Notice
   readonly contextStart: Context
   readonly contextEnd: Context
@@ -49,12 +51,13 @@ export type BeforeAnswer = {
   readonly note: { readonly text: string }
   readonly skill: { readonly text: string }
   readonly instructionFile: { readonly text: string } | Refusal
+  readonly attachedFile: { readonly text: string } | Refusal
   readonly reply: { readonly text: string }
-  readonly toolCall: { readonly input: Readonly<Record<string, unknown>> } | { readonly result: string } | Refusal
+  readonly toolCall: { readonly input?: Readonly<Record<string, unknown>>; readonly note?: string } | { readonly result: string; readonly note?: string } | Refusal
   readonly toolResult: { readonly output?: unknown; readonly isError?: true; readonly note?: string }
   readonly notice: { readonly text: string }
-  readonly taskStart: { readonly owner: { readonly model: string } } | Refusal
-  readonly turnEnd: Refusal
+  readonly taskStart: { readonly prompt?: string; readonly title?: string; readonly owner?: { readonly agentType?: string; readonly model?: string; readonly cwd?: string }; readonly isAsync?: boolean } | Refusal
+  readonly turnEnd: { readonly note: string } | Refusal
   readonly contextEnd: Refusal
 }
 
@@ -63,9 +66,12 @@ export type BeforeEvent = keyof BeforeAnswer
 export type Usage = {
   readonly model: string
   readonly contextWindow: { readonly tokenCount?: number; readonly size?: number; readonly percent?: number }
+  readonly rateLimits?: readonly RateLimit[]
   readonly cost?: { readonly usd: number }
 }
 
+export type RateLimit = { readonly type: string; readonly percent: number; readonly resetsAt?: string }
+
 export type Surface = 'terminal' | 'desktop' | 'mobile' | 'vscode'
 
 export const sessionEvents = {
@@ -77,6 +83,7 @@ export const sessionEvents = {
   ToolResult: 'toolResult',
   Skill: 'skill',
   InstructionFile: 'instructionFile',
+  AttachedFile: 'attachedFile',
   Notice: 'notice',
   ContextStart: 'contextStart',
   ContextEnd: 'contextEnd',
@@ -88,7 +95,7 @@ export const sessionEvents = {
   UsageChange: 'usageChange',
 } as const satisfies Readonly<Record<string, SessionEvent>>
 
-export const beforeEvents = ['Prompt', 'Note', 'Skill', 'InstructionFile', 'Reply', 'ToolCall', 'ToolResult', 'Notice', 'TaskStart', 'TurnEnd', 'ContextEnd'] as const satisfies readonly (keyof typeof sessionEvents)[]
+export const beforeEvents = ['Prompt', 'Note', 'Skill', 'InstructionFile', 'AttachedFile', 'Reply', 'ToolCall', 'ToolResult', 'Notice', 'TaskStart', 'TurnEnd', 'ContextEnd'] as const satisfies readonly (keyof typeof sessionEvents)[]
 
 export type EventName = keyof typeof sessionEvents
 
@@ -138,6 +145,7 @@ export type TaskStartArgs = {
   readonly title: string
   readonly name?: string
   readonly cwd?: string
+  readonly isBackground?: boolean
 }
 
 export type ToolCallArgs = {
@@ -164,12 +172,14 @@ export type Session = RecordPart & {
   messages(options?: { readonly after?: string; readonly last?: number }): Promise<Message[]>
   send(message: SessionSend): Promise<void>
   startTask(task: TaskStartArgs): Promise<Task>
+  fork(task: Pick<TaskStartArgs, 'prompt' | 'title'>): Promise<Task>
+  clone(task: Pick<TaskStartArgs, 'prompt' | 'title'>): Promise<Task>
   callTool(call: ToolCallArgs): Promise<ToolResult>
   usage(): Promise<Usage>
   surfaces(): Promise<Surface[]>
 }
 
-export type TaskOwner = Omit<Session, 'startTask' | 'callTool'>
+export type TaskOwner = Omit<Session, 'startTask' | 'callTool' | 'fork' | 'clone'>
 
 type ProcessEvent = { readonly on: string; readonly before?: string }
 
@@ -305,9 +315,9 @@ export type ProcessPayload = {
 export type ProcessAsked = Omit<ProcessPayload, 'SessionStart'> & { readonly SessionStart: SessionStartAsked }
 
 export type ProcessAnswer = {
-  readonly ProjectSetup: Record<never, never>
+  readonly ProjectSetup: { readonly note: string }
   readonly SessionStart: { readonly note?: string; readonly title?: string; readonly reloadSkills?: true; readonly firstPrompt?: string }
-  readonly ModelChange: { readonly ask: string } | Refusal
+  readonly ModelChange: { readonly ask: string } | { readonly note: string } | Refusal
   readonly WorktreeCreate: { readonly result: string }
   readonly Elicitation: Refusal
   readonly ElicitationResponse: Refusal

package/src/testing/fake-claude.ts

@@ -20,7 +20,7 @@ export type Fakes = {
   config: { list?: Claude['config']['list'] }
   command: { list?: Claude['command']['list']; run?: Claude['command']['run'] }
   ui: { ask?: Claude['ui']['ask']; open?: Claude['ui']['open']; scroll?: Claude['ui']['scroll']; copy?: Claude['ui']['copy']; focus?: Claude['ui']['focus'] }
-  session: { messages?: Claude['session']['messages']; append?: Claude['session']['append']; send?: Claude['session']['send'] }
+  session: { messages?: Claude['session']['messages']; append?: Claude['session']['append']; send?: Claude['session']['send']; surfaces?: Claude['session']['surfaces']; usage?: Claude['session']['usage'] }
   prompt: { submit?: Claude['prompt']['submit'] }
   model: { complete?: Claude['model']['complete'] }
   agent: { list?: Claude['agent']['list']; spawn?: Claude['agent']['spawn'] }
@@ -49,6 +49,7 @@ export type FakeClaude = {
   readonly shown: Shown
   readonly store: Map<string, unknown>
   settle(): Promise<void>
+  placePane(id: string): void
 }
 
 export function calledAnswer(caller: string, answer: EventResult<'cmod.call'>): unknown {
@@ -80,6 +81,16 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
     return async (...args: Args): Promise<Result> => run(...args)
   }
 
+  const cmodCall = rejected('cmod.call', () => fakes.cmod.call ?? cmodTakesParts)
+
+  const clonedAsClaudeCodeDoes = <Args,>(args: Args): Args => {
+    try {
+      return structuredClone(args)
+    } catch (error) {
+      throw new Error(`interface.call: arguments are not plain data: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
   const cmodTakesParts: Claude['cmod']['call'] = async (input) => {
     if (input.to === cmodPluginName && input.method === partMethods.changed) return null
     throw new Error(`cmod.call(${JSON.stringify(input)}) has no fake answer. Set fakes.cmod.call on the tested mod.`)
@@ -118,7 +129,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
         lines.push(text)
       },
       notice: () => undefined,
-      invalidate: () => undefined,
+      invalidate: (event) => void calls.push({ call: 'ui.invalidate', args: [event] }),
       ask: rejected('ui.ask', () => fakes.ui.ask),
       open: async (pane) => {
         calls.push({ call: 'ui.open', args: [pane] })
@@ -188,8 +199,8 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
       root: async () => plugin.root,
       cwd: async () => plugin.root,
       model: async () => 'test-model',
-      usage: async () => ({ startedAt: Date.parse('2026-01-01T00:00:00.000Z'), context: { window: 200000 }, rateLimits: [], cost: { usd: 0 } }),
-      surfaces: async () => ['terminal'],
+      usage: () => fakes.session.usage?.() ?? Promise.resolve({ startedAt: Date.parse('2026-01-01T00:00:00.000Z'), context: { window: 200000 }, rateLimits: [], cost: { usd: 0 } }),
+      surfaces: () => fakes.session.surfaces?.() ?? Promise.resolve(['terminal']),
       messages: rejected('session.messages', () => fakes.session.messages as ((args?: unknown) => Promise<unknown>) | undefined) as Claude['session']['messages'],
       append: rejected('session.append', () => fakes.session.append ?? appendNote),
       send: rejected('session.send', () => fakes.session.send ?? (async () => ({ isDelivered: true as const }))),
@@ -217,7 +228,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
       dataHome: async () => undefined,
       configHome: async () => undefined,
     },
-    cmod: { call: rejected('cmod.call', () => fakes.cmod.call ?? cmodTakesParts) },
+    cmod: { call: async (args) => cmodCall(clonedAsClaudeCodeDoes(args)) },
   }
 
   const settle = async () => {
@@ -228,7 +239,11 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
     } while (calls.length !== seen)
   }
 
-  return { claude, calls, fakes, shown, store, settle }
+  const placePane = (id: string) => {
+    if (unplacedPanes.delete(id)) shown.openPanes.add(id)
+  }
+
+  return { claude, calls, fakes, shown, store, settle, placePane }
 }
 
 declare function setTimeout(fn: () => void, ms: number): unknown