@scottwalker/claude-connector 0.2.0 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ Claude Code is a powerful AI coding agent, but it only runs in a terminal. **cla
 - **Two execution modes** — persistent SDK session (fast, default) or CLI process spawning (simple)
 - **Executor abstraction** — swap CLI for SDK or HTTP backend without changing your code
 - **Full CLI parity** — exposes all 45+ Claude Code flags through typed options
+- **Typed handles** — `StreamHandle` (fluent `.on().done()` + `for-await`) and `ChatHandle` (multi-turn conversations)
 
 ## Requirements
 
@@ -37,9 +38,9 @@ npm install @scottwalker/claude-connector
 ## Quick Start
 
 ```typescript
-import { Claude } from '@scottwalker/claude-connector'
+import { Claude, PERMISSION_ACCEPT_EDITS } from '@scottwalker/claude-connector'
 
-const claude = new Claude()
+const claude = new Claude({ permissionMode: PERMISSION_ACCEPT_EDITS })
 
 // Simple query
 const result = await claude.query('Find and fix bugs in auth.ts')
@@ -55,6 +56,8 @@ console.log(result.usage)       // { inputTokens, outputTokens }
 Point to a specific Claude Code installation when multiple versions coexist:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
 const claude = new Claude({
   executable: '/opt/claude-code/v2/bin/claude',
   cwd: '/path/to/project',
@@ -63,21 +66,41 @@ const claude = new Claude({
 
 ### Streaming
 
-Real-time output as Claude works:
+Real-time output as Claude works. `stream()` returns a `StreamHandle` — use the fluent `.on().done()` API or classic `for-await`:
 
 ```typescript
