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

package/dist/settings/schema.js

@@ -2,6 +2,27 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
+import { ReasoningSettingSchema } from "../llm/reasoning-setting.js";
+/**
+ * Tri-state project capability overlay. Lives in PROJECT settings only and
+ * layers over the global baseline (disabledSkills / disabledPlugins /
+ * mcpServers.<name>.enabled / disabledAgents). NOT a second denylist:
+ *   - "on"      → force enabled (even if globally disabled)
+ *   - "off"     → force disabled (even if globally enabled)
+ *   - "inherit" → take the global baseline. We don't persist "inherit"; an
+ *                 absent key means inherit. See the project-scoped
+ *                 capabilities design (spec §4).
+ */
+export const CapabilityOverrideSchema = z.enum(["inherit", "on", "off"]);
+export const CapabilityOverridesSchema = z
+    .object({
+    skills: z.record(CapabilityOverrideSchema).optional(),
+    plugins: z.record(CapabilityOverrideSchema).optional(),
+    agents: z.record(CapabilityOverrideSchema).optional(),
+    mcp: z.record(CapabilityOverrideSchema).optional(),
+    builtin: z.record(CapabilityOverrideSchema).optional(),
+})
+    .optional();
 export const SettingsSchema = z
     .object({
     agent: z
@@ -12,6 +33,14 @@ export const SettingsSchema = z
         disabledBuiltinTools: z.array(z.string()).default([]),
         customSystemPrompt: z.string().optional(),
         appendSystemPrompt: z.string().optional(),
+        responseLanguage: z.string().optional(),
+        userProfile: z.string().optional(),
+        instructions: z
+            .object({
+            compatClaude: z.boolean().default(true),
+            compatCodex: z.boolean().default(true),
+        })
+            .optional(),
     })
         .default({}),
     /**
@@ -22,6 +51,15 @@ export const SettingsSchema = z
      * both — appendOnboardingResult does this in one shot.
      */
     activeKey: z.string().optional(),
+    /**
+     * Auxiliary-task model — points at a models[].key. Background, non-user-
+     * facing LLM calls (memory extraction, the auto-dream loop) use this model
+     * instead of the active one, so per-turn book-keeping doesn't burn the
+     * expensive primary model. Pick something fast/cheap (e.g. a Haiku or
+     * DeepSeek key). When unset, those calls fall back to the active model
+     * (legacy behavior). An invalid/missing key also falls back to active.
+     */
+    auxModelKey: z.string().optional(),
     /**
      * Toggle background auto-update. When true (default), code-shell checks
      * npm for newer versions and — if the npm global prefix is writable —
@@ -62,12 +100,11 @@ export const SettingsSchema = z
         protocol: z.enum(["openai-compat", "anthropic-style"]).optional(),
         modelsPath: z.string().optional(),
         /**
-         * DeepSeek V4 thinking-mode default for this provider. "enabled"
-         * matches endpoint default; "disabled" makes V4 calls run in
-         * non-thinking mode (faster, cheaper). Ignored by every provider
-         * other than DeepSeek V4. Per-call overrides still win.
+         * Default reasoning/thinking setting for this provider's models.
+         * Rich shape: {mode:"off"|"on"} | {mode:"effort",effort} |
+         * {mode:"budget",budgetTokens}. Per-model `reasoning` wins.
          */
-        thinking: z.enum(["enabled", "disabled"]).optional(),
+        reasoning: ReasoningSettingSchema.optional(),
     }))
         .default([]),
     models: z
@@ -90,12 +127,12 @@ export const SettingsSchema = z
         baseUrl: z.string().optional(),
         apiKey: z.string().optional(),
         /**
-         * Per-model thinking override. Wins over the provider-level
-         * setting (settings.providers[].thinking). Use this when
-         * different models under the same provider need different
-         * defaults — e.g. DeepSeek V4 Pro off (faster) but V4 Flash on.
+         * Per-model reasoning override. Wins over the provider-level
+         * `reasoning` setting (settings.providers[].reasoning). Use this
+         * when different models under the same provider need different
+         * defaults — e.g. one model off (faster) and another on.
          */
