@mseep/claudian 2.0.25

package/src/utils/slashCommand.ts

@@ -0,0 +1,152 @@
+import type { SlashCommand } from '../core/types';
+import {
+  extractBoolean,
+  extractString,
+  extractStringArray,
+  isRecord,
+  parseFrontmatter,
+  validateSlugName,
+} from './frontmatter';
+
+export interface ParsedSlashCommandContent {
+  description?: string;
+  argumentHint?: string;
+  allowedTools?: string[];
+  model?: string;
+  promptContent: string;
+  // Skill fields
+  disableModelInvocation?: boolean;
+  userInvocable?: boolean;
+  context?: 'fork';
+  agent?: string;
+  hooks?: Record<string, unknown>;
+}
+
+export function extractFirstParagraph(content: string): string | undefined {
+  const paragraph = content.split(/\n\s*\n/).find(p => p.trim());
+  if (!paragraph) return undefined;
+  return paragraph.trim().replace(/\n/g, ' ');
+}
+
+export function validateCommandName(name: string): string | null {
+  return validateSlugName(name, 'Command');
+}
+
+export function isSkill(cmd: SlashCommand): boolean {
+  if (cmd.kind) return cmd.kind === 'skill';
+  return cmd.id.startsWith('skill-');
+}
+
+export function parsedToSlashCommand(
+  parsed: ParsedSlashCommandContent,
+  identity: Pick<SlashCommand, 'id' | 'name'> & { source?: SlashCommand['source'] },
+): SlashCommand {
+  return {
+    ...identity,
+    description: parsed.description,
+    argumentHint: parsed.argumentHint,
+    allowedTools: parsed.allowedTools,
+    model: parsed.model,
+    content: parsed.promptContent,
+    disableModelInvocation: parsed.disableModelInvocation,
+    userInvocable: parsed.userInvocable,
+    context: parsed.context,
+    agent: parsed.agent,
+    hooks: parsed.hooks,
+  };
+}
+
+export function parseSlashCommandContent(content: string): ParsedSlashCommandContent {
+  const parsed = parseFrontmatter(content);
+
+  if (!parsed) {
+    return { promptContent: content };
+  }
+
+  const fm = parsed.frontmatter;
+
+  return {
+    // Existing fields — support both kebab-case (file format) and camelCase
+    description: extractString(fm, 'description'),
+    argumentHint: extractString(fm, 'argument-hint') ?? extractString(fm, 'argumentHint'),
+    allowedTools: extractStringArray(fm, 'allowed-tools') ?? extractStringArray(fm, 'allowedTools'),
+    model: extractString(fm, 'model'),
+    promptContent: parsed.body,
+    // Skill fields — kebab-case preferred (CC file format), camelCase for backwards compat
+    disableModelInvocation:
+      extractBoolean(fm, 'disable-model-invocation') ?? extractBoolean(fm, 'disableModelInvocation'),
+    userInvocable:
+      extractBoolean(fm, 'user-invocable') ?? extractBoolean(fm, 'userInvocable'),
+    context: extractString(fm, 'context') === 'fork' ? 'fork' : undefined,
+    agent: extractString(fm, 'agent'),
+    hooks: isRecord(fm.hooks) ? fm.hooks : undefined,
+  };
+}
+
+export function normalizeArgumentHint(hint: string): string {
+  if (!hint) return hint;
+  if (hint.includes('[') || hint.includes('<')) return hint;
+  return `[${hint}]`;
+}
+
+export function yamlString(value: string): string {
+  if (value.includes(':') || value.includes('#') || value.includes('\n') ||
+      value.startsWith(' ') || value.endsWith(' ') ||
+      value.startsWith('[') || value.startsWith('{')) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+export function serializeCommand(cmd: SlashCommand): string {
+  const parsed = parseSlashCommandContent(cmd.content);
+  return serializeSlashCommandMarkdown(cmd, parsed.promptContent);
+}
+
+export function serializeSlashCommandMarkdown(cmd: Partial<SlashCommand>, body: string): string {
+  const lines: string[] = ['---'];
+
+  if (cmd.name) {
+    lines.push(`name: ${cmd.name}`);
+  }
+  if (cmd.description) {
+    lines.push(`description: ${yamlString(cmd.description)}`);
+  }
+  if (cmd.argumentHint) {
+    lines.push(`argument-hint: ${yamlString(cmd.argumentHint)}`);
+  }
+  if (cmd.allowedTools && cmd.allowedTools.length > 0) {
+    lines.push('allowed-tools:');
+    for (const tool of cmd.allowedTools) {
+      lines.push(`  - ${yamlString(tool)}`);
+    }
+  }
+  if (cmd.model) {
+    lines.push(`model: ${cmd.model}`);
+  }
+  if (cmd.disableModelInvocation !== undefined) {
+    lines.push(`disable-model-invocation: ${cmd.disableModelInvocation}`);
+  }
+  if (cmd.userInvocable !== undefined) {
+    lines.push(`user-invocable: ${cmd.userInvocable}`);
+  }
+  if (cmd.context) {
+    lines.push(`context: ${cmd.context}`);
+  }
+  if (cmd.agent) {
+    lines.push(`agent: ${cmd.agent}`);
+  }
+  if (cmd.hooks !== undefined) {
+    lines.push(`hooks: ${JSON.stringify(cmd.hooks)}`);
+  }
+  // Ensure at least one blank line between --- markers when no metadata exists
+  // (the frontmatter regex requires \n before the closing ---)
+  if (lines.length === 1) {
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(body);
+
+  return lines.join('\n');
+}

package/src/utils/subagentJsonl.ts

@@ -0,0 +1,52 @@
+/**
+ * Extracts the final textual result from subagent JSONL output.
+ * Prefers the latest assistant text block and falls back to top-level result.
+ */
+export function extractFinalResultFromSubagentJsonl(content: string): string | null {
+  const lines = content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && line.startsWith('{'));
+
+  let lastAssistantText: string | null = null;
+  let lastResultText: string | null = null;
+
+  for (const line of lines) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (!raw || typeof raw !== 'object') {
+      continue;
+    }
+
+    const record = raw as {
+      result?: unknown;
+      message?: { role?: unknown; content?: unknown };
+    };
+
+    if (typeof record.result === 'string' && record.result.trim().length > 0) {
+      lastResultText = record.result.trim();
+    }
+
+    if (record.message?.role !== 'assistant' || !Array.isArray(record.message.content)) {
+      continue;
+    }
+
+    for (const blockRaw of record.message.content) {
+      if (!blockRaw || typeof blockRaw !== 'object') {
+        continue;
+      }
+
+      const block = blockRaw as { type?: unknown; text?: unknown };
+      if (block.type === 'text' && typeof block.text === 'string' && block.text.trim().length > 0) {
+        lastAssistantText = block.text.trim();
+      }
+    }
+  }
+
+  return lastAssistantText ?? lastResultText;
+}

