claude-code-controller 0.2.0 → 0.4.0

package/dist/{controller-C9bh_59H.d.cts → claude-DectLQVR.d.cts}

@@ -106,6 +106,7 @@ interface TaskFile {
 }
 type TaskStatus = "pending" | "in_progress" | "completed";
 type AgentType = "general-purpose" | "Bash" | "Explore" | "Plan" | string;
+type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "delegate";
 interface SpawnAgentOptions {
     name: string;
     type?: AgentType;
@@ -113,6 +114,7 @@ interface SpawnAgentOptions {
     cwd?: string;
     prompt?: string;
     permissions?: string[];
+    permissionMode?: PermissionMode;
     /** Environment variables to inject into the agent's process */
     env?: Record<string, string>;
 }
@@ -394,4 +396,240 @@ declare class ClaudeCodeController extends EventEmitter<ControllerEvents> implem
     private ensureInitialized;
 }
 
-export { AgentHandle as A, ClaudeCodeController as C, type InboxMessage as I, type Logger as L, type PermissionRequestMessage as P, type ReceiveOptions as R, type StructuredMessage as S, type TaskAssignmentMessage as T, type LogLevel as a, type AgentType as b, type ControllerEvents as c, type ControllerOptions as d, type IdleNotificationMessage as e, type PermissionResponseMessage as f, type PlainTextMessage as g, type PlanApprovalRequestMessage as h, type PlanApprovalResponseMessage as i, type ShutdownApprovedMessage as j, type ShutdownRequestMessage as k, type SpawnAgentOptions as l, type TaskFile as m, TaskManager as n, type TaskStatus as o, type TeamConfig as p, TeamManager as q, type TeamMember as r };
+type PermissionPreset = "full" | "edit" | "plan" | "ask";
+interface ClaudeOptions {
+    /** Model to use: "sonnet" | "opus" | "haiku" | full model ID */
+    model?: "sonnet" | "opus" | "haiku" | (string & {});
+    /** Anthropic API key. Maps to ANTHROPIC_AUTH_TOKEN env var. */
+    apiKey?: string;
+    /** API base URL. Maps to ANTHROPIC_BASE_URL env var. */
+    baseUrl?: string;
+    /** Request timeout in ms. Maps to API_TIMEOUT_MS env var. */
+    timeout?: number;
+    /** Working directory for the agent. Defaults to process.cwd(). */
+    cwd?: string;
+    /**
+     * Permission level:
+     * - "full" (default) — all tools, no approval needed
+     * - "edit" — auto-approve read/write/bash
+     * - "plan" — read-only exploration
+     * - "ask" — fires permission events for each tool use
+     */
+    permissions?: PermissionPreset;
+    /**
+     * Auto-approve permission and plan requests.
+     * - `true` — approve everything automatically
+     * - `string[]` — only auto-approve these tool names, reject the rest
+     *
+     * Only meaningful with `permissions: "ask"`. Ignored when "full" or "edit".
+     *
+     * @example
+     * ```ts
+     * // Approve everything
+     * await claude.agent({ permissions: "ask", autoApprove: true });
+     *
+     * // Only approve safe tools
+     * await claude.agent({ permissions: "ask", autoApprove: ["Read", "Glob", "Grep"] });
+     * ```
+     */
+    autoApprove?: boolean | string[];
+    /**
+     * Inline callback for permission requests.
+     * Called when the agent wants to use a tool.
+     * Provides `req.approve()` / `req.reject()` methods.
+     *
+     * @example
+     * ```ts
+     * await claude.agent({
+     *   permissions: "ask",
+     *   onPermission: (req) => {
+     *     req.toolName === "Bash" ? req.reject() : req.approve();
+     *   },
+     * });
+     * ```
+     */
+    onPermission?: (request: PermissionRequestInfo) => void;
+    /**
+     * Inline callback for plan approval requests.
+     * Called when the agent submits a plan for review.
+     *
+     * @example
+     * ```ts
+     * await claude.agent({
+     *   onPlan: (req) => {
+     *     console.log(req.planContent);
+     *     req.approve();
+     *   },
+     * });
+     * ```
+     */
+    onPlan?: (request: PlanRequestInfo) => void;
+    /** Additional environment variables (escape hatch). */
+    env?: Record<string, string>;
+    /** Log level. Defaults to "warn" for the simplified API. */
+    logLevel?: LogLevel;
+    /** Custom logger instance. */
+    logger?: Logger;
+    /** Agent name. Auto-generated if omitted. */
+    name?: string;
+    /** Agent type. Defaults to "general-purpose". */
+    type?: AgentType;
+    /** Path to the claude binary. */
+    claudeBinary?: string;
+    /** Max time in ms to wait for agent to become ready. Default: 60_000. */
+    readyTimeout?: number;
+}
+interface AskOptions {
+    /** Response timeout in ms. Default: 120_000. */
+    timeout?: number;
+    /** Poll interval in ms. Default: 500. */
+    pollInterval?: number;
+}
+interface SessionOptions extends ClaudeOptions {
+    /** Team name. Auto-generated if omitted. */
+    teamName?: string;
+}
+interface SessionAgentOptions {
+    /** Model override for this agent. */
+    model?: string;
+    /** Working directory override. */
+    cwd?: string;
+    /** Agent type override. */
+    type?: AgentType;
+    /** Permission preset override. */
+    permissions?: PermissionPreset;
+    /** Auto-approve permission/plan requests. See ClaudeOptions.autoApprove. */
+    autoApprove?: boolean | string[];
+    /** Inline permission callback. See ClaudeOptions.onPermission. */
+    onPermission?: (request: PermissionRequestInfo) => void;
+    /** Inline plan callback. See ClaudeOptions.onPlan. */
+    onPlan?: (request: PlanRequestInfo) => void;
+    /** Per-agent env overrides. */
+    env?: Record<string, string>;
+    /** Max time in ms to wait for agent to become ready. Default: 60_000. */
+    readyTimeout?: number;
+}
+interface PermissionRequestInfo {
+    requestId: string;
+    toolName: string;
+    description: string;
+    input?: unknown;
+    approve(): Promise<void>;
+    reject(): Promise<void>;
+}
+interface PlanRequestInfo {
+    requestId: string;
+    planContent?: string;
+    approve(feedback?: string): Promise<void>;
+    reject(feedback: string): Promise<void>;
+}
+interface AgentEvents {
+    message: [text: string];
+    idle: [];
+    permission: [request: PermissionRequestInfo];
+    plan: [request: PlanRequestInfo];
+    exit: [code: number | null];
+    error: [error: Error];
+}
+declare class Agent extends EventEmitter<AgentEvents> {
+    private controller;
+    private handle;
+    private ownsController;
+    private disposed;
+    private boundListeners;
+    private constructor();
+    /** Create a standalone agent (owns its own controller). */
+    static create(opts?: ClaudeOptions): Promise<Agent>;
+    /** Create an agent within an existing session (session owns the controller). */
+    static createInSession(controller: ClaudeCodeController, name: string, opts?: SessionAgentOptions): Promise<Agent>;
+    /** The agent's name. */
+    get name(): string;
+    /** The agent process PID. */
+    get pid(): number | undefined;
+    /** Whether the agent process is still running. */
+    get isRunning(): boolean;
+    /**
+     * Send a message and wait for the response.
+     *
+     * Uses event-based waiting (via the controller's InboxPoller) instead of
+     * polling `readUnread()` directly, which avoids a race condition where the
+     * poller marks inbox messages as read before `receive()` can see them.
+     */
+    ask(question: string, opts?: AskOptions): Promise<string>;
+    /** Send a message without waiting for a response. */
+    send(message: string): Promise<void>;
+    /** Wait for the next response from this agent. */
+    receive(opts?: AskOptions): Promise<string>;
+    /**
+     * Close this agent. If standalone, shuts down the entire controller.
+     * If session-owned, kills only this agent's process.
+     */
+    close(): Promise<void>;
+    /** Mark as disposed (used by Session when it closes). */
+    markDisposed(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    private wireEvents;
+    private unwireEvents;
+    private wireBehavior;
+    private ensureNotDisposed;
+}
+declare class Session {
+    readonly controller: ClaudeCodeController;
+    private defaults;
+    private agents;
+    private disposed;
+    private constructor();
+    static create(opts?: SessionOptions): Promise<Session>;
+    /** Spawn a named agent in this session. Inherits session defaults. */
+    agent(name: string, opts?: SessionAgentOptions): Promise<Agent>;
+    /** Get an existing agent by name. */
+    get(name: string): Agent | undefined;
+    /** Close all agents and shut down the session. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private ensureNotDisposed;
+}
+/**
+ * One-liner: send a prompt, get a response.
+ * Creates an ephemeral agent, sends the message, returns the answer, cleans up.
+ *
+ * @example
+ * ```ts
+ * const answer = await claude("What does this project do?", { model: "sonnet" });
+ * ```
+ */
+declare function claudeCall(prompt: string, opts?: ClaudeOptions): Promise<string>;
+/**
+ * The simplified Claude Code API.
+ *
+ * - `claude(prompt, opts?)` — one-liner: ask a question, get an answer
+ * - `claude.agent(opts?)` — create a persistent agent for multi-turn conversations
+ * - `claude.session(opts?)` — create a multi-agent session
+ */
+declare const claude: typeof claudeCall & {
+    /**
+     * Create a persistent agent for multi-turn conversations.
+     *
+     * @example
+     * ```ts
+     * const agent = await claude.agent({ model: "sonnet" });
+     * const answer = await agent.ask("What is 2+2?");
+     * await agent.close();
+     * ```
+     */
+    agent: (opts?: ClaudeOptions) => Promise<Agent>;
+    /**
+     * Create a multi-agent session.
+     *
+     * @example
+     * ```ts
+     * const session = await claude.session({ model: "sonnet" });
+     * const reviewer = await session.agent("reviewer", { model: "opus" });
+     * const coder = await session.agent("coder");
+     * await session.close();
+     * ```
+     */
+    session: (opts?: SessionOptions) => Promise<Session>;
+};
+
+export { Agent as A, type TeamConfig as B, ClaudeCodeController as C, TeamManager as D, type TeamMember as E, claude as F, type InboxMessage as I, type Logger as L, type PermissionMode as P, type ReceiveOptions as R, type StructuredMessage as S, type TaskAssignmentMessage as T, type LogLevel as a, type AgentEvents as b, AgentHandle as c, type AgentType as d, type AskOptions as e, type ClaudeOptions as f, type ControllerEvents as g, type ControllerOptions as h, type IdleNotificationMessage as i, type PermissionPreset as j, type PermissionRequestInfo as k, type PermissionRequestMessage as l, type PermissionResponseMessage as m, type PlainTextMessage as n, type PlanApprovalRequestMessage as o, type PlanApprovalResponseMessage as p, type PlanRequestInfo as q, Session as r, type SessionAgentOptions as s, type SessionOptions as t, type ShutdownApprovedMessage as u, type ShutdownRequestMessage as v, type SpawnAgentOptions as w, type TaskFile as x, TaskManager as y, type TaskStatus as z };

package/dist/{controller-C9bh_59H.d.ts → claude-DectLQVR.d.ts}

@@ -106,6 +106,7 @@ interface TaskFile {
 }
 type TaskStatus = "pending" | "in_progress" | "completed";
 type AgentType = "general-purpose" | "Bash" | "Explore" | "Plan" | string;
+type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "delegate";
 interface SpawnAgentOptions {
     name: string;
     type?: AgentType;
@@ -113,6 +114,7 @@ interface SpawnAgentOptions {
     cwd?: string;
     prompt?: string;
     permissions?: string[];
+    permissionMode?: PermissionMode;
     /** Environment variables to inject into the agent's process */
     env?: Record<string, string>;
 }
@@ -394,4 +396,240 @@ declare class ClaudeCodeController extends EventEmitter<ControllerEvents> implem
     private ensureInitialized;
 }
 
-export { AgentHandle as A, ClaudeCodeController as C, type InboxMessage as I, type Logger as L, type PermissionRequestMessage as P, type ReceiveOptions as R, type StructuredMessage as S, type TaskAssignmentMessage as T, type LogLevel as a, type AgentType as b, type ControllerEvents as c, type ControllerOptions as d, type IdleNotificationMessage as e, type PermissionResponseMessage as f, type PlainTextMessage as g, type PlanApprovalRequestMessage as h, type PlanApprovalResponseMessage as i, type ShutdownApprovedMessage as j, type ShutdownRequestMessage as k, type SpawnAgentOptions as l, type TaskFile as m, TaskManager as n, type TaskStatus as o, type TeamConfig as p, TeamManager as q, type TeamMember as r };
+type PermissionPreset = "full" | "edit" | "plan" | "ask";
+interface ClaudeOptions {
+    /** Model to use: "sonnet" | "opus" | "haiku" | full model ID */
+    model?: "sonnet" | "opus" | "haiku" | (string & {});
+    /** Anthropic API key. Maps to ANTHROPIC_AUTH_TOKEN env var. */
+    apiKey?: string;
+    /** API base URL. Maps to ANTHROPIC_BASE_URL env var. */
+    baseUrl?: string;
+    /** Request timeout in ms. Maps to API_TIMEOUT_MS env var. */
+    timeout?: number;
+    /** Working directory for the agent. Defaults to process.cwd(). */
+    cwd?: string;
+    /**
+     * Permission level:
+     * - "full" (default) — all tools, no approval needed
+     * - "edit" — auto-approve read/write/bash
+     * - "plan" — read-only exploration
+     * - "ask" — fires permission events for each tool use
+     */
+    permissions?: PermissionPreset;
+    /**
+     * Auto-approve permission and plan requests.
+     * - `true` — approve everything automatically
+     * - `string[]` — only auto-approve these tool names, reject the rest
+     *
+     * Only meaningful with `permissions: "ask"`. Ignored when "full" or "edit".
+     *
+     * @example
+     * ```ts
+     * // Approve everything
+     * await claude.agent({ permissions: "ask", autoApprove: true });
+     *
+     * // Only approve safe tools
+     * await claude.agent({ permissions: "ask", autoApprove: ["Read", "Glob", "Grep"] });
+     * ```
+     */
+    autoApprove?: boolean | string[];
+    /**
+     * Inline callback for permission requests.
+     * Called when the agent wants to use a tool.
+     * Provides `req.approve()` / `req.reject()` methods.
+     *
+     * @example
+     * ```ts
+     * await claude.agent({
+     *   permissions: "ask",
+     *   onPermission: (req) => {
+     *     req.toolName === "Bash" ? req.reject() : req.approve();
+     *   },
+     * });
+     * ```
+     */
+    onPermission?: (request: PermissionRequestInfo) => void;
+    /**
+     * Inline callback for plan approval requests.
+     * Called when the agent submits a plan for review.
+     *
+     * @example
+     * ```ts
+     * await claude.agent({
+     *   onPlan: (req) => {
+     *     console.log(req.planContent);
+     *     req.approve();
+     *   },
+     * });
+     * ```
+     */
+    onPlan?: (request: PlanRequestInfo) => void;
+    /** Additional environment variables (escape hatch). */
+    env?: Record<string, string>;
+    /** Log level. Defaults to "warn" for the simplified API. */
+    logLevel?: LogLevel;
+    /** Custom logger instance. */
+    logger?: Logger;
+    /** Agent name. Auto-generated if omitted. */
+    name?: string;
+    /** Agent type. Defaults to "general-purpose". */
+    type?: AgentType;
+    /** Path to the claude binary. */
+    claudeBinary?: string;
+    /** Max time in ms to wait for agent to become ready. Default: 60_000. */
+    readyTimeout?: number;
+}
+interface AskOptions {
+    /** Response timeout in ms. Default: 120_000. */
+    timeout?: number;
+    /** Poll interval in ms. Default: 500. */
+    pollInterval?: number;
+}
+interface SessionOptions extends ClaudeOptions {
+    /** Team name. Auto-generated if omitted. */
+    teamName?: string;
+}
+interface SessionAgentOptions {
+    /** Model override for this agent. */
+    model?: string;
+    /** Working directory override. */
+    cwd?: string;
+    /** Agent type override. */
+    type?: AgentType;
+    /** Permission preset override. */
+    permissions?: PermissionPreset;
+    /** Auto-approve permission/plan requests. See ClaudeOptions.autoApprove. */
+    autoApprove?: boolean | string[];
+    /** Inline permission callback. See ClaudeOptions.onPermission. */
+    onPermission?: (request: PermissionRequestInfo) => void;
+    /** Inline plan callback. See ClaudeOptions.onPlan. */
+    onPlan?: (request: PlanRequestInfo) => void;
+    /** Per-agent env overrides. */
+    env?: Record<string, string>;
+    /** Max time in ms to wait for agent to become ready. Default: 60_000. */
+    readyTimeout?: number;
+}
+interface PermissionRequestInfo {
+    requestId: string;
+    toolName: string;
+    description: string;
+    input?: unknown;
+    approve(): Promise<void>;
+    reject(): Promise<void>;
+}
+interface PlanRequestInfo {
+    requestId: string;
+    planContent?: string;
+    approve(feedback?: string): Promise<void>;
+    reject(feedback: string): Promise<void>;
+}
+interface AgentEvents {
+    message: [text: string];
+    idle: [];
+    permission: [request: PermissionRequestInfo];
+    plan: [request: PlanRequestInfo];
+    exit: [code: number | null];
+    error: [error: Error];
+}
+declare class Agent extends EventEmitter<AgentEvents> {
+    private controller;
+    private handle;
+    private ownsController;
+    private disposed;
+    private boundListeners;
+    private constructor();
+    /** Create a standalone agent (owns its own controller). */
+    static create(opts?: ClaudeOptions): Promise<Agent>;
+    /** Create an agent within an existing session (session owns the controller). */
+    static createInSession(controller: ClaudeCodeController, name: string, opts?: SessionAgentOptions): Promise<Agent>;
+    /** The agent's name. */
+    get name(): string;
+    /** The agent process PID. */
+    get pid(): number | undefined;
+    /** Whether the agent process is still running. */
+    get isRunning(): boolean;
+    /**
+     * Send a message and wait for the response.
+     *
+     * Uses event-based waiting (via the controller's InboxPoller) instead of
+     * polling `readUnread()` directly, which avoids a race condition where the
+     * poller marks inbox messages as read before `receive()` can see them.
+     */
+    ask(question: string, opts?: AskOptions): Promise<string>;
+    /** Send a message without waiting for a response. */
+    send(message: string): Promise<void>;
+    /** Wait for the next response from this agent. */
+    receive(opts?: AskOptions): Promise<string>;
+    /**
+     * Close this agent. If standalone, shuts down the entire controller.
+     * If session-owned, kills only this agent's process.
+     */
+    close(): Promise<void>;
+    /** Mark as disposed (used by Session when it closes). */
+    markDisposed(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    private wireEvents;
+    private unwireEvents;
+    private wireBehavior;
+    private ensureNotDisposed;
+}
+declare class Session {
+    readonly controller: ClaudeCodeController;
+    private defaults;
+    private agents;
+    private disposed;
+    private constructor();
+    static create(opts?: SessionOptions): Promise<Session>;
+    /** Spawn a named agent in this session. Inherits session defaults. */
+    agent(name: string, opts?: SessionAgentOptions): Promise<Agent>;
+    /** Get an existing agent by name. */
+    get(name: string): Agent | undefined;
+    /** Close all agents and shut down the session. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private ensureNotDisposed;
+}
+/**
+ * One-liner: send a prompt, get a response.
+ * Creates an ephemeral agent, sends the message, returns the answer, cleans up.
+ *
+ * @example
+ * ```ts
+ * const answer = await claude("What does this project do?", { model: "sonnet" });
+ * ```
+ */
+declare function claudeCall(prompt: string, opts?: ClaudeOptions): Promise<string>;
+/**
+ * The simplified Claude Code API.
+ *
+ * - `claude(prompt, opts?)` — one-liner: ask a question, get an answer
+ * - `claude.agent(opts?)` — create a persistent agent for multi-turn conversations
+ * - `claude.session(opts?)` — create a multi-agent session
+ */
+declare const claude: typeof claudeCall & {
+    /**
+     * Create a persistent agent for multi-turn conversations.
+     *
+     * @example
+     * ```ts
+     * const agent = await claude.agent({ model: "sonnet" });
+     * const answer = await agent.ask("What is 2+2?");
+     * await agent.close();
+     * ```
+     */
+    agent: (opts?: ClaudeOptions) => Promise<Agent>;
+    /**
+     * Create a multi-agent session.
+     *
+     * @example
+     * ```ts
+     * const session = await claude.session({ model: "sonnet" });
+     * const reviewer = await session.agent("reviewer", { model: "opus" });
+     * const coder = await session.agent("coder");
+     * await session.close();
+     * ```
+     */
+    session: (opts?: SessionOptions) => Promise<Session>;
+};
+
+export { Agent as A, type TeamConfig as B, ClaudeCodeController as C, TeamManager as D, type TeamMember as E, claude as F, type InboxMessage as I, type Logger as L, type PermissionMode as P, type ReceiveOptions as R, type StructuredMessage as S, type TaskAssignmentMessage as T, type LogLevel as a, type AgentEvents as b, AgentHandle as c, type AgentType as d, type AskOptions as e, type ClaudeOptions as f, type ControllerEvents as g, type ControllerOptions as h, type IdleNotificationMessage as i, type PermissionPreset as j, type PermissionRequestInfo as k, type PermissionRequestMessage as l, type PermissionResponseMessage as m, type PlainTextMessage as n, type PlanApprovalRequestMessage as o, type PlanApprovalResponseMessage as p, type PlanRequestInfo as q, Session as r, type SessionAgentOptions as s, type SessionOptions as t, type ShutdownApprovedMessage as u, type ShutdownRequestMessage as v, type SpawnAgentOptions as w, type TaskFile as x, TaskManager as y, type TaskStatus as z };