-        thinking: z.enum(["enabled", "disabled"]).optional(),
+        reasoning: ReasoningSettingSchema.optional(),
     })
         .transform((m) => {
         // Normalize: prefer `protocol`; fall back to legacy `provider`.
@@ -146,6 +183,9 @@ export const SettingsSchema = z
         url: z.string().optional(),
         transport: z.enum(["stdio", "sse", "streamable-http", "inprocess"]).optional(),
         headers: z.record(z.string()).optional(),
+        // Codex-style on/off switch. Absent or true → connected; only
+        // literal false disables. Filtered in MCPManager.connectAll.
+        enabled: z.boolean().optional(),
     }))
         .default({}),
     /**
@@ -162,6 +202,20 @@ export const SettingsSchema = z
      * names (no colon suffix). See scanSkills(opts.disabledPlugins).
      */
     disabledPlugins: z.array(z.string()).default([]),
+    /**
+     * Sub-agent role names (the `name` in .code-shell/agents/*.md) to
+     * hide from the registry. A disabled role is filtered out at load
+     * so it never appears in registry.list()/get() — the Agent tool's
+     * agent_type list won't show it and the LLM can't pick it. Mirrors
+     * disabledSkills / disabledPlugins.
+     */
+    disabledAgents: z.array(z.string()).default([]),
+    /**
+     * Project-scoped tri-state capability overlay. Only meaningful in
+     * ${cwd}/.code-shell/settings.json; layered over the global baseline at
+     * capability-assembly time. Optional — absence === everything inherits.
+     */
+    capabilityOverrides: CapabilityOverridesSchema,
     instructions: z
         .object({
         fileName: z.string().default("CODESHELL.md"),
@@ -204,6 +258,15 @@ export const SettingsSchema = z
             .record(z.enum(["serper", "tavily", "searxng"]), z.object({
             apiKey: z.string().optional(),
             baseUrl: z.string().optional(),
+            lastProbe: z
+                .object({
+                status: z.enum(["ok", "error", "unconfigured"]),
+                sampleTitles: z.array(z.string()).optional(),
+                errorMessage: z.string().optional(),
+                errorDetail: z.string().optional(),
+                lastProbedAt: z.string(),
+            })
+                .optional(),
         }))
             .optional(),
     })
@@ -213,6 +276,24 @@ export const SettingsSchema = z
         format: z.enum(["text", "json", "jsonl", "stream-json"]).default("text"),
     })
         .default({}),
