subagent-cli 0.3.0 → 0.3.1

package/src/types/hooks.ts

@@ -1,290 +0,0 @@
-// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
-import { z } from 'zod/v4'
-import { lazySchema } from '../utils/lazySchema.js'
-import {
-  type HookEvent,
-  HOOK_EVENTS,
-  type HookInput,
-  type PermissionUpdate,
-} from 'src/entrypoints/agentSdkTypes.js'
-import type {
-  HookJSONOutput,
-  AsyncHookJSONOutput,
-  SyncHookJSONOutput,
-} from 'src/entrypoints/agentSdkTypes.js'
-import type { Message } from 'src/types/message.js'
-import type { PermissionResult } from 'src/utils/permissions/PermissionResult.js'
-import { permissionBehaviorSchema } from 'src/utils/permissions/PermissionRule.js'
-import { permissionUpdateSchema } from 'src/utils/permissions/PermissionUpdateSchema.js'
-import type { AppState } from '../state/AppState.js'
-import type { AttributionState } from '../utils/commitAttribution.js'
-
-export function isHookEvent(value: string): value is HookEvent {
-  return HOOK_EVENTS.includes(value as HookEvent)
-}
-
-// Prompt elicitation protocol types. The `prompt` key acts as discriminator
-// (mirroring the {async:true} pattern), with the id as its value.
-export const promptRequestSchema = lazySchema(() =>
-  z.object({
-    prompt: z.string(), // request id
-    message: z.string(),
-    options: z.array(
-      z.object({
-        key: z.string(),
-        label: z.string(),
-        description: z.string().optional(),
-      }),
-    ),
-  }),
-)
-
-export type PromptRequest = z.infer<ReturnType<typeof promptRequestSchema>>
-
-export type PromptResponse = {
-  prompt_response: string // request id
-  selected: string
-}
-
-// Sync hook response schema
-export const syncHookResponseSchema = lazySchema(() =>
-  z.object({
-    continue: z
-      .boolean()
-      .describe('Whether Claude should continue after hook (default: true)')
-      .optional(),
-    suppressOutput: z
-      .boolean()
-      .describe('Hide stdout from transcript (default: false)')
-      .optional(),
-    stopReason: z
-      .string()
-      .describe('Message shown when continue is false')
-      .optional(),
-    decision: z.enum(['approve', 'block']).optional(),
-    reason: z.string().describe('Explanation for the decision').optional(),
-    systemMessage: z
-      .string()
-      .describe('Warning message shown to the user')
-      .optional(),
-    hookSpecificOutput: z
-      .union([
-        z.object({
-          hookEventName: z.literal('PreToolUse'),
-          permissionDecision: permissionBehaviorSchema().optional(),
-          permissionDecisionReason: z.string().optional(),
-          updatedInput: z.record(z.string(), z.unknown()).optional(),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('UserPromptSubmit'),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('SessionStart'),
-          additionalContext: z.string().optional(),
-          initialUserMessage: z.string().optional(),
-          watchPaths: z
-            .array(z.string())
-            .describe('Absolute paths to watch for FileChanged hooks')
-            .optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('Setup'),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('SubagentStart'),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('PostToolUse'),
-          additionalContext: z.string().optional(),
-          updatedMCPToolOutput: z
-            .unknown()
-            .describe('Updates the output for MCP tools')
-            .optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('PostToolUseFailure'),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('PermissionDenied'),
-          retry: z.boolean().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('Notification'),
-          additionalContext: z.string().optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('PermissionRequest'),
-          decision: z.union([
-            z.object({
-              behavior: z.literal('allow'),
-              updatedInput: z.record(z.string(), z.unknown()).optional(),
-              updatedPermissions: z.array(permissionUpdateSchema()).optional(),
-            }),
-            z.object({
-              behavior: z.literal('deny'),
-              message: z.string().optional(),
-              interrupt: z.boolean().optional(),
-            }),
-          ]),
-        }),
-        z.object({
-          hookEventName: z.literal('Elicitation'),
-          action: z.enum(['accept', 'decline', 'cancel']).optional(),
-          content: z.record(z.string(), z.unknown()).optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('ElicitationResult'),
-          action: z.enum(['accept', 'decline', 'cancel']).optional(),
-          content: z.record(z.string(), z.unknown()).optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('CwdChanged'),
-          watchPaths: z
-            .array(z.string())
-            .describe('Absolute paths to watch for FileChanged hooks')
-            .optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('FileChanged'),
-          watchPaths: z
-            .array(z.string())
-            .describe('Absolute paths to watch for FileChanged hooks')
-            .optional(),
-        }),
-        z.object({
-          hookEventName: z.literal('WorktreeCreate'),
-          worktreePath: z.string(),
-        }),
-      ])
-      .optional(),
-  }),
-)
-
-// Zod schema for hook JSON output validation
-export const hookJSONOutputSchema = lazySchema(() => {
-  // Async hook response schema
-  const asyncHookResponseSchema = z.object({
-    async: z.literal(true),
-    asyncTimeout: z.number().optional(),
-  })
-  return z.union([asyncHookResponseSchema, syncHookResponseSchema()])
-})
-
-// Infer the TypeScript type from the schema
-type SchemaHookJSONOutput = z.infer<ReturnType<typeof hookJSONOutputSchema>>
-
-// Type guard function to check if response is sync
-export function isSyncHookJSONOutput(
-  json: HookJSONOutput,
-): json is SyncHookJSONOutput {
-  return !('async' in json && json.async === true)
-}
-
-// Type guard function to check if response is async
-export function isAsyncHookJSONOutput(
-  json: HookJSONOutput,
-): json is AsyncHookJSONOutput {
-  return 'async' in json && json.async === true
-}
-
-// Compile-time assertion that SDK and Zod types match
-import type { IsEqual } from 'type-fest'
-type Assert<T extends true> = T
-type _assertSDKTypesMatch = Assert<
-  IsEqual<SchemaHookJSONOutput, HookJSONOutput>
->
-
-/** Context passed to callback hooks for state access */
-export type HookCallbackContext = {
-  getAppState: () => AppState
-  updateAttributionState: (
-    updater: (prev: AttributionState) => AttributionState,
-  ) => void
-}
-
-/** Hook that is a callback. */
-export type HookCallback = {
-  type: 'callback'
-  callback: (
-    input: HookInput,
-    toolUseID: string | null,
-    abort: AbortSignal | undefined,
-    /** Hook index for SessionStart hooks to compute CLAUDE_ENV_FILE path */
-    hookIndex?: number,
-    /** Optional context for accessing app state */
-    context?: HookCallbackContext,
-  ) => Promise<HookJSONOutput>
-  /** Timeout in seconds for this hook */
-  timeout?: number
-  /** Internal hooks (e.g. session file access analytics) are excluded from tengu_run_hook metrics */
-  internal?: boolean
-}
-
-export type HookCallbackMatcher = {
-  matcher?: string
-  hooks: HookCallback[]
-  pluginName?: string
-}
-
-export type HookProgress = {
-  type: 'hook_progress'
-  hookEvent: HookEvent
-  hookName: string
-  command: string
-  promptText?: string
-  statusMessage?: string
-}
-
-export type HookBlockingError = {
-  blockingError: string
-  command: string
-}
-
-export type PermissionRequestResult =
-  | {
-      behavior: 'allow'
-      updatedInput?: Record<string, unknown>
-      updatedPermissions?: PermissionUpdate[]
-    }
-  | {
-      behavior: 'deny'
-      message?: string
-      interrupt?: boolean
-    }
-
-export type HookResult = {
-  message?: Message
-  systemMessage?: Message
-  blockingError?: HookBlockingError
-  outcome: 'success' | 'blocking' | 'non_blocking_error' | 'cancelled'
-  preventContinuation?: boolean
-  stopReason?: string
-  permissionBehavior?: 'ask' | 'deny' | 'allow' | 'passthrough'
-  hookPermissionDecisionReason?: string
-  additionalContext?: string
-  initialUserMessage?: string
-  updatedInput?: Record<string, unknown>
-  updatedMCPToolOutput?: unknown
-  permissionRequestResult?: PermissionRequestResult
-  retry?: boolean
-}
-
-export type AggregatedHookResult = {
-  message?: Message
-  blockingErrors?: HookBlockingError[]
-  preventContinuation?: boolean
-  stopReason?: string
-  hookPermissionDecisionReason?: string
-  permissionBehavior?: PermissionResult['behavior']
-  additionalContexts?: string[]
-  initialUserMessage?: string
-  updatedInput?: Record<string, unknown>
-  updatedMCPToolOutput?: unknown
-  permissionRequestResult?: PermissionRequestResult
-  retry?: boolean
-}

