@cmodjs/core 0.3.0 → 1.0.0

package/src/mod.ts

@@ -1,11 +1,7 @@
 import type {
-  AgentSpawnArgs,
-  AgentSpawnResult,
   AskOptions,
   ClassicHookInputs,
   CmodDependencies,
-  FsEntry,
-  FsStat,
   FsStatOptions,
   HookStream,
   HttpInit,
@@ -21,26 +17,45 @@ import type {
   ProcessSpawnRequest,
   ProcessSpawnResult,
   RenderElement,
-  SessionMessage,
-  Timer,
-  ToastOptions,
+  Settings,
   UiScrollArgs,
   UiScrollResult,
 } from 'claude-code'
 import type { Step } from './installer.js'
 import { checkOptions, type Option, type Options, type OptionValues } from './options.js'
-import type { FlagPermission, ListPermission } from './records.js'
-import type { Claude } from './runtime/claude.js'
-import type { RoutedEvent } from './runtime/hooks.js'
-import type { RoutedHook } from './runtime/router.js'
-import type { ToolCalls } from './runtime/tool-calls.js'
+import { bound } from './runtime/bound.js'
+import { Mod as modSender } from './session/context/turn/message/sender.js'
+import type { Sessions } from './session/session.js'
 import type { Pane } from './ui/define-pane.js'
-import type { Slot, SlotProps } from './ui/slots.js'
+import type { Place, PlaceProps } from './ui/places.js'
+import type { Matcher } from './utils/matcher.js'
 
-export type ProgressStep = {
-  readonly done: number
-  readonly total: number
-  readonly label?: string
+export type Disposable = {
+  dispose(): void
+}
+
+export type ToastId = string | number
+
+export type ToastType = 'default' | 'success' | 'info' | 'warning' | 'error' | 'loading'
+
+export type ToastOptions = {
+  readonly id?: ToastId
+  readonly description?: string | RenderElement
+  readonly action?: { readonly label: string; readonly onClick: () => unknown }
+  readonly duration?: number
+}
+
+type ToastMessage<Value> = string | ((value: Value) => string)
+
+export type Toast = {
+  (message: string, options?: ToastOptions): ToastId
+  success(message: string, options?: ToastOptions): ToastId
+  info(message: string, options?: ToastOptions): ToastId
+  warning(message: string, options?: ToastOptions): ToastId
+  error(message: string, options?: ToastOptions): ToastId
+  loading(message: string, options?: ToastOptions): ToastId
+  promise<T>(task: Promise<T> | (() => Promise<T>), messages: { readonly loading: string; readonly success: ToastMessage<T>; readonly error: ToastMessage<unknown> }): { unwrap(): Promise<T> }
+  dismiss(id?: ToastId): void
 }
 
 export type PaneHandle = {
@@ -50,30 +65,47 @@ export type PaneHandle = {
   readonly isOpen: boolean
 }
 
-export type { Claude, RoutedEvent, RoutedHook, ToolCalls }
-export { longestMs } from './runtime/deadline.js'
-export { notInstalled } from './runtime/dependencies.js'
-export { messageOf } from './utils/text.js'
+export const SessionStart = 'SessionStart'
+export const SessionEnd = 'SessionEnd'
+export const UserPromptSubmit = 'UserPromptSubmit'
+export const InstructionsLoaded = 'InstructionsLoaded'
+export const PreToolUse = 'PreToolUse'
+export const PermissionRequest = 'PermissionRequest'
+export const PermissionDenied = 'PermissionDenied'
+export const PostToolUse = 'PostToolUse'
+export const PostToolUseFailure = 'PostToolUseFailure'
+export const PostToolBatch = 'PostToolBatch'
+export const SubagentStart = 'SubagentStart'
+export const SubagentStop = 'SubagentStop'
+export const Notification = 'Notification'
+export const PreCompact = 'PreCompact'
+export const Stop = 'Stop'
+export const StopFailure = 'StopFailure'
+export const CwdChanged = 'CwdChanged'
+export const FileChanged = 'FileChanged'
 
-export type ModEvent =
-  | 'SessionStart'
-  | 'SessionEnd'
-  | 'UserPromptSubmit'
-  | 'InstructionsLoaded'
-  | 'PreToolUse'
-  | 'PermissionRequest'
-  | 'PermissionDenied'
-  | 'PostToolUse'
-  | 'PostToolUseFailure'
-  | 'PostToolBatch'
-  | 'SubagentStart'
-  | 'SubagentStop'
-  | 'Notification'
-  | 'PreCompact'
-  | 'Stop'
-  | 'StopFailure'
-  | 'CwdChanged'
-  | 'FileChanged'
+export const hooks = [
+  SessionStart,
+  SessionEnd,
+  UserPromptSubmit,
+  InstructionsLoaded,
+  PreToolUse,
+  PermissionRequest,
+  PermissionDenied,
+  PostToolUse,
+  PostToolUseFailure,
+  PostToolBatch,
+  SubagentStart,
+  SubagentStop,
+  Notification,
+  PreCompact,
+  Stop,
+  StopFailure,
+  CwdChanged,
+  FileChanged,
+] as const
+
+export type Hook = (typeof hooks)[number]
 
 export type HookAnswer = {
   continue?: boolean
@@ -83,7 +115,7 @@ export type HookAnswer = {
   decision?: 'block'
   reason?: string
   hookSpecificOutput?: {
-    hookEventName?: ModEvent
+    hookEventName?: Hook
     additionalContext?: string
     permissionDecision?: 'allow' | 'deny' | 'ask'
     permissionDecisionReason?: string
@@ -119,20 +151,14 @@ type HookInputs = Omit<ClassicHookInputs, 'PreToolUse' | 'PostToolUse' | 'PostTo
   CwdChanged: Omit<ClassicHookInputs['CwdChanged'], 'transcript_path'>
 }
 
-export type HookInput<E extends ModEvent> = HookInputs[E]
+export type HookInput<H extends Hook> = HookInputs[H]
 
-export type ModHook<E extends ModEvent> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>
+export type HookListener<H extends Hook> = (input: HookInput<H>) => HookAnswer | void | Promise<HookAnswer | void>
 
 export type HookOptions = {
   readonly timeoutMs?: number
 }
 
-export type ScrollArgs = Omit<UiScrollArgs, 'to'> & { readonly to: Exclude<UiScrollArgs['to'], { requestId: string }> }
-
-export type ModClaude = Claude & {
-  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
-}
-
 export type Metadata = Readonly<Record<string, string>>
 
 export type FileMatch = {
@@ -142,71 +168,136 @@ export type FileMatch = {
   readonly error?: string
 }
 
-type SessionMessages = {
-  (): Promise<SessionMessage[]>
-  (args: { readonly agentId: string }): Promise<SessionMessage[] | { readonly deny: string }>
+export type Entry = {
+  readonly name: string
+  readonly isFile: boolean
+  readonly isFolder: boolean
+  readonly isLink: boolean
+  readonly size: number
+  readonly modifiedAt: number
 }
 
-export type Mod<State extends object = Record<never, never>, Declared extends Options = Options> = {
-  readonly name: string
-  readonly state: Readonly<State>
-  readonly options: OptionValues<Declared>
-  readonly dataFolder: string
-  on<E extends ModEvent>(event: E, hook: ModHook<E>, options?: HookOptions): void
-  use<Handle>(job: Job<Handle, State>): Handle
-  every(ms: number, hook: () => unknown): Timer
-  readonly ui: {
-    pane(pane: Pane<State>): PaneHandle
-    render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => RenderElement): void
-    toast(text: string, options?: ToastOptions): void
-    progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
-    ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
-    scroll(args: ScrollArgs): Promise<UiScrollResult>
-  }
-  readonly process: {
-    run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>
-    spawn(argv: readonly string[], init?: Omit<ProcessSpawnRequest, 'argv'>): HookStream<ProcessSpawnChunk, ProcessSpawnResult>
-  }
+export type Stat = Omit<Entry, 'name'> & {
+  readonly realPath?: string
+}
+
+export type Allowed = {
+  allows(value: string): boolean
+}
+
+export type Permissions = {
+  readonly conversation: boolean
+  readonly prompt: boolean
+  readonly model: boolean
+  readonly tasks: boolean
+  readonly tools: boolean
+  readonly approve: boolean
+  readonly network: Allowed
+  readonly run: Allowed
+  readonly files: Allowed
+  readonly config: Allowed
+}
+
+export type SettingsFile = {
+  read(): Promise<Settings>
+  update(values: Readonly<Record<string, unknown>>): Promise<void>
+}
+
+export type Imports = {
+  readonly sessions: Sessions
+  readonly settings: { readonly user: SettingsFile; readonly project: SettingsFile; readonly local: SettingsFile }
+  readonly model: { complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult> }
   readonly fs: {
     read(path: string): Promise<string>
     write(path: string, text: string): Promise<void>
-    list(path?: string): Promise<FsEntry[]>
     exists(path: string): Promise<boolean>
-    stat(path: string, options?: FsStatOptions): Promise<FsStat>
     find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
+    list(path?: string): Promise<Entry[]>
+    stat(path: string, options?: FsStatOptions): Promise<Stat>
   }
   readonly metadata: {
     read(path: string): Promise<Metadata>
     update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
   }
-  readonly http: {
-    fetch(url: string, init?: HttpInit): Promise<HttpResponse>
+  readonly process: {
+    run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>
+    spawn(argv: readonly string[], init?: Omit<ProcessSpawnRequest, 'argv'>): HookStream<ProcessSpawnChunk, ProcessSpawnResult>
+  }
+  readonly http: { fetch(url: string, init?: HttpInit): Promise<HttpResponse> }
+}
+
+export const sessions: Imports['sessions'] = {
+  get current() {
+    return bound().sessions.current
+  },
+  list: (options) => bound().sessions.list(options),
+  search: (text, options) => bound().sessions.search(text, options),
+}
+
+export const settings: Imports['settings'] = {
+  user: { read: () => bound().settings.user.read(), update: (values) => bound().settings.user.update(values) },
+  project: { read: () => bound().settings.project.read(), update: (values) => bound().settings.project.update(values) },
+  local: { read: () => bound().settings.local.read(), update: (values) => bound().settings.local.update(values) },
+}
+
+export const model: Imports['model'] = {
+  complete: (request, options) => bound().model.complete(request, options),
+}
+
+export const fs: Imports['fs'] = {
+  read: (path) => bound().fs.read(path),
+  write: (path, text) => bound().fs.write(path, text),
+  exists: (path) => bound().fs.exists(path),
+  find: (glob) => bound().fs.find(glob),
+  list: (path) => bound().fs.list(path),
+  stat: (path, options) => bound().fs.stat(path, options),
+}
+
+export const metadata: Imports['metadata'] = {
+  read: (path) => bound().metadata.read(path),
+  update: (path, change) => bound().metadata.update(path, change),
+}
+
+export const process: Imports['process'] = {
+  run: (argv, init) => bound().process.run(argv, init),
+  spawn: (argv, init) => bound().process.spawn(argv, init),
+}
+
+export const http: Imports['http'] = {
+  fetch: (url, init) => bound().http.fetch(url, init),
+}
+
+export type Mod<State extends object = Record<never, never>, Declared extends Options = Options> = {
+  readonly name: string
+  readonly folder: string
+  readonly dataFolder: string
+  readonly state: Readonly<State>
+  readonly options: OptionValues<Declared>
+  readonly permissions: Permissions
+  on<H extends Hook>(hook: H, listener: HookListener<H>, options?: HookOptions): Disposable
+  on<H extends Hook>(hook: H, matcher: Matcher<HookInput<H>>, listener: HookListener<H>, options?: HookOptions): Disposable
+  every(ms: number, listener: () => unknown): Disposable
+  after(ms: number, listener: () => unknown): Disposable
+  use<Handle>(job: Job<Handle, State>): Handle
+  log(text: string): void
+  readonly ui: {
+    pane(pane: Pane<State>): PaneHandle
+    render<P extends Place>(place: P, Component: (props: PlaceProps<P>) => RenderElement): Disposable
+    readonly toast: Toast
+    ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
+    copy(text: string): Promise<void>
+    scroll(args: UiScrollArgs): Promise<UiScrollResult>
+    notice(callId: string, text: string | undefined): void
   }
   readonly settings: {
     page(page: Pane<State>): void
     open(pageId?: string): Promise<void>
   }
-  readonly session: {
-    messages: SessionMessages
-    append(text: string): Promise<void>
-    submit(text: string): Promise<void>
-  }
-  readonly agent: {
-    spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>
-  }
-  readonly model: {
-    complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult>
-  }
-  readonly permissions: {
-    has(name: ListPermission, value: string): boolean
-    has(name: FlagPermission): boolean
-  }
-  readonly projectRoot: string
-  readonly cwd: string
   readonly dependencies: CmodDependencies
-  readonly claude: ModClaude
 }
 
+export const Mod = modSender
+
 type StateGroups = {
   readonly memory?: object
   readonly session?: object
@@ -224,14 +315,13 @@ export type ModDefinition<State extends StateGroups = Record<never, never>, Name
   readonly options?: Declared
   readonly api?: Name extends keyof CmodDependencies ? Api<CmodDependencies[Name], State> : { readonly [method: string]: (input: never, mod: Mod<State>) => unknown }
   readonly installer?: readonly Step<State>[]
-  setup(mod: Mod<State, Declared>): void | Promise<void>
+  setup(mod: Mod<State, Declared>): unknown
 }
 
 export type JobContext<State extends object = Record<never, never>> = {
   readonly mod: Mod<State>
   announce(feature: string): void
-  reserveName(kind: string, name: string, taken: string): void
-  readonly toolCalls: ToolCalls
+  reserveName(type: string, name: string, taken: string): Disposable
 }
 
 export type Job<Handle, State extends object = Record<never, never>> = (context: JobContext<State>) => Handle
@@ -241,3 +331,25 @@ export function defineMod<State extends StateGroups = Record<never, never>, Name
   if (definition.options !== undefined) checkOptions(definition.name, definition.options)
   return definition
 }
+
+export type { Matcher } from './utils/matcher.js'
+export type { Place, PlaceProps } from './ui/places.js'
+export { AbovePrompt, AskUserQuestion, CommandOutput, PromptHint, SessionMode, Spinner, ToolGroup, ToolProgress, TurnDuration } from './ui/places.js'
+export { Session, type SessionEvent, type SessionPayload, type SessionScope, type SessionSend, type Sessions, type TaskStartArgs, type Usage } from './session/session.js'
+export { ContextEnd, ContextStart, type Context } from './session/context/context.js'
+export { TurnEnd, TurnStart, type Turn } from './session/context/turn/turn.js'
+export { Message, type MessageType } from './session/context/turn/message/message.js'
+export { Prompt } from './session/context/turn/message/prompt.js'
+export { Note } from './session/context/turn/message/note.js'
+export { Reply } from './session/context/turn/message/reply.js'
+export { ToolCall } from './session/context/turn/message/tool-call.js'
+export { ToolResult } from './session/context/turn/message/tool-result.js'
+export { Skill } from './session/context/turn/message/skill.js'
+export { Document } from './session/context/turn/message/document.js'
+export { Notice } from './session/context/turn/message/notice.js'
+export { Channel, Person, Schedule, Sdk, type Sender, type SenderType } from './session/context/turn/message/sender.js'
+export { GoalChange, type Goal } from './session/goal/goal.js'
+export { Task, TaskEnd, TaskStart } from './session/goal/task.js'
+export { longestMs } from './runtime/deadline.js'
+export { notInstalled } from './runtime/dependencies.js'
+export { messageOf } from './utils/text.js'

package/src/options.ts

@@ -1,11 +1,11 @@
-export type OptionKind = 'text' | 'secret' | 'number' | 'toggle' | 'choice' | 'folder' | 'file' | 'list'
+export type OptionType = 'text' | 'secret' | 'number' | 'toggle' | 'choice' | 'folder' | 'file' | 'list'
 
 export type OptionValue = string | number | boolean | readonly string[]
 
 type Described = { readonly title: string; readonly description: string }
 
 export type Option<Value extends OptionValue = OptionValue> = Described & {
-  readonly kind: OptionKind
+  readonly type: OptionType
   readonly default?: Value
   readonly min?: number
   readonly max?: number
@@ -27,17 +27,17 @@ export type UserConfigField = Described & {
 }
 
 export const option = {
-  text: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'text' }),
-  secret: (field: Described): Option<string> => ({ ...field, kind: 'secret' }),
-  number: (field: Described & { readonly default?: number; readonly min?: number; readonly max?: number }): Option<number> => ({ ...field, kind: 'number' }),
-  toggle: (field: Described & { readonly default?: boolean }): Option<boolean> => ({ ...field, kind: 'toggle', default: field.default ?? false }),
-  choice: <const Choice extends string>(choices: readonly Choice[], field: Described & { readonly default?: Choice }): Option<Choice> => ({ ...field, kind: 'choice', choices }),
-  folder: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'folder' }),
-  file: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'file' }),
-  list: (field: Described & { readonly default?: readonly string[] }): Option<readonly string[]> => ({ ...field, kind: 'list' }),
+  text: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, type: 'text' }),
+  secret: (field: Described): Option<string> => ({ ...field, type: 'secret' }),
+  number: (field: Described & { readonly default?: number; readonly min?: number; readonly max?: number }): Option<number> => ({ ...field, type: 'number' }),
+  toggle: (field: Described & { readonly default?: boolean }): Option<boolean> => ({ ...field, type: 'toggle', default: field.default ?? false }),
+  choice: <const Choice extends string>(choices: readonly Choice[], field: Described & { readonly default?: Choice }): Option<Choice> => ({ ...field, type: 'choice', choices }),
+  folder: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, type: 'folder' }),
+  file: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, type: 'file' }),
+  list: (field: Described & { readonly default?: readonly string[] }): Option<readonly string[]> => ({ ...field, type: 'list' }),
 }
 
