@miphamai/cli 0.36.2 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.36.2",
+  "version": "0.38.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/agent-registry.ts

@@ -73,7 +73,7 @@ export class AgentRegistry {
                 .split(',')
                 .map((s) => s.trim())
             : undefined,
-          background: (data.background as boolean) || false,
+          background: typeof data.background === 'boolean' ? data.background : undefined,
           memory: data.memory as 'user' | 'project' | 'local' | undefined,
           source,
           filePath: fullPath,
@@ -125,7 +125,6 @@ export class AgentRegistry {
         systemPrompt: BUILTIN_SYSTEM_PROMPTS[builtinType],
         model: 'inherit',
         permissionMode: 'inherit',
-        background: false,
         source: 'builtin',
       }
     }

package/src/agent/cross-session/discovery.ts

@@ -5,6 +5,7 @@ import {
   existsSync,
   mkdirSync,
   unlinkSync,
+  statSync,
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir, hostname } from 'node:os'
@@ -13,6 +14,9 @@ import type { SessionInfo } from '../../shared/types'
 const MIPHAM_HOME = join(homedir(), '.mipham')
 const ACTIVE_SESSIONS_DIR = join(MIPHAM_HOME, '.active-sessions')
 
+/** A session whose heartbeat file hasn't been touched in this long is dead. */
+const STALE_SESSION_TTL_MS = 10 * 60 * 1000 // 10 min — heartbeat is 30s
+
 /**
  * Register the current session as active.
  * Writes a SessionInfo JSON file + updates mtime for heartbeat.
@@ -56,11 +60,19 @@ export function discoverSessions(): SessionInfo[] {
 
   try {
     const files = readdirSync(ACTIVE_SESSIONS_DIR).filter((f) => f.endsWith('.json'))
+    const now = Date.now()
 
     const sessions: SessionInfo[] = []
     for (const file of files) {
+      const filePath = join(ACTIVE_SESSIONS_DIR, file)
       try {
-        const raw = readFileSync(join(ACTIVE_SESSIONS_DIR, file), 'utf-8')
+        // Prune stale session files (crashed without unregistering). A live
+        // session's 30s heartbeat keeps mtime fresh; 10 min of silence = dead.
+        if (now - statSync(filePath).mtimeMs > STALE_SESSION_TTL_MS) {
+          unlinkSync(filePath)
+          continue
+        }
+        const raw = readFileSync(filePath, 'utf-8')
         const info = JSON.parse(raw) as SessionInfo
         sessions.push(info)
       } catch {
@@ -97,3 +109,35 @@ export function createSessionInfo(
     model,
   }
 }
+
+/**
+ * Return a unique session name among active sessions. If `preferred` is taken
+ * by another session (excluding `selfId`), append `-2`, `-3`, … until free.
+ * Pure with respect to `existing` — no filesystem access, so it's unit-testable.
+ */
+export function ensureUniqueSessionName(
+  preferred: string,
+  existing: SessionInfo[],
+  selfId?: string,
+): string {
+  const taken = new Set(existing.filter((s) => s.id !== selfId).map((s) => s.name))
+  if (!taken.has(preferred)) return preferred
+  let i = 2
+  while (taken.has(`${preferred}-${i}`)) i++
+  return `${preferred}-${i}`
+}
+
+/**
+ * Rename an active session in the registry. Enforces uniqueness against other
+ * live sessions (excluding self). Returns null if the session isn't registered.
+ */
+export function renameActiveSession(sessionId: string, newName: string): string | null {
+  const filePath = join(ACTIVE_SESSIONS_DIR, `${sessionId}.json`)
+  if (!existsSync(filePath)) return null
+  const raw = readFileSync(filePath, 'utf-8')
+  const info = JSON.parse(raw) as SessionInfo
+  const others = discoverSessions().filter((s) => s.id !== sessionId)
+  info.name = ensureUniqueSessionName(newName, others)
+  writeFileSync(filePath, JSON.stringify(info, null, 2), 'utf-8')
+  return info.name
+}

package/src/agent/cross-session/file-inbox.ts

