feat(server): warn when the agent leaves the thread worktree

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});

apps/server/src/orchestration/Layers/ProviderCommandReactor.ts

@@ -42,6 +42,10 @@ import {
  appendProjectBoardToTurnInput,
  formatProjectBoardPromptBlock,
 } from "../projectBoardPrompt.ts";
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "../workspaceScopePrompt.ts";
 import {
  ProviderCommandReactor,
  type ProviderCommandReactorShape,
@@ -863,6 +867,12 @@ const make = Effect.gen(function* () {
  if (!rulesAlreadySent) threadsWithBoardRulesSent.add(input.threadId);
  turnInput = appendProjectBoardToTurnInput(turnInput, boardBlock);
  }
+ if (turnInput && thread.worktreePath) {
+ turnInput = prependWorkspaceScopeToTurnInput(
+ turnInput,
+ formatWorkspaceScopePromptBlock({ cwd: thread.worktreePath, branch: thread.branch }),
+ );
+ }
 
  return {
  threadId: input.threadId,

apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts

@@ -42,6 +42,7 @@ import {
  type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
 import { projectActivityPayload } from "../ActivityPayloadProjection.ts";
+import { maybeWorkspaceScopeWarningActivity } from "../workspaceScopeWarning.ts";
 import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { canReplaceThreadTitle } from "../threadTitles.ts";
@@ -900,6 +901,7 @@ const make = Effect.gen(function* () {
  crypto.randomUUIDv4.pipe(
  Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
  );
+ const warnedWorkspaceScopeKeys = new Set<string>();
 
  const turnMessageIdsByTurnKey = yield* Cache.make<string, Set<MessageId>>({
  capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
@@ -2041,6 +2043,21 @@ const make = Effect.gen(function* () {
  ),
  ),
  ).pipe(Effect.asVoid);
+ const workspaceScopeWarning = maybeWorkspaceScopeWarningActivity({
+ event,
+ worktreePath: thread.worktreePath,
+ warnedKeys: warnedWorkspaceScopeKeys,
+ });
+ if (workspaceScopeWarning) {
+ const commandId = yield* providerCommandId(event, "thread-activity-append-workspace-scope");
+ yield* orchestrationEngine.dispatch({
+ type: "thread.activity.append",
+ commandId,
+ threadId: thread.id,
+ activity: workspaceScopeWarning,
+ createdAt: workspaceScopeWarning.createdAt,
+ });
+ }
  });
 
  const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;

apps/server/src/orchestration/workspaceScopePrompt.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ formatWorkspaceScopePromptBlock,
+ prependWorkspaceScopeToTurnInput,
+} from "./workspaceScopePrompt.ts";
+
+describe("workspaceScopePrompt", () => {
+ it("names the assigned worktree path and branch", () => {
+ const block = formatWorkspaceScopePromptBlock({
+ cwd: "/tmp/worktree",
+ branch: "t3code/update-main-from-github",
+ });
+ expect(block).toContain("<t3_workspace_scope>");
+ expect(block).toContain("Path: /tmp/worktree");
+ expect(block).toContain("Branch: t3code/update-main-from-github");
+ expect(block).toContain("Do not switch to another clone");
+ });
+
+ it("prepends the block so the constraint is visible before the user prompt", () => {
+ expect(
+ prependWorkspaceScopeToTurnInput(
+ "fix the bug",
+ "<t3_workspace_scope>\nscoped\n</t3_workspace_scope>",
+ ),
+ ).toBe("<t3_workspace_scope>\nscoped\n</t3_workspace_scope>\n\nfix the bug");
+ });
+});

apps/server/src/orchestration/workspaceScopePrompt.ts

@@ -0,0 +1,24 @@
+export function formatWorkspaceScopePromptBlock(input: {
+ readonly cwd: string;
+ readonly branch: string | null;
+}): string {
+ const branchLine = input.branch ? `Branch: ${input.branch}` : "Branch: (unknown)";
+ return [
+ "<t3_workspace_scope>",
+ "This thread is attached to a Git worktree. All file edits, commits, git commands, and dev servers must use this directory as the working directory. Do not switch to another clone of the same repository.",
+ `Path: ${input.cwd}`,
+ branchLine,
+ "If you need a different path, stop and ask the user to confirm that exact path first.",
+ "</t3_workspace_scope>",
+ ].join("\n");
+}
+
+export function prependWorkspaceScopeToTurnInput(
+ input: string | undefined,
+ block: string | null,
+): string | undefined {
+ if (!block) return input;
+ const trimmed = input?.trim();
+ if (!trimmed) return block;
+ return `${block}\n\n${trimmed}`;
+}

apps/server/src/orchestration/workspaceScopeWarning.test.ts

@@ -0,0 +1,86 @@
+import {
+ EventId,
+ ProviderDriverKind,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { maybeWorkspaceScopeWarningActivity } from "./workspaceScopeWarning.ts";
+
+const worktree = "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c";
+const otherClone = "/Users/me/Documents/Project/marswalk";
+
+const base = {
+ provider: ProviderDriverKind.make("cursor"),
+ createdAt: "2026-08-31T12:00:00.000Z",
+ threadId: ThreadId.make("thread-1"),
+ turnId: TurnId.make("turn-1"),
+};
+
+function toolEvent(eventId: string, data: Record<string, unknown>): ProviderRuntimeEvent {
+ return {
+ ...base,
+ type: "item.completed",
+ eventId: EventId.make(eventId),
+ payload: {
+ itemType: "command_execution",
+ title: "Terminal",
+ data,
+ },
+ } satisfies ProviderRuntimeEvent;
+}
+
+describe("workspaceScopeWarning", () => {
+ it("warns when a command's working directory is another clone", () => {
+ const warnedKeys = new Set<string>();
+ const activity = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", {
+ command: "git status",
+ rawInput: { working_directory: otherClone },
+ }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(activity?.kind).toBe("runtime.warning");
+ expect(activity?.summary).toContain("different checkout");
+ const payload = activity?.payload as { detail?: string };
+ expect(payload.detail).toContain(otherClone);
+ expect(payload.detail).toContain(worktree);
+ expect(payload.detail).toContain("Provider: cursor");
+ });
+
+ it("warns only once per escaped path on a thread", () => {
+ const warnedKeys = new Set<string>();
+ const first = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ const second = maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-2", { rawInput: { cwd: otherClone } }),
+ worktreePath: worktree,
+ warnedKeys,
+ });
+ expect(first).not.toBeNull();
+ expect(second).toBeNull();
+ });
+
+ it("stays quiet when the thread has no worktree or the command stays in it", () => {
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: otherClone } }),
+ worktreePath: null,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ expect(
+ maybeWorkspaceScopeWarningActivity({
+ event: toolEvent("event-1", { rawInput: { working_directory: worktree } }),
+ worktreePath: worktree,
+ warnedKeys: new Set(),
+ }),
+ ).toBeNull();
+ });
+});