-const types: Readonly<Record<OptionKind, UserConfigField['type']>> = { text: 'string', secret: 'string', number: 'number', toggle: 'boolean', choice: 'string', folder: 'directory', file: 'file', list: 'string' }
+const types: Readonly<Record<OptionType, UserConfigField['type']>> = { text: 'string', secret: 'string', number: 'number', toggle: 'boolean', choice: 'string', folder: 'directory', file: 'file', list: 'string' }
 
 const optionKey = /^[A-Za-z_]\w*$/
 
@@ -46,8 +46,8 @@ export function checkOptions(name: string, options: Options): Options {
     const at = `${name}: options.${key}`
     if (!optionKey.test(key)) throw new Error(`${at} is not an option name. Use letters, digits, and _, starting with a letter, as Claude Code passes each option on as CLAUDE_PLUGIN_OPTION_${key.toUpperCase()}.`)
     if (declared.title.trim() === '') throw new Error(`${at} needs a title, the label /config shows.`)
-    if (declared.kind === 'choice' && (declared.choices ?? []).length === 0) throw new Error(`${at} is a choice with no choices. Give option.choice(['a', 'b'], { ... }).`)
-    if (declared.kind === 'choice' && declared.default !== undefined && !(declared.choices ?? []).includes(declared.default as string)) throw new Error(`${at} defaults to ${String(declared.default)}, which is not one of its choices: ${(declared.choices ?? []).join(', ')}.`)
+    if (declared.type === 'choice' && (declared.choices ?? []).length === 0) throw new Error(`${at} is a choice with no choices. Give option.choice(['a', 'b'], { ... }).`)
+    if (declared.type === 'choice' && declared.default !== undefined && !(declared.choices ?? []).includes(declared.default as string)) throw new Error(`${at} defaults to ${String(declared.default)}, which is not one of its choices: ${(declared.choices ?? []).join(', ')}.`)
   }
   return options
 }