-for await (const event of claude.stream('Rewrite the auth module')) {
+import {
+  Claude,
+  EVENT_TEXT, EVENT_TOOL_USE, EVENT_RESULT, EVENT_ERROR,
+} from '@scottwalker/claude-connector'
+
+const claude = new Claude()
+
+// Fluent API (.on / .done)
+const result = await claude
+  .stream('Rewrite the auth module')
+  .on(EVENT_TEXT, (e) => process.stdout.write(e.text))
+  .on(EVENT_TOOL_USE, (e) => console.log(`[Tool] ${e.toolName}`))
+  .on(EVENT_ERROR, (e) => console.error(e.message))
+  .done()
+
+console.log(`Done in ${result.durationMs}ms`)
+
+// Classic for-await
+const handle = claude.stream('Rewrite the auth module')
+
+for await (const event of handle) {
   switch (event.type) {
-    case 'text':
+    case EVENT_TEXT:
       process.stdout.write(event.text)
       break
-    case 'tool_use':
+    case EVENT_TOOL_USE:
       console.log(`[Tool] ${event.toolName}`)
       break
-    case 'result':
+    case EVENT_RESULT:
       console.log(`\nDone in ${event.durationMs}ms`)
       break
-    case 'error':
+    case EVENT_ERROR:
       console.error(event.message)
       break
   }
@@ -89,6 +112,9 @@ for await (const event of claude.stream('Rewrite the auth module')) {
 Maintain conversation context across queries:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
+const claude = new Claude()
 const session = claude.session()
 await session.query('Analyze the architecture of this project')
 await session.query('Now refactor the auth module based on your analysis')
@@ -107,6 +133,9 @@ const s3 = claude.session({ resume: session.sessionId!, fork: true })
 Get typed JSON responses via JSON Schema:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
+const claude = new Claude()
 const result = await claude.query('Extract all API endpoints from the codebase', {
   schema: {
     type: 'object',
@@ -134,10 +163,14 @@ console.log(result.structured)
 Run independent queries concurrently (each spawns a separate CLI process):
 
 ```typescript
+import { Claude, PERMISSION_PLAN } from '@scottwalker/claude-connector'
+
+const claude = new Claude()
+
 const [bugs, tests, docs] = await claude.parallel([
   { prompt: 'Find bugs in src/', options: { cwd: './src' } },
   { prompt: 'Run the test suite', options: { allowedTools: ['Bash'] } },
-  { prompt: 'Review documentation', options: { permissionMode: 'plan' } },
+  { prompt: 'Review documentation', options: { permissionMode: PERMISSION_PLAN } },
 ])
 ```
 
@@ -146,13 +179,16 @@ const [bugs, tests, docs] = await claude.parallel([
 Node.js-level equivalent of the `/loop` CLI command:
 
 ```typescript
+import { Claude, SCHED_RESULT, SCHED_ERROR } from '@scottwalker/claude-connector'
+
+const claude = new Claude()
 const job = claude.loop('5m', 'Check CI pipeline status and report failures')
 
-job.on('result', (result) => {
+job.on(SCHED_RESULT, (result) => {
   console.log(`[${new Date().toISOString()}] ${result.text}`)
 })
 
-job.on('error', (err) => {
+job.on(SCHED_ERROR, (err) => {
   console.error('Check failed:', err.message)
 })
 
@@ -167,6 +203,8 @@ Supported intervals: `'30s'`, `'5m'`, `'2h'`, `'1d'`, or raw milliseconds.
 Connect Model Context Protocol servers:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
 const claude = new Claude({
   // From config file
   mcpConfig: './mcp.json',
@@ -190,6 +228,8 @@ const claude = new Claude({
 Define specialized agents:
 
 ```typescript
+import { Claude, PERMISSION_ACCEPT_EDITS } from '@scottwalker/claude-connector'
+
 const claude = new Claude({
   agents: {
     reviewer: {
@@ -201,7 +241,7 @@ const claude = new Claude({
     deployer: {
       description: 'Deployment automation agent',
       tools: ['Bash', 'Read'],
-      permissionMode: 'acceptEdits',
+      permissionMode: PERMISSION_ACCEPT_EDITS,
     },
   },
 })
@@ -212,6 +252,9 @@ const claude = new Claude({
 Run operations in an isolated copy of the repository:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
+const claude = new Claude()
 const result = await claude.query('Refactor the entire auth module', {
   worktree: 'refactor-auth',  // or `true` for auto-generated name
 })
@@ -223,7 +266,9 @@ Pass data alongside the prompt (like `echo data | claude -p "prompt"`):
 
 ```typescript
 import { readFileSync } from 'node:fs'
+import { Claude } from '@scottwalker/claude-connector'
 
+const claude = new Claude()
 const result = await claude.query('Analyze this error log and suggest fixes', {
   input: readFileSync('./error.log', 'utf-8'),
 })
@@ -234,6 +279,8 @@ const result = await claude.query('Analyze this error log and suggest fixes', {
 Attach hooks to tool execution:
 
 ```typescript
+import { Claude } from '@scottwalker/claude-connector'
+
 const claude = new Claude({
   hooks: {
     PostToolUse: [
@@ -257,6 +304,11 @@ const claude = new Claude({
 All Claude Code CLI capabilities in one place:
 
 ```typescript
+import {
+  Claude,
+  EFFORT_HIGH, PERMISSION_ACCEPT_EDITS, PERMISSION_PLAN,
+} from '@scottwalker/claude-connector'
+
 const claude = new Claude({
   // CLI binary
   executable: '/usr/local/bin/claude',
@@ -264,11 +316,11 @@ const claude = new Claude({
 
   // Model
   model: 'opus',                      // 'opus' | 'sonnet' | 'haiku' | full model ID
-  effortLevel: 'high',                // 'low' | 'medium' | 'high' | 'max'
+  effortLevel: EFFORT_HIGH,           // EFFORT_LOW | EFFORT_MEDIUM | EFFORT_HIGH | EFFORT_MAX
   fallbackModel: 'sonnet',            // auto-fallback on failure
 
   // Permissions
-  permissionMode: 'acceptEdits',      // 'default' | 'acceptEdits' | 'plan' | 'auto' | 'dontAsk' | 'bypassPermissions'
+  permissionMode: PERMISSION_ACCEPT_EDITS,  // PERMISSION_DEFAULT | PERMISSION_ACCEPT_EDITS | PERMISSION_PLAN | PERMISSION_AUTO | PERMISSION_DONT_ASK | PERMISSION_BYPASS
   allowedTools: ['Read', 'Edit', 'Bash(npm run *)'],
   disallowedTools: ['WebFetch'],
 
@@ -306,7 +358,7 @@ const claude = new Claude({
 // Override any option per query
 const result = await claude.query('Analyze this module', {
   model: 'haiku',                     // cheaper model for this query
-  permissionMode: 'plan',             // read-only
+  permissionMode: PERMISSION_PLAN,    // read-only
   maxTurns: 3,
 })
 ```
@@ -326,6 +378,8 @@ import {
   ValidationError,
 } from '@scottwalker/claude-connector'
 
+const claude = new Claude()
+
 try {
   const result = await claude.query('Fix the bug')
 } catch (err) {
@@ -350,10 +404,13 @@ try {
 
 ## Custom Executor
 
-The `IExecutor` abstraction lets you swap the CLI backend for testing, mocking, or future SDK integration:
+The `IExecutor` abstraction lets you swap the CLI backend for testing, mocking, or alternative transports:
 
 ```typescript
-import { Claude, type IExecutor, type ExecuteOptions, type QueryResult, type StreamEvent } from '@scottwalker/claude-connector'
+import {
+  Claude, EVENT_TEXT, EVENT_RESULT,
+  type IExecutor, type ExecuteOptions, type QueryResult, type StreamEvent,
+} from '@scottwalker/claude-connector'
 
 class MockExecutor implements IExecutor {
   async execute(args: readonly string[], options: ExecuteOptions): Promise<QueryResult> {
@@ -370,9 +427,9 @@ class MockExecutor implements IExecutor {
   }
 
   async *stream(args: readonly string[], options: ExecuteOptions): AsyncIterable<StreamEvent> {
-    yield { type: 'text', text: 'Mocked stream' }
+    yield { type: EVENT_TEXT, text: 'Mocked stream' }
     yield {
-      type: 'result',
+      type: EVENT_RESULT,
       text: 'Mocked stream',
       sessionId: 'mock-session',
       usage: { inputTokens: 0, outputTokens: 0 },
@@ -438,7 +495,7 @@ cd claude-connector
 npm install
 
 npm run build              # compile TypeScript
-npm test                   # run 102 unit tests
+npm test                   # run 122 unit tests
 npm run test:integration   # build + run integration test
 npm run typecheck           # type-check without emitting
 ```

package/dist/builder/args-builder.d.ts

@@ -16,8 +16,9 @@ import type { ClientOptions, QueryOptions } from '../types/index.js';
  */
 /** Merged options ready for argument building. */
 export interface ResolvedOptions {
-    readonly prompt: string;
+    readonly prompt?: string;
     readonly outputFormat: 'json' | 'stream-json';
+    readonly inputFormat?: 'stream-json';
     readonly cwd: string;
     readonly model?: string;
     readonly effortLevel?: string;

package/dist/builder/args-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-builder.d.ts","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AAEH,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,KAAK,EAAE;IACL,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,eAAe,CA+BjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CA8H5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}
+{"version":3,"file":"args-builder.d.ts","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAarE;;;;;;;;;;;;;;GAcG;AAEH,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,EAC/B,KAAK,EAAE;IACL,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,eAAe,CA+BjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAqI5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,YAAY,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}

package/dist/builder/args-builder.js

@@ -1,3 +1,4 @@
+import { FLAG_PRINT, FLAG_OUTPUT_FORMAT, FLAG_VERBOSE, FLAG_INPUT_FORMAT, FLAG_CONTINUE, FLAG_RESUME, FLAG_FORK_SESSION, FLAG_MODEL, FLAG_FALLBACK_MODEL, FLAG_EFFORT, FLAG_PERMISSION_MODE, FLAG_ALLOWED_TOOLS, FLAG_DISALLOWED_TOOLS, FLAG_TOOLS, FLAG_SYSTEM_PROMPT, FLAG_APPEND_SYSTEM_PROMPT, FLAG_MAX_TURNS, FLAG_MAX_BUDGET, FLAG_ADD_DIR, FLAG_MCP_CONFIG, FLAG_STRICT_MCP_CONFIG, FLAG_AGENTS, FLAG_AGENT, FLAG_JSON_SCHEMA, FLAG_WORKTREE, FLAG_NO_SESSION_PERSISTENCE, FLAG_NAME, FLAG_SETTINGS, FORMAT_STREAM_JSON, } from '../constants.js';
 /**
  * Merge client-level defaults with per-query overrides.
  */
@@ -39,115 +40,121 @@ export function mergeOptions(client, query, extra) {
  * @returns Array of strings to pass to `spawn('claude', args)`.
  */
 export function buildArgs(options) {
-    const args = ['--print', '--output-format', options.outputFormat];
+    const args = [FLAG_PRINT, FLAG_OUTPUT_FORMAT, options.outputFormat];
     // BUG-1 fix: stream-json requires --verbose
-    if (options.outputFormat === 'stream-json') {
-        args.push('--verbose');
+    if (options.outputFormat === FORMAT_STREAM_JSON) {
+        args.push(FLAG_VERBOSE);
+    }
+    // ── Input format (bidirectional streaming) ─────────────────────
+    if (options.inputFormat) {
+        args.push(FLAG_INPUT_FORMAT, options.inputFormat);
     }
     // ── Prompt ──────────────────────────────────────────────────────
-    args.push(options.prompt);
+    if (options.prompt) {
+        args.push(options.prompt);
+    }
     // ── Session ─────────────────────────────────────────────────────
     if (options.continueSession) {
-        args.push('--continue');
+        args.push(FLAG_CONTINUE);
     }
     if (options.sessionId) {
-        args.push('--resume', options.sessionId);
+        args.push(FLAG_RESUME, options.sessionId);
     }
     if (options.forkSession) {
-        args.push('--fork-session');
+        args.push(FLAG_FORK_SESSION);
     }
     // ── Model ───────────────────────────────────────────────────────
     if (options.model) {
-        args.push('--model', options.model);
+        args.push(FLAG_MODEL, options.model);
     }
     if (options.fallbackModel) {
-        args.push('--fallback-model', options.fallbackModel);
+        args.push(FLAG_FALLBACK_MODEL, options.fallbackModel);
     }
     if (options.effortLevel) {
-        args.push('--effort', options.effortLevel);
+        args.push(FLAG_EFFORT, options.effortLevel);
     }
     // ── Permissions ─────────────────────────────────────────────────
     if (options.permissionMode) {
-        args.push('--permission-mode', options.permissionMode);
+        args.push(FLAG_PERMISSION_MODE, options.permissionMode);
     }
     if (options.allowedTools?.length) {
-        args.push('--allowedTools', ...options.allowedTools);
+        args.push(FLAG_ALLOWED_TOOLS, ...options.allowedTools);
     }
     if (options.disallowedTools?.length) {
-        args.push('--disallowedTools', ...options.disallowedTools);
+        args.push(FLAG_DISALLOWED_TOOLS, ...options.disallowedTools);
     }
     // ── Tools (built-in set restriction) ────────────────────────────
     if (options.tools) {
         if (options.tools.length === 0) {
-            args.push('--tools', '');
+            args.push(FLAG_TOOLS, '');
         }
         else {
-            args.push('--tools', ...options.tools);
+            args.push(FLAG_TOOLS, ...options.tools);
         }
     }
     // ── System prompt ───────────────────────────────────────────────
     if (options.systemPrompt) {
-        args.push('--system-prompt', options.systemPrompt);
+        args.push(FLAG_SYSTEM_PROMPT, options.systemPrompt);
     }
     if (options.appendSystemPrompt) {
-        args.push('--append-system-prompt', options.appendSystemPrompt);
+        args.push(FLAG_APPEND_SYSTEM_PROMPT, options.appendSystemPrompt);
     }
     // ── Limits ──────────────────────────────────────────────────────
     if (options.maxTurns !== undefined) {
-        args.push('--max-turns', String(options.maxTurns));
+        args.push(FLAG_MAX_TURNS, String(options.maxTurns));
     }
     if (options.maxBudget !== undefined) {
-        args.push('--max-budget-usd', String(options.maxBudget));
+        args.push(FLAG_MAX_BUDGET, String(options.maxBudget));
     }
     // ── Directories ─────────────────────────────────────────────────
     if (options.additionalDirs?.length) {
         for (const dir of options.additionalDirs) {
-            args.push('--add-dir', dir);
+            args.push(FLAG_ADD_DIR, dir);
         }
     }
     // ── MCP ─────────────────────────────────────────────────────────
     if (options.mcpConfig) {
         const configs = Array.isArray(options.mcpConfig) ? options.mcpConfig : [options.mcpConfig];
         for (const cfg of configs) {
-            args.push('--mcp-config', cfg);
+            args.push(FLAG_MCP_CONFIG, cfg);
         }
     }
     if (options.mcpServers && Object.keys(options.mcpServers).length > 0) {
-        args.push('--mcp-config', JSON.stringify({ mcpServers: options.mcpServers }));
+        args.push(FLAG_MCP_CONFIG, JSON.stringify({ mcpServers: options.mcpServers }));
     }
     if (options.strictMcpConfig) {
-        args.push('--strict-mcp-config');
+        args.push(FLAG_STRICT_MCP_CONFIG);
     }
     // ── Agents ──────────────────────────────────────────────────────
     if (options.agents && Object.keys(options.agents).length > 0) {
-        args.push('--agents', JSON.stringify(options.agents));
+        args.push(FLAG_AGENTS, JSON.stringify(options.agents));
     }
     if (options.agent) {
-        args.push('--agent', options.agent);
+        args.push(FLAG_AGENT, options.agent);
     }
     // ── Structured output ───────────────────────────────────────────
     if (options.schema) {
-        args.push('--json-schema', JSON.stringify(options.schema));
+        args.push(FLAG_JSON_SCHEMA, JSON.stringify(options.schema));
     }
     // ── Worktree ────────────────────────────────────────────────────
     if (options.worktree) {
         if (typeof options.worktree === 'string') {
-            args.push('--worktree', options.worktree);
+            args.push(FLAG_WORKTREE, options.worktree);
         }
         else {
-            args.push('--worktree');
+            args.push(FLAG_WORKTREE);
         }
     }
     // ── Misc ────────────────────────────────────────────────────────
     if (options.noSessionPersistence) {
-        args.push('--no-session-persistence');
+        args.push(FLAG_NO_SESSION_PERSISTENCE);
     }
     if (options.name) {
-        args.push('--name', options.name);
+        args.push(FLAG_NAME, options.name);
     }
     // ── Hooks (via --settings) ──────────────────────────────────────
     if (options.hooks && Object.keys(options.hooks).length > 0) {
-        args.push('--settings', JSON.stringify({ hooks: options.hooks }));
+        args.push(FLAG_SETTINGS, JSON.stringify({ hooks: options.hooks }));
     }
     return args;
 }

package/dist/builder/args-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"args-builder.js","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"args-builder.js","sourceRoot":"","sources":["../../src/builder/args-builder.ts"],"names":[],"mappings":"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"}

package/dist/client/chat-handle.d.ts

@@ -0,0 +1,115 @@
+import { Readable, Duplex } from 'node:stream';
+import { EVENT_TEXT, EVENT_TOOL_USE, EVENT_RESULT, EVENT_ERROR, EVENT_SYSTEM } from '../constants.js';
+import type { StreamToolUseEvent, StreamResultEvent, StreamErrorEvent, StreamSystemEvent } from '../types/index.js';
+type TextCallback = (text: string) => void;
+type ToolUseCallback = (event: StreamToolUseEvent) => void;
+type ResultCallback = (event: StreamResultEvent) => void;
+type ErrorCallback = (event: StreamErrorEvent) => void;
+type SystemCallback = (event: StreamSystemEvent) => void;
+/**
+ * Bidirectional streaming handle for real-time conversation.
+ *
+ * Uses `--input-format stream-json` to maintain a persistent CLI process.
+ * Send prompts with `.send()`, receive responses via callbacks or Node.js streams.
+ *
+ * ## Fluent callbacks
+ *
+ * ```ts
+ * const chat = claude.chat()
+ *   .on('text', (text) => process.stdout.write(text))
+ *   .on('result', (event) => console.log('Turn done'))
+ *
+ * await chat.send('What files are in src?')
+ * await chat.send('Fix the largest one')
+ * chat.end()
+ * ```
+ *
+ * ## Node.js Duplex stream
+ *
+ * ```ts
+ * const duplex = claude.chat().toDuplex()
+ * inputStream.pipe(duplex).pipe(process.stdout)
+ * ```
+ */
+export declare class ChatHandle {
+    private readonly child;
+    private readonly textCallbacks;
+    private readonly toolUseCallbacks;
+    private readonly resultCallbacks;
+    private readonly errorCallbacks;
+    private readonly systemCallbacks;
+    private buffer;
+    private _closed;
+    private _sessionId;
+    private _turnCount;
+    constructor(executable: string, args: readonly string[], options: {
+        cwd: string;
+        env: Record<string, string>;
+    });
+    /** Session ID (populated after the first result). */
+    get sessionId(): string | null;
+    /** Number of completed turns. */
+    get turnCount(): number;
+    /** Whether the chat has been closed. */
+    get closed(): boolean;
+    /**
+     * Register a callback. Returns `this` for chaining.
+     */
+    on(type: typeof EVENT_TEXT, callback: TextCallback): this;
+    on(type: typeof EVENT_TOOL_USE, callback: ToolUseCallback): this;
+    on(type: typeof EVENT_RESULT, callback: ResultCallback): this;
+    on(type: typeof EVENT_ERROR, callback: ErrorCallback): this;
+    on(type: typeof EVENT_SYSTEM, callback: SystemCallback): this;
+    /**
+     * Send a prompt and wait for the complete response.
+     * Returns the result event when this turn finishes.
+     *
+     * ```ts
+     * const result = await chat.send('Find bugs in auth.ts')
+     * console.log(result.durationMs)
+     *
+     * const result2 = await chat.send('Now fix them')
+     * ```
+     */
+    send(prompt: string): Promise<StreamResultEvent>;
+    /**
+     * Pipe text output to a writable stream.
+     * Returns the destination for chaining (Node.js convention).
+     *
+     * ```ts
+     * chat.pipe(process.stdout)
+     * chat.pipe(fs.createWriteStream('log.txt'))
+     * ```
+     */
+    pipe<T extends NodeJS.WritableStream>(dest: T): T;
+    /**
+     * Get a Node.js Readable that emits text chunks.
+     *
+     * ```ts
+     * claude.chat().toReadable().pipe(res)
+     * ```
+     */
+    toReadable(): Readable;
+    /**
+     * Get a Node.js Duplex stream.
+     * Write side accepts prompts (one per write). Read side emits text.
+     *
+     * ```ts
+     * const duplex = claude.chat().toDuplex()
+     * inputStream.pipe(duplex).pipe(process.stdout)
+     * ```
+     */
+    toDuplex(): Duplex;
+    /**
+     * Close the chat gracefully — signals EOF to the CLI process.
+     */
+    end(): void;
+    /**
+     * Abort the chat — kills the CLI process immediately.
+     */
+    abort(): void;
+    private startReading;
+    private dispatch;
+}
+export {};
+//# sourceMappingURL=chat-handle.d.ts.map

package/dist/client/chat-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-handle.d.ts","sourceRoot":"","sources":["../../src/client/chat-handle.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EAGb,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAC3C,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAC3D,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AACzD,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AACvD,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IAExD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAK;gBAGrB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE;IAWvD,qDAAqD;IACrD,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED,iCAAiC;IACjC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wCAAwC;IACxC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;OAEG;IACH,EAAE,CAAC,IAAI,EAAE,OAAO,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IACzD,EAAE,CAAC,IAAI,EAAE,OAAO,cAAc,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAChE,EAAE,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;IAC7D,EAAE,CAAC,IAAI,EAAE,OAAO,WAAW,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAC3D,EAAE,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;IAY7D;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBhD;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC;IAKjD;;;;;;OAMG;IACH,UAAU,IAAI,QAAQ;IAYtB;;;;;;;;OAQG;IACH,QAAQ,IAAI,MAAM;IAsBlB;;OAEG;IACH,GAAG,IAAI,IAAI;IAQX;;OAEG;IACH,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,QAAQ;CAmBjB"}