package/src/types/ids.ts

@@ -1,44 +0,0 @@
-/**
- * Branded types for session and agent IDs.
- * These prevent accidentally mixing up session IDs and agent IDs at compile time.
- */
-
-/**
- * A session ID uniquely identifies a Claude Code session.
- * Returned by getSessionId().
- */
-export type SessionId = string & { readonly __brand: 'SessionId' }
-
-/**
- * An agent ID uniquely identifies a subagent within a session.
- * Returned by createAgentId().
- * When present, indicates the context is a subagent (not the main session).
- */
-export type AgentId = string & { readonly __brand: 'AgentId' }
-
-/**
- * Cast a raw string to SessionId.
- * Use sparingly - prefer getSessionId() when possible.
- */
-export function asSessionId(id: string): SessionId {
-  return id as SessionId
-}
-
-/**
- * Cast a raw string to AgentId.
- * Use sparingly - prefer createAgentId() when possible.
- */
-export function asAgentId(id: string): AgentId {
-  return id as AgentId
-}
-
-const AGENT_ID_PATTERN = /^a(?:.+-)?[0-9a-f]{16}$/
-
-/**
- * Validate and brand a string as AgentId.
- * Matches the format produced by createAgentId(): `a` + optional `<label>-` + 16 hex chars.
- * Returns null if the string doesn't match (e.g. teammate names, team-addressing).
- */
-export function toAgentId(s: string): AgentId | null {
-  return AGENT_ID_PATTERN.test(s) ? (s as AgentId) : null
-}