@@ -57,12 +57,12 @@ export function userConfigOf(options: Options): Record<string, UserConfigField>
     Object.entries(options).map(([key, declared]) => [
       key,
       {
-        type: types[declared.kind],
+        type: types[declared.type],
         title: declared.title,
         description: declared.description,
-        ...(declared.kind === 'secret' ? { sensitive: true } : {}),
-        ...(declared.kind === 'list' ? { multiple: true } : {}),
-        ...(declared.kind === 'choice' ? { options: declared.choices } : {}),
+        ...(declared.type === 'secret' ? { sensitive: true } : {}),
+        ...(declared.type === 'list' ? { multiple: true } : {}),
+        ...(declared.type === 'choice' ? { options: declared.choices } : {}),
         ...(declared.default === undefined ? {} : { default: declared.default }),
         ...(declared.min === undefined ? {} : { min: declared.min }),
         ...(declared.max === undefined ? {} : { max: declared.max }),
@@ -76,16 +76,16 @@ export function isUnset(value: unknown): boolean {
 }
 
 export function fitsOption(declared: Option, value: unknown): string | undefined {
-  const kind = declared.kind
-  if (kind === 'toggle') return typeof value === 'boolean' ? undefined : 'takes true or false'
-  if (kind === 'number') {
+  const type = declared.type
+  if (type === 'toggle') return typeof value === 'boolean' ? undefined : 'takes true or false'
+  if (type === 'number') {
     if (typeof value !== 'number' || !Number.isFinite(value)) return 'takes a number'
     if (declared.min !== undefined && value < declared.min) return `takes ${declared.min} or more`
     if (declared.max !== undefined && value > declared.max) return `takes ${declared.max} or less`
     return undefined
   }
-  if (kind === 'list') return Array.isArray(value) && value.every((item) => typeof item === 'string') ? undefined : 'takes a list of text'
+  if (type === 'list') return Array.isArray(value) && value.every((item) => typeof item === 'string') ? undefined : 'takes a list of text'
   if (typeof value !== 'string') return 'takes text'
-  if (kind === 'choice' && !(declared.choices ?? []).includes(value)) return `takes one of: ${(declared.choices ?? []).join(', ')}`
+  if (type === 'choice' && !(declared.choices ?? []).includes(value)) return `takes one of: ${(declared.choices ?? []).join(', ')}`
   return undefined
 }

package/src/records.ts

@@ -19,23 +19,30 @@ export type Steps = {
   permissions?: readonly string[]
 }
 
-export const listPermissions = ['network', 'run', 'files'] as const
-export const flagPermissions = ['conversation', 'prompt', 'model', 'agents', 'tools', 'config', 'approve'] as const
+export const listPermissions = ['network', 'run', 'files', 'config'] as const
+export const flagPermissions = ['conversation', 'prompt', 'model', 'tasks', 'tools', 'approve'] as const
 export type ListPermission = (typeof listPermissions)[number]
 export type FlagPermission = (typeof flagPermissions)[number]
 const permissionNames: readonly string[] = [...listPermissions, ...flagPermissions]
 const hostName = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$/
 const programName = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/
+const settingName = /^[A-Za-z][A-Za-z0-9]*$/
+const listItemHint: Readonly<Record<ListPermission, string>> = {
+  network: 'a host alone, such as "api.github.com", or a socket path, such as "/var/run/docker.sock"',
+  run: 'a program\'s command, such as "gh"',
+  files: 'a path that starts with ~/ or /, such as "~/.zshrc"',
+  config: 'a Claude Code setting\'s name, such as "cleanupPeriodDays"',
+}
 
 export type ReadFile = (path: string) => Promise<string | undefined>
 
 export type RunnerEvent =
-  | { kind: 'progress'; done: number; total: number; label: string }
-  | { kind: 'log'; text: string }
-  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
-  | { kind: 'done'; name: string; version?: string }
-  | { kind: 'missing'; name: string }
-  | { kind: 'failed'; code: number; message: string }
+  | { type: 'progress'; done: number; total: number; label: string }
+  | { type: 'log'; text: string }
+  | { type: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
+  | { type: 'done'; name: string; version?: string }
+  | { type: 'missing'; name: string }
+  | { type: 'failed'; code: number; message: string }
 
 export const pluginName = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 
@@ -153,12 +160,12 @@ function readPermissions(steps: Record<string, unknown>): string[] {
       items.push('run:*')
       continue
     }
-    const example = name === 'network' ? '["api.github.com"]' : name === 'run' ? '["gh"], or "*" for any program' : '["~/.zshrc"]'
+    const example = { network: '["api.github.com"]', run: '["gh"], or "*" for any program', files: '["~/.zshrc"]', config: '["cleanupPeriodDays"]' }[name]
     if (!Array.isArray(value) || value.length === 0 || !value.every((each) => typeof each === 'string')) throw new Error(`${at} sets "${name}" to ${JSON.stringify(value)}. Write a list, such as "${name}": ${example}.`)
-    for (const each of value as string[]) {
+    for (const each of value) {
       const isPath = /^(~\/|\/)/.test(each) && !each.split('/').includes('..')
-      const isValid = name === 'network' ? hostName.test(each) || isPath : name === 'run' ? programName.test(each) : isPath
-      if (!isValid) throw new Error(`${at} lists "${each}" under "${name}". Write ${name === 'network' ? 'a host alone, such as "api.github.com", or a socket path, such as "/var/run/docker.sock"' : name === 'run' ? 'a program\'s command, such as "gh"' : 'a path that starts with ~/ or /, such as "~/.zshrc"'}.`)
+      const isValid = { network: hostName.test(each) || isPath, run: programName.test(each), files: isPath, config: settingName.test(each) }[name]
+      if (isValid !== true) throw new Error(`${at} lists "${each}" under "${name}". Write ${listItemHint[name as ListPermission]}.`)
       items.push(`${name}:${each}`)
     }
   }
@@ -176,17 +183,17 @@ export function permissionWords(item: string): string {
     case 'files':
       return `Change ${target}`
     case 'conversation':
-      return 'Read this conversation'
+      return 'Read your Claude Code conversations'
     case 'prompt':
       return 'Add text Claude reads and start turns'
     case 'model':
       return 'Ask a model, which uses your plan'
-    case 'agents':
-      return 'Start agents'
+    case 'tasks':
+      return 'Start tasks that work beside Claude'
     case 'tools':
       return "Use and change Claude's tool calls"
     case 'config':
-      return 'Change your Claude Code settings'
+      return `Change ${target} in your Claude Code settings`
     case 'approve':
       return "Approve Claude's tool calls for you"
     default:
@@ -196,6 +203,8 @@ export function permissionWords(item: string): string {
 
 export const settingsPagesMethod = 'cmod:settingsPages'
 
+export const changelogPage = 'changelog'
+
 export const openPageMethod = 'cmod:openPage'
 
 export const pendingStepsMethod = 'cmod:pendingSteps'
@@ -240,7 +249,10 @@ function readKeys(keys: unknown): Steps {
   return { keys: commands }
 }
 
+export const coreVersion = '1.0.0'
+
 export function oldestCmodFor(steps: Steps): string {
+  if (steps.permissions?.some((item) => item === 'tasks' || item.startsWith('config:')) === true) return '1.0.0'
   if (steps.permissions !== undefined) return '0.2.0'
   return Object.keys(steps.keys ?? {}).length > 0 ? '0.1.12' : '0.0.0'
 }
@@ -303,7 +315,7 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
 }
 
 export function formatEvent(event: RunnerEvent): string {
-  switch (event.kind) {
+  switch (event.type) {
     case 'progress':
       return `progress ${event.done} ${event.total}${event.label === '' ? '' : ` ${event.label}`}`
     case 'log':
@@ -321,19 +333,19 @@ export function formatEvent(event: RunnerEvent): string {
 
 export function parseEvent(line: string): RunnerEvent {
   const progress = /^progress (\d+) (\d+)(?: (.*))?$/.exec(line)
-  if (progress !== null) return { kind: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
+  if (progress !== null) return { type: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
   const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
   if (consent !== null) {
     const [keys = '', ...permissions] = (consent[4] ?? '').split('\t')
-    return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
+    return { type: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
   }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
-  if (done !== null) return { kind: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
+  if (done !== null) return { type: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
   const missing = /^missing (\S+)$/.exec(line)
-  if (missing !== null) return { kind: 'missing', name: missing[1] as string }
+  if (missing !== null) return { type: 'missing', name: missing[1] as string }
   const failed = /^failed (-?\d+)(?:\t(.*))?$/.exec(line)
-  if (failed !== null) return { kind: 'failed', code: Number(failed[1]), message: failed[2] ?? '' }
-  return { kind: 'log', text: line.replace(/^log /, '') }
+  if (failed !== null) return { type: 'failed', code: Number(failed[1]), message: failed[2] ?? '' }
+  return { type: 'log', text: line.replace(/^log /, '') }
 }
 
 export function isAtLeast(version: string, minimum: string): boolean {