@@ -6,6 +6,7 @@ import {
   unlinkSync,
   existsSync,
   renameSync,
+  lstatSync,
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
@@ -16,6 +17,15 @@ import type { SessionInfo } from '../../shared/types'
 const MIPHAM_HOME = join(homedir(), '.mipham')
 const INBOX_DIR = join(MIPHAM_HOME, 'inbox')
 
+/** True if a path exists and is a symbolic link (symlink-attack guard). */
+function isSymlink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
 /**
  * Filesystem-based cross-session transport.
  *
@@ -43,6 +53,9 @@ export class FileInboxTransport implements CrossSessionTransport {
       const inboxDir = join(INBOX_DIR, toSessionId)
       this.ensureDir(inboxDir)
 
+      // Symlink guard: refuse to write through a symlinked inbox directory.
+      if (isSymlink(INBOX_DIR) || isSymlink(inboxDir)) return false
+
       const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
       const filename = `${timestamp}-${msg.id}.json`
       const filePath = join(inboxDir, filename)
@@ -71,6 +84,8 @@ export class FileInboxTransport implements CrossSessionTransport {
     this.ensureInboxRoot()
     const inboxDir = join(INBOX_DIR, sessionId)
     if (!existsSync(inboxDir)) return []
+    // Symlink guard: refuse to read through a symlinked inbox directory.
+    if (isSymlink(INBOX_DIR) || isSymlink(inboxDir)) return []
 
     try {
       const files = readdirSync(inboxDir)

package/src/agent/message-router.ts

@@ -2,6 +2,7 @@ import { getMessageBus } from './message-bus'
 import { getFileInboxTransport } from './cross-session/file-inbox'
 import { discoverSessions, createSessionInfo } from './cross-session/discovery'
 import type { AgentMessage } from './message-bus'
+import type { SessionInfo } from '../shared/types'
 
 export interface RouteResult {
   success: boolean
@@ -10,6 +11,53 @@ export interface RouteResult {
   messageId?: string
 }
 
+export interface SessionResolution {
+  session?: SessionInfo
+  error?: string
+}
+
+/**
+ * Resolve a recipient among live sessions by bare name — session ID first,
+ * then session name. A name must uniquely match exactly one session; ambiguity
+ * and non-matches are reported as errors.
+ */
+export function resolveRecipientSession(sessions: SessionInfo[], to: string): SessionResolution {
+  const byId = sessions.find((s) => s.id === to)
+  if (byId) return { session: byId }
+
+  const byName = sessions.filter((s) => s.name === to)
+  if (byName.length === 1) return { session: byName[0] }
+  if (byName.length > 1) {
+    return {
+      error:
+        `Ambiguous session name "${to}" matches ${byName.length} live sessions. ` +
+        `Use a session ID to disambiguate (ListAgents).`,
+    }
+  }
+
+  return {
+    error: `No active session found matching "${to}". Use ListAgents to discover available sessions.`,
+  }
+}
+
+export interface MentionParse {
+  name: string
+  message: string
+}
+
+/**
+ * Parse a user-input `@name message` mention. Returns null when the input does
+ * not start with an @mention. The message may be empty — callers decide whether
+ * an empty body is valid. Used by the input bar to route a direct cross-session
+ * message without going through the AI.
+ */
+export function parseMention(input: string): MentionParse | null {
+  const trimmed = input.trim()
+  const m = /^@(\S+)(?:\s+([\s\S]+))?$/.exec(trimmed)
+  if (!m) return null
+  return { name: m[1]!, message: (m[2] ?? '').trim() }
+}
+
 /**
  * MessageRouter decides how to deliver a message based on the recipient.
  *
@@ -33,27 +81,26 @@ export class MessageRouter {
       }
     }
 
-    // Cross-session routing
+    // Cross-session routing (by session ID or bare name)
     const sessions = discoverSessions()
-    const targetSession = sessions.find((s) => s.id === to)
+    const resolution = resolveRecipientSession(sessions, to)
 
-    if (!targetSession) {
-      return {
-        success: false,
-        routedTo: 'unknown',
-        error: `No active session found with ID "${to}". Use ListAgents to discover available sessions.`,
-      }
+    if (resolution.error) {
+      return { success: false, routedTo: 'unknown', error: resolution.error }
     }
+    const targetSession = resolution.session!
 
-    // Get sender info
-    const senderSession = createSessionInfo(from, from)
+    // Get sender info — resolve the human-readable name when the sender is a
+    // registered session, else fall back to the raw id (e.g. non-session senders).
+    const senderName = discoverSessions().find((s) => s.id === from)?.name ?? from
+    const senderSession = createSessionInfo(from, senderName)
 
     try {
       const transport = getFileInboxTransport()
       const msg: AgentMessage = {
         id: `xmsg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
         from,
-        to,
+        to: targetSession.id,
         summary: summary.slice(0, 200),
         message,
         timestamp: new Date(),
@@ -61,7 +108,7 @@ export class MessageRouter {
         type: 'message',
       }
 
-      const delivered = await transport.send(senderSession, to, msg)
+      const delivered = await transport.send(senderSession, targetSession.id, msg)
       if (!delivered) {
         return { success: false, routedTo: 'inbox', error: 'Failed to write message to inbox.' }
       }

package/src/agent/sub-agent.ts

@@ -270,6 +270,13 @@ export class SubAgent {
     )
 
     context.setSystemPrompt(systemPrompt)
+
+    // Seed inherited parent conversation (fork inheritance) as a byte-identical
+    // prefix so the provider prompt cache is reused.
+    if (options.inheritContext && options.inheritContext.messages.length > 0) {
+      context.seedMessages(options.inheritContext.messages)
+    }
+
     context.addMessage({ role: 'user', content: prompt })
 
     const messages = context.getMessages()

package/src/agent/types.ts

@@ -1,5 +1,7 @@
 // apps/cli/src/agent/types.ts
 
+import type { Message } from '../shared/index.ts'
+
 export type SubAgentType = 'general' | 'explore' | 'plan' | 'code-review'
 
 export interface AgentFrontmatter {
@@ -26,7 +28,8 @@ export interface AgentDefinition {
   permissionMode: string
   maxTurns?: number
   skills?: string[]
-  background: boolean
+  /** Force background (true) or sync (false) execution. Unset inherits the tool default. */
+  background?: boolean
   source: 'builtin' | 'project' | 'user'
   filePath?: string
   memory?: 'user' | 'project' | 'local' // agent memory scope
@@ -47,6 +50,8 @@ export interface SubAgentOptions {
   onProgress?: (chunk: string) => void
   /** When set, tool executions use this path as cwd (git worktree isolation). */
   worktreePath?: string
+  /** Seed the sub-agent with a parent conversation prefix (e.g., fork inheritance). */
+  inheritContext?: { messages: Message[] }
   /** CRSI: when false, skip pattern analysis after agent execution. Default true. */
   autoPatternAnalysis?: boolean
 }

package/src/core/context-token.ts

@@ -12,6 +12,8 @@ export interface CacheTracker {
   isInCache(msg: Message): boolean
   /** Returns a snapshot of the cache state for metrics / logging. */
   getStatus(): CacheStatus
+  /** Record the set of messages currently held in the provider prompt cache. */
+  markCached?(messages: Message[]): void
   /** Clear the tracker state (does NOT evict from provider cache). */
   invalidate(): void
 }
@@ -41,11 +43,53 @@ export class NoopCacheTracker implements CacheTracker {
     this.messageCount = messages.length
   }
 
+  markCached(_messages: Message[]): void {
+    // No-op — prompt caching is disabled with this tracker.
+  }
+
   invalidate(): void {
     this.messageCount = 0
   }
 }
 