+    /**
+     * Image attachment handling. Sub-fields:
+     *   - detail: OpenAI-style fidelity hint applied to every user-
+     *     attached image. "low" = 85 tokens/image fixed (cheap
+     *     thumbnail), "high" = ~768 px tiles (default), "original" =
+     *     keep client-side dimensions (most expensive). Anthropic
+     *     ignores this field today; that's fine — it just gets
+     *     dropped on the Claude path.
+     *   - mcpImageTokenBudget: per-turn cap on token cost of images
+     *     returned by MCP tools. Codex doesn't enforce this; CC uses
+     *     25 000. Set to 0 to disable.
+     */
+    images: z
+        .object({
+        detail: z.enum(["low", "high", "original"]).optional(),
+        mcpImageTokenBudget: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
     /**
      * OS-level sandbox for shell-tool execution. "auto" picks per platform:
      * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
@@ -227,6 +308,34 @@ export const SettingsSchema = z
         network: z.enum(["allow", "deny"]).optional(),
     })
         .optional(),
+    /**
+     * Project-local environment profile. Mirrors Codex's local-environment
+     * shape at the settings layer: setup/cleanup scripts can be customized per
+     * platform, and env values are stored as KEY=VALUE pairs. Runtime wiring is
+     * intentionally separate from the MCP server env model above.
+     */
+    localEnvironment: z
+        .object({
+        name: z.string().optional(),
+        setupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        cleanupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        env: z.record(z.string()).optional(),
+    })
+        .optional(),
     /**
      * Shell-hook configuration. Each entry binds a HookEventName to a
      * shell command; the command receives ctx JSON on stdin and returns

package/dist/tool-system/builtin/add-marketplace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in AddMarketplace tool — register a plugin marketplace source so the
+ * user can browse/install plugins from it in the UI. The tool only *adds the
+ * source* (git clone + validate marketplace.json via core's addMarketplace);
+ * which plugin to install is left to the user. Pairs with WebSearch/WebFetch:
+ * the model can discover a marketplace repo, then add it.
+ *
+ * Side effects (network + git clone + disk write) → permissionDefault "ask".
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const addMarketplaceToolDef: ToolDefinition;
+export declare function addMarketplaceTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/add-marketplace.js

@@ -0,0 +1,76 @@
+/**
+ * Built-in AddMarketplace tool — register a plugin marketplace source so the
+ * user can browse/install plugins from it in the UI. The tool only *adds the
+ * source* (git clone + validate marketplace.json via core's addMarketplace);
+ * which plugin to install is left to the user. Pairs with WebSearch/WebFetch:
+ * the model can discover a marketplace repo, then add it.
+ *
+ * Side effects (network + git clone + disk write) → permissionDefault "ask".
+ */
+import { addMarketplace } from "../../plugins/marketplaceManager.js";
+export const addMarketplaceToolDef = {
+    name: "AddMarketplace",
+    description: "Register a plugin marketplace source so the user can browse and install " +
+        "plugins from it. Provide a short name and a source: either a GitHub repo " +
+        "(owner/name) or a git URL. This only ADDS the source — it does not install " +
+        "any plugin. Use WebSearch/WebFetch first to find a marketplace repo if you " +
+        "don't already have one.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Short local name for this marketplace (e.g. 'official').",
+            },
+            source_type: {
+                type: "string",
+                enum: ["github", "git"],
+                description: "'github' for an owner/name repo, 'git' for a clone URL.",
+            },
+            repo: {
+                type: "string",
+                description: "GitHub repo in owner/name form (required when source_type='github').",
+            },
+            url: {
+                type: "string",
+                description: "Git clone URL (required when source_type='git').",
+            },
+        },
+        required: ["name", "source_type"],
+    },
+};
+export async function addMarketplaceTool(args) {
+    const name = args.name;
+    if (typeof name !== "string" || !name.trim()) {
+        return "Error: name is required";
+    }
+    const sourceType = args.source_type;
+    let source;
+    if (sourceType === "github") {
+        const repo = args.repo;
+        if (typeof repo !== "string" || !repo.includes("/")) {
+            return "Error: github source requires repo in owner/name form";
+        }
+        source = { source: "github", repo };
+    }
+    else if (sourceType === "git") {
+        const url = args.url;
+        if (typeof url !== "string" || !url.trim()) {
+            return "Error: git source requires a url";
+        }
+        source = { source: "git", url };
+    }
+    else {
+        return "Error: source_type must be 'github' or 'git'";
+    }
+    try {
+        const result = await addMarketplace(name, source);
+        if (!result.ok) {
+            return `Error adding marketplace ${name}: ${result.error}`;
+        }
+        return `Marketplace '${name}' added. The user can now browse and install plugins from it in the Extensions → Market UI.`;
+    }
+    catch (err) {
+        return `Error adding marketplace ${name}: ${err.message}`;
+    }
+}

package/dist/tool-system/builtin/agent-registry.d.ts

