agentic-orchestrator 0.1.28 → 0.2.0

package/docs/superpowers/plans/2026-03-16-provider-cli-config.md

@@ -0,0 +1,743 @@
+# Provider CLI Config Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move user-profile-specific CLI flags (MCP server disable flags) out of hardcoded provider defaults and into a configurable `provider_cli_config` block in `agents.yaml`.
+
+**Architecture:** Add a `provider_cli_config` key to `agents.yaml` under `runtime`. A new `generateProviderCliExtraArgs()` helper in `provider-defaults.ts` translates named config options (e.g. `disable_mcp_servers`, `no_mcp`) into their CLI flag equivalents. These flags are stored as `cli_extra_args` on `ProviderSelection` and appended to every resolved command template in `cli-worker-provider.ts` and `providers.ts`. The hardcoded MCP server names are removed from `CODEX_DISABLE_MCP_FLAGS`.
+
+**Tech Stack:** TypeScript, Vitest, AJV (JSON Schema), YAML config
+
+---
+
+## Chunk 1: Core logic
+
+### Task 1: Clean `CODEX_DISABLE_MCP_FLAGS` and add `generateProviderCliExtraArgs`
+
+**Files:**
+
+- Modify: `apps/control-plane/src/providers/provider-defaults.ts`
+- Test: `apps/control-plane/test/worker-provider-adapters.spec.ts` (existing test will be updated in Task 5)
+
+- [ ] **Step 1: Write failing test for `generateProviderCliExtraArgs`**
+
+Add to a new `describe('generateProviderCliExtraArgs')` block in `apps/control-plane/test/providers.spec.ts`:
+
+```typescript
+import { generateProviderCliExtraArgs } from '../src/providers/provider-defaults.js';
+
+describe('generateProviderCliExtraArgs', () => {
+  it('GIVEN_no_config_WHEN_called_THEN_returns_empty_array', () => {
+    expect(generateProviderCliExtraArgs('codex', null)).toEqual([]);
+    expect(generateProviderCliExtraArgs('codex', undefined)).toEqual([]);
+    expect(generateProviderCliExtraArgs('codex', {})).toEqual([]);
+  });
+
+  it('GIVEN_codex_disable_mcp_servers_WHEN_called_THEN_returns_c_flags', () => {
+    const config = { codex: { disable_mcp_servers: ['context7', 'my-tool'] } };
+    expect(generateProviderCliExtraArgs('codex', config)).toEqual([
+      '-c',
+      'mcp_servers.context7.enabled=false',
+      '-c',
+      'mcp_servers.my-tool.enabled=false',
+    ]);
+  });
+
+  it('GIVEN_codex_empty_disable_list_WHEN_called_THEN_returns_empty_array', () => {
+    const config = { codex: { disable_mcp_servers: [] } };
+    expect(generateProviderCliExtraArgs('codex', config)).toEqual([]);
+  });
+
+  it('GIVEN_claude_no_mcp_true_WHEN_called_THEN_returns_no_mcp_flag', () => {
+    const config = { claude: { no_mcp: true } };
+    expect(generateProviderCliExtraArgs('claude', config)).toEqual(['--no-mcp']);
+  });
+
+  it('GIVEN_claude_no_mcp_false_WHEN_called_THEN_returns_empty_array', () => {
+    const config = { claude: { no_mcp: false } };
+    expect(generateProviderCliExtraArgs('claude', config)).toEqual([]);
+  });
+
+  it('GIVEN_config_for_other_provider_WHEN_called_for_codex_THEN_returns_empty_array', () => {
+    const config = { claude: { no_mcp: true } };
+    expect(generateProviderCliExtraArgs('codex', config)).toEqual([]);
+  });
+
+  it('GIVEN_non_string_entries_in_disable_list_WHEN_called_THEN_skips_invalid_entries', () => {
+    const config = { codex: { disable_mcp_servers: ['valid', 42, null, ''] } };
+    expect(
+      generateProviderCliExtraArgs('codex', config as unknown as Record<string, unknown>),
+    ).toEqual(['-c', 'mcp_servers.valid.enabled=false']);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+npx vitest run apps/control-plane/test/providers.spec.ts -t "generateProviderCliExtraArgs"
+```
+
+Expected: FAIL — `generateProviderCliExtraArgs` not exported.
+
+- [ ] **Step 3: Implement `generateProviderCliExtraArgs` and clean `CODEX_DISABLE_MCP_FLAGS`**
+
+Replace the contents of `apps/control-plane/src/providers/provider-defaults.ts`:
+
+```typescript
+export interface ProviderCommandTemplate {
+  command: string;
+  args: string[];
+}
+
+export interface ProviderCliDefaults {
+  run?: ProviderCommandTemplate;
+  attach?: ProviderCommandTemplate;
+  send?: ProviderCommandTemplate;
+}
+
+const CODEX_BASE_FLAGS = ['--disable', 'apps'];
+
+/**
+ * Translates a `provider_cli_config` block from agents.yaml into CLI flag arrays.
+ * Called during provider selection resolution; result is stored in ProviderSelection.cli_extra_args.
+ *
+ * Supported options:
+ *   codex.disable_mcp_servers: string[]  → -c mcp_servers.<name>.enabled=false per entry
+ *   claude.no_mcp: boolean               → --no-mcp
+ */
+export function generateProviderCliExtraArgs(
+  provider: string,
+  cliConfig: Record<string, unknown> | null | undefined,
+): string[] {
+  if (!cliConfig) {
+    return [];
+  }
+
+  const providerConfig = cliConfig[provider];
+  if (
+    typeof providerConfig !== 'object' ||
+    providerConfig === null ||
+    Array.isArray(providerConfig)
+  ) {
+    return [];
+  }
+
+  const config = providerConfig as Record<string, unknown>;
+  const result: string[] = [];
+
+  if (provider === 'codex') {
+    const servers = config['disable_mcp_servers'];
+    if (Array.isArray(servers)) {
+      for (const server of servers) {
+        if (typeof server === 'string' && server.length > 0) {
+          result.push('-c', `mcp_servers.${server}.enabled=false`);
+        }
+      }
+    }
+  }
+
+  if (provider === 'claude') {
+    if (config['no_mcp'] === true) {
+      result.push('--no-mcp');
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Canonical CLI command templates for each built-in provider.
+ * All provider-specific args are defined here — update this single object
+ * when a provider's CLI interface changes.
+ *
+ * Template placeholders: {session_id}, {prompt}, {message}, {feature_id}, {role}
+ * User-specific flags (e.g. MCP server disables) belong in agents.yaml provider_cli_config,
+ * not here.
+ */
+export const PROVIDER_CLI_DEFAULTS: Record<string, ProviderCliDefaults> = {
+  codex: {
+    run: {
+      command: 'codex',
+      args: [
+        'exec',
+        '--dangerously-bypass-approvals-and-sandbox',
+        '--output-last-message',
+        '{output_last_message_path}',
+        ...CODEX_BASE_FLAGS,
+      ],
+    },
+    attach: { command: 'codex', args: ['resume', '--last', ...CODEX_BASE_FLAGS] },
+    send: {
+      command: 'codex',
+      args: [
+        'exec',
+        '--dangerously-bypass-approvals-and-sandbox',
+        ...CODEX_BASE_FLAGS,
+        '{message}',
+      ],
+    },
+  },
+  claude: {
+    run: {
+      command: 'claude',
+      args: ['--dangerously-skip-permissions', '--print', '--output-format', 'text'],
+    },
+    attach: { command: 'claude', args: ['--dangerously-skip-permissions'] },
+    send: {
+      command: 'claude',
+      args: ['--dangerously-skip-permissions', '--print', '--output-format', 'text', '{message}'],
+    },
+  },
+  'kiro-cli': {
+    run: {
+      command: 'kiro-cli',
+      args: ['chat', '--session', '{session_id}', '--message', '{prompt}'],
+    },
+  },
+  copilot: {
+    run: {
+      command: 'copilot',
+      args: ['-p', '{prompt}', '--allow-all', '--resume', '{session_id}'],
+    },
+    attach: { command: 'copilot', args: ['--resume', '{session_id}', '--allow-all'] },
+    send: {
+      command: 'copilot',
+      args: ['-p', '{message}', '--allow-all', '--resume', '{session_id}'],
+    },
+  },
+};
+```
+
+- [ ] **Step 4: Run test to confirm it passes**
+
+```bash
+npx vitest run apps/control-plane/test/providers.spec.ts -t "generateProviderCliExtraArgs"
+```
+
+Expected: all 7 new tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/control-plane/src/providers/provider-defaults.ts apps/control-plane/test/providers.spec.ts
+git commit -m "feat: add generateProviderCliExtraArgs helper; remove hardcoded MCP server names from CODEX_BASE_FLAGS"
+```
+
+---
+
+### Task 2: Add `cli_extra_args` to `ProviderSelection` and populate in `resolveProviderSelection`
+
+**Files:**
+
+- Modify: `apps/control-plane/src/providers/providers.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Add to `apps/control-plane/test/providers.spec.ts` in the `resolveProviderSelection` describe block:
+
+```typescript
+it('GIVEN_provider_cli_config_with_codex_servers_WHEN_resolving_codex_selection_THEN_cli_extra_args_populated', () => {
+  const result = resolveProviderSelection({
+    cli: {},
+    env: {},
+    agentsConfig: {
+      runtime: {
+        default_provider: 'codex',
+        provider_cli_config: {
+          codex: { disable_mcp_servers: ['context7', 'my-server'] },
+        },
+      },
+    },
+  });
+  expect(result.cli_extra_args).toEqual([
+    '-c',
+    'mcp_servers.context7.enabled=false',
+    '-c',
+    'mcp_servers.my-server.enabled=false',
+  ]);
+});
+
+it('GIVEN_provider_cli_config_with_claude_no_mcp_WHEN_resolving_claude_selection_THEN_cli_extra_args_populated', () => {
+  const result = resolveProviderSelection({
+    cli: {},
+    env: {},
+    agentsConfig: {
+      runtime: {
+        default_provider: 'claude',
+        provider_cli_config: {
+          claude: { no_mcp: true },
+        },
+      },
+    },
+  });
+  expect(result.cli_extra_args).toEqual(['--no-mcp']);
+});
+
+it('GIVEN_no_provider_cli_config_WHEN_resolving_selection_THEN_cli_extra_args_is_undefined', () => {
+  const result = resolveProviderSelection({
+    cli: {},
+    env: {},
+    agentsConfig: { runtime: { default_provider: 'codex' } },
+  });
+  expect(result.cli_extra_args).toBeUndefined();
+});
+```
+
+- [ ] **Step 2: Run test to confirm it fails**
+
+```bash
+npx vitest run apps/control-plane/test/providers.spec.ts -t "provider_cli_config"
+```
+
+Expected: FAIL — `cli_extra_args` is not on `ProviderSelection`.
+
+- [ ] **Step 3: Update `ProviderSelection` interface and `resolveProviderSelection`**
+
+In `apps/control-plane/src/providers/providers.ts`:
+
+1. Add `cli_extra_args?: string[]` to the `ProviderSelection` interface:
+
+```typescript
+export interface ProviderSelection {
+  provider: string;
+  model: string;
+  provider_config_env: string | null;
+  provider_config_ref: string | null;
+  agent_config?: Record<string, unknown> | null;
+  cli_extra_args?: string[];
+}
+```
+
+2. Add `provider_cli_config?: Record<string, unknown>` to `ResolveSelectionInput.agentsConfig.runtime`:
+
+```typescript
+interface ResolveSelectionInput {
+  cli: Record<string, string | undefined>;
+  env: NodeJS.ProcessEnv;
+  agentsConfig?: {
+    runtime?: {
+      default_provider?: string;
+      default_model?: string;
+      provider_config_env?: string;
+      default_agent_config?: unknown;
+      provider_configs?: Record<string, unknown>;
+      provider_cli_config?: Record<string, unknown>;
+      role_provider_overrides?: Record<string, unknown>;
+    };
+  };
+  role?: string;
+}
+```
+
+3. Add import of `generateProviderCliExtraArgs` at the top of `providers.ts`:
+
+```typescript
+import {
+  PROVIDER_CLI_DEFAULTS,
+  generateProviderCliExtraArgs,
+  type ProviderCommandTemplate,
+} from './provider-defaults.js';
+```
+
+4. In `resolveProviderSelection`, after determining `agentConfig`, compute `cli_extra_args`:
+
+```typescript
+const providerCliConfig = isPlainObject(runtime?.provider_cli_config)
+  ? runtime.provider_cli_config
+  : null;
+const cliExtraArgs = generateProviderCliExtraArgs(provider, providerCliConfig);
+
+return {
+  provider,
+  model: model ?? `${provider}-default`,
+  provider_config_env: providerConfigEnv,
+  provider_config_ref: providerConfigRef,
+  agent_config: agentConfig,
+  ...(cliExtraArgs.length > 0 ? { cli_extra_args: cliExtraArgs } : {}),
+};
+```
+
+- [ ] **Step 4: Run test to confirm it passes**
+
+```bash
+npx vitest run apps/control-plane/test/providers.spec.ts -t "provider_cli_config"
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/control-plane/src/providers/providers.ts apps/control-plane/test/providers.spec.ts
+git commit -m "feat: add cli_extra_args to ProviderSelection; populate from provider_cli_config in agents.yaml"
+```
+
+---
+
+### Task 3: Append `cli_extra_args` in template resolvers (`cli-worker-provider.ts` and `providers.ts`)
+
+**Files:**
+
+- Modify: `apps/control-plane/src/providers/cli-worker-provider.ts`
+- Modify: `apps/control-plane/src/providers/providers.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `apps/control-plane/test/worker-provider-adapters.spec.ts` — a new test that exercises `cli_extra_args` being appended to the run command:
+
+```typescript
+it('GIVEN_selection_with_cli_extra_args_WHEN_runWorker_called_THEN_extra_args_appended_to_command', async () => {
+  const run = vi.fn(
+    async (): Promise<ProviderCommandResult> => ({
+      exitCode: 0,
+      stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+      stderr: '',
+    }),
+  );
+  const parse = vi.fn(
+    (): WorkerOutputEnvelope => ({
+      session_id: 'planner-feature-b-session',
+      role: 'planner',
+      feature_id: 'feature-b',
+      outputs: [{ type: 'NOTE', content: 'ok' }],
+      provider_meta: { provider: 'codex', model: 'codex-model' },
+    }),
+  );
+  const selection = makeSelection('codex', {});
+  selection.cli_extra_args = ['-c', 'mcp_servers.context7.enabled=false'];
+
+  const provider = new CliWorkerProvider(selection, {
+    outputParser: { parse },
+    commandRunner: { run },
+    workerResponseTimeoutMs: 1800000,
+  });
+
+  await provider.createSession('planner', 'feature-b', 'prompt');
+  await provider.runWorker({ role: 'planner', feature_id: 'feature-b', instructions: 'do work' });
+
+  const args = run.mock.calls.at(0)?.[1] as string[];
+  expect(args).toContain('-c');
+  expect(args).toContain('mcp_servers.context7.enabled=false');
+});
+```
+
+Also add a similar test to `providers.spec.ts` for `NullWorkerProvider.attachToSession`:
+
+```typescript
+it('GIVEN_selection_with_cli_extra_args_WHEN_attachToSession_called_THEN_extra_args_appended', async () => {
+  const runner = { run: vi.fn(async () => ({ exitCode: 0, signal: null })) };
+  const selection: ProviderSelection = {
+    provider: 'codex',
+    model: 'codex-default',
+    provider_config_env: null,
+    provider_config_ref: null,
+    cli_extra_args: ['-c', 'mcp_servers.context7.enabled=false'],
+  };
+  const provider = new NullWorkerProvider(selection, { commandRunner: runner });
+
+  await provider.attachToSession?.('session-1');
+
+  const args = runner.run.mock.calls.at(0)?.[1] as string[];
+  expect(args).toContain('-c');
+  expect(args).toContain('mcp_servers.context7.enabled=false');
+});
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+```bash
+npx vitest run apps/control-plane/test/worker-provider-adapters.spec.ts -t "cli_extra_args"
+npx vitest run apps/control-plane/test/providers.spec.ts -t "cli_extra_args"
+```
+
+Expected: both FAIL.
+
+- [ ] **Step 3: Update template resolvers in `cli-worker-provider.ts`**
+
+Modify `resolveRunTemplate`, `resolveAttachTemplate`, and `resolveSendTemplate` to append `selection.cli_extra_args`:
+
+```typescript
+function resolveRunTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const topLevelCommand = asNonEmptyString(selection.agent_config?.command);
+  const topLevelArgs = readStringArray(selection.agent_config?.args);
+  const topLevelTemplate =
+    topLevelCommand && topLevelArgs ? { command: topLevelCommand, args: topLevelArgs } : undefined;
+
+  const template = templateFromConfig(
+    selection.agent_config,
+    'run',
+    topLevelTemplate ?? PROVIDER_CLI_DEFAULTS[selection.provider]?.run,
+  );
+  return appendExtraArgs(template, selection.cli_extra_args);
+}
+
+function resolveAttachTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const template = templateFromConfig(
+    selection.agent_config,
+    'attach',
+    PROVIDER_CLI_DEFAULTS[selection.provider]?.attach,
+  );
+  return appendExtraArgs(template, selection.cli_extra_args);
+}
+
+function resolveSendTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const template = templateFromConfig(
+    selection.agent_config,
+    'send',
+    PROVIDER_CLI_DEFAULTS[selection.provider]?.send,
+  );
+  return appendExtraArgs(template, selection.cli_extra_args);
+}
+```
+
+Add the `appendExtraArgs` helper just above these functions:
+
+```typescript
+function appendExtraArgs(
+  template: ProviderCommandTemplate | undefined,
+  extraArgs: string[] | undefined,
+): ProviderCommandTemplate | undefined {
+  if (!template || !extraArgs?.length) {
+    return template;
+  }
+  return { command: template.command, args: [...template.args, ...extraArgs] };
+}
+```
+
+- [ ] **Step 4: Update `resolveProviderCommands` in `providers.ts` to append `cli_extra_args`**
+
+```typescript
+function resolveProviderCommands(selection: ProviderSelection): ProviderCliCommands {
+  const defaults = PROVIDER_CLI_DEFAULTS[selection.provider] ?? {};
+  const attachTemplate = resolveTemplateFromAgentConfig(
+    selection.agent_config,
+    'attach',
+    defaults.attach,
+  );
+  const sendTemplate = resolveTemplateFromAgentConfig(
+    selection.agent_config,
+    'send',
+    defaults.send,
+  );
+
+  const extra = selection.cli_extra_args;
+  return {
+    attach:
+      attachTemplate && extra?.length
+        ? { command: attachTemplate.command, args: [...attachTemplate.args, ...extra] }
+        : attachTemplate,
+    send:
+      sendTemplate && extra?.length
+        ? { command: sendTemplate.command, args: [...sendTemplate.args, ...extra] }
+        : sendTemplate,
+  };
+}
+```
+
+- [ ] **Step 5: Run new tests to confirm they pass**
+
+```bash
+npx vitest run apps/control-plane/test/worker-provider-adapters.spec.ts -t "cli_extra_args"
+npx vitest run apps/control-plane/test/providers.spec.ts -t "cli_extra_args"
+```
+
+Expected: both PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/control-plane/src/providers/cli-worker-provider.ts apps/control-plane/src/providers/providers.ts apps/control-plane/test/worker-provider-adapters.spec.ts apps/control-plane/test/providers.spec.ts
+git commit -m "feat: append cli_extra_args to all resolved command templates"
+```
+
+---
+
+## Chunk 2: Config wiring
+
+### Task 4: Update existing tests that still assert the old hardcoded MCP server names
+
+The existing tests in `worker-provider-adapters.spec.ts` and `providers.spec.ts` currently assert the MCP server names as part of the default args. Since those names are now gone from the defaults, these tests will be failing. Update them.
+
+**Files:**
+
+- Modify: `apps/control-plane/test/worker-provider-adapters.spec.ts`
+- Modify: `apps/control-plane/test/providers.spec.ts`
+
+- [ ] **Step 1: Run the full test suite to see which tests are failing**
+
+```bash
+npx vitest run apps/control-plane/test/worker-provider-adapters.spec.ts
+npx vitest run apps/control-plane/test/providers.spec.ts
+```
+
+Expected: failures on tests that assert `-c mcp_servers.context7.enabled=false` and `-c mcp_servers.useful-agent-instructions.enabled=false`.
+
+- [ ] **Step 2: Update `worker-provider-adapters.spec.ts` — remove MCP names from expected run args**
+
+Find the test at line ~431 (`GIVEN_codex_provider_...`) and update the expected args array — remove the two `-c mcp_servers.*` pairs (the `--disable apps` pair stays):
+
+```typescript
+expect(firstCall?.[1]).toEqual([
+  'exec',
+  '--dangerously-bypass-approvals-and-sandbox',
+  '--output-last-message',
+  expect.stringMatching(/last-message\.txt$/),
+  '--disable',
+  'apps',
+]);
+```
+
+- [ ] **Step 3: Update `providers.spec.ts` — remove MCP names from expected attach args**
+
+Find the test at line ~387 (`GIVEN_codex_provider_WHEN_attachToSession_called_THEN_executes_attach_command`) and update:
+
+```typescript
+expect(runner.run).toHaveBeenCalledWith('codex', ['resume', '--last', '--disable', 'apps'], {
+  interactive: true,
+  timeoutMs: undefined,
+});
+```
+
+- [ ] **Step 4: Run the test files to confirm all tests pass**
+
+```bash
+npx vitest run apps/control-plane/test/worker-provider-adapters.spec.ts
+npx vitest run apps/control-plane/test/providers.spec.ts
+```
+
+Expected: all tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/control-plane/test/worker-provider-adapters.spec.ts apps/control-plane/test/providers.spec.ts
+git commit -m "test: remove hardcoded MCP server names from default provider command expectations"
+```
+
+---
+
+### Task 5: Update `agents.schema.json` and `agents.yaml`
+
+**Files:**
+
+- Modify: `agentic/orchestrator/schemas/agents.schema.json`
+- Modify: `config/agentic/orchestrator/agents.yaml`
+
+- [ ] **Step 1: Add `provider_cli_config` to `agents.schema.json`**
+
+In the `runtime` object's `properties` block (after `provider_configs`), add:
+
+```json
+"provider_cli_config": {
+  "type": "object",
+  "description": "Per-provider CLI flag configuration for user-profile-specific flags (e.g. disabling MCP servers). Keyed by provider name.",
+  "additionalProperties": false,
+  "properties": {
+    "codex": {
+      "type": "object",
+      "description": "CLI flag configuration for the codex provider.",
+      "additionalProperties": false,
+      "properties": {
+        "disable_mcp_servers": {
+          "type": "array",
+          "description": "MCP server names to disable via -c mcp_servers.<name>.enabled=false. Use this to prevent user-profile MCPs from being invoked during worker execution.",
+          "items": { "type": "string" },
+          "default": []
+        }
+      }
+    },
+    "claude": {
+      "type": "object",
+      "description": "CLI flag configuration for the claude provider.",
+      "additionalProperties": false,
+      "properties": {
+        "no_mcp": {
+          "type": "boolean",
+          "description": "When true, passes --no-mcp to disable all MCP servers during worker execution. Prevents user-profile MCPs from being invoked.",
+          "default": false
+        }
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Add `provider_cli_config` block to `config/agentic/orchestrator/agents.yaml`**
+
+After `provider_configs: {}` (or `role_provider_overrides: {}`), add:
+
+```yaml
+provider_cli_config:
+  codex:
+    disable_mcp_servers:
+      - context7
+      - useful-agent-instructions
+```
+
+- [ ] **Step 3: Run schema validation to confirm agents.yaml is valid**
+
+```bash
+npm run validate:mcp-contracts
+```
+
+Expected: pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add agentic/orchestrator/schemas/agents.schema.json config/agentic/orchestrator/agents.yaml
+git commit -m "feat: add provider_cli_config to agents schema and config; move MCP server disables to user config"
+```
+
+---
+
+### Task 6: Full verification
+
+- [ ] **Step 1: Run the full test suite**
+
+```bash
+npm run test
+```
+
+Expected: all tests pass at ≥90% coverage. Zero failures.
+
+- [ ] **Step 2: Run the build**
+
+```bash
+npm run build
+```
+
+Expected: zero TypeScript errors, zero lint warnings.
+
+- [ ] **Step 3: Run architecture validator**
+
+```bash
+npm run validate:architecture
+```
+
+Expected: pass (silent).
+
+- [ ] **Step 4: Update `spec-files/progress.md`**
+
+Append a new entry:
+
+```
+✅ **Entry N — Provider CLI Config: Move MCP flags to agents.yaml**
+   - **Goal:** Remove user-profile-specific CLI flags (MCP server names) from hardcoded provider defaults; make them configurable in agents.yaml.
+   - **Changes made:**
+     - `apps/control-plane/src/providers/provider-defaults.ts` — removed MCP server names from CODEX_BASE_FLAGS; added `generateProviderCliExtraArgs()` helper.
+     - `apps/control-plane/src/providers/providers.ts` — added `provider_cli_config` to `ResolveSelectionInput`; added `cli_extra_args` to `ProviderSelection`; populate in `resolveProviderSelection`; append in `resolveProviderCommands`.
+     - `apps/control-plane/src/providers/cli-worker-provider.ts` — added `appendExtraArgs()` helper; call in all three template resolvers.
+     - `agentic/orchestrator/schemas/agents.schema.json` — added `provider_cli_config` schema with `codex.disable_mcp_servers` and `claude.no_mcp`.
+     - `config/agentic/orchestrator/agents.yaml` — added `provider_cli_config.codex.disable_mcp_servers` with user's server list.
+     - Tests updated and added in `worker-provider-adapters.spec.ts` and `providers.spec.ts`.
+   - **Result:** `npm test` ✅. `npm run build` ✅.
+```
+
+- [ ] **Step 5: Final commit**
+
+```bash
+git add spec-files/progress.md
+git commit -m "chore: update progress log for provider_cli_config implementation"
+```