ummaya 0.2.3 → 0.2.5

package/tui/src/tools/WorkspaceToolAdapter/WorkspaceToolAdapter.ts

@@ -0,0 +1,79 @@
+import type { Tool } from '../../Tool.js'
+import { BashTool } from '../BashTool/BashTool.js'
+import { FileEditTool } from '../FileEditTool/FileEditTool.js'
+import { FileReadTool } from '../FileReadTool/FileReadTool.js'
+import { FileWriteTool } from '../FileWriteTool/FileWriteTool.js'
+import { GlobTool } from '../GlobTool/GlobTool.js'
+import { GrepTool } from '../GrepTool/GrepTool.js'
+import { buildWorkspaceTool, type WorkspaceToolSpec } from './toolDefFactory.js'
+import {
+  WORKSPACE_BASH_TOOL_NAME,
+  WORKSPACE_EDIT_TOOL_NAME,
+  WORKSPACE_GLOB_TOOL_NAME,
+  WORKSPACE_GREP_TOOL_NAME,
+  WORKSPACE_READ_TOOL_NAME,
+  WORKSPACE_WRITE_TOOL_NAME,
+} from './toolNames.js'
+
+export {
+  WORKSPACE_BASH_TOOL_NAME,
+  WORKSPACE_EDIT_TOOL_NAME,
+  WORKSPACE_GLOB_TOOL_NAME,
+  WORKSPACE_GREP_TOOL_NAME,
+  WORKSPACE_READ_TOOL_NAME,
+  WORKSPACE_WRITE_TOOL_NAME,
+} from './toolNames.js'
+
+const WORKSPACE_TOOL_SPECS: readonly WorkspaceToolSpec[] = [
+  {
+    name: WORKSPACE_GLOB_TOOL_NAME,
+    source: () => GlobTool,
+    searchHint: 'find local files by name pattern',
+    alwaysLoad: true,
+    supportsUserFolderHints: true,
+    enforcesAllowedRoots: true,
+    readSearchDefaultAllowed: true,
+  },
+  {
+    name: WORKSPACE_GREP_TOOL_NAME,
+    source: () => GrepTool,
+    searchHint: 'search local file contents',
+    alwaysLoad: true,
+    supportsUserFolderHints: true,
+    enforcesAllowedRoots: true,
+    readSearchDefaultAllowed: true,
+  },
+  {
+    name: WORKSPACE_READ_TOOL_NAME,
+    source: () => FileReadTool,
+    searchHint: 'read local text files',
+    alwaysLoad: true,
+    enforcesAllowedRoots: true,
+    readSearchDefaultAllowed: true,
+  },
+  {
+    name: WORKSPACE_WRITE_TOOL_NAME,
+    source: () => FileWriteTool,
+    searchHint:
+      'create or overwrite local text files with visible permission boundary and blocked state',
+    blocksDocumentFormats: true,
+    enforcesAllowedRoots: true,
+  },
+  {
+    name: WORKSPACE_EDIT_TOOL_NAME,
+    source: () => FileEditTool,
+    searchHint: 'modify local text files in place',
+    blocksDocumentFormats: true,
+    enforcesAllowedRoots: true,
+  },
+  {
+    name: WORKSPACE_BASH_TOOL_NAME,
+    source: () => BashTool,
+    searchHint:
+      'run local shell commands with visible permission boundary and blocked state',
+  },
+]
+
+export function getWorkspaceTools(): readonly Tool[] {
+  return WORKSPACE_TOOL_SPECS.map(buildWorkspaceTool)
+}

package/tui/src/tools/WorkspaceToolAdapter/allowedRootPolicy.ts

