@klarkxy/dsh-safe-auto 0.1.0-rc.6 → 0.2.0

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Safe Auto",
-    "description": "Budgeted preflight and one-shot escalation; the reviewer follows the conversation or works independently."
+    "description": "An independent reviewer vets each sandbox escalation; only a pass auto-approves that one call."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "安全自动",
-    "description": "预算内预检、单次升级；审查可跟随当前会话，也可独立进行。"
+    "description": "沙箱提权请求由独立审核模型把关，通过才自动放行这一次调用。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@klarkxy/dsh-safe-auto",
-  "version": "0.1.0-rc.6",
-  "description": "Safe Auto: budgeted preflight and one-shot escalation with conversation-following or independent reviewers.",
+  "version": "0.2.0",
+  "description": "Safe Auto: an independent reviewer vets each native sandbox escalation; only a pass auto-approves that one call.",
   "icon": "./icon.svg",
   "type": "module",
   "main": "src/index.js",
@@ -24,12 +24,12 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "node --check src/config.js && node --check src/approval-review.js && node --check src/policy.js && node --check src/escalation.js && node --check src/model-route.js && node --check src/reviewer.js && node --check src/gate.js && node --check src/index.js && node --check src/control.js && node --check src/ui-host.js && tsdown && node ../../scripts/editor-plugins/wrap-client.mjs @klarkxy/dsh-safe-auto",
+    "build": "node --check src/config.js && node --check src/approval-review.js && node --check src/policy.js && node --check src/credential-paths.js && node --check src/credential-text.js && node --check src/credential-reads.js && node --check src/host-runtime.js && node --check src/review-paths.js && node --check src/shell-command.js && node --check src/model-route.js && node --check src/review-context.js && node --check src/execution-evidence.js && node --check src/human-approval.js && node --check src/reviewer.js && node --check src/gate.js && node --check src/index.js && node --check src/control.js && node --check src/ui-host.js && tsdown && node ../../scripts/editor-plugins/wrap-client.mjs @klarkxy/dsh-safe-auto",
     "test": "node --test test/*.test.js"
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.7-rc.2"
+    "dsh": ">=0.2.0-rc.2"
   },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -59,11 +59,16 @@
     }
   },
   "dependencies": {
-    "zod": "^4.1.5",
-    "@klarkxy/dsh-plugin-kit": "0.1.0"
+    "@klarkxy/dsh-plugin-kit": "0.3.0",
+    "jsonc-parser": "^3.3.1",
+    "toml-eslint-parser": "^1.0.3",
+    "unbash": "^5.0.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.1.5"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.7-rc.2"
+    "@deepseek-ai/cordis": ">=4.0.4",
+    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-storage-domain": {
@@ -71,14 +76,17 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-storage-domain": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.2",
+    "@klarkxy/dsh-model-route": "0.2.0",
+    "jsdom": "29.1.1"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "dshRelease": {
-    "contentHash": "5321eedca85ac7fee0b810ab8d95dde54a4bb4ae60f7691dac5f9314251b2b33"
+    "contentHash": "82e8f79730f15a39b180ac572531df3bef696467aa79ef7bcc76727252b3d09e"
   }
 }

package/src/approval-review.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { containsSecret, hardRisk } from './policy.js';
 
 const verdict = (kind, code, extra = {}) => ({ kind, code, ...extra });
