fix: reset is_background

* feat: enable tool call type coercion

* fix: tests for type coercion

---------

Co-authored-by: Mingholy <mingholy.lmh@gmail.com>

docs/subagents.md

@@ -133,6 +133,28 @@ Focus on creating clear, comprehensive documentation that helps both
 new contributors and end users understand the project.
 ```
 
+## Using Subagents Effectively
+
+### Automatic Delegation
+
+Qwen Code proactively delegates tasks based on:
+
+- The task description in your request
+- The description field in subagent configurations
+- Current context and available tools
+
+To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field.
+
+### Explicit Invocation
+
+Request a specific subagent by mentioning it in your command:
+
+```
+> Let the testing-expert subagent create unit tests for the payment module
+> Have the documentation-writer subagent update the API reference
+> Get the react-specialist subagent to optimize this component's performance
+```
+
 ## Examples
 
 ### Development Workflow Agents

packages/cli/src/ui/App.tsx

@@ -667,7 +667,13 @@ const App = ({ config, settings, startupWarnings = [], version }: AppProps) => {
   );
 
   const pendingHistoryItems = useMemo(
-    () => [...pendingSlashCommandHistoryItems, ...pendingGeminiHistoryItems],
+    () =>
+      [...pendingSlashCommandHistoryItems, ...pendingGeminiHistoryItems].map(
+        (item, index) => ({
+          ...item,
+          id: index,
+        }),
+      ),
     [pendingSlashCommandHistoryItems, pendingGeminiHistoryItems],
   );
 
@@ -1121,16 +1127,14 @@ const App = ({ config, settings, startupWarnings = [], version }: AppProps) => {
         </Static>
         <OverflowProvider>
           <Box ref={pendingHistoryItemRef} flexDirection="column">
-            {pendingHistoryItems.map((item, i) => (
+            {pendingHistoryItems.map((item) => (
               <HistoryItemDisplay
-                key={i}
+                key={item.id}
                 availableTerminalHeight={
                   constrainHeight ? availableTerminalHeight : undefined
                 }
                 terminalWidth={mainAreaWidth}
-                // TODO(taehykim): It seems like references to ids aren't necessary in
-                // HistoryItemDisplay. Refactor later. Use a fake id for now.
-                item={{ ...item, id: 0 }}
+                item={item}
                 isPending={true}
                 config={config}
                 isFocused={!isEditorDialogOpen}

packages/cli/src/ui/components/HistoryItemDisplay.tsx

@@ -5,6 +5,7 @@
  */
 
 import type React from 'react';
+import { memo } from 'react';
 import type { HistoryItem } from '../types.js';
 import { UserMessage } from './messages/UserMessage.js';
 import { UserShellMessage } from './messages/UserShellMessage.js';
@@ -35,7 +36,7 @@ interface HistoryItemDisplayProps {
   commands?: readonly SlashCommand[];
 }
 
-export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
+const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
   item,
   availableTerminalHeight,
   terminalWidth,
@@ -101,3 +102,7 @@ export const HistoryItemDisplay: React.FC<HistoryItemDisplayProps> = ({
     {item.type === 'summary' && <SummaryMessage summary={item.summary} />}
   </Box>
 );
+
+HistoryItemDisplayComponent.displayName = 'HistoryItemDisplay';
+
+export const HistoryItemDisplay = memo(HistoryItemDisplayComponent);

packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx

@@ -27,6 +27,7 @@ export interface ToolConfirmationMessageProps {
   isFocused?: boolean;
   availableTerminalHeight?: number;
   terminalWidth: number;
+  compactMode?: boolean;
 }
 
 export const ToolConfirmationMessage: React.FC<
@@ -37,6 +38,7 @@ export const ToolConfirmationMessage: React.FC<
   isFocused = true,
   availableTerminalHeight,
   terminalWidth,
+  compactMode = false,
 }) => {
   const { onConfirm } = confirmationDetails;
   const childWidth = terminalWidth - 2; // 2 for padding
@@ -70,6 +72,40 @@ export const ToolConfirmationMessage: React.FC<
 
   const handleSelect = (item: ToolConfirmationOutcome) => handleConfirm(item);
 
+  // Compact mode: return simple 3-option display
+  if (compactMode) {
+    const compactOptions: Array<RadioSelectItem<ToolConfirmationOutcome>> = [
+      {
+        label: 'Yes, allow once',
+        value: ToolConfirmationOutcome.ProceedOnce,
+      },
+      {
+        label: 'Allow always',
+        value: ToolConfirmationOutcome.ProceedAlways,
+      },
+      {
+        label: 'No',
+        value: ToolConfirmationOutcome.Cancel,
+      },
+    ];
+
+    return (
+      <Box flexDirection="column">
+        <Box>
+          <Text wrap="truncate">Do you want to proceed?</Text>
+        </Box>
+        <Box>
+          <RadioButtonSelect
+            items={compactOptions}
+            onSelect={handleSelect}
+            isFocused={isFocused}
+          />
+        </Box>
+      </Box>
+    );
+  }
+
+  // Original logic continues unchanged below
   let bodyContent: React.ReactNode | null = null; // Removed contextDisplay here
   let question: string;
 

packages/cli/src/ui/components/subagents/create/AgentCreationWizard.tsx

@@ -5,7 +5,7 @@
  */
 
 import { useReducer, useCallback, useMemo } from 'react';
-import { Box, Text, useInput } from 'ink';
+import { Box, Text } from 'ink';
 import { wizardReducer, initialWizardState } from '../reducers.js';
 import { LocationSelector } from './LocationSelector.js';
 import { GenerationMethodSelector } from './GenerationMethodSelector.js';
@@ -20,6 +20,7 @@ import type { Config } from '@qwen-code/qwen-code-core';
 import { Colors } from '../../../colors.js';
 import { theme } from '../../../semantic-colors.js';
 import { TextEntryStep } from './TextEntryStep.js';
+import { useKeypress } from '../../../hooks/useKeypress.js';
 
 interface AgentCreationWizardProps {
   onClose: () => void;
@@ -49,8 +50,12 @@ export function AgentCreationWizard({
   }, [onClose]);
 
   // Centralized ESC key handling for the entire wizard
-  useInput((input, key) => {
-    if (key.escape) {
+  useKeypress(
+    (key) => {
+      if (key.name !== 'escape') {
+        return;
+      }
+
       // LLM DescriptionInput handles its own ESC logic when generating
       const kind = getStepKind(state.generationMethod, state.currentStep);
       if (kind === 'LLM_DESC' && state.isGenerating) {
@@ -64,8 +69,9 @@ export function AgentCreationWizard({
         // On other steps, ESC goes back to previous step
         handlePrevious();
       }
-    }
-  });
+    },
+    { isActive: true },
+  );
 
   const stepProps: WizardStepProps = useMemo(
     () => ({

packages/cli/src/ui/components/subagents/manage/AgentSelectionStep.tsx

@@ -227,7 +227,7 @@ export const AgentSelectionStep = ({
     const textColor = isSelected ? theme.text.accent : theme.text.primary;
 
     return (
-      <Box key={agent.name} alignItems="center">
+      <Box key={`${agent.name}-${agent.level}`} alignItems="center">
         <Box minWidth={2} flexShrink={0}>
           <Text color={isSelected ? theme.text.accent : theme.text.primary}>
             {isSelected ? '●' : ' '}

packages/cli/src/ui/components/subagents/manage/AgentsManagerDialog.tsx

@@ -5,7 +5,7 @@
  */
 
 import { useState, useCallback, useMemo, useEffect } from 'react';
-import { Box, Text, useInput } from 'ink';
+import { Box, Text } from 'ink';
 import { AgentSelectionStep } from './AgentSelectionStep.js';
 import { ActionSelectionStep } from './ActionSelectionStep.js';
 import { AgentViewerStep } from './AgentViewerStep.js';
@@ -17,7 +17,8 @@ import { MANAGEMENT_STEPS } from '../types.js';
 import { Colors } from '../../../colors.js';
 import { theme } from '../../../semantic-colors.js';
 import { getColorForDisplay, shouldShowColor } from '../utils.js';
-import type { Config, SubagentConfig } from '@qwen-code/qwen-code-core';
+import type { SubagentConfig, Config } from '@qwen-code/qwen-code-core';
+import { useKeypress } from '../../../hooks/useKeypress.js';
 
 interface AgentsManagerDialogProps {
   onClose: () => void;
@@ -52,18 +53,7 @@ export function AgentsManagerDialog({
     const manager = config.getSubagentManager();
 
     // Load agents from all levels separately to show all agents including conflicts
-    const [projectAgents, userAgents, builtinAgents] = await Promise.all([
-      manager.listSubagents({ level: 'project' }),
-      manager.listSubagents({ level: 'user' }),
-      manager.listSubagents({ level: 'builtin' }),
-    ]);
-
-    // Combine all agents (project, user, and builtin level)
-    const allAgents = [
-      ...(projectAgents || []),
-      ...(userAgents || []),
-      ...(builtinAgents || []),
-    ];
+    const allAgents = await manager.listSubagents();
 
     setAvailableAgents(allAgents);
   }, [config]);
@@ -122,8 +112,12 @@ export function AgentsManagerDialog({
   );
 
   // Centralized ESC key handling for the entire dialog
-  useInput((input, key) => {
-    if (key.escape) {
+  useKeypress(
+    (key) => {
+      if (key.name !== 'escape') {
+        return;
+      }
+
       const currentStep = getCurrentStep();
       if (currentStep === MANAGEMENT_STEPS.AGENT_SELECTION) {
         // On first step, ESC cancels the entire dialog
@@ -132,8 +126,9 @@ export function AgentsManagerDialog({
         // On other steps, ESC goes back to previous step in navigation stack
         handleNavigateBack();
       }
-    }
-  });
+    },
+    { isActive: true },
+  );
 
   // Props for child components - now using direct state and callbacks
   const commonProps = useMemo(

packages/cli/src/ui/components/subagents/runtime/AgentExecutionDisplay.tsx

@@ -18,12 +18,12 @@ import { COLOR_OPTIONS } from '../constants.js';
 import { fmtDuration } from '../utils.js';
 import { ToolConfirmationMessage } from '../../messages/ToolConfirmationMessage.js';
 
-export type DisplayMode = 'default' | 'verbose';
+export type DisplayMode = 'compact' | 'default' | 'verbose';
 
 export interface AgentExecutionDisplayProps {
   data: TaskResultDisplay;
   availableHeight?: number;
-  childWidth?: number;
+  childWidth: number;
   config: Config;
 }
 
@@ -80,7 +80,7 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
   childWidth,
   config,
 }) => {
-  const [displayMode, setDisplayMode] = React.useState<DisplayMode>('default');
+  const [displayMode, setDisplayMode] = React.useState<DisplayMode>('compact');
 
   const agentColor = useMemo(() => {
     const colorOption = COLOR_OPTIONS.find(
@@ -93,8 +93,6 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
     // This component only listens to keyboard shortcut events when the subagent is running
     if (data.status !== 'running') return '';
 
-    if (displayMode === 'verbose') return 'Press ctrl+r to show less.';
-
     if (displayMode === 'default') {
       const hasMoreLines =
         data.taskPrompt.split('\n').length > MAX_TASK_PROMPT_LINES;
@@ -102,17 +100,28 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
         data.toolCalls && data.toolCalls.length > MAX_TOOL_CALLS;
 
       if (hasMoreToolCalls || hasMoreLines) {
-        return 'Press ctrl+r to show more.';
+        return 'Press ctrl+r to show less, ctrl+e to show more.';
       }
-      return '';
+      return 'Press ctrl+r to show less.';
     }
-    return '';
-  }, [displayMode, data.toolCalls, data.taskPrompt, data.status]);
 
-  // Handle ctrl+r keypresses to control display mode
+    if (displayMode === 'verbose') {
+      return 'Press ctrl+e to show less.';
+    }
+
+    return '';
+  }, [displayMode, data]);
+
+  // Handle keyboard shortcuts to control display mode
   useKeypress(
     (key) => {
       if (key.ctrl && key.name === 'r') {
+        // ctrl+r toggles between compact and default
+        setDisplayMode((current) =>
+          current === 'compact' ? 'default' : 'compact',
+        );
+      } else if (key.ctrl && key.name === 'e') {
+        // ctrl+e toggles between default and verbose
         setDisplayMode((current) =>
           current === 'default' ? 'verbose' : 'default',
         );
@@ -121,6 +130,82 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
     { isActive: true },
   );
 
+  if (displayMode === 'compact') {
+    return (
+      <Box flexDirection="column">
+        {/* Header: Agent name and status */}
+        {!data.pendingConfirmation && (
+          <Box flexDirection="row">
+            <Text bold color={agentColor}>
+              {data.subagentName}
+            </Text>
+            <StatusDot status={data.status} />
+            <StatusIndicator status={data.status} />
+          </Box>
+        )}
+
+        {/* Running state: Show current tool call and progress */}
+        {data.status === 'running' && (
+          <>
+            {/* Current tool call */}
+            {data.toolCalls && data.toolCalls.length > 0 && (
+              <Box flexDirection="column">
+                <ToolCallItem
+                  toolCall={data.toolCalls[data.toolCalls.length - 1]}
+                  compact={true}
+                />
+                {/* Show count of additional tool calls if there are more than 1 */}
+                {data.toolCalls.length > 1 && !data.pendingConfirmation && (
+                  <Box flexDirection="row" paddingLeft={4}>
+                    <Text color={Colors.Gray}>
+                      +{data.toolCalls.length - 1} more tool calls (ctrl+r to
+                      expand)
+                    </Text>
+                  </Box>
+                )}
+              </Box>
+            )}
+
+            {/* Inline approval prompt when awaiting confirmation */}
+            {data.pendingConfirmation && (
+              <Box flexDirection="column" marginTop={1} paddingLeft={1}>
+                <ToolConfirmationMessage
+                  confirmationDetails={data.pendingConfirmation}
+                  isFocused={true}
+                  availableTerminalHeight={availableHeight}
+                  terminalWidth={childWidth}
+                  compactMode={true}
+                  config={config}
+                />
+              </Box>
+            )}
+          </>
+        )}
+
+        {/* Completed state: Show summary line */}
+        {data.status === 'completed' && data.executionSummary && (
+          <Box flexDirection="row" marginTop={1}>
+            <Text color={theme.text.secondary}>
+              Execution Summary: {data.executionSummary.totalToolCalls} tool
+              uses · {data.executionSummary.totalTokens.toLocaleString()} tokens
+              · {fmtDuration(data.executionSummary.totalDurationMs)}
+            </Text>
+          </Box>
+        )}
+
+        {/* Failed/Cancelled state: Show error reason */}
+        {data.status === 'failed' && (
+          <Box flexDirection="row" marginTop={1}>
+            <Text color={theme.status.error}>
+              Failed: {data.terminateReason}
+            </Text>
+          </Box>
+        )}
+      </Box>
+    );
+  }
+
+  // Default and verbose modes use normal layout
   return (
     <Box flexDirection="column" paddingX={1} gap={1}>
       {/* Header with subagent name and status */}
@@ -158,7 +243,8 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
             config={config}
             isFocused={true}
             availableTerminalHeight={availableHeight}
-            terminalWidth={childWidth ?? 80}
+            terminalWidth={childWidth}
+            compactMode={true}
           />
         </Box>
       )}
@@ -280,7 +366,8 @@ const ToolCallItem: React.FC<{
     resultDisplay?: string;
     description?: string;
   };
-}> = ({ toolCall }) => {
+  compact?: boolean;
+}> = ({ toolCall, compact = false }) => {
   const STATUS_INDICATOR_WIDTH = 3;
 
   // Map subagent status to ToolCallStatus-like display
@@ -335,8 +422,8 @@ const ToolCallItem: React.FC<{
         </Text>
       </Box>
 
-      {/* Second line: truncated returnDisplay output */}
-      {truncatedOutput && (
+      {/* Second line: truncated returnDisplay output - hidden in compact mode */}
+      {!compact && truncatedOutput && (
         <Box flexDirection="row" paddingLeft={STATUS_INDICATOR_WIDTH}>
           <Text color={Colors.Gray}>{truncatedOutput}</Text>
         </Box>

packages/cli/src/ui/hooks/useGeminiStream.ts

@@ -911,10 +911,13 @@ export const useGeminiStream = (
     ],
   );
 
-  const pendingHistoryItems = [
-    pendingHistoryItemRef.current,
-    pendingToolCallGroupDisplay,
-  ].filter((i) => i !== undefined && i !== null);
+  const pendingHistoryItems = useMemo(
+    () =>
+      [pendingHistoryItemRef.current, pendingToolCallGroupDisplay].filter(
+        (i) => i !== undefined && i !== null,
+      ),
+    [pendingHistoryItemRef, pendingToolCallGroupDisplay],
+  );
 
   useEffect(() => {
     const saveRestorableToolCalls = async () => {

packages/core/src/core/client.test.ts

@@ -226,6 +226,9 @@ describe('Gemini Client (client.ts)', () => {
       vertexai: false,
       authType: AuthType.USE_GEMINI,
     };
+    const mockSubagentManager = {
+      listSubagents: vi.fn().mockResolvedValue([]),
+    };
     const mockConfigObject = {
       getContentGeneratorConfig: vi
         .fn()
@@ -260,6 +263,7 @@ describe('Gemini Client (client.ts)', () => {
       getCliVersion: vi.fn().mockReturnValue('1.0.0'),
       getChatCompression: vi.fn().mockReturnValue(undefined),
       getSkipNextSpeakerCheck: vi.fn().mockReturnValue(false),
+      getSubagentManager: vi.fn().mockReturnValue(mockSubagentManager),
       getSkipLoopDetection: vi.fn().mockReturnValue(false),
     };
     const MockedConfig = vi.mocked(Config, true);

packages/core/src/core/client.ts

@@ -29,6 +29,7 @@ import {
   makeChatCompressionEvent,
   NextSpeakerCheckEvent,
 } from '../telemetry/types.js';
+import { TaskTool } from '../tools/task.js';
 import {
   getDirectoryContextString,
   getEnvironmentContext,
@@ -455,7 +456,8 @@ export class GeminiClient {
     turns: number = MAX_TURNS,
     originalModel?: string,
   ): AsyncGenerator<ServerGeminiStreamEvent, Turn> {
-    if (this.lastPromptId !== prompt_id) {
+    const isNewPrompt = this.lastPromptId !== prompt_id;
+    if (isNewPrompt) {
       this.loopDetector.reset(prompt_id);
       this.lastPromptId = prompt_id;
     }
@@ -552,6 +554,24 @@ export class GeminiClient {
       this.forceFullIdeContext = false;
     }
 
+    if (isNewPrompt) {
+      const taskTool = this.config.getToolRegistry().getTool(TaskTool.Name);
+      const subagents = (
+        await this.config.getSubagentManager().listSubagents()
+      ).filter((subagent) => subagent.level !== 'builtin');
+
+      if (taskTool && subagents.length > 0) {
+        this.getChat().addHistory({
+          role: 'user',
+          parts: [
+            {
+              text: `<system-reminder>You have powerful specialized agents at your disposal, available agent types are: ${subagents.map((subagent) => subagent.name).join(', ')}. PROACTIVELY use the ${TaskTool.Name} tool to delegate user's task to appropriate agent when user's task matches agent capabilities. Ignore this message if user's task is not relevant to any agent. This message is for internal use only. Do not mention this to user in your response.</system-reminder>`,
+            },
+          ],
+        });
+      }
+    }
+
     const turn = new Turn(this.getChat(), prompt_id);
 
     if (!this.config.getSkipLoopDetection()) {

packages/core/src/subagents/subagent-manager.test.ts

@@ -185,6 +185,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         validMarkdown,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.name).toBe('test-agent');
@@ -209,6 +210,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         markdownWithTools,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.tools).toEqual(['read_file', 'write_file']);
@@ -229,6 +231,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         markdownWithModel,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.modelConfig).toEqual({ model: 'custom-model', temp: 0.5 });
@@ -249,6 +252,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         markdownWithRun,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.runConfig).toEqual({ max_time_minutes: 5, max_turns: 10 });
@@ -266,6 +270,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         markdownWithNumeric,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.name).toBe('11');
@@ -286,6 +291,7 @@ You are a helpful assistant.
       const config = manager.parseSubagentContent(
         markdownWithBoolean,
         validConfig.filePath,
+        'project',
       );
 
       expect(config.name).toBe('true');