@@ -0,0 +1,85 @@
+import { relative } from 'node:path'
+import type { ToolUseContext, ValidationResult } from '../../Tool.js'
+import { getCwd } from '../../utils/cwd.js'
+import { getPathsForPermissionCheck } from '../../utils/fsOperations.js'
+import { expandPath } from '../../utils/path.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import {
+  inferredDownloadsPath,
+  latestUserTextFromWorkspaceContext,
+} from './inputNormalization.js'
+
+export const WORKSPACE_PATH_ESCAPE_MESSAGE =
+  'Path resolves outside the allowed workspace roots. Re-select the folder or use an explicit document primitive flow.'
+
+function pathIsInsideRoot(candidate: string, root: string): boolean {
+  const rel = relative(root, candidate)
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/'))
+}
+
+function resolvedForms(path: string): readonly string[] {
+  return getPathsForPermissionCheck(expandPath(path))
+}
+
+function allowedWorkspaceRoots(context: ToolUseContext): readonly string[] {
+  const roots = new Set<string>(resolvedForms(getCwd()))
+  const appState = context.getAppState()
+  for (const directory of appState.toolPermissionContext.additionalWorkingDirectories.values()) {
+    for (const resolved of resolvedForms(directory.path)) {
+      roots.add(resolved)
+    }
+  }
+  const downloadsPath = inferredDownloadsPath(
+    latestUserTextFromWorkspaceContext(context),
+  )
+  if (downloadsPath !== undefined) {
+    for (const resolved of resolvedForms(downloadsPath)) {
+      roots.add(resolved)
+    }
+  }
+  return Array.from(roots)
+}
+
+export function validateWorkspacePathInsideAllowedRoots(
+  path: string,
+  context: ToolUseContext,
+): ValidationResult {
+  if (typeof context.getAppState !== 'function') return { result: true }
+  const targetForms = resolvedForms(path)
+  const rootForms = allowedWorkspaceRoots(context)
+  const inside = targetForms.every(target =>
+    rootForms.some(root => pathIsInsideRoot(target, root)),
+  )
+  if (inside) return { result: true }
+  return {
+    result: false,
+    message: WORKSPACE_PATH_ESCAPE_MESSAGE,
+    errorCode: 20,
+  }
+}
+
+export function workspaceReadSearchDecision(
+  path: string,
+  input: Record<string, unknown>,
+  context: ToolUseContext,
+): PermissionDecision {
+  const validation = validateWorkspacePathInsideAllowedRoots(path, context)
+  if (!validation.result) {
+    return {
+      behavior: 'deny',
+      message: validation.message,
+      decisionReason: {
+        type: 'workingDir',
+        reason: 'Path resolves outside allowed workspace roots',
+      },
+    }
+  }
+  return {
+    behavior: 'allow',
+    updatedInput: input,
+    decisionReason: {
+      type: 'mode',
+      mode: 'default',
+    },
+  }
+}

package/tui/src/tools/WorkspaceToolAdapter/documentFormatGuards.ts