@@ -11,9 +12,10 @@ export function assessApproval(call, config) {
   if (!call || !call.args || typeof call.args !== 'object' || Array.isArray(call.args)) return verdict('ask', 'INVALID_ARGUMENTS');
   const hard = hardRisk(call);
   if (hard) return hard;
-  if (config.approvalReview !== true) return verdict('ask', 'APPROVAL_REVIEW_DISABLED');
+  if (config.enabled !== true) return verdict('ask', 'SAFE_AUTO_DISABLED');
   if (call.sandbox?.mode !== 'workspace-write') return verdict('deny', 'WORKSPACE_SANDBOX_REQUIRED');
   if (!call.session || typeof call.session !== 'object' || call.subagent !== false || call.nested !== false) return verdict('ask', 'NO_DIRECT_USER_AUTHORITY');
+  if (call.authorityIncomplete) return verdict('ask', 'AUTHORITY_CONTEXT_INCOMPLETE');
   if (call.localExecution !== true || call.remote === true) return verdict('ask', 'LOCAL_EXECUTION_UNVERIFIED');
   if (!nonempty(call.cwd)) return verdict('ask', 'INVALID_CWD');
   if (!TOOLS.has(call.tool)) return verdict('ask', 'UNSUPPORTED_TOOL');
@@ -39,7 +41,9 @@ export function assessApproval(call, config) {
       (Object.hasOwn(args, 'replace_all') && typeof args.replace_all !== 'boolean')) return verdict('ask', 'INVALID_FILE_ARGUMENTS');
   } else {
     if (!nonempty(args.command) || !nonempty(args.description)) return verdict('ask', 'INVALID_COMMAND_ARGUMENTS');
-    if (Object.hasOwn(args, 'timeoutMs') && (!Number.isSafeInteger(args.timeoutMs) || args.timeoutMs <= 0 || args.timeoutMs > 60000)) return verdict('ask', 'INVALID_TIMEOUT');
+    // Native shell tools accept positive finite values; the executor owns caps.
+    // This process timeout is independent of the review budget and grant lease.
+    if (Object.hasOwn(args, 'timeoutMs') && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) return verdict('ask', 'INVALID_TIMEOUT');
     if (Object.hasOwn(args, 'workdir') && !nonempty(args.workdir)) return verdict('ask', 'INVALID_WORKDIR');
     if (Object.hasOwn(args, 'run_in_background') && typeof args.run_in_background !== 'boolean') return verdict('ask', 'INVALID_BACKGROUND');
   }
@@ -53,6 +57,24 @@ export function assessApproval(call, config) {
   if (containsSecret(serialized)) return verdict('deny', 'SENSITIVE_ARGUMENTS');
   return verdict('review', 'NATIVE_APPROVAL_REVIEW', { action: {
     tool: call.tool, arguments: JSON.parse(serialized), cwd: call.cwd,
+    ...(call.reviewPaths === undefined ? {} : { reviewPaths: call.reviewPaths }),
+    ...(call.trustedRuntime === undefined ? {} : { trustedRuntime: call.trustedRuntime }),
     permission: { from: call.sandbox.mode, to: args.sandbox_permissions, scope: 'this-call-only' },
   } });
 }
+
+/** Both grant and request use the native helper's exact audited reason, not a prefix match. */
+export function escalationReason(call) {
+  return `escalate sandbox to ${call.args.sandbox_permissions}: ${call.args.justification}`;
+}
+
+/** Include execution identity in the pending decision; authorization is never cached across calls. */
+export function bindingOf(call, assessment) {
+  return createHash('sha256').update(JSON.stringify({
+    tool: call.tool, args: call.args, cwd: call.cwd, sandbox: call.sandbox, reviewPaths: call.reviewPaths, trustedRuntime: call.trustedRuntime,
+    task: call.task, intent: call.intent, authorizationContext: call.authorizationContext,
+    authorityIncomplete: call.authorityIncomplete, subagent: call.subagent, nested: call.nested,
+    localExecution: call.localExecution, jobsAvailable: call.jobsAvailable, shellConfined: call.shellConfined,
+    code: assessment.code,
+  })).digest('hex');
+}

package/src/config.js

@@ -1,23 +1,17 @@
-import { isAbsolute } from 'node:path';
-import { parseEscalationCandidates } from './escalation.js';
 import { validateModelConfig } from './model-route.js';
 
 const defaults = Object.freeze({
-  mode: 'shadow', approvalReview: false, workspaceRoots: [], shellCandidates: [], escalationCandidates: [],
-  escalationApprovalTtlMs: 30000, escalationMaxTimeoutMs: 30000,
-  endpoint: '', fastProvider: '', fastModel: '', deepProvider: '', deepModel: '', apiKeyEnv: 'DSH_SAFE_AUTO_API_KEY',
-  fastReasoningEffort: '', deepReasoningEffort: '', reviewerPrompt: '',
-  tokenField: 'max_tokens', timeoutMs: 8000, maxInputBytes: 8192,
-  fastOutputTokens: 64, deepOutputTokens: 256,
-  fastCallsPerTask: 20, deepCallsPerTask: 3, sessionBudgetUnits: 100000,
-  consecutiveDenials: 3, totalDenials: 20,
+  enabled: true,
+  provider: '', model: '', reasoningEffort: '', reviewerPrompt: '',
+  timeoutMs: 30000, maxInputBytes: 32768, outputTokens: 1024,
+  humanApprovalTimeoutMs: 60000,
+  maxReviewsPerTask: 20, consecutiveDenials: 3,
+  staticReadonly: true,
 });
 const limits = {
-  escalationApprovalTtlMs: [100, 120000], escalationMaxTimeoutMs: [100, 60000],
-  timeoutMs: [100, 60000], maxInputBytes: [512, 32768],
-  fastOutputTokens: [32, 512], deepOutputTokens: [64, 2048],
-  fastCallsPerTask: [1, 100], deepCallsPerTask: [0, 20],
-  sessionBudgetUnits: [1024, 10000000], consecutiveDenials: [1, 20], totalDenials: [1, 100],
+  timeoutMs: [100, 120000], maxInputBytes: [512, 32768], outputTokens: [64, 2048],
+  maxReviewsPerTask: [1, 100], consecutiveDenials: [1, 20],
+  humanApprovalTimeoutMs: [0, 300000],
 };
 
 /** Immutable, load-time policy. Unknown keys fail rather than silently disabling a control. */
