Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/advanced-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -633,6 +633,7 @@ remain in the selected model, but context-limit keys use the model name before
| `CLAUDE_CODE_DISABLE_ULTRATHINK` | No | Set truthy to stop the `ultrathink` keyword from raising the turn to high effort |
| `CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES` | No | Set truthy to stop periodic forked-agent progress-summary requests for running agents |
| `CLAUDE_CODE_DISABLE_FILE_MENTIONS` | No | Set truthy so `@`-mentioned files pass their path only; contents are not read into context |
| `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` | No | Set truthy to stop advertising MCP task support, so tools/call never returns a server-side task |
| `CLAUDE_CODE_RESUME_HINT_COMMAND` | No | Override the program name printed in the exit-time resume hint (default: `openclaude`) |

### Web search
Expand Down Expand Up @@ -1136,3 +1137,22 @@ project's `disabledMcpServers` key to restore inheritance. Builtin servers that
are disabled by default keep their separate project-level `enabledMcpServers`
allowlist. Existing running sessions are not forcibly disconnected by a toggle
in another project.

## MCP server tasks

A server that supports the MCP tasks extension may answer a `tools/call` with
a task handle instead of a result when the tool's listing marks it
`execution.taskSupport`. When that happens, OpenClaude registers a
`mcp_server` background task, returns a "task started" result immediately,
and delivers the real result as a task notification when the server finishes.
The task list (`/tasks` or the background-tasks dialog) shows these under
"Server tasks"; `x` sends `tasks/cancel` to the server.

The client polls `tasks/get` at the interval the server suggests and also
listens for `notifications/tasks/status`. A disconnect before the task
finishes marks the local task failed. When the server reports a task as
failed or cancelled, OpenClaude also asks for `tasks/result` and, if the server
returns diagnostic content, saves it to the task output file; otherwise the
notification and output rely on the server's `statusMessage`. Set
`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` to disable the whole path: the
tasks capability is then not advertised and every tool call stays synchronous.
Comment thread
beardthelion marked this conversation as resolved.
Resolved
2 changes: 2 additions & 0 deletions src/Task.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ export type TaskType =
| 'in_process_teammate'
| 'local_workflow'
| 'monitor_mcp'
| 'mcp_server'
| 'dream'

export type TaskStatus =
Expand Down Expand Up @@ -83,6 +84,7 @@ const TASK_ID_PREFIXES: Record<string, string> = {
in_process_teammate: 't',
local_workflow: 'w',
monitor_mcp: 'm',
mcp_server: 's',
dream: 'd',
}