+/**
+ * Tracks which messages are currently held in the provider's prompt cache.
+ * The engine informs it of the cached prefix after each successful request
+ * (Anthropic caches "all messages except the newest"; DeepSeek/OpenAI auto-cache
+ * the same prefix). Object-identity based, so it stays valid across the
+ * ContextManager's shallow-copied message arrays.
+ */
+export class PrefixCacheTracker implements CacheTracker {
+  private cachedMessages = new WeakSet<Message>()
+  private cachedCount = 0
+  private cachedTokens = 0
+
+  markCached(messages: Message[]): void {
+    this.cachedMessages = new WeakSet(messages)
+    this.cachedCount = messages.length
+    this.cachedTokens = messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0)
+  }
+
+  isInCache(msg: Message): boolean {
+    return this.cachedMessages.has(msg)
+  }
+
+  getStatus(): CacheStatus {
+    return {
+      totalMessages: this.cachedCount,
+      cachedMessages: this.cachedCount,
+      cachedTokens: this.cachedTokens,
+      uncachedTokens: 0,
+    }
+  }
+
+  invalidate(): void {
+    this.cachedMessages = new WeakSet()
+    this.cachedCount = 0
+    this.cachedTokens = 0
+  }
+}
+
 /**
  * Estimate the token count for a single message.
  *

package/src/core/context.ts

@@ -116,6 +116,17 @@ export class ContextManager {
     this.checkCompression()
   }
 
+  /**
+   * Seed a batch of pre-existing messages (e.g., an inherited parent
+   * conversation). Unlike addMessage, this does not trigger compaction so the
+   * byte-identical prefix is preserved for prompt-cache hits.
+   */
+  seedMessages(messages: Message[]): void {
+    if (messages.length === 0) return
+    this.messages.push(...messages)
+    this.reEstimateTokens()
+  }
+
   getMessages(): Message[] {
     return [...this.messages]
   }
@@ -252,6 +263,11 @@ export class ContextManager {
     this.cacheTracker = tracker
   }
 
