codesift-mcp 0.5.21 → 0.5.27

package/dist/register-tools.js

@@ -246,6 +246,71 @@ const FRAMEWORK_TOOL_GROUPS = {
         "extract_kotlin_serialization_contract",
         "trace_flow_chain",
     ],
+    // Python — detected by pyproject.toml (poetry/pdm/uv/hatch) or requirements.txt
+    "pyproject.toml": [
+        "get_model_graph",
+        "get_test_fixtures",
+        "find_framework_wiring",
+        "run_ruff",
+        "parse_pyproject",
+        "find_python_callers",
+        "analyze_django_settings",
+        "run_mypy",
+        "run_pyright",
+        "analyze_python_deps",
+        "trace_fastapi_depends",
+        "analyze_async_correctness",
+        "get_pydantic_models",
+        "python_audit",
+    ],
+    "requirements.txt": [
+        "get_model_graph",
+        "get_test_fixtures",
+        "find_framework_wiring",
+        "run_ruff",
+        "find_python_callers",
+        "analyze_django_settings",
+        "run_mypy",
+        "run_pyright",
+        "analyze_python_deps",
+        "trace_fastapi_depends",
+        "analyze_async_correctness",
+        "get_pydantic_models",
+        "python_audit",
+    ],
+    // TypeScript baseline — auto-enabled on any project with tsconfig.json.
+    // Promotes 3 high-value but historically dark tools so that vanilla TS /
+    // library / monorepo repos get a proper entry point beyond search_text.
+    "tsconfig.json": [
+        "dependency_audit",
+        "check_boundaries",
+        "architecture_summary",
+    ],
+    // Monorepo signals — orchestration-level analysis is most useful when
+    // there are >1 packages. Each of these files alone is enough to fire.
+    "pnpm-workspace.yaml": [
+        "check_boundaries",
+        "architecture_summary",
+    ],
+    "lerna.json": [
+        "check_boundaries",
+        "architecture_summary",
+    ],
+    "nx.json": [
+        "check_boundaries",
+        "architecture_summary",
+    ],
+    "turbo.json": [
+        "check_boundaries",
+        "architecture_summary",
+    ],
+    // Prisma — root-level schema. Nested prisma/schema.prisma handled in
+    // detectAutoLoadTools after the loop. drizzle-kit dep handled in
+    // detectFromPackageJson.
+    "schema.prisma": [
+        "analyze_prisma_schema",
+        "migration_lint",
+    ],
 };
 /**
  * React-specific tools — auto-enabled when a React project is detected.
@@ -282,6 +347,22 @@ const HONO_TOOLS = [
     "detect_hono_modules",
     "find_dead_hono_routes",
 ];
+/**
+ * Monorepo tools — auto-enabled when `pkg.workspaces` field is present
+ * (mirror of the file-based monorepo signals in FRAMEWORK_TOOL_GROUPS).
+ */
+const MONOREPO_TOOLS = [
+    "check_boundaries",
+    "architecture_summary",
+];
+/**
+ * Prisma tools — auto-enabled when `prisma` or `drizzle-kit` is in deps
+ * (mirror of the schema.prisma file signal in FRAMEWORK_TOOL_GROUPS).
+ */
+const PRISMA_TOOLS = [
+    "analyze_prisma_schema",
+    "migration_lint",
+];
 const AUTO_LOAD_CACHE_TTL_MS = 5_000;
 const autoLoadToolsCache = new Map();
 /**
@@ -290,6 +371,8 @@ const autoLoadToolsCache = new Map();
  * Exported for unit testing.
  */
 export async function detectAutoLoadTools(cwd) {
+    // Kill switch: spec D-FB. Skip workspace walk entirely when set.
+    const killSwitchOff = process.env.CODESIFT_DISABLE_MONOREPO !== "1";
     const { existsSync, readFileSync, readdirSync } = await import("node:fs");
     const { join } = await import("node:path");
     const toEnable = [];
@@ -298,30 +381,79 @@ export async function detectAutoLoadTools(cwd) {
             toEnable.push(...tools);
         }
     }
