@cjhyy/code-shell-core 0.7.0 → 0.7.1

package/dist/hooks/registry.js

@@ -101,6 +101,9 @@ export class HookRegistry {
                 if (result.continueSession) {
                     aggregated.continueSession = true;
                 }
+                if (result.goalTermination !== undefined) {
+                    aggregated.goalTermination = result.goalTermination;
+                }
                 if (result.stop) {
                     aggregated.stop = true;
                     break;

package/dist/hooks/shell-runner.d.ts

@@ -28,16 +28,27 @@
  *   timeout     Defaults to 60_000 ms; settings.timeout_ms overrides.
  *               On timeout we SIGTERM then SIGKILL, log, and return {}.
  */
+import type { Writable } from "node:stream";
 import type { HookContext, HookResult } from "./events.js";
 import type { SettingsHookConfig } from "../types.js";
 import { validateHookResult } from "./hook-output.js";
 export { validateHookResult };
+export declare const MAX_HOOK_STDIN_BYTES: number;
+/**
+ * Write one hook envelope without leaving a Writable `error` event unhandled.
+ * The listener is installed before write(), remains through end(), and the
+ * promise does not resolve until both the write callback and any required
+ * drain have completed.
+ */
+export declare function writeHookStdin(stdin: Writable | null | undefined, envelope: string): Promise<void>;
+/** Close stdin for an oversized envelope while still absorbing stream errors. */
+export declare function closeHookStdin(stdin: Writable | null | undefined): void;
 /**
  * Run one shell-hook command and return the parsed HookResult. Catches
  * every failure mode (spawn error, timeout, malformed JSON) and
  * returns an empty result so the registry's chain keeps going.
  */
-export declare function runShellHook(config: SettingsHookConfig, ctx: HookContext): Promise<HookResult>;
+export declare function runShellHook(config: SettingsHookConfig, ctx: HookContext, abortSignal?: AbortSignal): Promise<HookResult>;
 /**
  * Check whether the hook should fire for the current ctx, respecting
  * the optional `matcher` regex. Returns false for non-tool events

package/dist/hooks/shell-runner.js

@@ -35,13 +35,105 @@ import { killChildTree } from "../runtime/spawn-common.js";
 // "./shell-runner.js" (e.g. tests) keep compiling.
 export { validateHookResult };
 const DEFAULT_TIMEOUT_MS = 60_000;
+export const MAX_HOOK_STDIN_BYTES = 256 * 1024;
+function stdinFailure(error) {
+    const err = error;
+    return {
+        type: "stdin_error",
+        code: typeof err?.code === "string" ? err.code : "UNKNOWN",
+        message: err instanceof Error ? err.message : String(error),
+    };
+}
+/**
+ * Write one hook envelope without leaving a Writable `error` event unhandled.
+ * The listener is installed before write(), remains through end(), and the
+ * promise does not resolve until both the write callback and any required
+ * drain have completed.
+ */
+export function writeHookStdin(stdin, envelope) {
+    if (!stdin)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let writeComplete = false;
+        let drained = false;
+        let ending = false;
+        const cleanup = (removeErrorListener = true) => {
+            if (removeErrorListener)
+                stdin.off("error", onError);
+            stdin.off("drain", onDrain);
+        };
+        const finish = (error, keepErrorListener = false) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup(!keepErrorListener);
+            if (error !== undefined)
+                reject(error);
+            else
+                resolve();
+        };
+        const onError = (error) => finish(error);
+        const onDrain = () => {
+            drained = true;
+            maybeEnd();
+        };
+        const maybeEnd = () => {
+            if (!writeComplete || !drained || ending || settled)
+                return;
+            ending = true;
+            try {
+                stdin.end(() => finish());
+            }
+            catch (error) {
+                finish(error, true);
+            }
+        };
+        // EventEmitter treats an unhandled stream `error` as fatal. Register the
+        // one-shot handler before the first byte is handed to the child.
+        stdin.once("error", onError);
+        try {
+            drained = stdin.write(envelope, (error) => {
+                if (error) {
+                    // Some Writable implementations invoke the callback before emitting
+                    // their fatal `error`. Keep the one-shot guard installed for it.
+                    finish(error, true);
+                    return;
+                }
+                writeComplete = true;
+                maybeEnd();
+            });
+            if (!drained)
+                stdin.once("drain", onDrain);
+            maybeEnd();
+        }
+        catch (error) {
+            finish(error, true);
+        }
+    });
+}
+/** Close stdin for an oversized envelope while still absorbing stream errors. */
+export function closeHookStdin(stdin) {
+    if (!stdin)
+        return;
+    stdin.once("error", () => { });
+    try {
+        stdin.end();
+    }
+    catch {
+        // No envelope was written; the hook is still allowed to run without args.
+    }
+}
 /**
  * Run one shell-hook command and return the parsed HookResult. Catches
  * every failure mode (spawn error, timeout, malformed JSON) and
  * returns an empty result so the registry's chain keeps going.
  */