package/src/types/logs.ts

@@ -1,330 +0,0 @@
-import type { UUID } from 'crypto'
-import type { FileHistorySnapshot } from 'src/utils/fileHistory.js'
-import type { ContentReplacementRecord } from 'src/utils/toolResultStorage.js'
-import type { AgentId } from './ids.js'
-import type { Message } from './message.js'
-import type { QueueOperationMessage } from './messageQueueTypes.js'
-
-export type SerializedMessage = Message & {
-  cwd: string
-  userType: string
-  entrypoint?: string // CLAUDE_CODE_ENTRYPOINT — distinguishes cli/sdk-ts/sdk-py/etc.
-  sessionId: string
-  timestamp: string
-  version: string
-  gitBranch?: string
-  slug?: string // Session slug for files like plans (used for resume)
-}
-
-export type LogOption = {
-  date: string
-  messages: SerializedMessage[]
-  fullPath?: string
-  value: number
-  created: Date
-  modified: Date
-  firstPrompt: string
-  messageCount: number
-  fileSize?: number // File size in bytes (for display)
-  isSidechain: boolean
-  isLite?: boolean // True for lite logs (messages not loaded)
-  sessionId?: string // Session ID for lite logs
-  teamName?: string // Team name if this is a spawned agent session
-  agentName?: string // Agent's custom name (from /rename or swarm)
-  agentColor?: string // Agent's color (from /rename or swarm)
-  agentSetting?: string // Agent definition used (from --agent flag or settings.agent)
-  isTeammate?: boolean // Whether this session was created by a swarm teammate
-  leafUuid?: UUID // If given, this uuid must appear in the DB
-  summary?: string // Optional conversation summary
-  customTitle?: string // Optional user-set custom title
-  tag?: string // Optional tag for the session (searchable in /resume)
-  fileHistorySnapshots?: FileHistorySnapshot[] // Optional file history snapshots
-  attributionSnapshots?: AttributionSnapshotMessage[] // Optional attribution snapshots
-  contextCollapseCommits?: ContextCollapseCommitEntry[] // Ordered — commit B may reference commit A's summary
-  contextCollapseSnapshot?: ContextCollapseSnapshotEntry // Last-wins — staged queue + spawn state
-  gitBranch?: string // Git branch at the end of the session
-  projectPath?: string // Original project directory path
-  prNumber?: number // GitHub PR number linked to this session
-  prUrl?: string // Full URL to the linked PR
-  prRepository?: string // Repository in "owner/repo" format
-  mode?: 'coordinator' | 'normal' // Session mode for coordinator/normal detection
-  worktreeSession?: PersistedWorktreeSession | null // Worktree state at session end (null = exited, undefined = never entered)
-  contentReplacements?: ContentReplacementRecord[] // Replacement decisions for resume reconstruction
-}
-
-export type SummaryMessage = {
-  type: 'summary'
-  leafUuid: UUID
-  summary: string
-}
-
-export type CustomTitleMessage = {
-  type: 'custom-title'
-  sessionId: UUID
-  customTitle: string
-}
-
-/**
- * AI-generated session title. Distinct from CustomTitleMessage so that:
- * - User renames (custom-title) always win over AI titles in read preference
- * - reAppendSessionMetadata never re-appends AI titles (they're ephemeral/
- *   regeneratable; re-appending would clobber user renames on resume)
- * - VS Code's onlyIfNoCustomTitle CAS check only matches user titles,
- *   allowing AI to overwrite its own previous AI title but not user titles
- */
-export type AiTitleMessage = {
-  type: 'ai-title'
-  sessionId: UUID
-  aiTitle: string
-}
-
-export type LastPromptMessage = {
-  type: 'last-prompt'
-  sessionId: UUID
-  lastPrompt: string
-}
-
-/**
- * Periodic fork-generated summary of what the agent is currently doing.
- * Written every min(5 steps, 2min) by forking the main thread mid-turn so
- * `claude ps` can show something more useful than the last user prompt
- * (which is often "ok go" or "fix it").
- */
-export type TaskSummaryMessage = {
-  type: 'task-summary'
-  sessionId: UUID
-  summary: string
-  timestamp: string
-}
-
-export type TagMessage = {
-  type: 'tag'
-  sessionId: UUID
-  tag: string
-}
-
-export type AgentNameMessage = {
-  type: 'agent-name'
-  sessionId: UUID
-  agentName: string
-}
-
-export type AgentColorMessage = {
-  type: 'agent-color'
-  sessionId: UUID
-  agentColor: string
-}
-
-export type AgentSettingMessage = {
-  type: 'agent-setting'
-  sessionId: UUID
-  agentSetting: string
-}
-
-/**
- * PR link message stored in session transcript.
- * Links a session to a GitHub pull request for tracking and navigation.
- */
-export type PRLinkMessage = {
-  type: 'pr-link'
-  sessionId: UUID
-  prNumber: number
-  prUrl: string
-  prRepository: string // e.g., "owner/repo"
-  timestamp: string // ISO timestamp when linked
-}
-
-export type ModeEntry = {
-  type: 'mode'
-  sessionId: UUID
-  mode: 'coordinator' | 'normal'
-}
-
-/**
- * Worktree session state persisted to the transcript for resume.
- * Subset of WorktreeSession from utils/worktree.ts — excludes ephemeral
- * fields (creationDurationMs, usedSparsePaths) that are only used for
- * first-run analytics.
- */
-export type PersistedWorktreeSession = {
-  originalCwd: string
-  worktreePath: string
-  worktreeName: string
-  worktreeBranch?: string
-  originalBranch?: string
-  originalHeadCommit?: string
-  sessionId: string
-  tmuxSessionName?: string
-  hookBased?: boolean
-}
-
-/**
- * Records whether the session is currently inside a worktree created by
- * EnterWorktree or --worktree. Last-wins: an enter writes the session,
- * an exit writes null. On --resume, restored only if the worktreePath
- * still exists on disk (the /exit dialog may have removed it).
- */
-export type WorktreeStateEntry = {
-  type: 'worktree-state'
-  sessionId: UUID
-  worktreeSession: PersistedWorktreeSession | null
-}
-
-/**
- * Records content blocks whose in-context representation was replaced with a
- * smaller stub (the full content was persisted elsewhere). Replayed on resume
- * for prompt cache stability. Written once per enforcement pass that replaces
- * at least one block. When agentId is set, the record belongs to a subagent
- * sidechain (AgentTool resume reads these); when absent, it's main-thread
- * (/resume reads these).
- */
-export type ContentReplacementEntry = {
-  type: 'content-replacement'
-  sessionId: UUID
-  agentId?: AgentId
-  replacements: ContentReplacementRecord[]
-}
-
-export type FileHistorySnapshotMessage = {
-  type: 'file-history-snapshot'
-  messageId: UUID
-  snapshot: FileHistorySnapshot
-  isSnapshotUpdate: boolean
-}
-
-/**
- * Per-file attribution state tracking Claude's character contributions.
- */
-export type FileAttributionState = {
-  contentHash: string // SHA-256 hash of file content
-  claudeContribution: number // Characters written by Claude
-  mtime: number // File modification time
-}
-
-/**
- * Attribution snapshot message stored in session transcript.
- * Tracks character-level contributions by Claude for commit attribution.
- */
-export type AttributionSnapshotMessage = {
-  type: 'attribution-snapshot'
-  messageId: UUID
-  surface: string // Client surface (cli, ide, web, api)
-  fileStates: Record<string, FileAttributionState>
-  promptCount?: number // Total prompts in session
-  promptCountAtLastCommit?: number // Prompts at last commit
-  permissionPromptCount?: number // Total permission prompts shown
-  permissionPromptCountAtLastCommit?: number // Permission prompts at last commit
-  escapeCount?: number // Total ESC presses (cancelled permission prompts)
-  escapeCountAtLastCommit?: number // ESC presses at last commit
-}
-
-export type TranscriptMessage = SerializedMessage & {
-  parentUuid: UUID | null
-  logicalParentUuid?: UUID | null // Preserves logical parent when parentUuid is nullified for session breaks
-  isSidechain: boolean
-  gitBranch?: string
-  agentId?: string // Agent ID for sidechain transcripts to enable resuming agents
-  teamName?: string // Team name if this is a spawned agent session
-  agentName?: string // Agent's custom name (from /rename or swarm)
-  agentColor?: string // Agent's color (from /rename or swarm)
-  promptId?: string // Correlates with OTel prompt.id for user prompt messages
-}
-
-export type SpeculationAcceptMessage = {
-  type: 'speculation-accept'
-  timestamp: string
-  timeSavedMs: number
-}
-
-/**
- * Persisted context-collapse commit. The archived messages themselves are
- * NOT persisted — they're already in the transcript as ordinary user/
- * assistant messages. We only persist enough to reconstruct the splice
- * instruction (boundary uuids) and the summary placeholder (which is NOT
- * in the transcript because it's never yielded to the REPL).
- *
- * On restore, the store reconstructs CommittedCollapse with archived=[];
- * projectView lazily fills the archive the first time it finds the span.
- *
- * Discriminator is obfuscated to match the gate name. sessionStorage.ts
- * isn't feature-gated (it's the generic transcript plumbing used by every
- * entry type), so a descriptive string here would leak into external builds
- * via the appendEntry dispatch / loadTranscriptFile parser even though
- * nothing in an external build ever writes or reads this entry.
- */
-export type ContextCollapseCommitEntry = {
-  type: 'marble-origami-commit'
-  sessionId: UUID
-  /** 16-digit collapse ID. Max across entries reseeds the ID counter. */
-  collapseId: string
-  /** The summary placeholder's uuid — registerSummary() needs it. */
-  summaryUuid: string
-  /** Full <collapsed id="...">text</collapsed> string for the placeholder. */
-  summaryContent: string
-  /** Plain summary text for ctx_inspect. */
-  summary: string
-  /** Span boundaries — projectView finds these in the resumed Message[]. */
-  firstArchivedUuid: string
-  lastArchivedUuid: string
-}
-
-/**
- * Snapshot of the staged queue and spawn trigger state. Unlike commits
- * (append-only, replay-all), snapshots are last-wins — only the most
- * recent snapshot entry is applied on restore. Written after every
- * ctx-agent spawn resolves (when staged contents may have changed).
- *
- * Staged boundaries are UUIDs (session-stable), not collapse IDs (which
- * reset with the uuidToId bimap). Restoring a staged span issues fresh
- * collapse IDs for those messages on the next decorate/display, but the
- * span itself resolves correctly.
- */
-export type ContextCollapseSnapshotEntry = {
-  type: 'marble-origami-snapshot'
-  sessionId: UUID
-  staged: Array<{
-    startUuid: string
-    endUuid: string
-    summary: string
-    risk: number
-    stagedAt: number
-  }>
-  /** Spawn trigger state — so the +interval clock picks up where it left off. */
-  armed: boolean
-  lastSpawnTokens: number
-}
-
-export type Entry =
-  | TranscriptMessage
-  | SummaryMessage
-  | CustomTitleMessage
-  | AiTitleMessage
-  | LastPromptMessage
-  | TaskSummaryMessage
-  | TagMessage
-  | AgentNameMessage
-  | AgentColorMessage
-  | AgentSettingMessage
-  | PRLinkMessage
-  | FileHistorySnapshotMessage
-  | AttributionSnapshotMessage
-  | QueueOperationMessage
-  | SpeculationAcceptMessage
-  | ModeEntry
-  | WorktreeStateEntry
-  | ContentReplacementEntry
-  | ContextCollapseCommitEntry
-  | ContextCollapseSnapshotEntry
-
-export function sortLogs(logs: LogOption[]): LogOption[] {
-  return logs.sort((a, b) => {
-    // Sort by modified date (newest first)
-    const modifiedDiff = b.modified.getTime() - a.modified.getTime()
-    if (modifiedDiff !== 0) {
-      return modifiedDiff
-    }
-
-    // If modified dates are equal, sort by created date (newest first)
-    return b.created.getTime() - a.created.getTime()
-  })
-}