package/src/utils/windowsCmdShim.ts

@@ -0,0 +1,98 @@
+const WINDOWS_CMD_ARGUMENT_CHARS = /[\s"&<>|{}^=;!'+,`~()%@]/u;
+
+export interface WindowsCmdShimSpawnSpec {
+  args: string[];
+  command: string;
+  killProcessTree?: boolean;
+  windowsVerbatimArguments?: boolean;
+}
+
+interface KillableProcess {
+  kill(signal?: NodeJS.Signals | number): boolean;
+  pid?: number;
+}
+
+interface ErrorEmitterLike {
+  on(event: 'error', listener: (error: Error) => void): unknown;
+}
+
+type SpawnProcess = (
+  command: string,
+  args: string[],
+  options: { stdio: 'ignore'; windowsHide: true },
+) => unknown;
+
+export function resolveWindowsCmdShimSpawnSpec(
+  spec: Pick<WindowsCmdShimSpawnSpec, 'args' | 'command'>,
+): WindowsCmdShimSpawnSpec {
+  const command = spec.command.trim();
+  if (!command || process.platform !== 'win32' || !command.toLowerCase().endsWith('.cmd')) {
+    return {
+      args: spec.args,
+      command: spec.command,
+    };
+  }
+
+  const shellCommand = [command, ...spec.args]
+    .map(value => quoteWindowsShellArgument(value))
+    .join(' ');
+
+  return {
+    args: ['/d', '/s', '/c', `"${shellCommand}"`],
+    command: process.env.ComSpec || process.env.comspec || 'cmd.exe',
+    killProcessTree: true,
+    windowsVerbatimArguments: true,
+  };
+}
+
+export function terminateSpawnedProcess(
+  proc: KillableProcess,
+  signal: NodeJS.Signals | number | undefined,
+  spawnProcess: SpawnProcess,
+  spawnSpec?: WindowsCmdShimSpawnSpec | null,
+): boolean {
+  if (
+    process.platform !== 'win32'
+    || !spawnSpec?.killProcessTree
+    || typeof proc.pid !== 'number'
+  ) {
+    return proc.kill(signal);
+  }
+
+  try {
+    const taskkill = spawnProcess('taskkill.exe', ['/pid', String(proc.pid), '/t', '/f'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    if (isErrorEmitterLike(taskkill)) {
+      taskkill.on('error', () => {});
+    }
+    return true;
+  } catch {
+    return proc.kill(signal);
+  }
+}
+
+function isErrorEmitterLike(value: unknown): value is ErrorEmitterLike {
+  return value !== null
+    && typeof value === 'object'
+    && typeof (value as { on?: unknown }).on === 'function';
+}
+
+function requiresWindowsShellQuoting(value: string): boolean {
+  return WINDOWS_CMD_ARGUMENT_CHARS.test(value)
+    || value.includes('[')
+    || value.includes(']');
+}
+
+function quoteWindowsShellArgument(value: string): string {
+  if (!value.length) {
+    return '""';
+  }
+
+  if (!requiresWindowsShellQuoting(value)) {
+    return value;
+  }
+
+  return `"${value.replace(/"/g, '""')}"`;
+}

package/tests/__mocks__/claude-agent-sdk.ts

@@ -0,0 +1,317 @@
+// Mock for @anthropic-ai/claude-agent-sdk
+
+export interface HookCallbackMatcher {
+  matcher?: string;
+  hooks: Array<(hookInput: any, toolUseID: string, options: any) => Promise<{ continue: boolean; hookSpecificOutput?: any }>>;
+}
+
+export interface SpawnOptions {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env: {
+    [envVar: string]: string | undefined;
+  };
+  signal: AbortSignal;
+}
+
+export interface SpawnedProcess {
+  stdin: NodeJS.WritableStream;
+  stdout: NodeJS.ReadableStream;
+  stderr?: NodeJS.ReadableStream | null;
+  killed: boolean;
+  exitCode: number | null;
+  kill: (signal?: NodeJS.Signals) => void;
+  on: (event: 'exit' | 'error', listener: (...args: any[]) => void) => void;
+  once: (event: 'exit' | 'error', listener: (...args: any[]) => void) => void;
+  off: (event: 'exit' | 'error', listener: (...args: any[]) => void) => void;
+}
+
+export interface Options {
+  cwd?: string;
+  permissionMode?: string;
+  allowDangerouslySkipPermissions?: boolean;
+  model?: string;
+  tools?: string[];
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  abortController?: AbortController;
+  pathToClaudeCodeExecutable?: string;
+  resume?: string;
+  maxThinkingTokens?: number;
+  thinking?: { type: string; budgetTokens?: number };
+  effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  canUseTool?: CanUseTool;
+  systemPrompt?: string | { content: string; cacheControl?: { type: string } };
+  mcpServers?: Record<string, unknown>;
+  settingSources?: ('user' | 'project' | 'local')[];
+  spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess;
+  hooks?: {
+    PreToolUse?: HookCallbackMatcher[];
+    PostToolUse?: HookCallbackMatcher[];
+    Stop?: HookCallbackMatcher[];
+  };
+  agents?: Record<string, AgentDefinition>;
+  persistSession?: boolean;
+}
+
+export interface Settings {
+  effortLevel?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+}
+
+// Type exports that match the real SDK
+export type AgentDefinition = {
+  description: string;
+  tools?: string[];
+  disallowedTools?: string[];
+  prompt: string;
+  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
+  mcpServers?: unknown[];
+  skills?: string[];
+  maxTurns?: number;
+  hooks?: Record<string, unknown>;
+};
+
+export type AgentMcpServerSpec = string | Record<string, unknown>;
+
+export type McpServerConfig = Record<string, unknown>;
+
+export type PermissionBehavior = 'allow' | 'deny' | 'ask';
+
+export type PermissionRuleValue = {
+  toolName: string;
+  ruleContent?: string;
+};
+
+export type PermissionUpdateDestination = 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg';
+
+export type PermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'default' | 'delegate' | 'dontAsk' | 'plan';
+
+export type PermissionUpdate =
+  | { type: 'addRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination }
+  | { type: 'replaceRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination }
+  | { type: 'removeRules'; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination }
+  | { type: 'setMode'; mode: PermissionMode; destination: PermissionUpdateDestination }
+  | { type: 'addDirectories'; directories: string[]; destination: PermissionUpdateDestination }
+  | { type: 'removeDirectories'; directories: string[]; destination: PermissionUpdateDestination };
+
+export type CanUseTool = (toolName: string, input: Record<string, unknown>, options: {
+  signal: AbortSignal;
+  suggestions?: PermissionUpdate[];
+  blockedPath?: string;
+  decisionReason?: string;
+  toolUseID: string;
+  agentID?: string;
+}) => Promise<PermissionResult>;
+
+export type PermissionResult =
+  | { behavior: 'allow'; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; toolUseID?: string }
+  | { behavior: 'deny'; message: string; interrupt?: boolean; toolUseID?: string };
+
+// Default mock messages for testing
+const mockMessages = [
+  { type: 'system', subtype: 'init', session_id: 'test-session-123' },
+  { type: 'assistant', message: { content: [{ type: 'text', text: 'Hello, I am Claude!' }] } },
+  { type: 'result', subtype: 'success', result: 'completed' },
+];
+
+let customMockMessages: any[] | null = null;
+let appendResultMessage = true;
+let lastOptions: Options | undefined;
+let mockSupportedCommands: Array<{ name: string; description: string; argumentHint?: string }> = [];
+let lastResponse: (AsyncGenerator<any> & {
+  interrupt: jest.Mock;
+  setModel: jest.Mock;
+  setMaxThinkingTokens: jest.Mock;
+  setPermissionMode: jest.Mock;
+  applyFlagSettings: jest.Mock;
+  setMcpServers: jest.Mock;
+  supportedCommands: jest.Mock;
+}) | null = null;
+
+// Crash simulation control
+let shouldThrowOnIteration = false;
+let throwAfterChunks = 0;
+let queryCallCount = 0;
+
+// Allow tests to set custom mock messages
+export function setMockMessages(messages: any[], options?: { appendResult?: boolean }) {
+  customMockMessages = messages;
+  appendResultMessage = options?.appendResult ?? true;
+}
+
+export function resetMockMessages() {
+  customMockMessages = null;
+  appendResultMessage = true;
+  lastOptions = undefined;
+  mockSupportedCommands = [];
+  lastResponse = null;
+  shouldThrowOnIteration = false;
+  throwAfterChunks = 0;
+  queryCallCount = 0;
+}
+
+export function setMockSupportedCommands(
+  commands: Array<{ name: string; description: string; argumentHint?: string }>
+) {
+  mockSupportedCommands = commands;
+}
+
+/**
+ * Configure the mock to throw an error during iteration.
+ * @param afterChunks - Number of chunks to emit before throwing (0 = throw immediately)
+ */
+export function simulateCrash(afterChunks = 0) {
+  shouldThrowOnIteration = true;
+  throwAfterChunks = afterChunks;
+}
+
+/**
+ * Get the number of times query() was called (useful for verifying restart behavior).
+ */
+export function getQueryCallCount(): number {
+  return queryCallCount;
+}
+
+export function getLastOptions(): Options | undefined {
+  return lastOptions;
+}
+
+export function getLastResponse(): typeof lastResponse {
+  return lastResponse;
+}
+
+// Helper to run PreToolUse hooks
+async function runPreToolUseHooks(
+  hooks: HookCallbackMatcher[] | undefined,
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  toolId: string
+): Promise<{ blocked: boolean; reason?: string }> {
+  if (!hooks) return { blocked: false };
+
+  for (const hookMatcher of hooks) {
+    // Check if matcher matches the tool (no matcher = match all)
+    if (hookMatcher.matcher && hookMatcher.matcher !== toolName) {
+      continue;
+    }
+
+    for (const hookFn of hookMatcher.hooks) {
+      const hookInput = { tool_name: toolName, tool_input: toolInput };
+      const result = await hookFn(hookInput, toolId, {});
+
+      if (!result.continue) {
+        const reason = result.hookSpecificOutput?.permissionDecisionReason || 'Blocked by hook';
+        return { blocked: true, reason };
+      }
+    }
+  }
+
+  return { blocked: false };
+}
+
+// Mock query function that returns an async generator
+function isAsyncIterable(value: any): value is AsyncIterable<any> {
+  return !!value && typeof value[Symbol.asyncIterator] === 'function';
+}
+
+function getMessagesForPrompt(): any[] {
+  const baseMessages = customMockMessages || mockMessages;
+  const messages = [...baseMessages];
+  if (appendResultMessage && !messages.some((msg) => msg.type === 'result')) {
+    messages.push({ type: 'result', subtype: 'success' });
+  }
+  return messages;
+}
+
+async function* emitMessages(messages: any[], options: Options) {
+  let chunksEmitted = 0;
+
+  for (const msg of messages) {
+    // Check if we should throw (crash simulation)
+    if (shouldThrowOnIteration && chunksEmitted >= throwAfterChunks) {
+      // Reset for next query (allows recovery to work)
+      shouldThrowOnIteration = false;
+      throw new Error('Simulated consumer crash');
+    }
+
+    // Check for tool_use in assistant messages and run hooks
+    if (msg.type === 'assistant' && msg.message?.content) {
+      let wasBlocked = false;
+      for (const block of msg.message.content) {
+        if (block.type === 'tool_use') {
+          const hookResult = await runPreToolUseHooks(
+            options.hooks?.PreToolUse,
+            block.name,
+            block.input,
+            block.id || `tool-${Date.now()}`
+          );
+
+          if (hookResult.blocked) {
+            // Yield the assistant message first (with tool_use)
+            yield msg;
+            chunksEmitted++;
+            // Then yield a blocked indicator as a user message with error
+            yield {
+              type: 'user',
+              parent_tool_use_id: block.id,
+              tool_use_result: `BLOCKED: ${hookResult.reason}`,
+              message: { content: [] },
+              _blocked: true,
+              _blockReason: hookResult.reason,
+            };
+            chunksEmitted++;
+            wasBlocked = true;
+            break; // Exit inner loop since we already handled this message
+          }
+        }
+      }
+      // If the message was blocked, don't yield it again
+      if (wasBlocked) {
+        continue;
+      }
+    }
+    yield msg;
+    chunksEmitted++;
+  }
+}
+
+export function query({ prompt, options }: { prompt: any; options: Options }): AsyncGenerator<any> & { interrupt: () => Promise<void> } {
+  lastOptions = options;
+  queryCallCount++;
+
+  const generator = async function* () {
+    if (isAsyncIterable(prompt)) {
+      for await (const _ of prompt) {
+        void _; // Consume async iterable input
+        const messages = getMessagesForPrompt();
+        yield* emitMessages(messages, options);
+      }
+      return;
+    }
+
+    const messages = getMessagesForPrompt();
+    yield* emitMessages(messages, options);
+  };
+
+  const gen = generator() as AsyncGenerator<any> & {
+    interrupt: jest.Mock;
+    setModel: jest.Mock;
+    setMaxThinkingTokens: jest.Mock;
+    setPermissionMode: jest.Mock;
+    applyFlagSettings: jest.Mock;
+    setMcpServers: jest.Mock;
+    supportedCommands: jest.Mock;
+  };
+  gen.interrupt = jest.fn().mockResolvedValue(undefined);
+  // Dynamic update methods for persistent queries
+  gen.setModel = jest.fn().mockResolvedValue(undefined);
+  gen.setMaxThinkingTokens = jest.fn().mockResolvedValue(undefined);
+  gen.setPermissionMode = jest.fn().mockResolvedValue(undefined);
+  gen.applyFlagSettings = jest.fn().mockResolvedValue(undefined);
+  gen.setMcpServers = jest.fn().mockResolvedValue({ added: [], removed: [], errors: {} });
+  gen.supportedCommands = jest.fn().mockResolvedValue(mockSupportedCommands);
+  lastResponse = gen;
+
+  return gen;
+}

package/tests/__mocks__/codex-sdk.ts

@@ -0,0 +1,88 @@
+/**
+ * Jest mock for @openai/codex-sdk.
+ *
+ * The unit tests need a configurable SDK surface because Jest maps every
+ * `@openai/codex-sdk` import to this file. Export the mock fns so tests can
+ * control thread creation and streamed events explicitly.
+ */
+
+export const mockRunStreamed = jest.fn();
+export const mockRun = jest.fn();
+export const mockStartThread = jest.fn();
+export const mockResumeThread = jest.fn();
+export const mockCodexConstructor = jest.fn();
+
+function defaultStreamedResult() {
+  return {
+    events: (async function* () {
+      yield { type: 'thread.started', thread_id: 'mock-thread-id' };
+      yield { type: 'turn.started' };
+      yield { type: 'turn.completed', usage: { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 } };
+    })(),
+  };
+}
+
+export function resetCodexSdkMocks(): void {
+  mockCodexConstructor.mockReset();
+  mockRunStreamed.mockReset();
+  mockRun.mockReset();
+  mockStartThread.mockReset();
+  mockResumeThread.mockReset();
+
+  mockRunStreamed.mockResolvedValue(defaultStreamedResult());
+  mockRun.mockResolvedValue({
+    items: [],
+    finalResponse: '',
+    usage: { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 },
+  });
+  mockStartThread.mockImplementation((_options?: any) => new Thread());
+  mockResumeThread.mockImplementation((_id: string, _options?: any) => new Thread());
+}
+
+export class Codex {
+  constructor(options?: any) {
+    mockCodexConstructor(options);
+  }
+
+  startThread(options?: any) {
+    return mockStartThread(options);
+  }
+
+  resumeThread(id: string, options?: any) {
+    return mockResumeThread(id, options);
+  }
+}
+
+export class Thread {
+  private _id: string | null = 'mock-thread-id';
+
+  get id() {
+    return this._id;
+  }
+
+  async runStreamed(input: any, turnOptions?: any) {
+    return mockRunStreamed(input, turnOptions);
+  }
+
+  async run(input: any, turnOptions?: any) {
+    return mockRun(input, turnOptions);
+  }
+}
+
+resetCodexSdkMocks();
+
+// Type stubs (values don't matter for type-only imports)
+export type ThreadEvent = any;
+export type ThreadOptions = any;
+export type ModelReasoningEffort = string;
+export type ThreadItem = any;
+export type Usage = any;
+export type Input = any;
+export type UserInput = any;
+export type TurnOptions = any;
+export type StreamedTurn = any;
+export type Turn = any;
+export type CodexOptions = any;
+export type SandboxMode = string;
+export type ApprovalMode = string;
+export type WebSearchMode = string;