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

package/dist/agent/agent-definition-registry.d.ts

@@ -0,0 +1,14 @@
+import { type AgentDefinition } from "./agent-definition.js";
+/**
+ * Loads reusable sub-agent role definitions from a directory of `*.md` files.
+ * Non-recursive. Malformed files are skipped with a warning rather than
+ * failing the whole load — one bad role file must not break the agent system.
+ */
+export declare class AgentDefinitionRegistry {
+    private defs;
+    readonly warnings: string[];
+    static loadFromDir(dir: string): AgentDefinitionRegistry;
+    has(name: string): boolean;
+    get(name: string): AgentDefinition | undefined;
+    list(): AgentDefinition[];
+}

package/dist/agent/agent-definition-registry.js

@@ -0,0 +1,45 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseAgentDefinition } from "./agent-definition.js";
+/**
+ * Loads reusable sub-agent role definitions from a directory of `*.md` files.
+ * Non-recursive. Malformed files are skipped with a warning rather than
+ * failing the whole load — one bad role file must not break the agent system.
+ */
+export class AgentDefinitionRegistry {
+    defs = new Map();
+    warnings = [];
+    static loadFromDir(dir) {
+        const reg = new AgentDefinitionRegistry();
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            return reg;
+        for (const entry of readdirSync(dir).sort()) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const full = join(dir, entry);
+            try {
+                if (!statSync(full).isFile())
+                    continue;
+                const def = parseAgentDefinition(readFileSync(full, "utf8"), entry);
+                if (reg.defs.has(def.name)) {
+                    reg.warnings.push(`${entry}: duplicate agent name '${def.name}' ignored (first definition wins)`);
+                    continue;
+                }
+                reg.defs.set(def.name, def);
+            }
+            catch (err) {
+                reg.warnings.push(`${entry}: ${err.message}`);
+            }
+        }
+        return reg;
+    }
+    has(name) {
+        return this.defs.has(name);
+    }
+    get(name) {
+        return this.defs.get(name);
+    }
+    list() {
+        return [...this.defs.values()];
+    }
+}

package/dist/agent/agent-definition.d.ts

@@ -0,0 +1,20 @@
+/** A reusable sub-agent role, loaded from a Markdown file. */
+export interface AgentDefinition {
+    /** Unique role key, e.g. "researcher". Matched against Agent({ agent_type }). */
+    name: string;
+    /** Human-facing summary of when to use this role. */
+    description: string;
+    /** Optional ModelPool key (e.g. "flash"). Undefined → inherit parent model. */
+    model?: string;
+    /** Optional turn cap for this role. Undefined → caller/default decides. */
+    maxTurns?: number;
+    /** Optional tool allowlist. Undefined → inherit parent's full tool set. */
+    tools?: string[];
+    /** Markdown body — becomes the child Engine's appendSystemPrompt. */
+    systemPrompt: string;
+}
+/**
+ * Parse a Markdown agent-definition file (YAML frontmatter + body).
+ * Pure: no filesystem access. `sourceName` is only used in error messages.
+ */
+export declare function parseAgentDefinition(raw: string, sourceName: string): AgentDefinition;

package/dist/agent/agent-definition.js

@@ -0,0 +1,38 @@
+import { parse as parseYaml } from "yaml";
+/**
+ * Parse a Markdown agent-definition file (YAML frontmatter + body).
+ * Pure: no filesystem access. `sourceName` is only used in error messages.
+ */
+export function parseAgentDefinition(raw, sourceName) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw.trim());
+    if (!match) {
+        throw new Error(`${sourceName}: missing YAML frontmatter (expected leading '---' block)`);
+    }
+    const [, yamlSrc, body] = match;
+    let fm;
+    try {
+        fm = (parseYaml(yamlSrc) ?? {});
+    }
+    catch (err) {
+        throw new Error(`${sourceName}: invalid YAML frontmatter — ${err.message}`, { cause: err });
+    }
+    if (typeof fm.name !== "string" || fm.name.trim().length === 0) {
+        throw new Error(`${sourceName}: frontmatter must include a non-empty 'name'`);
+    }
+    if (typeof fm.description !== "string" || fm.description.trim().length === 0) {
+        throw new Error(`${sourceName}: frontmatter must include a non-empty 'description'`);
+    }
+    const def = {
+        name: fm.name.trim(),
+        description: fm.description.trim(),
+        systemPrompt: body.trim(),
+    };
+    if (typeof fm.model === "string" && fm.model.trim())
+        def.model = fm.model.trim();
+    if (typeof fm.maxTurns === "number")
+        def.maxTurns = fm.maxTurns;
+    if (Array.isArray(fm.tools)) {
+        def.tools = fm.tools.filter((t) => typeof t === "string");
+    }
+    return def;
+}

package/dist/cli/agent-server-stdio.js

@@ -40,7 +40,9 @@ import { CostTracker } from "../cost-tracker.js";
 // ─── Read base config from environment / settings ─────────────────
 const cwd = process.env.AGENT_CWD ?? process.cwd();
 // Load settings once to derive llm config for the seed engine.
