@xortex/xcode 3.0.0

package/tools/ConfigTool/supportedSettings.ts

@@ -0,0 +1,211 @@
+import { feature } from 'bun:bundle'
+import { getRemoteControlAtStartup } from '../../utils/config.js'
+import {
+  EDITOR_MODES,
+  NOTIFICATION_CHANNELS,
+  TEAMMATE_MODES,
+} from '../../utils/configConstants.js'
+import { getModelOptions } from '../../utils/model/modelOptions.js'
+import { validateModel } from '../../utils/model/validateModel.js'
+import { THEME_NAMES, THEME_SETTINGS } from '../../utils/theme.js'
+
+/** AppState keys that can be synced for immediate UI effect */
+type SyncableAppStateKey = 'verbose' | 'mainLoopModel' | 'thinkingEnabled'
+
+type SettingConfig = {
+  source: 'global' | 'settings'
+  type: 'boolean' | 'string'
+  description: string
+  path?: string[]
+  options?: readonly string[]
+  getOptions?: () => string[]
+  appStateKey?: SyncableAppStateKey
+  /** Async validation called when writing/setting a value */
+  validateOnWrite?: (v: unknown) => Promise<{ valid: boolean; error?: string }>
+  /** Format value when reading/getting for display */
+  formatOnRead?: (v: unknown) => unknown
+}
+
+export const SUPPORTED_SETTINGS: Record<string, SettingConfig> = {
+  theme: {
+    source: 'global',
+    type: 'string',
+    description: 'Color theme for the UI',
+    options: feature('AUTO_THEME') ? THEME_SETTINGS : THEME_NAMES,
+  },
+  editorMode: {
+    source: 'global',
+    type: 'string',
+    description: 'Key binding mode',
+    options: EDITOR_MODES,
+  },
+  verbose: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Show detailed debug output',
+    appStateKey: 'verbose',
+  },
+  preferredNotifChannel: {
+    source: 'global',
+    type: 'string',
+    description: 'Preferred notification channel',
+    options: NOTIFICATION_CHANNELS,
+  },
+  autoCompactEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Auto-compact when context is full',
+  },
+  autoMemoryEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable auto-memory',
+  },
+  autoDreamEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable background memory consolidation',
+  },
+  fileCheckpointingEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Enable file checkpointing for code rewind',
+  },
+  showTurnDuration: {
+    source: 'global',
+    type: 'boolean',
+    description:
+      'Show turn duration message after responses (e.g., "Cooked for 1m 6s")',
+  },
+  terminalProgressBarEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Show OSC 9;4 progress indicator in supported terminals',
+  },
+  todoFeatureEnabled: {
+    source: 'global',
+    type: 'boolean',
+    description: 'Enable todo/task tracking',
+  },
+  model: {
+    source: 'settings',
+    type: 'string',
+    description: 'Override the default model',
+    appStateKey: 'mainLoopModel',
+    getOptions: () => {
+      try {
+        return getModelOptions()
+          .filter(o => o.value !== null)
+          .map(o => o.value as string)
+      } catch {
+        return ['sonnet', 'opus', 'haiku']
+      }
+    },
+    validateOnWrite: v => validateModel(String(v)),
+    formatOnRead: v => (v === null ? 'default' : v),
+  },
+  alwaysThinkingEnabled: {
+    source: 'settings',
+    type: 'boolean',
+    description: 'Enable extended thinking (false to disable)',
+    appStateKey: 'thinkingEnabled',
+  },
+  'permissions.defaultMode': {
+    source: 'settings',
+    type: 'string',
+    description: 'Default permission mode for tool usage',
+    options: feature('TRANSCRIPT_CLASSIFIER')
+      ? ['default', 'plan', 'acceptEdits', 'dontAsk', 'auto']
+      : ['default', 'plan', 'acceptEdits', 'dontAsk'],
+  },
+  language: {
+    source: 'settings',
+    type: 'string',
+    description:
+      'Preferred language for Claude responses and voice dictation (e.g., "japanese", "spanish")',
+  },
+  teammateMode: {
+    source: 'global',
+    type: 'string',
+    description:
+      'How to spawn teammates: "tmux" for traditional tmux, "in-process" for same process, "auto" to choose automatically',
+    options: TEAMMATE_MODES,
+  },
+  ...(process.env.USER_TYPE === 'ant'
+    ? {
+        classifierPermissionsEnabled: {
+          source: 'settings' as const,
+          type: 'boolean' as const,
+          description:
+            'Enable AI-based classification for Bash(prompt:...) permission rules',
+        },
+      }
+    : {}),
+  ...(feature('VOICE_MODE')
+    ? {
+        voiceEnabled: {
+          source: 'settings' as const,
+          type: 'boolean' as const,
+          description: 'Enable voice dictation (hold-to-talk)',
+        },
+      }
+    : {}),
+  ...(feature('BRIDGE_MODE')
+    ? {
+        remoteControlAtStartup: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Enable Remote Control for all sessions (true | false | default)',
+          formatOnRead: () => getRemoteControlAtStartup(),
+        },
+      }
+    : {}),
+  ...(feature('KAIROS') || feature('KAIROS_PUSH_NOTIFICATION')
+    ? {
+        taskCompleteNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Push to your mobile device when idle after Claude finishes (requires Remote Control)',
+        },
+        inputNeededNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Push to your mobile device when a permission prompt or question is waiting (requires Remote Control)',
+        },
+        agentPushNotifEnabled: {
+          source: 'global' as const,
+          type: 'boolean' as const,
+          description:
+            'Allow Claude to push to your mobile device when it deems it appropriate (requires Remote Control)',
+        },
+      }
+    : {}),
+}
+
+export function isSupported(key: string): boolean {
+  return key in SUPPORTED_SETTINGS
+}
+
+export function getConfig(key: string): SettingConfig | undefined {
+  return SUPPORTED_SETTINGS[key]
+}
+
+export function getAllKeys(): string[] {
+  return Object.keys(SUPPORTED_SETTINGS)
+}
+
+export function getOptionsForSetting(key: string): string[] | undefined {
+  const config = SUPPORTED_SETTINGS[key]
+  if (!config) return undefined
+  if (config.options) return [...config.options]
+  if (config.getOptions) return config.getOptions()
+  return undefined
+}
+
+export function getPath(key: string): string[] {
+  const config = SUPPORTED_SETTINGS[key]
+  return config?.path ?? key.split('.')
+}