@@ -25,32 +19,15 @@ export function parseConfig(raw = {}) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('config must be an object');
   for (const key of Object.keys(raw)) if (!Object.hasOwn(defaults, key)) throw new Error(`unknown config field: ${key}`);
   const c = { ...defaults, ...raw };
-  if (!['off', 'shadow', 'smart', 'unattended'].includes(c.mode)) throw new Error('invalid mode');
-  if (typeof c.approvalReview !== 'boolean') throw new Error('approvalReview must be a boolean');
-  for (const key of ['endpoint', 'fastProvider', 'fastModel', 'deepProvider', 'deepModel', 'apiKeyEnv', 'tokenField', 'fastReasoningEffort', 'deepReasoningEffort', 'reviewerPrompt']) {
+  if (typeof c.enabled !== 'boolean') throw new Error('enabled must be a boolean');
+  if (typeof c.staticReadonly !== 'boolean') throw new Error('staticReadonly must be a boolean');
+  for (const key of ['provider', 'model', 'reasoningEffort', 'reviewerPrompt']) {
     if (typeof c[key] !== 'string' || c[key].length > 4096) throw new Error(`${key} must be a string`);
   }
-  for (const key of ['workspaceRoots', 'shellCandidates']) {
-    if (!Array.isArray(c[key]) || c[key].length > 100 || c[key].some(x => typeof x !== 'string' || !x || x.length > 4096)) {
-      throw new Error(`${key} must contain at most 100 nonempty strings`);
-    }
-    c[key] = Object.freeze([...new Set(c[key])]);
-  }
-  if (c.workspaceRoots.some(p => !isAbsolute(p))) throw new Error('workspaceRoots must be absolute local paths');
   for (const [key, [min, max]] of Object.entries(limits)) {
     if (!Number.isSafeInteger(c[key]) || c[key] < min || c[key] > max) throw new Error(`invalid ${key}`);
   }
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(c.apiKeyEnv)) throw new Error('invalid apiKeyEnv');
-  if (!['max_tokens', 'max_completion_tokens'].includes(c.tokenField)) throw new Error('invalid tokenField');
   validateModelConfig(c);
-  if (c.endpoint) {
-    const u = new URL(c.endpoint);
-    if (u.username || u.password || u.hash || u.search) throw new Error('endpoint must not contain credentials, query or fragment');
-    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
-    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback)) throw new Error('endpoint requires HTTPS or loopback HTTP');
-    c.endpoint = u.href;
-  }
-  c.escalationCandidates = parseEscalationCandidates(c.escalationCandidates, c.workspaceRoots);
   return Object.freeze(c);
 }
 

package/src/control.js

@@ -2,18 +2,20 @@ import { isSubagentSession } from '@klarkxy/dsh-plugin-kit/contracts';
 import { parseConfig } from './config.js';
 
 export const CHANNEL = '/dsh-safe-auto';
-export const REVIEW_FIELDS = ['fastProvider', 'fastModel', 'deepProvider', 'deepModel', 'fastReasoningEffort', 'deepReasoningEffort', 'reviewerPrompt'];
-export const SETTINGS_FIELDS = ['approvalReview', ...REVIEW_FIELDS];
+export const REVIEW_FIELDS = ['provider', 'model', 'reasoningEffort', 'reviewerPrompt'];
+export const SETTINGS_FIELDS = REVIEW_FIELDS;
 const modes = new Set(['read-only', 'workspace-write', 'danger-full-access']);
 
