agent-orchestrator-mcp-server 0.2.5 → 0.4.1

package/README.md

@@ -23,7 +23,7 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 | Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                 |
 | -------------------------- | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_sessions`          | sessions      | read       | Search/list sessions with optional ID lookup, query, and status filter                                                                                      |
+| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                              |
 | `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                |
 | `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, stop conditions)                                                                                  |
 | `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                           |
@@ -59,7 +59,7 @@ Control which tools are available via the `TOOL_GROUPS` environment variable:
 | Group                    | Description                                                                                              |
 | ------------------------ | -------------------------------------------------------------------------------------------------------- |
 | `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs |
-| `sessions_readonly`      | Session tools (read only): search_sessions, get_session, get_configs, get_transcript_archive             |
+| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive       |
 | `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                     |
 | `notifications_readonly` | Notification tools (read only): get_notifications                                                        |
 | `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                 |
@@ -109,13 +109,14 @@ TOOL_GROUPS=sessions,notifications_readonly,triggers_readonly,health_readonly
 
 ### Environment Variables
 
-| Variable                      | Required | Description                                 | Default                                               |
-| ----------------------------- | -------- | ------------------------------------------- | ----------------------------------------------------- |
-| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API           | -                                                     |
-| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication                  | -                                                     |
-| `TOOL_GROUPS`                 | No       | Comma-separated list of enabled tool groups | `sessions,notifications,triggers,health` (all groups) |
-| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup      | `false`                                               |
-| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds        | `10000`                                               |
+| Variable                      | Required | Description                                                                                                                                                                                                                                   | Default                                               |
+| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API                                                                                                                                                                                                             | -                                                     |
+| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication                                                                                                                                                                                                                    | -                                                     |
+| `TOOL_GROUPS`                 | No       | Comma-separated list of enabled tool groups                                                                                                                                                                                                   | `sessions,notifications,triggers,health` (all groups) |
+| `ALLOWED_AGENT_ROOTS`         | No       | Comma-separated list of allowed agent root names. When set, constrains the server to only permit sessions with these specific agent roots and their exact default MCP servers. Also blocks `change_mcp_servers` and trigger creation/updates. | -                                                     |
+| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup                                                                                                                                                                                                        | `false`                                               |
+| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds                                                                                                                                                                                                          | `10000`                                               |
 
 ### Claude Desktop
 

package/build/index.js

@@ -34,6 +34,11 @@ function validateEnvironment() {
             description: 'Comma-separated list of tool groups to enable (sessions,sessions_readonly,notifications,notifications_readonly,triggers,triggers_readonly,health,health_readonly)',
             defaultValue: 'all groups enabled',
         },
+        {
+            name: 'ALLOWED_AGENT_ROOTS',
+            description: 'Comma-separated list of allowed agent root names. When set, only these agent roots are shown in get_configs and allowed in start_session (with their exact default MCP servers only)',
+            defaultValue: 'all agent roots allowed',
+        },
         {
             name: 'SKIP_HEALTH_CHECKS',
             description: 'Skip API connectivity check at startup (set to "true" to skip)',
@@ -72,6 +77,9 @@ function validateEnvironment() {
     if (process.env.TOOL_GROUPS) {
         logWarning('config', `Tool groups filter active: ${process.env.TOOL_GROUPS}`);
     }
+    if (process.env.ALLOWED_AGENT_ROOTS) {
+        logWarning('config', `Allowed agent roots filter active: ${process.env.ALLOWED_AGENT_ROOTS}`);
+    }
 }
 // =============================================================================
 // HEALTH CHECKS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.2.5",
+  "version": "0.4.1",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/allowed-agent-roots.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ALLOWED_AGENT_ROOTS constraint system.
+ *
+ * When the ALLOWED_AGENT_ROOTS environment variable is set (comma-separated list of agent root names),
+ * the server is constrained to only allow sessions using those specific agent roots
+ * with their exact default MCP server configurations.
+ *
+ * This provides a way to lock down the server to only permit preconfigured invocations.
+ */
+import type { AgentRootInfo } from './types.js';
+/**
+ * Parse the ALLOWED_AGENT_ROOTS environment variable into a list of allowed agent root names.
+ * Returns null if the env var is not set (meaning no restrictions).
+ */
+export declare function parseAllowedAgentRoots(envValue?: string): string[] | null;
+/**
+ * Filter agent roots to only include those in the allowed list.
+ * If allowedRoots is null, returns all agent roots (no filtering).
+ */
+export declare function filterAgentRoots(agentRoots: AgentRootInfo[], allowedRoots: string[] | null): AgentRootInfo[];
+export interface AgentRootValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate a start_session request against the allowed agent roots constraints.
+ *
+ * When ALLOWED_AGENT_ROOTS is set:
+ * - git_root must match one of the allowed agent roots
+ * - mcp_servers must exactly match the default_mcp_servers of that agent root
+ *   (no more, no less — any deviation is rejected)
+ *
+ * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
+ */
+export declare function validateAgentRootConstraints(allowedRoots: string[] | null, agentRoots: AgentRootInfo[], gitRoot?: string, mcpServers?: string[]): AgentRootValidationResult;
+//# sourceMappingURL=allowed-agent-roots.d.ts.map

package/shared/allowed-agent-roots.js

@@ -0,0 +1,86 @@
+/**
+ * ALLOWED_AGENT_ROOTS constraint system.
+ *
+ * When the ALLOWED_AGENT_ROOTS environment variable is set (comma-separated list of agent root names),
+ * the server is constrained to only allow sessions using those specific agent roots
+ * with their exact default MCP server configurations.
+ *
+ * This provides a way to lock down the server to only permit preconfigured invocations.
+ */
+/**
+ * Parse the ALLOWED_AGENT_ROOTS environment variable into a list of allowed agent root names.
+ * Returns null if the env var is not set (meaning no restrictions).
+ */
+export function parseAllowedAgentRoots(envValue) {
+    const value = envValue ?? process.env.ALLOWED_AGENT_ROOTS ?? '';
+    if (!value.trim()) {
+        return null; // No restrictions
+    }
+    const roots = value
+        .split(',')
+        .map((r) => r.trim())
+        .filter((r) => r.length > 0);
+    if (roots.length === 0) {
+        return null;
+    }
+    return roots;
+}
+/**
+ * Filter agent roots to only include those in the allowed list.
+ * If allowedRoots is null, returns all agent roots (no filtering).
+ */
+export function filterAgentRoots(agentRoots, allowedRoots) {
+    if (allowedRoots === null) {
+        return agentRoots;
+    }
+    return agentRoots.filter((root) => allowedRoots.includes(root.name));
+}
+/**
+ * Validate a start_session request against the allowed agent roots constraints.
+ *
+ * When ALLOWED_AGENT_ROOTS is set:
+ * - git_root must match one of the allowed agent roots
+ * - mcp_servers must exactly match the default_mcp_servers of that agent root
+ *   (no more, no less — any deviation is rejected)
+ *
+ * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
+ */
+export function validateAgentRootConstraints(allowedRoots, agentRoots, gitRoot, mcpServers) {
+    if (allowedRoots === null) {
+        return { valid: true };
+    }
+    // Find the matching agent root by git_root
+    const matchingRoot = agentRoots.find((root) => allowedRoots.includes(root.name) && root.git_root === gitRoot);
+    if (!matchingRoot) {
+        const allowedNames = allowedRoots.join(', ');
+        const allowedGitRoots = agentRoots
+            .filter((root) => allowedRoots.includes(root.name))
+            .map((root) => root.git_root);
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — only the following agent roots are permitted: ${allowedNames}. ` +
+                `The provided git_root "${gitRoot || '(not provided)'}" does not match any allowed agent root. ` +
+                (allowedGitRoots.length > 0
+                    ? `Allowed git_root values: ${allowedGitRoots.join(', ')}`
+                    : 'No matching agent roots found in configuration.'),
+        };
+    }
+    // Validate mcp_servers matches the default_mcp_servers exactly
+    const defaultServers = matchingRoot.default_mcp_servers ?? [];
+    const requestedServers = mcpServers ?? [];
+    const sortedDefault = [...defaultServers].sort();
+    const sortedRequested = [...requestedServers].sort();
+    const serversMatch = sortedDefault.length === sortedRequested.length &&
+        sortedDefault.every((s, i) => s === sortedRequested[i]);
+    if (!serversMatch) {
+        const defaultStr = defaultServers.length > 0 ? defaultServers.join(', ') : '(none)';
+        const requestedStr = requestedServers.length > 0 ? requestedServers.join(', ') : '(none)';
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — agent root "${matchingRoot.name}" must use its exact default MCP servers. ` +
+                `Expected: [${defaultStr}], but got: [${requestedStr}]. ` +
+                `You cannot add or remove MCP servers when ALLOWED_AGENT_ROOTS restrictions are active.`,
+        };
+    }
+    return { valid: true };
+}

package/shared/orchestrator-client/orchestrator-client.d.ts

@@ -36,7 +36,6 @@ export interface IAgentOrchestratorClient {
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
-        search_contents?: boolean;
         status?: SessionStatus;
         agent_type?: string;
         show_archived?: boolean;
@@ -146,6 +145,11 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     private timeoutMs;
     constructor(baseUrl: string, apiKey: string, timeoutMs?: number);
     private request;
+    /**
+     * Like request(), but reads the response as text and wraps it in a TranscriptResponse.
+     * Used for API endpoints that return raw text instead of JSON (e.g., transcript with format=text).
+     */
+    private requestText;
     listSessions(options?: {
         status?: SessionStatus;
         agent_type?: string;
@@ -154,7 +158,6 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
-        search_contents?: boolean;
         status?: SessionStatus;
         agent_type?: string;
         show_archived?: boolean;

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -111,7 +111,6 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             const paginatedSessions = sessions.slice(start, start + perPage);
             return {
                 query,
-                search_contents: options?.search_contents || false,
                 sessions: paginatedSessions,
                 pagination: {
                     page,

package/shared/orchestrator-client/orchestrator-client.js

@@ -98,6 +98,67 @@ export class AgentOrchestratorClient {
         }
         return response.json();
     }
+    /**
+     * Like request(), but reads the response as text and wraps it in a TranscriptResponse.
+     * Used for API endpoints that return raw text instead of JSON (e.g., transcript with format=text).
+     */
+    async requestText(method, path, body, queryParams) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (queryParams) {
+            Object.entries(queryParams).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, String(value));
+                }
+            });
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const options = {
+            method,
+            headers,
+            signal: controller.signal,
+        };
+        if (body && (method === 'POST' || method === 'PATCH' || method === 'PUT')) {
+            options.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(url.toString(), options);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorMessage;
+            try {
+                const errorJson = JSON.parse(errorText);
+                errorMessage = errorJson.message || errorJson.error || errorText;
+            }
+            catch {
+                errorMessage = errorText;
+            }
+            throw new Error(`API Error (${response.status}): ${errorMessage}`);
+        }
+        if (response.status === 204) {
+            return { transcript_text: '' };
+        }
+        const text = await response.text();
+        return { transcript_text: text };
+    }
     // Sessions
     async listSessions(options) {
         return this.request('GET', '/sessions', undefined, options);
@@ -234,6 +295,11 @@ export class AgentOrchestratorClient {
         });
     }
     async getTranscript(id, format = 'json') {
+        if (format === 'text') {
+            // The API returns raw text (not JSON) when format=text,
+            // so we must use response.text() instead of response.json()
+            return this.requestText('GET', `/sessions/${id}/transcript`, undefined, { format });
+        }
         return this.request('GET', `/sessions/${id}/transcript`, undefined, {
             format,
         });

package/shared/resources.js

@@ -67,7 +67,7 @@ export function createRegisterResources(clientFactory) {
                     },
                     toolGroups: {
                         sessions: 'All session tools (read + write): search, get, configs, start, action, enqueued messages',
-                        sessions_readonly: 'Session tools (read only): search_sessions, get_session, get_configs',
+                        sessions_readonly: 'Session tools (read only): quick_search_sessions, get_session, get_configs',
                         notifications: 'All notification tools (read + write): get, send, mark read, dismiss',
                         notifications_readonly: 'Notification tools (read only): get_notifications',
                         triggers: 'All trigger tools (read + write): search, create, update, delete, toggle',

package/shared/tools/action-session.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
 const PARAM_DESCRIPTIONS = {
     session_id: 'Session ID (numeric) or slug (string). Required for most actions. Not required for "refresh_all" and "bulk_archive".',
     action: 'Action to perform: "follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"',
@@ -146,6 +147,18 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Block change_mcp_servers when ALLOWED_AGENT_ROOTS is active
+                if (action === 'change_mcp_servers' && parseAllowedAgentRoots() !== null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "change_mcp_servers" action is not allowed when ALLOWED_AGENT_ROOTS is set. MCP servers are locked to the defaults configured for each allowed agent root.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 // Validate fork requires message_index
                 if (action === 'fork' && message_index === undefined) {
                     return {

package/shared/tools/action-trigger.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
 const ACTION_ENUM = ['create', 'update', 'delete', 'toggle'];
 export const ActionTriggerSchema = z.object({
     action: z.enum(ACTION_ENUM),
@@ -63,6 +64,18 @@ export function actionTriggerTool(_server, clientFactory) {
                 const validated = ActionTriggerSchema.parse(args);
                 const client = clientFactory();
                 const { action, id } = validated;
+                // Block create/update when ALLOWED_AGENT_ROOTS is active
+                if ((action === 'create' || action === 'update') && parseAllowedAgentRoots() !== null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: The "${action}" action is not allowed when ALLOWED_AGENT_ROOTS is set. Triggers cannot be created or modified because sessions are restricted to specific preconfigured agent roots and their default MCP servers.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 let result;
                 switch (action) {
                     case 'create': {

package/shared/tools/get-configs.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
+import { parseAllowedAgentRoots, filterAgentRoots } from '../allowed-agent-roots.js';
 export const GetConfigsSchema = z.object({
     force_refresh: z
         .boolean()
@@ -37,14 +38,14 @@ export function getConfigsTool(_server, clientFactory) {
                 // Use cached data if available and not forcing refresh
                 const cachedConfigs = getConfigsCache();
                 if (cachedConfigs !== null && !forceRefresh) {
-                    return formatResponse(cachedConfigs, true);
+                    return formatResponse(applyAgentRootFilter(cachedConfigs), true);
                 }
                 // Fetch fresh data using unified configs endpoint
                 const client = clientFactory();
                 const configs = await client.getConfigs();
-                // Update shared cache
+                // Update shared cache (store unfiltered data so filtering is always applied fresh)
                 setConfigsCache(configs);
-                return formatResponse(configs, false);
+                return formatResponse(applyAgentRootFilter(configs), false);
             }
             catch (error) {
                 return {
@@ -60,6 +61,16 @@ export function getConfigsTool(_server, clientFactory) {
         },
     };
 }
+function applyAgentRootFilter(configs) {
+    const allowedRoots = parseAllowedAgentRoots();
+    if (allowedRoots === null) {
+        return configs;
+    }
+    return {
+        ...configs,
+        agent_roots: filterAgentRoots(configs.agent_roots, allowedRoots),
+    };
+}
 function formatResponse(configs, fromCache) {
     const lines = [];
     // MCP Servers section
@@ -112,6 +123,7 @@ function formatResponse(configs, fromCache) {
     lines.push('');
     lines.push('- Use `name` values from **MCP Servers** in `start_session` `mcp_servers` parameter');
     lines.push('- Use `git_root` from **Agent Roots** to start sessions with preconfigured defaults');
+    lines.push('- If an **Agent Root** has a `default_subdirectory`, pass it as `subdirectory` in `start_session` — do not set `subdirectory` to arbitrary internal paths');
     lines.push('- Use `id` values from **Stop Conditions** in `start_session` `stop_condition` parameter');
     if (fromCache) {
         lines.push('');

package/shared/tools/search-sessions.d.ts

@@ -1,10 +1,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
-export declare const SearchSessionsSchema: z.ZodObject<{
+export declare const QuickSearchSessionsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNumber>;
     query: z.ZodOptional<z.ZodString>;
-    search_contents: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodOptional<z.ZodEnum<["waiting", "running", "needs_input", "failed", "archived"]>>;
     agent_type: z.ZodOptional<z.ZodString>;
     show_archived: z.ZodOptional<z.ZodBoolean>;
@@ -16,7 +15,6 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }, {
@@ -25,11 +23,10 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }>;
-export declare function searchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+export declare function quickSearchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;
     description: string;
     inputSchema: {
@@ -42,11 +39,7 @@ export declare function searchSessionsTool(_server: Server, clientFactory: () =>
             query: {
                 type: string;
                 maxLength: number;
-                description: "Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.";
-            };
-            search_contents: {
-                type: string;
-                description: "Also search within transcript contents. May be slow for sessions with large transcripts. Default: false";
+                description: "Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.";
             };
             status: {
                 type: string;

package/shared/tools/search-sessions.js

@@ -1,18 +1,16 @@
 import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     id: 'Get a specific session by ID. When provided, other filters are ignored.',
-    query: 'Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.',
-    search_contents: 'Also search within transcript contents. May be slow for sessions with large transcripts. Default: false',
+    query: 'Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.',
     status: 'Filter results by status. Options: "waiting", "running", "needs_input", "failed", "archived"',
     agent_type: 'Filter results by agent type.',
     show_archived: 'Include archived sessions in results. Default: false',
     page: 'Page number for pagination. Default: 1',
     per_page: 'Number of results per page (1-100). Default: 25',
 };
-export const SearchSessionsSchema = z.object({
+export const QuickSearchSessionsSchema = z.object({
     id: z.number().optional().describe(PARAM_DESCRIPTIONS.id),
     query: z.string().max(1000).optional().describe(PARAM_DESCRIPTIONS.query),
-    search_contents: z.boolean().optional().describe(PARAM_DESCRIPTIONS.search_contents),
     status: z
         .enum(['waiting', 'running', 'needs_input', 'failed', 'archived'])
         .optional()
@@ -22,11 +20,13 @@ export const SearchSessionsSchema = z.object({
     page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.page),
     per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.per_page),
 });
-const TOOL_DESCRIPTION = `Search for agent sessions in the Agent Orchestrator.
+const TOOL_DESCRIPTION = `Quick title-based search for agent sessions in the Agent Orchestrator.
+
+**Important:** This tool only searches session titles. It is NOT a full-text or semantic search across session contents/transcripts. Use this when you roughly know the session title you're looking for.
 
 **Use cases:**
 - Find a specific session by ID (set id parameter)
-- Search sessions by keyword in title/prompt (set query parameter)
+- Search sessions by title keyword (set query parameter)
 - List all sessions with optional status filter
 - Monitor sessions requiring attention (status: "needs_input")
 
@@ -66,9 +66,9 @@ function formatSession(session) {
     lines.push(`- **Updated:** ${session.updated_at}`);
     return lines.join('\n');
 }
-export function searchSessionsTool(_server, clientFactory) {
+export function quickSearchSessionsTool(_server, clientFactory) {
     return {
-        name: 'search_sessions',
+        name: 'quick_search_sessions',
         description: TOOL_DESCRIPTION,
         inputSchema: {
             type: 'object',
@@ -82,10 +82,6 @@ export function searchSessionsTool(_server, clientFactory) {
                     maxLength: 1000,
                     description: PARAM_DESCRIPTIONS.query,
                 },
-                search_contents: {
-                    type: 'boolean',
-                    description: PARAM_DESCRIPTIONS.search_contents,
-                },
                 status: {
                     type: 'string',
                     enum: ['waiting', 'running', 'needs_input', 'failed', 'archived'],
@@ -115,7 +111,7 @@ export function searchSessionsTool(_server, clientFactory) {
         },
         handler: async (args) => {
             try {
-                const validatedArgs = SearchSessionsSchema.parse(args);
+                const validatedArgs = QuickSearchSessionsSchema.parse(args);
                 const client = clientFactory();
                 // If ID is provided, get that specific session
                 if (validatedArgs.id !== undefined) {
@@ -133,9 +129,8 @@ export function searchSessionsTool(_server, clientFactory) {
                 let sessions;
                 let pagination;
                 if (validatedArgs.query) {
-                    // Use search endpoint
+                    // Use search endpoint (title-only search, no content search)
                     const response = await client.searchSessions(validatedArgs.query, {
-                        search_contents: validatedArgs.search_contents,
                         status: validatedArgs.status,
                         agent_type: validatedArgs.agent_type,
                         show_archived: validatedArgs.show_archived,

package/shared/tools/start-session.d.ts

@@ -65,7 +65,7 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
             };
             subdirectory: {
                 type: string;
-                description: "Subdirectory within the repository to focus on.";
+                description: string;
             };
             title: {
                 type: string;
@@ -107,13 +107,13 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
             type: string;
             text: string;
         }[];
-        isError?: undefined;
+        isError: boolean;
     } | {
         content: {
             type: string;
             text: string;
         }[];
-        isError: boolean;
+        isError?: undefined;
     }>;
 };
 //# sourceMappingURL=start-session.d.ts.map

package/shared/tools/start-session.js

@@ -1,10 +1,17 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots, validateAgentRootConstraints } from '../allowed-agent-roots.js';
+import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
 const PARAM_DESCRIPTIONS = {
     agent_type: 'Agent type for the session. Currently only "claude_code" is supported. Default: "claude_code"',
     prompt: 'Initial prompt for the agent. If provided, the agent job is automatically queued. Omit for a clone-only session.',
     git_root: 'Repository URL or local path. Examples: "https://github.com/example/repo.git", "/path/to/repo"',
     branch: 'Git branch to work on. Default: "main"',
-    subdirectory: 'Subdirectory within the repository to focus on.',
+    subdirectory: 'Subdirectory within the repository to use as the agent working directory. ' +
+        'This should match a preconfigured agent root default_subdirectory from get_configs — it defines ' +
+        'the root scope for the agent session. Do NOT use this to point at internal package directories ' +
+        '(e.g. "experimental/gcs" in a monorepo) as this blinds the agent to root-level configuration ' +
+        'like CLAUDE.md, build scripts, CI workflows, and monorepo tooling. If no agent root defines ' +
+        'a default_subdirectory, leave this unset.',
     title: 'STRONGLY RECOMMENDED: Always set a title — treat it as effectively required. ' +
         'The title appears in the AO web UI and push notifications, making sessions identifiable at a glance. ' +
         'Compose a short, descriptive title (under 70 characters) that captures what the session is doing ' +
@@ -113,6 +120,23 @@ export function startSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = StartSessionSchema.parse(args);
                 const client = clientFactory();
+                // Enforce ALLOWED_AGENT_ROOTS constraints if set
+                const allowedRoots = parseAllowedAgentRoots();
+                if (allowedRoots !== null) {
+                    // Ensure we have configs (fetch if not cached)
+                    let configs = getConfigsCache();
+                    if (!configs) {
+                        configs = await client.getConfigs();
+                        setConfigsCache(configs);
+                    }
+                    const validation = validateAgentRootConstraints(allowedRoots, configs.agent_roots, validatedArgs.git_root, validatedArgs.mcp_servers);
+                    if (!validation.valid) {
+                        return {
+                            content: [{ type: 'text', text: `Error starting session: ${validation.error}` }],
+                            isError: true,
+                        };
+                    }
+                }
                 const session = await client.createSession(validatedArgs);
                 const lines = [
                     `## Session Started Successfully`,

package/shared/tools.js

@@ -1,6 +1,6 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 // 13 tools across 4 domains
-import { searchSessionsTool } from './tools/search-sessions.js';
+import { quickSearchSessionsTool } from './tools/search-sessions.js';
 import { startSessionTool } from './tools/start-session.js';
 import { getSessionTool } from './tools/get-session.js';
 import { actionSessionTool } from './tools/action-session.js';
@@ -59,7 +59,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * All available tools with their group assignments.
  *
  * 14 tools across 4 domains:
- * - search_sessions: Search/list/get sessions by ID (sessions, read)
+ * - quick_search_sessions: Quick title-based search/list/get sessions by ID (sessions, read)
  * - get_session: Get detailed session info with optional logs/transcripts (sessions, read)
  * - get_configs: Fetch all static configuration (sessions, read)
  * - get_transcript_archive: Get transcript archive download URL and metadata (sessions, read)
@@ -76,7 +76,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  */
 const ALL_TOOLS = [
     // Session tools - read operations
-    { factory: searchSessionsTool, group: 'sessions', isWriteOperation: false },
+    { factory: quickSearchSessionsTool, group: 'sessions', isWriteOperation: false },
     { factory: getSessionTool, group: 'sessions', isWriteOperation: false },
     { factory: getConfigsTool, group: 'sessions', isWriteOperation: false },
     { factory: getTranscriptArchiveTool, group: 'sessions', isWriteOperation: false },

package/shared/types.d.ts

@@ -68,7 +68,6 @@ export interface SessionsResponse {
 }
 export interface SearchSessionsResponse {
     query: string;
-    search_contents: boolean;
     sessions: Session[];
     pagination: Pagination;
 }