@g3nomaly/g3n-mods 0.0.0-stage → 0.1.1

package/mods/custom-crab-agents/hooks/register.tsx

@@ -0,0 +1,508 @@
+// packages/g3n-mods/mods/custom-crab-agents/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Crab, CrabSteps, PlannedItem } from '../types'
+
+const PANE = 'crabs'
+const TITLE = 'Crabs'
+const crabs = atom({ plugin: 'custom-crab-agents', key: 'crabs' } as const, [])
+const planned = atom({ plugin: 'custom-crab-agents', key: 'planned' } as const, [])
+const contextWindow = atom({ plugin: 'custom-crab-agents', key: 'window' } as const, 1_000_000)
+
+const KEEP = 30
+const PIXEL = 4
+
+/** Effort level → tier name, color and hat. */
+const TIERS: Readonly<Record<string, { name: string; color: string; hat: keyof typeof HATS }>> = {
+  low: { name: 'light', color: '#3fa66b', hat: 'cap' },
+  medium: { name: 'medium', color: '#4c8bf5', hat: 'sailor' },
+  high: { name: 'careful', color: '#e0a030', hat: 'hardhat' },
+  xhigh: { name: 'heavy', color: '#e05a4f', hat: 'beanie' },
+  max: { name: 'heavy', color: '#e05a4f', hat: 'beanie' },
+}
+const DEFAULT_TIER = { name: 'medium', color: '#4c8bf5', hat: 'sailor' as const }
+
+/** Sprite rows, 12 pixels wide; each letter is a palette color, `.` is empty. */
+const BODY = [
+  '...k....k...',
+  'C..b....b..C',
+  'CC.bbbbbb.CC',
+  '.CbbbbbbbbC.',
+  '..bbbbbbbb..',
+  '..bbbbbbbb..',
+  '..b.b..b.b..',
+  '.b..b..b..b.',
+]
+const HATS = {
+  cap: ['...gggg.....', '..gggggg....', '..ggggggggg.'],
+  sailor: ['...wwwwww...', '..wwwwwwww..', '..uuuuuuuu..'],
+  hardhat: ['....yyyy....', '...yyyyyy...', '.yyyyyyyyyy.'],
+  beanie: ['.....t......', '...nnnnnn...', '..nnnnnnnn..'],
+} as const
+const PALETTE: Readonly<Record<string, string>> = {
+  b: '#e07a5f', C: '#c8553d', k: '#1e1e1e',
+  g: '#3fa66b', w: '#f0f0f0', u: '#4c8bf5', y: '#f2c14e', t: '#e8e8e8', n: '#7a4a2a',
+}
+
+/** Price per million tokens: input, output, cache read, cache write. First match wins. */
+const PRICES: ReadonlyArray<[RegExp, [number, number, number, number]]> = [
+  [/fable|mythos/, [10, 50, 0.25, 12.5]],
+  [/opus-5-5/, [4, 20, 0.2, 5]],
+  [/opus/, [5, 25, 0.5, 6.25]],
+  [/sonnet-5/, [2, 10, 0.2, 2.5]],
+  [/sonnet/, [3, 15, 0.3, 3.75]],
+  [/haiku-5/, [0.1, 0.5, 0.01, 0.125]],
+  [/haiku/, [1, 5, 0.1, 1.25]],
+]
+
+/**
+ * Looks up the tier of an effort level, falling back to the default tier.
+ *
+ * @param effort - Effort level of an Agent call, e.g. `high`, or `undefined` when none was given.
+ * @returns The tier with its name, color and hat.
+ */
+function tierOf(effort: string | undefined) {
+  return (effort === undefined ? undefined : TIERS[effort]) ?? DEFAULT_TIER
+}
+
+/**
+ * Formats a model id or alias as a short display name.
+ *
+ * @param model - Model id or alias, e.g. `claude-opus-5-5` or `haiku`.
+ * @returns The family and version, e.g. `Opus 5.5` or `Haiku`, or `model` unchanged when no family matches.
+ */
+export function modelName(model: string): string {
+  const match = /(opus|sonnet|haiku|fable|mythos)(?:-(\d+))?(?:-(\d+))?/i.exec(model)
+  if (match === null) return model
+  const family = (match[1] ?? '').charAt(0).toUpperCase() + (match[1] ?? '').slice(1).toLowerCase()
+  const version = [match[2], match[3]].filter(part => part !== undefined && part.length <= 2).join('.')
+  return version.length > 0 ? `${family} ${version}` : family
+}
+
+/**
+ * Estimates the dollar cost of a usage record from the price table.
+ *
+ * @param model - Model id or alias, matched against the price table.
+ * @param usage - Usage record with token counts under `input_tokens`, `output_tokens`,
+ *   `cache_read_input_tokens` and `cache_creation_input_tokens`, e.g. `{ input_tokens: 1200 }`.
+ * @returns Estimated cost in US dollars, or `undefined` when no price matches the model.
+ */
+export function costOf(model: string, usage: Record<string, unknown>): number | undefined {
+  const price = PRICES.find(([match]) => match.test(model))?.[1]
+  if (price === undefined) return undefined
+  /**
+   * Reads one token count from the usage record.
+   *
+   * @param key - Token field to read, e.g. `input_tokens`.
+   * @returns The count, or `0` when the field is missing or not a number.
+   */
+  const n = (key: string) => (typeof usage[key] === 'number' ? (usage[key] as number) : 0)
+  return (n('input_tokens') * price[0] + n('output_tokens') * price[1]
+    + n('cache_read_input_tokens') * price[2] + n('cache_creation_input_tokens') * price[3]) / 1_000_000
+}
+
+/**
+ * Formats a token count as `892`, `1.2k` or `52k`.
+ *
+ * @param tokens - Token count, e.g. `52000`.
+ * @returns Short label.
+ */
+function formatTokens(tokens: number): string {
+  return tokens >= 10_000 ? `${Math.round(tokens / 1000)}k` : tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens)
+}
+
+/**
+ * Formats a duration as `m:ss`.
+ *
+ * @param ms - Duration in milliseconds.
+ * @returns Minutes and zero-padded seconds, e.g. `1:05`.
+ */
+function minutes(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000))
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
+}
+
+/**
+ * Draws the crab as one SVG: hat rows for the tier on top of the body; a planned crab is drawn grey.
+ *
+ * @param hat - Hat to draw, a key of `HATS`.
+ * @param isPlanned - Whether the crab is planned work, not a running or finished subagent.
+ * @returns The SVG markup as a string.
+ */
+function crabSvg(hat: keyof typeof HATS, isPlanned: boolean): string {
+  const rows = [...HATS[hat], ...BODY]
+  const rects: string[] = []
+  rows.forEach((row, y) => {
+    for (let x = 0; x < row.length; x++) {
+      const color = PALETTE[row.charAt(x)]
+      if (color !== undefined) rects.push(`<rect x="${x * PIXEL}" y="${y * PIXEL}" width="${PIXEL}" height="${PIXEL}" fill="${color}"/>`)
+    }
+  })
+  const width = 12 * PIXEL
+  const height = rows.length * PIXEL
+  const filter = isPlanned ? ' opacity="0.45" style="filter:grayscale(1)"' : ''
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"${filter}>${rects.join('')}</svg>`
+}
+
+/**
+ * Draws a progress bar as one SVG, filled to `share` of its width.
+ *
+ * @param width - Width of the bar in pixels.
+ * @param share - Filled part of the bar, from `0` to `1`.
+ * @param color - Fill color as a CSS hex string.
+ * @returns The SVG markup as a string.
+ */
+function progressSvg(width: number, share: number, color: string): string {
+  const w = Math.max(0, Math.min(1, share)) * width
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="5" viewBox="0 0 ${width} 5"><rect width="${width}" height="5" rx="2" fill="#2b3240"/><rect width="${w.toFixed(1)}" height="5" rx="2" fill="${color}"/></svg>`
+}
+
+/**
+ * Reads one property of an unknown value when the property passes `guard`.
+ *
+ * @param value - Any value, e.g. a parsed tool result.
+ * @param key - Name of the property to read.
+ * @param guard - Type guard the property value must pass.
+ * @returns The property value, or `undefined` when `value` is not an object or the guard fails.
+ */
+function field<T>(value: unknown, key: string, guard: (v: unknown) => v is T): T | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const found = (value as Record<string, unknown>)[key]
+  return guard(found) ? found : undefined
+}
+/** Tells whether `v` is a string. */
+const isString = (v: unknown): v is string => typeof v === 'string'
+/** Tells whether `v` is a number. */
+const isNumber = (v: unknown): v is number => typeof v === 'number'
+/** Tells whether `v` is a non-null object. */
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null
+
+/**
+ * Applies `patch` to every crab that `match` selects.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param match - Selects the crabs to change.
+ * @param patch - Returns the changed crab for a selected one.
+ */
+async function patchCrab($: EngineInterface, match: (crab: Crab) => boolean, patch: (crab: Crab) => Crab): Promise<void> {
+  await update($, crabs, list => list.map(crab => (match(crab) ? patch(crab) : crab)))
+}
+
+/**
+ * Records a subagent the main thread just started and shows the pane.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param crab - New running crab to add, see `Crab`.
+ */
+async function startCrab($: EngineInterface, crab: Crab): Promise<void> {
+  await update($, crabs, list => [...list.filter(one => one.id !== crab.id), crab].slice(-KEEP))
+  void $.ui.open({ id: PANE, title: TITLE })
+}
+
+/**
+ * Settles a crab from the Agent tool's result: its usage, model and time, or that it went to the background.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param id - `tool_use_id` of the Agent call that started the crab.
+ * @param result - Raw result of the Agent call, of unknown shape.
+ * @param isError - Whether the Agent call reported an error.
+ */
+async function finishCrab($: EngineInterface, id: string, result: unknown, isError: boolean): Promise<void> {
+  const status = field(result, 'status', isString)
+  const agentId = field(result, 'agentId', isString)
+  if (status === 'async_launched') {
+    await patchCrab($, crab => crab.id === id, crab => ({ ...crab, agentId: agentId ?? crab.agentId }))
+    return
+  }
+  const usage = field(result, 'usage', isRecord) ?? {}
+  const now = await $.clock.now()
+  await patchCrab($, crab => crab.id === id, crab => {
+    const model = field(result, 'resolvedModel', isString) ?? crab.model
+    return {
+      ...crab,
+      agentId: agentId ?? crab.agentId,
+      model,
+      status: isError ? 'failed' : 'finished',
+      durationMs: field(result, 'totalDurationMs', isNumber) ?? now - crab.startedAt,
+      tokens: field(result, 'totalTokens', isNumber) ?? crab.tokens,
+      costUsd: costOf(model, usage) ?? crab.costUsd,
+      steps: crab.steps.total > 0 ? { ...crab.steps, done: crab.steps.total, current: undefined } : crab.steps,
+    }
+  })
+}
+
+/**
+ * Settles a background crab when its own loop completes.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id of the subagent whose loop completed.
+ * @param usage - Usage record of that loop, or `undefined` when none was reported.
+ */
+async function finishBackground($: EngineInterface, agentId: string, usage: Record<string, unknown> | undefined): Promise<void> {
+  const now = await $.clock.now()
+  await patchCrab($, crab => crab.agentId === agentId && crab.status === 'running', crab => ({
+    ...crab,
+    status: 'finished',
+    durationMs: now - crab.startedAt,
+    tokens: usage === undefined ? crab.tokens : ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']
+      .reduce((sum, key) => sum + (typeof usage[key] === 'number' ? (usage[key] as number) : 0), 0),
+    costUsd: usage === undefined ? crab.costUsd : costOf(crab.model, usage),
+  }))
+}
+
+/**
+ * Ties a subagent's id to the newest running crab of its type that has none yet.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id the engine gave the subagent.
+ * @param agentType - Subagent type the crab was started with, e.g. `Explore`.
+ */
+async function bindAgent($: EngineInterface, agentId: string, agentType: string): Promise<void> {
+  await update($, crabs, list => {
+    if (list.some(crab => crab.agentId === agentId)) return list
+    const index = list.map(crab => crab.status === 'running' && crab.agentId === undefined && crab.subagentType === agentType).lastIndexOf(true)
+    return index === -1 ? list : list.map((crab, i) => (i === index ? { ...crab, agentId } : crab))
+  })
+}
+
+/**
+ * Turns a todo list into steps (a subagent's own list) or planned items (the main thread's).
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param todos - Raw `todos` field of a TodoWrite call, of unknown shape.
+ * @param agentId - Id of the subagent that wrote the list, or `undefined` for the main thread.
+ */
+async function readTodos($: EngineInterface, todos: unknown, agentId: string | undefined): Promise<void> {
+  if (!Array.isArray(todos)) return
+  const items = todos.filter(isRecord).map(todo => ({
+    content: field(todo, 'content', isString) ?? '',
+    status: field(todo, 'status', isString) ?? 'pending',
+    activeForm: field(todo, 'activeForm', isString),
+  }))
+
+  if (agentId !== undefined) {
+    const steps: CrabSteps = {
+      done: items.filter(item => item.status === 'completed').length,
+      total: items.length,
+      current: items.find(item => item.status === 'in_progress')?.activeForm,
+    }
+    await patchCrab($, crab => crab.agentId === agentId, crab => ({ ...crab, steps }))
+    return
+  }
+
+  const open: PlannedItem[] = []
+  items.forEach((item, i) => {
+    if (item.status !== 'pending') return
+    const after = items.slice(0, i).map((other, j) => (other.status === 'completed' ? 0 : j + 1)).filter(n => n > 0)
+    open.push({ index: i + 1, content: item.content, after })
+  })
+  await update($, planned, () => open)
+}
+
+/**
+ * Counts a subagent's model requests and keeps its model and effort current.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id of the subagent that made the request.
+ * @param model - Model the request ran on.
+ * @param effort - Effort level of the request, or `undefined` when none applies.
+ */
+async function countStep($: EngineInterface, agentId: string, model: string, effort: string | undefined): Promise<void> {
+  await patchCrab($, crab => crab.agentId === agentId, crab => ({ ...crab, requests: crab.requests + 1, model, effort: effort ?? crab.effort }))
+}
+
+/**
+ * Redraws once a second while a crab runs, so its time moves.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
+async function tick($: EngineInterface): Promise<void> {
+  if ((await read($, crabs)).some(crab => crab.status === 'running')) $.ui.invalidate('ui.render')
+}
+
+/**
+ * Reads the session's context window size into state, keeping the old size when the read fails.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
+async function readWindow($: EngineInterface): Promise<void> {
+  const usage = await $.session.usage().catch(() => undefined)
+  if (usage !== undefined && usage.context.window > 0) await update($, contextWindow, () => usage.context.window)
+}
+
+/**
+ * Registers this mod's `crabs` command, its session, tool, subagent and turn hooks, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'crabs', description: 'Show or hide the subagent crabs' })
+    await readWindow($)
+    $.clock.every(1000, () => void tick($))
+    return next(e)
+  })
+
+  on('command.run', { command: 'crabs' }, async $ => {
+    if ((await $.ui.panes()).some(pane => pane.id === PANE)) {
+      await $.ui.close({ id: PANE })
+      return { text: 'Crabs hidden.' }
+    }
+    await $.ui.open({ id: PANE, title: TITLE })
+    return { text: 'Crabs shown.' }
+  })
+
+  on('tool.call', { tool: 'Agent' }, async ($, e, next) => {
+    if (e.agentId !== undefined) return next(e)
+    const startedAt = await $.clock.now()
+    await startCrab($, {
+      id: e.tool_use_id,
+      title: e.description,
+      subagentType: e.subagent_type ?? 'general-purpose',
+      model: e.model ?? 'inherit',
+      effort: e.effort === undefined ? undefined : String(e.effort),
+      status: 'running',
+      startedAt,
+      steps: { done: 0, total: 0 },
+      requests: 0,
+    })
+    const ran = await next(e)
+    if ('deny' in ran) {
+      await update($, crabs, list => list.filter(crab => crab.id !== e.tool_use_id))
+      return ran
+    }
+    await finishCrab($, e.tool_use_id, ran.result, ran.isError === true)
+    return ran
+  }).catch(($, e, next) => next(e))
+
+  on('tool.call', { tool: 'TodoWrite' }, async ($, e, next) => {
+    const ran = await next(e)
+    if (!('deny' in ran) && ran.isError !== true) await readTodos($, e.todos, e.agentId)
+    return ran
+  }).catch(($, e, next) => next(e))
+
+  on('classic.SubagentStart', async ($, e, next) => {
+    await bindAgent($, e.agent_id, e.agent_type)
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  on('turn.step', async function* ($, e, next) {
+    if (e.agentId !== undefined) await countStep($, e.agentId, e.model, e.effort === undefined ? undefined : String(e.effort))
+    return yield* next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    const result = await next(e)
+    if (e.agentId !== undefined) await finishBackground($, e.agentId, e.usage === undefined ? undefined : { ...e.usage })
+    return result
+  }).catch(($, e, next) => next(e))
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const list = await read($, crabs)
+    const plan = await read($, planned)
+    const window = await read($, contextWindow)
+    const now = await $.clock.now()
+    if (list.length === 0 && plan.length === 0) return <Text dimColor>No subagents yet. Each one shows up here as a crab.</Text>
+
+    const barWidth = Math.max(120, (e.props.bodyColumns - 10) * 7)
+    /**
+     * Draws a crab sprite: an emoji in the terminal, an SVG elsewhere.
+     *
+     * @param hat - Hat to draw, a key of `HATS`.
+     * @param isPlanned - Whether the crab is planned work.
+     * @returns The sprite element.
+     */
+    const sprite = (hat: keyof typeof HATS, isPlanned: boolean) => {
+      if (e.surface === 'terminal') return <Text color={isPlanned ? '#6b7280' : PALETTE.b}>🦀</Text>
+      const { Svg } = $.ui.resolve(e)
+      return <Svg source={crabSvg(hat, isPlanned)} alt="crab" width={12 * PIXEL} height={11 * PIXEL} />
+    }
+    /**
+     * Draws a progress bar for a crab.
+     *
+     * @param share - Filled part of the bar, from `0` to `1`.
+     * @param color - Fill color as a CSS hex string.
+     * @returns The bar element.
+     */
+    const progress = (share: number, color: string) => {
+      if (e.surface === 'terminal') {
+        const cells = Math.max(10, e.props.bodyColumns - 10)
+        const filled = Math.round(Math.max(0, Math.min(1, share)) * cells)
+        return <Text><Text color={color}>{'━'.repeat(filled)}</Text><Text color="#2b3240">{'━'.repeat(cells - filled)}</Text></Text>
+      }
+      const { Svg } = $.ui.resolve(e)
+      return <Svg source={progressSvg(barWidth, share, color)} alt={`${Math.round(share * 100)}%`} width={barWidth} height={5} />
+    }
+
+    /**
+     * Draws one crab card: sprite, title, tier, model, step line, stats and progress.
+     *
+     * @param crab - Crab to draw, see `Crab`.
+     * @returns The card element.
+     */
+    const card = (crab: Crab) => {
+      const tier = tierOf(crab.effort)
+      const elapsed = crab.durationMs ?? now - crab.startedAt
+      const tokens = crab.tokens ?? 0
+      const share = crab.steps.total > 0 ? crab.steps.done / crab.steps.total : crab.status === 'running' ? 0.08 + Math.min(0.8, crab.requests / 40) : 1
+      const stepLine = crab.steps.total > 0
+        ? `${crab.steps.done}/${crab.steps.total}${crab.steps.current === undefined ? '' : ` · ${crab.steps.current}`}`
+        : crab.status === 'running' ? `step ${crab.requests}` : `${crab.requests} step${crab.requests === 1 ? '' : 's'}`
+      const stats = [
+        tokens > 0 ? `ctx ${Math.max(1, Math.round((tokens / window) * 100))}%` : '',
+        tokens > 0 ? formatTokens(tokens) : '',
+        crab.costUsd === undefined ? '' : `≈$${crab.costUsd.toFixed(2)}`,
+        minutes(elapsed),
+      ].filter(part => part.length > 0).join(' · ')
+      const mark = crab.status === 'running' ? <Text color="#2f6b4a">●</Text>
+        : crab.status === 'failed' ? <Text color="#e06c6c">✗</Text>
+        : <Text color="#7cc47f">✓</Text>
+      return (
+        <Box flexDirection="row" columnGap={2} paddingY={1}>
+          {sprite(tier.hat, false)}
+          <Box flexDirection="column" flexGrow={1}>
+            <Box flexDirection="row" justifyContent="space-between">
+              <Text bold wrap="truncate-end">{crab.title}</Text>
+              {mark}
+            </Box>
+            <Text>
+              <Text color={tier.color}>{tier.name}</Text>
+              <Text dimColor> {modelName(crab.model)}{crab.effort === undefined ? '' : ` · ${crab.effort}`}</Text>
+            </Text>
+            <Box flexDirection="row" justifyContent="space-between">
+              <Text wrap="truncate-end">{stepLine}</Text>
+              <Text dimColor>{stats}</Text>
+            </Box>
+            {progress(share, tier.color)}
+          </Box>
+        </Box>
+      )
+    }
+
+    const running = list.filter(crab => crab.status === 'running')
+    const done = list.filter(crab => crab.status !== 'running')
+
+    return (
+      <Box flexDirection="column">
+        {running.map(card)}
+        {done.length > 0 && <Text dimColor>▾ Finished · {done.length}</Text>}
+        {done.slice().reverse().map(card)}
+        {plan.length > 0 && <Text dimColor>Planned · {plan.length}</Text>}
+        {plan.map(item => (
+          <Box flexDirection="row" columnGap={2} paddingY={1}>
+            {sprite('beanie', true)}
+            <Box flexDirection="column" flexGrow={1}>
+              <Box flexDirection="row" justifyContent="space-between">
+                <Text bold dimColor wrap="truncate-end">{item.index}. {item.content}</Text>
+                <Text dimColor>◷</Text>
+              </Box>
+              <Text dimColor>planned{item.after.length > 0 ? ` · after ${item.after.join(', ')}` : ''}</Text>
+            </Box>
+          </Box>
+        ))}
+      </Box>
+    )
+  })
+}

package/mods/custom-crab-agents/types/index.d.ts

@@ -0,0 +1,45 @@
+// packages/g3n-mods/mods/custom-crab-agents/types/index.d.ts
+
+/** Progress a subagent reported through its own todo list. */
+export type CrabSteps = {
+  done: number
+  total: number
+  /** The step in progress, as its todo's active form says, e.g. `Writing hero copy` */
+  current?: string
+}
+
+/** One subagent drawn as a crab; times are milliseconds since the epoch. */
+export type Crab = {
+  /** The Agent call's tool_use_id */
+  id: string
+  title: string
+  subagentType: string
+  /** Model id or alias, e.g. `claude-opus-5-5` or `haiku` */
+  model: string
+  /** `low`, `medium`, `high`, `xhigh` or `max` */
+  effort?: string
+  status: 'running' | 'finished' | 'failed'
+  agentId?: string
+  startedAt: number
+  durationMs?: number
+  tokens?: number
+  costUsd?: number
+  steps: CrabSteps
+  /** Model requests the subagent has made so far */
+  requests: number
+}
+
+/** One open item of the main thread's todo list, drawn as a planned crab. */
+export type PlannedItem = {
+  /** 1-based position in the todo list */
+  index: number
+  content: string
+  /** Positions of the open items before it */
+  after: number[]
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'custom-crab-agents': { crabs: Crab[]; planned: PlannedItem[]; window: number }
+  }
+}

package/mods/delete-guard/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "delete-guard",
+  "version": "0.1.0",
+  "description": "Denies rm -rf and other permanent deletes and points Claude to the trash.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts"
+}

package/mods/delete-guard/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.ts"] }