@@ -301,8 +307,13 @@ You are a helpful assistant.
       const projectConfig = manager.parseSubagentContent(
         validMarkdown,
         projectPath,
+        'project',
+      );
+      const userConfig = manager.parseSubagentContent(
+        validMarkdown,
+        userPath,
+        'user',
       );
-      const userConfig = manager.parseSubagentContent(validMarkdown, userPath);
 
       expect(projectConfig.level).toBe('project');
       expect(userConfig.level).toBe('user');
@@ -313,7 +324,11 @@ You are a helpful assistant.
 Just content`;
 
       expect(() =>
-        manager.parseSubagentContent(invalidMarkdown, validConfig.filePath),
+        manager.parseSubagentContent(
+          invalidMarkdown,
+          validConfig.filePath,
+          'project',
+        ),
       ).toThrow(SubagentError);
     });
 
@@ -326,7 +341,11 @@ You are a helpful assistant.
 `;
 
       expect(() =>
-        manager.parseSubagentContent(markdownWithoutName, validConfig.filePath),
+        manager.parseSubagentContent(
+          markdownWithoutName,
+          validConfig.filePath,
+          'project',
+        ),
       ).toThrow(SubagentError);
     });
 
@@ -342,39 +361,20 @@ You are a helpful assistant.
         manager.parseSubagentContent(
           markdownWithoutDescription,
           validConfig.filePath,
+          'project',
         ),
       ).toThrow(SubagentError);
     });
 
