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

package/dist/plugins/pluginInstaller.js

@@ -4,23 +4,82 @@
  * source types (path / git / github / git-subdir), no dependencies, no
  * sparse-checkout, no npm/pip.
  */
-import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync, } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, realpathSync, rmSync, rmdirSync } from "node:fs";
+import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { homedir, tmpdir } from "node:os";
-import { gitClone, gitRevParseHead, githubRepoToCloneUrl } from "./gitOps.js";
+import { gitClone, gitRevParseHead, gitSparseCheckoutAdd, githubRepoToCloneUrl, } from "./gitOps.js";
 import { loadMarketplace } from "./marketplaceManager.js";
 import { readKnownMarketplaces } from "./knownMarketplaces.js";
 import { appendInstallEntry, pluginInstallKey, readInstalledPlugins, removeInstallEntries, } from "./installedPlugins.js";
 import { rewritePluginVars } from "./varRewrite.js";
+import { assertSafePluginName } from "./installer/paths.js";
+import { pruneDisabledSettingsForPlugin } from "./installer/pruneDisabled.js";
 function userHome() {
     return process.env.HOME ?? homedir();
 }
 function pluginCacheRoot() {
     return join(userHome(), ".code-shell", "plugins", "cache");
 }
-function pluginCacheDir(marketplace, plugin, version) {
+/**
+ * Compose the on-disk cache directory for a plugin version. Every path segment
+ * (marketplace / plugin / version) can originate from an attacker-controlled
+ * marketplace manifest, so each must be validated as a single safe path
+ * segment before it enters `join`. Without this a manifest entry named `..`
+ * (or containing a separator) would let the materialized plugin tree be
+ * written outside the plugin cache root — a supply-chain path traversal.
+ *
+ * Reuses `assertSafePluginName` (rejects empty / "." / ".." / separators /
+ * NUL). Exported so the segment-validation contract can be unit-tested
+ * directly.
+ */
+export function pluginCacheDir(marketplace, plugin, version) {
+    assertSafePluginName(marketplace);
+    assertSafePluginName(plugin);
+    assertSafePluginName(version);
     return join(pluginCacheRoot(), marketplace, plugin, version);
 }
+/**
+ * Resolve a candidate `installPath` to a realpath and verify it lives strictly
+ * underneath the plugin cache root. Returns the resolved path on success, or
+ * null when the path is missing, escapes the cache, equals the cache root
+ * itself, or is otherwise unsafe to remove.
+ *
+ * Exported so tests can exercise the safety predicate directly without
+ * arranging a full uninstall — the contract this defends (no rmSync outside
+ * the plugin cache) is the entire point of T2 / Workstream A2.
+ */
+export function resolveSafePluginPath(installPath, cacheRoot) {
+    if (typeof installPath !== "string" || installPath.length === 0)
+        return null;
+    // Realpath the cache root once. We require it to exist; if the cache root
+    // itself can't be resolved, refuse all deletions rather than fall back to
+    // a string-only check.
+    let safeCacheRoot;
+    try {
+        safeCacheRoot = realpathSync(cacheRoot);
+    }
+    catch {
+        return null;
+    }
+    // Realpath the target. A missing target (dangling symlink, already removed,
+    // typo in installed_plugins.json) returns null — caller will skip silently.
+    let resolvedTarget;
+    try {
+        resolvedTarget = realpathSync(installPath);
+    }
+    catch {
+        return null;
+    }
+    // Strict containment: must start with cacheRoot + separator. Equal-to-root
+    // is explicitly rejected so a tampered entry can't wipe the whole cache.
+    const rootWithSep = safeCacheRoot.endsWith(sep) ? safeCacheRoot : safeCacheRoot + sep;
+    if (resolvedTarget === safeCacheRoot)
+        return null;
+    if (!resolvedTarget.startsWith(rootWithSep))
+        return null;
+    return resolvedTarget;
+}
 async function materializePath(marketplaceInstallLocation, relativePath, cacheTarget) {
     const src = isAbsolute(relativePath)
         ? relativePath
@@ -28,17 +87,17 @@ async function materializePath(marketplaceInstallLocation, relativePath, cacheTa
     if (!existsSync(src)) {
         return { ok: false, error: `plugin source path "${relativePath}" not found in marketplace` };
     }
-    mkdirSync(dirname(cacheTarget), { recursive: true });
+    await mkdir(dirname(cacheTarget), { recursive: true });
     if (existsSync(cacheTarget))
-        rmSync(cacheTarget, { recursive: true, force: true });
-    cpSync(src, cacheTarget, { recursive: true });
+        await rm(cacheTarget, { recursive: true, force: true });
+    await cp(src, cacheTarget, { recursive: true });
     return { ok: true, sha: undefined };
 }
 async function materializeGit(url, ref, cacheTarget) {
-    mkdirSync(dirname(cacheTarget), { recursive: true });
+    await mkdir(dirname(cacheTarget), { recursive: true });
     if (existsSync(cacheTarget))
-        rmSync(cacheTarget, { recursive: true, force: true });
-    const clone = await gitClone(url, cacheTarget, ref ? { ref } : undefined);
+        await rm(cacheTarget, { recursive: true, force: true });
+    const clone = await gitClone(url, cacheTarget, { full: true, ...(ref ? { ref } : {}) });
     if (!clone.ok)
         return { ok: false, error: clone.error };
     const head = await gitRevParseHead(cacheTarget);
@@ -48,9 +107,9 @@ async function materializeGit(url, ref, cacheTarget) {
 }
 async function materializeGitSubdir(url, subPath, ref, cacheTarget) {
     // Clone to a tempdir, then copy the subdir over.
-    const tmp = mkdtempSync(join(tmpdir(), "plugin-clone-"));
+    const tmp = await mkdtemp(join(tmpdir(), "plugin-clone-"));
     try {
-        const clone = await gitClone(url, tmp + "/repo", ref ? { ref } : undefined);
+        const clone = await gitClone(url, tmp + "/repo", { full: true, ...(ref ? { ref } : {}) });
         if (!clone.ok)
             return { ok: false, error: clone.error };
         const head = await gitRevParseHead(tmp + "/repo");
@@ -63,14 +122,14 @@ async function materializeGitSubdir(url, subPath, ref, cacheTarget) {
                 error: `git-subdir path "${subPath}" not found in cloned repository`,
             };
         }
-        mkdirSync(dirname(cacheTarget), { recursive: true });
+        await mkdir(dirname(cacheTarget), { recursive: true });
         if (existsSync(cacheTarget))
-            rmSync(cacheTarget, { recursive: true, force: true });
-        cpSync(src, cacheTarget, { recursive: true });
+            await rm(cacheTarget, { recursive: true, force: true });
+        await cp(src, cacheTarget, { recursive: true });
         return { ok: true, sha: head.stdout };
     }
     finally {
-        rmSync(tmp, { recursive: true, force: true });
+        await rm(tmp, { recursive: true, force: true });
     }
 }
 function shortSha(sha) {
@@ -78,20 +137,53 @@ function shortSha(sha) {
         return "unknown";
     return sha.slice(0, 12);
 }
+/**
+ * Compare a marketplace-declared SHA against the cloned HEAD. The
+ * declaration is allowed to be a short prefix (>= 7 chars, standard git
+ * abbreviation length); for stricter integrity guarantees marketplaces
+ * should pin the full 40-char hash. Case-insensitive.
+ *
+ * Exported so a unit test can pin the policy without spinning up a real
+ * clone.
+ */
+export function shaMatches(declared, actual) {
+    if (typeof declared !== "string" || typeof actual !== "string")
+        return false;
+    const d = declared.trim().toLowerCase();
+    const a = actual.trim().toLowerCase();
+    if (d.length < 7)
+        return false; // refuse 6-or-less; too collision-prone
+    if (d.length > 40)
+        return false; // not a valid SHA
+    return a.startsWith(d);
+}
 async function materialize(source, marketplaceInstallLocation, marketplace, plugin) {
     // First pass: install into a placeholder dir, then rename to the SHA dir
     // once we know it. For path sources there's no SHA — use "local".
     const placeholder = pluginCacheDir(marketplace, plugin, "_pending_");
     if (typeof source === "string") {
+        // The marketplace was cloned sparse (only the manifest dirs are on disk),
+        // so a local-path plugin's tree may not be checked out yet. Expand the
+        // sparse-checkout to include it before reading. Best-effort: on a
+        // non-sparse (full) clone this errors harmlessly and the files are already
+        // present, so we ignore the result and let materializePath report a real
+        // missing-path error if the subdir truly isn't there.
+        if (!isAbsolute(source)) {
+            // Strip a leading "./" — in non-cone sparse mode the literal "./" prefix
+            // doesn't match repo paths (which are stored without it), so the
+            // expand would silently no-op and the tree would stay un-materialized.
+            const sparseRel = source.replace(/^\.\//, "");
+            await gitSparseCheckoutAdd(marketplaceInstallLocation, sparseRel);
+        }
         const r = await materializePath(marketplaceInstallLocation, source, placeholder);
         if (!r.ok)
             return r;
         const finalDir = pluginCacheDir(marketplace, plugin, "local");
         if (existsSync(finalDir))
-            rmSync(finalDir, { recursive: true, force: true });
-        mkdirSync(dirname(finalDir), { recursive: true });
-        cpSync(placeholder, finalDir, { recursive: true });
-        rmSync(placeholder, { recursive: true, force: true });
+            await rm(finalDir, { recursive: true, force: true });
+        await mkdir(dirname(finalDir), { recursive: true });
+        await cp(placeholder, finalDir, { recursive: true });
+        await rm(placeholder, { recursive: true, force: true });
         return { ok: true, cacheDir: finalDir, version: "local", sha: undefined };
     }
     if (source.source === "git" || source.source === "github") {
@@ -99,32 +191,51 @@ async function materialize(source, marketplaceInstallLocation, marketplace, plug
         const r = await materializeGit(url, source.ref, placeholder);
         if (!r.ok) {
             if (existsSync(placeholder))
-                rmSync(placeholder, { recursive: true, force: true });
+                await rm(placeholder, { recursive: true, force: true });
             return r;
         }
+        // Supply-chain check: when the marketplace entry pins a SHA, fail the
+        // install if the cloned HEAD doesn't match. Without this the `sha`
+        // field is decorative — present in metadata, never enforced.
+        if (source.sha && !shaMatches(source.sha, r.sha)) {
+            if (existsSync(placeholder))
+                await rm(placeholder, { recursive: true, force: true });
+            return {
+                ok: false,
+                error: `sha mismatch for ${plugin}: expected ${source.sha}, got ${r.sha}`,
+            };
+        }
         const version = shortSha(r.sha);
         const finalDir = pluginCacheDir(marketplace, plugin, version);
         if (existsSync(finalDir))
-            rmSync(finalDir, { recursive: true, force: true });
-        mkdirSync(dirname(finalDir), { recursive: true });
-        cpSync(placeholder, finalDir, { recursive: true });
-        rmSync(placeholder, { recursive: true, force: true });
+            await rm(finalDir, { recursive: true, force: true });
+        await mkdir(dirname(finalDir), { recursive: true });
+        await cp(placeholder, finalDir, { recursive: true });
+        await rm(placeholder, { recursive: true, force: true });
         return { ok: true, cacheDir: finalDir, version, sha: r.sha };
     }
     if (source.source === "git-subdir") {
         const r = await materializeGitSubdir(source.url, source.path, source.ref, placeholder);
         if (!r.ok) {
             if (existsSync(placeholder))
-                rmSync(placeholder, { recursive: true, force: true });
+                await rm(placeholder, { recursive: true, force: true });
             return r;
         }
+        if (source.sha && !shaMatches(source.sha, r.sha)) {
+            if (existsSync(placeholder))
+                await rm(placeholder, { recursive: true, force: true });
+            return {
+                ok: false,
+                error: `sha mismatch for ${plugin}: expected ${source.sha}, got ${r.sha}`,
+            };
+        }
         const version = shortSha(r.sha);
         const finalDir = pluginCacheDir(marketplace, plugin, version);
         if (existsSync(finalDir))
-            rmSync(finalDir, { recursive: true, force: true });
-        mkdirSync(dirname(finalDir), { recursive: true });
-        cpSync(placeholder, finalDir, { recursive: true });
-        rmSync(placeholder, { recursive: true, force: true });
+            await rm(finalDir, { recursive: true, force: true });
+        await mkdir(dirname(finalDir), { recursive: true });
+        await cp(placeholder, finalDir, { recursive: true });
+        await rm(placeholder, { recursive: true, force: true });
         return { ok: true, cacheDir: finalDir, version, sha: r.sha };
     }
     return { ok: false, error: `unsupported source type "${source.source}"` };
@@ -154,7 +265,18 @@ export async function installPlugin(pluginName, marketplaceName) {
     if (!entry) {
         return { ok: false, error: `plugin "${pluginName}" not found in marketplace "${marketplaceName}".` };
     }
-    const mat = await materialize(entry.source, km.installLocation, marketplaceName, pluginName);
+    // materialize() validates every cache path segment (marketplace / plugin /
+    // version) and throws a PluginInstallError on an unsafe one. Convert that to
+    // a clean failure result — every caller (bootstrap / marketplace-service /
+    // tui handler) consumes { ok, error } and must not be crashed by a hostile
+    // marketplace manifest.
+    let mat;
+    try {
+        mat = await materialize(entry.source, km.installLocation, marketplaceName, pluginName);
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
     if (!mat.ok)
         return mat;
     // Rewrite ${CLAUDE_PLUGIN_ROOT} → ${CODESHELL_PLUGIN_ROOT} across every
@@ -194,10 +316,19 @@ export function uninstallPlugin(pluginName, marketplaceName) {
     const data = readInstalledPlugins();
     const entries = data.plugins[key];
     let removedFromDisk = false;
+    const cacheRoot = pluginCacheRoot();
     if (entries) {
         for (const e of entries) {
-            if (e.installPath && existsSync(e.installPath)) {
-                rmSync(e.installPath, { recursive: true, force: true });
+            if (!e.installPath)
+                continue;
+            // Containment check: the on-disk installed_plugins.json can be tampered
+            // with to point at arbitrary paths (e.g. "/", "$HOME"). Refuse to rm
+            // anything that doesn't realpath to a strict child of the plugin cache.
+            const safePath = resolveSafePluginPath(e.installPath, cacheRoot);
+            if (!safePath)
+                continue;
+            if (existsSync(safePath)) {
+                rmSync(safePath, { recursive: true, force: true });
                 removedFromDisk = true;
             }
         }
@@ -205,14 +336,16 @@ export function uninstallPlugin(pluginName, marketplaceName) {
         const pluginParent = join(pluginCacheRoot(), marketplaceName, pluginName);
         try {
             // rmdir succeeds only when empty; ignore failures.
-            const fs = require("node:fs");
-            fs.rmdirSync(pluginParent);
+            rmdirSync(pluginParent);
         }
         catch {
             // not empty or doesn't exist — fine
         }
     }
     const removedFromManifest = removeInstallEntries(key);
+    // Clear orphaned disable flags (disabledSkills "name:skill" /
+    // disabledPlugins "name") so a removed plugin leaves no dangling entries.
+    pruneDisabledSettingsForPlugin(pluginName);
     return { ok: removedFromManifest || removedFromDisk, removedFromManifest, removedFromDisk };
 }
 export function listInstalled() {

package/dist/plugins/schemas.js

@@ -44,6 +44,30 @@ export function validatePluginEntrySource(raw, path) {
             },
         };
     }
+    if (kind === "local") {
+        // Codex / agents-format marketplaces (e.g. awesome-codex-plugins) express
+        // a local plugin as { source: "local", path }. Our installer's local path
+        // source is a bare string, so normalize onto that.
+        if (typeof raw.path !== "string" || !raw.path) {
+            return { ok: false, error: `${path}: local source requires path` };
+        }
+        return { ok: true, value: raw.path };
+    }
+    if (kind === "url") {
+        // The official claude-plugins-official marketplace emits a "url" source
+        // type for "clone this git repo" (optionally a subdir via `path`). It is
+        // semantically identical to our git / git-subdir sources, so normalize it
+        // onto those rather than carrying a fourth code path through the installer.
+        if (typeof raw.url !== "string" || !raw.url) {
+            return { ok: false, error: `${path}: url source requires url` };
+        }
+        const ref = typeof raw.ref === "string" ? raw.ref : undefined;
+        const sha = typeof raw.sha === "string" ? raw.sha : undefined;
+        if (typeof raw.path === "string" && raw.path) {
+            return { ok: true, value: { source: "git-subdir", url: raw.url, path: raw.path, ref, sha } };
+        }
+        return { ok: true, value: { source: "git", url: raw.url, ref, sha } };
+    }
     if (kind === "git-subdir") {
         if (typeof raw.url !== "string" || !raw.url) {
             return { ok: false, error: `${path}: git-subdir source requires url` };
@@ -99,6 +123,7 @@ export function validatePluginEntry(raw, index) {
             category: typeof raw.category === "string" ? raw.category : undefined,
             source: source.value,
             homepage: typeof raw.homepage === "string" ? raw.homepage : undefined,
+            version: typeof raw.version === "string" ? raw.version : undefined,
         },
     };
 }
@@ -108,8 +133,21 @@ export function validateMarketplace(raw) {
     if (typeof raw.name !== "string" || !raw.name) {
         return { ok: false, error: "marketplace.json: name is required" };
     }
-    if (!isObject(raw.owner) || typeof raw.owner.name !== "string") {
-        return { ok: false, error: "marketplace.json: owner.name is required" };
+    // Claude Code marketplaces carry a top-level `owner: { name }`. Codex /
+    // agents-format marketplaces omit it and instead carry `interface.displayName`.
+    // Accept either, falling back to the marketplace name as a last resort, so a
+    // Codex manifest is not rejected purely for lacking an owner.
+    let ownerName;
+    let ownerEmail;
+    if (isObject(raw.owner) && typeof raw.owner.name === "string") {
+        ownerName = raw.owner.name;
+        ownerEmail = typeof raw.owner.email === "string" ? raw.owner.email : undefined;
+    }
+    else if (isObject(raw.interface) && typeof raw.interface.displayName === "string") {
+        ownerName = raw.interface.displayName;
+    }
+    else {
+        ownerName = raw.name;
     }
     if (!Array.isArray(raw.plugins)) {
         return { ok: false, error: "marketplace.json: plugins must be an array" };
@@ -126,10 +164,7 @@ export function validateMarketplace(raw) {
         value: {
             name: raw.name,
             description: typeof raw.description === "string" ? raw.description : undefined,
-            owner: {
-                name: raw.owner.name,
-                email: typeof raw.owner.email === "string" ? raw.owner.email : undefined,
-            },
+            owner: { name: ownerName, email: ownerEmail },
             plugins,
         },
     };

package/dist/plugins/types.d.ts

@@ -11,10 +11,14 @@ export type MarketplaceSource = {
     source: "git";
     url: string;
 };
+/** Which plugin-manifest convention a cloned marketplace ships. */
+export type MarketplaceFormat = "claude-code" | "codex" | "universal";
 export interface KnownMarketplace {
     source: MarketplaceSource;
     installLocation: string;
     lastUpdated: string;
+    /** Optional: absent on entries written before format detection existed. */
+    format?: MarketplaceFormat;
 }
 export type KnownMarketplaces = Record<string, KnownMarketplace>;
 export type PluginEntrySource = string | {
@@ -44,6 +48,12 @@ export interface PluginMarketplaceEntry {
     category?: string;
     source: PluginEntrySource;
     homepage?: string;
+    /**
+     * Declared version from the marketplace manifest, when the author wrote
+     * one. CC's marketplace.json has no version convention, so this is often
+     * absent — the UI hides it rather than showing a placeholder.
+     */
+    version?: string;
 }
 export interface PluginMarketplace {
     name: string;

package/dist/preset/index.d.ts

@@ -51,8 +51,14 @@ export declare function listPresetNames(): string[];
 export declare function resolveAgentPreset(name?: string): AgentPreset;
 /**
  * Build the full system prompt for a preset by loading and joining its sections.
+ *
+ * `activeToolNames` (the turn's effective tool set, post capability-override
+ * filtering) gates tool-coupled sections: the "browser" section is dropped when
+ * no browser tool is active, so the browser capability is a single on/off unit
+ * (tools + usage instructions disappear together). Omit `activeToolNames` to
+ * include all sections (e.g. when assembling a generic/preview prompt).
  */
-export declare function buildPresetSystemPrompt(preset: AgentPreset): string;
+export declare function buildPresetSystemPrompt(preset: AgentPreset, activeToolNames?: readonly string[]): string;
 export declare function resolveBuiltinToolNames(options?: {
     preset?: string;
     enabledBuiltinTools?: string[];

package/dist/preset/index.js

@@ -18,8 +18,25 @@ const GENERAL_BUILTIN_TOOLS = [
     "Glob",
     "Grep",
     "Bash",
+    // Bash(run_in_background=true) companions — without these in the preset
+    // whitelist, the registry skips them (registerBuiltins filters BUILTIN_TOOLS
+    // by the selected set), so a model that correctly calls BashOutput after
+    // launching a background shell hits "Tool not found" and the turn dies.
+    "BashOutput",
+    "KillShell",
+    "ListShells",
+    // Browser automation (drive the in-app webview) — 3 semantic tools. Same
+    // whitelist requirement as the BashOutput trio above: registerBuiltins filters
+    // BUILTIN_TOOLS by the preset set, so without these the model calling
+    // browser_observe/etc. hits "Tool not found". They self-degrade to a clear
+    // error when no browser panel is wired (headless), so listing is safe.
+    "browser_observe",
+    "browser_act",
+    "browser_navigate",
     "WebSearch",
     "WebFetch",
+    "GenerateImage",
+    "GenerateVideo",
     "AskUserQuestion",
     "Agent",
     // AgentStatus removed: background agents now write to ~/.code-shell/agents/
@@ -35,13 +52,57 @@ const GENERAL_BUILTIN_TOOLS = [
     "CronCreate",
     "CronDelete",
     "CronList",
+    // cc-orchestrator:驱动外部 claude CLI 跑一轮。同 BashOutput/UseCredential/
+    // EditModelCatalog 的 whitelist 要求:已在 BUILTIN_TOOLS 注册,但 registerBuiltins
+    // 按 preset 集过滤 → 名单里没有它,agent 就没有「指挥 Claude Code」的工具,只能幻觉
+    // RemoteTrigger / 兜底 Bash `claude -p`(用户实测「为什么驱动 cc 没作为工具」)。
+    // 定时/循环驱动统一走 CronCreate(到点跑一轮引擎,prompt 里调 DriveAgent);
+    // 无人值守审批由 DriveAgent 自身 bypass 解决,不需要定时层专门的 CC 调度工具。
+    // DriveAgent 是通用驱动(cli: claude|codex);DriveClaudeCode 保留为 cli:claude 的
+    // 别名(老 prompt/记忆兼容)。两个都要在白名单里,否则 registerBuiltins 滤掉。
+    "DriveAgent",
+    "DriveClaudeCode",
+    // 编排时读 CC/Codex 剩余额度做规划(开几个/等重置/换 provider)。
+    "CheckQuota",
     "Skill",
     "MCPTool",
     "ListMcpResources",
     "ReadMcpResource",
-    "RemoteTrigger",
     "REPL",
     "PowerShell",
+    // Persistent cross-session memory. Including these in the default preset is
+    // what lets the LLM list/read/save/delete memories during a normal session,
+    // AND what makes the end-of-session auto-dream consolidation work — its
+    // tool-call loop pulls these from the registry, so without them every dream
+    // run bailed with "missing memory tools". Save/Delete in the user scope stay
+    // permission-gated (the tools declare permissionDefault: "ask"); dream-scope
+    // writes go through freely.
+    "MemoryList",
+    "MemoryRead",
+    "MemorySave",
+    "MemoryDelete",
+    // AI 取用已存凭证(cookie/token/link)给 yt-dlp/curl 等。必须在 preset 白名单里
+    // 否则 registerBuiltins 滤掉它 → 即使存了凭证、注册了工具,AI 列表里也没有
+    // UseCredential(用户实测「找不到这个工具」的真因)。它带 isUseCredentialAvailable
+    // guard:cwd 凭证库为空时仍自动隐藏,所以无条件列入是安全的(空库不会冒出来)。
+    "UseCredential",
+    // 同理:把 cookie 凭证注入内置浏览器(恢复登录态后用 browser_* 工具)。带
+    // isInjectCredentialAvailable guard(无 cookie 凭证时自动隐藏),无条件列入安全。
+    "InjectCredential",
+    // AI 增/改模型 catalog(写 ~/.code-shell/model-catalog.user.json)。同 BashOutput/
+    // UseCredential 一样的 whitelist 要求:registerBuiltins 按 preset 集过滤 BUILTIN_TOOLS,
+    // 名单里没有它 → 即使工具已注册,AI 列表里也没有 → 用户实测「找不到这个工具」。
+    // permissionDefault: "ask",列入只是让 AI 看得到,调用仍走审批,无条件列入安全。
+    "EditModelCatalog",
+    // Goal-mode control tools. Same whitelist requirement as the rest:
+    // registerBuiltins filters BUILTIN_TOOLS by the preset set, so a goal tool
+    // absent here is registered-but-invisible — the model never sees it and can
+    // neither self-declare completion (complete_goal) nor honor a user's request
+    // to abandon the goal (cancel_goal), stranding a persistent goal that only a
+    // manual disk edit could clear. cancel_goal is the "strong intent" escape
+    // hatch (requires confirm+reason); the turn-loop enforces the guard.
+    "complete_goal",
+    "cancel_goal",
 ];
 const TERMINAL_CODING_EXTRA_TOOLS = [
     "EnterWorktree",
@@ -68,9 +129,31 @@ const GENERAL_PERMISSION_RULES = [
     { tool: "TodoWrite", decision: "allow" },
     { tool: "Sleep", decision: "allow" },
     { tool: "CronList", decision: "allow" },
+    { tool: "CheckQuota", decision: "allow" },
     { tool: "Skill", decision: "allow" },
+    // ListMcpResources only enumerates resource names (and the executor filters
+    // the list to this session's enabled servers). ReadMcpResource pulls actual
+    // content and is intentionally NOT auto-allowed here — it falls back to its
+    // tool-level "ask" default so a default-mode session confirms the read.
     { tool: "ListMcpResources", decision: "allow" },
-    { tool: "ReadMcpResource", decision: "allow" },
+    // Reading memory is always safe; writes (MemorySave/MemoryDelete) stay gated
+    // by the tools' own permissionDefault so the user confirms each change.
+    { tool: "MemoryList", decision: "allow" },
+    { tool: "MemoryRead", decision: "allow" },
+    // Browser automation (3 semantic tools). Rules are first-match-wins, ordered
+    // by specificity — so the action-gating rule for browser_act MUST come first:
+    // click/type/select mutate the page/form → "ask"; all other actions (hover/
+    // scroll/wait/press_key/list_tabs/switch_tab) fall through to browser_act's
+    // tool-level "allow". observe (read-only) and navigate auto-allow.
+    // (Main-side sensitive-action + domain-whitelist enforcement also applies.)
+    {
+        tool: "browser_act",
+        argsPattern: { action: "^(click|type|select)$" },
+        decision: "ask",
+        reason: "browser_act click/type/select mutate the page",
+    },
+    { tool: "browser_observe", decision: "allow" },
+    { tool: "browser_navigate", decision: "allow" },
 ];
 // ─── Preset definitions ──────────────────────────────────────────
 export const BUILTIN_AGENT_PRESETS = {
@@ -78,7 +161,7 @@ export const BUILTIN_AGENT_PRESETS = {
         name: "general",
         label: "General Orchestrator",
         description: "Domain-agnostic orchestration for research, operations, automation, and long-running tasks.",
-        promptSections: ["base", "orchestration", "tone"],
+        promptSections: ["base", "orchestration", "browser", "tone"],
         injectGitStatus: false,
         builtinTools: [...GENERAL_BUILTIN_TOOLS],
         defaultPermissionRules: GENERAL_PERMISSION_RULES,
@@ -87,7 +170,7 @@ export const BUILTIN_AGENT_PRESETS = {
         name: "terminal-coding",
         label: "Terminal Coding Assistant",
         description: "General orchestration plus coding-focused guidance and code-navigation tools.",
-        promptSections: ["base", "orchestration", "coding", "tone"],
+        promptSections: ["base", "orchestration", "coding", "browser", "tone"],
         injectGitStatus: true,
         builtinTools: [...GENERAL_BUILTIN_TOOLS, ...TERMINAL_CODING_EXTRA_TOOLS],
         defaultPermissionRules: [
@@ -140,11 +223,34 @@ export function resolveAgentPreset(name) {
     const allowed = listPresetNames().join(", ");
     throw new Error(`Unknown agent preset "${name}". Available presets: ${allowed}`);
 }
+/** Tool names that gate the "browser" prompt section — if NONE of these are in
+ *  the active tool set (browser capability turned off), the section is dropped
+ *  so the model isn't told how to use tools it can't see. Keep in sync with the
+ *  browser tools registered in builtin/index.ts. */
+const BROWSER_SECTION_TOOLS = ["browser_observe", "browser_act", "browser_navigate"];
+/** Prompt sections whose inclusion is gated by an active tool being present. */
+const TOOL_GATED_SECTIONS = {
+    browser: BROWSER_SECTION_TOOLS,
+};
 /**
  * Build the full system prompt for a preset by loading and joining its sections.
+ *
+ * `activeToolNames` (the turn's effective tool set, post capability-override
+ * filtering) gates tool-coupled sections: the "browser" section is dropped when
+ * no browser tool is active, so the browser capability is a single on/off unit
+ * (tools + usage instructions disappear together). Omit `activeToolNames` to
+ * include all sections (e.g. when assembling a generic/preview prompt).
  */
-export function buildPresetSystemPrompt(preset) {
-    return loadSections(preset.promptSections);
+export function buildPresetSystemPrompt(preset, activeToolNames) {
+    let sections = preset.promptSections;
+    if (activeToolNames) {
+        const active = new Set(activeToolNames);
+        sections = sections.filter((s) => {
+            const gate = TOOL_GATED_SECTIONS[s];
+            return !gate || gate.some((t) => active.has(t));
+        });
+    }
+    return loadSections(sections);
 }
 export function resolveBuiltinToolNames(options) {
     const preset = resolveAgentPreset(options?.preset);

package/dist/product/types.d.ts

@@ -21,7 +21,7 @@
 import type { PermissionRule, MCPServerConfig } from "../types.js";
 import type { Evaluator } from "../run/Evaluator.js";
 import type { RegisteredTool } from "../types.js";
-import type { EngineHookConfig } from "../engine/engine.js";
+import type { EngineHookConfig } from "../engine/types.js";
 export interface ProductPreset {
     /** Unique name for this product's preset. */
     name: string;