+  /** Mark a set of messages as cached by the provider (called after a request). */
+  markCached(messages: Message[]): void {
+    this.cacheTracker.markCached?.(messages)
+  }
+
   /** Get a snapshot of the provider prompt-cache state. */
   getCacheStatus(): CacheStatus {
     return this.cacheTracker.getStatus()

package/src/core/credential-masker/output-scrub.ts

@@ -1,6 +1,15 @@
 import { CREDENTIAL_SENTINEL } from './types'
 import type { CredentialMaskingConfig } from '../../shared/index.ts'
 
+/**
+ * Well-known secret token prefixes. These are high-signal formats that must
+ * never leak into output, independent of the configured patterns.
+ * - GitHub: ghp_ (personal access), gho_ (OAuth), ghs_ (server), ghu_/ghr_ (user/server-to-server), github_pat_ (fine-grained)
+ * - GitLab: glpat- (personal access), gldt- (deploy), glrt- (runner), gloas- (OAuth app)
+ */
+const TOKEN_REDACTION_PATTERN =
+  /\b(?:ghp_|gho_|ghs_|ghu_|ghr_|github_pat_|glpat-|gldt-|glrt-|gloas-)[A-Za-z0-9_-]{8,}/g
+
 /**
  * Scrub credential patterns from stdout/stderr output.
  * Uses the configured output_scrubbing patterns to detect and replace
@@ -10,6 +19,10 @@ export function maskOutput(output: string, config: CredentialMaskingConfig): str
   if (!config.enabled || !config.output_scrubbing.enabled) return output
 
   let masked = output
+
+  // Redact bare secret tokens by prefix (always on, independent of config patterns).
+  masked = masked.replace(TOKEN_REDACTION_PATTERN, CREDENTIAL_SENTINEL)
+
   for (const pattern of config.output_scrubbing.patterns) {
     try {
       // Strip (?i) inline flags — JS uses the 'i' flag instead

package/src/core/engine.ts

@@ -35,7 +35,7 @@ import { SelfCritique } from './self-critique.js'
 import { UsageTracker } from './usage-tracker'
 import { buildRequest, sendInferenceCheck, isInferenceHookEnabled } from './inference-hook'
 import { getFileInboxTransport } from '../agent/cross-session/file-inbox'
-import { getMessageBus } from '../agent/message-bus'
+import { getMessageBus, type AgentMessage } from '../agent/message-bus'
 import { createT } from '../i18n-core/t'
 import enUS from '../i18n-core/locales/en-US.json'
 import zhCN from '../i18n-core/locales/zh-CN.json'
@@ -47,6 +47,20 @@ const bundles: Record<string, TranslationMap> = {
 }
 const t = createT(bundles['en-US'] || (enUS as TranslationMap), enUS as TranslationMap)
 
+/**
+ * Drop inbound messages whose timestamp is older than the dialog-expiry TTL.
+ * A stale message's approval dialog is no longer relevant, so it's discarded
+ * before forwarding. Pure — unit-testable without touching the inbox.
+ */
+export function filterExpiredMessages(
+  messages: AgentMessage[],
+  dialogExpirySeconds: number,
+  now = Date.now(),
+): AgentMessage[] {
+  const maxAgeMs = dialogExpirySeconds * 1000
+  return messages.filter((m) => now - new Date(m.timestamp).getTime() <= maxAgeMs)
+}
+
 export class QueryEngine {
   private hookEngine?: HookEngine
   private artifactServer?: ArtifactServer
@@ -131,8 +145,11 @@ export class QueryEngine {
       const transport = getFileInboxTransport()
       const messages = await transport.poll(this.sessionId)
       if (messages.length > 0) {
+        // dialogExpiry: discard messages older than the approval-dialog TTL
+        const fresh = filterExpiredMessages(messages, this.crossSessionConfig.dialogExpiry)
+        if (fresh.length === 0) return
         const bus = getMessageBus()
-        for (const msg of messages) {
+        for (const msg of fresh) {
           // P2-1: Trigger Notification hook for cross-session messages
           if (this.hookEngine) {
             this.hookEngine
@@ -532,6 +549,12 @@ export class QueryEngine {
       return
     }
 
+    // Record the provider's cached prefix (all messages except the newest)
+    // for cache-aware microcompaction.
+    if (messages.length >= 2) {
+      this.context.markCached(messages.slice(0, -1))
+    }
+
     // Track last assistant content for goal checking
     if (assistantContent) {
       this.lastAssistantContent = assistantContent

package/src/core/red-team.ts

@@ -19,6 +19,7 @@
 import type { ConstitutionLoader } from './constitution-loader.js'
 import type { PreFlightChecker } from './preflight-checker.js'
 import type { ErrorSignatureDB } from './error-signature-db.js'
+import { isBlocked } from '../tools/exec/bash'
 
 // ── Types ──
 
@@ -262,7 +263,21 @@ export class RedTeam {
       }
     }
 
-    // 3. Not caught — security gap
+    // 3. Check the real Bash tool's isBlocked — ground-truth defense, not just
+    // the constitution/preflight abstraction. Catches e.g. `git push --force`.
+    if (attack.toolName === 'Bash' && typeof attack.params.command === 'string') {
+      const blockedReason = isBlocked(attack.params.command)
+      if (blockedReason) {
+        return {
+          attack,
+          blocked: true,
+          caughtBy: 'bash-tool',
+          message: blockedReason,
+        }
+      }
+    }
+
+    // 4. Not caught — security gap
     return {
       attack,
       blocked: false,

package/src/core/workspace-trust.ts

@@ -25,6 +25,26 @@ function realPath(dir: string): string {
   }
 }
 
+/**
+ * True if a `.git` file or directory exists anywhere strictly between `dir` and
+ * its trusted ancestor `ancestor`. A `.git` marks the root of a separate
+ * repository — trust does not cross that boundary (nested-repo isolation).
+ */
+function hasGitBoundary(dir: string, ancestor: string): boolean {
+  let cur = dir
+  // Case-insensitive termination matches isTrusted's `toLowerCase()` ancestor
+  // check — otherwise a path referenced with different casing than when it was
+  // trusted would walk past the ancestor and miss the boundary.
+  const targetLower = ancestor.toLowerCase()
+  while (cur.toLowerCase() !== targetLower && cur.length > ancestor.length) {
+    if (existsSync(join(cur, '.git'))) return true
+    const parent = dirname(cur)
+    if (parent === cur) break
+    cur = parent
+  }
+  return false
+}
+
 /**
  * Manages the workspace trust store.
  *
@@ -82,8 +102,11 @@ export class WorkspaceTrust {
       const trustedLower = trusted.toLowerCase()
       // Exact match
       if (resolvedLower === trustedLower) return true
-      // Ancestor match: trusted dir is a parent of the target
-      if (resolvedLower.startsWith(trustedLower + '/')) return true
+      // Ancestor match: trusted dir is a parent of the target. Trust does not
+      // cross a nested git-repository boundary (vendored/submodule isolation).
+      if (resolvedLower.startsWith(trustedLower + '/') && !hasGitBoundary(resolved, trusted)) {
+        return true
+      }
     }
 
     return false

package/src/i18n-core/locales/en-US.json

@@ -682,6 +682,10 @@
       "count": "{shown} of {total}",
       "all": "all"
     },
+    "mention_hints": {
+      "label": "Sessions:",
+      "empty": "No active sessions"
+    },
     "picker": {
       "title": "Select Model",
       "nav_help": "←→ navigate · ↑↓ move · Enter select · Esc close",

package/src/i18n-core/locales/zh-CN.json

@@ -682,6 +682,10 @@
       "count": "{shown} / {total}",
       "all": "全部"
     },
+    "mention_hints": {
+      "label": "会话：",
+      "empty": "无活跃会话"
+    },
     "picker": {
       "title": "选择模型",
       "nav_help": "←→ 导航 · ↑↓ 移动 · Enter 选择 · Esc 关闭",

package/src/index.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import { join } from 'node:path'
+import { join, basename } from 'node:path'
 import { homedir } from 'node:os'
 import { existsSync } from 'node:fs'
 import { render } from 'ink'
@@ -16,11 +16,14 @@ import {
   heartbeatSession,
   unregisterSession,
   createSessionInfo,
+  ensureUniqueSessionName,
+  discoverSessions,
 } from './agent/cross-session/discovery'
 import { bootstrapProviders } from './providers/bootstrap'
 import { InstructionsLoader } from './core/instructions'
 import { loadSessionMemories, getMemoryManager } from './core/memory/memory-loader'
 import { ContextManager } from './core/context'
+import { PrefixCacheTracker } from './core/context-token'
 import { QueryEngine } from './core/engine'
 import { ExperienceRuleEngine } from './core/rule-engine.js'
 import { SessionStore } from './core/session-store'
@@ -325,6 +328,8 @@ export async function runApp(options: RunOptions): Promise<void> {
     compactionThreshold: 0.9,
     contextWindow: adaptiveThresholds ? modelContextWindow : undefined,
   })
+  // Cache-aware microcompaction: track the provider's prompt-cache prefix.
+  context.setCacheTracker(new PrefixCacheTracker())
 
   // Adaptive memory budget: scale with model's context window
   getMemoryManager().setContextWindow(modelContextWindow)
@@ -512,9 +517,13 @@ export async function runApp(options: RunOptions): Promise<void> {
 
   // ── Cross-session messaging: register session, heartbeat, shutdown ──
   engine.setSessionId(sessionName)
+  // Human-readable, cross-session-addressable name. Defaults to the cwd basename
+  // so `@mipham-code` can address this session; uniqueness is enforced against
+  // other live sessions (suffix -2, -3, …). The id stays a stable `session-<ts>`.
+  const defaultName = basename(process.cwd()) || 'session'
   const sessionInfo = createSessionInfo(
     sessionName,
-    sessionName,
+    ensureUniqueSessionName(defaultName, discoverSessions()),
     process.cwd(),
     defaultProvider,
     defaultModel,

package/src/mcp/client.ts

@@ -22,6 +22,15 @@ const bundles: Record<string, TranslationMap> = {
 }
 const t = createT(bundles['en-US'] || (enUS as TranslationMap), enUS as TranslationMap)
 
+// Connect-handshake timeout: a hung MCP server should fail startup fast rather
+// than block on the per-request 60s timeout. Overridable via env for tests.
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000
+
+function connectTimeoutMs(): number {
+  const env = Number(process.env.MIPHAM_MCP_CONNECT_TIMEOUT_MS)
+  return Number.isFinite(env) && env > 0 ? env : DEFAULT_CONNECT_TIMEOUT_MS
+}
+
 interface ActiveConnection {
   config: McpServerConfig
   transport: Transport
@@ -167,33 +176,63 @@ export class McpClient {
     this.connections.set(config.name, connection)
 
     try {
-      // Start the transport (transport-specific), then perform the handshake.
-      if (transport instanceof HttpTransport) {
-        await transport.start(config.url ?? '', config.headers, config.env)
-      } else {
-        await transport.start(config.command ?? '', config.args ?? [], config.env)
-      }
-      const initResult: InitializeResult = await protocol.initialize()
+      await this.withConnectTimeout(config.name, async () => {
+        // Start the transport (transport-specific), then perform the handshake.
+        if (transport instanceof HttpTransport) {
+          await transport.start(config.url ?? '', config.headers, config.env)
+        } else {
+          await transport.start(config.command ?? '', config.args ?? [], config.env)
+        }
+        const initResult: InitializeResult = await protocol.initialize()
 
-      connection.status = 'connected'
-      connection.serverInfo = initResult.serverInfo
+        connection.status = 'connected'
+        connection.serverInfo = initResult.serverInfo
 
-      // Wire tools-changed notification
-      protocol.on('tools-changed', async () => {
-        await this.onToolsChanged(config.name)
-      })
+        // Wire tools-changed notification
+        protocol.on('tools-changed', async () => {
+          await this.onToolsChanged(config.name)
+        })
 
-      // Discover tools
-      if (initResult.capabilities.tools) {
-        connection.tools = await protocol.listTools()
-      }
+        // Discover tools
+        if (initResult.capabilities.tools) {
+          connection.tools = await protocol.listTools()
+        }
+      })
     } catch (err) {
       connection.status = 'error'
       connection.error = String(err)
+      try {
+        await transport.close()
+      } catch {
+        // Best-effort cleanup on a failed connect
+      }
       throw err
     }
   }
 
+  /** Race the connect handshake against a timeout so a hung server fails fast. */
+  private async withConnectTimeout<T>(name: string, fn: () => Promise<T>): Promise<T> {
+    const timeoutMs = connectTimeoutMs()
+    let timer: ReturnType<typeof setTimeout> | null = null
+    // Swallow a late rejection: if the timeout wins, transport.close() in the
+    // caller's catch makes fn()'s pending request reject after we've moved on.
+    const work = fn()
+    work.catch(() => {})
+    try {
+      return await Promise.race([
+        work,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`MCP connect timed out for "${name}" after ${timeoutMs}ms`)),
+            timeoutMs,
+          )
+        }),
+      ])
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
   /**
    * Disconnect an MCP server and return the names of its registered tools
    * so the caller can unregister them from the central tool registry.

package/src/providers/anthropic.ts

@@ -52,15 +52,20 @@ export class AnthropicProvider implements ProviderInstance {
     let currentToolId = ''
     let accumulatedToolInput = ''
 
+    const messages = this.convertMessages(req.messages)
+    this.markPrefixCacheBreakpoint(messages)
+
     const body: Record<string, unknown> = {
       model: req.model,
       max_tokens: req.maxTokens || 4096,
       stream: true,
-      messages: this.convertMessages(req.messages),
+      messages,
     }
 
     if (req.systemPrompt) {
-      body.system = req.systemPrompt
+      // Mark the system prompt for prompt caching — it's the largest stable
+      // block and byte-identical across turns, so it always hits the cache.
+      body.system = [{ type: 'text', text: req.systemPrompt, cache_control: { type: 'ephemeral' } }]
     }
 
     if (req.temperature !== undefined) {
@@ -68,11 +73,14 @@ export class AnthropicProvider implements ProviderInstance {
     }
 
     if (req.tools && req.tools.length > 0) {
-      body.tools = req.tools.map((t) => ({
+      const tools: Record<string, unknown>[] = req.tools.map((t) => ({
         name: t.name,
         description: t.description,
         input_schema: t.parameters || t.input_schema || { type: 'object', properties: {} },
       }))
+      // Cache the tools: mark the last tool definition as a breakpoint.
+      tools[tools.length - 1]!.cache_control = { type: 'ephemeral' }
+      body.tools = tools
     }
 
     const response = await fetchWithRetry(`${this.baseUrl}/messages`, {
@@ -239,6 +247,20 @@ export class AnthropicProvider implements ProviderInstance {
     return apiKey.length > 0 && apiKey.startsWith('sk-ant-')
   }
 
+  /**
+   * Mark the stable conversation prefix for prompt caching. The breakpoint is
+   * placed on the last block of the second-to-last message, leaving only the
+   * newest message uncached.
+   */
+  private markPrefixCacheBreakpoint(messages: Record<string, unknown>[]): void {
+    if (messages.length < 2) return
+    const boundary = messages[messages.length - 2]!
+    const content = boundary.content
+    if (!Array.isArray(content) || content.length === 0) return
+    const lastBlock = content[content.length - 1] as Record<string, unknown>
+    lastBlock.cache_control = { type: 'ephemeral' }
+  }
+
   private convertMessages(messages: Message[]): Record<string, unknown>[] {
     const result: Record<string, unknown>[] = []
 

package/src/tools/agent/agent.ts

@@ -5,13 +5,26 @@ import { getBackgroundAgentRegistry } from '../../agent/background-registry'
 
 const VALID_TYPES: SubAgentType[] = ['general', 'explore', 'plan', 'code-review']
 
+/**
+ * Resolve whether a sub-agent should run in the background.
+ * Precedence: explicit `run_in_background` param > agent frontmatter
+ * `background` field > default (background, Claude Code 2.1.232 parity).
+ */
+export function resolveRunInBackground(
+  runInBackground: boolean | undefined,
+  agentDef?: { background?: boolean },
+): boolean {
+  return runInBackground ?? agentDef?.background ?? true
+}
+
 export const agentTool: ToolDefinition = {
   name: 'Agent',
   description:
     'Launch a sub-agent to handle complex, multi-step tasks independently. ' +
     'Available types: general (default), explore (code search), plan (design), code-review. ' +
-    'Set run_in_background: true to execute asynchronously — returns a task ID immediately; ' +
-    'results are retrievable via the Task tool (output action) or Agent View.',
+    'Runs in the background by default — returns a task ID immediately; results are ' +
+    'retrievable via the Task tool (output action) or Agent View. ' +
+    'Set run_in_background: false to run synchronously.',
   category: 'agent',
   permission: 'ask',
   parameters: {
@@ -26,7 +39,7 @@ export const agentTool: ToolDefinition = {
       run_in_background: {
         type: 'boolean',
         description:
-          'When true, execute asynchronously and return a task ID immediately. Use Task output to retrieve results. Default: false.',
+          'When false, execute synchronously and return the result directly. Default: true (background).',
       },
     },
     required: ['description', 'prompt'],
@@ -35,7 +48,6 @@ export const agentTool: ToolDefinition = {
     const description = params.description as string
     const prompt = params.prompt as string
     const agentType = (params.subagent_type as SubAgentType) || 'general'
-    const runInBackground = params.run_in_background === true
 
     if (!VALID_TYPES.includes(agentType)) {
       return {
@@ -58,6 +70,10 @@ export const agentTool: ToolDefinition = {
 
     // Resolve agent definition from registry (custom > builtin)
     const agentDef = ctx.agentRegistry?.resolve(agentType)
+    const runInBackground = resolveRunInBackground(
+      params.run_in_background as boolean | undefined,
+      agentDef,
+    )
 
     try {
       const sub = new SubAgent(

package/src/tools/agent/send-message.ts

@@ -6,7 +6,7 @@ export const sendMessageTool: ToolDefinition = {
   description:
     'Send a message to another agent or session. ' +
     'Use "main" for the parent conversation, a background task ID for same-process agents, ' +
-    'or a session ID for cross-session messaging (use ListAgents to discover sessions).',
+    'or a session ID (or unique session name) for cross-session messaging (use ListAgents to discover sessions).',
   category: 'agent',
   permission: 'auto',
   parameters: {
@@ -15,7 +15,7 @@ export const sendMessageTool: ToolDefinition = {
       to: {
         type: 'string',
         description:
-          'Recipient: "main" for the parent conversation, a background task ID, or a session ID for cross-session messaging.',
+          'Recipient: "main" for the parent conversation, a background task ID, or a session ID / unique session name for cross-session messaging.',
       },
       summary: {
         type: 'string',

package/src/tools/exec/bash.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition, CredentialMaskingConfig } from '../../shared/index.ts'
 import { sanitizeCommand } from '../../shared/sanitize.ts'
+import { DANGEROUS_GIT_PATTERNS } from './git.ts'
 
 // Injected at startup — set via index.tsx
 let credentialConfig: CredentialMaskingConfig | undefined
@@ -103,7 +104,7 @@ function normalizeEscapes(command: string): string {
   )
 }
 
-function isBlocked(command: string): string | null {
+export function isBlocked(command: string): string | null {
   // Normalize ANSI-C escape sequences for defense-in-depth
   const normalized = normalizeEscapes(command)
   // P0-1: Also sanitize for permission check (strips invisible chars, normalizes homoglyphs)
@@ -124,6 +125,19 @@ function isBlocked(command: string): string | null {
     return `Command "${sanitizedFirstWord}" rejected by security policy.`
   }
 
+  // Detect dangerous git operations invoked via Bash. The Git tool guards these,
+  // but shelling out with `git push --force` would bypass it — apply the same
+  // pattern list to any Bash command that starts with a git invocation.
+  const gitInvocation = normalized.trim().match(/^(?:sudo\s+)?git(?:\s+|$)(.*)$/i)
+  if (gitInvocation) {
+    const subcommand = gitInvocation[1] || ''
+    for (const { pattern, description } of DANGEROUS_GIT_PATTERNS) {
+      if (pattern.test(subcommand)) {
+        return `Dangerous git command blocked: "${description}". Run manually if intended.`
+      }
+    }
+  }
+
   // Check dangerous patterns (on original, normalized, and sanitized)
   for (const pattern of BLOCKED_PATTERNS) {
     if (pattern.test(command) || pattern.test(normalized) || pattern.test(sanitized)) {

package/src/tools/exec/git.ts

@@ -2,7 +2,7 @@ import type { ToolDefinition } from '../../shared/index.ts'
 
 // P0-4 (v2.1.222 alignment): Regex-based word-boundary patterns replace
 // fragile substring matching. Each pattern describes what it blocks.
-const DANGEROUS_GIT_PATTERNS: Array<{ pattern: RegExp; description: string }> = [
+export const DANGEROUS_GIT_PATTERNS: Array<{ pattern: RegExp; description: string }> = [
   // Destructive push
   { pattern: /\bpush\s+.*--force(?:-with-lease)?\b/, description: 'push --force' },
   { pattern: /\bpush\s+.*-[fF]\b/, description: 'push -f (force)' },

package/src/ui/app.tsx

@@ -11,6 +11,8 @@ import { setPreference } from '../config/preferences'
 import { saveProviderApiKey } from '../config/loader'
 import { AgentRegistry } from '../agent/agent-registry'
 import { getBackgroundAgentRegistry } from '../agent/background-registry'
+import { getMessageRouter, parseMention, resolveRecipientSession } from '../agent/message-router'
+import { discoverSessions } from '../agent/cross-session/discovery'
 import { ChatPanel } from './chat'
 import { InputBar } from './input'
 import { ModelPicker } from './picker'
@@ -325,6 +327,40 @@ export function App({
     async (input: string) => {
       if (!input.trim()) return
 
+      // ── @mention: direct cross-session message — only when the name resolves
+      // to a live session; otherwise fall through to normal AI processing so a
+      // leading `@word` (e.g. "@bob please review") isn't hijacked as a send. ──
+      const mention = parseMention(input)
+      if (mention && resolveRecipientSession(discoverSessions(), mention.name).session) {
+        if (!mention.message) {
+          setMessages((prev) => [
+            ...prev,
+            { role: 'user', content: input },
+            { role: 'system', content: 'Usage: @session-name <message>' },
+          ])
+          return
+        }
+        const mentionSummary =
+          mention.message.length > 50 ? mention.message.slice(0, 47) + '...' : mention.message
+        const result = await getMessageRouter().route(
+          sessionId || 'main',
+          mention.name,
+          mentionSummary,
+          mention.message,
+        )
+        setMessages((prev) => [
+          ...prev,
+          { role: 'user', content: input },
+          {
+            role: 'system',
+            content: result.success
+              ? `── Message sent to ${mention.name} ──${result.messageId ? `\nID: ${result.messageId}` : ''}`
+              : `❌ Failed to send to ${mention.name}: ${result.error}`,
+          },
+        ])
+        return
+      }
+
       // ── Slash command dispatch ──
       if (looksLikeSlashCommand(input)) {
         const { command, args } = parseSlashCommand(input)

package/src/ui/commands.ts

@@ -12,6 +12,7 @@ import type { Message } from '../shared/types.js'
 import { McpClient } from '../mcp/client'
 import { NPM_UPDATE_COMMAND, PACKAGE_VERSION } from '../shared/index.ts'
 import { getPreference } from '../config/preferences'
+import { loadCrossSessionConfig } from '../config/loader'
 import { stripIndent } from './strip-indent.js'
 import { createT } from '../i18n-core/t'
 import type { TranslationMap } from '../i18n-core/types'
@@ -43,6 +44,7 @@ import { keysCmd } from '../commands/keys'
 import { workflowViewCmd, workflowWatchCmd } from '../commands/workflow-view.js'
 import { execSync } from 'node:child_process'
 import { OLLAMA_PRESET_MODELS } from '../shared/constants'
+import { renameActiveSession } from '../agent/cross-session/discovery'
 
 export interface CommandContext {
   engine: QueryEngine
@@ -517,12 +519,16 @@ const switchCmd: CommandHandler = (ctx, args) => {
 const configCmd: CommandHandler = (ctx) => {
   const t = resolveT(ctx)
   const c = ctx.config
+  const xs = loadCrossSessionConfig(process.cwd())
   const lines = [
     `version:          ${c.version}`,
     `defaultProvider:  ${c.defaultProvider}`,
     `defaultModel:     ${c.defaultModel}`,
     `permission:       ${c.permission}`,
     `providers:        ${c.providers.length} configured`,
+    '',
+    `crossSessionInbound: ${xs.crossSessionInbound}`,
+    `dialogExpiry:        ${xs.dialogExpiry}s`,
   ]
   return {
     content: `${t('commands.config.title')}\n${lines.join('\n')}\n\n${t('commands.config.edit')}`,
@@ -1588,7 +1594,10 @@ const renameCmd: CommandHandler = (ctx, args) => {
     return { content: t('commands.rename.usage') }
   }
   ctx.setSessionTitle(name.trim())
-  return { content: t('commands.rename.confirmed', { name: name.trim() }) }
+  // Persist to the cross-session registry so `@name` can address this session.
+  // Returns the (possibly uniquified) final name — surface that to the user.
+  const finalName = renameActiveSession(ctx.sessionId, name.trim())
+  return { content: t('commands.rename.confirmed', { name: finalName ?? name.trim() }) }
 }
 
 const goalCmd: CommandHandler = (ctx, args) => {
@@ -4041,8 +4050,10 @@ const forkCmd: CommandHandler = async (ctx, args) => {
         ctx.engine.getTools(),
         ctx.engine.getPermission(),
       )
+      const parentContext = ctx.engine.getContext()
       const result = await sa.execute(prompt, 'fork: ' + prompt.slice(0, 60), {
         worktreePath: wtPath,
+        inheritContext: { messages: parentContext.getMessages() },
       })
       try {
         const { execSync: ex } = await import('node:child_process')

package/src/ui/input.tsx

@@ -5,6 +5,7 @@ import { VimMotionEngine, type VimMode } from './vim-motions.js'
 import { getCommandList } from './commands.js'
 import { CommandPicker } from './command-picker.js'
 import { useI18n } from '../i18n-context'
+import { discoverSessions } from '../agent/cross-session/discovery'
 
 interface InputBarProps {
   onSubmit: (input: string) => void
@@ -107,6 +108,15 @@ export function InputBar({
     return allCommands.filter((c) => c.name.toLowerCase().includes(filter)).slice(0, 8)
   }, [value, allCommands])
 
+  // ── @mention hints (cross-session recipients) ──
+  const mentionHints = useMemo(() => {
+    if (!value.startsWith('@')) return []
+    const filter = value.slice(1).toLowerCase()
+    const names = discoverSessions().map((s) => s.name)
+    if (!filter) return names.slice(0, 12)
+    return names.filter((n) => n.toLowerCase().includes(filter)).slice(0, 8)
+  }, [value])
+
   // Rotate gerunds while loading — use tRef to avoid re-running when i18n context re-renders
   useEffect(() => {
     if (!isLoading) return
@@ -448,6 +458,17 @@ export function InputBar({
           </Text>
         </Box>
       )}
+      {/* @mention hints — active sessions (cross-session messaging) */}
+      {mentionHints.length > 0 && vimMode === 'insert' && !pickerActive && (
+        <Box marginTop={1} flexDirection="column" gap={1}>
+          <Text dimColor>{t('ui.mention_hints.label')} </Text>
+          {mentionHints.map((name) => (
+            <Text key={name} color="green">
+              {name}
+            </Text>
+          ))}
+        </Box>
+      )}
     </Box>
   )
 }