-export async function runShellHook(config, ctx) {
+export async function runShellHook(config, ctx, abortSignal) {
     const timeoutMs = config.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    const signal = abortSignal ?? ctx.data.signal;
+    if (signal?.aborted)
+        return {};
     return new Promise((resolve) => {
         let child;
         try {
@@ -64,13 +156,20 @@ export async function runShellHook(config, ctx) {
         let stdout = "";
         let stderr = "";
         let settled = false;
+        let timer;
         const settle = (value) => {
             if (settled)
                 return;
             settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
             resolve(value);
         };
-        const timer = setTimeout(() => {
+        const onAbort = () => {
+            killChildTree(child, 1000);
+            settle({});
+        };
+        timer = setTimeout(() => {
             // eslint-disable-next-line no-console
             console.warn(`[hooks] ${config.event} hook timed out after ${timeoutMs}ms: ${config.command}`);
             // win32: taskkill /T reaps the shell tree; POSIX: SIGTERM → grace →
@@ -78,6 +177,9 @@ export async function runShellHook(config, ctx) {
             killChildTree(child, 1000);
             settle({});
         }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
         // Byte cap: once we cross MAX_HOOK_OUTPUT_BYTES on stdout, kill the
         // child and surface a 'cap exceeded' failure. A misbehaving handler
         // can otherwise hold the engine memory hostage while we accumulate
@@ -119,8 +221,9 @@ export async function runShellHook(config, ctx) {
             console.error(`[hooks] ${config.event} hook failed: ${config.command}`, err.message);
             settle({});
         });
-        child.on("close", (code) => {
-            clearTimeout(timer);
+        let stdinFinished = false;
+        let pendingClose;
+        const handleClose = (code) => {
             if (stdoutCapped) {
                 // eslint-disable-next-line no-console
                 console.error(`[hooks] ${config.event} hook killed due to oversized stdout (> ${MAX_HOOK_OUTPUT_BYTES} bytes)`);
@@ -166,17 +269,65 @@ export async function runShellHook(config, ctx) {
             // eslint-disable-next-line no-console
             console.error(`[hooks] ${config.event} hook exited with code ${code}:`, stderr.slice(0, 500));
             settle({});
+        };
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            // If close wins the event-loop race, wait for stdin's callback/error so
+            // an EPIPE cannot be overwritten by an apparently clean child exit.
+            if (!stdinFinished && !stdoutCapped) {
+                pendingClose = { code };
+                return;
+            }
+            handleClose(code);
         });
-        // Write the context envelope on stdin then close.
+        const finishStdin = () => {
+            stdinFinished = true;
+            if (pendingClose && !settled) {
+                const { code } = pendingClose;
+                pendingClose = undefined;
+                handleClose(code);
+            }
+        };
+        let envelope;
         try {
-            child.stdin?.write(JSON.stringify({ eventName: ctx.eventName, data: ctx.data }));
-            child.stdin?.end();
+            envelope = JSON.stringify({ eventName: ctx.eventName, data: ctx.data });
         }
-        catch (err) {
+        catch (error) {
             // eslint-disable-next-line no-console
-            console.error(`[hooks] failed to write stdin for ${config.event}:`, err.message);
+            console.error(`[hooks] failed to serialize stdin for ${config.event}:`, error instanceof Error ? error.message : String(error));
             settle({});
+            return;
         }
+        if (Buffer.byteLength(envelope, "utf8") > MAX_HOOK_STDIN_BYTES) {
+            // eslint-disable-next-line no-console
+            console.warn(`[hooks] ${config.event} hook stdin exceeded ${MAX_HOOK_STDIN_BYTES} bytes; running without envelope`);
+            closeHookStdin(child.stdin);
+            finishStdin();
+            return;
+        }
+        // Let the spawned shell enter user code before writing. Besides avoiding a
+        // needless race, this makes an intentional early stdin close observable as
+        // EPIPE/ECONNRESET while the child is still alive.
+        setImmediate(() => {
+            void (async () => {
+                if (settled)
+                    return;
+                try {
+                    await writeHookStdin(child.stdin, envelope);
+                    finishStdin();
+                }
+                catch (error) {
+                    clearTimeout(timer);
+                    const failure = stdinFailure(error);
+                    // eslint-disable-next-line no-console
+                    console.error(`[hooks] failed to write stdin for ${config.event}:`, failure.message);
+                    killChildTree(child, 1000);
+                    settle({ data: { hookFailure: failure } });
+                }
+            })();
+        });
     });
 }
 /**

package/dist/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.7.0";
-export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionWorkspace, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
+export declare const VERSION = "0.7.1";
+export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionWorkspace, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 export { Engine, loadAgentDefinitionsForCwd } from "./engine/engine.js";
 export type { EngineConfig, EngineHookConfig, EngineResult } from "./engine/types.js";
@@ -30,7 +30,7 @@ export type { ApprovalBackend } from "./tool-system/permission.js";
 export { BUILTIN_TOOLS } from "./tool-system/builtin/index.js";
 export type { BuiltinTool, BuiltinToolFn } from "./tool-system/builtin/index.js";
 export { makeUpdateAutomationMemoryTool } from "./tool-system/builtin/update-automation-memory.js";
-export { MCPManager, buildHttpHeaders, buildStdioEnv } from "./tool-system/mcp-manager.js";
+export { MCPManager, buildHttpHeaders, buildStdioEnv, createMcpAuthenticatedFetch, } from "./tool-system/mcp-manager.js";
 export type { AskUserFn } from "./tool-system/builtin/ask-user.js";
 export type { Task, TaskStatus } from "./tool-system/builtin/task.js";
 export { HookRegistry } from "./hooks/registry.js";
@@ -41,9 +41,9 @@ export { AgentClient, type BackgroundAgentCompletedHandler } from "./protocol/cl
 export { createInProcessTransport, StdioTransport, type Transport } from "./protocol/transport.js";
 export { SocketTransport, listenTcp, type TcpListenResult } from "./protocol/tcp-transport.js";
 export { createServer, createClient, type CreateServerOptions, type CreateClientOptions, type ServerHandle, } from "./protocol/factories.js";
-export { Methods, ErrorCodes, type RpcMessage, type RunResult } from "./protocol/types.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult, type ForkSessionParams, type ForkSessionResult as ProtocolForkSessionResult, } from "./protocol/types.js";
 export { Transcript } from "./session/transcript.js";
-export { SessionManager } from "./session/session-manager.js";
+export { SessionManager, buildForkState, buildForkTranscript, type ForkSessionOptions, type ForkSessionResult, } from "./session/session-manager.js";
 export { FileHistory } from "./session/file-history.js";
 export { createWorktree, currentBranch, DEFAULT_WORKTREE_BRANCH_PREFIX, getWorktreeDiff, isManagedWorktreeBranch, isValidWorktreeBranchPrefix, findMainWorktreeRoot, listWorktrees, listWorktreesFast, normalizeWorktreeBranchPrefix, removeWorktree, validateWorktreeSlug, worktreeHasUncommittedOrAheadChanges, worktreeHasUncommittedChanges, type CreateWorktreeOptions, type ListWorktreesOptions, type ListWorktreesFastOptions, type RemoveWorktreeResult, type RemoveWorktreeOptions, type WorktreeDiffSummary, type WorktreeInfo, type WorktreeWorkspaceOwner, } from "./git/worktree.js";
 export { latestUndoTarget, earliestSnapshotsPerFile, latestTurnUndoTargets, latestRedoTargets, } from "./session/undo-target.js";
@@ -51,6 +51,7 @@ export { diffLines, renderDiffPreview, type DiffLine } from "./session/simple-di
 export { MemoryManager } from "./session/memory.js";
 export type { MemoryEntry, MemoryOrigin, MemoryScope } from "./session/memory.js";
 export { runDreamConsolidation, type DreamConsolidationInput, type DreamConsolidationResult, } from "./services/dream-consolidation.js";
+export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, type OAuthConfig, type OAuthTokens, type OAuthAuthorizeOptions, type OAuthRefreshOptions, type HardenedOAuthFetchOptions, } from "./services/oauth.js";
 export type { FileSnapshot, RedoRecord } from "./session/file-history.js";
 export { PromptComposer } from "./prompt/composer.js";
 export { SectionCache } from "./prompt/section-cache.js";
@@ -109,7 +110,7 @@ export { migrateConfig, configVersionOf, CURRENT_CONFIG_VERSION, type MigrationS
 export { SettingsSchema, validateSettings } from "./settings/schema.js";
 export { settingsJsonSchema, writeSettingsSchemaFile } from "./settings/schema-export.js";
 export { personalizationFrom, type PersonalizationConfig } from "./settings/personalization.js";
-export { CredentialStore, type CredentialScope, type MaskedCredential, type Credential, type CredentialType, type CredentialStoreFile, type OAuthCredentialPublicStatus, type OAuthCredentialSecret, buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, formatNetscapeCookies, parseCookieJar, type CookieLike, useCredentialToolDef, useCredentialToolDefFor, sweepStaleCredentialCookies, getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, type CredentialAccess, type CredentialAccessScope, type CredentialMetadata, type CredentialSnapshot, type CredentialSnapshotEntry, type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./credentials/index.js";
+export { CredentialStore, type CredentialScope, type MaskedCredential, type Credential, type CredentialType, type CredentialStoreFile, type OAuthCredentialPublicStatus, type OAuthCredentialSecret, type OAuthTokenResponse, buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, formatNetscapeCookies, parseCookieJar, type CookieLike, useCredentialToolDef, useCredentialToolDefFor, sweepStaleCredentialCookies, getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, credentialAllowsEnvExposure, credentialSecretHint, isCredentialSecretAvailable, materializeCookieSecret, type CredentialAccess, type CredentialAccessScope, type CredentialMetadata, type CredentialSnapshot, type CredentialSnapshotEntry, type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./credentials/index.js";
 /** @internal Shared with the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, type AttributedCounter, type ChannelEntry, } from "./state.js";
 /** @internal Shared primitives for the in-repo TUI/desktop hosts; not stable SDK surface. */

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.7.0";
+export const VERSION = "0.7.1";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────
@@ -27,7 +27,7 @@ export { ToolExecutor } from "./tool-system/executor.js";
 export { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend, } from "./tool-system/permission.js";
 export { BUILTIN_TOOLS } from "./tool-system/builtin/index.js";
 export { makeUpdateAutomationMemoryTool } from "./tool-system/builtin/update-automation-memory.js";
-export { MCPManager, buildHttpHeaders, buildStdioEnv } from "./tool-system/mcp-manager.js";
+export { MCPManager, buildHttpHeaders, buildStdioEnv, createMcpAuthenticatedFetch, } from "./tool-system/mcp-manager.js";
 // ─── Hooks ───────────────────────────────────────────────────────
 export { HookRegistry } from "./hooks/registry.js";
 export { wrapHookMessages } from "./hooks/inject.js";
@@ -39,16 +39,17 @@ export { SocketTransport, listenTcp } from "./protocol/tcp-transport.js";
 // Recommended public factories — see protocol/factories.ts for the
 // stable construction contract referenced by standard §7.
 export { createServer, createClient, } from "./protocol/factories.js";
-export { Methods, ErrorCodes } from "./protocol/types.js";
+export { Methods, ErrorCodes, } from "./protocol/types.js";
 // ─── Session ─────────────────────────────────────────────────────
 export { Transcript } from "./session/transcript.js";
-export { SessionManager } from "./session/session-manager.js";
+export { SessionManager, buildForkState, buildForkTranscript, } from "./session/session-manager.js";
 export { FileHistory } from "./session/file-history.js";
 export { createWorktree, currentBranch, DEFAULT_WORKTREE_BRANCH_PREFIX, getWorktreeDiff, isManagedWorktreeBranch, isValidWorktreeBranchPrefix, findMainWorktreeRoot, listWorktrees, listWorktreesFast, normalizeWorktreeBranchPrefix, removeWorktree, validateWorktreeSlug, worktreeHasUncommittedOrAheadChanges, worktreeHasUncommittedChanges, } from "./git/worktree.js";
 export { latestUndoTarget, earliestSnapshotsPerFile, latestTurnUndoTargets, latestRedoTargets, } from "./session/undo-target.js";
 export { diffLines, renderDiffPreview } from "./session/simple-diff.js";
 export { MemoryManager } from "./session/memory.js";
 export { runDreamConsolidation, } from "./services/dream-consolidation.js";
+export { authorize, refreshToken, generatePKCE, createHardenedOAuthFetch, } from "./services/oauth.js";
 // ─── Prompt ──────────────────────────────────────────────────────
 export { PromptComposer } from "./prompt/composer.js";
 export { SectionCache } from "./prompt/section-cache.js";
@@ -127,7 +128,7 @@ export { migrateConfig, configVersionOf, CURRENT_CONFIG_VERSION, } from "./setti
 export { SettingsSchema, validateSettings } from "./settings/schema.js";
 export { settingsJsonSchema, writeSettingsSchemaFile } from "./settings/schema-export.js";
 export { personalizationFrom } from "./settings/personalization.js";
-export { CredentialStore, buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, formatNetscapeCookies, parseCookieJar, useCredentialToolDef, useCredentialToolDefFor, sweepStaleCredentialCookies, getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./credentials/index.js";
+export { CredentialStore, buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, formatNetscapeCookies, parseCookieJar, useCredentialToolDef, useCredentialToolDefFor, sweepStaleCredentialCookies, getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, credentialAllowsEnvExposure, credentialSecretHint, isCredentialSecretAvailable, materializeCookieSecret, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./credentials/index.js";
 // ─── State (runtime singletons shared with TUI) ──────────────────
 /** @internal Shared with the in-repo TUI/desktop hosts; not stable SDK surface. */
 export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, } from "./state.js";

package/dist/llm/client-base.js

@@ -54,16 +54,18 @@ export class LLMClientBase {
         this.initClient();
     }
     recordUsage(usage, options) {
-        if (options?.recordUsage === false)
-            return;
-        this.usage.records.push(usage);
-        this.usage.totalPromptTokens += usage.promptTokens;
-        this.usage.totalCompletionTokens += usage.completionTokens;
-        this.usage.totalTokens += usage.totalTokens;
-        this.usage.totalCacheReadTokens += usage.cacheReadTokens ?? 0;
-        this.usage.totalCacheCreationTokens += usage.cacheCreationTokens ?? 0;
-        this.usage.requestCount++;
-        LLMClientBase.onUsage?.(this.model, usage);
+        if (options?.requestVisible !== false) {
+            this.usage.records.push(usage);
+            this.usage.totalPromptTokens += usage.promptTokens;
+            this.usage.totalCompletionTokens += usage.completionTokens;
+            this.usage.totalTokens += usage.totalTokens;
+            this.usage.totalCacheReadTokens += usage.cacheReadTokens ?? 0;
+            this.usage.totalCacheCreationTokens += usage.cacheCreationTokens ?? 0;
+            this.usage.requestCount++;
+        }
+        if (options?.billingEnabled !== false) {
+            LLMClientBase.onUsage?.(this.model, usage);
+        }
     }
     getUsage() {
         return { ...this.usage };

package/dist/llm/types.d.ts

@@ -12,13 +12,20 @@ export interface CreateMessageOptions {
     onChunk?: (chunk: LLMStreamChunk) => void;
     signal?: AbortSignal;
     /**
-     * If false, this call's usage is excluded from the client's usage tracker
-     * and from the process-wide onUsage hook. Used for auxiliary sub-calls
-     * (tool-summary, future helper prompts) that should not appear in
-     * session_end.cost or skew turn/requestCount semantics.
+     * Whether this real provider request is billed through the process-wide
+     * usage hook. This is independent of request visibility: auxiliary calls
+     * are normally billed while remaining hidden from the foreground request
+     * tracker. Only explicit manual-audit paths should disable billing.
      * @default true
      */
-    recordUsage?: boolean;
+    billingEnabled?: boolean;
+    /**
+     * Whether this request appears in the client's foreground usage tracker.
+     * Hidden auxiliary calls must report their usage to their owning Engine's
+     * session/Goal recorder instead.
+     * @default true
+     */
+    requestVisible?: boolean;
     /**
      * Reasoning/thinking setting for this call. Overrides LLMConfig.reasoning.
      * Rich shape ({mode:"off"|"on"} | {mode:"effort",effort} |

package/dist/plugins/pluginCommandHook.d.ts

@@ -42,13 +42,13 @@ export interface PluginCommandHookSpec {
     timeoutMs?: number;
 }
 /**
- * Run one plugin hook command. Returns an empty HookResult on any failure
- * (spawn error, timeout, non-zero exit, unparseable stdout) so the hook
- * chain keeps moving — a misbehaving plugin must not wedge the engine.
+ * Run one plugin hook command. CC's exit-code 2 and explicit deny/reject JSON
+ * are normalized to the native HookResult deny contract. Other failures stay
+ * non-blocking so a broken plugin does not wedge the engine.
  *
  * Stdin carries the same envelope shape the codeshell-native shell-runner
  * uses (eventName + data) so plugin authors who want richer context can
  * read it; CC plugins typically ignore stdin and emit context derived from
  * their own state (e.g. reading a SKILL.md off disk via PLUGIN_ROOT).
  */
-export declare function runPluginCommandHook(spec: PluginCommandHookSpec, ctx: HookContext): Promise<HookResult>;
+export declare function runPluginCommandHook(spec: PluginCommandHookSpec, ctx: HookContext, abortSignal?: AbortSignal): Promise<HookResult>;

package/dist/plugins/pluginCommandHook.js

@@ -32,6 +32,7 @@
  */
 import { spawn } from "node:child_process";
 import { MAX_HOOK_OUTPUT_BYTES } from "../hooks/hook-output.js";
+import { closeHookStdin, MAX_HOOK_STDIN_BYTES, writeHookStdin } from "../hooks/shell-runner.js";
 import { killChildTree } from "../runtime/spawn-common.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 /**
@@ -60,18 +61,49 @@ function extractAdditionalContext(parsed) {
     }
     return null;
 }
+function extractExplicitDenial(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    const nested = obj.hookSpecificOutput && typeof obj.hookSpecificOutput === "object"
+        ? obj.hookSpecificOutput
+        : undefined;
+    const decision = obj.decision ?? obj.permissionDecision ?? nested?.decision ?? nested?.permissionDecision;
+    if (decision !== "deny" && decision !== "reject")
+        return null;
+    const message = obj.reason ??
+        obj.message ??
+        obj.permissionDecisionReason ??
+        nested?.reason ??
+        nested?.message ??
+        nested?.permissionDecisionReason;
+    return typeof message === "string" && message.trim() ? { message: message.trim() } : {};
+}
+function parseJson(stdout) {
+    if (!stdout)
+        return undefined;
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
- * Run one plugin hook command. Returns an empty HookResult on any failure
- * (spawn error, timeout, non-zero exit, unparseable stdout) so the hook
- * chain keeps moving — a misbehaving plugin must not wedge the engine.
+ * Run one plugin hook command. CC's exit-code 2 and explicit deny/reject JSON
+ * are normalized to the native HookResult deny contract. Other failures stay
+ * non-blocking so a broken plugin does not wedge the engine.
  *
  * Stdin carries the same envelope shape the codeshell-native shell-runner
  * uses (eventName + data) so plugin authors who want richer context can
  * read it; CC plugins typically ignore stdin and emit context derived from
  * their own state (e.g. reading a SKILL.md off disk via PLUGIN_ROOT).
  */
-export async function runPluginCommandHook(spec, ctx) {
+export async function runPluginCommandHook(spec, ctx, abortSignal) {
     const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const signal = abortSignal ?? ctx.data.signal;
+    if (signal?.aborted)
+        return {};
     return new Promise((resolve) => {
         let child;
         try {
@@ -101,6 +133,7 @@ export async function runPluginCommandHook(spec, ctx) {
         let stdout = "";
         let stderr = "";
         let settled = false;
+        let timer;
         // Output byte caps mirror src/hooks/shell-runner.ts so a chatty plugin
         // hook can't hold engine memory hostage. Past the cap we SIGTERM the
         // child and treat the hook as failed; stderr cap truncates with a
@@ -112,15 +145,24 @@ export async function runPluginCommandHook(spec, ctx) {
             if (settled)
                 return;
             settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
             resolve(value);
         };
-        const timer = setTimeout(() => {
+        const onAbort = () => {
+            killChildTree(child, 1000);
+            settle({});
+        };
+        timer = setTimeout(() => {
             // eslint-disable-next-line no-console
             console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} timed out after ${timeoutMs}ms`);
             // win32: taskkill /T reaps the tree; POSIX: SIGTERM → grace → SIGKILL.
             killChildTree(child, 1000);
             settle({});
         }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
         child.stdout?.on("data", (chunk) => {
             stdoutBytes += chunk.length;
             if (stdoutBytes > MAX_HOOK_OUTPUT_BYTES) {
@@ -150,21 +192,29 @@ export async function runPluginCommandHook(spec, ctx) {
             console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} spawn error:`, err.message);
             settle({});
         });
-        child.on("close", (code) => {
-            clearTimeout(timer);
+        let stdinFinished = false;
+        let pendingClose;
+        const handleClose = (code) => {
             if (stdoutCapped) {
                 // eslint-disable-next-line no-console
                 console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} killed due to oversized stdout (> ${MAX_HOOK_OUTPUT_BYTES} bytes)`);
                 settle({});
                 return;
             }
+            const trimmed = stdout.trim();
+            const parsedForDecision = parseJson(trimmed);
+            const explicitDenial = extractExplicitDenial(parsedForDecision);
+            if (code === 2 || explicitDenial) {
+                const message = stderr.trim() || explicitDenial?.message || "Plugin denied this tool operation";
+                settle({ decision: "deny", messages: [message] });
+                return;
+            }
             if (code !== 0) {
                 // eslint-disable-next-line no-console
                 console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} exited ${code}; stderr:`, stderr.slice(0, 500));
                 settle({});
                 return;
             }
-            const trimmed = stdout.trim();
             if (trimmed.length === 0) {
                 settle({});
                 return;
@@ -185,16 +235,64 @@ export async function runPluginCommandHook(spec, ctx) {
                 return;
             }
             settle({ messages: [additional] });
+        };
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            if (!stdinFinished && !stdoutCapped) {
+                pendingClose = { code };
+                return;
+            }
+            handleClose(code);
         });
+        const finishStdin = () => {
+            stdinFinished = true;
+            if (pendingClose && !settled) {
+                const { code } = pendingClose;
+                pendingClose = undefined;
+                handleClose(code);
+            }
+        };
         // Stdin envelope: matches the shape codeshell-native shell hooks use.
-        // CC plugins generally don't read stdin, but writing it is cheap and
-        // keeps the protocol open for plugin authors who want it.
+        let envelope;
         try {
-            child.stdin?.write(JSON.stringify({ eventName: ctx.eventName, data: ctx.data }));
-            child.stdin?.end();
+            envelope = JSON.stringify({ eventName: ctx.eventName, data: ctx.data });
         }
         catch {
-            // Child may have closed stdin already; not fatal.
+            closeHookStdin(child.stdin);
+            finishStdin();
+            return;
         }
+        if (Buffer.byteLength(envelope, "utf8") > MAX_HOOK_STDIN_BYTES) {
+            // eslint-disable-next-line no-console
+            console.warn(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} stdin exceeded ${MAX_HOOK_STDIN_BYTES} bytes; running without envelope`);
+            closeHookStdin(child.stdin);
+            finishStdin();
+            return;
+        }
+        setImmediate(() => {
+            void (async () => {
+                if (settled)
+                    return;
+                try {
+                    await writeHookStdin(child.stdin, envelope);
+                    finishStdin();
+                }
+                catch (error) {
+                    clearTimeout(timer);
+                    const err = error;
+                    const failure = {
+                        type: "stdin_error",
+                        code: typeof err?.code === "string" ? err.code : "UNKNOWN",
+                        message: err instanceof Error ? err.message : String(error),
+                    };
+                    // eslint-disable-next-line no-console
+                    console.error(`[plugin-hook] ${spec.pluginKey} ${ctx.eventName} stdin error:`, failure.message);
+                    killChildTree(child, 1000);
+                    settle({ data: { hookFailure: failure } });
+                }
+            })();
+        });
     });
 }