crewly 1.20.436 → 1.20.437

package/dist/backend/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "eba65f5222082df4731cd741161afb6d8590b84a",
-  "builtAt": "2026-10-26T10:15:11.100Z"
+  "commit": "0325d3b3ba4216522326cbe59359c72df5760c4f",
+  "builtAt": "2026-10-26T10:49:46.811Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewly",
-  "version": "1.20.436",
+  "version": "1.20.437",
   "type": "module",
   "description": "Multi-agent orchestration platform for AI coding teams — coordinates Claude Code, Gemini CLI, and Codex agents with a real-time web dashboard",
   "workspaces": [

package/packages/crewly-agent/src/runtime/agent-runner.service.test.ts

@@ -253,6 +253,65 @@ describe('AgentRunnerService', () => {
     });
   });
 
+  describe('sub-agents (#1317)', () => {
+    const okResult = {
+      text: 'done',
+      steps: [{ toolCalls: [], toolResults: [] }],
+      usage: { inputTokens: 10, outputTokens: 5 },
+      finishReason: 'stop',
+    };
+
+    it('gives a normal agent spawn_subagent on top of the full tool set', async () => {
+      await runner.initialize();
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      await runner.run('hi');
+      const tools = mockGenerateText.mock.calls[0][0].tools as Record<string, unknown>;
+      expect(tools.spawn_subagent).toBeDefined();
+      expect(tools.report_to_parent).toBeUndefined();
+      expect(tools.send_message).toBeDefined();
+      expect(tools.read_file).toBeDefined();
+    });
+
+    it('gives a sub-agent only the confined file/search/shell tools plus report_to_parent', async () => {
+      const child = new AgentRunnerService(
+        {
+          ...baseConfig,
+          sessionName: 'test-session/sub-1',
+          projectPath: '/tmp/proj',
+          subagent: { cwd: '/tmp/proj', readOnly: false, depth: 1, parentSession: 'test-session' },
+        },
+        mockModelManager,
+        mockApiClient,
+      );
+      child._generateTextFn = mockGenerateText;
+      await child.initialize();
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      await child.run('task');
+      const tools = mockGenerateText.mock.calls[0][0].tools as Record<string, unknown>;
+      expect(tools.report_to_parent).toBeDefined();
+      expect(tools.read_file).toBeDefined();
+      expect(tools.bash_exec).toBeDefined();
+      expect(tools.spawn_subagent).toBeUndefined();
+      expect(tools.send_message).toBeUndefined();
+      expect(tools.delegate_task).toBeUndefined();
+      expect(tools.remember).toBeUndefined();
+      expect(child.getSubagentReport()).toBeNull();
+    });
+
+    it('folds a child\'s tokens into the parent\'s next run result and totals, once', async () => {
+      await runner.initialize();
+      runner.recordChildUsage({ input: 1000, output: 200, cachedInput: 50 });
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      const first = await runner.run('one');
+      expect(first.usage).toEqual({ input: 1010, output: 205, cachedInput: 50 });
+      expect(runner.getState().totalTokens).toEqual({ input: 1010, output: 205 });
+
+      mockGenerateText.mockResolvedValueOnce(okResult);
+      const second = await runner.run('two');
+      expect(second.usage).toEqual({ input: 10, output: 5, cachedInput: 0 });
+    });
+  });
+
   describe('serial queue', () => {
     beforeEach(async () => {
       await runner.initialize();

package/packages/crewly-agent/src/runtime/agent-runner.service.ts

@@ -17,6 +17,13 @@ import { ApprovalQueueService, type PendingApproval } from './approval-queue.ser
 import { OutputFilterService } from './output-filter.service.js';
 import { parseTextToolCalls, coerceArgs, resolveToolName, type TextToolCall, type SchemaLike } from './text-tool-calls.js';
 import { unverifiedDesktopWork } from './desktop-task.tool.js';
+import {
+  createSpawnSubagentTool,
+  createSubagentRegistry,
+  restrictToolsForSubagent,
+  type SubagentRegistry,
+  type SubagentReport,
+} from './subagent.js';
 import type { ToolDefinition, McpClientLike } from './types.js';
 import {
   type CrewlyAgentConfig,
@@ -477,6 +484,12 @@ export class AgentRunnerService {
   private outputFilter: OutputFilterService = new OutputFilterService();
   /** @internal Override for testing — replaces the AI SDK generateText call */
   _generateTextFn: GenerateTextFn | null = null;
+  /** Children spawned by this runner (#1317): how many run now, how many ever */
+  private readonly subagentRegistry: SubagentRegistry = createSubagentRegistry();
+  /** What this runner reported when it is itself a sub-agent */
+  private subagentReport: SubagentReport | null = null;
+  /** Tokens spent by children since the last run result, folded into the next one */
+  private childUsage = { input: 0, output: 0, cachedInput: 0 };
 
   /**
    * Create a new AgentRunnerService.
@@ -1070,7 +1083,9 @@ export class AgentRunnerService {
       },
     };
     const mcpTools = Object.keys(this.mcpToolDefs).length > 0 ? this.mcpToolDefs : undefined;
-    const tools = createTools(this.apiClient, this.config.sessionName, this.config.projectPath, callbacks, this.currentConversationId, this.currentSlackContext, mcpTools);
+    const tools = this.attachSubagentTools(
+      createTools(this.apiClient, this.config.sessionName, this.config.projectPath, callbacks, this.currentConversationId, this.currentSlackContext, mcpTools),
+    );
 
     // Create abort controller that merges external signal with internal control
     const runAbort = new AbortController();
@@ -1134,6 +1149,72 @@ export class AgentRunnerService {
     }
   }
 
+  /**
+   * Give a run its sub-agent tools (#1317).
+   *
+   * A sub-agent (config.subagent set) gets the restricted map — file, search
+   * and shell tools confined to its cwd, plus `report_to_parent` — and
+   * nothing that talks to people or spawns further helpers. Any other runner
+   * gets the full map plus `spawn_subagent`, whose children are built from
+   * this runner's config and counted in its registry and usage.
+   *
+   * @param tools - The full `createTools()` map
+   * @returns The map this run should see
+   */
+  private attachSubagentTools(tools: Record<string, ToolDefinition>): Record<string, ToolDefinition> {
+    if (this.config.subagent) {
+      return restrictToolsForSubagent(tools, this.config.subagent, (report) => { this.subagentReport = report; });
+    }
+    return {
+      ...tools,
+      spawn_subagent: createSpawnSubagentTool({
+        parentConfig: this.config,
+        registry: this.subagentRegistry,
+        createRunner: (config) => new AgentRunnerService(config, this.modelManager, this.apiClient),
+        onUsage: (usage) => this.recordChildUsage(usage),
+      }),
+    };
+  }
+
+  /**
+   * What this runner reported through `report_to_parent`, when it is a
+   * sub-agent; null for a parent or a child that never reported.
+   *
+   * @returns The last report
+   */
+  getSubagentReport(): SubagentReport | null {
+    return this.subagentReport;
+  }
+
+  /**
+   * Count a child's tokens against this runner (#1317): they are spent on
+   * this agent's behalf, so its ledger and spend cap must see them.
+   *
+   * @param usage - The child's usage
+   */
+  recordChildUsage(usage: { input: number; output: number; cachedInput: number }): void {
+    this.childUsage.input += usage.input;
+    this.childUsage.output += usage.output;
+    this.childUsage.cachedInput += usage.cachedInput;
+  }
+
+  /**
+   * Fold pending child usage into a run's reported usage and this runner's
+   * totals, then reset it. Context occupancy is not touched: a child's
+   * tokens never sat in this runner's context window.
+   *
+   * @param own - The run's own usage
+   * @returns Own plus children
+   */
+  private absorbChildUsage(own: { input: number; output: number; cachedInput: number }): { input: number; output: number; cachedInput: number } {
+    const child = this.childUsage;
+    if (child.input === 0 && child.output === 0 && child.cachedInput === 0) return own;
+    this.childUsage = { input: 0, output: 0, cachedInput: 0 };
+    this.state.totalTokens.input += child.input;
+    this.state.totalTokens.output += child.output;
+    return { input: own.input + child.input, output: own.output + child.output, cachedInput: own.cachedInput + child.cachedInput };
+  }
+
   /**
    * Resolve the wall-clock budget for one run.
    *
@@ -1637,7 +1718,7 @@ export class AgentRunnerService {
       return {
         text,
         steps: stepCount,
-        usage,
+        usage: this.absorbChildUsage(usage),
         toolCalls,
         finishReason,
         budgetWarning,
@@ -1818,7 +1899,7 @@ export class AgentRunnerService {
     return {
       text: finalText,
       steps: result.steps.length,
-      usage,
+      usage: this.absorbChildUsage(usage),
       toolCalls,
       finishReason: result.finishReason,
       budgetWarning,

package/packages/crewly-agent/src/runtime/subagent.test.ts

@@ -0,0 +1,466 @@
+// Short-lived sub-agents (#1317): tool restriction, config derivation, spawn tool.
+import { describe, it, expect, vi, type Mocked } from 'vitest';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import {
+  SUBAGENT_READ_TOOLS,
+  SUBAGENT_WRITE_TOOLS,
+  REPORT_TOOL_NAME,
+  SPAWN_TOOL_NAME,
+  buildSubagentConfig,
+  buildSubagentPrompt,
+  createSpawnSubagentTool,
+  createSubagentRegistry,
+  isInsideDir,
+  resolveSubagentModel,
+  resolveSubagentPath,
+  restrictToolsForSubagent,
+  summarizeSubagentRun,
+  type SubagentReport,
+  type SubagentRunner,
+} from './subagent.js';
+import { createTools, getToolNames, TOOL_SENSITIVITY } from './tool-registry.js';
+import { CrewlyApiClient } from './api-client.js';
+import { CREWLY_AGENT_DEFAULTS, WRITE_TOOLS, type AgentRunResult, type CrewlyAgentConfig, type ToolDefinition } from './types.js';
+
+const CWD = '/work/project';
+
+const parentConfig: CrewlyAgentConfig = {
+  model: { provider: 'deepseek', modelId: 'deepseek-chat', temperature: 0.2, maxTokens: 4096 },
+  maxSteps: 500,
+  sessionName: 'think-tank-kai',
+  apiBaseUrl: 'http://localhost:8787',
+  systemPrompt: 'You are Kai, the team lead.',
+  maxHistoryMessages: 40,
+  compactionThreshold: 0.8,
+  projectPath: CWD,
+  memberId: 'member-1',
+  mcpServers: { playwright: { command: 'npx', args: ['playwright-mcp'] } },
+};
+
+/** A run result with the given tool calls and no incompleteness. */
+function runResult(partial: Partial<AgentRunResult> = {}): AgentRunResult {
+  return {
+    text: 'final text',
+    steps: 3,
+    usage: { input: 100, output: 20, cachedInput: 5 },
+    toolCalls: [],
+    finishReason: 'stop',
+    ...partial,
+  };
+}
+
+/** A scripted child runner. */
+function fakeRunner(opts: {
+  result?: AgentRunResult | (() => Promise<AgentRunResult>);
+  report?: SubagentReport | null;
+  throwOn?: 'initialize' | 'run';
+}): SubagentRunner & { shutdown: ReturnType<typeof vi.fn>; run: ReturnType<typeof vi.fn> } {
+  const run = vi.fn(async (_m: string, _c?: string, _md?: Record<string, string>, _o?: { abortSignal?: AbortSignal }) => {
+    if (opts.throwOn === 'run') throw new Error('provider exploded');
+    return typeof opts.result === 'function' ? opts.result() : (opts.result ?? runResult());
+  });
+  return {
+    initialize: vi.fn(async () => {
+      if (opts.throwOn === 'initialize') throw new Error('no api key');
+    }),
+    run,
+    shutdown: vi.fn(async () => undefined),
+    getSubagentReport: () => opts.report ?? null,
+  };
+}
+
+describe('subagent', () => {
+  describe('isInsideDir / resolveSubagentPath', () => {
+    it('accepts the directory itself and anything beneath it', () => {
+      expect(isInsideDir(CWD, CWD)).toBe(true);
+      expect(isInsideDir(`${CWD}/src/a.ts`, CWD)).toBe(true);
+      expect(isInsideDir(`${CWD}/src/../src/b.ts`, CWD)).toBe(true);
+    });
+
+    it('rejects siblings, parents and look-alike prefixes', () => {
+      expect(isInsideDir('/work/project2/a.ts', CWD)).toBe(false);
+      expect(isInsideDir('/work', CWD)).toBe(false);
+      expect(isInsideDir(`${CWD}/../other/x`, CWD)).toBe(false);
+      expect(isInsideDir('/etc/passwd', CWD)).toBe(false);
+    });
+
+    it('resolves relative paths against cwd and expands ~ and $HOME like the file tools', () => {
+      expect(resolveSubagentPath('src/a.ts', CWD)).toBe(`${CWD}/src/a.ts`);
+      expect(resolveSubagentPath('/abs/x', CWD)).toBe('/abs/x');
+      expect(resolveSubagentPath('~/notes.md', CWD)).toBe(path.join(homedir(), 'notes.md'));
+      expect(resolveSubagentPath('$HOME/notes.md', CWD)).toBe(path.join(homedir(), 'notes.md'));
+    });
+  });
+
+  describe('restrictToolsForSubagent', () => {
+    let mockClient: Mocked<CrewlyApiClient>;
+    let full: Record<string, ToolDefinition>;
+
+    const policy = { cwd: CWD, readOnly: false, depth: 1, parentSession: 'think-tank-kai' };
+
+    function freshTools(): Record<string, ToolDefinition> {
+      mockClient = {
+        get: vi.fn<any>().mockResolvedValue({ success: false, data: null, status: 404 }),
+        post: vi.fn<any>(),
+        delete: vi.fn<any>(),
+      } as any;
+      return createTools(mockClient, 'think-tank-kai/sub-1', CWD);
+    }
+
+    it('keeps only file, search and shell tools plus report_to_parent', () => {
+      full = freshTools();
+      const restricted = restrictToolsForSubagent(full, policy, () => undefined);
+      const names = Object.keys(restricted).sort();
+      const expected = [...SUBAGENT_READ_TOOLS, ...SUBAGENT_WRITE_TOOLS, REPORT_TOOL_NAME].filter((n) => n === REPORT_TOOL_NAME || full[n]).sort();
+      expect(names).toEqual(expected);
+      expect(names).toContain('read_file');
+      expect(names).toContain('grep');
+      expect(names).toContain('bash_exec');
+      expect(names).toContain('edit_file');
+    });
+
+    it('has none of the communication, delegation, lifecycle, memory or ticket tools', () => {
+      full = freshTools();
+      const restricted = restrictToolsForSubagent(full, policy, () => undefined);
+      for (const forbidden of [
+        'send_message', 'reply_slack', 'broadcast', 'delegate_task', 'handoff_task', 'report_status', 'complete_task',
+        'get_tasks', 'start_agent', 'stop_agent', 'handle_agent_failure', 'remember', 'recall_memory', 'schedule_check',
+        'register_self', 'subscribe_event', 'get_audit_log', 'compact_memory', 'computer', 'desktop_task', 'git_commit',
+        SPAWN_TOOL_NAME,
+      ]) {
+        expect(restricted[forbidden], forbidden).toBeUndefined();
+      }
+    });
+
+    it('never passes through a spawn_subagent or MCP tool present in the input map', () => {
+      full = freshTools();
+      const withExtras: Record<string, ToolDefinition> = {
+        ...full,
+        [SPAWN_TOOL_NAME]: { description: 'x', inputSchema: {} as any, execute: async () => ({}) },
+        'playwright:click': { description: 'x', inputSchema: {} as any, execute: async () => ({}) },
+      };
+      const restricted = restrictToolsForSubagent(withExtras, policy, () => undefined);
+      expect(restricted[SPAWN_TOOL_NAME]).toBeUndefined();
+      expect(restricted['playwright:click']).toBeUndefined();
+    });
+
+    it('readOnly drops the shell and the write tools', () => {
+      full = freshTools();
+      const restricted = restrictToolsForSubagent(full, { ...policy, readOnly: true }, () => undefined);
+      const names = Object.keys(restricted);
+      for (const w of SUBAGENT_WRITE_TOOLS) expect(names).not.toContain(w);
+      for (const w of WRITE_TOOLS) expect(names).not.toContain(w);
+      expect(names).toContain('read_file');
+      expect(names).toContain(REPORT_TOOL_NAME);
+    });
+
+    it('refuses edit_file and write_file outside cwd and resolves relative paths inside it', async () => {
+      const inner = vi.fn(async () => ({ success: true }));
+      const tools: Record<string, ToolDefinition> = {
+        edit_file: { description: 'e', inputSchema: {} as any, execute: inner },
+        write_file: { description: 'w', inputSchema: {} as any, execute: inner },
+      };
+      const restricted = restrictToolsForSubagent(tools, policy, () => undefined);
+
+      const outside = await restricted.edit_file.execute({ file_path: '/etc/hosts', old_string: 'a', new_string: 'b' }) as Record<string, unknown>;
+      expect(outside.success).toBe(false);
+      expect(String(outside.error)).toMatch(/outside the sub-agent working directory/);
+      const climb = await restricted.write_file.execute({ file_path: '../sibling/x.ts', content: '' }) as Record<string, unknown>;
+      expect(climb.success).toBe(false);
+      const home = await restricted.write_file.execute({ file_path: '~/x.ts', content: '' }) as Record<string, unknown>;
+      expect(home.success).toBe(false);
+      expect(inner).not.toHaveBeenCalled();
+
+      await restricted.edit_file.execute({ file_path: 'src/a.ts', old_string: 'a', new_string: 'b' });
+      expect(inner).toHaveBeenCalledWith(expect.objectContaining({ file_path: `${CWD}/src/a.ts` }));
+    });
+
+    it('forces bash_exec into cwd when the model asks for a directory outside it', async () => {
+      const inner = vi.fn(async () => ({ success: true, stdout: '' }));
+      const tools: Record<string, ToolDefinition> = {
+        bash_exec: { description: 'b', inputSchema: {} as any, execute: inner },
+      };
+      const restricted = restrictToolsForSubagent(tools, policy, () => undefined);
+      await restricted.bash_exec.execute({ command: 'ls' });
+      expect(inner).toHaveBeenLastCalledWith({ command: 'ls', cwd: CWD });
+      await restricted.bash_exec.execute({ command: 'ls', cwd: '/' });
+      expect(inner).toHaveBeenLastCalledWith({ command: 'ls', cwd: CWD });
+      await restricted.bash_exec.execute({ command: 'ls', cwd: 'packages' });
+      expect(inner).toHaveBeenLastCalledWith({ command: 'ls', cwd: `${CWD}/packages` });
+    });
+
+    it('report_to_parent records the report and tells the child to stop', async () => {
+      const reports: SubagentReport[] = [];
+      const restricted = restrictToolsForSubagent({}, policy, (r) => reports.push(r));
+      const out = await restricted[REPORT_TOOL_NAME].execute({ summary: 'found 3 call sites', filesChanged: ['a.ts'] }) as Record<string, unknown>;
+      expect(out.success).toBe(true);
+      expect(String(out.note)).toMatch(/finish your turn/i);
+      expect(reports).toEqual([{ summary: 'found 3 call sites', filesChanged: ['a.ts'] }]);
+      expect(TOOL_SENSITIVITY[REPORT_TOOL_NAME]).toBe('safe');
+      expect(TOOL_SENSITIVITY[SPAWN_TOOL_NAME]).toBe('sensitive');
+      // Neither is a registry tool: the runner adds them per run.
+      expect(getToolNames()).not.toContain(SPAWN_TOOL_NAME);
+    });
+  });
+
+  describe('resolveSubagentModel', () => {
+    const parent = parentConfig.model;
+
+    it('keeps the parent model when none is asked for', () => {
+      expect(resolveSubagentModel(parent)).toEqual({ model: parent });
+      expect(resolveSubagentModel(parent, '  ')).toEqual({ model: parent });
+    });
+
+    it('swaps the model id on the same provider, or takes provider/modelId', () => {
+      expect(resolveSubagentModel(parent, 'deepseek-reasoner')).toEqual({ model: { ...parent, modelId: 'deepseek-reasoner' } });
+      expect(resolveSubagentModel(parent, 'google/gemini-3-flash-preview')).toEqual({
+        model: { ...parent, provider: 'google', modelId: 'gemini-3-flash-preview' },
+      });
+    });
+
+    it('refuses an unknown provider or an empty model id', () => {
+      expect(resolveSubagentModel(parent, 'acme/foo')).toEqual({ error: expect.stringMatching(/unknown model provider "acme"/) });
+      expect(resolveSubagentModel(parent, 'openai/')).toEqual({ error: expect.stringMatching(/names no model/) });
+    });
+  });
+
+  describe('buildSubagentConfig', () => {
+    it('derives a child config: own session name, short prompt, cwd as project path, policy, no MCP or member id', () => {
+      const built = buildSubagentConfig(parentConfig, { task: 'Find every caller of foo()' }, 2);
+      expect('config' in built).toBe(true);
+      const cfg = (built as { config: CrewlyAgentConfig }).config;
+      expect(cfg.sessionName).toBe('think-tank-kai/sub-2');
+      expect(cfg.role).toBe('subagent');
+      expect(cfg.model).toEqual(parentConfig.model);
+      expect(cfg.maxSteps).toBe(CREWLY_AGENT_DEFAULTS.SUBAGENT.MAX_STEPS);
+      expect(cfg.projectPath).toBe(CWD);
+      expect(cfg.apiBaseUrl).toBe(parentConfig.apiBaseUrl);
+      expect(cfg.systemPrompt).toBe(buildSubagentPrompt('think-tank-kai', CWD, false));
+      expect(cfg.systemPrompt).not.toContain('You are Kai');
+      expect(cfg.subagent).toEqual({ cwd: CWD, readOnly: false, depth: 1, parentSession: 'think-tank-kai' });
+      expect(cfg.mcpServers).toBeUndefined();
+      expect(cfg.memberId).toBeUndefined();
+      expect(cfg.evalMode).toBeUndefined();
+    });
+
+    it('caps maxSteps, resolves cwd under the project, and honours readOnly', () => {
+      const built = buildSubagentConfig(parentConfig, { task: 'x', maxSteps: 999, cwd: 'packages/ui', readOnly: true }, 1);
+      const cfg = (built as { config: CrewlyAgentConfig }).config;
+      expect(cfg.maxSteps).toBe(CREWLY_AGENT_DEFAULTS.SUBAGENT.MAX_STEPS_CAP);
+      expect(cfg.projectPath).toBe(`${CWD}/packages/ui`);
+      expect(cfg.subagent?.readOnly).toBe(true);
+      expect(cfg.systemPrompt).toMatch(/read-only tools/);
+      const small = buildSubagentConfig(parentConfig, { task: 'x', maxSteps: 5 }, 1);
+      expect((small as { config: CrewlyAgentConfig }).config.maxSteps).toBe(5);
+    });
+
+    it('refuses an empty or oversized task and a bad model', () => {
+      expect(buildSubagentConfig(parentConfig, { task: '   ' }, 1)).toEqual({ error: 'task is required' });
+      const huge = 'x'.repeat(CREWLY_AGENT_DEFAULTS.SUBAGENT.TASK_MAX_CHARS + 1);
+      expect(buildSubagentConfig(parentConfig, { task: huge }, 1)).toEqual({ error: expect.stringMatching(/too long/) });
+      expect(buildSubagentConfig(parentConfig, { task: 'x', model: 'nope/m' }, 1)).toEqual({ error: expect.stringMatching(/unknown model provider/) });
+    });
+
+    it('a child of a child would be depth 2 — but a child never gets the spawn tool, so this stays theoretical', () => {
+      const child = (buildSubagentConfig(parentConfig, { task: 'x' }, 1) as { config: CrewlyAgentConfig }).config;
+      const grandchild = (buildSubagentConfig(child, { task: 'y' }, 1) as { config: CrewlyAgentConfig }).config;
+      expect(grandchild.subagent?.depth).toBe(2);
+      expect(grandchild.sessionName).toBe('think-tank-kai/sub-1/sub-1');
+    });
+  });
+
+  describe('summarizeSubagentRun', () => {
+    it('zero working tool calls is did_nothing, even when the child reported', () => {
+      const out = summarizeSubagentRun(
+        runResult({ toolCalls: [{ toolName: REPORT_TOOL_NAME, args: { summary: 'all good' }, result: { success: true } }] }),
+        { summary: 'all good', filesChanged: [] },
+        's/sub-1',
+        10,
+        false,
+      );
+      expect(out.stoppedReason).toBe('did_nothing');
+      expect(out.success).toBe(false);
+      expect(out.toolCalls).toBe(0);
+      expect(out.summary).toBe('all good');
+    });
+
+    it('done: counts working calls, lists tool names, collects files from successful writes and the report', () => {
+      const out = summarizeSubagentRun(
+        runResult({
+          toolCalls: [
+            { toolName: 'grep', args: { pattern: 'foo' }, result: { success: true } },
+            { toolName: 'edit_file', args: { file_path: `${CWD}/a.ts` }, result: { success: true } },
+            { toolName: 'edit_file', args: { file_path: `${CWD}/b.ts` }, result: { success: false, error: 'not unique' } },
+            { toolName: 'write_file', args: { file_path: `${CWD}/c.ts` }, result: { success: true } },
+            { toolName: REPORT_TOOL_NAME, args: { summary: 'r' }, result: { success: true } },
+          ],
+        }),
+        { summary: 'changed a and c', filesChanged: [`${CWD}/d.md`] },
+        's/sub-1',
+        1234,
+        false,
+      );
+      expect(out.stoppedReason).toBe('done');
+      expect(out.success).toBe(true);
+      expect(out.toolCalls).toBe(4);
+      expect(out.toolNames).toEqual(['grep', 'edit_file', 'write_file']);
+      expect(out.filesChanged).toEqual([`${CWD}/a.ts`, `${CWD}/c.ts`, `${CWD}/d.md`]);
+      expect(out.usage).toEqual({ input: 100, output: 20, cachedInput: 5 });
+      expect(out.durationMs).toBe(1234);
+      expect(out.sessionName).toBe('s/sub-1');
+    });
+
+    it('maps incompleteness and timeouts, and falls back to the final text without a report', () => {
+      const calls = [{ toolName: 'read_file', args: { file_path: 'x' }, result: { success: true } }];
+      expect(summarizeSubagentRun(runResult({ toolCalls: calls, incomplete: { reason: 'steps-exhausted', detail: '', finishReason: 'tool-calls', recoveryAttempts: 0 } }), null, 's', 1, false).stoppedReason).toBe('steps_exhausted');
+      expect(summarizeSubagentRun(runResult({ toolCalls: calls, incomplete: { reason: 'truncated', detail: '', finishReason: 'length', recoveryAttempts: 3 } }), null, 's', 1, false).stoppedReason).toBe('incomplete');
+      const timed = summarizeSubagentRun(runResult({ toolCalls: calls }), null, 's', 1, true);
+      expect(timed.stoppedReason).toBe('timeout');
+      expect(timed.error).toMatch(/exceeded/);
+      expect(summarizeSubagentRun(runResult({ toolCalls: calls, text: '  the answer  ' }), null, 's', 1, false).summary).toBe('the answer');
+    });
+
+    it('caps a long summary', () => {
+      const long = 'y'.repeat(CREWLY_AGENT_DEFAULTS.SUBAGENT.SUMMARY_MAX_CHARS + 50);
+      const out = summarizeSubagentRun(runResult({ toolCalls: [{ toolName: 'grep', args: {}, result: {} }] }), { summary: long, filesChanged: [] }, 's', 1, false);
+      expect(out.summary.length).toBeLessThan(long.length);
+      expect(out.summary).toMatch(/\[truncated\]$/);
+    });
+  });
+
+  describe('createSpawnSubagentTool', () => {
+    it('runs a child with the task as its only message, returns its outcome, counts usage and disposes it', async () => {
+      const registry = createSubagentRegistry();
+      const child = fakeRunner({
+        result: runResult({ toolCalls: [{ toolName: 'grep', args: { pattern: 'x' }, result: { success: true } }] }),
+        report: { summary: 'two call sites: a.ts:10, b.ts:42', filesChanged: [] },
+      });
+      const createRunner = vi.fn(() => child);
+      const onUsage = vi.fn();
+      const tool = createSpawnSubagentTool({ parentConfig, registry, createRunner, onUsage });
+
+      const out = await tool.execute({ task: '  Find callers of foo()  ', readOnly: true }) as Record<string, unknown>;
+
+      expect(createRunner).toHaveBeenCalledTimes(1);
+      const cfg = createRunner.mock.calls[0]![0] as unknown as CrewlyAgentConfig;
+      expect(cfg.sessionName).toBe('think-tank-kai/sub-1');
+      expect(cfg.subagent).toEqual({ cwd: CWD, readOnly: true, depth: 1, parentSession: 'think-tank-kai' });
+      expect(child.initialize).toHaveBeenCalledTimes(1);
+      expect(child.run).toHaveBeenCalledTimes(1);
+      expect(child.run.mock.calls[0]![0]).toBe('Find callers of foo()');
+      expect(child.run.mock.calls[0]![3]?.abortSignal).toBeInstanceOf(AbortSignal);
+      expect(out.success).toBe(true);
+      expect(out.stoppedReason).toBe('done');
+      expect(out.summary).toBe('two call sites: a.ts:10, b.ts:42');
+      expect(out.sessionName).toBe('think-tank-kai/sub-1');
+      expect(onUsage).toHaveBeenCalledWith({ input: 100, output: 20, cachedInput: 5 });
+      expect(child.shutdown).toHaveBeenCalledTimes(1);
+      expect(registry).toEqual({ active: 0, spawned: 1 });
+    });
+
+    it('a child that made no tool call comes back as did_nothing, not success', async () => {
+      const tool = createSpawnSubagentTool({
+        parentConfig,
+        registry: createSubagentRegistry(),
+        createRunner: () => fakeRunner({ result: runResult({ toolCalls: [], text: 'I would look at the files.' }) }),
+      });
+      const out = await tool.execute({ task: 'look' }) as Record<string, unknown>;
+      expect(out.success).toBe(false);
+      expect(out.stoppedReason).toBe('did_nothing');
+      expect(out.summary).toBe('I would look at the files.');
+    });
+
+    it('numbers children in spawn order and refuses a fourth concurrent child', async () => {
+      const registry = createSubagentRegistry();
+      let release!: () => void;
+      const gate = new Promise<void>((r) => { release = r; });
+      const slow = () => fakeRunner({
+        result: async () => { await gate; return runResult({ toolCalls: [{ toolName: 'grep', args: {}, result: {} }] }); },
+      });
+      const createRunner = vi.fn(slow);
+      const tool = createSpawnSubagentTool({ parentConfig, registry, createRunner });
+
+      const running = [tool.execute({ task: 'a' }), tool.execute({ task: 'b' }), tool.execute({ task: 'c' })];
+      await Promise.resolve();
+      expect(registry.active).toBe(CREWLY_AGENT_DEFAULTS.SUBAGENT.MAX_CONCURRENT);
+      const refused = await tool.execute({ task: 'd' }) as Record<string, unknown>;
+      expect(refused.success).toBe(false);
+      expect(refused.stoppedReason).toBe('error');
+      expect(String(refused.error)).toMatch(/at most 3 sub-agents/);
+      expect(createRunner).toHaveBeenCalledTimes(3);
+
+      release();
+      const done = await Promise.all(running) as Array<Record<string, unknown>>;
+      expect(done.map((d) => d.sessionName)).toEqual(['think-tank-kai/sub-1', 'think-tank-kai/sub-2', 'think-tank-kai/sub-3']);
+      expect(registry).toEqual({ active: 0, spawned: 3 });
+
+      // A slot is free again.
+      const fifth = await createSpawnSubagentTool({ parentConfig, registry, createRunner: () => fakeRunner({ result: runResult({ toolCalls: [{ toolName: 'grep', args: {}, result: {} }] }) }) })
+        .execute({ task: 'e' }) as Record<string, unknown>;
+      expect(fifth.sessionName).toBe('think-tank-kai/sub-4');
+    });
+
+    it('a runner that throws yields error, still disposes the child and frees the slot', async () => {
+      const registry = createSubagentRegistry();
+      const child = fakeRunner({ throwOn: 'run' });
+      const tool = createSpawnSubagentTool({ parentConfig, registry, createRunner: () => child });
+      const out = await tool.execute({ task: 'boom' }) as Record<string, unknown>;
+      expect(out.success).toBe(false);
+      expect(out.stoppedReason).toBe('error');
+      expect(out.error).toBe('provider exploded');
+      expect(out.sessionName).toBe('think-tank-kai/sub-1');
+      expect(child.shutdown).toHaveBeenCalledTimes(1);
+      expect(registry.active).toBe(0);
+
+      const bad = fakeRunner({ throwOn: 'initialize' });
+      const out2 = await createSpawnSubagentTool({ parentConfig, registry, createRunner: () => bad }).execute({ task: 'x' }) as Record<string, unknown>;
+      expect(out2.error).toBe('no api key');
+      expect(bad.shutdown).toHaveBeenCalledTimes(1);
+    });
+
+    it('aborts the child when the wall-clock budget runs out and reports timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        const registry = createSubagentRegistry();
+        const child = fakeRunner({
+          result: () => new Promise<AgentRunResult>((_, reject) => {
+            // The real runner rejects on abort; mirror that.
+            setTimeout(() => reject(new Error('aborted')), 60_000);
+          }),
+        });
+        const tool = createSpawnSubagentTool({ parentConfig, registry, createRunner: () => child, timeoutMs: 1_000 });
+        const pending = tool.execute({ task: 'slow' });
+        await vi.advanceTimersByTimeAsync(1_000);
+        const signal = child.run.mock.calls[0]![3]?.abortSignal as AbortSignal;
+        expect(signal.aborted).toBe(true);
+        await vi.advanceTimersByTimeAsync(60_000);
+        const out = await pending as Record<string, unknown>;
+        expect(out.stoppedReason).toBe('timeout');
+        expect(out.success).toBe(false);
+        expect(child.shutdown).toHaveBeenCalledTimes(1);
+        expect(registry.active).toBe(0);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('refuses a bad spawn before creating any runner', async () => {
+      const createRunner = vi.fn();
+      const tool = createSpawnSubagentTool({ parentConfig, registry: createSubagentRegistry(), createRunner });
+      const out = await tool.execute({ task: 'x', model: 'nope/m' }) as Record<string, unknown>;
+      expect(out.success).toBe(false);
+      expect(String(out.error)).toMatch(/unknown model provider/);
+      expect(createRunner).not.toHaveBeenCalled();
+    });
+
+    it('describes when to use it and what did_nothing means, and declares its sensitivity', () => {
+      const tool = createSpawnSubagentTool({ parentConfig, registry: createSubagentRegistry(), createRunner: vi.fn() });
+      expect(tool.sensitivity).toBe('sensitive');
+      expect(tool.description).toMatch(/teammate instead/);
+      expect(tool.description).toMatch(/did_nothing/);
+      const parsed = (tool.inputSchema as any).safeParse({ task: 'x', maxSteps: 0 });
+      expect(parsed.success).toBe(false);
+    });
+  });
+});

package/packages/crewly-agent/src/runtime/subagent.ts

@@ -0,0 +1,510 @@
+/**
+ * Short-lived sub-agents for the in-process runtime (#1317, slice 1).
+ *
+ * A Claude Code agent can hand a bounded piece of work to a helper that does
+ * it and exits. Agents on the in-process runtime (DeepSeek, Gemini API, …)
+ * had no such thing: `createTools()` only knows named teammates. This module
+ * gives the parent a `spawn_subagent` tool that runs a fresh
+ * `AgentRunnerService` loop inside the same process with the task text as
+ * its only context, and gives that child a tool set the harness has cut
+ * down — no messaging, no delegation, no tickets, no nested spawning — plus
+ * `report_to_parent`. The child's result (summary, tool-call count, files
+ * changed, stop reason, usage) comes back as the tool result and the child
+ * runner is disposed. Nothing persists: no session, no TeamMember, no Slack
+ * identity.
+ *
+ * Scope is enforced here, not in the prompt (the lesson of #852 /
+ * specs/2026-10-03-subagent-guard.md): a forbidden tool is absent from the
+ * child's tool map, a write outside `cwd` is refused by a wrapper, and a
+ * child has no `spawn_subagent` because {@link restrictToolsForSubagent}
+ * never copies one.
+ */
+
+import { z } from 'zod';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import {
+  CREWLY_AGENT_DEFAULTS,
+  isModelProvider,
+  type AgentRunResult,
+  type CrewlyAgentConfig,
+  type ModelConfig,
+  type SubagentPolicy,
+  type ToolDefinition,
+} from './types.js';
+
+/** Tools a sub-agent may use in every mode: they read, they do not act. */
+export const SUBAGENT_READ_TOOLS: readonly string[] = ['read_file', 'glob', 'grep', 'git_status', 'git_diff', 'web_search'];
+
+/** Tools a sub-agent may use unless it was spawned `readOnly`. */
+export const SUBAGENT_WRITE_TOOLS: readonly string[] = ['bash_exec', 'edit_file', 'write_file'];
+
+/** Name of the tool a sub-agent reports with. */
+export const REPORT_TOOL_NAME = 'report_to_parent';
+
+/** Name of the tool a parent spawns with. */
+export const SPAWN_TOOL_NAME = 'spawn_subagent';
+
+/** Why a sub-agent stopped, as the parent sees it. */
+export type SubagentStopReason =
+  /** Ran to its natural end and did some work. */
+  | 'done'
+  /** Finished without a single working tool call — the parent must not read that as success. */
+  | 'did_nothing'
+  /** Hit its step cap with work outstanding. */
+  | 'steps_exhausted'
+  /** Hit the wall-clock budget. */
+  | 'timeout'
+  /** Ended early for another reason (truncated output, provider error…). */
+  | 'incomplete'
+  /** The runner threw. */
+  | 'error';
+
+/** What a sub-agent hands back through `report_to_parent`. */
+export interface SubagentReport {
+  /** The child's own account of what it found or changed. */
+  summary: string;
+  /** Files the child says it changed (merged with what its tool calls show). */
+  filesChanged: string[];
+}
+
+/** The tool result the parent receives. */
+export interface SubagentOutcome {
+  /** True only when `stoppedReason` is `done`. */
+  success: boolean;
+  stoppedReason: SubagentStopReason;
+  /** The child's report, else its final text (capped). */
+  summary: string;
+  /** Working tool calls the child made (`report_to_parent` not counted). */
+  toolCalls: number;
+  /** Distinct tool names used, so the parent can see what kind of work happened. */
+  toolNames: string[];
+  /** Files written or edited successfully, absolute paths. */
+  filesChanged: string[];
+  /** Tokens the child spent; also folded into the parent's usage. */
+  usage: { input: number; output: number; cachedInput: number };
+  /** Model steps the child took. */
+  steps: number;
+  /** The child's session name, `<parent>/sub-<n>`, for traces and logs. */
+  sessionName: string;
+  durationMs: number;
+  /** Set when `stoppedReason` is `error` or `timeout`. */
+  error?: string;
+}
+
+/** The arguments of `spawn_subagent`. */
+export interface SpawnSubagentInput {
+  task: string;
+  cwd?: string;
+  readOnly?: boolean;
+  maxSteps?: number;
+  /** `modelId` on the parent's provider, or `provider/modelId`. */
+  model?: string;
+}
+
+/**
+ * The part of `AgentRunnerService` a spawn needs. Injected so the tool can
+ * be tested with a scripted runner and so this module does not import the
+ * runner (which imports this module).
+ */
+export interface SubagentRunner {
+  initialize(): Promise<void>;
+  run(
+    message: string,
+    conversationId?: string,
+    metadata?: Record<string, string>,
+    options?: { abortSignal?: AbortSignal },
+  ): Promise<AgentRunResult>;
+  shutdown(): Promise<void>;
+  getSubagentReport(): SubagentReport | null;
+}
+
+/** Per-parent bookkeeping: how many children run now, how many ever. */
+export interface SubagentRegistry {
+  active: number;
+  spawned: number;
+}
+
+/**
+ * A fresh registry for one parent runner.
+ *
+ * @returns Zeroed counters
+ */
+export function createSubagentRegistry(): SubagentRegistry {
+  return { active: 0, spawned: 0 };
+}
+
+/**
+ * Whether `target` is `dir` or lies beneath it (after resolving both).
+ *
+ * @param target - Path to test
+ * @param dir - Directory that must contain it
+ * @returns True when inside
+ */
+export function isInsideDir(target: string, dir: string): boolean {
+  const rel = path.relative(path.resolve(dir), path.resolve(target));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Resolve a tool's path argument the way the file tools do (`~`, `$HOME`,
+ * relative to the working directory), so the containment check sees the
+ * same file the tool would touch.
+ *
+ * @param filePath - As the model passed it
+ * @param cwd - The sub-agent's working directory
+ * @returns Absolute path
+ */
+export function resolveSubagentPath(filePath: string, cwd: string): string {
+  const home = homedir();
+  let p = filePath;
+  if (p === '~' || p.startsWith('~/')) p = home + p.slice(1);
+  else if (p === '$HOME' || p.startsWith('$HOME/')) p = home + p.slice(5);
+  return path.isAbsolute(p) ? path.normalize(p) : path.resolve(cwd, p);
+}
+
+/**
+ * Wrap one allowed tool so it cannot act outside the sub-agent's directory.
+ *
+ * `edit_file` / `write_file` refuse a path outside `cwd`; `bash_exec` runs in
+ * `cwd` (or a directory beneath it) whatever `cwd` the model asked for. Read
+ * tools pass through: the issue confines writes, not reads.
+ *
+ * @param name - Tool name
+ * @param tool - The parent's definition of it
+ * @param cwd - Containment root
+ * @returns The same tool, confined
+ */
+function confineTool(name: string, tool: ToolDefinition, cwd: string): ToolDefinition {
+  if (name === 'edit_file' || name === 'write_file') {
+    return {
+      ...tool,
+      execute: async (args) => {
+        const requested = String(args['file_path'] ?? '');
+        const abs = resolveSubagentPath(requested, cwd);
+        if (!isInsideDir(abs, cwd)) {
+          return { success: false, error: `refused: ${requested} is outside the sub-agent working directory ${cwd}` };
+        }
+        return tool.execute({ ...args, file_path: abs });
+      },
+    };
+  }
+  if (name === 'bash_exec') {
+    return {
+      ...tool,
+      execute: async (args) => {
+        const requested = typeof args['cwd'] === 'string' && args['cwd'] ? resolveSubagentPath(args['cwd'], cwd) : cwd;
+        return tool.execute({ ...args, cwd: isInsideDir(requested, cwd) ? requested : cwd });
+      },
+    };
+  }
+  return tool;
+}
+
+/**
+ * The tool set a sub-agent gets: the allowed subset of the parent's tools,
+ * confined to `policy.cwd`, plus `report_to_parent`. Everything else —
+ * `send_message`, `reply_slack`, `broadcast`, `delegate_task`,
+ * `handoff_task`, `report_status`, `complete_task`, `start_agent`,
+ * `stop_agent`, `remember`, approvals, browser and desktop tools, MCP tools
+ * and `spawn_subagent` itself — is simply not in the map.
+ *
+ * @param tools - The full `createTools()` result of the child runner
+ * @param policy - The child's policy (cwd, readOnly)
+ * @param onReport - Receives the child's `report_to_parent` payload
+ * @returns The restricted tool map
+ */
+export function restrictToolsForSubagent(
+  tools: Record<string, ToolDefinition>,
+  policy: SubagentPolicy,
+  onReport: (report: SubagentReport) => void,
+): Record<string, ToolDefinition> {
+  const allowed = policy.readOnly ? SUBAGENT_READ_TOOLS : [...SUBAGENT_READ_TOOLS, ...SUBAGENT_WRITE_TOOLS];
+  const out: Record<string, ToolDefinition> = {};
+  for (const name of allowed) {
+    const tool = tools[name];
+    if (tool) out[name] = confineTool(name, tool, policy.cwd);
+  }
+  out[REPORT_TOOL_NAME] = {
+    description:
+      'Hand your result to the agent that spawned you. Call it once, at the end: what you found or changed, '
+      + 'the files you touched, what you could not do and why. The parent sees only this report and your final text.',
+    inputSchema: z.object({
+      summary: z.string().min(1).describe('Concrete findings or changes, with file paths and line references where they help'),
+      filesChanged: z.array(z.string()).optional().describe('Files you created or edited'),
+    }),
+    sensitivity: 'safe',
+    execute: async (args) => {
+      onReport({
+        summary: String(args['summary'] ?? ''),
+        filesChanged: Array.isArray(args['filesChanged']) ? args['filesChanged'].map(String) : [],
+      });
+      return { success: true, note: 'Reported to the parent. Finish your turn now with one line at most.' };
+    },
+  };
+  return out;
+}
+
+/**
+ * The system prompt of a sub-agent. Short on purpose: the task text is the
+ * context, and the harness rules are appended by the runner.
+ *
+ * @param parentSession - Who spawned it
+ * @param cwd - Where it may write
+ * @param readOnly - Whether writes are off
+ * @returns Prompt text
+ */
+export function buildSubagentPrompt(parentSession: string, cwd: string, readOnly: boolean): string {
+  return [
+    `You are a short-lived helper spawned by the agent "${parentSession}" for one bounded task.`,
+    `Working directory: ${cwd}. ${readOnly ? 'You have read-only tools: look, do not change anything.' : `You may change files only under ${cwd}.`}`,
+    'You cannot message anyone, delegate, schedule, or touch tickets; nobody but your parent will read you.',
+    `Do the task with your tools, then call ${REPORT_TOOL_NAME} once with what you found or changed, the files you touched, and anything you could not do.`,
+    'Report facts you verified, with paths and line numbers; if you did nothing, say so instead of inventing a result.',
+  ].join('\n');
+}
+
+/**
+ * Pick the child's model: the parent's by default, a different id on the
+ * parent's provider, or `provider/modelId`.
+ *
+ * @param parent - Parent model
+ * @param requested - The `model` argument, if any
+ * @returns The model, or why it was refused
+ */
+export function resolveSubagentModel(parent: ModelConfig, requested?: string): { model: ModelConfig } | { error: string } {
+  if (!requested || !requested.trim()) return { model: parent };
+  const spec = requested.trim();
+  const slash = spec.indexOf('/');
+  if (slash < 0) return { model: { ...parent, modelId: spec } };
+  const provider = spec.slice(0, slash);
+  const modelId = spec.slice(slash + 1);
+  if (!isModelProvider(provider)) return { error: `unknown model provider "${provider}" in "${spec}"` };
+  if (!modelId) return { error: `"${spec}" names no model` };
+  return { model: { ...parent, provider, modelId } };
+}
+
+/**
+ * The child's configuration, derived from the parent's.
+ *
+ * The child shares the API base URL, history and compaction settings; it
+ * gets its own session name (`<parent>/sub-<n>`), its own short prompt, the
+ * requested working directory as project path, no MCP servers (one process
+ * per server is the parent's cost to bear, not every helper's), no member id
+ * and the `subagent` policy that makes the runner restrict its tools.
+ *
+ * @param parent - Parent config
+ * @param input - Spawn arguments
+ * @param ordinal - 1-based child number for this parent
+ * @returns The config, or why the spawn was refused
+ */
+export function buildSubagentConfig(
+  parent: CrewlyAgentConfig,
+  input: SpawnSubagentInput,
+  ordinal: number,
+): { config: CrewlyAgentConfig } | { error: string } {
+  const task = (input.task ?? '').trim();
+  if (!task) return { error: 'task is required' };
+  if (task.length > CREWLY_AGENT_DEFAULTS.SUBAGENT.TASK_MAX_CHARS) {
+    return { error: `task is too long (${task.length} chars; keep it under ${CREWLY_AGENT_DEFAULTS.SUBAGENT.TASK_MAX_CHARS})` };
+  }
+  const base = parent.projectPath ?? process.cwd();
+  const cwd = input.cwd ? resolveSubagentPath(input.cwd, base) : base;
+  const picked = resolveSubagentModel(parent.model, input.model);
+  if ('error' in picked) return picked;
+  const requestedSteps = Number.isFinite(input.maxSteps) && (input.maxSteps as number) > 0
+    ? Math.floor(input.maxSteps as number)
+    : CREWLY_AGENT_DEFAULTS.SUBAGENT.MAX_STEPS;
+  const readOnly = input.readOnly === true;
+  const sessionName = `${parent.sessionName}/sub-${ordinal}`;
+  return {
+    config: {
+      model: picked.model,
+      maxSteps: Math.min(requestedSteps, CREWLY_AGENT_DEFAULTS.SUBAGENT.MAX_STEPS_CAP),
+      sessionName,
+      role: 'subagent',
+      apiBaseUrl: parent.apiBaseUrl,
+      systemPrompt: buildSubagentPrompt(parent.sessionName, cwd, readOnly),
+      maxHistoryMessages: parent.maxHistoryMessages,
+      compactionThreshold: parent.compactionThreshold,
+      projectPath: cwd,
+      subagent: { cwd, readOnly, depth: (parent.subagent?.depth ?? 0) + 1, parentSession: parent.sessionName },
+    },
+  };
+}
+
+/**
+ * Turn a child's run result into what the parent gets back.
+ *
+ * `report_to_parent` is not a working call: a child that only reported
+ * "did nothing". Files changed are read off successful `edit_file` /
+ * `write_file` calls and merged with the report's list, so a child cannot
+ * claim a change its tools never made — and cannot hide one either.
+ *
+ * @param result - The child's run result
+ * @param report - What it reported, if it did
+ * @param sessionName - The child's session name
+ * @param durationMs - Wall-clock time
+ * @param timedOut - Whether the parent's timer fired
+ * @returns The outcome
+ */
+export function summarizeSubagentRun(
+  result: AgentRunResult,
+  report: SubagentReport | null,
+  sessionName: string,
+  durationMs: number,
+  timedOut: boolean,
+): SubagentOutcome {
+  const work = result.toolCalls.filter((tc) => tc.toolName !== REPORT_TOOL_NAME);
+  const changed = new Set<string>();
+  for (const tc of work) {
+    if (tc.toolName !== 'edit_file' && tc.toolName !== 'write_file') continue;
+    const ok = tc.result == null || typeof tc.result !== 'object' || (tc.result as Record<string, unknown>)['success'] !== false;
+    const fp = tc.args['file_path'];
+    if (ok && typeof fp === 'string' && fp) changed.add(fp);
+  }
+  for (const fp of report?.filesChanged ?? []) if (fp) changed.add(fp);
+
+  let stoppedReason: SubagentStopReason = 'done';
+  if (timedOut) stoppedReason = 'timeout';
+  else if (work.length === 0) stoppedReason = 'did_nothing';
+  else if (result.incomplete?.reason === 'steps-exhausted') stoppedReason = 'steps_exhausted';
+  else if (result.incomplete) stoppedReason = 'incomplete';
+
+  const raw = (report?.summary ?? result.text ?? '').trim();
+  const cap = CREWLY_AGENT_DEFAULTS.SUBAGENT.SUMMARY_MAX_CHARS;
+  const summary = raw.length > cap ? `${raw.slice(0, cap)}\n…[truncated]` : raw;
+  return {
+    success: stoppedReason === 'done',
+    stoppedReason,
+    summary,
+    toolCalls: work.length,
+    toolNames: [...new Set(work.map((tc) => tc.toolName))],
+    filesChanged: [...changed],
+    usage: result.usage,
+    steps: result.steps,
+    sessionName,
+    durationMs,
+    ...(timedOut ? { error: `sub-agent exceeded ${CREWLY_AGENT_DEFAULTS.SUBAGENT.TIMEOUT_MS} ms` } : {}),
+  };
+}
+
+/** What the spawn tool needs from its parent runner. */
+export interface SpawnSubagentContext {
+  /** The parent's config; the child's is derived from it. */
+  parentConfig: CrewlyAgentConfig;
+  /** Shared counters for this parent. */
+  registry: SubagentRegistry;
+  /** Builds a child runner from a config (the runner injects `new AgentRunnerService`). */
+  createRunner: (config: CrewlyAgentConfig) => SubagentRunner;
+  /** Receives the child's usage so the parent's ledger counts it. */
+  onUsage?: (usage: { input: number; output: number; cachedInput: number }) => void;
+  /** Wall-clock budget per child; defaults to the runtime default. */
+  timeoutMs?: number;
+  /** Clock, for tests. */
+  now?: () => number;
+}
+
+/**
+ * An outcome for a spawn that failed before or while running.
+ *
+ * @param sessionName - Child session name, or the parent's when none was built
+ * @param reason - `error` or `timeout`
+ * @param error - What went wrong
+ * @param durationMs - Time spent
+ * @returns The outcome
+ */
+function failedOutcome(sessionName: string, reason: 'error' | 'timeout', error: string, durationMs: number): SubagentOutcome {
+  return {
+    success: false,
+    stoppedReason: reason,
+    summary: '',
+    toolCalls: 0,
+    toolNames: [],
+    filesChanged: [],
+    usage: { input: 0, output: 0, cachedInput: 0 },
+    steps: 0,
+    sessionName,
+    durationMs,
+    error,
+  };
+}
+
+/**
+ * The parent's `spawn_subagent` tool.
+ *
+ * Refuses when the parent already has the maximum number of children
+ * running. Otherwise builds the child config, runs the child once with the
+ * task as its only message under a wall-clock budget, folds its usage into
+ * the parent's, and always disposes the child runner — on success, error or
+ * timeout.
+ *
+ * @param ctx - Parent-side dependencies
+ * @returns The tool definition
+ *
+ * @example
+ * ```ts
+ * tools.spawn_subagent = createSpawnSubagentTool({
+ *   parentConfig: this.config,
+ *   registry: this.subagentRegistry,
+ *   createRunner: (cfg) => new AgentRunnerService(cfg, this.modelManager, this.apiClient),
+ *   onUsage: (u) => this.recordChildUsage(u),
+ * });
+ * ```
+ */
+export function createSpawnSubagentTool(ctx: SpawnSubagentContext): ToolDefinition {
+  const limits = CREWLY_AGENT_DEFAULTS.SUBAGENT;
+  const now = ctx.now ?? (() => Date.now());
+  const timeoutMs = ctx.timeoutMs ?? limits.TIMEOUT_MS;
+  return {
+    description:
+      'Run a short-lived helper agent on one bounded, self-contained piece of work — parallel research, a large read you want '
+      + 'kept out of your own context, a scoped fix — and get its report back as this tool result. The helper starts with only '
+      + 'your task text, works in the given directory with file, search and shell tools (no messaging, no delegation, no tickets, '
+      + 'no further helpers), and is gone when it returns. Use a teammate instead for anything that needs a named owner, a review, '
+      + `or communication. At most ${limits.MAX_CONCURRENT} helpers run at once; each gets up to ${limits.MAX_STEPS} steps `
+      + `(cap ${limits.MAX_STEPS_CAP}) and ${Math.round(limits.TIMEOUT_MS / 60000)} minutes. A result with stoppedReason `
+      + '"did_nothing" means the helper made no tool call: treat it as a failure, not as an answer.',
+    inputSchema: z.object({
+      task: z.string().min(1).describe('Everything the helper needs: the goal, the files or area, what "done" looks like, what to report'),
+      cwd: z.string().optional().describe('Directory the helper works in and may write under (default: your project path)'),
+      readOnly: z.boolean().optional().describe('True for research or review: no shell, no file writes'),
+      maxSteps: z.number().int().positive().optional().describe(`Model steps the helper may take (default ${limits.MAX_STEPS}, cap ${limits.MAX_STEPS_CAP})`),
+      model: z.string().optional().describe('A cheaper model for simple work: a model id on your provider, or provider/modelId'),
+    }),
+    sensitivity: 'sensitive',
+    execute: async (args): Promise<SubagentOutcome> => {
+      const started = now();
+      if (ctx.registry.active >= limits.MAX_CONCURRENT) {
+        return failedOutcome(
+          ctx.parentConfig.sessionName,
+          'error',
+          `at most ${limits.MAX_CONCURRENT} sub-agents run at once; wait for one to finish`,
+          now() - started,
+        );
+      }
+      const built = buildSubagentConfig(ctx.parentConfig, args as unknown as SpawnSubagentInput, ctx.registry.spawned + 1);
+      if ('error' in built) return failedOutcome(ctx.parentConfig.sessionName, 'error', built.error, now() - started);
+      const { config } = built;
+      ctx.registry.spawned += 1;
+      ctx.registry.active += 1;
+      const abort = new AbortController();
+      const timer = setTimeout(() => abort.abort(), timeoutMs);
+      let runner: SubagentRunner | null = null;
+      try {
+        runner = ctx.createRunner(config);
+        await runner.initialize();
+        const result = await runner.run(String(args['task']).trim(), undefined, undefined, { abortSignal: abort.signal });
+        ctx.onUsage?.(result.usage);
+        return summarizeSubagentRun(result, runner.getSubagentReport(), config.sessionName, now() - started, abort.signal.aborted);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return failedOutcome(config.sessionName, abort.signal.aborted ? 'timeout' : 'error', message, now() - started);
+      } finally {
+        clearTimeout(timer);
+        ctx.registry.active -= 1;
+        if (runner) await runner.shutdown().catch(() => { /* the child is gone either way */ });
+      }
+    },
+  };
+}

package/packages/crewly-agent/src/runtime/tool-registry.ts

@@ -617,6 +617,10 @@ export const TOOL_SENSITIVITY: Record<string, ToolSensitivity> = {
   // The task layer only plans and verifies; the acting happens through
   // `computer`, which carries the destructive rating.
   desktop_task: 'sensitive',
+  // Short-lived sub-agents (#1317): spawning spends tokens and may write
+  // files under cwd; reporting back is informational.
+  spawn_subagent: 'sensitive',
+  report_to_parent: 'safe',
 };
 
 /**

package/packages/crewly-agent/src/runtime/types.ts

@@ -125,6 +125,22 @@ export interface ConversationState {
   lastActivityAt: Date;
 }
 
+/**
+ * What a short-lived sub-agent may do (#1317). Set on a child runner's
+ * config by `spawn_subagent`; its presence makes the runner cut the tool set
+ * down with `restrictToolsForSubagent` instead of adding `spawn_subagent`.
+ */
+export interface SubagentPolicy {
+  /** Directory the child works in and may write under */
+  cwd: string;
+  /** No shell and no file writes when true */
+  readOnly: boolean;
+  /** 1 for a direct child; a child never gets `spawn_subagent`, so it stays 1 */
+  depth: number;
+  /** Session name of the agent that spawned it */
+  parentSession: string;
+}
+
 /**
  * Configuration for the Crewly Agent runtime
  */
@@ -160,6 +176,11 @@ export interface CrewlyAgentConfig {
    * - Enables post-execution deliverable self-check (Stop Hook)
    */
   evalMode?: boolean;
+  /**
+   * Set when this runner is a short-lived sub-agent (#1317): restricts its
+   * tools to file/search/shell within `cwd` plus `report_to_parent`.
+   */
+  subagent?: SubagentPolicy;
 }
 
 /**
@@ -663,6 +684,21 @@ export const CREWLY_AGENT_DEFAULTS = {
     maxAuditEntries: 500,
     readOnlyMode: false,
   } satisfies SecurityPolicy,
+  /** Short-lived sub-agents spawned by an in-process agent (#1317) */
+  SUBAGENT: {
+    /** Model steps a child gets when the parent names none */
+    MAX_STEPS: 30,
+    /** Hard cap on the steps a parent may grant */
+    MAX_STEPS_CAP: 60,
+    /** Wall-clock budget per child */
+    TIMEOUT_MS: 600_000,
+    /** Children one parent may have running at once */
+    MAX_CONCURRENT: 3,
+    /** Characters of the child's report kept for the parent */
+    SUMMARY_MAX_CHARS: 6000,
+    /** Characters a task may have; longer means the parent is pasting context it should summarise */
+    TASK_MAX_CHARS: 12_000,
+  },
   /** Default security guardrail configuration */
   SECURITY_GUARDRAILS: {
     outputFilterEnabled: true,