-const settingsManager = new SettingsManager(cwd);
+// Desktop is a host application: read the full disk hierarchy (incl. the
+// user's ~/.code-shell). The SDK default 'project' would skip user config.
+const settingsManager = new SettingsManager(cwd, "full");
 const settings = settingsManager.get();
 const llmConfig = {
     provider: settings.model.provider,
@@ -54,6 +56,7 @@ const llmConfig = {
 const seedEngine = new Engine({
     llm: llmConfig,
     cwd,
+    settingsScope: "full",
     // No runtime — Engine.populateModelPoolFromSettings() runs in ctor.
 });
 // ─── Step 2: extract shared resources ────────────────────────────
@@ -93,6 +96,8 @@ const chatManager = new ChatSessionManager({
         llm: resolvedLlmConfig,
         cwd,
         runtime,
+        // Inherit full scope so spawned subagents read user config too.
+        settingsScope: "full",
         // Per-session overrides from the protocol request
         permissionMode: slice.permissionMode,
         preset: slice.preset,

package/dist/engine/engine.d.ts

@@ -10,10 +10,12 @@ import type { HookHandler } from "../hooks/registry.js";
 import { SessionManager } from "../session/session-manager.js";
 import type { CostStateStore } from "./cost-store.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
+import { type SettingsScope } from "../settings/manager.js";
 import type { ToolContext } from "../tool-system/context.js";
 import { type SandboxConfig } from "../tool-system/sandbox/index.js";
 import { type AgentPresetName } from "../preset/index.js";
 import { ModelPool, type ModelEntry } from "../llm/model-pool.js";
+import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { EngineRuntime } from "./runtime.js";
 export interface EngineConfig {
     llm: LLMConfig;
@@ -68,6 +70,16 @@ export interface EngineConfig {
      * work unchanged — T11 will migrate them.
      */
     runtime?: EngineRuntime;
+    /**
+     * Which disk config layers this Engine may read. Defaults to 'project' —
+     * the safe default: a library/SDK embedding never silently inherits the
+     * host user's personal ~/.code-shell config (keys, models, MCP, hooks); it
+     * only reads the project-level ${cwd}/.code-shell that travels with a repo.
+     * Host-terminal entrypoints (TUI/desktop/CLI) pass 'full' to restore the
+     * managed+user+project+local behavior. 'isolated' reads no disk at all.
+     * Subagents inherit the parent Engine's scope. See SettingsScope.
+     */
+    settingsScope?: SettingsScope;
 }
 export interface EngineHookConfig {
     event: HookEventName;
@@ -82,6 +94,27 @@ export interface EngineResult {
     turnCount: number;
     usage: TokenUsage;
 }
+/**
+ * Resolve the LLM config for a spawned child Engine.
+ * - `modelKey` set + present in pool → that model's config (over parent base).
+ * - otherwise (no key, no pool, or key miss) → the parent's llm unchanged.
+ * Key miss is a soft fallback, NOT an error: a stale agent definition must not
+ * crash the spawn.
+ */
+export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
+/** Load reusable sub-agent role definitions from <cwd>/.code-shell/agents. */
+export declare function loadAgentDefinitionsForCwd(cwd: string): AgentDefinitionRegistry;
+/**
+ * Compute a child Engine's tool scope.
+ * - `allowlist` set → child enabled = allowlist minus nested-agent tools
+ *   (a per-role tool whitelist, e.g. a read-only researcher).
+ * - `allowlist` undefined → inherit parent enabled/disabled, always with the
+ *   nested-agent tools forced into `disabled` (no grandchildren).
+ */
+export declare function resolveChildToolScope(allowlist: string[] | undefined, parentDisabled: string[] | undefined, parentEnabled: string[] | undefined): {
+    enabled?: string[];
+    disabled: string[];
+};
 export declare class Engine {
     private config;
     private readonly preset;
@@ -90,6 +123,8 @@ export declare class Engine {
     private sessionManager;
     private mcpManager;
     private modelPool;
+    /** Memoized sub-agent role registry, keyed by the cwd it was loaded from. */
+    private agentDefsCache?;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     readonly runtime: EngineRuntime | null;
     /** Active permission mode for this Engine instance. */
@@ -279,6 +314,12 @@ export declare class Engine {
      * Also syncs permissionMode to keep both fields consistent.
      */
     setPlanMode(value: boolean): void;
+    /**
+     * Sub-agent role registry for the given cwd, memoized per-cwd so the
+     * directory is read once rather than every turn. A new cwd (e.g. via
+     * run({ cwd })) reloads.
+     */
+    private getAgentDefinitions;
     /**
      * Build a base ToolContext for this Engine. Used by run() (which then
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
@@ -286,10 +327,15 @@ export declare class Engine {
      */
     buildToolContext(): ToolContext;
     /**
-     * Read settings.disabledSkills. Sub-agents skip this for the same
-     * reason they skip settings.hooks / plugin hooks (registerSettingsHooks
-     * at ~line 237): they run with a minimal surface area. Defaults to []
-     * so callers don't have to null-check.
+     * Read settings.disabledSkills + settings.disabledPlugins in a single
+     * pass. Sub-agents skip both for the same reason they skip
+     * settings.hooks / plugin hooks (registerSettingsHooks at ~line 237):
+     * they run with a minimal surface area. Defaults to [] for both
+     * fields so callers don't have to null-check.
+     *
+     * Combined read avoids drift if settings change between two separate
+     * reads — the prompt composer and the tool context will always see
+     * the same snapshot.
      */
-    private readDisabledSkills;
+    private readDisabledLists;
 }

package/dist/engine/engine.js

@@ -27,6 +27,7 @@ import { FileHistory } from "../session/file-history.js";
 import { defaultSandboxConfig, resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
 import { resolveAgentPreset, resolveBuiltinToolNames, } from "../preset/index.js";
 import { ModelPool } from "../llm/model-pool.js";
+import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { ProviderCatalog } from "../llm/provider-catalog.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
 import { detectProviderFromApiKey, buildModelPool, } from "../onboarding.js";
@@ -37,6 +38,44 @@ import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+/**
+ * Resolve the LLM config for a spawned child Engine.
+ * - `modelKey` set + present in pool → that model's config (over parent base).
+ * - otherwise (no key, no pool, or key miss) → the parent's llm unchanged.
+ * Key miss is a soft fallback, NOT an error: a stale agent definition must not
+ * crash the spawn.
+ */
+export function resolveChildLlm(modelKey, pool, parentLlm) {
+    if (modelKey && pool?.has(modelKey)) {
+        const resolved = pool.resolveLLMConfig(modelKey, parentLlm);
+        if (resolved)
+            return resolved;
+    }
+    return parentLlm;
+}
+/** Load reusable sub-agent role definitions from <cwd>/.code-shell/agents. */
+export function loadAgentDefinitionsForCwd(cwd) {
+    return AgentDefinitionRegistry.loadFromDir(`${cwd}/.code-shell/agents`);
+}
+const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel"];
+/**
+ * Compute a child Engine's tool scope.
+ * - `allowlist` set → child enabled = allowlist minus nested-agent tools
+ *   (a per-role tool whitelist, e.g. a read-only researcher).
+ * - `allowlist` undefined → inherit parent enabled/disabled, always with the
+ *   nested-agent tools forced into `disabled` (no grandchildren).
+ */
+export function resolveChildToolScope(allowlist, parentDisabled, parentEnabled) {
+    if (allowlist) {
+        return {
+            enabled: allowlist.filter((t) => !NESTED_AGENT_TOOLS.includes(t)),
+            disabled: [...NESTED_AGENT_TOOLS],
+        };
+    }
+    const disabled = Array.from(new Set([...(parentDisabled ?? []), ...NESTED_AGENT_TOOLS]));
+    const enabled = parentEnabled?.filter((t) => !NESTED_AGENT_TOOLS.includes(t));
+    return { enabled, disabled };
+}
 export class Engine {
     config;
     preset;
@@ -45,6 +84,8 @@ export class Engine {
     sessionManager;
     mcpManager;
     modelPool;
+    /** Memoized sub-agent role registry, keyed by the cwd it was loaded from. */
+    agentDefsCache;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     runtime;
     /** Active permission mode for this Engine instance. */
@@ -201,24 +242,31 @@ export class Engine {
                 // We then switch the pool and write the resolved entry's credentials
                 // into config.llm, so the first run() uses the right endpoint instead
                 // of whatever env-derived fallback repl.ts seeded earlier.
-                const activeKey = settings.activeKey;
-                let match;
-                if (activeKey) {
-                    match = settings.models.find((m) => m.key === activeKey);
-                }
-                if (!match) {
-                    const currentModel = this.config.llm.model;
-                    // OpenRouter stores entries as "provider/model-name"; the top-level
-                    // settings.model.name is just "model-name". Match either form.
-                    match = settings.models.find((m) => m.model === currentModel ||
-                        (currentModel && m.model?.endsWith(`/${currentModel}`)));
-                }
-                if (match) {
-                    const entry = this.modelPool.switch(match.key);
-                    this.config = {
-                        ...this.config,
-                        llm: this.modelPool.toLLMConfig(entry, this.config.llm),
-                    };
+                // Sub-agents skip the activeKey resync: their llm is chosen by the
+                // parent's resolveChildLlm (per-role model routing). activeKey is the
+                // *user's* current UI model selection and must not clobber a child's
+                // routed model — without this guard a role's `model: flash` is silently
+                // overridden back to whatever the user has active in the foreground.
+                if (this.config.isSubAgent !== true) {
+                    const activeKey = settings.activeKey;
+                    let match;
+                    if (activeKey) {
+                        match = settings.models.find((m) => m.key === activeKey);
+                    }
+                    if (!match) {
+                        const currentModel = this.config.llm.model;
+                        // OpenRouter stores entries as "provider/model-name"; the top-level
+                        // settings.model.name is just "model-name". Match either form.
+                        match = settings.models.find((m) => m.model === currentModel ||
+                            (currentModel && m.model?.endsWith(`/${currentModel}`)));
+                    }
+                    if (match) {
+                        const entry = this.modelPool.switch(match.key);
+                        this.config = {
+                            ...this.config,
+                            llm: this.modelPool.toLLMConfig(entry, this.config.llm),
+                        };
+                    }
                 }
             }
             else if (this.config.llm.apiKey) {
@@ -388,29 +436,27 @@ export class Engine {
                 // background process explosion), and the sid / approval / dock
                 // model assumes a flat parent→children hierarchy. Layered with a
                 // runtime check in agent.ts as defense-in-depth.
-                const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel"];
-                const childDisabled = Array.from(new Set([
-                    ...(this.config.disabledBuiltinTools ?? []),
-                    ...NESTED_AGENT_TOOLS,
-                ]));
-                // If enabledBuiltinTools is set (explicit allow-list mode), strip
-                // the nested-agent tools from it too so the disable above isn't
-                // contradicted by an explicit allow.
-                const childEnabled = this.config.enabledBuiltinTools?.filter((t) => !NESTED_AGENT_TOOLS.includes(t));
+                const { enabled: childEnabled, disabled: childDisabled } = resolveChildToolScope(req.toolAllowlist, this.config.disabledBuiltinTools, this.config.enabledBuiltinTools);
+                const childLlm = resolveChildLlm(req.model, this.modelPool, this.config.llm);
                 const child = new Engine({
-                    llm: { ...this.config.llm, retryMaxAttempts: 2 },
+                    llm: { ...childLlm, retryMaxAttempts: 2 },
                     cwd,
                     permissionMode: this.config.permissionMode,
                     preset: this.preset.name,
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
                     customSystemPrompt: this.config.customSystemPrompt,
-                    appendSystemPrompt: this.config.appendSystemPrompt,
+                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt]
+                        .filter(Boolean)
+                        .join("\n\n") || undefined,
                     maxTurns: req.maxTurns,
                     maxContextTokens: this.config.maxContextTokens ?? 200_000,
                     sessionStorageDir: this.config.sessionStorageDir,
                     headless: this.config.headless,
                     sandbox: this.config.sandbox,
+                    // Subagents inherit the parent's scope: a child runs in the same
+                    // cwd/session, so it should see the same config layers the parent did.
+                    settingsScope: this.config.settingsScope ?? "project",
                     isSubAgent: true,
                 });
                 // Where the spawned child Engine's stream events go. AgentTool's
@@ -470,6 +516,7 @@ export class Engine {
         const toolCtx = {
             ...this.buildToolContext(),
             subAgentSpawner,
+            agentDefinitions: this.getAgentDefinitions(cwd),
             sandbox: sandboxBackend,
             cwd,
             // TodoWrite reads this to push task_update events independently
@@ -715,13 +762,15 @@ export class Engine {
                 maxTokens: this.resolveMaxContextTokens(),
             });
             this.lastContextManager = contextManager;
+            const { disabledSkills, disabledPlugins } = this.readDisabledLists();
             const promptComposer = new PromptComposer({
                 cwd,
                 model: this.config.llm.model,
                 preset: this.preset,
                 customSystemPrompt: this.config.customSystemPrompt,
                 appendSystemPrompt: this.config.appendSystemPrompt,
-                disabledSkills: this.readDisabledSkills(),
+                disabledSkills,
+                disabledPlugins,
             });
             // Connect MCP servers (if configured and not already connected).
             // B1: prefer the Runtime-owned MCPManager so all sessions in a
@@ -1305,7 +1354,7 @@ export class Engine {
     }
     getSettingsManager() {
         if (!this.settingsManager) {
-            this.settingsManager = new SettingsManager(this.config.cwd);
+            this.settingsManager = new SettingsManager(this.config.cwd, this.config.settingsScope ?? "project");
         }
         return this.settingsManager;
     }
@@ -1357,7 +1406,7 @@ export class Engine {
             rules.push({ tool: "Bash", decision: "allow" });
         }
         try {
-            const settingsManager = new SettingsManager(cwd);
+            const settingsManager = new SettingsManager(cwd, this.config.settingsScope ?? "project");
             const settings = settingsManager.get();
             if (settings.permissions?.rules?.length) {
                 rules.unshift(...settings.permissions.rules);
@@ -1428,12 +1477,24 @@ export class Engine {
             this.planMode = value;
         }
     }
+    /**
+     * Sub-agent role registry for the given cwd, memoized per-cwd so the
+     * directory is read once rather than every turn. A new cwd (e.g. via
+     * run({ cwd })) reloads.
+     */
+    getAgentDefinitions(cwd) {
+        if (this.agentDefsCache?.cwd !== cwd) {
+            this.agentDefsCache = { cwd, reg: loadAgentDefinitionsForCwd(cwd) };
+        }
+        return this.agentDefsCache.reg;
+    }
     /**
      * Build a base ToolContext for this Engine. Used by run() (which then
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
     buildToolContext() {
+        const { disabledSkills, disabledPlugins } = this.readDisabledLists();
         return {
             cwd: this.config.cwd ?? process.cwd(),
             llmConfig: this.config.llm,
@@ -1444,24 +1505,34 @@ export class Engine {
             hooks: this.hooks,
             planMode: this.planMode,
             engine: this,
-            disabledSkills: this.readDisabledSkills(),
+            disabledSkills,
+            disabledPlugins,
         };
     }
     /**
-     * Read settings.disabledSkills. Sub-agents skip this for the same
-     * reason they skip settings.hooks / plugin hooks (registerSettingsHooks
-     * at ~line 237): they run with a minimal surface area. Defaults to []
-     * so callers don't have to null-check.
+     * Read settings.disabledSkills + settings.disabledPlugins in a single
+     * pass. Sub-agents skip both for the same reason they skip
+     * settings.hooks / plugin hooks (registerSettingsHooks at ~line 237):
+     * they run with a minimal surface area. Defaults to [] for both
+     * fields so callers don't have to null-check.
+     *
+     * Combined read avoids drift if settings change between two separate
+     * reads — the prompt composer and the tool context will always see
+     * the same snapshot.
      */
-    readDisabledSkills() {
-        if (this.config.isSubAgent === true)
-            return [];
+    readDisabledLists() {
+        if (this.config.isSubAgent === true) {
+            return { disabledSkills: [], disabledPlugins: [] };
+        }
         try {
             const settings = this.getSettingsManager().get();
-            return settings.disabledSkills ?? [];
+            return {
+                disabledSkills: settings.disabledSkills ?? [],
+                disabledPlugins: settings.disabledPlugins ?? [],
+            };
         }
         catch {
-            return [];
+            return { disabledSkills: [], disabledPlugins: [] };
         }
     }
 }

package/dist/index.d.ts

@@ -72,7 +72,7 @@ export type { IterateConfig, IterateResult, IterateSubject, IterateFormat, Itera
 export { RunManager, type RunManagerConfig, type RunStore, FileRunStore, RunQueue, EngineRunner, type EngineRunnerConfig, type RunExecutionHandle, type RunExecutor, type CustomToolEntry, RunApprovalBackend, createRunAskUserFn, type RunLifecycleHooks, CheckpointWriter, ArtifactTracker, RunLock, Heartbeat, NoopEvaluator, CompositeEvaluator, type Evaluator, type EvaluatorResult, type EvaluatorContext, type RunStatus, type RunSnapshot, type RunEvent, type RunCheckpoint, type RunApproval, type RunArtifactRef, type SubmitRunInput, type ResumeRunInput, type ListRunsQuery, type RunStreamEvent, type RunStreamCallback, type DetachFn, VALID_TRANSITIONS, createRunManager, type CreateRunManagerOptions, } from "./run/index.js";
 export { defineProduct, type ProductDefinition, type ProductPreset, type ProductAdapter, type ProductContract, type CustomTool, type ProductRuntimeOptions, type ProductInstance, } from "./product/index.js";
 export { logger } from "./logging/logger.js";
-export { SettingsManager } from "./settings/manager.js";
+export { SettingsManager, type SettingsScope } from "./settings/manager.js";
 export { SettingsSchema, validateSettings } from "./settings/schema.js";
 export { getSessionId, switchSession, getOriginalCwd, setOriginalCwd, getProjectRoot, setProjectRoot, getCwdState, getIsInteractive, updateLastInteractionTime, flushInteractionTime, markScrollActivity, type AttributedCounter, type ChannelEntry, } from "./state.js";
 export { getGraphemeSegmenter, firstGrapheme, lastGrapheme, getWordSegmenter, getRelativeTimeFormat, getTimeZone, getSystemLocaleLanguage, } from "./utils/intl.js";

package/dist/prompt/composer.d.ts

@@ -23,6 +23,12 @@ export interface ComposerOptions {
      * dispatch — see scanSkills(opts.disabledSkills) and skillTool.
      */
     disabledSkills?: string[];
+    /**
+     * Plugin names the user has totally disabled. Coarser knob than
+     * disabledSkills — every skill whose namespaced name starts with
+     * `${pluginName}:` is filtered. See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins?: string[];
 }
 export declare class PromptComposer {
     private readonly options;

package/dist/prompt/composer.js

@@ -136,6 +136,7 @@ export class PromptComposer {
             compute: () => {
                 const skills = scanSkills(this.options.cwd, {
                     disabledSkills: this.options.disabledSkills,
+                    disabledPlugins: this.options.disabledPlugins,
                 });
                 return buildSkillListing(skills);
             },

package/dist/settings/manager.d.ts

@@ -5,11 +5,22 @@
  */
 import { type ValidatedSettings } from "./schema.js";
 export type SettingsSourceName = "managed" | "user" | "project" | "local" | "flag";
+/**
+ * Which disk layers a SettingsManager is allowed to read.
+ *   'full'     — managed + user (~/.code-shell) + project + local (host terminal entrypoints)
+ *   'project'  — project + local only (${cwd}/.code-shell); never the host user dir. [default]
+ *   'isolated' — no disk layers at all; only explicit flag overrides.
+ * Flag overrides always apply regardless of scope. Default is 'project' so a
+ * codeshell library/SDK embedding never silently inherits the host user's
+ * personal ~/.code-shell config (keys, models, MCP servers, hooks).
+ */
+export type SettingsScope = "isolated" | "project" | "full";
 export declare class SettingsManager {
     private readonly cwd;
+    private readonly scope;
     private sources;
     private merged;
-    constructor(cwd?: string);
+    constructor(cwd?: string, scope?: SettingsScope);
     /**
      * Load settings from all sources.
      */

package/dist/settings/manager.js

@@ -20,29 +20,39 @@ function userHome() {
 }
 export class SettingsManager {
     cwd;
+    scope;
     sources = [];
     merged = null;
-    constructor(cwd = process.cwd()) {
+    constructor(cwd = process.cwd(), scope = "project") {
         this.cwd = cwd;
+        this.scope = scope;
     }
     /**
      * Load settings from all sources.
      */
     load(flagOverrides) {
         this.sources = [];
-        // 1. Managed (lowest priority)
-        this.loadJsonFile(join(userHome(), ".code-shell", "settings.managed.json"), "managed", 0);
-        // 2. User — only ~/.code-shell/. We used to also read ~/.claude/settings.json
-        // for "zero-migration from Claude Code", but Claude Code's schema diverges
-        // (e.g. `model` is a string there, an object here). Merging caused boot
-        // crashes on machines that had Claude Code installed but never ran us.
-        // File-level compat (CLAUDE.md, .claude/skills/) is kept elsewhere — only
-        // the settings.json read is dropped.
-        this.loadJsonFile(join(userHome(), ".code-shell", "settings.json"), "user", 1);
-        // 3. Project
-        this.loadJsonFile(join(this.cwd, ".code-shell", "settings.json"), "project", 2);
-        // 4. Local
-        this.loadJsonFile(join(this.cwd, ".code-shell", "settings.local.json"), "local", 3);
+        // Scope gates which disk layers we read. 'full' reads the host user dir
+        // (~/.code-shell); 'project' and 'isolated' never do. See SettingsScope.
+        const readUser = this.scope === "full";
+        const readProject = this.scope !== "isolated";
+        if (readUser) {
+            // 1. Managed (lowest priority)
+            this.loadJsonFile(join(userHome(), ".code-shell", "settings.managed.json"), "managed", 0);
+            // 2. User — only ~/.code-shell/. We used to also read ~/.claude/settings.json
+            // for "zero-migration from Claude Code", but Claude Code's schema diverges
+            // (e.g. `model` is a string there, an object here). Merging caused boot
+            // crashes on machines that had Claude Code installed but never ran us.
+            // File-level compat (CLAUDE.md, .claude/skills/) is kept elsewhere — only
+            // the settings.json read is dropped.
+            this.loadJsonFile(join(userHome(), ".code-shell", "settings.json"), "user", 1);
+        }
+        if (readProject) {
+            // 3. Project
+            this.loadJsonFile(join(this.cwd, ".code-shell", "settings.json"), "project", 2);
+            // 4. Local
+            this.loadJsonFile(join(this.cwd, ".code-shell", "settings.local.json"), "local", 3);
+        }
         // 5. CLI flags (highest priority)
         if (flagOverrides && Object.keys(flagOverrides).length > 0) {
             this.sources.push({ name: "flag", priority: 4, data: flagOverrides });
@@ -54,9 +64,10 @@ export class SettingsManager {
         // Auto-migrate legacy models[] in the user settings file. Runs directly
         // on the user-scope file (not the merged result), because the merge
         // collapses provenance and the migration needs to write back to a
-        // single physical file.
+        // single physical file. Gated on readUser: under non-full scope we must
+        // not read — let alone rewrite — the host's ~/.code-shell/settings.json.
         const userPath = join(userHome(), ".code-shell", "settings.json");
-        if (existsSync(userPath)) {
+        if (readUser && existsSync(userPath)) {
             try {
                 const userRaw = JSON.parse(readFileSync(userPath, "utf-8"));
                 const result = migrateModels({

package/dist/settings/manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settings/manager.test.js

@@ -0,0 +1,73 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { SettingsManager } from "./manager.js";
+/**
+ * Scope isolation tests. We point HOME at a temp dir (userHome() reads
+ * process.env.HOME first) and use a separate temp cwd, then seed each of the
+ * four disk layers with a uniquely-named mcpServers entry. mcpServers is a
+ * record merged key-by-key, so every layer that was actually read leaves its
+ * own key in the merged result — letting us detect which layers were read
+ * (unlike arrays, which deep-merge replaces wholesale).
+ */
+describe("SettingsManager scope", () => {
+    let home;
+    let cwd;
+    let prevHome;
+    function serverFor(tag) {
+        return { [tag]: { name: tag, command: "echo", transport: "stdio" } };
+    }
+    function writeSettings(dir, file, tag) {
+        mkdirSync(join(dir, ".code-shell"), { recursive: true });
+        writeFileSync(join(dir, ".code-shell", file), JSON.stringify({ mcpServers: serverFor(tag) }), "utf-8");
+    }
+    function layersIn(sm) {
+        return Object.keys(sm.get().mcpServers ?? {}).sort();
+    }
+    beforeEach(() => {
+        prevHome = process.env.HOME;
+        home = mkdtempSync(join(tmpdir(), "cs-home-"));
+        cwd = mkdtempSync(join(tmpdir(), "cs-cwd-"));
+        process.env.HOME = home;
+        writeSettings(home, "settings.managed.json", "MANAGED");
+        writeSettings(home, "settings.json", "USER");
+        writeSettings(cwd, "settings.json", "PROJECT");
+        writeSettings(cwd, "settings.local.json", "LOCAL");
+    });
+    afterEach(() => {
+        process.env.HOME = prevHome;
+        rmSync(home, { recursive: true, force: true });
+        rmSync(cwd, { recursive: true, force: true });
+    });
+    test("full reads all four disk layers", () => {
+        expect(layersIn(new SettingsManager(cwd, "full"))).toEqual([
+            "LOCAL",
+            "MANAGED",
+            "PROJECT",
+            "USER",
+        ]);
+    });
+    test("project (default) reads project+local, never user/managed", () => {
+        expect(layersIn(new SettingsManager(cwd, "project"))).toEqual(["LOCAL", "PROJECT"]);
+    });
+    test("default scope is project", () => {
+        expect(layersIn(new SettingsManager(cwd))).toEqual(["LOCAL", "PROJECT"]);
+    });
+    test("isolated reads no disk layers", () => {
+        expect(layersIn(new SettingsManager(cwd, "isolated"))).toEqual([]);
+    });
+    test("flag overrides apply even under isolated", () => {
+        const sm = new SettingsManager(cwd, "isolated");
+        sm.load({ mcpServers: serverFor("FLAG") });
+        expect(layersIn(sm)).toEqual(["FLAG"]);
+    });
+    test("non-full scope never triggers user-file model migration write-back", () => {
+        // Legacy models[] in the user file would normally be migrated (and the
+        // file rewritten with a .bak). Under project/isolated we must not touch
+        // the user file at all.
+        writeFileSync(join(home, ".code-shell", "settings.json"), JSON.stringify({ models: [{ id: "legacy", provider: "x" }] }), "utf-8");
+        new SettingsManager(cwd, "project").get();
+        expect(existsSync(join(home, ".code-shell", "settings.json.bak"))).toBe(false);
+    });
+});

package/dist/settings/schema.d.ts

@@ -257,6 +257,13 @@ export declare const SettingsSchema: z.ZodObject<{
      * tool both see the filtered set — see scanSkills(opts).
      */
     disabledSkills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Plugin-level total switch: every skill whose namespaced name
+     * starts with `${pluginName}:` is filtered. Coarser knob than
+     * disabledSkills; both are honored simultaneously. Bare plugin
+     * names (no colon suffix). See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
         scanDirs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -661,6 +668,13 @@ export declare const SettingsSchema: z.ZodObject<{
      * tool both see the filtered set — see scanSkills(opts).
      */
     disabledSkills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Plugin-level total switch: every skill whose namespaced name
+     * starts with `${pluginName}:` is filtered. Coarser knob than
+     * disabledSkills; both are honored simultaneously. Bare plugin
+     * names (no colon suffix). See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
         scanDirs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -1065,6 +1079,13 @@ export declare const SettingsSchema: z.ZodObject<{
      * tool both see the filtered set — see scanSkills(opts).
      */
     disabledSkills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Plugin-level total switch: every skill whose namespaced name
+     * starts with `${pluginName}:` is filtered. Coarser knob than
+     * disabledSkills; both are honored simultaneously. Bare plugin
+     * names (no colon suffix). See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
         scanDirs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;

package/dist/settings/schema.js

@@ -155,6 +155,13 @@ export const SettingsSchema = z
      * tool both see the filtered set — see scanSkills(opts).
      */
     disabledSkills: z.array(z.string()).default([]),
+    /**
+     * Plugin-level total switch: every skill whose namespaced name
+     * starts with `${pluginName}:` is filtered. Coarser knob than
+     * disabledSkills; both are honored simultaneously. Bare plugin
+     * names (no colon suffix). See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins: z.array(z.string()).default([]),
     instructions: z
         .object({
         fileName: z.string().default("CODESHELL.md"),

package/dist/skills/scanner.d.ts

@@ -17,15 +17,22 @@ export interface SkillDefinition {
     source: "project" | "user" | "plugin";
 }
 /**
- * Options accepted by scanSkills. The disabled-skill filter is applied
- * after the memoized scan returns so the cache stays warm across
- * different filter values — changing `settings.disabledSkills` should
- * never force a re-scan. Names in `disabledSkills` must match the
- * SkillDefinition.name exactly, including any "<plugin>:" prefix —
- * see scanInstalledPlugins() at line ~168 for namespace construction.
+ * Options accepted by scanSkills. Both filters are applied after the
+ * memoized scan returns so the cache stays warm across different filter
+ * values — changing `settings.disabledSkills` or `settings.disabledPlugins`
+ * should never force a re-scan.
+ *
+ * - `disabledSkills` names must match the SkillDefinition.name exactly,
+ *   including any "<plugin>:" prefix — see scanInstalledPlugins() at
+ *   line ~168 for namespace construction.
+ * - `disabledPlugins` names are bare plugin names (no colon suffix).
+ *   Every skill whose name starts with `${pluginName}:` is filtered.
+ *   This is the coarse "plugin total switch" knob; `disabledSkills` is
+ *   the per-skill knob.
  */
 export interface ScanSkillsOptions {
     disabledSkills?: string[];
+    disabledPlugins?: string[];
 }
 export declare function scanSkills(cwd: string, opts?: ScanSkillsOptions): SkillDefinition[];
 export declare function invalidateSkillCache(): void;

package/dist/skills/scanner.js

@@ -160,11 +160,30 @@ function installedPluginsMtime() {
 const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}`);
 export function scanSkills(cwd, opts) {
     const all = memoized(cwd);
-    const disabled = opts?.disabledSkills;
-    if (!disabled || disabled.length === 0)
+    const disabledSkills = opts?.disabledSkills;
+    const disabledPlugins = opts?.disabledPlugins;
+    const hasSkillFilter = disabledSkills && disabledSkills.length > 0;
+    const hasPluginFilter = disabledPlugins && disabledPlugins.length > 0;
+    if (!hasSkillFilter && !hasPluginFilter)
         return all;
-    const set = new Set(disabled);
-    return all.filter((s) => !set.has(s.name));
+    const skillSet = hasSkillFilter ? new Set(disabledSkills) : null;
+    const pluginSet = hasPluginFilter ? new Set(disabledPlugins) : null;
+    return all.filter((s) => {
+        if (skillSet && skillSet.has(s.name))
+            return false;
+        if (pluginSet) {
+            // Use indexOf, not split — skill names may theoretically contain
+            // more colons after the first; the namespace boundary is the
+            // first ":" only.
+            const colon = s.name.indexOf(":");
+            if (colon > 0) {
+                const prefix = s.name.slice(0, colon);
+                if (pluginSet.has(prefix))
+                    return false;
+            }
+        }
+        return true;
+    });
 }
 export function invalidateSkillCache() {
     memoized.cache.clear?.();

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

@@ -12,6 +12,8 @@
  * RunManager, not here.
  */
 export type AsyncAgentStatus = "running" | "completed" | "failed" | "cancelled";
+/** Process-wide cap on concurrent background sub-agents (aligns with Codex max_threads=6). */
+export declare const MAX_BACKGROUND_AGENTS = 6;
 /**
  * Minimal structural shape for an entry in an agent's transcript. We avoid
  * importing the UI's `ChatEntry` here to prevent a tool-system → ui import
@@ -44,6 +46,8 @@ declare class AsyncAgentRegistry {
     subscribe: (cb: () => void) => (() => void);
     getSnapshot: () => AsyncAgentEntry[];
     hasRunning: () => boolean;
+    /** Count of agents currently in the "running" state (cap enforcement). */
+    runningCount(): number;
     private notify;
     register(entry: AsyncAgentEntry): void;
     appendToTranscript(agentId: string, entry: AgentTranscriptEntry): void;

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

@@ -11,6 +11,8 @@
  * the right boundary: long-running cross-process work belongs to
  * RunManager, not here.
  */
+/** Process-wide cap on concurrent background sub-agents (aligns with Codex max_threads=6). */
+export const MAX_BACKGROUND_AGENTS = 6;
 class AsyncAgentRegistry {
     agents = new Map();
     listeners = new Set();
@@ -28,6 +30,10 @@ class AsyncAgentRegistry {
     hasRunning = () => {
         return this.snapshot.some((e) => e.status === "running");
     };
+    /** Count of agents currently in the "running" state (cap enforcement). */
+    runningCount() {
+        return this.snapshot.filter((e) => e.status === "running").length;
+    }
     notify() {
         this.snapshot = [...this.agents.values()];
         for (const cb of this.listeners) {

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

@@ -8,9 +8,45 @@
  */
 import type { ToolDefinition } from "../../types.js";
 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 {
+    model?: string;
+    maxTurns?: number;
+    toolAllowlist?: string[];
+    appendSystemPrompt?: string;
+}
+/**
+ * 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.
+ */
+export declare function resolveAgentTypeOverrides(agentType: string | undefined, registry: AgentDefinitionRegistry | undefined): AgentTypeOverrides;
+type SubAgentLifecycle = "subagent_start" | "subagent_finish" | "subagent_error";
+/**
+ * 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
+ * async, we deliberately `void` it so bookkeeping never blocks on a handler
+ * (mirrors the background-completion notification below).
+ */
+export declare function emitSubAgentHook(hooks: HookRegistry | undefined, kind: SubAgentLifecycle, payload: {
+    agentId: string;
+    description: string;
+    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;
 export declare function agentStatusTool(args: Record<string, unknown>): Promise<string>;
 export declare const agentCancelToolDef: ToolDefinition;
 export declare function agentCancelTool(args: Record<string, unknown>): Promise<string>;
+export {};

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

@@ -6,7 +6,7 @@
  * Supports AbortSignal for cascading cancellation.
  * Supports onStream for real-time output passthrough.
  */
-import { asyncAgentRegistry } from "./agent-registry.js";
+import { asyncAgentRegistry, MAX_BACKGROUND_AGENTS } from "./agent-registry.js";
 import { createTranscriptTranslator } from "./agent-transcript-translator.js";
 import { notificationQueue } from "./agent-notifications.js";
 import { nanoid } from "nanoid";
@@ -32,6 +32,58 @@ function safeEmit(sink, event) {
         });
     }
 }
+/**
+ * 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.
+ */
+export function resolveAgentTypeOverrides(agentType, registry) {
+    if (!agentType)
+        return {};
+    const def = registry?.get(agentType);
+    if (!def) {
+        const available = registry?.list().map((d) => d.name).join(", ") || "(none defined)";
+        throw new Error(`unknown agent_type '${agentType}'. Available: ${available}`);
+    }
+    return {
+        model: def.model,
+        maxTurns: def.maxTurns,
+        toolAllowlist: def.tools,
+        appendSystemPrompt: def.systemPrompt,
+    };
+}
+/**
+ * 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
+ * async, we deliberately `void` it so bookkeeping never blocks on a handler
+ * (mirrors the background-completion notification below).
+ */
+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. " +
@@ -53,6 +105,12 @@ export const agentToolDef = {
                     "Shown in the agent dock to identify what kind of work this sub-agent is doing. " +
                     "Keep it 1-2 words. Defaults to 'Agent' if omitted.",
             },
+            agent_type: {
+                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'.",
+            },
             description: {
                 type: "string",
                 description: "A short (3-5 word) description of the task",
@@ -100,6 +158,7 @@ streamOverride) {
     const { agentId, name, description } = opts;
     const startEndSink = uiStream ?? spawner.parentStream;
     safeEmit(startEndSink, { type: "agent_start", agentId, name, description });
+    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
     // isolation between parent and child is enforced via separate Engine
@@ -107,6 +166,7 @@ streamOverride) {
     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 });
+    emitSubAgentHook(opts.hooks, "subagent_finish", { agentId, description, text: finalText });
     return finalText;
 }
 export async function agentTool(args, ctx) {
@@ -132,7 +192,15 @@ export async function agentTool(args, ctx) {
     if (parentSignal?.aborted) {
         return "Agent aborted before starting.";
     }
-    const maxTurns = args.max_turns || 15;
+    const agentType = args.agent_type?.trim() || undefined;
+    let overrides;
+    try {
+        overrides = resolveAgentTypeOverrides(agentType, ctx?.agentDefinitions);
+    }
+    catch (err) {
+        return `Error: ${err.message}`;
+    }
+    const maxTurns = args.max_turns || overrides.maxTurns || 15;
     const runInBackground = args.run_in_background === true;
     const agentId = nanoid(8);
     const parentStream = spawner.parentStream;
@@ -142,6 +210,10 @@ export async function agentTool(args, ctx) {
     // (background agents survive the spawning turn). Cancellation goes
     // through AgentCancel(agent_id).
     if (runInBackground) {
+        if (asyncAgentRegistry.runningCount() >= MAX_BACKGROUND_AGENTS) {
+            return `Error: too many background agents running (limit ${MAX_BACKGROUND_AGENTS}). ` +
+                `Wait for some to finish or cancel one with AgentCancel(agent_id) before launching more.`;
+        }
         const controller = new AbortController();
         asyncAgentRegistry.register({
             agentId,
@@ -171,6 +243,10 @@ export async function agentTool(args, ctx) {
             description,
             prompt,
             maxTurns,
+            model: overrides.model,
+            toolAllowlist: overrides.toolAllowlist,
+            appendSystemPrompt: overrides.appendSystemPrompt,
+            hooks: ctx?.hooks,
             signal: controller.signal,
         }, parentStream, // uiStream: agent_start/end → main feed
         transcriptSink)
@@ -262,22 +338,38 @@ 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.
+    const syncController = new AbortController();
+    const onParentAbort = () => syncController.abort();
+    parentSignal?.addEventListener("abort", onParentAbort, { once: true });
     try {
-        return await runSubAgent(spawner, {
+        return await runWithTimeout(() => runSubAgent(spawner, {
             agentId,
             name,
             description,
             prompt,
             maxTurns,
-            signal: parentSignal ?? new AbortController().signal,
-        });
+            model: overrides.model,
+            toolAllowlist: overrides.toolAllowlist,
+            appendSystemPrompt: overrides.appendSystemPrompt,
+            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 });
         if (parentSignal?.aborted)
             return "Agent was aborted.";
         return `Agent error: ${err.message}`;
     }
+    finally {
+        parentSignal?.removeEventListener("abort", onParentAbort);
+    }
 }
 // ─── AgentStatus / AgentCancel — companions to run_in_background ─
 export const agentStatusToolDef = {

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

@@ -31,16 +31,34 @@ export async function skillTool(args, ctx) {
     if (!skillName) {
         return "Error: skill name is required.";
     }
-    // Reject disabled skills before scanning so the user gets a clear
-    // message that distinguishes "disabled" from "not found" — matches
-    // the UI's toggle semantics. The scanner would also filter the entry
-    // out, which alone would produce a misleading "not found" reply.
+    // Reject disabled skills/plugins before scanning so the user gets a
+    // clear message that distinguishes "disabled" from "not found" —
+    // matches the UI's toggle semantics. The scanner would also filter
+    // these entries out, which alone would produce a misleading "not
+    // found" reply.
+    //
+    // Ordering: per-skill check fires BEFORE plugin-level check so the
+    // more-specific match wins. Both produce distinct error strings so
+    // ordering is observable but not load-bearing.
     const disabledSkills = ctx?.disabledSkills;
+    const disabledPlugins = ctx?.disabledPlugins;
     if (disabledSkills && disabledSkills.includes(skillName)) {
         return `Skill "${skillName}" is disabled. Enable it in Customize or remove it from settings.disabledSkills.`;
     }
+    if (disabledPlugins && disabledPlugins.length > 0) {
+        const colon = skillName.indexOf(":");
+        if (colon > 0) {
+            const pluginName = skillName.slice(0, colon);
+            if (disabledPlugins.includes(pluginName)) {
+                return `Skill "${skillName}" is in disabled plugin "${pluginName}". Enable the plugin in Customize or remove "${pluginName}" from settings.disabledPlugins.`;
+            }
+        }
+    }
     // A4: scan skills from the Engine's cwd, not the host process cwd.
-    const skills = scanSkills(ctx?.cwd ?? process.cwd(), { disabledSkills });
+    const skills = scanSkills(ctx?.cwd ?? process.cwd(), {
+        disabledSkills,
+        disabledPlugins,
+    });
     const found = skills.find((s) => s.name === skillName);
     if (!found) {
         return `Skill "${skillName}" not found. Run /skills to list available skills.`;

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

@@ -65,6 +65,23 @@ export interface SubAgentSpawnRequest {
      * gets `agent_start` / `agent_end` markers via `spawner.parentStream`.
      */
     streamOverride?: StreamCallback;
+    /**
+     * Optional ModelPool key for the child Engine's LLM (e.g. "flash").
+     * Undefined → child inherits the parent's model (current behavior).
+     */
+    model?: string;
+    /**
+     * Optional tool-name allowlist for the child. When set, the child's tool
+     * pool is restricted to these names (still minus the nested-agent tools).
+     * Undefined → child inherits the parent's full tool set (current behavior).
+     */
+    toolAllowlist?: string[];
+    /**
+     * Optional per-call system prompt appended to the child Engine's prompt
+     * (the role definition's Markdown body). Undefined → child inherits only
+     * the parent's appendSystemPrompt (current behavior).
+     */
+    appendSystemPrompt?: string;
 }
 export interface SubAgentSpawner {
     /** Run a sub-agent synchronously and return its text output. */
@@ -97,6 +114,12 @@ export interface ToolContext {
     askUser?: AskUserFn;
     /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
     subAgentSpawner?: SubAgentSpawner;
+    /**
+     * Reusable sub-agent role definitions (loaded from .code-shell/agents/*.md).
+     * The Agent tool reads this to resolve `agent_type`. Undefined → only the
+     * ephemeral (inline prompt) mode is available.
+     */
+    agentDefinitions?: import("../agent/agent-definition-registry.js").AgentDefinitionRegistry;
     /**
      * True when this Engine is itself a sub-agent. Set from EngineConfig.
      * The Agent tool refuses to spawn when this is true — runtime check
@@ -150,6 +173,14 @@ export interface ToolContext {
      * Populated from `settings.disabledSkills` by Engine.run().
      */
     disabledSkills?: string[];
+    /**
+     * Plugin names the user has totally disabled. Every skill whose
+     * namespaced name starts with `${pluginName}:` is hidden from the
+     * LLM and rejected at dispatch by the skill builtin tool with a
+     * distinct "disabled plugin" message. Populated from
+     * `settings.disabledPlugins` by Engine.run().
+     */
+    disabledPlugins?: string[];
 }
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.5.0-rc.0",
+  "version": "0.5.0-rc.1",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",