package/tools/EnterPlanModeTool/EnterPlanModeTool.ts

@@ -0,0 +1,126 @@
+import { feature } from 'bun:bundle'
+import { z } from 'zod/v4'
+import {
+  getAllowedChannels,
+  handlePlanModeTransition,
+} from '../../bootstrap/state.js'
+import type { Tool } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { applyPermissionUpdate } from '../../utils/permissions/PermissionUpdate.js'
+import { prepareContextForPlanMode } from '../../utils/permissions/permissionSetup.js'
+import { isPlanModeInterviewPhaseEnabled } from '../../utils/planModeV2.js'
+import { ENTER_PLAN_MODE_TOOL_NAME } from './constants.js'
+import { getEnterPlanModeToolPrompt } from './prompt.js'
+import {
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseRejectedMessage,
+} from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    // No parameters needed
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    message: z.string().describe('Confirmation that plan mode was entered'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const EnterPlanModeTool: Tool<InputSchema, Output> = buildTool({
+  name: ENTER_PLAN_MODE_TOOL_NAME,
+  searchHint: 'switch to plan mode to design an approach before coding',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Requests permission to enter plan mode for complex tasks requiring exploration and design'
+  },
+  async prompt() {
+    return getEnterPlanModeToolPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return ''
+  },
+  shouldDefer: true,
+  isEnabled() {
+    // When --channels is active, ExitPlanMode is disabled (its approval
+    // dialog needs the terminal). Disable entry too so plan mode isn't a
+    // trap the model can enter but never leave.
+    if (
+      (feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
+      getAllowedChannels().length > 0
+    ) {
+      return false
+    }
+    return true
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  renderToolUseRejectedMessage,
+  async call(_input, context) {
+    if (context.agentId) {
+      throw new Error('EnterPlanMode tool cannot be used in agent contexts')
+    }
+
+    const appState = context.getAppState()
+    handlePlanModeTransition(appState.toolPermissionContext.mode, 'plan')
+
+    // Update the permission mode to 'plan'. prepareContextForPlanMode runs
+    // the classifier activation side effects when the user's defaultMode is
+    // 'auto' — see permissionSetup.ts for the full lifecycle.
+    context.setAppState(prev => ({
+      ...prev,
+      toolPermissionContext: applyPermissionUpdate(
+        prepareContextForPlanMode(prev.toolPermissionContext),
+        { type: 'setMode', mode: 'plan', destination: 'session' },
+      ),
+    }))
+
+    return {
+      data: {
+        message:
+          'Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.',
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam({ message }, toolUseID) {
+    const instructions = isPlanModeInterviewPhaseEnabled()
+      ? `${message}
+
+DO NOT write or edit any files except the plan file. Detailed workflow instructions will follow.`
+      : `${message}
+
+In plan mode, you should:
+1. Thoroughly explore the codebase to understand existing patterns
+2. Identify similar features and architectural approaches
+3. Consider multiple approaches and their trade-offs
+4. Use AskUserQuestion if you need to clarify the approach
+5. Design a concrete implementation strategy
+6. When ready, use ExitPlanMode to present your plan for approval
+
+Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase.`
+
+    return {
+      type: 'tool_result',
+      content: instructions,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

package/tools/EnterPlanModeTool/UI.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { BLACK_CIRCLE } from 'src/constants/figures.js';
+import { getModeColor } from 'src/utils/permissions/PermissionMode.js';
+import { Box, Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import type { ThemeName } from '../../utils/theme.js';
+import type { Output } from './EnterPlanModeTool.js';
+export function renderToolUseMessage(): React.ReactNode {
+  return null;
+}
+export function renderToolResultMessage(_output: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], _options: {
+  theme: ThemeName;
+}): React.ReactNode {
+  return <Box flexDirection="column" marginTop={1}>
+      <Box flexDirection="row">
+        <Text color={getModeColor('plan')}>{BLACK_CIRCLE}</Text>
+        <Text> Entered plan mode</Text>
+      </Box>
+      <Box paddingLeft={2}>
+        <Text dimColor>
+          Claude is now exploring and designing an implementation approach.
+        </Text>
+      </Box>
+    </Box>;
+}
+export function renderToolUseRejectedMessage(): React.ReactNode {
+  return <Box flexDirection="row" marginTop={1}>
+      <Text color={getModeColor('default')}>{BLACK_CIRCLE}</Text>
+      <Text> User declined to enter plan mode</Text>
+    </Box>;
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIkJMQUNLX0NJUkNMRSIsImdldE1vZGVDb2xvciIsIkJveCIsIlRleHQiLCJUb29sUHJvZ3Jlc3NEYXRhIiwiUHJvZ3Jlc3NNZXNzYWdlIiwiVGhlbWVOYW1lIiwiT3V0cHV0IiwicmVuZGVyVG9vbFVzZU1lc3NhZ2UiLCJSZWFjdE5vZGUiLCJyZW5kZXJUb29sUmVzdWx0TWVzc2FnZSIsIl9vdXRwdXQiLCJfcHJvZ3Jlc3NNZXNzYWdlc0Zvck1lc3NhZ2UiLCJfb3B0aW9ucyIsInRoZW1lIiwicmVuZGVyVG9vbFVzZVJlamVjdGVkTWVzc2FnZSJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgKiBhcyBSZWFjdCBmcm9tICdyZWFjdCdcbmltcG9ydCB7IEJMQUNLX0NJUkNMRSB9IGZyb20gJ3NyYy9jb25zdGFudHMvZmlndXJlcy5qcydcbmltcG9ydCB7IGdldE1vZGVDb2xvciB9IGZyb20gJ3NyYy91dGlscy9wZXJtaXNzaW9ucy9QZXJtaXNzaW9uTW9kZS5qcydcbmltcG9ydCB7IEJveCwgVGV4dCB9IGZyb20gJy4uLy4uL2luay5qcydcbmltcG9ydCB0eXBlIHsgVG9vbFByb2dyZXNzRGF0YSB9IGZyb20gJy4uLy4uL1Rvb2wuanMnXG5pbXBvcnQgdHlwZSB7IFByb2dyZXNzTWVzc2FnZSB9IGZyb20gJy4uLy4uL3R5cGVzL21lc3NhZ2UuanMnXG5pbXBvcnQgdHlwZSB7IFRoZW1lTmFtZSB9IGZyb20gJy4uLy4uL3V0aWxzL3RoZW1lLmpzJ1xuaW1wb3J0IHR5cGUgeyBPdXRwdXQgfSBmcm9tICcuL0VudGVyUGxhbk1vZGVUb29sLmpzJ1xuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZU1lc3NhZ2UoKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuIG51bGxcbn1cblxuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlclRvb2xSZXN1bHRNZXNzYWdlKFxuICBfb3V0cHV0OiBPdXRwdXQsXG4gIF9wcm9ncmVzc01lc3NhZ2VzRm9yTWVzc2FnZTogUHJvZ3Jlc3NNZXNzYWdlPFRvb2xQcm9ncmVzc0RhdGE+W10sXG4gIF9vcHRpb25zOiB7IHRoZW1lOiBUaGVtZU5hbWUgfSxcbik6IFJlYWN0LlJlYWN0Tm9kZSB7XG4gIHJldHVybiAoXG4gICAgPEJveCBmbGV4RGlyZWN0aW9uPVwiY29sdW1uXCIgbWFyZ2luVG9wPXsxfT5cbiAgICAgIDxCb3ggZmxleERpcmVjdGlvbj1cInJvd1wiPlxuICAgICAgICA8VGV4dCBjb2xvcj17Z2V0TW9kZUNvbG9yKCdwbGFuJyl9PntCTEFDS19DSVJDTEV9PC9UZXh0PlxuICAgICAgICA8VGV4dD4gRW50ZXJlZCBwbGFuIG1vZGU8L1RleHQ+XG4gICAgICA8L0JveD5cbiAgICAgIDxCb3ggcGFkZGluZ0xlZnQ9ezJ9PlxuICAgICAgICA8VGV4dCBkaW1Db2xvcj5cbiAgICAgICAgICBDbGF1ZGUgaXMgbm93IGV4cGxvcmluZyBhbmQgZGVzaWduaW5nIGFuIGltcGxlbWVudGF0aW9uIGFwcHJvYWNoLlxuICAgICAgICA8L1RleHQ+XG4gICAgICA8L0JveD5cbiAgICA8L0JveD5cbiAgKVxufVxuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFVzZVJlamVjdGVkTWVzc2FnZSgpOiBSZWFjdC5SZWFjdE5vZGUge1xuICByZXR1cm4gKFxuICAgIDxCb3ggZmxleERpcmVjdGlvbj1cInJvd1wiIG1hcmdpblRvcD17MX0+XG4gICAgICA8VGV4dCBjb2xvcj17Z2V0TW9kZUNvbG9yKCdkZWZhdWx0Jyl9PntCTEFDS19DSVJDTEV9PC9UZXh0PlxuICAgICAgPFRleHQ+IFVzZXIgZGVjbGluZWQgdG8gZW50ZXIgcGxhbiBtb2RlPC9UZXh0PlxuICAgIDwvQm94PlxuICApXG59XG4iXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBS0EsS0FBSyxNQUFNLE9BQU87QUFDOUIsU0FBU0MsWUFBWSxRQUFRLDBCQUEwQjtBQUN2RCxTQUFTQyxZQUFZLFFBQVEseUNBQXlDO0FBQ3RFLFNBQVNDLEdBQUcsRUFBRUMsSUFBSSxRQUFRLGNBQWM7QUFDeEMsY0FBY0MsZ0JBQWdCLFFBQVEsZUFBZTtBQUNyRCxjQUFjQyxlQUFlLFFBQVEsd0JBQXdCO0FBQzdELGNBQWNDLFNBQVMsUUFBUSxzQkFBc0I7QUFDckQsY0FBY0MsTUFBTSxRQUFRLHdCQUF3QjtBQUVwRCxPQUFPLFNBQVNDLG9CQUFvQkEsQ0FBQSxDQUFFLEVBQUVULEtBQUssQ0FBQ1UsU0FBUyxDQUFDO0VBQ3RELE9BQU8sSUFBSTtBQUNiO0FBRUEsT0FBTyxTQUFTQyx1QkFBdUJBLENBQ3JDQyxPQUFPLEVBQUVKLE1BQU0sRUFDZkssMkJBQTJCLEVBQUVQLGVBQWUsQ0FBQ0QsZ0JBQWdCLENBQUMsRUFBRSxFQUNoRVMsUUFBUSxFQUFFO0VBQUVDLEtBQUssRUFBRVIsU0FBUztBQUFDLENBQUMsQ0FDL0IsRUFBRVAsS0FBSyxDQUFDVSxTQUFTLENBQUM7RUFDakIsT0FDRSxDQUFDLEdBQUcsQ0FBQyxhQUFhLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQztBQUM3QyxNQUFNLENBQUMsR0FBRyxDQUFDLGFBQWEsQ0FBQyxLQUFLO0FBQzlCLFFBQVEsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUNSLFlBQVksQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUNELFlBQVksQ0FBQyxFQUFFLElBQUk7QUFDL0QsUUFBUSxDQUFDLElBQUksQ0FBQyxrQkFBa0IsRUFBRSxJQUFJO0FBQ3RDLE1BQU0sRUFBRSxHQUFHO0FBQ1gsTUFBTSxDQUFDLEdBQUcsQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDMUIsUUFBUSxDQUFDLElBQUksQ0FBQyxRQUFRO0FBQ3RCO0FBQ0EsUUFBUSxFQUFFLElBQUk7QUFDZCxNQUFNLEVBQUUsR0FBRztBQUNYLElBQUksRUFBRSxHQUFHLENBQUM7QUFFVjtBQUVBLE9BQU8sU0FBU2UsNEJBQTRCQSxDQUFBLENBQUUsRUFBRWhCLEtBQUssQ0FBQ1UsU0FBUyxDQUFDO0VBQzlELE9BQ0UsQ0FBQyxHQUFHLENBQUMsYUFBYSxDQUFDLEtBQUssQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDMUMsTUFBTSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQ1IsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQ0QsWUFBWSxDQUFDLEVBQUUsSUFBSTtBQUNoRSxNQUFNLENBQUMsSUFBSSxDQUFDLGlDQUFpQyxFQUFFLElBQUk7QUFDbkQsSUFBSSxFQUFFLEdBQUcsQ0FBQztBQUVWIiwiaWdub3JlTGlzdCI6W119

package/tools/EnterPlanModeTool/constants.ts

@@ -0,0 +1 @@
+export const ENTER_PLAN_MODE_TOOL_NAME = 'EnterPlanMode'

package/tools/EnterPlanModeTool/prompt.ts

@@ -0,0 +1,170 @@
+import { isPlanModeInterviewPhaseEnabled } from '../../utils/planModeV2.js'
+import { ASK_USER_QUESTION_TOOL_NAME } from '../AskUserQuestionTool/prompt.js'
+
+const WHAT_HAPPENS_SECTION = `## What Happens in Plan Mode
+
+In plan mode, you'll:
+1. Thoroughly explore the codebase using Glob, Grep, and Read tools
+2. Understand existing patterns and architecture
+3. Design an implementation approach
+4. Present your plan to the user for approval
+5. Use ${ASK_USER_QUESTION_TOOL_NAME} if you need to clarify approaches
+6. Exit plan mode with ExitPlanMode when ready to implement
+
+`
+
+function getEnterPlanModeToolPromptExternal(): string {
+  // When interview phase is enabled, omit the "What Happens" section —
+  // detailed workflow instructions arrive via the plan_mode attachment (messages.ts).
+  const whatHappens = isPlanModeInterviewPhaseEnabled()
+    ? ''
+    : WHAT_HAPPENS_SECTION
+
+  return `Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
+
+## When to Use This Tool
+
+**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
+
+1. **New Feature Implementation**: Adding meaningful new functionality
+   - Example: "Add a logout button" - where should it go? What should happen on click?
+   - Example: "Add form validation" - what rules? What error messages?
+
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" - many optimization strategies possible
+
+3. **Code Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the login flow" - what exactly should change?
+   - Example: "Refactor this component" - what's the target architecture?
+
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+   - Example: "Implement state management" - Redux vs Context vs custom solution
+
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
+   - Example: "Refactor the authentication system"
+   - Example: "Add a new API endpoint with tests"
+
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make the app faster" - need to profile and identify bottlenecks
+   - Example: "Fix the bug in checkout" - need to investigate root cause
+
+7. **User Preferences Matter**: The implementation could reasonably go multiple ways
+   - If you would use ${ASK_USER_QUESTION_TOOL_NAME} to clarify the approach, use EnterPlanMode instead
+   - Plan mode lets you explore first, then present options with context
+
+## When NOT to Use This Tool
+
+Only skip EnterPlanMode for simple tasks:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- Adding a single function with clear requirements
+- Tasks where the user has given very specific, detailed instructions
+- Pure research/exploration tasks (use the Agent tool with explore agent instead)
+
+${whatHappens}## Examples
+
+### GOOD - Use EnterPlanMode:
+User: "Add user authentication to the app"
+- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
+
+User: "Optimize the database queries"
+- Multiple approaches possible, need to profile first, significant impact
+
+User: "Implement dark mode"
+- Architectural decision on theme system, affects many components
+
+User: "Add a delete button to the user profile"
+- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
+
+User: "Update the error handling in the API"
+- Affects multiple files, user should approve the approach
+
+### BAD - Don't use EnterPlanMode:
+User: "Fix the typo in the README"
+- Straightforward, no planning needed
+
+User: "Add a console.log to debug this function"
+- Simple, obvious implementation
+
+User: "What files handle routing?"
+- Research task, not implementation planning
+
+## Important Notes
+
+- This tool REQUIRES user approval - they must consent to entering plan mode
+- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
+- Users appreciate being consulted before significant changes are made to their codebase
+`
+}
+
+function getEnterPlanModeToolPromptAnt(): string {
+  // When interview phase is enabled, omit the "What Happens" section —
+  // detailed workflow instructions arrive via the plan_mode attachment (messages.ts).
+  const whatHappens = isPlanModeInterviewPhaseEnabled()
+    ? ''
+    : WHAT_HAPPENS_SECTION
+
+  return `Use this tool when a task has genuine ambiguity about the right approach and getting user input before coding would prevent significant rework. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
+
+## When to Use This Tool
+
+Plan mode is valuable when the implementation approach is genuinely unclear. Use it when:
+
+1. **Significant Architectural Ambiguity**: Multiple reasonable approaches exist and the choice meaningfully affects the codebase
+   - Example: "Add caching to the API" - Redis vs in-memory vs file-based
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+
+2. **Unclear Requirements**: You need to explore and clarify before you can make progress
+   - Example: "Make the app faster" - need to profile and identify bottlenecks
+   - Example: "Refactor this module" - need to understand what the target architecture should be
+
+3. **High-Impact Restructuring**: The task will significantly restructure existing code and getting buy-in first reduces risk
+   - Example: "Redesign the authentication system"
+   - Example: "Migrate from one state management approach to another"
+
+## When NOT to Use This Tool
+
+Skip plan mode when you can reasonably infer the right approach:
+- The task is straightforward even if it touches multiple files
+- The user's request is specific enough that the implementation path is clear
+- You're adding a feature with an obvious implementation pattern (e.g., adding a button, a new endpoint following existing conventions)
+- Bug fixes where the fix is clear once you understand the bug
+- Research/exploration tasks (use the Agent tool instead)
+- The user says something like "can we work on X" or "let's do X" — just get started
+
+When in doubt, prefer starting work and using ${ASK_USER_QUESTION_TOOL_NAME} for specific questions over entering a full planning phase.
+
+${whatHappens}## Examples
+
+### GOOD - Use EnterPlanMode:
+User: "Add user authentication to the app"
+- Genuinely ambiguous: session vs JWT, where to store tokens, middleware structure
+
+User: "Redesign the data pipeline"
+- Major restructuring where the wrong approach wastes significant effort
+
+### BAD - Don't use EnterPlanMode:
+User: "Add a delete button to the user profile"
+- Implementation path is clear; just do it
+
+User: "Can we work on the search feature?"
+- User wants to get started, not plan
+
+User: "Update the error handling in the API"
+- Start working; ask specific questions if needed
+
+User: "Fix the typo in the README"
+- Straightforward, no planning needed
+
+## Important Notes
+
+- This tool REQUIRES user approval - they must consent to entering plan mode
+`
+}
+
+export function getEnterPlanModeToolPrompt(): string {
+  return process.env.USER_TYPE === 'ant'
+    ? getEnterPlanModeToolPromptAnt()
+    : getEnterPlanModeToolPromptExternal()
+}

package/tools/EnterWorktreeTool/EnterWorktreeTool.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod/v4'
+import { getSessionId, setOriginalCwd } from '../../bootstrap/state.js'
+import { clearSystemPromptSections } from '../../constants/systemPromptSections.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { Tool } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { clearMemoryFileCaches } from '../../utils/claudemd.js'
+import { getCwd } from '../../utils/cwd.js'
+import { findCanonicalGitRoot } from '../../utils/git.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getPlanSlug, getPlansDirectory } from '../../utils/plans.js'
+import { setCwd } from '../../utils/Shell.js'
+import { saveWorktreeState } from '../../utils/sessionStorage.js'
+import {
+  createWorktreeForSession,
+  getCurrentWorktreeSession,
+  validateWorktreeSlug,
+} from '../../utils/worktree.js'
+import { ENTER_WORKTREE_TOOL_NAME } from './constants.js'
+import { getEnterWorktreeToolPrompt } from './prompt.js'
+import { renderToolResultMessage, renderToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    name: z
+      .string()
+      .superRefine((s, ctx) => {
+        try {
+          validateWorktreeSlug(s)
+        } catch (e) {
+          ctx.addIssue({ code: 'custom', message: (e as Error).message })
+        }
+      })
+      .optional()
+      .describe(
+        'Optional name for the worktree. Each "/"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided.',
+      ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    worktreePath: z.string(),
+    worktreeBranch: z.string().optional(),
+    message: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+export const EnterWorktreeTool: Tool<InputSchema, Output> = buildTool({
+  name: ENTER_WORKTREE_TOOL_NAME,
+  searchHint: 'create an isolated git worktree and switch into it',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return 'Creates an isolated worktree (via git or configured hooks) and switches the session into it'
+  },
+  async prompt() {
+    return getEnterWorktreeToolPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'Creating worktree'
+  },
+  shouldDefer: true,
+  toAutoClassifierInput(input) {
+    return input.name ?? ''
+  },
+  renderToolUseMessage,
+  renderToolResultMessage,
+  async call(input) {
+    // Validate not already in a worktree created by this session
+    if (getCurrentWorktreeSession()) {
+      throw new Error('Already in a worktree session')
+    }
+
+    // Resolve to main repo root so worktree creation works from within a worktree
+    const mainRepoRoot = findCanonicalGitRoot(getCwd())
+    if (mainRepoRoot && mainRepoRoot !== getCwd()) {
+      process.chdir(mainRepoRoot)
+      setCwd(mainRepoRoot)
+    }
+
+    const slug = input.name ?? getPlanSlug()
+
+    const worktreeSession = await createWorktreeForSession(getSessionId(), slug)
+
+    process.chdir(worktreeSession.worktreePath)
+    setCwd(worktreeSession.worktreePath)
+    setOriginalCwd(getCwd())
+    saveWorktreeState(worktreeSession)
+    // Clear cached system prompt sections so env_info_simple recomputes with worktree context
+    clearSystemPromptSections()
+    // Clear memoized caches that depend on CWD
+    clearMemoryFileCaches()
+    getPlansDirectory.cache.clear?.()
+
+    logEvent('tengu_worktree_created', {
+      mid_session: true,
+    })
+
+    const branchInfo = worktreeSession.worktreeBranch
+      ? ` on branch ${worktreeSession.worktreeBranch}`
+      : ''
+
+    return {
+      data: {
+        worktreePath: worktreeSession.worktreePath,
+        worktreeBranch: worktreeSession.worktreeBranch,
+        message: `Created worktree at ${worktreeSession.worktreePath}${branchInfo}. The session is now working in the worktree. Use ExitWorktree to leave mid-session, or exit the session to be prompted.`,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam({ message }, toolUseID) {
+    return {
+      type: 'tool_result',
+      content: message,
+      tool_use_id: toolUseID,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)