Explain why read_files blocks gitignored files

Author: nordicnode

sdk/src/__tests__/read-files.test.ts

@@ -393,11 +393,61 @@ describe('getFiles', () => {
         fs: mockFs,
       })
 
-      expect(result['node_modules/package/index.js']).toBe(
-        FILE_READ_STATUS.IGNORED,
+      expect(
+        result['node_modules/package/index.js']!.startsWith(
+          FILE_READ_STATUS.IGNORED,
+        ),
+      ).toBe(true)
+      expect(result['node_modules/package/index.js']).toContain(
+        'excluded by ignore rules',
       )
     })
 
+    test('ignore-rule block explains reason and unblock path; env-policy block stays opaque', async () => {
+      isFileIgnoredSpy.mockResolvedValue(true)
+
+      const mockFs = createMockFs({
+        files: {
+          '/project/AGENTS.local.md': { content: 'private notes' },
+        },
+      })
+
+      const result = await getFiles({
+        filePaths: ['AGENTS.local.md'],
+        cwd: '/project',
+        fs: mockFs,
+      })
+
+      expect(
+        result['AGENTS.local.md']!.startsWith(FILE_READ_STATUS.IGNORED),
+      ).toBe(true)
+      expect(result['AGENTS.local.md']).toContain('excluded by ignore rules')
+      expect(result['AGENTS.local.md']).toContain('cannot re-include')
+
+      // Ignored-and-deleted: the block must not assert the file exists.
+      const goneFs = createMockFs({ files: {} })
+      const goneResult = await getFiles({
+        filePaths: ['AGENTS.local.md'],
+        cwd: '/project',
+        fs: goneFs,
+      })
+      expect(
+        goneResult['AGENTS.local.md']!.startsWith(FILE_READ_STATUS.IGNORED),
+      ).toBe(true)
+      expect(goneResult['AGENTS.local.md']).not.toContain('exists on disk')
+
+      // The env-policy block must NOT leak a reason or an unblock hint.
+      const envFs = createMockFs({
+        files: { '/project/.env': { content: 'SECRET=value' } },
+      })
+      const envResult = await getFiles({
+        filePaths: ['.env'],
+        cwd: '/project',
+        fs: envFs,
+      })
+      expect(envResult['.env']).toBe(FILE_READ_STATUS.IGNORED)
+    })
+
     test('should call isFileIgnored with correct parameters', async () => {
       const mockFs = createMockFs({
         files: {
@@ -436,7 +486,11 @@ describe('getFiles', () => {
       })
 
       expect(result['src/index.ts']).toBe('main code')
-      expect(result['node_modules/pkg/index.js']).toBe(FILE_READ_STATUS.IGNORED)
+      expect(
+        result['node_modules/pkg/index.js']!.startsWith(
+          FILE_READ_STATUS.IGNORED,
+        ),
+      ).toBe(true)
     })
   })
 
@@ -454,10 +508,13 @@ describe('getFiles', () => {
         filePaths: ['node_modules/pkg/index.js'],
         cwd: '/project',
         fs: mockFs,
-        // No fileFilter provided - SDK applies default gitignore checking
       })
 
-      expect(result['node_modules/pkg/index.js']).toBe(FILE_READ_STATUS.IGNORED)
+      expect(
+        result['node_modules/pkg/index.js']!.startsWith(
+          FILE_READ_STATUS.IGNORED,
+        ),
+      ).toBe(true)
       expect(isFileIgnoredSpy).toHaveBeenCalled()
     })
 
@@ -615,8 +672,12 @@ describe('getFiles', () => {
         fileFilter: () => ({ status: 'allow' }),
       })
 
-      expect(result['.env.example']).toBe(FILE_READ_STATUS.IGNORED)
-      expect(result['.ENV.SAMPLE']).toBe(FILE_READ_STATUS.IGNORED)
+      expect(result['.env.example']!.startsWith(FILE_READ_STATUS.IGNORED)).toBe(
+        true,
+      )
+      expect(result['.ENV.SAMPLE']!.startsWith(FILE_READ_STATUS.IGNORED)).toBe(
+        true,
+      )
       expect(isFileIgnoredSpy).toHaveBeenCalledTimes(2)
     })
 

sdk/src/__tests__/run-file-filter.test.ts

@@ -275,7 +275,9 @@ describe('CodebuffClientOptions fileFilter', () => {
     })
 
     expect(result.output.type).toBe('lastMessage')
-    expect(requestedFiles['.env.example']).toBe(FILE_READ_STATUS.IGNORED)
+    expect(
+      requestedFiles['.env.example']!.startsWith(FILE_READ_STATUS.IGNORED),
+    ).toBe(true)
   })
 
   it('should pass fileFilter to requestOptionalFile as well', async () => {

sdk/src/tools/read-files.ts

@@ -99,7 +99,20 @@ export async function getFiles(params: {
         ...(isEnvTemplate ? { allowEnvTemplate: true } : {}),
       })
       if (ignored) {
-        result[relativePath] = FILE_READ_STATUS.IGNORED
+        // Keep the sentinel as the prefix (consumers match with startsWith)
+        // and append the reason, following the FILE_TOO_LARGE precedent.
+        // The ignore check never touches the file itself, so only claim
+        // existence when a stat confirms it.
+        let exists = false
+        try {
+          await fs.stat(fullPath)
+          exists = true
+        } catch {
+          // missing or unreadable: omit the existence claim
+        }
+        result[relativePath] =
+          FILE_READ_STATUS.IGNORED +
+          `: ${isEnvTemplate ? 'blocked by ignore-rule checking' : 'excluded by ignore rules'} (.gitignore, .codebuffignore, or built-in defaults), not an OS permission issue.${exists ? ' The file exists on disk;' : ''} glob and code_search omit it for the same reason. To allow tool reads, adjust or negate the matching rule in .codebuffignore (a file-level negation cannot re-include a path under an excluded directory).`
         continue
       }
     }