@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/tool-system/builtin/worktree.d.ts

@@ -2,9 +2,10 @@
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 import { type WorktreeSession } from "../../git/worktree.js";
 export declare function getActiveWorktree(): WorktreeSession | undefined;
 export declare const enterWorktreeToolDef: ToolDefinition;
-export declare function enterWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;
 export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/worktree.js

@@ -1,7 +1,7 @@
 /**
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
-import { createWorktree, removeWorktree, validateWorktreeSlug, } from "../../git/worktree.js";
+import { createWorktree, removeWorktree, validateWorktreeSlug, selectPlatformScript, runWorktreeSetup, } from "../../git/worktree.js";
 // Global worktree state
 let _activeWorktree;
 export function getActiveWorktree() {
@@ -25,7 +25,7 @@ export const enterWorktreeToolDef = {
         required: ["slug"],
     },
 };
-export async function enterWorktreeTool(args) {
+export async function enterWorktreeTool(args, ctx) {
     const slug = args.slug;
     if (!slug)
         return "Error: slug is required";
@@ -41,18 +41,45 @@ export async function enterWorktreeTool(args) {
     try {
         // Use a placeholder session ID (the agent should set this properly)
         const sessionId = args.__sessionId ?? `wt-${Date.now()}`;
-        const cwd = args.__cwd ?? process.cwd();
+        const cwd = args.__cwd ?? ctx?.cwd ?? process.cwd();
         _activeWorktree = createWorktree(cwd, slug, sessionId);
+        // Run the project's localEnvironment.setupScripts once in the new
+        // worktree root (Beta decision 2026-06-08: setup belongs to the worktree
+        // lifecycle, not the conversation). Failure warns-but-continues — a broken
+        // setup script must not strand the agent outside a worktree it just made.
+        let setupNote = "";
+        const setupScripts = ctx?.engine?.readWorktreeSetupScripts(cwd);
+        const script = selectPlatformScript(setupScripts);
+        if (script) {
+            const setup = await runWorktreeSetup(_activeWorktree.worktreePath, script, {
+                sandbox: ctx?.sandbox,
+                shellEnv: ctx?.shellEnv,
+                signal: ctx?.signal,
+            });
+            if (setup.ok) {
+                setupNote = `\n\nRan setup script (exit 0).${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+            else {
+                setupNote =
+                    `\n\n⚠️ Setup script failed (exit ${setup.exitCode ?? "?"}) — continuing anyway. ` +
+                        `You may need to run setup manually.${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+        }
         return (`Worktree created:\n` +
             `  Path:   ${_activeWorktree.worktreePath}\n` +
             `  Branch: ${_activeWorktree.worktreeBranch}\n` +
             `  From:   ${_activeWorktree.originalBranch ?? "HEAD"}\n\n` +
-            `You are now working in an isolated copy. Changes here won't affect the main repo.`);
+            `You are now working in an isolated copy. Changes here won't affect the main repo.` +
+            setupNote);
     }
     catch (err) {
         return `Error creating worktree: ${err.message}`;
     }
 }
+/** Keep setup output from bloating the tool result — head+tail-ish trim. */
+function truncate(s, max = 2000) {
+    return s.length <= max ? s : `${s.slice(0, max)}\n…(${s.length - max} more chars)`;
+}
 export const exitWorktreeToolDef = {
     name: "ExitWorktree",
     description: "Exit the current worktree and return to the main working directory. " +

package/dist/tool-system/builtin/write.js

@@ -4,7 +4,6 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { fileCache } from "./file-cache.js";
-import { enforcePathPolicy } from "../path-policy.js";
 export const writeToolDef = {
     name: "Write",
     description: "Write content to a file. Creates the file if it doesn't exist, " +
@@ -25,11 +24,6 @@ export async function writeTool(args, ctx) {
         return "Error: file_path is required";
     if (content === undefined)
         return "Error: content is required";
-    // Path policy gate: deny writes to sensitive paths, refuse writes outside
-    // workspace until approved. See tool-system/path-policy.ts.
-    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
-    if (blocked)
-        return blocked;
     try {
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, content, "utf-8");

package/dist/tool-system/context.d.ts

@@ -18,11 +18,39 @@ import type { ToolRegistry } from "./registry.js";
 import type { AgentPresetName } from "../preset/index.js";
 import type { SandboxBackend } from "./sandbox/index.js";
 import type { HookRegistry } from "../hooks/registry.js";
-import type { Engine } from "../engine/engine.js";
+/**
+ * Narrow view of the owning Engine that tools are allowed to call back into.
+ * Defined here (in the low-level tool-system) rather than importing the
+ * concrete `Engine` type so tool-system does NOT depend on the top-level
+ * engine module — that import created a tool-system ↔ engine cycle. The Engine
+ * class satisfies this structurally (no `implements` needed); this interface
+ * lists exactly the members tools use today (see plan.ts / worktree.ts).
+ */
+export interface ToolRuntimeHost {
+    /** Whether the owning Engine is currently in plan mode. */
+    readonly planMode: boolean;
+    /** Toggle plan mode (EnterPlanMode / ExitPlanMode tools). */
+    setPlanMode(value: boolean): void;
+    /** Per-worktree setup scripts, or undefined for sub-agents / no cwd. */
+    readWorktreeSetupScripts(cwd?: string): {
+        default?: string;
+        macos?: string;
+        linux?: string;
+        windows?: string;
+    } | undefined;
+}
 /** One choice in a multiple-choice AskUserQuestion. */
 export interface AskUserChoice {
     label: string;
     description: string;
+    /**
+     * Optional semantic hint for how the UI colors this choice and its resolved
+     * echo — `ok` (affirmative / allow → green ✓), `danger` (negative / deny →
+     * red ✕), `neutral` (no coloring). Only set by trusted first-party callers
+     * with fixed option sets (e.g. the credential-use gate); the LLM-facing
+     * AskUserQuestion tool strips it so model-authored prompts stay neutral.
+     */
+    tone?: "ok" | "danger" | "neutral";
 }
 /**
  * Optional rendering hints / multiple-choice options carried alongside the
@@ -35,6 +63,14 @@ export interface AskUserOptions {
     options?: AskUserChoice[];
     /** Allow the user to pick more than one option. Defaults to false. */
     multiSelect?: boolean;
+    /**
+     * When true, the UI must offer ONLY the given `options` — no "其它…"
+     * free-text escape hatch. Used by closed-set decisions (e.g. a path-permission
+     * 允许本次/拒绝 prompt) where the answer is interpreted by an exact label
+     * match, so a free-typed answer like "允许" would never match and silently
+     * deny. Ignored unless `options` is non-empty.
+     */
+    optionsOnly?: boolean;
 }
 /**
  * Function the host UI / server uses to ask the user a question.
@@ -76,6 +112,12 @@ export interface SubAgentSpawnRequest {
      * Undefined → child inherits the parent's full tool set (current behavior).
      */
     toolAllowlist?: string[];
+    /**
+     * Optional skill-name allowlist for the child (hard isolation). When set,
+     * the child only sees/invokes these skills in its system prompt and Skill
+     * tool. Undefined → child inherits the parent's full skill pool.
+     */
+    skillAllowlist?: string[];
     /**
      * Optional per-call system prompt appended to the child Engine's prompt
      * (the role definition's Markdown body). Undefined → child inherits only
@@ -84,10 +126,34 @@ export interface SubAgentSpawnRequest {
     appendSystemPrompt?: string;
     /** True for read-only reviewer/researcher children; tunes investigation guard reminders. */
     readOnlySession?: boolean;
+    /**
+     * Resume an existing child session instead of cold-starting a new one.
+     * When set, the child Engine runs with `sessionId: resumeSessionId`, which
+     * loads that session's full transcript (all prior tool calls + results) and
+     * appends this turn's prompt — i.e. transcript replay, the CC model. When
+     * omitted, the child cold-starts under its own `agentId` as the session id
+     * (so `agentId === childSid`, enabling later resume with no extra mapping).
+     * See AgentSendInput in builtin/agent.ts.
+     */
+    resumeSessionId?: string;
 }
 export interface SubAgentSpawner {
-    /** Run a sub-agent synchronously and return its text output. */
-    spawn(req: SubAgentSpawnRequest): Promise<string>;
+    /**
+     * Run a sub-agent synchronously. Returns its text output and the child's
+     * session id. The session id equals the request's `agentId` on a cold start
+     * (or `resumeSessionId` when resuming), so the parent can address follow-up
+     * input at the same session via AgentSendInput (transcript replay).
+     */
+    spawn(req: SubAgentSpawnRequest): Promise<{
+        text: string;
+        sessionId: string;
+    }>;
+    /**
+     * Whether a child session id exists on disk. Lets AgentSendInput resume an
+     * agent across a process restart (when the in-memory registry is empty but
+     * the session transcript is still persisted). Optional for legacy callers.
+     */
+    sessionExists?(sessionId: string): boolean;
     /** Stream callback to forward sub-agent events back to the parent UI. */
     parentStream?: StreamCallback;
     /** Static config used to describe what the spawned engine looks like. */
@@ -103,6 +169,10 @@ export interface SubAgentSpawner {
  * Optional fields are filled in by Engine.run(); some headless paths may
  * leave them undefined (e.g. running without UI → no askUser).
  */
+export interface ToolVisibilityContext {
+    cwd: string;
+    hasGoal: boolean;
+}
 export interface ToolContext {
     /** Active working directory for this Engine. */
     cwd: string;
@@ -156,9 +226,18 @@ export interface ToolContext {
     /** Whether the owning Engine is currently in plan mode. Replaces the
      *  removed module-level `isInPlanMode()` singleton. */
     planMode: boolean;
-    /** The Engine that built this context. Lets tools call back into the engine
-     *  (e.g. ctx.engine.setPlanMode(true/false)) without a module-level singleton. */
-    engine: Engine;
+    /**
+     * The owning Engine's permission mode. Path policy reads this so that
+     * `bypassPermissions` (the user's "完全访问") skips the path-approval prompt
+     * entirely — matching the tool-permission backend and CC, where bypass
+     * skips ALL checks including path validation. Undefined → treat as
+     * "default" (always enforce). */
+    permissionMode?: string;
+    /** The Engine that built this context, as the narrow {@link ToolRuntimeHost}
+     *  view. Lets tools call back into the engine (e.g. ctx.engine.setPlanMode)
+     *  without a module-level singleton — and without tool-system depending on
+     *  the concrete Engine type (which would re-introduce the import cycle). */
+    engine: ToolRuntimeHost;
     /**
      * sessionId of the Engine.run() turn this context was built for. Tools
      * that emit session-scoped side effects (today: background-agent
@@ -183,6 +262,28 @@ export interface ToolContext {
      * `settings.disabledPlugins` by Engine.run().
      */
     disabledPlugins?: string[];
+    /**
+     * Sub-agent skill allowlist (hard isolation). When set, this sub-agent may
+     * only see/invoke skills in this list — applied on top of the disabled
+     * lists. Undefined → inherit the parent's full pool (current behavior).
+     * Comes from the agent role definition's `skills:` frontmatter, threaded
+     * through SubAgentSpawnRequest.skillAllowlist into the child Engine.
+     */
+    skillAllowlist?: string[];
+    /**
+     * Background-shell manager (Bash run_in_background + BashOutput / KillShell
+     * / ListShells). Undefined → the tools fall back to the process-local
+     * `backgroundShellManager` singleton. Threaded explicitly so tests (and
+     * any future per-engine isolation) can inject their own instance.
+     */
+    backgroundShells?: import("../runtime/background-shell.js").BackgroundShellManager;
+    /**
+     * False in unattended automation/cron runs — `Bash(run_in_background=true)`
+     * is rejected and the three background-shell tools are stripped (design
+     * §5.5): no one is watching to reap a long-lived dev server. Defaults to
+     * true (interactive sessions allow it).
+     */
+    allowBackgroundShells?: boolean;
     /**
      * Builtin tool names the project's capabilityOverrides marked `off` for
      * this cwd. Engine.run() already HIDES these from the LLM-visible tool
@@ -193,7 +294,64 @@ export interface ToolContext {
      * sub-agents and no-cwd contexts (same as readBuiltinOverride).
      */
     disabledBuiltins?: Set<string>;
+    /**
+     * Per-turn context used by builtin availability guards. Engine.run() uses the
+     * same object to hide tools from the model; ToolExecutor reuses it to reject
+     * direct calls to tools that are not available in the current runtime state.
+     */
+    toolVisibility?: ToolVisibilityContext;
+    /**
+     * MCP servers THIS session's merged config enables (keys of
+     * config.mcpServers, enabled!==false). The pool + registry are
+     * worker-shared (B1), so tools registered by another project's session live
+     * in the same registry — the engine hides them from this session's tool
+     * list and the executor rejects calls to them via this set. Undefined =
+     * no gating (sub-agents / tests whose registries carry no MCP tools).
+     */
+    allowedMcpServers?: Set<string>;
+    /**
+     * The engine's settings scope, so tools that read disk config directly (e.g.
+     * the credential tools) can honor host-isolation instead of always merging
+     * the host user's ~/.code-shell. "full" = host app (user + project); "project"
+     * / "isolated" = must not surface host user credentials or autoApprove.
+     * Undefined = legacy/no-cwd → treated as "full" by consumers for compat.
+     */
+    settingsScope?: import("../settings/manager.js").SettingsScope;
+    /**
+     * Project-scoped extra environment variables (the user's
+     * `localEnvironment.env` KEY=VALUE pairs for this cwd). Layered on top of
+     * the shell env that the Bash tool and background shells build, so a project
+     * can inject e.g. `DATABASE_URL` / `NODE_ENV` into every command it runs.
+     * Unlike the sandbox allowlist, these bypass the deny regex — the user put
+     * them in project settings deliberately. Undefined for sub-agents and
+     * no-cwd contexts (populated from settings by Engine.buildToolContext()).
+     */
+    shellEnv?: Record<string, string>;
+    /**
+     * Browser automation bridge (browser_snapshot / click / type / navigate /
+     * scroll). The renderer implements it on top of the webview's CDP
+     * (Accessibility.getFullAXTree + Input.dispatchMouseEvent). Undefined →
+     * headless / no browser panel → the browser tools degrade with a clear error.
+     * See tool-system/browser-bridge.ts and the MVP spec
+     * docs/superpowers/specs/2026-06-16-browser-automation-mvp.md.
+     */
+    browser?: import("./browser-bridge.js").BrowserBridge;
+    /**
+     * Inject a stored cookie credential into the built-in browser (restore its
+     * login state so the AI can drive the page as that account). The host
+     * (desktop main) implements it on top of `restoreCookiesToBrowser`. Undefined
+     * → headless / no browser → the InjectCredential tool degrades with a clear
+     * error. Mirrors the askUser cross-process callback shape. The credentialId
+     * names a `type:"cookie"` credential; result counts cookies written.
+     */
+    injectCredentialToBrowser?: InjectCredentialFn;
 }
+/** Inject a cookie credential into the built-in browser (host-implemented). */
+export type InjectCredentialFn = (credentialId: string) => Promise<{
+    ok: boolean;
+    count?: number;
+    error?: string;
+}>;
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.
  * Engine creates one of these in run() and passes it to ToolExecutor.

package/dist/tool-system/executor.d.ts

@@ -39,7 +39,9 @@ export declare class ToolExecutor {
     /** Check if a tool is safe for concurrent execution (read-only). */
     isConcurrencySafe(toolName: string): boolean;
     executeSingle(callIn: ToolCall): Promise<ToolResult>;
-    private isReadOnlyBashCommand;
+    private resolvePolicyOperation;
+    private enforceDeclaredPathPolicy;
+    private resolvePathPolicyTargets;
     /**
      * Convert tool results into Message entries for the transcript.
      */