-    it('should warn when filename does not match subagent name', () => {
-      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-      const mismatchedPath = '/test/project/.qwen/agents/wrong-filename.md';
-
-      const config = manager.parseSubagentContent(
-        validMarkdown,
-        mismatchedPath,
-      );
-
-      expect(config.name).toBe('test-agent');
-      expect(consoleSpy).toHaveBeenCalledWith(
-        expect.stringContaining(
-          'Warning: Subagent file "wrong-filename.md" contains name "test-agent"',
-        ),
-      );
-      expect(consoleSpy).toHaveBeenCalledWith(
-        expect.stringContaining(
-          'Consider renaming the file to "test-agent.md"',
-        ),
-      );
-
-      consoleSpy.mockRestore();
-    });
-
     it('should not warn when filename matches subagent name', () => {
       const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
       const matchingPath = '/test/project/.qwen/agents/test-agent.md';
 
-      const config = manager.parseSubagentContent(validMarkdown, matchingPath);
+      const config = manager.parseSubagentContent(
+        validMarkdown,
+        matchingPath,
+        'project',
+      );
 
       expect(config.name).toBe('test-agent');
       expect(consoleSpy).not.toHaveBeenCalled();

packages/core/src/subagents/subagent-manager.ts

@@ -39,6 +39,7 @@ const AGENT_CONFIG_DIR = 'agents';
  */
 export class SubagentManager {
   private readonly validator: SubagentValidator;
+  private subagentsCache: Map<SubagentLevel, SubagentConfig[]> | null = null;
 
   constructor(private readonly config: Config) {
     this.validator = new SubagentValidator();
@@ -92,6 +93,8 @@ export class SubagentManager {
 
     try {
       await fs.writeFile(filePath, content, 'utf8');
+      // Clear cache after successful creation
+      this.clearCache();
     } catch (error) {
       throw new SubagentError(
         `Failed to write subagent file: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -180,6 +183,8 @@ export class SubagentManager {
 
     try {
       await fs.writeFile(existing.filePath, content, 'utf8');
+      // Clear cache after successful update
+      this.clearCache();
     } catch (error) {
       throw new SubagentError(
         `Failed to update subagent file: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -236,6 +241,9 @@ export class SubagentManager {
         name,
       );
     }
+
+    // Clear cache after successful deletion
+    this.clearCache();
   }
 
   /**
@@ -254,9 +262,17 @@ export class SubagentManager {
       ? [options.level]
       : ['project', 'user', 'builtin'];
 
+    // Check if we should use cache or force refresh
+    const shouldUseCache = !options.force && this.subagentsCache !== null;
+
+    // Initialize cache if it doesn't exist or we're forcing a refresh
+    if (!shouldUseCache) {
+      await this.refreshCache();
+    }
+
     // Collect subagents from each level (project takes precedence over user, user takes precedence over builtin)
     for (const level of levelsToCheck) {
-      const levelSubagents = await this.listSubagentsAtLevel(level);
+      const levelSubagents = this.subagentsCache?.get(level) || [];
 
       for (const subagent of levelSubagents) {
         // Skip if we've already seen this name (precedence: project > user > builtin)
@@ -304,6 +320,30 @@ export class SubagentManager {
     return subagents;
   }
 
+  /**
+   * Refreshes the subagents cache by loading all subagents from disk.
+   * This method is called automatically when cache is null or when force=true.
+   *
+   * @private
+   */
+  private async refreshCache(): Promise<void> {
+    this.subagentsCache = new Map();
+
+    const levels: SubagentLevel[] = ['project', 'user', 'builtin'];
+
+    for (const level of levels) {
+      const levelSubagents = await this.listSubagentsAtLevel(level);
+      this.subagentsCache.set(level, levelSubagents);
+    }
+  }
+
+  /**
+   * Clears the subagents cache, forcing the next listSubagents call to reload from disk.
+   */
+  clearCache(): void {
+    this.subagentsCache = null;
+  }
+
   /**
    * Finds a subagent by name and returns its metadata.
    *
@@ -329,7 +369,10 @@ export class SubagentManager {
    * @returns SubagentConfig
    * @throws SubagentError if parsing fails
    */
-  async parseSubagentFile(filePath: string): Promise<SubagentConfig> {
+  async parseSubagentFile(
+    filePath: string,
+    level: SubagentLevel,
+  ): Promise<SubagentConfig> {
     let content: string;
 
     try {
@@ -341,7 +384,7 @@ export class SubagentManager {
       );
     }
 
-    return this.parseSubagentContent(content, filePath);
+    return this.parseSubagentContent(content, filePath, level);
   }
 
   /**
@@ -352,7 +395,11 @@ export class SubagentManager {
    * @returns SubagentConfig
    * @throws SubagentError if parsing fails
    */
-  parseSubagentContent(content: string, filePath: string): SubagentConfig {
+  parseSubagentContent(
+    content: string,
+    filePath: string,
+    level: SubagentLevel,
+  ): SubagentConfig {
     try {
       // Split frontmatter and content
       const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
@@ -393,31 +440,16 @@ export class SubagentManager {
         | undefined;
       const color = frontmatter['color'] as string | undefined;
 
-      // Determine level from file path using robust, cross-platform check
-      // A project-level agent lives under <projectRoot>/.qwen/agents
-      const projectAgentsDir = path.join(
-        this.config.getProjectRoot(),
-        QWEN_CONFIG_DIR,
-        AGENT_CONFIG_DIR,
-      );
-      const rel = path.relative(
-        path.normalize(projectAgentsDir),
-        path.normalize(filePath),
-      );
-      const isProjectLevel =
-        rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
-      const level: SubagentLevel = isProjectLevel ? 'project' : 'user';
-
       const config: SubagentConfig = {
         name,
         description,
         tools,
         systemPrompt: systemPrompt.trim(),
-        level,
         filePath,
         modelConfig: modelConfig as Partial<ModelConfig>,
         runConfig: runConfig as Partial<RunConfig>,
         color,
+        level,
       };
 
       // Validate the parsed configuration
@@ -426,16 +458,6 @@ export class SubagentManager {
         throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
       }
 
-      // Warn if filename doesn't match subagent name (potential issue)
-      const expectedFilename = `${config.name}.md`;
-      const actualFilename = path.basename(filePath);
-      if (actualFilename !== expectedFilename) {
-        console.warn(
-          `Warning: Subagent file "${actualFilename}" contains name "${config.name}" but filename suggests "${path.basename(actualFilename, '.md')}". ` +
-            `Consider renaming the file to "${expectedFilename}" for consistency.`,
-        );
-      }
-
       return config;
     } catch (error) {
       throw new SubagentError(
@@ -678,14 +700,18 @@ export class SubagentManager {
       return BuiltinAgentRegistry.getBuiltinAgents();
     }
 
-    const baseDir =
-      level === 'project'
-        ? path.join(
-            this.config.getProjectRoot(),
-            QWEN_CONFIG_DIR,
-            AGENT_CONFIG_DIR,
-          )
-        : path.join(os.homedir(), QWEN_CONFIG_DIR, AGENT_CONFIG_DIR);
+    const projectRoot = this.config.getProjectRoot();
+    const homeDir = os.homedir();
+    const isHomeDirectory = path.resolve(projectRoot) === path.resolve(homeDir);
+
+    // If project level is requested but project root is same as home directory,
+    // return empty array to avoid conflicts between project and global agents
+    if (level === 'project' && isHomeDirectory) {
+      return [];
+    }
+
+    let baseDir = level === 'project' ? projectRoot : homeDir;
+    baseDir = path.join(baseDir, QWEN_CONFIG_DIR, AGENT_CONFIG_DIR);
 
     try {
       const files = await fs.readdir(baseDir);
@@ -697,7 +723,7 @@ export class SubagentManager {
         const filePath = path.join(baseDir, file);
 
         try {
-          const config = await this.parseSubagentFile(filePath);
+          const config = await this.parseSubagentFile(filePath, level);
           subagents.push(config);
         } catch (_error) {
           // Ignore invalid files

packages/core/src/subagents/types.ts

@@ -116,6 +116,9 @@ export interface ListSubagentsOptions {
 
   /** Sort direction */
   sortOrder?: 'asc' | 'desc';
+
+  /** Force refresh from disk, bypassing cache. Defaults to false. */
+  force?: boolean;
 }
 
 /**

packages/core/src/tools/glob.test.ts

@@ -62,6 +62,9 @@ describe('GlobTool', () => {
     // Ensure a noticeable difference in modification time
     await new Promise((resolve) => setTimeout(resolve, 50));
     await fs.writeFile(path.join(tempRootDir, 'newer.sortme'), 'newer_content');
+
+    // For type coercion testing
+    await fs.mkdir(path.join(tempRootDir, '123'));
   });
 
   afterEach(async () => {
@@ -279,26 +282,20 @@ describe('GlobTool', () => {
       );
     });
 
-    it('should return error if path is provided but is not a string (schema validation)', () => {
+    it('should pass if path is provided but is not a string (type coercion)', () => {
       const params = {
         pattern: '*.ts',
         path: 123,
-      };
-      // @ts-expect-error - We're intentionally creating invalid params for testing
-      expect(globTool.validateToolParams(params)).toBe(
-        'params/path must be string',
-      );
+      } as unknown as GlobToolParams; // Force incorrect type
+      expect(globTool.validateToolParams(params)).toBeNull();
     });
 
-    it('should return error if case_sensitive is provided but is not a boolean (schema validation)', () => {
+    it('should pass if case_sensitive is provided but is not a boolean (type coercion)', () => {
       const params = {
         pattern: '*.ts',
         case_sensitive: 'true',
-      };
-      // @ts-expect-error - We're intentionally creating invalid params for testing
-      expect(globTool.validateToolParams(params)).toBe(
-        'params/case_sensitive must be boolean',
-      );
+      } as unknown as GlobToolParams; // Force incorrect type
+      expect(globTool.validateToolParams(params)).toBeNull();
     });
 
     it("should return error if search path resolves outside the tool's root directory", () => {

packages/core/src/tools/read-many-files.test.ts

@@ -191,14 +191,12 @@ describe('ReadManyFilesTool', () => {
       );
     });
 
-    it('should throw error if include array contains non-string elements', () => {
+    it('should coerce non-string elements in include array', () => {
       const params = {
         paths: ['file1.txt'],
         include: ['*.ts', 123] as string[],
       };
-      expect(() => tool.build(params)).toThrow(
-        'params/include/1 must be string',
-      );
+      expect(() => tool.build(params)).toBeDefined();
     });
 
     it('should throw error if exclude array contains non-string elements', () => {

packages/core/src/tools/shell.ts

@@ -419,6 +419,11 @@ export class ShellTool extends BaseDeclarativeTool<
             type: 'string',
             description: getCommandDescription(),
           },
+          is_background: {
+            type: 'boolean',
+            description:
+              'Whether to run the command in background. Default is false. Set to true for long-running processes like development servers, watchers, or daemons that should continue running without blocking further commands.',
+          },
           description: {
             type: 'string',
             description:

packages/core/src/tools/write-file.test.ts

@@ -220,14 +220,12 @@ describe('WriteFileTool', () => {
       );
     });
 
-    it('should throw an error if the content is null', () => {
-      const dirAsFilePath = path.join(rootDir, 'a_directory');
-      fs.mkdirSync(dirAsFilePath);
+    it('should coerce null content into an empty string', () => {
       const params = {
-        file_path: dirAsFilePath,
+        file_path: path.join(rootDir, 'test.txt'),
         content: null,
       } as unknown as WriteFileToolParams; // Intentionally non-conforming
-      expect(() => tool.build(params)).toThrow('params/content must be string');
+      expect(() => tool.build(params)).toBeDefined();
     });
 
     it('should throw error if the file_path is empty', () => {

packages/core/src/utils/schemaValidator.ts

@@ -9,7 +9,7 @@ import * as addFormats from 'ajv-formats';
 // Ajv's ESM/CJS interop: use 'any' for compatibility as recommended by Ajv docs
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const AjvClass = (AjvPkg as any).default || AjvPkg;
-const ajValidator = new AjvClass();
+const ajValidator = new AjvClass({ coerceTypes: true });
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const addFormatsFunc = (addFormats as any).default || addFormats;
 addFormatsFunc(ajValidator);
@@ -32,8 +32,27 @@ export class SchemaValidator {
     const validate = ajValidator.compile(schema);
     const valid = validate(data);
     if (!valid && validate.errors) {
-      return ajValidator.errorsText(validate.errors, { dataVar: 'params' });
+      // Find any True or False values and lowercase them
+      fixBooleanCasing(data as Record<string, unknown>);
+
+      const validate = ajValidator.compile(schema);
+      const valid = validate(data);
+
+      if (!valid && validate.errors) {
+        return ajValidator.errorsText(validate.errors, { dataVar: 'params' });
+      }
     }
     return null;
   }
 }
+
+function fixBooleanCasing(data: Record<string, unknown>) {
+  for (const key of Object.keys(data)) {
+    if (!(key in data)) continue;
+
+    if (typeof data[key] === 'object') {
+      fixBooleanCasing(data[key] as Record<string, unknown>);
+    } else if (data[key] === 'True') data[key] = 'true';
+    else if (data[key] === 'False') data[key] = 'false';
+  }
+}