Load authorized workspace repository instructions into agent context

Author: danny-avila

api/server/services/ToolService.js

@@ -49,6 +49,7 @@ const {
   isFatalAgentInitializationError,
   codeExecutionAuthHeaders,
   createAttachedWorkspaceBashTool,
+  createRepositoryInstructionLoader,
   resolveAttachedWorkspaceCommandTimeoutMax,
   createGitIdentityProgrammaticBashTool,
   resolveCodeExecutionContext,
@@ -105,6 +106,7 @@ const { processFileURL, uploadImageBuffer } = require('~/server/services/Files/p
 const { primeFiles: primeSearchFiles } = require('~/app/clients/tools/util/fileSearch');
 const { primeFiles: primeCodeFiles } = require('~/server/services/Files/Code/process');
 const { manifestToolMap, toolkits } = require('~/app/clients/tools/manifest');
+const loadRepositoryInstructions = createRepositoryInstructionLoader();
 const { createOnSearchResults } = require('~/server/services/Tools/search');
 const { reinitMCPServer } = require('~/server/services/Tools/mcp');
 const {
@@ -1757,6 +1759,24 @@ async function loadAgentTools({
     getAppConfig,
   });
 
+  const repositoryInstructionBlock = await loadRepositoryInstructions({
+    assertContent: (content) =>
+      assertModelBoundContent({
+        filters: appConfig.filters,
+        agents: [{ instructions: content }],
+        onTraversalFailure: reportLocatorTraversalFailure,
+      }),
+    enabled: codeExecutionEnabled,
+    context: codeExecutionContext,
+    mode: agent.repositoryInstructions,
+    principalId: JSON.stringify([getTenantId(), req.user.id]),
+    signal,
+    authHeaders: () =>
+      codeExecutionAuthHeaders(
+        (bridgeWorkerId) => getCodeApiAuthHeaders(req, bridgeWorkerId),
+        codeExecutionContext,
+      ),
+  });
   const { loadedTools, toolContextMap, dynamicToolContextMap, primedCodeFiles } = await loadTools({
     agent,
     signal,
@@ -1859,6 +1879,7 @@ async function loadAgentTools({
 
   if (preparedActionSnapshot == null) {
     return {
+      repositoryInstructionBlock,
       toolRegistry,
       requestScopedConnections: getMCPRequestContext(req, res),
       userMCPAuthMap,
@@ -1880,6 +1901,7 @@ async function loadAgentTools({
       logger.warn(`No tools found for ${_agentTools.length} specified tool call(s)`);
     }
     return {
+      repositoryInstructionBlock,
       toolRegistry,
       requestScopedConnections: getMCPRequestContext(req, res),
       userMCPAuthMap,
@@ -2012,6 +2034,7 @@ async function loadAgentTools({
     toolRegistry,
     requestScopedConnections: getMCPRequestContext(req, res),
     toolContextMap,
+    repositoryInstructionBlock,
     dynamicToolContextMap,
     userMCPAuthMap,
     toolDefinitions,

client/src/common/agents-types.ts

@@ -53,6 +53,7 @@ export type AgentForm = {
   /** Operator-configured managed or attached execution environment. */
   code_environment_id?: string | null;
   code_workspace_id?: string;
+  repositoryInstructions?: 'prefer' | 'defer' | 'off';
   /** Git authorship applied to sandboxed commands for this agent. */
   git_identity?: Agent['git_identity'];
   provider?: AgentProvider | OptionWithIcon;

client/src/components/Chat/Input/CodeWorkspaceMenu.tsx

@@ -95,6 +95,7 @@ function EnvironmentWorkspaces({
   isSelected: (workspaceId: string) => boolean;
   onSelect: (selection: CodeWorkspaceSelection) => void;
 }) {
+  const localize = useLocalize();
   return (
     <div>
       <Ariakit.MenuHeading render={<div />} className={headingClasses}>
@@ -123,6 +124,18 @@ function EnvironmentWorkspaces({
               {descriptor.name && (
                 <p className="truncate text-xs text-text-secondary">{descriptor.id}</p>
               )}
+              {descriptor.instructions !== undefined && (
+                <p className="truncate text-xs text-text-secondary">
+                  {descriptor.instructions.length === 0
+                    ? localize('com_ui_repository_instructions_none')
+                    : descriptor.instructions
+                        .map(
+                          (file) =>
+                            `${file.path} · ${(file.bytes / 1024).toFixed(1)} KB${file.truncated ? ` · ${localize('com_ui_repository_instructions_truncated')}` : ''}`,
+                        )
+                        .join(', ')}
+                </p>
+              )}
               {(descriptor.environment?.repo || descriptor.environment?.ref) && (
                 <p className="truncate text-xs text-text-secondary">
                   {[descriptor.environment.repo, descriptor.environment.ref]

client/src/components/Chat/Input/__tests__/CodeWorkspaceMenu.spec.tsx

@@ -88,6 +88,19 @@ function renderMenu(ui: React.ReactElement) {
 }
 
 describe('CodeWorkspaceMenu', () => {
+  test('shows the instruction file and truncation reported by the worker', async () => {
+    const state = workspace();
+    state.environments[0].workspaces[0].instructions = [
+      { path: 'AGENTS.md', bytes: 32768, sha256: 'a'.repeat(64), truncated: true },
+    ];
+    renderMenu(
+      <CodeWorkspaceMenu setConversation={jest.fn()} workspace={state} disabled={false} />,
+    );
+    await userEvent.click(screen.getByTestId('code-workspace'));
+    expect(
+      await screen.findByText('AGENTS.md · 32.0 KB · com_ui_repository_instructions_truncated'),
+    ).toBeInTheDocument();
+  });
   test.each([
     ['example/app', 'example/app · dev'],
     [undefined, 'dev'],

client/src/components/SidePanel/Agents/AgentPanel.tsx

@@ -91,6 +91,7 @@ export function composeAgentUpdatePayload(
     stateful_code_sessions,
     stateful_code_environment,
     code_environment_id,
+    repositoryInstructions,
     code_workspace_id,
     git_identity,
     recursion_limit,
@@ -162,6 +163,7 @@ export function composeAgentUpdatePayload(
       stateful_code_sessions: normalizedStatefulCodeSessions,
       stateful_code_environment: normalizedStatefulCodeEnvironment,
       code_environment_id: agent_id ? code_environment_id : (code_environment_id ?? undefined),
+      repositoryInstructions,
       code_workspace_id,
       git_identity: normalizedGitIdentity,
       recursion_limit,
@@ -667,6 +669,7 @@ export default function AgentPanel() {
       create.mutate({
         ...basePayload,
         git_identity: basePayload.git_identity ?? undefined,
+        repositoryInstructions: basePayload.repositoryInstructions,
         model,
         tools,
         provider,

client/src/components/SidePanel/Agents/AgentSelect.tsx

@@ -101,6 +101,7 @@ function AgentSelect({
         avatar_action: null,
         stateful_code_environment: fullAgent.stateful_code_environment ?? 'user',
         code_environment_id: fullAgent.code_environment_id,
+        repositoryInstructions: fullAgent.repositoryInstructions,
         code_workspace_id: fullAgent.code_workspace_id,
         git_identity: fullAgent.git_identity,
       };

client/src/components/SidePanel/Agents/Code/Settings.tsx

@@ -308,6 +308,37 @@ export default function CodeSettings() {
           )}
           {showGitIdentity && (
             <div className="space-y-2 border-t border-border-light pt-3">
+              <label
+                htmlFor="repository-instructions"
+                className="text-xs font-medium text-text-secondary"
+              >
+                {localize('com_ui_repository_instructions')}
+              </label>
+              <Select
+                value={watch('repositoryInstructions') ?? 'prefer'}
+                onValueChange={(value) => {
+                  if (value === 'prefer' || value === 'defer' || value === 'off')
+                    setValue('repositoryInstructions', value, { shouldDirty: true });
+                }}
+              >
+                <SelectTrigger id="repository-instructions">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="prefer">
+                    {localize('com_ui_repository_instructions_prefer')}
+                  </SelectItem>
+                  <SelectItem value="defer">
+                    {localize('com_ui_repository_instructions_defer')}
+                  </SelectItem>
+                  <SelectItem value="off">
+                    {localize('com_ui_repository_instructions_off')}
+                  </SelectItem>
+                </SelectContent>
+              </Select>
+              <p className="text-xs text-text-tertiary">
+                {localize('com_ui_repository_instructions_description')}
+              </p>
               <div className="text-xs font-medium text-text-secondary">
                 {localize('com_ui_agent_git_identity')}
               </div>

client/src/locales/en/translation.json

@@ -1,4 +1,11 @@
 {
+  "com_ui_repository_instructions": "Repository instructions",
+  "com_ui_repository_instructions_prefer": "Prefer repository conventions",
+  "com_ui_repository_instructions_defer": "Prefer agent conventions",
+  "com_ui_repository_instructions_off": "Off",
+  "com_ui_repository_instructions_description": "Load AGENTS.md, or CLAUDE.md when absent, from the selected workspace when its owner enables discovery. Tool permissions remain unchanged.",
+  "com_ui_repository_instructions_none": "No repository instructions",
+  "com_ui_repository_instructions_truncated": "Truncated",
   "com_ui_code_workspace_default": "Default workspace for new chats",
   "com_ui_code_workspace_last_used": "Last used workspace",
   "com_ui_code_workspace_default_description": "New chats use this workspace. Without a default, reuse your last available choice for this agent and machine in this browser. Existing chats keep their workspace.",

packages/api/src/agents/__tests__/initialize.test.ts

@@ -287,6 +287,30 @@ describe('initializeAgent — execution context', () => {
     jest.clearAllMocks();
   });
 
+  it('places loaded repository instructions after agent instructions in the stable block', async () => {
+    const { agent, req, res, loadTools, db } = createMocks();
+    agent.instructions = 'Agent conventions';
+    loadTools.mockResolvedValue({
+      tools: [],
+      toolDefinitions: [],
+      repositoryInstructionBlock: 'Repository conventions',
+    });
+    const result = await initializeAgent(
+      {
+        req,
+        res,
+        agent,
+        loadTools,
+        endpointOption: { endpoint: EModelEndpoint.agents },
+        allowedProviders: new Set([agent.provider]),
+        isInitialAgent: true,
+      },
+      db,
+    );
+    expect(result.instructions).toBe('Agent conventions\n\nRepository conventions');
+    expect(result.additional_instructions ?? '').not.toContain('Repository conventions');
+  });
+
   it('carries request-resolved Azure identity to the run without changing persisted agent fields', async () => {
     const { agent, req, res, loadTools, db } = createMocks({
       provider: EModelEndpoint.azureOpenAI,

packages/api/src/agents/execution.ts

@@ -41,6 +41,7 @@ export interface CodeExecutionContext {
   /** Live, server-validated directory selection. Never derive session reuse from this field. */
   codeWorkspace?: CodeWorkspaceSelection & {
     operations: CodeWorkspaceOperation[];
+    instructions?: CodeWorkspaceDescriptor['instructions'];
     environment?: CodeWorkspaceDescriptor['environment'];
   };
 }