-    // React + Hono detection: both need to read package.json for dep signals.
-    const pkgPath = join(cwd, "package.json");
-    if (existsSync(pkgPath)) {
+    // Nested Prisma schema — `prisma/schema.prisma` is the more common layout
+    // than root-level. The root-level case is covered by FRAMEWORK_TOOL_GROUPS.
+    if (existsSync(join(cwd, "prisma", "schema.prisma"))) {
+        toEnable.push(...PRISMA_TOOLS);
+    }
+    const detectFromPackageJson = (pkgRoot) => {
+        const enabled = [];
+        const pkgPath = join(pkgRoot, "package.json");
+        if (!existsSync(pkgPath))
+            return enabled;
         try {
             const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
             const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-            // React: dep + .tsx/.jsx files
-            const hasReact = !!(allDeps["react"] || allDeps["next"] || allDeps["@remix-run/react"]);
-            if (hasReact && hasJsxFilesShallow(cwd, readdirSync)) {
-                toEnable.push(...REACT_TOOLS);
-            }
-            // Hono: any hono package is enough — the framework is only pulled in
-            // when used, and all 5 hidden tools degrade gracefully on non-Hono repos
-            // so false positives are harmless (return "no Hono detected" errors).
+            const hasReact = !!(allDeps["react"] ||
+                allDeps["next"] ||
+                allDeps["@remix-run/react"] ||
+                allDeps["@xyflow/react"] ||
+                allDeps["preact"]);
+            if (hasReact && hasJsxFilesShallow(pkgRoot, readdirSync)) {
+                enabled.push(...REACT_TOOLS);
+            }
             const hasHono = !!(allDeps["hono"] ||
                 allDeps["@hono/zod-openapi"] ||
                 allDeps["@hono/node-server"] ||
                 allDeps["hono-openapi"] ||
                 allDeps["chanfana"]);
-            if (hasHono) {
-                toEnable.push(...HONO_TOOLS);
+            if (hasHono)
+                enabled.push(...HONO_TOOLS);
+            // Prisma / Drizzle — schema-driven DB stacks. analyze_prisma_schema
+            // works for Prisma; migration_lint (squawk) works for any SQL migration
+            // dir, useful for both. We don't condition on @prisma/client because
+            // it's runtime-only — the schema work belongs to the `prisma` CLI dep.
+            const hasPrismaLike = !!(allDeps["prisma"] ||
+                allDeps["@prisma/client"] ||
+                allDeps["drizzle-kit"] ||
+                allDeps["drizzle-orm"]);
+            if (hasPrismaLike)
+                enabled.push(...PRISMA_TOOLS);
+            // npm/yarn/pnpm workspaces field — content-based monorepo signal.
+            // Complements the file-based signals (pnpm-workspace.yaml, lerna.json,
+            // nx.json, turbo.json) so plain `"workspaces": [...]` setups also fire.
+            const hasWorkspaces = Array.isArray(pkg.workspaces) ||
+                (pkg.workspaces && typeof pkg.workspaces === "object" &&
+                    Array.isArray(pkg.workspaces.packages));
+            if (hasWorkspaces)
+                enabled.push(...MONOREPO_TOOLS);
+        }
+        catch {
+            /* malformed package.json */
+        }
+        return enabled;
+    };
+    // Root-level detection (existing behavior — unchanged for flat repos).
+    toEnable.push(...detectFromPackageJson(cwd));
+    // Monorepo workspace walk (Task 15). When monorepo detected at cwd, union
+    // each workspace's framework signals into the auto-load set. Hard cap at 50
+    // workspaces to bound startup cost (sync FS reads at module-init time);
+    // very large monorepos (>50 packages) fall back to root-only auto-load —
+    // discover_tools / describe_tools still work for any framework tool needed
+    // at query time.
+    if (killSwitchOff) {
+        try {
+            const { resolveWorkspaces } = await import("./storage/workspace-resolver.js");
+            const resolved = await resolveWorkspaces(cwd);
+            if (resolved && resolved.workspaces.length > 0 && resolved.workspaces.length <= 50) {
+                for (const ws of resolved.workspaces) {
+                    toEnable.push(...detectFromPackageJson(ws.root));
+                }
             }
         }
-        catch { /* malformed package.json */ }
+        catch {
+            /* monorepo resolver failure is non-fatal; flat-repo behavior preserved */
+        }
     }
     return toEnable;
 }
@@ -487,6 +619,7 @@ export const CORE_TOOL_NAMES = new Set([
     "discover_tools", // meta: discovers remaining hidden tools
     "describe_tools", // meta: full schema for hidden tools
     "plan_turn", // meta: route query to best tools/symbols/files
+    "initial_instructions", // meta: Serena-style onboarding tool, "must call first"
     "get_session_snapshot", // session: compaction survival
     "analyze_project", // project profile
     "get_extractor_versions", // cache invalidation
@@ -526,11 +659,15 @@ const TOOL_DEFINITIONS = [
             path: z.string().describe("Absolute path to the folder to index"),
             incremental: zBool().describe("Only re-index changed files"),
             include_paths: z.union([z.array(z.string()), z.string().transform((s) => JSON.parse(s))]).optional().describe("Glob patterns to include. Can be passed as JSON string."),
+            max_files: z.number().int().positive().optional().describe("Cap on files indexed. Default 50000 (or CODESIFT_MAX_FILES env). Walker stops at this count and returns partial results — protects against OOM on huge repos. Use include_paths to scope instead of raising this for large vendored trees."),
+            watch: zBool().describe("Whether to set up a chokidar file watcher for incremental updates after indexing. Default true. Pass false for bulk/CI indexing scenarios — file watchers consume system file descriptors (1+ per repo on macOS FSEvents); indexing many repos with watchers active can exhaust the system file table (ENFILE)."),
         })),
         handler: async (args) => {
             const result = await indexFolder(args.path, {
                 incremental: args.incremental,
                 include_paths: args.include_paths,
+                max_files: args.max_files,
+                watch: args.watch,
             });
             // Auto-enable framework tools based on indexed path (not CWD)
             try {
@@ -696,15 +833,40 @@ const TOOL_DEFINITIONS = [
             auto_group: zBool().describe("Auto group_by_file when >50 matches."),
             ranked: z.boolean().optional().describe("Classify hits by containing symbol and rank by centrality"),
         })),
-        handler: (args) => searchText(args.repo, args.query, {
-            regex: args.regex,
-            context_lines: args.context_lines,
-            file_pattern: args.file_pattern,
-            max_results: args.max_results,
-            group_by_file: args.group_by_file,
-            auto_group: args.auto_group,
-            ranked: args.ranked,
-        }),
+        handler: async (args) => {
+            const result = await searchText(args.repo, args.query, {
+                regex: args.regex,
+                context_lines: args.context_lines,
+                file_pattern: args.file_pattern,
+                max_results: args.max_results,
+                group_by_file: args.group_by_file,
+                auto_group: args.auto_group,
+                ranked: args.ranked,
+            });
+            // Zero-result hint: 41% of search_text calls return nothing in telemetry.
+            // Suggest the most likely fix based on query shape so the agent doesn't
+            // burn 2-3 follow-up turns guessing.
+            const isEmpty = (Array.isArray(result) && result.length === 0)
+                || (typeof result === "string" && result.length === 0);
+            if (isEmpty) {
+                const q = args.query;
+                const fp = args.file_pattern;
+                const looksLikeSymbol = /::|->|\.[a-z][a-zA-Z0-9_]*\(/.test(q)
+                    || /^(class|function|def|fn|interface|type)\s+\w/.test(q)
+                    || (/^[A-Z][a-zA-Z0-9_]+$|^[a-z][a-zA-Z0-9_]+$/.test(q.trim()) && !q.includes(" "));
+                const hints = ["No matches."];
+                if (looksLikeSymbol)
+                    hints.push("Query looks like a symbol — try search_symbols(query=...) instead.");
+                if (fp)
+                    hints.push(`Try without file_pattern="${fp}" to widen scope.`);
+                if (args.regex === true)
+                    hints.push("Try regex=false (literal) — escapes may be off.");
+                if (!fp && !looksLikeSymbol)
+                    hints.push("Try a shorter substring, or add file_pattern= to scope.");
+                return { matches: [], hint: hints.join(" ") };
+            }
+            return result;
+        },
     },
     // --- Outline ---
     {
@@ -792,10 +954,19 @@ const TOOL_DEFINITIONS = [
             const opts = {};
             if (args.include_related != null)
                 opts.include_related = args.include_related;
-            const result = await getSymbol(args.repo, args.symbol_id, opts);
+            const symbolId = args.symbol_id;
+            const result = await getSymbol(args.repo, symbolId, opts);
             if (!result) {
+                // Telemetry: 24% of get_symbol calls return null (hallucinated IDs).
+                // Suggest closest matches by name so the agent doesn't burn turns guessing.
+                const { findSimilarSymbols } = await import("./tools/symbol-tools.js");
+                const similar = await findSimilarSymbols(args.repo, symbolId, 3);
+                if (similar.length > 0) {
+                    const suggestions = similar.map((s) => `  ${s.id}  (${s.kind} ${s.name} @ ${s.file}:${s.start_line})`).join("\n");
+                    return `Symbol "${symbolId}" not found. Did you mean:\n${suggestions}`;
+                }
                 const hint = await checkTextStubHint(args.repo, "get_symbol", true);
-                return hint ?? null;
+                return hint ?? `Symbol "${symbolId}" not found. Use search_symbols(query=...) to discover available IDs.`;
             }
             let text = await formatSymbolCompact(result.symbol);
             if (result.related && result.related.length > 0) {
@@ -817,10 +988,31 @@ const TOOL_DEFINITIONS = [
             ]).describe("Array of symbol identifiers. Can be passed as JSON string."),
         })),
         handler: async (args) => {
-            const syms = await getSymbols(args.repo, args.symbol_ids);
+            const ids = args.symbol_ids;
+            const syms = await getSymbols(args.repo, ids);
             const output = await formatSymbolsCompact(syms);
+            // Surface fuzzy suggestions for missing IDs (telemetry: 26% zero rate).
+            let suggestions = "";
+            if (syms.length < ids.length) {
+                const foundIds = new Set(syms.map((s) => s.id));
+                const missing = ids.filter((id) => !foundIds.has(id));
+                if (missing.length > 0) {
+                    const { findSimilarSymbols } = await import("./tools/symbol-tools.js");
+                    const lines = [];
+                    for (const m of missing.slice(0, 5)) {
+                        const sims = await findSimilarSymbols(args.repo, m, 2);
+                        if (sims.length > 0) {
+                            lines.push(`  ${m} → ${sims.map((s) => s.id).join(", ")}`);
+                        }
+                        else {
+                            lines.push(`  ${m} → no similar symbols`);
+                        }
+                    }
+                    suggestions = `\n\n--- not found (${missing.length}) — suggestions ---\n${lines.join("\n")}`;
+                }
+            }
             const hint = await checkTextStubHint(args.repo, "get_symbols", syms.length === 0);
-            return hint ? hint + output : output;
+            return (hint ? hint + output : output) + suggestions;
         },
     },
     {
@@ -1583,6 +1775,9 @@ const TOOL_DEFINITIONS = [
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
             focus: z.string().optional().describe("Scope to directory (e.g., 'src/tools')"),
             output_dir: z.string().optional().describe("Output directory (default: {repo_root}/.codesift/wiki)"),
+            journal_mode: z.enum(["skip", "refresh-overview", "append", "full"]).optional().default("skip").describe("Journal integration mode (default: skip)"),
+            journal_since_ref: z.string().optional().describe("git-relative ref for journal_mode=append (e.g., '2 weeks ago' or ISO date)"),
+            journal_bulk_fill: z.boolean().optional().describe("Bulk-fill all phases when journal_mode=full"),
         })),
         handler: async (args) => {
             const opts = {};
@@ -1590,10 +1785,39 @@ const TOOL_DEFINITIONS = [
                 opts.focus = args.focus;
             if (args.output_dir !== undefined)
                 opts.output_dir = args.output_dir;
+            if (args.journal_mode !== undefined)
+                opts.journal_mode = args.journal_mode;
+            if (args.journal_since_ref !== undefined)
+                opts.journal_since_ref = args.journal_since_ref;
+            if (args.journal_bulk_fill !== undefined)
+                opts.journal_bulk_fill = args.journal_bulk_fill;
             const result = await generateWiki(args.repo, opts);
             return JSON.stringify(result, null, 2);
         },
     },