@@ -29,7 +29,15 @@ export interface AsyncAgentEntry {
     agentId: string;
     /** Short kind label shown in the dock (e.g. "Explore", "Plan"). */
     name?: string;
+    /** Dispatched role (e.g. "general-purpose", "explorer"); shown in the dock
+     *  so you can see what kind of agent is running. */
+    agentType?: string;
     description: string;
+    /** Session that spawned this background agent. Lets the spawning
+     *  Engine.run wait only on ITS OWN background agents (hasRunningForSession),
+     *  not every concurrent session's. Undefined only for legacy/ad-hoc callers
+     *  outside Engine.run. */
+    sessionId?: string;
     status: AsyncAgentStatus;
     startedAt: number;
     finishedAt?: number;
@@ -46,6 +54,9 @@ declare class AsyncAgentRegistry {
     subscribe: (cb: () => void) => (() => void);
     getSnapshot: () => AsyncAgentEntry[];
     hasRunning: () => boolean;
+    /** True if any background agent spawned by `sessionId` is still running.
+     *  Drives Engine.run's "wait for my background agents before resolving". */
+    hasRunningForSession: (sessionId: string) => boolean;
     /** Count of agents currently in the "running" state (cap enforcement). */
     runningCount(): number;
     private notify;

package/dist/tool-system/builtin/agent-registry.js

@@ -30,6 +30,11 @@ class AsyncAgentRegistry {
     hasRunning = () => {
         return this.snapshot.some((e) => e.status === "running");
     };
+    /** True if any background agent spawned by `sessionId` is still running.
+     *  Drives Engine.run's "wait for my background agents before resolving". */
+    hasRunningForSession = (sessionId) => {
+        return this.snapshot.some((e) => e.status === "running" && e.sessionId === sessionId);
+    };
     /** Count of agents currently in the "running" state (cap enforcement). */
     runningCount() {
         return this.snapshot.filter((e) => e.status === "running").length;
@@ -108,10 +113,9 @@ class AsyncAgentRegistry {
         catch {
             // ignore abort errors — we still mark cancelled
         }
-        e.status = "cancelled";
-        e.finishedAt = Date.now();
-        e.finishedFadeAt = e.finishedAt + 30_000;
-        this.notify();
+        // Reuse markFinished for the status/timestamp/notify bookkeeping rather
+        // than duplicating it (the entry is still "running" after abort()).
+        this.markFinished(agentId, "cancelled");
         return true;
     }
     reset() {

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

@@ -11,6 +11,7 @@ import type { ToolContext } from "../context.js";
 import type { AgentDefinitionRegistry } from "../../agent/agent-definition-registry.js";
 import type { HookRegistry } from "../../hooks/registry.js";
 export interface AgentTypeOverrides {
+    resolvedType?: string;
     model?: string;
     maxTurns?: number;
     toolAllowlist?: string[];
@@ -18,10 +19,36 @@ export interface AgentTypeOverrides {
 }
 /**
  * Resolve an `agent_type` against the role registry into spawn overrides.
- * Omitted type → empty overrides (ephemeral mode). Unknown type → throw, so
- * the LLM gets a clear correction instead of silently running a generic agent.
+ *
+ * - Omitted type + non-empty registry → fall back to a configured role
+ *   ("general-purpose" if present, else the first available) instead of
+ *   running a nameless ephemeral agent. Relaxed from the earlier "throw when
+ *   agent_type omitted": the model habitually omits it, and a hard error just
+ *   turned every spawn into a failure. Falling back to a real role keeps the
+ *   tool-allowlist / system-prompt benefits without breaking the call.
+ * - Omitted type + empty registry → empty overrides (true ephemeral; nothing
+ *   to fall back to).
+ * - Unknown explicit type → throw, so the LLM gets a clear correction rather
+ *   than silently running a generic agent.
  */
 export declare function resolveAgentTypeOverrides(agentType: string | undefined, registry: AgentDefinitionRegistry | undefined): AgentTypeOverrides;
+/**
+ * Render the "Available agent types" block injected into the Agent tool's
+ * description, listing the roles defined in .code-shell/agents/*.md so the
+ * model knows it can pass `agent_type` instead of hand-rolling an ad-hoc
+ * agent. Without this the model never sees the registry (it lives per-engine,
+ * not in the static tool def) and falls back to nameless ephemeral agents —
+ * see the Core A/B/C incident. Returns "" when no roles are defined, so the
+ * base description is left untouched.
+ */
+export declare function buildAgentTypesBlock(registry: AgentDefinitionRegistry | undefined): string;
+/**
+ * Produce an Agent tool definition whose description ends with the live
+ * available-agent-types listing. Pure: takes the registry, returns a new def
+ * (the base `agentToolDef` const is never mutated). When no roles exist the
+ * base def is returned unchanged.
+ */
+export declare function agentToolDefWithTypes(registry: AgentDefinitionRegistry | undefined): ToolDefinition;
 type SubAgentLifecycle = "subagent_start" | "subagent_finish" | "subagent_error";
 /**
  * Emit a sub-agent lifecycle event via the existing `notification` hook,
@@ -35,14 +62,6 @@ export declare function emitSubAgentHook(hooks: HookRegistry | undefined, kind:
     text?: string;
     error?: string;
 }): void;
-/** Default per-sub-agent wall-clock timeout (5 minutes). */
-export declare const DEFAULT_SUBAGENT_TIMEOUT_MS: number;
-/**
- * Run `work()` with a timeout. On expiry, calls `onTimeout` (to abort the
- * child) and rejects with a timeout error. The child's own abort handling
- * unwinds its resources.
- */
-export declare function runWithTimeout<T>(work: () => Promise<T>, timeoutMs: number, onTimeout: () => void): Promise<T>;
 export declare const agentToolDef: ToolDefinition;
 export declare function agentTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const agentStatusToolDef: ToolDefinition;

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

@@ -32,26 +32,79 @@ function safeEmit(sink, event) {
         });
     }
 }
+/** Preferred default role when the caller omits agent_type but roles exist. */
+const DEFAULT_AGENT_TYPE = "general-purpose";
 /**
  * Resolve an `agent_type` against the role registry into spawn overrides.
- * Omitted type → empty overrides (ephemeral mode). Unknown type → throw, so
- * the LLM gets a clear correction instead of silently running a generic agent.
+ *
+ * - Omitted type + non-empty registry → fall back to a configured role
+ *   ("general-purpose" if present, else the first available) instead of
+ *   running a nameless ephemeral agent. Relaxed from the earlier "throw when
+ *   agent_type omitted": the model habitually omits it, and a hard error just
+ *   turned every spawn into a failure. Falling back to a real role keeps the
+ *   tool-allowlist / system-prompt benefits without breaking the call.
+ * - Omitted type + empty registry → empty overrides (true ephemeral; nothing
+ *   to fall back to).
+ * - Unknown explicit type → throw, so the LLM gets a clear correction rather
+ *   than silently running a generic agent.
  */
 export function resolveAgentTypeOverrides(agentType, registry) {
-    if (!agentType)
-        return {};
-    const def = registry?.get(agentType);
+    const available = registry?.list().map((d) => d.name) ?? [];
+    let resolvedType = agentType;
+    if (!resolvedType) {
+        if (available.length === 0)
+            return {};
+        resolvedType = available.includes(DEFAULT_AGENT_TYPE) ? DEFAULT_AGENT_TYPE : available[0];
+    }
+    const def = registry?.get(resolvedType);
     if (!def) {
-        const available = registry?.list().map((d) => d.name).join(", ") || "(none defined)";
-        throw new Error(`unknown agent_type '${agentType}'. Available: ${available}`);
+        const list = available.join(", ") || "(none defined)";
+        throw new Error(`unknown agent_type '${resolvedType}'. Available: ${list}`);
     }
     return {
+        resolvedType,
         model: def.model,
         maxTurns: def.maxTurns,
         toolAllowlist: def.tools,
         appendSystemPrompt: def.systemPrompt,
     };
 }
+/**
+ * Render the "Available agent types" block injected into the Agent tool's
+ * description, listing the roles defined in .code-shell/agents/*.md so the
+ * model knows it can pass `agent_type` instead of hand-rolling an ad-hoc
+ * agent. Without this the model never sees the registry (it lives per-engine,
+ * not in the static tool def) and falls back to nameless ephemeral agents —
+ * see the Core A/B/C incident. Returns "" when no roles are defined, so the
+ * base description is left untouched.
+ */
+export function buildAgentTypesBlock(registry) {
+    const defs = registry?.list() ?? [];
+    if (defs.length === 0)
+        return "";
+    const lines = defs.map((d) => {
+        const tools = d.tools && d.tools.length > 0 ? d.tools.join(", ") : "all parent tools";
+        return `- ${d.name}: ${d.description} (tools: ${tools})`;
+    });
+    return [
+        "",
+        "Available agent types (pass one as `agent_type` to reuse its role, tool allowlist, and turn cap):",
+        ...lines,
+        "Pass the closest matching agent_type (e.g. read-only investigation → researcher/explorer, planning → planner, full multi-step work → general-purpose). If you omit agent_type it defaults to general-purpose (or the first available role) — passing an explicit one is preferred.",
+    ].join("\n");
+}
+/**
+ * Produce an Agent tool definition whose description ends with the live
+ * available-agent-types listing. Pure: takes the registry, returns a new def
+ * (the base `agentToolDef` const is never mutated). When no roles exist the
+ * base def is returned unchanged.
+ */
+export function agentToolDefWithTypes(registry) {
+    const block = buildAgentTypesBlock(registry);
+    if (!block)
+        return agentToolDef;
+    return { ...agentToolDef, description: agentToolDef.description + "\n" + block };
+}
 /**
  * Emit a sub-agent lifecycle event via the existing `notification` hook,
  * tagged with a `kind`. No-op when hooks are absent. Fire-and-forget: emit is
@@ -61,41 +114,25 @@ export function resolveAgentTypeOverrides(agentType, registry) {
 export function emitSubAgentHook(hooks, kind, payload) {
     void hooks?.emit("notification", { kind, ...payload });
 }
-/** Default per-sub-agent wall-clock timeout (5 minutes). */
-export const DEFAULT_SUBAGENT_TIMEOUT_MS = 5 * 60_000;
-/**
- * Run `work()` with a timeout. On expiry, calls `onTimeout` (to abort the
- * child) and rejects with a timeout error. The child's own abort handling
- * unwinds its resources.
- */
-export async function runWithTimeout(work, timeoutMs, onTimeout) {
-    let timer;
-    const timeout = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-            onTimeout();
-            reject(new Error(`Sub-agent timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
-    });
-    try {
-        return await Promise.race([work(), timeout]);
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
 export const agentToolDef = {
     name: "Agent",
-    description: "Launch a sub-agent to handle a complex task autonomously. " +
-        "The sub-agent has access to the same tools and runs independently. " +
-        "Use this for tasks that can be delegated, parallelized, or require deep exploration. " +
-        "Provide a clear, complete description of what the agent should do.\n\n" +
-        "When you launch multiple agents for independent work, send them in a single " +
-        "message with multiple tool uses so they run concurrently.\n\n" +
-        "You can optionally run agents in the background using the run_in_background " +
-        "parameter. When an agent runs in the background, you will be automatically " +
-        "notified when it completes — do NOT sleep, poll, or proactively check on its " +
-        "progress. Continue with other work or respond to the user instead.",
+    description: "Launch a sub-agent to handle a task in its own clean, isolated context. " +
+        "The sub-agent runs independently with access to the same tools, and its final " +
+        "report is the ONLY thing returned to you — it is stateless, so you cannot send " +
+        "follow-up messages. Write a complete, self-contained task description.\n\n" +
+        "PRIMARY USE — context isolation: when a task needs to read many files or run a " +
+        "broad investigation but you only need the conclusion, delegate it. The sub-agent " +
+        "absorbs the noisy intermediate output in its own context; you keep the answer, not " +
+        "the file dumps. This protects your main context from being flooded.\n\n" +
+        "DON'T use this for a quick lookup where you know the file/symbol and expect a few " +
+        "matches — use Read/Grep/Glob directly instead; spawning an agent wastes a turn.\n\n" +
+        "Parallel fan-out is the EXCEPTION: only launch several agents in one message when " +
+        "the work truly splits into independent pieces with no shared state. Prefer one " +
+        "well-scoped delegation over a swarm.\n\n" +
+        "You can optionally run an agent in the background using the run_in_background " +
+        "parameter. When it runs in the background, you will be automatically notified when " +
+        "it completes — do NOT sleep, poll, or proactively check on its progress. Continue " +
+        "with other work or respond to the user instead.",
     inputSchema: {
         type: "object",
         properties: {
@@ -109,7 +146,10 @@ export const agentToolDef = {
                 type: "string",
                 description: "Optional reusable role defined in .code-shell/agents/*.md (e.g. 'researcher'). " +
                     "Loads that role's model, tool allowlist, turn cap, and system prompt. " +
-                    "Omit to run an ad-hoc agent described entirely by 'prompt'.",
+                    "Disabled roles are not available. If you pass an unknown role you'll get " +
+                    "an error listing the currently available roles. " +
+                    "If omitted, defaults to a configured role (general-purpose or the first available); " +
+                    "with no roles configured it runs an ephemeral agent. Passing an explicit role is preferred.",
             },
             description: {
                 type: "string",
@@ -155,9 +195,9 @@ uiStream,
  * sub-agents.
  */
 streamOverride) {
-    const { agentId, name, description } = opts;
+    const { agentId, name, description, agentType } = opts;
     const startEndSink = uiStream ?? spawner.parentStream;
-    safeEmit(startEndSink, { type: "agent_start", agentId, name, description });
+    safeEmit(startEndSink, { type: "agent_start", agentId, name, description, agentType });
     emitSubAgentHook(opts.hooks, "subagent_start", { agentId, description });
     // `resetPlanMode` / `restorePlanMode` operated on a module-level singleton
     // that no longer exists. The child Engine is a fresh instance; plan-mode
@@ -165,7 +205,7 @@ streamOverride) {
     // instances (finalized in T6).
     const text = await spawner.spawn({ ...opts, streamOverride });
     const finalText = text || `Agent completed but produced no text output.`;
-    safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText });
+    safeEmit(startEndSink, { type: "agent_end", agentId, name, description, text: finalText, agentType });
     emitSubAgentHook(opts.hooks, "subagent_finish", { agentId, description, text: finalText });
     return finalText;
 }
@@ -218,7 +258,11 @@ export async function agentTool(args, ctx) {
         asyncAgentRegistry.register({
             agentId,
             name,
+            agentType: overrides.resolvedType,
             description,
+            // Tag with the spawning session so the parent Engine.run waits only on
+            // its own background agents (hasRunningForSession).
+            sessionId: ctx?.sessionId,
             status: "running",
             startedAt: Date.now(),
             abort: () => controller.abort(),
@@ -241,11 +285,13 @@ export async function agentTool(args, ctx) {
             agentId,
             name,
             description,
+            agentType: overrides.resolvedType,
             prompt,
             maxTurns,
             model: overrides.model,
             toolAllowlist: overrides.toolAllowlist,
             appendSystemPrompt: overrides.appendSystemPrompt,
+            readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
             hooks: ctx?.hooks,
             signal: controller.signal,
         }, parentStream, // uiStream: agent_start/end → main feed
@@ -338,31 +384,41 @@ export async function agentTool(args, ctx) {
         ].join("\n");
     }
     // ─── Synchronous path ──────────────────────────────────────────
-    // A timeout-capable controller: the timeout callback aborts the child, and
-    // a parent abort is forwarded to it too. Keeping the timeout OUTSIDE
-    // runSubAgent (and off the background path) avoids the background path's
-    // "abort means user-cancel → drop silently" semantics; here a timeout is a
-    // genuine error surfaced to the parent.
+    // No wall-clock timeout on the sub-agent lifecycle — that matches Claude
+    // Code / Codex, where a sub-agent (Task) is bounded by maxTurns + per-tool
+    // timeouts (Bash etc. carry their own) + parent/user abort, NOT by a global
+    // countdown that kills legitimate heavy work mid-task. The old
+    // runWithTimeout(5min) both (a) murdered a "read 40 files" agent at 5:00 and
+    // (b) raced with the normal completion path: the timeout aborted the child,
+    // the catch emitted agent_end{error}, AND the aborted child still let
+    // runSubAgent reach its line-280 agent_end{text} — two agent_end events for
+    // one agent, the later text one overwriting the error so a timed-out agent
+    // rendered as "done". Dropping the timeout removes the race entirely: a
+    // genuine spawn error throws BEFORE the success emit, so only the catch
+    // fires; a clean run emits agent_end{text} exactly once. (fix:
+    // subagent-timeout-double-agent-end)
     const syncController = new AbortController();
     const onParentAbort = () => syncController.abort();
     parentSignal?.addEventListener("abort", onParentAbort, { once: true });
     try {
-        return await runWithTimeout(() => runSubAgent(spawner, {
+        return await runSubAgent(spawner, {
             agentId,
             name,
             description,
+            agentType: overrides.resolvedType,
             prompt,
             maxTurns,
             model: overrides.model,
             toolAllowlist: overrides.toolAllowlist,
             appendSystemPrompt: overrides.appendSystemPrompt,
+            readOnlySession: overrides.resolvedType === "researcher" || overrides.resolvedType === "explorer",
             hooks: ctx?.hooks,
             signal: syncController.signal,
-        }), DEFAULT_SUBAGENT_TIMEOUT_MS, () => syncController.abort());
+        });
     }
     catch (err) {
         emitSubAgentHook(ctx?.hooks, "subagent_error", { agentId, description, error: err.message });
-        safeEmit(parentStream, { type: "agent_end", agentId, name, description, error: err.message });
+        safeEmit(parentStream, { type: "agent_end", agentId, name, description, error: err.message, agentType: overrides.resolvedType });
         if (parentSignal?.aborted)
             return "Agent was aborted.";
         return `Agent error: ${err.message}`;