package/src/types/message.ts

@@ -1,40 +0,0 @@
-// Stub: types/message.ts - all type exports
-export type AssistantMessage = any
-export type AttachmentMessage = any
-export type CollapsedReadSearchGroup = any
-export type CollapsibleMessage = any
-export type CompactMetadata = any
-export type GroupedToolUseMessage = any
-export type HookResultMessage = any
-export type Message = any
-export type MessageOrigin = any
-export type NormalizedAssistantMessage = any
-export type NormalizedMessage = any
-export type NormalizedUserMessage = any
-export type PartialCompactDirection = any
-export type ProgressMessage = any
-export type RenderableMessage = any
-export type RequestStartEvent = any
-export type StopHookInfo = any
-export type StreamEvent = any
-export type SystemAgentsKilledMessage = any
-export type SystemAPIErrorMessage = any
-export type SystemApiMetricsMessage = any
-export type SystemAwaySummaryMessage = any
-export type SystemBridgeStatusMessage = any
-export type SystemCompactBoundaryMessage = any
-export type SystemFileSnapshotMessage = any
-export type SystemInformationalMessage = any
-export type SystemLocalCommandMessage = any
-export type SystemMemorySavedMessage = any
-export type SystemMessage = any
-export type SystemMessageLevel = any
-export type SystemMicrocompactBoundaryMessage = any
-export type SystemPermissionRetryMessage = any
-export type SystemScheduledTaskFireMessage = any
-export type SystemStopHookSummaryMessage = any
-export type SystemThinkingMessage = any
-export type SystemTurnDurationMessage = any
-export type TombstoneMessage = any
-export type ToolUseSummaryMessage = any
-export type UserMessage = any