Fix MCP env var handling: add Task.env/Plan.globalEnv with process.env apply/restore around session creation

[Copilot]

SDK v0.1.25 standardizes MCP env var propagation via envValueMode: direct, but Planeteer had no mechanism to set env vars before createSession() is called — and no Task.env or Plan.globalEnv fields at all.

Model changes (plan.ts)

• Task.env?: Record<string, string> — task-scoped env vars
• Plan.globalEnv?: Record<string, string> — plan-wide env vars (overridden per-task)

New utility (src/utils/env-validation.ts)

• isSensitiveKey(name) — detects key, token, password, secret, credential, auth in var names
• maskEnvVars(env) — replaces sensitive values with *** for safe display
• isValidEnvName(name) — POSIX name validation (^[A-Za-z_][A-Za-z0-9_]*$)

Executor changes (executor.ts)

Exported mergeEnv(globalEnv?, taskEnv?) merges the two maps (task wins), skipping invalid POSIX names. Before each sendPromptSync call (which internally calls createSession), env vars are applied to process.env and restored in a finally block — covering both task execution and the init bootstrap:

const mergedEnv = mergeEnv(updatedPlan.globalEnv, task.env);
const savedEnv = applyEnv(mergedEnv);   // sets process.env before createSession
try {
  const result = await sendPromptSync(...);
} finally {
  restoreEnv(savedEnv);                 // always restores original state
}

Other

• package.json: @github/copilot-sdk bumped to ^0.1.25
• README: added MCP environment variable configuration section with JSON examples for both globalEnv and task-level env

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[enhancement] Fix MCP server environment variable handling per SDK v0.1.25</issue_title>
<issue_description>## Background

SDK v0.1.25 (released Feb 18, 2026) includes a critical fix for MCP server environment variables: "Fix MCP env vars: send envValueMode direct across all SDKs" (PR colindembovsky/planeteer#484 by Steve Sanderson).

Key SDK change:

• Previously, MCP environment variable handling (envValueMode) was inconsistent across SDK languages
• v0.1.25 standardizes how env vars are passed to MCP servers
• Ensures that environment variables set in Task.env or Settings.globalEnv are correctly propagated to MCP tools

Why this matters for Planeteer:

• According to the custom instructions, Planeteer supports MCP tools via Task.env and Settings.globalEnv (mentioned in repository memories)
• Environment variables are merged in executor.ts and set in process.env before session creation
• Incorrect env handling could cause MCP servers to fail silently or use wrong credentials/config

Related commits:

• 2f2bcf7 - v0.1.25 release including MCP env var fix

Proposal

Audit and update Planeteer's MCP environment variable handling to align with SDK v0.1.25+ guarantees:

1. Review src/services/executor.ts:
   • Verify that Task.env and Settings.globalEnv are correctly merged
   • Ensure process.env is set before createSession() is called
   • Confirm that sensitive env vars (tokens, keys) are properly masked in logs/UI
2. Update src/models/plan.ts (if needed):
   • Ensure Task.env and Settings.globalEnv types support string values (no complex objects)
   • Add validation for env var names (no spaces, follow POSIX conventions)
3. Add tests for MCP env var scenarios:
   • Test that env vars flow from plan → executor → session → MCP server
   • Verify sensitive var masking (existing pattern from src/utils/env-validation.ts)
4. Upgrade to SDK ^0.1.25:
   • Update package.json dependency
   • Run npm install and verify no breaking changes in copilot.ts
5. Document MCP env var usage:
   • Add a section to README explaining how to configure MCP servers with env vars
   • Provide example showing Task.env or Settings.globalEnv usage

Benefit

• MCP reliability: Environment variables will be correctly passed to MCP servers, preventing configuration failures
• Cross-platform consistency: Aligns with SDK's standardized env handling across Node.js, Python, Go, .NET
• Security: Ensures sensitive env vars are masked in UI/logs (already implemented per memories)
• Up-to-date SDK: Takes advantage of latest bug fixes and features

Acceptance Criteria

• package.json updated to @github/copilot-sdk: ^0.1.25
• src/services/executor.ts correctly merges Task.env and Settings.globalEnv before session creation
• Environment variables are set in process.env prior to calling createSession()
• Tests verify env vars are available to MCP tools during execution
• Sensitive env var masking is preserved (tokens, keys, passwords, secrets)
• README includes MCP environment variable configuration examples
• No regressions in existing task execution flows

AI generated by Weekly Enhancement Suggestions

Comments on the Issue (you are @copilot in this section)

• Fixes [enhancement] Fix MCP server environment variable handling per SDK v0.1.25 #22

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.