Expand Down
36 changes: 35 additions & 1 deletion src/components/tasks/BackgroundTask.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ type Props = {
maxActivityWidth?: number;
};
export function BackgroundTask(t0) {
const $ = _c(92);
const $ = _c(102);
const {
task,
maxActivityWidth
Expand Down Expand Up @@ -293,6 +293,40 @@ export function BackgroundTask(t0) {
}
return t5;
}
case "mcp_server":
{
let t1;
if ($[92] !== activityLimit || $[93] !== task.description) {
t1 = truncate(task.description, activityLimit, true);
$[92] = activityLimit;
$[93] = task.description;
$[94] = t1;
} else {
t1 = $[94];
}
const t2 = task.status === "completed" ? "done" : undefined;
const t3 = task.status === "completed" && !task.notified ? ", unread" : undefined;
let t4;
if ($[95] !== t2 || $[96] !== t3 || $[97] !== task.status) {
t4 = <TaskStatusText status={task.status} label={t2} suffix={t3} />;
$[95] = t2;
$[96] = t3;
$[97] = task.status;
$[98] = t4;
} else {
t4 = $[98];
}
let t5;
if ($[99] !== t1 || $[100] !== t4) {
t5 = <Text>{t1}{" "}{t4}</Text>;
$[99] = t1;
$[100] = t4;
$[101] = t5;
} else {
t5 = $[101];
}
return t5;
}
case "dream":
{
const n = task.filesTouched.length;
Expand Down
54 changes: 43 additions & 11 deletions src/components/tasks/BackgroundTasksDialog.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import type { LocalShellTaskState } from 'src/tasks/LocalShellTask/guards.js';
import { LocalShellTask } from 'src/tasks/LocalShellTask/LocalShellTask.js';
// Type import is erased at build time — safe even though module is ant-gated.
import type { LocalWorkflowTaskState } from 'src/tasks/LocalWorkflowTask/LocalWorkflowTask.js';
import { killMcpServerTask, type McpServerTaskState } from 'src/tasks/McpServerTask/McpServerTask.js';
import type { MonitorMcpTaskState } from 'src/tasks/MonitorMcpTask/MonitorMcpTask.js';
import { RemoteAgentTask, type RemoteAgentTaskState } from 'src/tasks/RemoteAgentTask/RemoteAgentTask.js';
import { type BackgroundTaskState, isBackgroundTask, type TaskState } from 'src/tasks/types.js';
Expand All @@ -39,6 +40,7 @@ import { AsyncAgentDetailDialog } from './AsyncAgentDetailDialog.js';
import { BackgroundTask as BackgroundTaskComponent } from './BackgroundTask.js';
import { DreamDetailDialog } from './DreamDetailDialog.js';
import { InProcessTeammateDetailDialog } from './InProcessTeammateDetailDialog.js';
import { McpServerTaskDetailDialog } from './McpServerTaskDetailDialog.js';
import { RemoteSessionDetailDialog } from './RemoteSessionDetailDialog.js';
import { ShellDetailDialog } from './ShellDetailDialog.js';
type ViewState = {
Expand Down Expand Up @@ -90,6 +92,12 @@ type ListItem = {
label: string;
status: string;
task: DeepImmutable<MonitorMcpTaskState>;
} | {
id: string;
type: 'mcp_server';
label: string;
status: string;
task: DeepImmutable<McpServerTaskState>;
} | {
id: string;
type: 'dream';
Expand Down Expand Up @@ -176,6 +184,7 @@ export function BackgroundTasksDialog({
teammateTasks,
workflowTasks,
mcpMonitors,
mcpServerTasks,
dreamTasks: dreamTasks_0,
allSelectableItems
} = useMemo(() => {
Expand All @@ -197,9 +206,10 @@ export function BackgroundTasksDialog({
const agent = sorted.filter(item_1 => item_1.type === 'local_agent' && item_1.id !== foregroundedTaskId);
const workflows = sorted.filter(item_2 => item_2.type === 'local_workflow');
const monitorMcp = sorted.filter(item_3 => item_3.type === 'monitor_mcp');
const dreamTasks = sorted.filter(item_4 => item_4.type === 'dream');
const mcpServer = sorted.filter(item_4 => item_4.type === 'mcp_server');
const dreamTasks = sorted.filter(item_5 => item_5.type === 'dream');
// In spinner-tree mode, exclude teammates from the dialog (they appear in the tree)
const teammates = showSpinnerTree ? [] : sorted.filter(item_5 => item_5.type === 'in_process_teammate');
const teammates = showSpinnerTree ? [] : sorted.filter(item_6 => item_6.type === 'in_process_teammate');
// Add leader entry when there are teammates, so users can foreground back to leader
const leaderItem: ListItem[] = teammates.length > 0 ? [{
id: '__leader__',
Expand All @@ -213,12 +223,13 @@ export function BackgroundTasksDialog({
agentTasks: agent,
workflowTasks: workflows,
mcpMonitors: monitorMcp,
mcpServerTasks: mcpServer,
dreamTasks,
teammateTasks: [...leaderItem, ...teammates],
// Order MUST match JSX render order (teammates \u2192 bash \u2192 monitorMcp \u2192
// remote \u2192 agent \u2192 workflows \u2192 dream) so \u2193/\u2191 navigation moves the cursor
// visually downward.
allSelectableItems: [...leaderItem, ...teammates, ...bash, ...monitorMcp, ...remote, ...agent, ...workflows, ...dreamTasks]
allSelectableItems: [...leaderItem, ...teammates, ...bash, ...monitorMcp, ...mcpServer, ...remote, ...agent, ...workflows, ...dreamTasks]
};
}, [typedTasks, foregroundedTaskId, showSpinnerTree]);
const currentSelection = allSelectableItems[selectedIndex] ?? null;
Expand Down Expand Up @@ -278,6 +289,8 @@ export function BackgroundTasksDialog({
killWorkflowTask(currentSelection_0.id, setAppState);
} else if (currentSelection_0.type === 'monitor_mcp' && currentSelection_0.status === 'running' && killMonitorMcp) {
killMonitorMcp(currentSelection_0.id, setAppState);
} else if (currentSelection_0.type === 'mcp_server' && currentSelection_0.status === 'running') {
killMcpServerTask(currentSelection_0.id, setAppState);
} else if (currentSelection_0.type === 'dream' && currentSelection_0.status === 'running') {
void killDreamTask(currentSelection_0.id);
} else if (currentSelection_0.type === 'remote_agent' && currentSelection_0.status === 'running') {
Expand Down Expand Up @@ -393,6 +406,8 @@ export function BackgroundTasksDialog({
case 'monitor_mcp':
if (!MonitorMcpDetailDialog) return null;
return <MonitorMcpDetailDialog task={task_0} onKill={task_0.status === 'running' && killMonitorMcp ? () => killMonitorMcp(task_0.id, setAppState) : undefined} onBack={goBackToList} key={`monitor-mcp-${task_0.id}`} />;
case 'mcp_server':
return <McpServerTaskDetailDialog task={task_0} onDone={onDone} onBack={goBackToList} onKill={task_0.status === 'running' ? () => killMcpServerTask(task_0.id, setAppState) : undefined} key={`mcp-server-${task_0.id}`} />;
case 'dream':
return <DreamDetailDialog task={task_0} onDone={() => onDone('Background tasks dialog dismissed', {
display: 'system'
Expand Down Expand Up @@ -453,37 +468,46 @@ export function BackgroundTasksDialog({
</Box>
</Box>}

{remoteSessions.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 ? 1 : 0}>
{mcpServerTasks.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 ? 1 : 0}>
<Text dimColor>
<Text bold>{' '}Server tasks</Text> ({mcpServerTasks.length})
</Text>
<Box flexDirection="column">
{mcpServerTasks.map(item_8 => <Item key={item_8.id} item={item_8} isSelected={item_8.id === currentSelection?.id} />)}
</Box>
</Box>}

{remoteSessions.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || mcpServerTasks.length > 0 ? 1 : 0}>
<Text dimColor>
<Text bold>{' '}Remote agents</Text> ({remoteSessions.length}
)
</Text>
<Box flexDirection="column">
{remoteSessions.map(item_8 => <Item key={item_8.id} item={item_8} isSelected={item_8.id === currentSelection?.id} />)}
{remoteSessions.map(item_9 => <Item key={item_9.id} item={item_9} isSelected={item_9.id === currentSelection?.id} />)}
</Box>
</Box>}

{agentTasks.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || remoteSessions.length > 0 ? 1 : 0}>
{agentTasks.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || mcpServerTasks.length > 0 || remoteSessions.length > 0 ? 1 : 0}>
<Text dimColor>
<Text bold>{' '}Local agents</Text> ({agentTasks.length})
</Text>
<Box flexDirection="column">
{agentTasks.map(item_9 => <Item key={item_9.id} item={item_9} isSelected={item_9.id === currentSelection?.id} />)}
{agentTasks.map(item_10 => <Item key={item_10.id} item={item_10} isSelected={item_10.id === currentSelection?.id} />)}
</Box>
</Box>}

{workflowTasks.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || remoteSessions.length > 0 || agentTasks.length > 0 ? 1 : 0}>
{workflowTasks.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || mcpServerTasks.length > 0 || remoteSessions.length > 0 || agentTasks.length > 0 ? 1 : 0}>
<Text dimColor>
<Text bold>{' '}Workflows</Text> ({workflowTasks.length})
</Text>
<Box flexDirection="column">
{workflowTasks.map(item_10 => <Item key={item_10.id} item={item_10} isSelected={item_10.id === currentSelection?.id} />)}
{workflowTasks.map(item_11 => <Item key={item_11.id} item={item_11} isSelected={item_11.id === currentSelection?.id} />)}
</Box>
</Box>}

{dreamTasks_0.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || remoteSessions.length > 0 || agentTasks.length > 0 || workflowTasks.length > 0 ? 1 : 0}>
{dreamTasks_0.length > 0 && <Box flexDirection="column" marginTop={teammateTasks.length > 0 || bashTasks.length > 0 || mcpMonitors.length > 0 || mcpServerTasks.length > 0 || remoteSessions.length > 0 || agentTasks.length > 0 || workflowTasks.length > 0 ? 1 : 0}>
<Box flexDirection="column">
{dreamTasks_0.map(item_11 => <Item key={item_11.id} item={item_11} isSelected={item_11.id === currentSelection?.id} />)}
{dreamTasks_0.map(item_12 => <Item key={item_12.id} item={item_12} isSelected={item_12.id === currentSelection?.id} />)}
</Box>
</Box>}
</Box>}
Expand Down Expand Up @@ -540,6 +564,14 @@ function toListItem(task: BackgroundTaskState): ListItem {
status: task.status,
task
};
case 'mcp_server':
return {
id: task.id,
type: 'mcp_server',
label: task.description,
status: task.status,
task
};
case 'dream':
return {
id: task.id,
Expand Down
96 changes: 96 additions & 0 deletions src/components/tasks/McpServerTaskDetailDialog.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
import * as React from 'react'
import { useElapsedTime } from '../../hooks/useElapsedTime.js'
import type { KeyboardEvent } from '../../ink/events/keyboard-event.js'
import { Box, Text } from '../../ink.js'
import { useKeybindings } from '../../keybindings/useKeybinding.js'
import type { McpServerTaskState } from '../../tasks/McpServerTask/McpServerTask.js'
import type { DeepImmutable } from '../../types/utils.js'
import { Byline } from '../design-system/Byline.js'
import { Dialog } from '../design-system/Dialog.js'
import { KeyboardShortcutHint } from '../design-system/KeyboardShortcutHint.js'

type Props = {
task: DeepImmutable<McpServerTaskState>
onDone: () => void
onBack?: () => void
onKill?: () => void
}

/**
* Detail view for an MCP server-initiated task. The remote task is owned by
* the MCP server; this view shows what it has reported (statusMessage) and
* offers tasks/cancel through the kill control.
*/
export function McpServerTaskDetailDialog({
task,
onDone,
onBack,
onKill,
}: Props): React.ReactNode {
const elapsedTime = useElapsedTime(
task.startTime,
task.status === 'running',
1000,
0,
)

useKeybindings({ 'confirm:yes': onDone }, { context: 'Confirmation' })

function onKeyDown(e: KeyboardEvent) {
if (e.key === ' ') {
e.preventDefault()
onDone()
} else if (e.key === 'left' && onBack) {
e.preventDefault()
onBack()
} else if (e.key === 'x' && task.status === 'running' && onKill) {
e.preventDefault()
onKill()
}
}

return (
<Dialog
title={task.description}
onCancel={onDone}
color="background"
inputGuide={() => (
<Byline>
{onBack && <KeyboardShortcutHint shortcut="←" action="go back" />}
<KeyboardShortcutHint shortcut="Esc/Enter/Space" action="close" />
{task.status === 'running' && onKill && (
<KeyboardShortcutHint shortcut="x" action="cancel" />
)}
</Byline>
)}
>
<Box
flexDirection="column"
gap={1}
tabIndex={0}
autoFocus
onKeyDown={onKeyDown}
>
<Box flexDirection="column">
<Text>
<Text dimColor>server: </Text>
{task.mcpServerName}
</Text>
<Text>
<Text dimColor>tool: </Text>
{task.mcpToolName}
</Text>
<Text>
<Text dimColor>status: </Text>
{task.status}
{task.statusMessage ? `: ${task.statusMessage}` : ''}
</Text>
<Text>
<Text dimColor>elapsed: </Text>
{elapsedTime}
</Text>
</Box>
</Box>
</Dialog>
)
}
Loading
Loading