-/** UI writes only reviewer preferences. Permission envelopes remain operator-owned profile config. */
-export function createControl(base, { table, presets, sandboxPolicy, sessions, platform = process.platform }) {
+/** UI writes only reviewer preferences. The enable switch and budgets remain operator-owned profile config. */
+export function createControl(base, { table, presets, sandboxPolicy, sessions, platform = process.platform, onChange = () => {}, onSettingsChanged = () => {} }) {
   let settings = table.get('reviewer') ?? { revision: 0, values: {} };
   let tail = Promise.resolve();
+  const lifetime = new AbortController();
   const selections = new WeakMap();
   let generation = 0;
   const effective = () => parseConfig({ ...base, ...settings.values });
   function active(session) {
+    if (lifetime.signal.aborted) return false;
     const selected = session && selections.get(session);
     if (!selected || selected.enabled === false) return false;
     const events = session.snapshotEvents();
@@ -32,8 +34,8 @@ export function createControl(base, { table, presets, sandboxPolicy, sessions, p
     return { active: enabled, revision: `${settings.revision}:${selected?.generation ?? 0}` };
   }
   function config(session) {
-    if (!active(session)) return parseConfig({ ...effective(), mode: 'off' });
-    return parseConfig({ ...effective(), mode: 'smart' });
+    if (!active(session)) return parseConfig({ ...effective(), enabled: false });
+    return effective();
   }
   function workspaceOption() {
     return presets.catalog().options.find(o => {
@@ -43,16 +45,15 @@ export function createControl(base, { table, presets, sandboxPolicy, sessions, p
   }
   function policyView() {
     const c = effective();
-    return { available: base.mode !== 'off' && Boolean(workspaceOption()), platform,
-      candidateCounts: { workspaceRoots: c.workspaceRoots.length, shellCandidates: c.shellCandidates.length, escalationCandidates: c.escalationCandidates.length },
+    return { available: base.enabled && Boolean(workspaceOption()), platform,
       policyLimits: { readonly: true, sandbox: 'workspace-write', approval: 'ask', rootSessionsOnly: true,
-        escalationScope: 'this-call-only', escalationApprovalTtlMs: c.escalationApprovalTtlMs, escalationMaxTimeoutMs: c.escalationMaxTimeoutMs,
-        timeoutMs: c.timeoutMs, maxInputBytes: c.maxInputBytes, fastCallsPerTask: c.fastCallsPerTask, deepCallsPerTask: c.deepCallsPerTask,
-        sessionBudgetUnits: c.sessionBudgetUnits, consecutiveDenials: c.consecutiveDenials, totalDenials: c.totalDenials } };
+        escalationScope: 'this-call-only', timeoutMs: c.timeoutMs, maxInputBytes: c.maxInputBytes,
+        outputTokens: c.outputTokens, maxReviewsPerTask: c.maxReviewsPerTask, consecutiveDenials: c.consecutiveDenials,
+        humanApprovalTimeoutMs: c.humanApprovalTimeoutMs } };
   }
   function settingsView() {
     const c = effective();
-    return { revision: settings.revision, values: { approvalReview: c.approvalReview ?? false, ...Object.fromEntries(REVIEW_FIELDS.map(k => [k, c[k] ?? ''])) }, http: Boolean(c.endpoint), ...policyView() };
+    return { revision: settings.revision, values: Object.fromEntries(REVIEW_FIELDS.map(k => [k, c[k] ?? ''])), ...policyView() };
   }
   function sessionView(session) {
     const catalog = presets.catalog();
@@ -76,13 +77,16 @@ export function createControl(base, { table, presets, sandboxPolicy, sessions, p
     if (endpoint === 'settings.get') return settingsView();
     if (endpoint === 'settings.save') {
       if (payload.expectedRevision !== settings.revision) throw new Error('Settings changed; reload and retry');
-      if (base.endpoint) throw new Error('HTTP reviewer settings remain in the profile');
       const values = payload.values;
       if (!values || typeof values !== 'object' || Array.isArray(values) || Object.keys(values).some(k => !SETTINGS_FIELDS.includes(k))) throw new Error('Only reviewer settings may be edited here');
       const nextConfig = parseConfig({ ...base, ...settings.values, ...values });
-      const next = { revision: settings.revision + 1, values: { approvalReview: nextConfig.approvalReview ?? false, ...Object.fromEntries(REVIEW_FIELDS.map(k => [k, nextConfig[k] ?? ''])) } };
+      const next = { revision: settings.revision + 1, values: Object.fromEntries(REVIEW_FIELDS.map(k => [k, nextConfig[k] ?? ''])) };
       await table.put('reviewer', next);
       settings = next;
+      // Notify committed writes even when the caller was cancelled while saving.
+      try { onSettingsChanged(next.revision); } catch {}
+      signal?.throwIfAborted();
+      onChange();
       return settingsView();
     }
     if (endpoint === 'session.list') return { sessions: sessions.list()
@@ -95,10 +99,11 @@ export function createControl(base, { table, presets, sandboxPolicy, sessions, p
     if (payload.expectedRevision !== sessionView(session).revision) throw new Error('Session changed; refresh the list and retry');
     if (endpoint === 'session.disable') {
       selections.set(session, { enabled: false, generation: ++generation });
+      onChange();
       return sessionView(session);
     }
     if (payload.value === 'safe-auto') {
-      if (base.mode === 'off') throw new Error('Safe Auto is disabled in the profile');
+      if (!base.enabled) throw new Error('Safe Auto is disabled in the profile');
       const option = workspaceOption();
       if (!option) throw new Error('Workspace Write with native approval is unavailable');
       presets.set(session, option.value);
@@ -110,11 +115,18 @@ export function createControl(base, { table, presets, sandboxPolicy, sessions, p
       selections.set(session, { enabled: false, generation: ++generation });
       presets.set(session, option.value);
     }
+    onChange();
     return sessionView(session);
   }
-  return { state, config, settingsView,
+  return { state, config, settingsView, getSession, signal: lifetime.signal,
+    async dispose() {
+      lifetime.abort(new Error('Safe Auto control unloaded'));
+      await tail;
+    },
     call(endpoint, payload, signal) {
-      const work = tail.then(() => dispatch(endpoint, payload, signal));
+      if (lifetime.signal.aborted) return Promise.reject(lifetime.signal.reason);
+      const combined = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+      const work = tail.then(() => dispatch(endpoint, payload, combined));
       tail = work.catch(() => {});
       return work;
     },

package/src/credential-paths.js

@@ -0,0 +1,29 @@
+// Path names identify dedicated stores, never entire agent/config directories.
+// Content screening handles credentials embedded in otherwise ordinary files.
+export function normalizedCredentialPath(path) {
+  return String(path ?? '').replaceAll('\\', '/').replace(/\/+/g, '/').toLowerCase();
+}
+
+export function credentialSourcePath(path) {
+  return normalizedCredentialPath(path).replace(/:(?:\$data|:\$data)$/i, '').replace(/[. ]+$/g, '')
+    .replace(/(?:\.(?:bak|backup|old|orig|save|tmp)|\.corrupt-[a-z0-9_-]+|~)+$/g, '');
+}
+
+export function isCredentialPath(path) {
+  const normalized = credentialSourcePath(path);
+  const parts = normalized.split('/').filter(Boolean);
+  const base = parts.at(-1) ?? '';
+  if (/^(?:auth(?:entication)?|credentials?|\.credentials|tokens?|token-cache|access-tokens|refresh-tokens)\.(?:jsonc?|jsonl|ya?ml|toml|db|sqlite3?)$/.test(base)) return true;
+  if (['credentials', '.netrc', '_netrc', '.git-credentials', '.dockercfg'].includes(base)) return true;
+  if (parts.includes('.ssh') && /^(?:id_(?:rsa|dsa|ecdsa|ed25519)(?:_sk)?|identity)$/.test(base)) return true;
+  if (parts.includes('.gnupg') && (parts.includes('private-keys-v1.d') || /^(?:secring|secret-keys)\./.test(base))) return true;
+  if (parts.includes('.aws') && (parts.includes('sso') && parts.includes('cache') || parts.includes('cli') && parts.includes('cache'))) return true;
+  if (parts.includes('.azure') && /^(?:msal_token_cache|accesstokens)\./.test(base)) return true;
+  if (parts.includes('gcloud') && /^(?:application_default_credentials\.json|credentials\.db|access_tokens\.db)$/.test(base)) return true;
+  return /\.(?:p12|pfx)$/.test(base);
+}
+
+// Mutation protection deliberately remains stricter than read protection.
+export const isMutationProtectedPath = path => /(?:^|[\\/])(?:\.git|\.ssh|\.aws|\.gnupg|\.codex|\.dsh|\.claude|\.agents|\.github|\.kube|\.azure|\.config)(?:[\\/]|$)|(?:^|[\\/])(?:\.env(?:\.[^\\/]*)?|\.npmrc|\.netrc|\.pypirc|\.gitconfig|\.bashrc|\.zshrc|\.profile|AGENTS(?:\.local)?\.md|CLAUDE\.md|id_rsa|id_ed25519|credentials)(?:[\\/]|$)|\.(?:pem|key|p12|pfx)$/i.test(String(path ?? ''));
+
+export const isStructuredCredentialText = path => /\.(?:jsonc?|jsonl|ndjson|ya?ml|toml|ini|conf|config)$/.test(credentialSourcePath(path)) || /(?:^|\/)(?:\.env(?:\.[^/]*)?|\.npmrc|\.pypirc|\.gitconfig|config)$/.test(credentialSourcePath(path));

package/src/credential-reads.js

@@ -0,0 +1,227 @@
+import { isAbsolute } from 'node:path';
+import { credentialSourcePath, isCredentialPath, isStructuredCredentialText, isMutationProtectedPath } from './credential-paths.js';
+import { redactCredentialText } from './credential-text.js';
+import { analyzeShell, isSafeStaticExposure, shellRefusals } from './shell-command.js';
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+const MAX_WINDOW_BYTES = 8 * MAX_SOURCE_BYTES;
+const errorResult = code => {
+  const message = `safe-auto: ${code}. Use the native read tool for non-secret file content; credentials are withheld.`;
+  return { isError: true, error: { message, info: { name: 'SafeAutoError', code } }, content: [{ type: 'text', text: message }] };
+};
+const failure = () => { throw new Error('CREDENTIAL_READ_UNAVAILABLE'); };
+const stripCR = line => line.endsWith('\r') ? line.slice(0, -1) : line;
+const fresh = value => ({ isError: false, value, content: [] });
+const identity = (fs, target) => `${target.targetKey ?? ''}\0${fs.processPath(target)}`;
+const fsAvailable = fs => fs && ['resolve', 'stat', 'readBytes', 'processPath'].every(key => typeof fs[key] === 'function');
+const textRead = exec => exec.name === 'read' || exec.name === 'str_replace_editor' && exec.arguments?.command === 'view';
+const cwdOf = exec => exec.name === 'str_replace_editor' ? undefined : exec.agent?.session?.header?.cwd;
+
+async function resolveFile(fs, path, exec, cwd = cwdOf(exec)) {
+  const target = await fs.resolve(path, { cwd, signal: exec.signal });
+  if (isCredentialPath(path) || isCredentialPath(fs.processPath(target))) throw new Error('CREDENTIAL_PATH');
+  return { target, path, key: identity(fs, target), info: await fs.stat(target, exec.signal) };
+}
+
+async function unchanged(fs, saved, exec) {
+  const next = await resolveFile(fs, saved.path, exec);
+  if (saved.key !== next.key || saved.info?.version !== next.info?.version || saved.info?.type !== next.info?.type) failure();
+}
+
+async function wholeSource(fs, saved, exec) {
+  const bytes = await fs.readBytes(saved.target, exec.signal, MAX_SOURCE_BYTES);
+  if (!(bytes instanceof Uint8Array) || bytes.length > MAX_SOURCE_BYTES) failure();
+  const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  if (source.includes('\0')) failure();
+  const sanitized = redactCredentialText(source, fs.processPath(saved.target));
+  await unchanged(fs, saved, exec);
+  return { source, sanitized };
+}
+
+// Preserve the host's exact window and configured caps. A truncated native
+// line is matched to its original prefix, never independently parsed as JSON.
+function projectLine(raw, safe, rendered) {
+  raw = stripCR(raw); safe = stripCR(safe);
+  if (rendered === raw) return safe;
+  const suffix = /\.\.\. \(line truncated to (\d+) chars\)$/.exec(rendered);
+  const cap = suffix && Number(suffix[1]);
+  if (!cap || raw.length <= cap || rendered !== raw.slice(0, cap) + suffix[0]) failure();
+  return safe.slice(0, cap) + suffix[0];
+}
+
+async function windowSource(fs, saved, value, exec) {
+  const name = credentialSourcePath(fs.processPath(saved.target));
+  const jsonl = /\.(?:jsonl|ndjson)$/i.test(name);
+  if (isStructuredCredentialText(name) && !jsonl || typeof fs.streamText !== 'function') failure();
+  const wanted = new Set(value.lines.map(line => line.number));
+  const selected = new Map();
+  let pending = '', lineNumber = 0, bytes = 0, inPrivateKey = false;
+  const consume = () => {
+    lineNumber++;
+    const raw = pending; pending = '';
+    if (raw.includes('\0')) failure();
+    if (!jsonl && /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(raw)) inPrivateKey = true;
+    if (wanted.has(lineNumber)) {
+      bytes += Buffer.byteLength(raw);
+      if (bytes > MAX_WINDOW_BYTES) failure();
+      const safe = inPrivateKey ? raw.replace(/[^\s]/g, '*') : redactCredentialText(raw, jsonl ? 'session.jsonl' : name).text;
+      selected.set(lineNumber, { raw, safe });
+    }
+    if (!jsonl && /-----END [A-Z ]*PRIVATE KEY-----/.test(raw)) inPrivateKey = false;
+  };
+  for await (const chunk of await fs.streamText(saved.target, exec.signal)) {
+    exec.signal.throwIfAborted();
+    if (typeof chunk !== 'string') failure();
+    const pieces = chunk.split('\n');
+    for (let i = 0; i < pieces.length; i++) {
+      pending += pieces[i];
+      // Complete JSONL lines are bounded independently; the overall session
+      // may be arbitrarily large. A too-long selected line is withheld.
+      if (pending.length > MAX_SOURCE_BYTES) {
+        if (!jsonl || wanted.has(lineNumber + 1)) failure();
+        pending = pending.slice(0, MAX_SOURCE_BYTES);
+      }
+      if (i < pieces.length - 1) consume();
+    }
+  }
+  if (pending.length) consume();
+  if (lineNumber !== value.totalLines) failure();
+  await unchanged(fs, saved, exec);
+  return selected;
+}
+
+async function projectRead(fs, saved, result, exec) {
+  const value = result.value;
+  if (!value || !Array.isArray(value.lines) || typeof value.path !== 'string' || !Number.isInteger(value.totalLines)) failure();
+  let selected;
+  if (saved.info.size === undefined || saved.info.size > MAX_SOURCE_BYTES) selected = await windowSource(fs, saved, value, exec);
+  else {
+    const { source, sanitized } = await wholeSource(fs, saved, exec);
+    const raw = source.split('\n'), safe = sanitized.text.split('\n');
+    const total = source ? raw.length - Number(source.endsWith('\n')) : 0;
+    if (total !== value.totalLines) failure();
+    selected = new Map(value.lines.map(({ number }) => [number, { raw: raw[number - 1], safe: safe[number - 1] }]));
+  }
+  const lines = value.lines.map(({ number, text }) => {
+    const line = selected.get(number);
+    if (!line || typeof line.raw !== 'string' || typeof text !== 'string') failure();
+    return { number, text: projectLine(line.raw, line.safe, text) };
+  });
+  return fresh({ path: value.path, offset: value.offset, lines, totalLines: value.totalLines });
+}
+
+async function projectGrep(fs, result, exec) {
+  if (!Array.isArray(result.value?.matches)) failure();
+  const sources = new Map();
+  const matches = [];
+  for (const match of result.value.matches) {
+    exec.signal.throwIfAborted();
+    if (typeof match.path !== 'string' || !Number.isInteger(match.lineNumber) || typeof match.line !== 'string') failure();
+    let lines = sources.get(match.path);
+    if (!lines) {
+      try {
+        const saved = await resolveFile(fs, match.path, exec);
+        if (saved.info?.type !== 'file' || saved.info.size > MAX_SOURCE_BYTES || sources.size >= 64) failure();
+        const { source, sanitized } = await wholeSource(fs, saved, exec);
+        lines = { raw: source.split('\n'), safe: sanitized.text.split('\n') };
+      } catch { lines = { withheld: true }; }
+      sources.set(match.path, lines);
+    }
+    const raw = lines.raw?.[match.lineNumber - 1];
+    const coherent = typeof raw === 'string' && stripCR(raw) === match.line;
+    matches.push({ path: match.path, lineNumber: match.lineNumber,
+      line: !lines.withheld && coherent ? stripCR(lines.safe[match.lineNumber - 1]) : '[content withheld; use native read]' });
+  }
+  return fresh({ matches });
+}
+
+/** Native tool registrations and their filesystem provider are trusted host
+ * components. Bind global definitions so scope shadows/replacements cannot
+ * inherit the verified 0.2.0-rc.2 read/grep pipeline contract.
+ * Read has no body-owned raw persistence; grep spills only in post-execute.
+ * Shell jobs persist before around-return, so known secret inputs are refused
+ * BEFORE their body. This is not an OS sandbox for arbitrary scripts.
+ */
+export function createCredentialReads(ctx, lifetimeSignal) {
+  const owners = new Map();
+  const owner = exec => {
+    const current = ctx.tools?.get?.(exec.name);
+    if (!current) return false;
+    if (!owners.has(exec.name)) owners.set(exec.name, current);
+    return owners.get(exec.name) === current && ctx.tools.get(exec.name, exec.agent) === current;
+  };
+  async function shellCheck(fs, exec) {
+    const command = exec.arguments?.command;
+    if (typeof command !== 'string') return;
+    if (isSafeStaticExposure(analyzeShell(command))) return;
+    const values = new Set([...shellRefusals(command).values,
+      ...(command.match(/"[^"\r\n]+"|'[^'\r\n]+'|[^\s;&|<>]+/g) ?? []).map(value => value.replace(/^["']|["']$/g, ''))]);
+    let count = 0;
+    for (const path of values) {
+      if (isCredentialPath(path)) throw new Error('CREDENTIAL_PATH');
+      if (!isAbsolute(path) && !/^[A-Za-z]:[\\/]/.test(path)) continue;
+      if (++count > 32) throw new Error('CREDENTIAL_READ_UNAVAILABLE');
+      // Persistent shells may have a different cwd; only absolute operands
+      // have a provable target here. Relative/opaque commands stay reviewed.
+      let saved;
+      try { saved = await resolveFile(fs, path, exec); }
+      catch (error) { if (error.message === 'CREDENTIAL_PATH') throw error; continue; }
+      if (saved.info?.type !== 'file') continue;
+      try {
+        const { sanitized } = await wholeSource(fs, saved, exec);
+        if (sanitized.redacted) throw new Error('USE_SAFE_READ');
+      } catch (error) {
+        if (error.message === 'USE_SAFE_READ') throw error;
+        if (isStructuredCredentialText(path)) throw new Error('USE_SAFE_READ');
+      }
+    }
+  }
+  return { async execute(exec, next) {
+    if (lifetimeSignal) exec = { ...exec, signal: AbortSignal.any([exec.signal, lifetimeSignal]) };
+    const fs = typeof ctx.get === 'function' ? ctx.get('fs') : ctx.fs;
+    // Hosts without the FS seam still retain the lexical hard-risk policy;
+    // no filesystem projection or extra exposure is claimed for custom tools.
+    if (!fsAvailable(fs)) return next();
+    const fileTool = textRead(exec) || ['read_image', 'write', 'edit', 'str_replace_editor'].includes(exec.name);
+    const grep = exec.name === 'grep';
+    const shell = ['bash', 'pwsh', 'shell'].includes(exec.name);
+    if (!fileTool && !grep && !shell) return next();
+    try {
+      let saved;
+      const path = exec.arguments?.file_path ?? exec.arguments?.path;
+      if (fileTool && typeof path === 'string') {
+        const cwd = ['write', 'edit'].includes(exec.name)
+          ? ctx.sandboxPolicy?.resolve({ session: exec.agent?.session })?.workspaceRoot ?? cwdOf(exec)
+          : cwdOf(exec);
+        saved = await resolveFile(fs, path, exec, cwd);
+      }
+      if (saved && !textRead(exec) && exec.name !== 'read_image' && isMutationProtectedPath(fs.processPath(saved.target))) throw new Error('CREDENTIAL_PATH');
+      if (grep && typeof path === 'string') await resolveFile(fs, path, exec);
+      if (shell) await shellCheck(fs, exec);
+      if (textRead(exec) && saved?.info?.type === 'file' || grep) {
+        if (!owner(exec)) throw new Error('CREDENTIAL_READER_CHANGED');
+      }
+      if (textRead(exec) && exec.name === 'str_replace_editor' && saved?.info?.type === 'file') {
+        const { sanitized } = await wholeSource(fs, saved, exec);
+        if (sanitized.redacted) throw new Error('USE_SAFE_READ');
+      }
+      exec.signal.throwIfAborted();
+      const result = await next();
+      if (result?.isError) return result;
+      exec.signal.throwIfAborted();
+      if (exec.name === 'read' && saved?.info?.type === 'file') {
+        if (!owner(exec)) failure();
+        return await projectRead(fs, saved, result, exec);
+      }
+      if (grep) {
+        if (!owner(exec)) failure();
+        return await projectGrep(fs, result, exec);
+      }
+      if (exec.name === 'str_replace_editor' && textRead(exec) && saved) await unchanged(fs, saved, exec);
+      return result;
+    } catch (error) {
+      if (exec.signal.aborted) return errorResult('CANCELLED');
+      return errorResult(['CREDENTIAL_PATH', 'USE_SAFE_READ', 'CREDENTIAL_READER_CHANGED'].includes(error.message) ? error.message : 'CREDENTIAL_READ_UNAVAILABLE');
+    }
+  } };
+}