apps/server/src/orchestration/workspaceScopeWarning.ts

@@ -0,0 +1,73 @@
+import {
+ EventId,
+ type OrchestrationThreadActivity,
+ type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { findOutOfWorkspaceScopePath } from "@t3tools/shared/workspaceScope";
+
+const WARNABLE_EVENT_TYPES = new Set([
+ "item.started",
+ "item.updated",
+ "item.completed",
+ "request.opened",
+]);
+
+const FILE_PATH_ITEM_TYPES = new Set([
+ "command_execution",
+ "file_change",
+ "file_edit",
+ "create_file",
+ "edit",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+ return value !== null && typeof value === "object" && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function payloadLooksLikeFileMutation(payload: Record<string, unknown>): boolean {
+ const itemType = typeof payload.itemType === "string" ? payload.itemType : undefined;
+ if (itemType && FILE_PATH_ITEM_TYPES.has(itemType)) {
+ return true;
+ }
+ const requestType = typeof payload.requestType === "string" ? payload.requestType : undefined;
+ return requestType === "command" || requestType === "file-change";
+}
+
+export function maybeWorkspaceScopeWarningActivity(input: {
+ readonly event: ProviderRuntimeEvent;
+ readonly worktreePath: string | null;
+ readonly warnedKeys: Set<string>;
+}): OrchestrationThreadActivity | null {
+ const worktreePath = input.worktreePath?.trim() ?? "";
+ if (!worktreePath || !WARNABLE_EVENT_TYPES.has(input.event.type)) {
+ return null;
+ }
+ const payload = asRecord(input.event.payload) ?? {};
+ const outOfScopePath = findOutOfWorkspaceScopePath({
+ workspaceRoot: worktreePath,
+ data: payload,
+ includeFilePaths: payloadLooksLikeFileMutation(payload),
+ });
+ if (!outOfScopePath) {
+ return null;
+ }
+ const warningKey = `${input.event.threadId}:${outOfScopePath}`;
+ if (input.warnedKeys.has(warningKey)) {
+ return null;
+ }
+ input.warnedKeys.add(warningKey);
+ return {
+ id: EventId.make(`workspace-scope:${input.event.eventId}`),
+ createdAt: input.event.createdAt,
+ tone: "info",
+ kind: "runtime.warning",
+ summary: "Agent used a different checkout than this thread's worktree",
+ payload: {
+ message: "Agent used a different checkout than this thread's worktree",
+ detail: `Thread worktree: ${worktreePath}\nUsed path: ${outOfScopePath}\nProvider: ${input.event.provider}`,
+ },
+ turnId: input.event.turnId ?? null,
+ };
+}

apps/web/src/components/chat/MessagesTimeline.tsx

@@ -128,6 +128,10 @@ import { cn } from "~/lib/utils";
 import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatChatTimestampTooltip, formatDayAwareTimestamp } from "../../timestampFormat";
+import {
+ parseWorkspaceScopeWarning,
+ WorkspaceScopeWarningRow,
+} from "../../workspaceScopeWarningUi";
 
 import {
  buildInlineTerminalContextText,
@@ -2718,7 +2722,17 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
  isExpandedToolGroupEntry: boolean;
 }) {
  const { workEntry, workspaceRoot, isExpandedToolGroupEntry } = props;
+ const workspaceScopeMismatch = parseWorkspaceScopeWarning(workEntry);
  const [expanded, setExpanded] = useState(false);
+ if (workspaceScopeMismatch) {
+ return (
+ <WorkspaceScopeWarningRow
+ label={workEntry.label}
+ mismatch={workspaceScopeMismatch}
+ isExpandedToolGroupEntry={isExpandedToolGroupEntry}
+ />
+ );
+ }
  const iconConfig = workToneIcon(workEntry.tone);
  const showWarningIndicator = workEntry.sourceActivityKind === "runtime.warning";
  const showFailedIndicator = workEntryDisplayIndicatesToolFailure(workEntry);

apps/web/src/workspaceScopeWarningUi.test.ts

@@ -0,0 +1,43 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseWorkspaceScopeWarning } from "./workspaceScopeWarningUi";
+
+describe("parseWorkspaceScopeWarning", () => {
+ it("reads aligned thread and agent paths from the warning detail", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk\nProvider: cursor",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: ProviderDriverKind.make("cursor"),
+ });
+ });
+
+ it("ignores other runtime warnings", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail: "Model rerouted to a fallback",
+ }),
+ ).toBeNull();
+ });
+
+ it("keeps older warnings that have no provider line", () => {
+ expect(
+ parseWorkspaceScopeWarning({
+ sourceActivityKind: "runtime.warning",
+ detail:
+ "Thread worktree: /Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c\nUsed path: /Users/me/Documents/Project/marswalk",
+ }),
+ ).toEqual({
+ threadWorktree: "/Users/me/.t3-jcode/worktrees/marswalk/t3code-dae6736c",
+ usedPath: "/Users/me/Documents/Project/marswalk",
+ provider: null,
+ });
+ });
+});