Keep env secrets opaque on internal-edit path; document codebuffignore

Author: nordicnode

sdk/README.md

@@ -180,6 +180,11 @@ gitignore. This built-in policy is scoped to
 SDK-mediated agent file reads (including `read_files`); it does not add
 terminal-command or internal-edit restrictions.
 
+Ignore-rule blocks on `read_files` return `[BLOCKED]` followed by a trailing
+reason. `.codebuffignore` — a project-level ignore file with `.gitignore`
+syntax, checked alongside `.gitignore` — is the escape hatch: adjust or
+negate the matching rule there to allow tool reads of a specific file.
+
 Custom `overrideTools.read_files` implementations must preserve project
 gitignore behavior for env templates. The built-in CLI, Desktop, Web, and Cloud
 bridges already do this.

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

@@ -436,6 +436,19 @@ describe('getFiles', () => {
       ).toBe(true)
       expect(goneResult['AGENTS.local.md']).not.toContain('exists on disk')
 
+      // Internal-edit path (no env policy): a secret blocked by built-in
+      // ignore defaults must stay opaque too.
+      const editFs = createMockFs({
+        files: { '/project/.env': { content: 'SECRET=value' } },
+      })
+      const editResult = await getFiles({
+        filePaths: ['.env'],
+        cwd: '/project',
+        fs: editFs,
+        enforceEnvPolicy: false,
+      })
+      expect(editResult['.env']).toBe(FILE_READ_STATUS.IGNORED)
+
       // The env-policy block must NOT leak a reason or an unblock hint.
       const envFs = createMockFs({
         files: { '/project/.env': { content: 'SECRET=value' } },

sdk/src/tools/read-files.ts

@@ -99,6 +99,13 @@ export async function getFiles(params: {
         ...(isEnvTemplate ? { allowEnvTemplate: true } : {}),
       })
       if (ignored) {
+        // The internal-edit path (enforceEnvPolicy: false) skips the env
+        // gate above, so secrets can reach this branch via built-in ignore
+        // defaults. Never explain or hint unblocking for them.
+        if (isSensitiveEnvFilePath(relativePath)) {
+          result[relativePath] = FILE_READ_STATUS.IGNORED
+          continue
+        }
         // 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