@navels/neal 0.2.0 → 0.3.1

package/dist/neal/prompts/specs.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 function field(key, source, required, description) {
     return { key, source, required, description };
 }
@@ -36,8 +37,7 @@ const PLAN_REVIEWER_CONTEXT = context('PlanReviewerPromptContext', [
     field('parentPlanDoc', 'prompt_argument', false, 'Path to the parent plan when reviewing a derived plan.'),
     field('derivedFromScopeNumber', 'orchestrator_state', false, 'Parent scope number when reviewing a derived plan.'),
     field('repositoryState', 'repository_state', true, 'Current repository context and directly referenced companion docs.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined plan document, parent plan, and review-history sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
 const SCOPE_CODER_CONTEXT = context('ScopeCoderPromptContext', [
     field('planDoc', 'prompt_argument', true, 'Path to the active execute-mode plan.'),
@@ -65,8 +65,7 @@ const SCOPE_REVIEWER_CONTEXT = context('ScopeReviewerPromptContext', [
     field('recentHistorySummary', 'review_history', true, 'Accepted-scope history for the active parent objective.'),
     field('reviewMarkdownPath', 'run_artifact', true, 'Review artifact that carries prior findings and coder responses.'),
     field('scratchDir', 'run_artifact', true, 'Run-local reviewer scratch directory for temporary verification artifacts.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined full diff, plan document, and review-history sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
 const COMPLETION_CODER_CONTEXT = context('CompletionCoderPromptContext', [
     field('planDoc', 'prompt_argument', true, 'Path to the execute-mode plan being evaluated for final completion.'),
@@ -79,18 +78,32 @@ const COMPLETION_REVIEWER_CONTEXT = context('CompletionReviewerPromptContext', [
     field('summary', 'review_history', true, 'Coder-authored whole-plan completion summary under review.'),
     field('scratchDir', 'run_artifact', true, 'Run-local final-completion reviewer scratch directory for temporary verification artifacts.'),
     field('repositoryState', 'repository_state', true, 'Current repository state used to judge whole-plan completion.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined aggregate diff (or evidence-gap statement) and plan-document sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
-const BLOCKED_ADJUDICATOR_CONTEXT = context('BlockedAdjudicatorPromptContext', [
+const CONSULTANT_CONTEXT = context('ConsultantPromptContext', [
     field('blockedReason', 'prompt_argument', true, 'Blocked reason reported by the stalled coder or reviewer turn.'),
-    field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context (plan content, open blocking findings, reviewer-round snapshots, or coder blocker plus changed files) the adjudicator judges entirely from.'),
+    field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context (plan content, open blocking findings, reviewer-round snapshots, or coder blocker plus changed files) the consultant judges entirely from.'),
 ]);
 export const PROMPT_SPECS = [
     {
         id: 'plan_author',
+        version: 3,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '2e5600ef64885419b574cc0a04b684dc93f3efcc9ede65e4cacc8951a220d5cd',
+            },
+            {
+                version: 2,
+                renderSha: 'a9ebcafa81fa0f60812adcb7c7b68f999a6c45c1c7fa7b7a20911031d6b0fd9e',
+            },
+            {
+                version: 3,
+                renderSha: '51943007b2a334ee0c92d8314616fb882e9cea7b410b05c5aeda668c7c9e04dc',
+            },
+        ],
         role: 'coder',
-        purpose: 'Author or revise Neal-executable plans without leaking planning-task scaffolding into final artifacts.',
+        purpose: 'Author or revise concise, human-reviewable Neal-executable plans at moderate-to-high-level implementation detail.',
         requiredContext: PLAN_AUTHOR_CONTEXT,
         schemaTarget: {
             kind: 'structured_json',
@@ -108,6 +121,8 @@ export const PROMPT_SPECS = [
         evaluationNotes: [
             'Render tests should assert the canonical Neal-executable execution-shape contract stays present.',
             'Fixture cases should cover single-scope vs multi-scope decisions and cleanup of planning-only scaffolding.',
+            'Prompt tests should preserve repository grounding while rejecting exhaustive implementation inventories.',
+            'Planner and response prompts should narrow self-imposed global verification guarantees unless they are necessary for the requested change to be correct.',
         ],
         firstMigrationPriority: 1,
         currentHome: 'src/neal/prompts',
@@ -160,8 +175,23 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'plan_reviewer',
+        version: 3,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'c84e630d1463590eda463726a0529dab6277f1980a2c9c586a3fe3673e44d2ee',
+            },
+            {
+                version: 2,
+                renderSha: '43a6f77d767bb5a010203f37b2c1ac980f0d7c6e1eb104f038c33afcea97c658',
+            },
+            {
+                version: 3,
+                renderSha: 'fa0309ed0e394c690dfc3135da3c98a74dd5413ccb754fefa100171bf35b72b6',
+            },
+        ],
         role: 'reviewer',
-        purpose: 'Review Neal-executable plans for execution-shape correctness, verification concreteness, and resume safety.',
+        purpose: 'Review human-reviewable Neal-executable plans for material approach, scope, verification, and resume-safety defects.',
         requiredContext: PLAN_REVIEWER_CONTEXT,
         schemaTarget: {
             kind: 'structured_json',
@@ -183,7 +213,8 @@ export const PROMPT_SPECS = [
         providerVariants: SHARED_PROVIDER_VARIANTS,
         evaluationNotes: [
             'Render tests should assert the reviewer prompt requires executionShape confirmation.',
-            'Render tests should assert shared adversarial plan-readiness posture and verification skepticism without adding implementation diff-review instructions.',
+            'Render tests should assert independent material plan review without adding implementation diff-review instructions or exhaustive detail requirements.',
+            'Reviewer tests should distinguish requested-change correctness from incomplete enforcement of broader guarantees introduced by the plan.',
             'Fixture cases should cover ordinary plans and derived plans.',
         ],
         firstMigrationPriority: 1,
@@ -206,8 +237,7 @@ export const PROMPT_SPECS = [
                         field('planDoc', 'prompt_argument', true, 'Path to the plan artifact under review.'),
                         field('round', 'orchestrator_state', true, 'Plan-review round number.'),
                         field('reviewMarkdownPath', 'run_artifact', true, 'Review history artifact path.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -230,8 +260,7 @@ export const PROMPT_SPECS = [
                         field('planDoc', 'prompt_argument', true, 'Path to the derived plan artifact under review.'),
                         field('parentPlanDoc', 'prompt_argument', false, 'Path to the parent plan artifact.'),
                         field('derivedFromScopeNumber', 'orchestrator_state', false, 'Parent scope number that the derived plan replaces.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined derived-plan/parent-plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -245,6 +274,13 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_coder',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'c579d65db51be90fa81dbe3b7dd260083bc4960cc4cba32ccf2cd802d19703bc',
+            },
+        ],
         role: 'coder',
         purpose: 'Execute exactly one bounded implementation scope and respond to in-scope review feedback without starting new scopes.',
         requiredContext: SCOPE_CODER_CONTEXT,
@@ -347,6 +383,17 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_reviewer',
+        version: 2,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '38a19da2b70dc10f6f4d8c4b955ece084bbe6e1291151de9c557dca194411386',
+            },
+            {
+                version: 2,
+                renderSha: '431a75ad341a531535606af607187239a31d12cf921575eb17774b317ad639a0',
+            },
+        ],
         role: 'reviewer',
         purpose: 'Review execute-scope results for correctness, verification coverage, and meaningful progress toward the active parent objective.',
         requiredContext: SCOPE_REVIEWER_CONTEXT,
@@ -400,8 +447,7 @@ export const PROMPT_SPECS = [
                         field('reviewMarkdownPath', 'run_artifact', true, 'Review history artifact path.'),
                         field('parentScopeLabel', 'orchestrator_state', true, 'Active parent objective label.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for reviewer verification artifacts.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined diff/plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -436,6 +482,13 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_coder',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'f88b43d206de28212ad7f6f3ae84576718934b0a5e36953e35afee89c4d7ce5e',
+            },
+        ],
         role: 'coder',
         purpose: 'Summarize whole-plan completion state in compact structured JSON.',
         requiredContext: COMPLETION_CODER_CONTEXT,
@@ -489,6 +542,17 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_reviewer',
+        version: 2,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'e5d104d46899f01cf69db9d2e6d109aa32d0faf645d6d908aae443558900a131',
+            },
+            {
+                version: 2,
+                renderSha: 'cc06cea4a8de6366f07a6943718fc1ae219e4c9092a5cf52542fa9de0caa02da',
+            },
+        ],
         role: 'reviewer',
         purpose: 'Judge whole-plan completion and decide whether Neal should accept completion, continue execution, or block for operator input.',
         requiredContext: COMPLETION_REVIEWER_CONTEXT,
@@ -533,8 +597,7 @@ export const PROMPT_SPECS = [
                         field('packet', 'orchestrator_state', true, 'Whole-plan completion packet.'),
                         field('summary', 'review_history', true, 'Coder-authored completion summary.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for final-completion reviewer artifacts.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined aggregate-diff/plan context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -547,60 +610,144 @@ export const PROMPT_SPECS = [
         ],
     },
     {
-        id: 'blocked_adjudicator',
+        id: 'consultant',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '42e41552be1e8cceb0596a26f09892e13cc31adf07e58479d939d289c8b469e3',
+            },
+        ],
         role: 'reviewer',
         purpose: 'Triage a blocked Neal run entirely from Neal-inlined context and decide whether the block is an in-scope recoverable misunderstanding or a genuine wall that must escalate to a human.',
-        requiredContext: BLOCKED_ADJUDICATOR_CONTEXT,
+        requiredContext: CONSULTANT_CONTEXT,
         schemaTarget: {
             kind: 'structured_json',
-            schemaBuilder: 'buildBlockedAdjudicatorSchema',
-            parser: 'validateBlockedAdjudicatorVerdictPayload',
+            schemaBuilder: 'buildConsultantSchema',
+            parser: 'validateConsultantVerdictPayload',
             providerSurface: 'neal_json_block_protocol',
         },
         baseInstructions: {
             kind: 'builder',
             modulePath: 'src/neal/agents/prompts.ts',
-            exportName: 'buildBlockedAdjudicatorPrompt',
-            inputShape: context('BuildBlockedAdjudicatorPromptArgs', [
+            exportName: 'buildConsultantPrompt',
+            inputShape: context('BuildConsultantPromptArgs', [
                 field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
                 field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
             ]),
         },
         providerVariants: SHARED_PROVIDER_VARIANTS,
         evaluationNotes: [
-            'Render tests should assert the adjudicator judges entirely from inlined context and its static instructions carry no repository-access phrasing.',
+            'Render tests should assert the consultant judges entirely from inlined context and its static instructions carry no repository-access phrasing.',
             'A golden render test pins the exact prompt bytes, including the ALL-CAPS emphasis lines.',
         ],
         firstMigrationPriority: 3,
         currentHome: 'mixed',
         ownershipNotes: [
-            'Prompt spec owns the adjudicator instructions and required context only; anti-thrash guarding, recovery routing, and verdict persistence stay in src/neal/adjudicator/ outside the prompt-spec library.',
+            'Prompt spec owns the consultant instructions and required context only; anti-thrash guarding, recovery routing, and verdict persistence stay in src/neal/adjudicator/ outside the prompt-spec library.',
         ],
         variants: [
             {
                 kind: 'primary',
                 status: 'adjacent',
                 description: 'Read-only blocked-run adjudication round.',
-                currentRoundEntrypoints: ['runBlockedAdjudicatorRound'],
+                currentRoundEntrypoints: ['runConsultantRound'],
                 baseInstructions: {
                     kind: 'builder',
                     modulePath: 'src/neal/agents/prompts.ts',
-                    exportName: 'buildBlockedAdjudicatorPrompt',
-                    inputShape: context('BuildBlockedAdjudicatorPromptArgs', [
+                    exportName: 'buildConsultantPrompt',
+                    inputShape: context('BuildConsultantPromptArgs', [
                         field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
                         field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
                     ]),
                 },
                 schemaTarget: {
                     kind: 'structured_json',
-                    schemaBuilder: 'buildBlockedAdjudicatorSchema',
-                    parser: 'validateBlockedAdjudicatorVerdictPayload',
+                    schemaBuilder: 'buildConsultantSchema',
+                    parser: 'validateConsultantVerdictPayload',
                     providerSurface: 'neal_json_block_protocol',
                 },
             },
         ],
     },
 ];
+// SHA-256 of `text` as lowercase hex. Used to pin the render matrix (via the
+// changelog `renderSha`) and, in the render-integrity test, the builder-module
+// source tripwire.
+export function sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+// Canonical, order-independent serialization of a render matrix. Each cell is a
+// `{ key, render }` pair; cells are sorted by `key` and joined as
+// `=== <key> ===\n<render>\n` blocks so the output is deterministic regardless
+// of generation order and stays human-diffable in the versioned goldens.
+export function serializeRenderMatrix(cells) {
+    return [...cells]
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map((cell) => `=== ${cell.key} ===\n${cell.render}\n`)
+        .join('');
+}
+// Structural validation of a spec's integer version and sha-anchored changelog.
+// This is format/shape enforcement only; it does not compare the recorded
+// `renderSha` against any live render (that is verifyRenderVersionContract's
+// job) so it can run cheaply at module load for every spec.
+export function validatePromptSpecVersioning(spec) {
+    const { id, version, changelog } = spec;
+    if (!Number.isSafeInteger(version) || version < 1) {
+        throw new Error(`Prompt spec ${id} version must be a safe integer >= 1, received ${String(version)}`);
+    }
+    if (changelog.length === 0) {
+        throw new Error(`Prompt spec ${id} changelog must not be empty`);
+    }
+    let previousVersion = 0;
+    for (const entry of changelog) {
+        if (!Number.isSafeInteger(entry.version) || entry.version < 1) {
+            throw new Error(`Prompt spec ${id} changelog entry version must be a safe integer >= 1, received ${String(entry.version)}`);
+        }
+        if (entry.version <= previousVersion) {
+            throw new Error(`Prompt spec ${id} changelog entry versions must be strictly increasing, received ${entry.version} after ${previousVersion}`);
+        }
+        previousVersion = entry.version;
+        if (!/^[0-9a-f]{64}$/.test(entry.renderSha)) {
+            throw new Error(`Prompt spec ${id} changelog entry renderSha must be 64-char lowercase hex, received ${entry.renderSha}`);
+        }
+    }
+    const last = changelog[changelog.length - 1];
+    if (last.version !== version) {
+        throw new Error(`Prompt spec ${id} last changelog entry version ${last.version} must equal spec version ${version}`);
+    }
+}
+// Internal-consistency and change-visibility contract over a spec's live render
+// matrix and its versioned goldens. Throws when the last changelog entry does
+// not match the spec version, when the live matrix sha does not match the last
+// recorded `renderSha`, or when any changelog entry's golden is missing or does
+// not hash to its recorded `renderSha`. This is not tamper evidence: an author
+// who edits the live render, the golden, and the recorded sha together produces
+// an internally consistent state that passes here; catching that coordinated
+// same-version repin is the documented review/CI append-only rule, not this
+// unit contract.
+export function verifyRenderVersionContract(args) {
+    const { specId, version, changelog, liveMatrix, readGolden } = args;
+    const last = changelog[changelog.length - 1];
+    if (!last || last.version !== version) {
+        throw new Error(`Prompt spec ${specId} last changelog entry version ${String(last?.version)} must equal spec version ${version}`);
+    }
+    const liveSha = sha256Hex(liveMatrix);
+    if (liveSha !== last.renderSha) {
+        throw new Error(`Prompt spec ${specId} live render matrix sha ${liveSha} does not match recorded renderSha ${last.renderSha} for version ${version}. ` +
+            'The render changed: re-audit the builder axes, bump the version, add a new versioned golden, and re-pin the recorded renderSha.');
+    }
+    for (const entry of changelog) {
+        const golden = readGolden(entry.version);
+        if (golden === undefined) {
+            throw new Error(`Prompt spec ${specId} is missing the versioned golden for version ${entry.version}`);
+        }
+        const goldenSha = sha256Hex(golden);
+        if (goldenSha !== entry.renderSha) {
+            throw new Error(`Prompt spec ${specId} golden for version ${entry.version} sha ${goldenSha} does not match recorded renderSha ${entry.renderSha}`);
+        }
+    }
+}
 function getContractFieldKeys(contract) {
     return new Set(contract.fields.map((field) => field.key));
 }
@@ -613,6 +760,7 @@ function validateBuilderInputShape(spec, builder, label) {
 }
 function validatePromptSpecContracts(specs) {
     for (const spec of specs) {
+        validatePromptSpecVersioning(spec);
         validateBuilderInputShape(spec, spec.baseInstructions, 'baseInstructions');
         for (const variant of spec.variants) {
             validateBuilderInputShape(spec, variant.baseInstructions, `variant ${variant.kind}/${variant.baseInstructions.exportName}`);

package/dist/neal/providers/agent-settings-isolation.js

@@ -0,0 +1,35 @@
+/**
+ * Whether neal-driven agent runs should be isolated from the operator's
+ * interactive agent config.
+ *
+ * The native adapters drive the Codex and Claude SDKs, which by default load
+ * the operator's own config — the Codex `notify` hook, the Claude
+ * `Stop`/`Notification` hooks, `CLAUDE.md`, permissions. In normal use
+ * (pipeline, local `neal go`) that is correct: it is the operator's machine
+ * and their configured agent behavior, so neal honors it.
+ *
+ * The one exception is the compat qualification harness (`neal compat`, which
+ * `scripts/qualify-sdk.sh` drives). It is a hermetic, repeatable capability
+ * probe that runs the whole planner/coder/reviewer matrix — many turns — and
+ * must not fire the operator's per-turn notifier hooks or let ambient config
+ * skew the verdict. So `runCompat` turns isolation ON for its process, and the
+ * native adapters read it here.
+ *
+ * A process-level env flag (matching NEAL_STOP_AFTER_CURRENT_SCOPE_FILE /
+ * NEAL_GUIDANCE_DIR) rather than a threaded option, because compat drives the
+ * adapters through the full orchestrator, and the flag would otherwise have to
+ * cross every layer between the command and adapter construction.
+ */
+const ISOLATION_ENV_FLAG = 'NEAL_ISOLATE_AGENT_SETTINGS';
+export function enableAgentSettingsIsolation() {
+    process.env[ISOLATION_ENV_FLAG] = '1';
+}
+// Symmetric off switch. Production only ever enables (compat, once), but tests
+// that exercise the isolated path need a clean teardown so the process-level
+// flag does not leak into sibling tests.
+export function disableAgentSettingsIsolation() {
+    delete process.env[ISOLATION_ENV_FLAG];
+}
+export function agentSettingsIsolated() {
+    return process.env[ISOLATION_ENV_FLAG] === '1';
+}

package/dist/neal/providers/anthropic-claude.js

@@ -2,6 +2,8 @@ import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { buildStructuredJsonPrompt, runStructuredJsonProtocol, runStructuredJsonRepairLoop, validateStructuredJsonPayload, } from '../agents/structured-json.js';
+import { agentSettingsIsolated } from './agent-settings-isolation.js';
+import { agentSubprocessEnv } from './git-config-isolation.js';
 import { NealProviderError } from './types.js';
 const ANTHROPIC_CLAUDE_PROVIDER_ID = 'anthropic-claude';
 const requireFromProvider = createRequire(import.meta.url);
@@ -57,7 +59,7 @@ class ClaudeInactivityTimeoutError extends Error {
 }
 // In-round transient (`api_error`) retries back off exponentially: 500 ms
 // base, doubling per retry, capped at 5 s — the same schedule as the
-// generic-agentic adapter. `sleep` is injectable through the run functions so
+// openai-compatible adapter. `sleep` is injectable through the run functions so
 // tests observe the delays without wall-clock waiting.
 const API_RETRY_BASE_DELAY_MS = 500;
 const API_RETRY_MAX_DELAY_MS = 5_000;
@@ -602,11 +604,26 @@ function deriveClaudeAbortController(signal) {
 function buildClaudeCoreQueryOptions(spec) {
     return {
         cwd: spec.cwd,
+        // Full environment plus the git-config isolation overrides: Claude's Bash
+        // tool must not be able to write the operator's real global gitconfig.
+        // See git-config-isolation.ts.
+        env: agentSubprocessEnv(),
         ...(spec.abortController ? { abortController: spec.abortController } : {}),
         ...(spec.model ? { model: spec.model } : {}),
         ...(spec.effort ? { effort: spec.effort } : {}),
         tools: spec.tools,
         ...(spec.hooks ? { hooks: spec.hooks } : {}),
+        // Under compat qualification only, run Claude in the SDK's isolation mode
+        // (load no filesystem settings). Left unset, the SDK loads ~/.claude and any
+        // repo .claude by default, pulling in the operator's interactive config —
+        // permissions, statusline, CLAUDE.md, and the Stop / Notification hooks that
+        // fire a desktop notifier on every turn. compat runs the whole role matrix,
+        // so those hooks would spam one notification per turn; isolating keeps the
+        // capability probe quiet and hermetic. Normal neal runs (pipeline, local
+        // `neal go`) honor the operator's config — it's their machine. neal's own
+        // hooks (the coder write-path guard passed programmatically above) are
+        // unaffected either way. See agent-settings-isolation.ts.
+        ...(agentSettingsIsolated() ? { settingSources: [] } : {}),
         permissionMode: 'bypassPermissions',
         allowDangerouslySkipPermissions: true,
         ...(spec.resumeHandle ? { resume: spec.resumeHandle } : {}),

package/dist/neal/providers/detection.js

@@ -92,10 +92,9 @@ export function detectBuiltInProviders(options = {}) {
         cwd: options.cwd ?? process.cwd(),
         resolveOpenAICompatibleSettings: options.resolveOpenAICompatibleSettings ?? ((cwd) => getOpenAICompatibleSettings(cwd, env)),
     };
-    // generic-agentic reuses the openai-compatible settings surface
-    // (providers.openai_compatible + env fallbacks), so both providers share
-    // one resolved-settings check. Memoized so the settings resolver still
-    // runs at most once per detection pass.
+    // openai-compatible resolves from the shared settings surface
+    // (providers.openai_compatible + env fallbacks). Memoized so the settings
+    // resolver still runs at most once per detection pass.
     let sharedOpenAICompatibleDetection;
     const detectFromSharedOpenAICompatibleSettings = () => {
         sharedOpenAICompatibleDetection ??= detectOpenAICompatible(resolvedOptions);
@@ -119,9 +118,6 @@ export function detectBuiltInProviders(options = {}) {
             case 'openai-compatible':
                 detection = detectFromSharedOpenAICompatibleSettings();
                 break;
-            case 'generic-agentic':
-                detection = detectFromSharedOpenAICompatibleSettings();
-                break;
             default:
                 detection = {
                     runtimeAvailable: false,

package/dist/neal/providers/git-config-isolation.js

@@ -0,0 +1,83 @@
+/**
+ * Git-config isolation for agent subprocesses.
+ *
+ * Agents (the coder especially) run shell commands with the operator's real
+ * environment, so `git config --global ...` writes the operator's actual
+ * `~/.gitconfig`. That has happened twice: a coder model hit git identity
+ * friction inside a throwaway worktree and "fixed" it globally, clobbering the
+ * operator's `[user]` block and breaking commit signing on their machine
+ * (issue #54).
+ *
+ * The defense is environmental, not behavioral: every agent subprocess gets
+ * `GIT_CONFIG_GLOBAL` pointed at a neal-owned scratch copy of the operator's
+ * global config, and `GIT_CONFIG_SYSTEM` pointed at the null device. Reads
+ * behave identically (the copy has the operator's settings, and `includeIf`
+ * paths inside it still resolve), agent commits keep the operator's identity
+ * and signing config, and a `--global` write succeeds from the agent's point
+ * of view — it just lands in the scratch copy instead of the operator's file.
+ *
+ * One scratch copy per process, created lazily: adapters are constructed per
+ * round, and the copy must be stable across rounds so an agent's own global
+ * writes persist for the life of the run.
+ */
+import { copyFileSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { devNull, homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+let cached = null;
+/** Candidate sources for the operator's global config, in git's own precedence. */
+function globalConfigSourcePaths() {
+    const fromEnv = process.env.GIT_CONFIG_GLOBAL;
+    if (fromEnv !== undefined && fromEnv !== '') {
+        return [fromEnv];
+    }
+    const xdgBase = process.env.XDG_CONFIG_HOME !== undefined && process.env.XDG_CONFIG_HOME !== ''
+        ? process.env.XDG_CONFIG_HOME
+        : join(homedir(), '.config');
+    // ~/.gitconfig wins over the XDG file when both exist, matching git.
+    return [join(homedir(), '.gitconfig'), join(xdgBase, 'git', 'config')];
+}
+export function gitConfigIsolationEnv() {
+    if (cached !== null) {
+        return cached;
+    }
+    const dir = mkdtempSync(join(tmpdir(), 'neal-git-config-'));
+    const scratch = join(dir, 'gitconfig');
+    let copied = false;
+    for (const source of globalConfigSourcePaths()) {
+        try {
+            copyFileSync(source, scratch);
+            copied = true;
+            break;
+        }
+        catch {
+            // Missing source — try the next candidate.
+        }
+    }
+    if (!copied) {
+        // No global config on this machine; give agents an empty one to write to.
+        writeFileSync(scratch, '');
+    }
+    cached = { GIT_CONFIG_GLOBAL: scratch, GIT_CONFIG_SYSTEM: devNull };
+    return cached;
+}
+/**
+ * The full environment for an agent subprocess whose SDK replaces (rather
+ * than merges with) the parent environment when `env` is provided.
+ * `undefined` entries are dropped because those SDKs type env as
+ * `Record<string, string>`.
+ */
+export function agentSubprocessEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    return { ...env, ...gitConfigIsolationEnv() };
+}
+// Test-only: drop the process-level cache so a test can point the source at a
+// fixture file. Mirrors disableAgentSettingsIsolation's teardown role.
+export function resetGitConfigIsolationForTests() {
+    cached = null;
+}

package/dist/neal/providers/openai-codex.js

@@ -1,7 +1,9 @@
 import { Codex } from '@openai/codex-sdk';
 import { runStructuredJsonProtocol } from '../agents/structured-json.js';
+import { agentSettingsIsolated } from './agent-settings-isolation.js';
+import { agentSubprocessEnv } from './git-config-isolation.js';
 import { resolveRateCost } from './pricing.js';
-import { NealProviderError } from './types.js';
+import { isContentSafetyRefusalMessage, NealProviderError } from './types.js';
 const OPENAI_CODEX_PROVIDER_ID = 'openai-codex';
 class CodexInactivityTimeoutError extends Error {
     constructor(timeoutMs) {
@@ -11,7 +13,7 @@ class CodexInactivityTimeoutError extends Error {
 }
 // In-round transient (`api_error`) retries back off exponentially: 500 ms
 // base, doubling per retry, capped at 5 s — the same schedule as the
-// generic-agentic adapter. `sleep` is injectable through the adapter options
+// openai-compatible adapter. `sleep` is injectable through the adapter options
 // so tests observe the delays without wall-clock waiting.
 const API_RETRY_BASE_DELAY_MS = 500;
 const API_RETRY_MAX_DELAY_MS = 5_000;
@@ -68,6 +70,12 @@ function inferCodexErrorKind(error, message, fallback) {
     if (error instanceof CodexInactivityTimeoutError || /\btimed out after\b/i.test(message)) {
         return 'timeout';
     }
+    // Placed before the permission check so a content-safety refusal is never
+    // misread as permission_denied when OpenAI phrases it with the word
+    // "authorized".
+    if (isContentSafetyRefusalMessage(message)) {
+        return 'content_refused';
+    }
     if (text.includes('permission') || text.includes('denied') || text.includes('forbidden') || text.includes('not authorized')) {
         return 'permission_denied';
     }
@@ -229,7 +237,21 @@ function buildCodexThreadOptions(args) {
     };
 }
 function createCodexThread(args) {
-    const codex = new Codex();
+    // Under compat qualification only, isolate from the user's interactive
+    // `notify` hook in ~/.codex/config.toml: compat runs the whole role matrix
+    // through Codex, and left alone the hook fires a desktop notification per
+    // planner/coder/reviewer turn. Override `notify` to empty (a `--config
+    // notify=[]` pass to the CLI) for that case. Normal neal runs (pipeline,
+    // local `neal go`) honor the user's config. See agent-settings-isolation.ts.
+    //
+    // `env` is always passed (the SDK stops inheriting process.env once env is
+    // provided, so it is the full environment plus the git-config isolation
+    // overrides): the Codex CLI and every shell it runs must not be able to
+    // write the operator's real global gitconfig. See git-config-isolation.ts.
+    const env = agentSubprocessEnv();
+    const codex = agentSettingsIsolated()
+        ? new Codex({ config: { notify: [] }, env })
+        : new Codex({ env });
     const threadOptions = buildCodexThreadOptions({
         cwd: args.cwd,
         model: args.model,