@@ -0,0 +1,73 @@
+import type { Tool, ValidationResult } from '../../Tool.js'
+import { isWorkspaceInputRecord } from './inputNormalization.js'
+import { WORKSPACE_BASH_TOOL_NAME } from './toolNames.js'
+
+const DOCUMENT_DERIVATIVE_PATH_RE = /\.(?:hwp|hwpx|docx|pdf|xlsx|pptx)$/iu
+const DOCUMENT_FORMAT_PATH_RE = /\.(?:hwp|hwpx|docx|pdf|xlsx|pptx)$/iu
+const DOCUMENT_FORMAT_COMMAND_RE =
+  /\.(?:hwp|hwpx|docx|pdf|xlsx|pptx)(?=$|[\s"'`;|&<>])/iu
+
+export const DOCUMENT_DERIVATIVE_MUTATION_MESSAGE =
+  'Document derivatives must be mutated through the document primitive, not raw file tools.'
+
+const WORKSPACE_DOCUMENT_FORMAT_MESSAGE_PREFIX =
+  'Document formats must be edited through the document primitive, not'
+
+export function isDocumentDerivativePath(filePath: string): boolean {
+  return DOCUMENT_DERIVATIVE_PATH_RE.test(filePath)
+}
+
+export function documentDerivativeMutationValidation(
+  filePath: string,
+): ValidationResult | null {
+  if (!isDocumentDerivativePath(filePath)) return null
+  return {
+    result: false,
+    message: DOCUMENT_DERIVATIVE_MUTATION_MESSAGE,
+    errorCode: 20,
+  }
+}
+
+export function documentPathFromInput(input: unknown): string | undefined {
+  if (!isWorkspaceInputRecord(input)) return undefined
+  return typeof input.file_path === 'string' ? input.file_path : undefined
+}
+
+export function workspaceDocumentFormatPathValidation(
+  toolName: string,
+  input: unknown,
+): ValidationResult | null {
+  const filePath = documentPathFromInput(input)
+  if (filePath === undefined || !DOCUMENT_FORMAT_PATH_RE.test(filePath)) {
+    return null
+  }
+  return {
+    result: false,
+    message: `${WORKSPACE_DOCUMENT_FORMAT_MESSAGE_PREFIX} ${toolName}.`,
+    errorCode: 1,
+  }
+}
+
+export function workspaceBashDocumentFormatValidation(
+  source: Tool,
+  input: unknown,
+): ValidationResult | null {
+  if (!isWorkspaceInputRecord(input)) return null
+  if (input.dangerouslyDisableSandbox === true) {
+    return {
+      result: false,
+      message:
+        'workspace_bash does not allow dangerouslyDisableSandbox. Use the normal permission and sandbox boundary.',
+      errorCode: 2,
+    }
+  }
+  const command = typeof input.command === 'string' ? input.command : ''
+  if (DOCUMENT_FORMAT_COMMAND_RE.test(command) && !source.isReadOnly(input)) {
+    return {
+      result: false,
+      message: `${WORKSPACE_DOCUMENT_FORMAT_MESSAGE_PREFIX} ${WORKSPACE_BASH_TOOL_NAME}.`,
+      errorCode: 1,
+    }
+  }
+  return null
+}

package/tui/src/tools/WorkspaceToolAdapter/inputNormalization.ts

@@ -0,0 +1,105 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { ToolUseContext } from '../../Tool.js'
+import { WORKSPACE_GLOB_TOOL_NAME } from './toolNames.js'
+
+const DOCUMENT_FORMAT_HINT_RE =
+  /\b(?:hwp|hwpx|docx|pdf|xlsx|pptx)\b|\.(?:hwp|hwpx|docx|pdf|xlsx|pptx)\b/iu
+const HWPX_DOCUMENT_HINT_RE = /\bhwpx\b|\.hwpx\b/iu
+const MALFORMED_GLOB_EXTENSION_RE =
+  /\s|\*\.hwp\s+\*\.hwpx|\*\.hwpx\s+\*\.hwp/iu
+const DOWNLOADS_FOLDER_RE = /\bdownloads?\b|다운로드/iu
+
+type WorkspaceInputNormalizationSpec = {
+  readonly name: string
+  readonly supportsUserFolderHints?: boolean
+}
+
+export function isWorkspaceInputRecord(
+  input: unknown,
+): input is Record<string, unknown> {
+  return typeof input === 'object' && input !== null && !Array.isArray(input)
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => {
+      if (typeof block === 'string') return block
+      if (!isWorkspaceInputRecord(block)) return ''
+      return typeof block.text === 'string' ? block.text : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+export function latestUserTextFromWorkspaceContext(
+  context: ToolUseContext,
+): string {
+  for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+    const message = context.messages[index]
+    if (!isWorkspaceInputRecord(message)) continue
+    const nested = message.message
+    if (!isWorkspaceInputRecord(nested)) continue
+    if (nested.role !== 'user') continue
+    const text = textFromContent(nested.content)
+    if (text.trim()) return text
+  }
+  return ''
+}
+
+export function userTextMentionsDownloads(text: string): boolean {
+  return DOWNLOADS_FOLDER_RE.test(text)
+}
+
+export function inferredDownloadsPath(text: string): string | undefined {
+  return userTextMentionsDownloads(text)
+    ? join(homedir(), 'Downloads')
+    : undefined
+}
+
+function normalizedDocumentGlobPattern(
+  text: string,
+  pattern: unknown,
+): string | undefined {
+  if (typeof pattern !== 'string') return undefined
+  if (!DOCUMENT_FORMAT_HINT_RE.test(text)) return undefined
+  if (pattern.startsWith('**/') && !pattern.startsWith('**/*')) {
+    const basenamePattern = pattern.slice('**/'.length)
+    if (
+      !basenamePattern.includes('/') &&
+      /\.(?:hwp|hwpx|docx|pdf|xlsx|pptx)$/iu.test(basenamePattern)
+    ) {
+      return `**/*${basenamePattern}`
+    }
+  }
+  if (!HWPX_DOCUMENT_HINT_RE.test(text)) return undefined
+  if (!MALFORMED_GLOB_EXTENSION_RE.test(pattern)) return undefined
+  return '**/*.hwpx'
+}
+
+export function normalizeWorkspaceInputFromContext(
+  spec: WorkspaceInputNormalizationSpec,
+  input: unknown,
+  context: ToolUseContext,
+): unknown {
+  if (!spec.supportsUserFolderHints) return input
+  if (!isWorkspaceInputRecord(input)) return input
+  const userText = latestUserTextFromWorkspaceContext(context)
+  if (spec.name === WORKSPACE_GLOB_TOOL_NAME) {
+    const normalizedPattern = normalizedDocumentGlobPattern(
+      userText,
+      input.pattern,
+    )
+    if (normalizedPattern !== undefined) {
+      input.pattern = normalizedPattern
+    }
+  }
+  if (typeof input.path === 'string' && input.path.trim()) return input
+  const inferredPath = inferredDownloadsPath(userText)
+  if (inferredPath !== undefined) {
+    input.path = inferredPath
+  }
+  return input
+}

package/tui/src/tools/WorkspaceToolAdapter/mcpExposurePolicy.ts

@@ -0,0 +1,64 @@
+import type { ToolPermissionContext } from '../../Tool.js'
+import { mcpInfoFromString } from '../../services/mcp/mcpStringUtils.js'
+import { getAllowRules } from '../../utils/permissions/permissions.js'
+
+type McpExposureCandidate = {
+  readonly name: string
+  readonly mcpInfo?: { readonly serverName: string; readonly toolName: string }
+}
+
+export const MCP_MODEL_EXPOSURE_SERVER_CLASSES = [
+  'ummaya',
+  'trusted-configured',
+  'untrusted-configured',
+] as const
+
+export type McpModelExposureServerClass =
+  (typeof MCP_MODEL_EXPOSURE_SERVER_CLASSES)[number]
+
+function getMcpServerName(tool: McpExposureCandidate): string | null {
+  if (tool.mcpInfo?.serverName) return tool.mcpInfo.serverName
+  return mcpInfoFromString(tool.name)?.serverName ?? null
+}
+
+function hasTrustedConfiguredMcpServerRecord(
+  permissionContext: ToolPermissionContext,
+  serverName: string,
+): boolean {
+  return getAllowRules(permissionContext).some(rule => {
+    if (rule.ruleValue.ruleContent !== undefined) return false
+    const ruleInfo = mcpInfoFromString(rule.ruleValue.toolName)
+    if (ruleInfo === null) return false
+    return (
+      ruleInfo.serverName === serverName &&
+      (ruleInfo.toolName === undefined || ruleInfo.toolName === '*')
+    )
+  })
+}
+
+export function classifyMcpServerForModelExposure(
+  tool: McpExposureCandidate,
+  permissionContext: ToolPermissionContext,
+): McpModelExposureServerClass {
+  const serverName = getMcpServerName(tool)
+  if (serverName === 'ummaya') return 'ummaya'
+  if (serverName === null) return 'untrusted-configured'
+  if (hasTrustedConfiguredMcpServerRecord(permissionContext, serverName)) {
+    return 'trusted-configured'
+  }
+  return 'untrusted-configured'
+}
+
+export function isModelFacingMcpTool(
+  tool: McpExposureCandidate,
+  permissionContext: ToolPermissionContext,
+): boolean {
+  const serverClass = classifyMcpServerForModelExposure(tool, permissionContext)
+  switch (serverClass) {
+    case 'ummaya':
+    case 'trusted-configured':
+      return true
+    case 'untrusted-configured':
+      return false
+  }
+}

package/tui/src/tools/WorkspaceToolAdapter/toolDefFactory.ts

@@ -0,0 +1,215 @@
+import type { Tool } from '../../Tool.js'
+import { validateWorkspacePathInsideAllowedRoots, workspaceReadSearchDecision } from './allowedRootPolicy.js'
+import {
+  isWorkspaceInputRecord,
+  normalizeWorkspaceInputFromContext,
+} from './inputNormalization.js'
+import {
+  workspaceBashDocumentFormatValidation,
+  workspaceDocumentFormatPathValidation,
+} from './documentFormatGuards.js'
+import { WORKSPACE_BASH_TOOL_NAME } from './toolNames.js'
+
+export type WorkspaceToolSpec = {
+  readonly name: string
+  readonly source: () => Tool
+  readonly searchHint: string
+  readonly alwaysLoad?: boolean
+  readonly shouldDefer?: boolean
+  readonly blocksDocumentFormats?: boolean
+  readonly supportsUserFolderHints?: boolean
+  readonly enforcesAllowedRoots?: boolean
+  readonly readSearchDefaultAllowed?: boolean
+}
+
+function migrateToolText(text: string): string {
+  return text
+    .replace(/\bGlob\b/g, 'workspace_glob')
+    .replace(/\bGrep\b/g, 'workspace_grep')
+    .replace(/\bRead\b/g, 'workspace_read')
+    .replace(/\bWrite\b/g, 'workspace_write')
+    .replace(/\bEdit\b/g, 'workspace_edit')
+    .replace(/\bBash\b/g, WORKSPACE_BASH_TOOL_NAME)
+}
+
+function lazyWorkspaceToolOptionals(
+  tool: Tool,
+  source: () => Tool,
+): Tool {
+  Object.defineProperties(tool, {
+    backfillObservableInput: { get: () => source().backfillObservableInput },
+    extractSearchText: { get: () => source().extractSearchText },
+    getToolUseSummary: { get: () => source().getToolUseSummary },
+    inputJSONSchema: { get: () => source().inputJSONSchema },
+    inputsEquivalent: { get: () => source().inputsEquivalent },
+    isLsp: { get: () => source().isLsp },
+    isMcp: { get: () => source().isMcp },
+    isOpenWorld: { get: () => source().isOpenWorld },
+    isResultTruncated: { get: () => source().isResultTruncated },
+    isTransparentWrapper: { get: () => source().isTransparentWrapper },
+    mcpInfo: { get: () => source().mcpInfo },
+    outputSchema: { get: () => source().outputSchema },
+    preparePermissionMatcher: { get: () => source().preparePermissionMatcher },
+    renderGroupedToolUse: { get: () => source().renderGroupedToolUse },
+    renderToolResultMessage: { get: () => source().renderToolResultMessage },
+    renderToolUseErrorMessage: { get: () => source().renderToolUseErrorMessage },
+    renderToolUseProgressMessage: {
+      get: () => source().renderToolUseProgressMessage,
+    },
+    renderToolUseQueuedMessage: { get: () => source().renderToolUseQueuedMessage },
+    renderToolUseRejectedMessage: {
+      get: () => source().renderToolUseRejectedMessage,
+    },
+    renderToolUseTag: { get: () => source().renderToolUseTag },
+    requiresUserInteraction: { get: () => source().requiresUserInteraction },
+    strict: { get: () => source().strict },
+    userFacingNameBackgroundColor: {
+      get: () => source().userFacingNameBackgroundColor,
+    },
+  })
+  return tool
+}
+
+export function buildWorkspaceTool(spec: WorkspaceToolSpec): Tool {
+  const source = spec.source
+  const workspaceTool: Tool = {
+    name: spec.name,
+    aliases: [],
+    searchHint: spec.searchHint,
+    alwaysLoad: spec.alwaysLoad,
+    shouldDefer: spec.alwaysLoad ? false : spec.shouldDefer ?? true,
+    get maxResultSizeChars() {
+      return source().maxResultSizeChars
+    },
+    get inputSchema() {
+      return source().inputSchema
+    },
+    call(input, context, canUseTool, parentMessage, onProgress) {
+      const normalizedInput = normalizeWorkspaceInputFromContext(
+        spec,
+        input,
+        context,
+      )
+      return source().call(
+        normalizedInput,
+        context,
+        canUseTool,
+        parentMessage,
+        onProgress,
+      )
+    },
+    async description(input, options) {
+      const base = await source().description(input, options)
+      return `${migrateToolText(base)}
+
+UMMAYA workspace adapter: this tool delegates to the Claude Code local workspace implementation under a namespaced tool id. Use the document primitive for HWPX, HWP, DOCX, PDF, XLSX, and PPTX content edits.`
+    },
+    async prompt(options) {
+      const base = await source().prompt(options)
+      return `${migrateToolText(base)}
+
+UMMAYA workspace boundary:
+- This adapter is for local workspace text/file access.
+- Use document for HWPX, HWP, DOCX, PDF, XLSX, and PPTX reading, editing, rendering, diffing, or saving.
+- Do not call raw Claude Code tool names; use the workspace_* adapter names exposed in this session.`
+    },
+    async validateInput(input, context) {
+      const sourceTool = source()
+      normalizeWorkspaceInputFromContext(spec, input, context)
+      if (spec.blocksDocumentFormats) {
+        const documentValidation = workspaceDocumentFormatPathValidation(
+          spec.name,
+          input,
+        )
+        if (documentValidation !== null) return documentValidation
+      }
+      const workspacePath =
+        typeof sourceTool.getPath === 'function' && isWorkspaceInputRecord(input)
+          ? sourceTool.getPath(input)
+          : undefined
+      if (spec.enforcesAllowedRoots && workspacePath) {
+        const workspaceValidation = validateWorkspacePathInsideAllowedRoots(
+          workspacePath,
+          context,
+        )
+        if (!workspaceValidation.result) return workspaceValidation
+      }
+      if (spec.name === WORKSPACE_BASH_TOOL_NAME) {
+        const bashValidation = workspaceBashDocumentFormatValidation(
+          sourceTool,
+          input,
+        )
+        if (bashValidation !== null) return bashValidation
+      }
+      return sourceTool.validateInput
+        ? sourceTool.validateInput(input, context)
+        : { result: true }
+    },
+    async checkPermissions(input, context) {
+      const sourceTool = source()
+      const normalizedInput = normalizeWorkspaceInputFromContext(
+        spec,
+        input,
+        context,
+      )
+      if (
+        spec.readSearchDefaultAllowed &&
+        typeof sourceTool.getPath === 'function'
+      ) {
+        if (!isWorkspaceInputRecord(normalizedInput)) {
+          return sourceTool.checkPermissions(normalizedInput, context)
+        }
+        return workspaceReadSearchDecision(
+          sourceTool.getPath(normalizedInput),
+          normalizedInput,
+          context,
+        )
+      }
+      return sourceTool.checkPermissions(normalizedInput, context)
+    },
+    isConcurrencySafe(input) {
+      return source().isConcurrencySafe(input)
+    },
+    isDestructive(input) {
+      return source().isDestructive?.(input) ?? false
+    },
+    isEnabled() {
+      return source().isEnabled()
+    },
+    isReadOnly(input) {
+      return source().isReadOnly(input)
+    },
+    interruptBehavior() {
+      return source().interruptBehavior?.() ?? 'block'
+    },
+    isSearchOrReadCommand(input) {
+      return (
+        source().isSearchOrReadCommand?.(input) ?? {
+          isSearch: false,
+          isRead: false,
+          isList: false,
+        }
+      )
+    },
+    mapToolResultToToolResultBlockParam(content, toolUseID) {
+      return source().mapToolResultToToolResultBlockParam(content, toolUseID)
+    },
+    renderToolUseMessage(input, options) {
+      return source().renderToolUseMessage(input, options)
+    },
+    toAutoClassifierInput(input) {
+      return source().toAutoClassifierInput(input)
+    },
+    userFacingName() {
+      return spec.name
+    },
+    getActivityDescription(input) {
+      const activity = source().getActivityDescription?.(input)
+      return activity ? migrateToolText(activity) : spec.name
+    },
+  }
+  Object.defineProperty(workspaceTool, 'getPath', {
+    get: () => source().getPath,
+  })
+  return lazyWorkspaceToolOptionals(workspaceTool, source)
+}

package/tui/src/tools/WorkspaceToolAdapter/toolNames.ts

@@ -0,0 +1,6 @@
+export const WORKSPACE_GLOB_TOOL_NAME = 'workspace_glob'
+export const WORKSPACE_GREP_TOOL_NAME = 'workspace_grep'
+export const WORKSPACE_READ_TOOL_NAME = 'workspace_read'
+export const WORKSPACE_WRITE_TOOL_NAME = 'workspace_write'
+export const WORKSPACE_EDIT_TOOL_NAME = 'workspace_edit'
+export const WORKSPACE_BASH_TOOL_NAME = 'workspace_bash'

package/tui/src/tools/WorkspaceToolAdapter/workspacePolicy.ts

@@ -0,0 +1,15 @@
+export {
+  validateWorkspacePathInsideAllowedRoots,
+  workspaceReadSearchDecision,
+  WORKSPACE_PATH_ESCAPE_MESSAGE,
+} from './allowedRootPolicy.js'
+export {
+  documentDerivativeMutationValidation,
+  DOCUMENT_DERIVATIVE_MUTATION_MESSAGE,
+  isDocumentDerivativePath,
+} from './documentFormatGuards.js'
+export {
+  inferredDownloadsPath,
+  latestUserTextFromWorkspaceContext,
+  userTextMentionsDownloads,
+} from './inputNormalization.js'

package/tui/src/tools/_shared/citizenUserText.ts

@@ -0,0 +1,49 @@
+const SYNTHETIC_USER_CONTEXT_RE =
+  /<available_adapters\b|<\/available_adapters>|<available-deferred-tools\b|<\/available-deferred-tools>|##\s*Available tools|Current session context|Concrete UMMAYA|Pick a concrete adapter from <available_adapters>|Prefer concrete adapter function calls|<tool_use_error\b|<\/tool_use_error>|AdapterNotFound:|Permission delegation required:|tool-choice mismatch|Required follow-up for this tool chain|Emergency evidence chain complete|KMA analyzed weather-chart|Protected-domain/iu
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function messageContent(message: unknown): unknown {
+  const outer = asRecord(message)
+  const inner = asRecord(outer?.message)
+  return inner?.content ?? outer?.content
+}
+
+function contentHasToolResult(content: unknown): boolean {
+  if (!Array.isArray(content)) return false
+  return content.some(block => asRecord(block)?.type === 'tool_result')
+}
+
+export function isSyntheticUserMessage(message: unknown): boolean {
+  const outer = asRecord(message)
+  const inner = asRecord(outer?.message)
+  return (
+    outer?.isMeta === true ||
+    inner?.isMeta === true ||
+    outer?.isCompactSummary === true ||
+    outer?.isVisibleInTranscriptOnly === true ||
+    outer?.toolUseResult !== undefined ||
+    outer?.sourceToolAssistantUUID !== undefined ||
+    contentHasToolResult(messageContent(message))
+  )
+}
+
+export function isSyntheticUserText(text: string): boolean {
+  const trimmed = text.trim()
+  return trimmed.length > 0 && SYNTHETIC_USER_CONTEXT_RE.test(trimmed)
+}
+
+export function isNonSyntheticUserText(text: string): boolean {
+  return text.trim().length > 0 && !isSyntheticUserText(text)
+}
+
+export function isNonSyntheticUserMessageText(
+  message: unknown,
+  text: string,
+): boolean {
+  return !isSyntheticUserMessage(message) && isNonSyntheticUserText(text)
+}