Add InstructionsLoaded hook for instruction file loading

packages/cli/src/config/config.ts

@@ -12,6 +12,7 @@ import {
   FileDiscoveryService,
   getAllGeminiMdFilenames,
   loadServerHierarchicalMemory,
+  type LoadServerHierarchicalMemoryOptions,
   type LoadServerHierarchicalMemoryResponse,
   setGeminiMdFilename as setServerGeminiMdFilename,
   resolveTelemetrySettings,
@@ -1130,6 +1131,7 @@ export async function loadHierarchicalGeminiMemory(
   folderTrust: boolean,
   memoryImportFormat: 'flat' | 'tree' = 'tree',
   contextRuleExcludes: string[] = [],
+  options: LoadServerHierarchicalMemoryOptions = {},
 ): Promise<LoadServerHierarchicalMemoryResponse> {
   // FIX: Use real, canonical paths for a reliable comparison to handle symlinks.
   const realCwd = fs.realpathSync(path.resolve(currentWorkingDirectory));
@@ -1149,6 +1151,7 @@ export async function loadHierarchicalGeminiMemory(
     folderTrust,
     memoryImportFormat,
     contextRuleExcludes,
+    options,
   );
 }
 

packages/cli/src/ui/AppContainer.tsx

@@ -43,6 +43,7 @@ import {
   getAllGeminiMdFilenames,
   ShellExecutionService,
   Storage,
+  createInstructionsLoadedCallback,
   SessionEndReason,
   generatePromptSuggestion,
   logPromptSuggestion,
@@ -1324,6 +1325,11 @@ export const AppContainer = (props: AppContainerProps) => {
           config.isTrustedFolder(),
           settings.merged.context?.importFormat || 'tree', // Use setting or default to 'tree'
           config.getContextRuleExcludes(),
+          {
+            onInstructionsLoaded: createInstructionsLoadedCallback(() =>
+              config.getHookSystem(),
+            ),
+          },
         );
 
       config.setUserMemory(memoryContent);

packages/cli/src/ui/commands/directoryCommand.tsx

@@ -17,6 +17,7 @@ import * as path from 'node:path';
 import {
   loadServerHierarchicalMemory,
   ConditionalRulesRegistry,
+  createInstructionsLoadedCallback,
 } from '@qwen-code/qwen-code-core';
 import { t } from '../../i18n/index.js';
 import { SettingScope } from '../../config/settings.js';
@@ -241,6 +242,11 @@ export const directoryCommand: SlashCommand = {
                 context.services.settings.merged.context?.importFormat ||
                   'tree', // Use setting or default to 'tree'
                 config.getContextRuleExcludes(),
+                {
+                  onInstructionsLoaded: createInstructionsLoadedCallback(() =>
+                    config.getHookSystem(),
+                  ),
+                },
               );
               config.setUserMemory(memoryContent);
               config.setGeminiMdFileCount(fileCount);

packages/cli/src/ui/components/hooks/constants.test.ts

@@ -93,6 +93,11 @@ describe('hooks constants', () => {
       expect(exitCodes).toHaveLength(3);
     });
 
+    it('should return exit codes for InstructionsLoaded event', () => {
+      const exitCodes = getHookExitCodes(HookEventName.InstructionsLoaded);
+      expect(exitCodes).toHaveLength(2);
+    });
+
     it('should return exit codes for PostCompact event', () => {
       const exitCodes = getHookExitCodes(HookEventName.PostCompact);
       expect(exitCodes).toHaveLength(2);
@@ -138,6 +143,11 @@ describe('hooks constants', () => {
       expect(desc).toBe('When a new session is started');
     });
 
+    it('should return description for InstructionsLoaded', () => {
+      const desc = getHookShortDescription(HookEventName.InstructionsLoaded);
+      expect(desc).toBe('When instruction files are loaded');
+    });
+
     it('should return description for PostCompact', () => {
       const desc = getHookShortDescription(HookEventName.PostCompact);
       expect(desc).toBe('After conversation compaction');
@@ -185,6 +195,13 @@ describe('hooks constants', () => {
       expect(desc).toBe('');
     });
 
+    it('should return description for InstructionsLoaded', () => {
+      const desc = getHookDescription(HookEventName.InstructionsLoaded);
+      expect(desc).toContain('file_path');
+      expect(desc).toContain('memory_type');
+      expect(desc).toContain('load_reason');
+    });
+
     it('should return description for PostCompact', () => {
       const desc = getHookDescription(HookEventName.PostCompact);
       expect(desc).toContain('trigger');
@@ -243,10 +260,11 @@ describe('hooks constants', () => {
       expect(DISPLAY_HOOK_EVENTS).toContain(HookEventName.PermissionDenied);
       expect(DISPLAY_HOOK_EVENTS).toContain(HookEventName.TodoCreated);
       expect(DISPLAY_HOOK_EVENTS).toContain(HookEventName.TodoCompleted);
+      expect(DISPLAY_HOOK_EVENTS).toContain(HookEventName.InstructionsLoaded);
     });
 
-    it('should have 17 events', () => {
-      expect(DISPLAY_HOOK_EVENTS).toHaveLength(17);
+    it('should have 18 events', () => {
+      expect(DISPLAY_HOOK_EVENTS).toHaveLength(18);
     });
   });
 
@@ -352,5 +370,15 @@ describe('hooks constants', () => {
       expect(info.exitCodes).toHaveLength(3);
       expect(info.matcherGroups).toEqual([]);
     });
+
+    it('should create empty info for InstructionsLoaded', () => {
+      const info = createEmptyHookEventInfo(HookEventName.InstructionsLoaded);
+
+      expect(info.event).toBe(HookEventName.InstructionsLoaded);
+      expect(info.shortDescription).toBe('When instruction files are loaded');
+      expect(info.description).toContain('file_path');
+      expect(info.exitCodes).toHaveLength(2);
+      expect(info.matcherGroups).toEqual([]);
+    });
   });
 });

packages/cli/src/ui/components/hooks/constants.ts

@@ -47,6 +47,10 @@ export function getHookExitCodes(eventName: string): HookExitCode[] {
       { code: 0, description: t('stdout/stderr not shown') },
       { code: 'Other', description: t('show stderr to user only') },
     ],
+    [HookEventName.InstructionsLoaded]: [
+      { code: 0, description: t('stdout/stderr not shown') },
+      { code: 'Other', description: t('show stderr to user only') },
+    ],
     [HookEventName.UserPromptSubmit]: [
       { code: 0, description: t('stdout shown to Qwen') },
       {
@@ -145,6 +149,7 @@ export function getHookShortDescription(eventName: string): string {
     [HookEventName.PostToolUse]: t('After tool execution'),
     [HookEventName.PostToolUseFailure]: t('After tool execution fails'),
     [HookEventName.Notification]: t('When notifications are sent'),
+    [HookEventName.InstructionsLoaded]: t('When instruction files are loaded'),
     [HookEventName.UserPromptSubmit]: t('When the user submits a prompt'),
     [HookEventName.SessionStart]: t('When a new session is started'),
     [HookEventName.Stop]: t('Right before Qwen Code concludes its response'),
@@ -190,6 +195,9 @@ export function getHookDescription(eventName: string): string {
     [HookEventName.Notification]: t(
       'Input to command is JSON with notification message and type.',
     ),
+    [HookEventName.InstructionsLoaded]: t(
+      'Input to command is JSON with file_path, memory_type, load_reason, and optional trigger_file_path and parent_file_path.',
+    ),
     [HookEventName.UserPromptSubmit]: t(
       'Input to command is JSON with original user prompt text.',
     ),

packages/core/src/config/config.test.ts

@@ -49,6 +49,7 @@ import { ToolNames } from '../tools/tool-names.js';
 import { fireNotificationHook } from '../core/toolHookTriggers.js';
 import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import { loadServerHierarchicalMemory } from '../utils/memoryDiscovery.js';
+import type { LoadServerHierarchicalMemoryOptions } from '../utils/memoryDiscovery.js';
 import { readAutoMemoryIndex } from '../memory/store.js';
 import { ExtensionManager } from '../extension/extensionManager.js';
 import { SkillManager } from '../skills/skill-manager.js';
@@ -151,6 +152,29 @@ vi.mock('../hooks/index.js', () => {
   return {
     HookSystem: HookSystemMock,
     createHookOutput: vi.fn(),
+    createInstructionsLoadedCallback:
+      (
+        getHookSystem: () => {
+          fireInstructionsLoadedEvent?: (...args: unknown[]) => unknown;
+        },
+      ) =>
+      async (notification: {
+        filePath: string;
+        memoryType: string;
+        loadReason: string;
+        triggerFilePath?: string;
+        parentFilePath?: string;
+      }) => {
+        await getHookSystem()?.fireInstructionsLoadedEvent?.(
+          notification.filePath,
+          notification.memoryType,
+          notification.loadReason,
+          {
+            triggerFilePath: notification.triggerFilePath,
+            parentFilePath: notification.parentFilePath,
+          },
+        );
+      },
   };
 });
 
@@ -1440,7 +1464,7 @@ describe('Server Config (config.ts)', () => {
     await config.refreshHierarchicalMemory();
 
     const lastCall = vi.mocked(loadServerHierarchicalMemory).mock.calls.at(-1);
-    expect(lastCall?.at(-1)).toEqual({ explicitOnly: true });
+    expect(lastCall?.at(-1)).toMatchObject({ explicitOnly: true });
     expect(lastCall?.[1]).toEqual([]);
     expect(readAutoMemoryIndex).not.toHaveBeenCalled();
     expect(config.getUserMemory()).toContain('Project rules');
@@ -1468,7 +1492,49 @@ describe('Server Config (config.ts)', () => {
 
     const lastCall = vi.mocked(loadServerHierarchicalMemory).mock.calls.at(-1);
     expect(lastCall?.[1]).toEqual([explicitDir]);
-    expect(lastCall?.at(-1)).toEqual({ explicitOnly: true });
+    expect(lastCall?.at(-1)).toMatchObject({ explicitOnly: true });
+  });
+
+  it('refreshHierarchicalMemory should fire InstructionsLoaded hooks from memory notifications', async () => {
+    const config = new Config(baseParams);
+    const fireInstructionsLoadedEvent = vi.fn().mockResolvedValue(undefined);
+    config['hookSystem'] = {
+      fireInstructionsLoadedEvent,
+    } as unknown as HookSystem;
+
+    vi.mocked(loadServerHierarchicalMemory).mockResolvedValue({
+      memoryContent: '--- Context from: QWEN.md ---\nProject rules',
+      fileCount: 1,
+      ruleCount: 0,
+      conditionalRules: [],
+      projectRoot: '/tmp',
+    });
+
+    await config.refreshHierarchicalMemory();
+
+    const lastCall = vi.mocked(loadServerHierarchicalMemory).mock.calls.at(-1);
+    const options = lastCall?.at(-1) as
+      | LoadServerHierarchicalMemoryOptions
+      | undefined;
+    expect(options?.onInstructionsLoaded).toEqual(expect.any(Function));
+
+    await options?.onInstructionsLoaded?.({
+      filePath: '/tmp/project/QWEN.md',
+      memoryType: 'project',
+      loadReason: 'include',
+      triggerFilePath: '/tmp/project/AGENTS.md',
+      parentFilePath: '/tmp/project/AGENTS.md',
+    });
+
+    expect(fireInstructionsLoadedEvent).toHaveBeenCalledWith(
+      '/tmp/project/QWEN.md',
+      'project',
+      'include',
+      {
+        triggerFilePath: '/tmp/project/AGENTS.md',
+        parentFilePath: '/tmp/project/AGENTS.md',
+      },
+    );
   });
 
   it('Config constructor should call setGeminiMdFilename with contextFileName if provided', () => {

packages/core/src/config/config.ts

@@ -105,7 +105,11 @@ import {
   ExtensionManager,
   type Extension,
 } from '../extension/extensionManager.js';
-import { HookSystem, createHookOutput } from '../hooks/index.js';
+import {
+  HookSystem,
+  createHookOutput,
+  createInstructionsLoadedCallback,
+} from '../hooks/index.js';
 import { MessageBus } from '../confirmation-bus/message-bus.js';
 import {
   MessageBusType,
@@ -1864,7 +1868,12 @@ export class Config {
         this.isTrustedFolder(),
         this.getImportFormat(),
         this.contextRuleExcludes,
-        { explicitOnly: this.getBareMode() },
+        {
+          explicitOnly: this.getBareMode(),
+          onInstructionsLoaded: createInstructionsLoadedCallback(
+            () => this.hookSystem,
+          ),
+        },
       );
     if (this.getManagedAutoMemoryEnabled()) {
       const managedAutoMemoryIndex = await readAutoMemoryIndex(

packages/core/src/hooks/hookEventHandler.test.ts

@@ -168,6 +168,52 @@ describe('HookEventHandler', () => {
     });
   });
 
+  describe('fireInstructionsLoadedEvent', () => {
+    it('should include instruction load metadata in hook input', async () => {
+      const mockPlan = createMockExecutionPlan([
+        {
+          type: HookType.Command,
+          command: 'echo test',
+          source: HooksConfigSource.Project,
+        },
+      ]);
+      vi.mocked(mockHookPlanner.createExecutionPlan).mockReturnValue(mockPlan);
+      vi.mocked(mockHookRunner.executeHooksParallel).mockResolvedValue([]);
+      vi.mocked(mockHookAggregator.aggregateResults).mockReturnValue(
+        createMockAggregatedResult(true),
+      );
+
+      await hookEventHandler.fireInstructionsLoadedEvent(
+        '/repo/.qwen/QWEN.local.md',
+        'local',
+        'include',
+        {
+          parentFilePath: '/repo/QWEN.md',
+        },
+      );
+
+      expect(mockHookPlanner.createExecutionPlan).toHaveBeenCalledWith(
+        HookEventName.InstructionsLoaded,
+        {
+          filePath: '/repo/.qwen/QWEN.local.md',
+        },
+      );
+
+      const mockCalls = (mockHookRunner.executeHooksParallel as Mock).mock
+        .calls;
+      const input = mockCalls[0][2] as {
+        file_path: string;
+        memory_type: string;
+        load_reason: string;
+        parent_file_path?: string;
+      };
+      expect(input.file_path).toBe('/repo/.qwen/QWEN.local.md');
+      expect(input.memory_type).toBe('local');
+      expect(input.load_reason).toBe('include');
+      expect(input.parent_file_path).toBe('/repo/QWEN.md');
+    });
+  });
+
   describe('fireStopEvent', () => {
     it('should execute hooks for Stop event', async () => {
       const mockPlan = createMockExecutionPlan([]);

packages/core/src/hooks/hookEventHandler.ts

@@ -45,6 +45,9 @@ import type {
   TodoCompletedInput,
   TodoItem,
   TodoStatus,
+  InstructionsLoadedInput,
+  InstructionMemoryType,
+  InstructionLoadReason,
 } from './types.js';
 import { HookPhase, PermissionMode } from './types.js';
 import { createDebugLogger } from '../utils/debugLogger.js';
@@ -116,6 +119,35 @@ export class HookEventHandler {
     );
   }
 
+  async fireInstructionsLoadedEvent(
+    filePath: string,
+    memoryType: InstructionMemoryType,
+    loadReason: InstructionLoadReason,
+    options: {
+      triggerFilePath?: string;
+      parentFilePath?: string;
+    } = {},
+    signal?: AbortSignal,
+  ): Promise<AggregatedHookResult> {
+    const input: InstructionsLoadedInput = {
+      ...this.createBaseInput(HookEventName.InstructionsLoaded),
+      file_path: filePath,
+      memory_type: memoryType,
+      load_reason: loadReason,
+      trigger_file_path: options.triggerFilePath,
+      parent_file_path: options.parentFilePath,
+    };
+
+    return this.executeHooks(
+      HookEventName.InstructionsLoaded,
+      input,
+      {
+        filePath,
+      },
+      signal,
+    );
+  }
+
   /**
    * Fire a Stop event
    * Called by handleHookExecutionRequest - executes hooks directly