+    {
+        name: "journal_append",
+        category: "reporting",
+        searchHint: "journal append phases git commits since wiki journal",
+        description: "Append new journal phases for commits since the given git ref. Dispatches to runJournalAppend.",
+        schema: lazySchema(() => ({
+            since: z.string().describe("git-relative string like '2 weeks ago' or ISO date"),
+            max_cost_usd: z.number().optional().default(2.0).describe("Maximum LLM cost cap in USD (default: 2.0)"),
+            dry_run: z.boolean().optional().default(false).describe("Plan phases without writing files (default: false)"),
+        })),
+        handler: async (args) => {
+            const { runJournalAppend } = await import("./tools/journal-generator.js");
+            const opts = {
+                cwd: process.cwd(),
+                outputDir: ".codesift/wiki",
+                since: args.since,
+            };
+            if (args.dry_run !== undefined)
+                opts.dryRun = args.dry_run;
+            const r = await runJournalAppend(opts);
+            return JSON.stringify(r, null, 2);
+        },
+    },
     // --- Conversations ---
     {
         name: "index_conversations",
@@ -1650,6 +1874,85 @@ const TOOL_DEFINITIONS = [
             return formatConversations(result);
         },
     },
+    // --- Monorepo Workspaces (Tasks 8-11 of monorepo workspace intelligence plan) ---
+    {
+        name: "list_workspaces",
+        category: "analysis",
+        searchHint: "monorepo workspace list packages turbo pnpm yarn npm",
+        description: "List workspace packages for a JS/TS monorepo (Turbo / pnpm / yarn / npm / Nx). Returns shape-stable empty result on flat repos.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+        })),
+        handler: async (args) => {
+            const { listWorkspacesHandler } = await import("./tools/workspace-tools.js");
+            return listWorkspacesHandler(args.repo ? { repo: args.repo } : {});
+        },
+    },
+    {
+        name: "workspace_graph",
+        category: "analysis",
+        searchHint: "monorepo workspace dependency graph turbo nx mermaid dot",
+        description: "Build the workspace-to-workspace dependency DAG of a monorepo. Output formats: json (default), mermaid, dot.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            format: z.enum(["json", "mermaid", "dot"]).optional().describe("Output format (default: json)"),
+        })),
+        handler: async (args) => {
+            const { workspaceGraphHandler } = await import("./tools/workspace-tools.js");
+            const opts = {};
+            if (args.repo)
+                opts.repo = args.repo;
+            if (args.format)
+                opts.format = args.format;
+            return workspaceGraphHandler(opts);
+        },
+    },
+    {
+        name: "affected_workspaces",
+        category: "analysis",
+        searchHint: "monorepo affected workspaces git diff impact transitive turbo nx",
+        description: "Compute affected workspaces for a git diff. File changes -> containing workspace -> reverse-dep walk. Lockfile-only commits surface separately and never fan out.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            since: z.string().describe("Git ref to diff against (e.g. HEAD~1, main, <sha>)"),
+            include_transitive: zBool().describe("Include transitive reverse-deps (default: true)"),
+        })),
+        handler: async (args) => {
+            const { affectedWorkspacesHandler } = await import("./tools/workspace-tools.js");
+            const opts = {
+                since: args.since,
+            };
+            if (args.repo)
+                opts.repo = args.repo;
+            if (args.include_transitive !== undefined)
+                opts.include_transitive = args.include_transitive;
+            return affectedWorkspacesHandler(opts);
+        },
+    },
+    {
+        name: "workspace_boundaries",
+        category: "analysis",
+        searchHint: "monorepo boundary rules workspace import violations enforce",
+        description: "Enforce workspace-level import boundaries. Walks ALL cross-workspace import edges (relative + bare/tsconfig-alias) and reports rule violations.",
+        schema: lazySchema(() => ({
+            repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            rules: z
+                .array(z.object({
+                from_workspace: z.string().describe("Workspace name OR glob (e.g. 'apps/*')"),
+                cannot_import_workspaces: z.array(z.string()).describe("Names, globs, or negation entries"),
+            }))
+                .describe("Workspace boundary rules"),
+        })),
+        handler: async (args) => {
+            const { workspaceBoundariesHandler } = await import("./tools/workspace-tools.js");
+            const opts = {
+                rules: args.rules,
+            };
+            if (args.repo)
+                opts.repo = args.repo;
+            return workspaceBoundariesHandler(opts);
+        },
+    },
     // --- Security ---
     {
         name: "scan_secrets",
@@ -2581,6 +2884,16 @@ const TOOL_DEFINITIONS = [
         handler: async (args) => {
             const result = await indexStatus(args.repo);
             if (!result.indexed) {
+                // Stale: index file exists but extractor_version drifted. Distinct
+                // from "never indexed" — agents seeing "STALE" know that re-running
+                // index_folder will fix it without wondering whether earlier indexing
+                // attempts silently failed.
+                if (result.stale) {
+                    return (`index_status: STALE — extractor_version_mismatch ` +
+                        `(${result.stale.language}: indexed at ${result.stale.actual_version}, ` +
+                        `current ${result.stale.expected_version}). ` +
+                        `Run index_folder to refresh.`);
+                }
                 // If no repo specified, list available repos so the agent can pick one
                 if (!args.repo) {
                     const { listAllRepos } = await import("./tools/index-tools.js");
@@ -2752,15 +3065,28 @@ const TOOL_DEFINITIONS = [
     {
         name: "nest_audit",
         category: "nestjs",
-        searchHint: "nestjs audit analysis comprehensive module di guard route lifecycle pattern graphql websocket schedule typeorm microservice hook onModuleInit onApplicationBootstrap shutdown dependency graph circular import boundary injection provider constructor inject cycle interceptor pipe filter middleware chain security endpoint api map inventory list all params resolver query mutation subscription apollo gateway subscribemessage socketio realtime event cron interval timeout scheduled job task onevent listener entity relation onetomany manytoone database schema messagepattern eventpattern kafka rabbitmq nats transport request pipeline handler execution flow visualization bull bullmq queue processor process background worker scope transient singleton performance escalation swagger openapi documentation apiproperty apioperation apiresponse contract extract",
-        description: "One-call NestJS architecture audit: modules, DI, guards, routes, lifecycle, patterns, GraphQL, WebSocket, schedule, TypeORM, microservices.",
+        searchHint: "nestjs audit analysis comprehensive module di guard route lifecycle pattern graphql websocket schedule typeorm microservice hook onModuleInit onApplicationBootstrap shutdown dependency graph circular import boundary injection provider constructor inject cycle interceptor pipe filter middleware chain security endpoint api map inventory list all params resolver query mutation subscription apollo gateway subscribemessage socketio realtime event cron interval timeout scheduled job task onevent listener entity relation onetomany manytoone database schema messagepattern eventpattern kafka rabbitmq nats transport request pipeline handler execution flow visualization bull bullmq queue processor process background worker scope transient singleton performance escalation swagger openapi documentation apiproperty apioperation apiresponse contract extract workspace monorepo",
+        description: "One-call NestJS architecture audit: modules, DI, guards, routes, lifecycle, patterns, GraphQL, WebSocket, schedule, TypeORM, microservices. Pass workspace=<name|path> in monorepos to scope to a single workspace.",
         schema: lazySchema(() => ({
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace: z.string().optional().describe("Monorepo workspace name or path. Scopes the audit to that workspace's files."),
             checks: z.string().optional().describe("Comma-separated checks (default: all). Options: modules,routes,di,guards,lifecycle,patterns,graphql,websocket,schedule,typeorm,microservice"),
         })),
         handler: async (args) => {
+            const { resolveWorkspaceScope } = await import("./tools/workspace-scope-helper.js");
             const checks = args.checks?.split(",").map((s) => s.trim()).filter(Boolean);
-            return nestAudit(args.repo ?? "", checks ? { checks } : undefined);
+            const scope = await resolveWorkspaceScope(args.repo ?? "", args.workspace, "nestjs");
+            if ("error" in scope) {
+                return { error: scope.error, input: scope.input, available: scope.available };
+            }
+            const opts = {};
+            if (checks)
+                opts.checks = checks;
+            if (scope.rootPaths.length > 0) {
+                // Pass first matched workspace path through the existing file_pattern-style hook
+                opts.file_pattern = `${scope.rootPaths[0]}/**`;
+            }
+            return nestAudit(args.repo ?? "", opts);
         },
     },
     // --- Agent config audit ---
@@ -3099,18 +3425,27 @@ const TOOL_DEFINITIONS = [
     {
         name: "astro_audit",
         category: "analysis",
-        searchHint: "astro meta audit full health check score gates recommendations islands hydration routes config actions content migration patterns",
-        description: "One-call Astro project health check: runs all 7 Astro tools + 13 Astro patterns in parallel, returns unified {score, gates, sections, recommendations}. Mirrors react_quickstart pattern.",
+        searchHint: "astro meta audit full health check score gates recommendations islands hydration routes config actions content migration patterns workspace monorepo",
+        description: "One-call Astro project health check: runs all 7 Astro tools + 13 Astro patterns in parallel, returns unified {score, gates, sections, recommendations}. Pass workspace=<name|path> in monorepos to scope to a single workspace.",
         schema: lazySchema(() => ({
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
+            workspace: z.string().optional().describe("Monorepo workspace name or path. Scopes the audit to that workspace."),
             skip: z.array(z.string()).optional().describe("Sections to skip: config, hydration, routes, actions, content, migration, patterns"),
         })),
         handler: async (args) => {
+            const { resolveWorkspaceScope } = await import("./tools/workspace-scope-helper.js");
+            const scope = await resolveWorkspaceScope(args.repo ?? "", args.workspace, "astro");
+            if ("error" in scope) {
+                return { error: scope.error, input: scope.input, available: scope.available };
+            }
             const opts = {};
             if (args.repo != null)
                 opts.repo = args.repo;
             if (args.skip != null)
                 opts.skip = args.skip;
+            if (scope.rootPaths.length > 0) {
+                opts.file_pattern = `${scope.rootPaths[0]}/**`;
+            }
             return await astroAudit(opts);
         },
     },
@@ -3140,16 +3475,29 @@ const TOOL_DEFINITIONS = [
     {
         name: "analyze_hono_app",
         category: "analysis",
-        searchHint: "hono overview analyze app routes middleware runtime env bindings rpc",
-        description: "Complete Hono application overview: routes grouped by method/scope, middleware map, context vars, OpenAPI status, RPC exports (flags Issue #3869 slow pattern), runtime, env bindings. One call for full project analysis.",
+        searchHint: "hono overview analyze app routes middleware runtime env bindings rpc workspace monorepo",
+        description: "Complete Hono application overview: routes grouped by method/scope, middleware map, context vars, OpenAPI status, RPC exports (flags Issue #3869 slow pattern), runtime, env bindings. Pass workspace=<name|path> in monorepos to scope to a single workspace.",
         schema: lazySchema(() => ({
             repo: z.string().optional().describe("Repository identifier (default: auto-detected from CWD)"),
             entry_file: z.string().optional().describe("Hono entry file (auto-detected if omitted)"),
+            workspace: z.string().optional().describe("Monorepo workspace name or path (e.g. '@org/api' or 'apps/api'). Scopes Hono entry resolution to that workspace."),
             force_refresh: z.boolean().optional().describe("Clear cache and rebuild"),
         })),
         handler: async (args) => {
             const { analyzeHonoApp } = await import("./tools/hono-analyze-app.js");
-            return await analyzeHonoApp(args.repo, args.entry_file, args.force_refresh);
+            const { resolveWorkspaceScope } = await import("./tools/workspace-scope-helper.js");
+            const repo = args.repo;
+            const scope = await resolveWorkspaceScope(repo, args.workspace, "hono");
+            if ("error" in scope) {
+                return { error: scope.error, input: scope.input, available: scope.available };
+            }
+            // If workspace scoping resolved to a path, prefer it as entry_file root hint.
+            let entry = args.entry_file;
+            if (!entry && scope.rootPaths.length === 1) {
+                // Hono's entry resolver searches src/index.ts under the path provided
+                entry = scope.rootPaths[0];
+            }
+            return await analyzeHonoApp(repo, entry, args.force_refresh);
         },
     },
     {
@@ -3596,6 +3944,17 @@ const TOOL_DEFINITIONS = [
         },
     },
     // --- Discovery / concierge ---
+    {
+        name: "initial_instructions",
+        category: "meta",
+        searchHint: "initial instructions onboarding setup start session",
+        description: "IMPORTANT: Call this tool IMMEDIATELY after the user gives you a task, BEFORE any other tool calls. Returns CodeSift's full instruction manual which critically informs how to use the 146 code intelligence tools. Skipping this tool causes the agent to miss CodeSift's pre-built BM25 + semantic index and waste tokens on Grep/Read instead.",
+        schema: lazySchema(() => ({})),
+        handler: async () => {
+            const { CODESIFT_INSTRUCTIONS } = await import("./instructions.js");
+            return CODESIFT_INSTRUCTIONS;
+        },
+    },
     {
         name: "plan_turn",
         category: "discovery",