fix(agent-context): support multiple context files safely (#2969)

* fix(agent-context): support multiple context files safely * fix(agent-context): harden context file validation * fix(agent-context): preserve disabled context target * fix(agent-context): address review follow-ups * fix(agent-context): dedupe PowerShell context files * fix(agent-context): align context file dedupe * fix(agent-context): align bash context file dedupe * fix(agent-context): preserve disabled display target * fix(agent-context): require yaml-capable updater python * fix(agent-context): preserve context files config * fix(agent-context): align context file fallbacks * fix(agent-context): share context file resolution --------- Co-authored-by: AustinZ21 <AustinZ21@users.noreply.github.com>
2026-07-06 22:32:13 +08:00 · 2026-06-22 10:10:55 -07:00
parent cac16dd1d7
commit bbdf1b8f40
15 changed files with 1486 additions and 203 deletions
--- a/extensions/agent-context/README.md
+++ b/extensions/agent-context/README.md
@@ -10,6 +10,7 @@ Not every Spec Kit user wants Spec Kit to write into the coding agent's context

 - **Opt out** entirely with `specify extension disable agent-context` — Spec Kit will then never create or modify the agent context file.
 - **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` — both the Python layer and the bundled scripts honor the same `context_markers` value.
+- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.
 - **Refresh on demand** with `/speckit.agent-context.update`, or automatically through the hooks declared in `extension.yml` (`after_specify`, `after_plan`).

 ## Commands
@@ -27,6 +28,12 @@ All configuration flows through the extension's own config file at
 # Path to the coding agent context file managed by this extension
 context_file: CLAUDE.md

+# Optional list of coding agent context files to manage together.
+# When non-empty, this takes precedence over context_file.
+context_files:
+  - AGENTS.md
+  - CLAUDE.md
+
 # Delimiters for the managed Spec Kit section
 context_markers:
  start: "<!-- SPECKIT START -->"
@@ -34,6 +41,7 @@ context_markers:
 ```

 - `context_file` — the project-relative path to the coding agent context file, written by `specify init` and `specify integration install`.
+- `context_files` — optional project-relative paths to multiple coding agent context files. When non-empty, the list takes precedence over `context_file`. Absolute paths, backslash separators, and `..` path segments are rejected.
 - `context_markers.start` / `.end` — the delimiters around the managed section. Edit these to use custom markers.

 ## Requirements
@@ -55,3 +63,4 @@ specify extension disable agent-context
 ```

 When disabled, Spec Kit skips context file creation, updates, and removal (the gates are inside `upsert_context_section()` and `remove_context_section()`).
+Disabled projects also ignore stale `context_files` values during command rendering so disabling the extension remains a complete opt-out.
--- a/extensions/agent-context/agent-context-config.yml
+++ b/extensions/agent-context/agent-context-config.yml
@@ -2,12 +2,17 @@
 # These values are populated automatically by `specify init` and
 # `specify integration use` / `specify integration install`.

-# Path (relative to the project root) to the coding agent context file
+# Path (relative to the project root) to the default coding agent context file
 # managed by this extension (e.g. CLAUDE.md, AGENTS.md,
 # .github/copilot-instructions.md). Set automatically from the active
 # integration and regenerated during `specify init` or integration switches.
 context_file: ""

+# Optional list of project-relative coding agent context files managed by this
+# extension. When non-empty, this list takes precedence over `context_file`.
+# Use this for projects that intentionally keep multiple agent anchors in sync.
+context_files: []
+
 # Delimiters for the managed Spec Kit section.
 # Edit these to use custom markers.
 context_markers:
--- a/extensions/agent-context/commands/speckit.agent-context.update.md
+++ b/extensions/agent-context/commands/speckit.agent-context.update.md
@@ -1,5 +1,5 @@
 ---
-description: "Refresh the managed Spec Kit section in the coding agent context file"
+description: "Refresh the managed Spec Kit section in coding agent context file(s)"
 ---

 # Update Coding Agent Context
@@ -12,11 +12,12 @@ The script reads the agent-context extension config at
 `.specify/extensions/agent-context/agent-context-config.yml` to discover:

 - `context_file` — the path of the coding agent context file to manage.
+- `context_files` — optional project-relative paths for multiple coding agent context files. When non-empty, the script updates each listed file and the list takes precedence over `context_file`.
 - `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` when the field is missing.

 It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).

-If `context_file` is empty or the file cannot be located, the command reports nothing to do and exits successfully.
+If `context_files` and `context_file` are empty, the command reports nothing to do and exits successfully. Context file paths must stay project-relative; absolute paths, Windows drive paths, backslash separators, and `..` path segments are rejected.

 ## Execution

--- a/extensions/agent-context/scripts/bash/update-agent-context.sh
+++ b/extensions/agent-context/scripts/bash/update-agent-context.sh
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 # update-agent-context.sh
 #
-# Refresh the managed Spec Kit section in the coding agent's context file
+# Refresh the managed Spec Kit section in the coding agent's context file(s)
 # (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
 #
-# Reads `context_file` and `context_markers.{start,end}` from the
+# Reads `context_files` or `context_file`, plus `context_markers.{start,end}`, from the
 # agent-context extension config:
 #   .specify/extensions/agent-context/agent-context-config.yml
 #
@@ -26,22 +26,41 @@ if [[ ! -f "$EXT_CONFIG" ]]; then
  exit 0
 fi

-# Locate a suitable Python interpreter (python3, then python).
+# Locate a Python 3 interpreter with PyYAML available.
 _python=""
-if command -v python3 >/dev/null 2>&1; then
-  _python="python3"
-elif command -v python >/dev/null 2>&1 && python --version 2>&1 | grep -q "^Python 3"; then
-  _python="python"
-fi
+_python_candidates=()
+[[ -n "${SPECKIT_PYTHON:-}" ]] && _python_candidates+=("$SPECKIT_PYTHON")
+_python_candidates+=("python3" "python")
+for _candidate in "${_python_candidates[@]}"; do
+  if command -v "$_candidate" >/dev/null 2>&1 \
+    && "$_candidate" - <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml  # noqa: F401
+except ImportError:
+    sys.exit(1)
+sys.exit(0 if sys.version_info[0] == 3 else 1)
+PY
+  then
+    _python="$_candidate"
+    break
+  fi
+done
+unset _candidate _python_candidates

 if [[ -z "$_python" ]]; then
-  echo "agent-context: Python 3 not found on PATH; skipping update." >&2
+  echo "agent-context: Python 3 with PyYAML not found on PATH; skipping update." >&2
+  echo "  To resolve: pip install pyyaml (or install it into the environment used by python3)." >&2
  exit 0
 fi
+_case_insensitive_context_files=0
+case "$(uname -s 2>/dev/null || true)" in
+  MINGW*|MSYS*|CYGWIN*) _case_insensitive_context_files=1 ;;
+esac

-# Parse extension config once; emit three newline-separated fields:
-# context_file, context_markers.start, context_markers.end
-if ! _raw_opts="$("$_python" - "$EXT_CONFIG" <<'PY'
+# Parse extension config once; emit context files as JSON, followed by marker strings.
+if ! _raw_opts="$("$_python" - "$EXT_CONFIG" "$_case_insensitive_context_files" <<'PY'
+import json
 import sys
 try:
    import yaml
@@ -73,7 +92,28 @@ def get_str(obj, *keys):
        else:
            return ""
    return node if isinstance(node, str) else ""
-print(get_str(data, "context_file"))
+context_files = []
+seen_context_files = set()
+case_insensitive = sys.argv[2] == "1" or sys.platform.startswith(("win32", "cygwin"))
+raw_files = data.get("context_files")
+if isinstance(raw_files, list):
+    for value in raw_files:
+        if not isinstance(value, str):
+            continue
+        candidate = value.strip()
+        if not candidate:
+            continue
+        key = candidate.casefold() if case_insensitive else candidate
+        if key in seen_context_files:
+            continue
+        context_files.append(candidate)
+        seen_context_files.add(key)
+if not context_files:
+    raw_file = get_str(data, "context_file")
+    candidate = raw_file.strip()
+    if candidate:
+        context_files.append(candidate)
+print(json.dumps(context_files))
 print(get_str(data, "context_markers", "start"))
 print(get_str(data, "context_markers", "end"))
 PY
@@ -87,31 +127,71 @@ while IFS= read -r _line || [[ -n "$_line" ]]; do
  _opts_lines+=("$_line")
 done < <(printf '%s\n' "$_raw_opts")
 if (( ${#_opts_lines[@]} < 3 )); then
-  echo "agent-context: malformed config parser output; expected 3 lines (context_file, marker_start, marker_end), got ${#_opts_lines[@]}; skipping update." >&2
+  echo "agent-context: malformed config parser output; expected 3 lines (context_files, marker_start, marker_end), got ${#_opts_lines[@]}; skipping update." >&2
  exit 0
 fi
-CONTEXT_FILE="${_opts_lines[0]}"
+CONTEXT_FILES_JSON="${_opts_lines[0]}"
 MARKER_START="${_opts_lines[1]}"
 MARKER_END="${_opts_lines[2]}"

-if [[ -z "$CONTEXT_FILE" ]]; then
-  echo "agent-context: context_file not set in extension config; nothing to do." >&2
+if ! _context_files_raw="$("$_python" - "$CONTEXT_FILES_JSON" <<'PY'
+import json
+import sys
+try:
+    data = json.loads(sys.argv[1])
+except Exception:
+    data = []
+if not isinstance(data, list):
+    data = []
+for value in data:
+    if isinstance(value, str) and value:
+        print(value)
+PY
+)"; then
+  echo "agent-context: malformed context_files parser output; skipping update." >&2
  exit 0
 fi

-# Reject absolute paths, backslash separators, and '..' path segments in context_file
-if [[ "$CONTEXT_FILE" == /* ]] || [[ "$CONTEXT_FILE" =~ ^[A-Za-z]: ]]; then
-  echo "agent-context: context_file must be a project-relative path; got '$CONTEXT_FILE'." >&2
-  exit 1
+CONTEXT_FILES=()
+while IFS= read -r _line || [[ -n "$_line" ]]; do
+  [[ -n "$_line" ]] && CONTEXT_FILES+=("$_line")
+done < <(printf '%s\n' "$_context_files_raw")
+
+if (( ${#CONTEXT_FILES[@]} == 0 )); then
+  echo "agent-context: context_files/context_file not set in extension config; nothing to do." >&2
+  exit 0
 fi
-if [[ "$CONTEXT_FILE" == *\\* ]]; then
-  echo "agent-context: context_file must not contain backslash separators; got '$CONTEXT_FILE'." >&2
-  exit 1
-fi
-IFS='/' read -ra _cf_parts <<< "$CONTEXT_FILE"
-for _seg in "${_cf_parts[@]}"; do
-  if [[ "$_seg" == ".." ]]; then
-    echo "agent-context: context_file must not contain '..' path segments; got '$CONTEXT_FILE'." >&2
+
+for CONTEXT_FILE in "${CONTEXT_FILES[@]}"; do
+  # Reject absolute paths, backslash separators, and '..' path segments in context files
+  if [[ "$CONTEXT_FILE" == /* ]] || [[ "$CONTEXT_FILE" =~ ^[A-Za-z]: ]]; then
+    echo "agent-context: context files must be project-relative paths; got '$CONTEXT_FILE'." >&2
+    exit 1
+  fi
+  if [[ "$CONTEXT_FILE" == *\\* ]]; then
+    echo "agent-context: context files must not contain backslash separators; got '$CONTEXT_FILE'." >&2
+    exit 1
+  fi
+  IFS='/' read -ra _cf_parts <<< "$CONTEXT_FILE"
+  for _seg in "${_cf_parts[@]}"; do
+    if [[ "$_seg" == ".." ]]; then
+      echo "agent-context: context files must not contain '..' path segments; got '$CONTEXT_FILE'." >&2
+      exit 1
+    fi
+  done
+  if ! "$_python" - "$PROJECT_ROOT" "$CONTEXT_FILE" <<'PY'
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1]).resolve()
+target = (root / sys.argv[2]).resolve(strict=False)
+try:
+    target.relative_to(root)
+except ValueError:
+    sys.exit(1)
+PY
+  then
+    echo "agent-context: context file path resolves outside the project root; got '$CONTEXT_FILE'." >&2
    exit 1
  fi
 done
@@ -142,9 +222,6 @@ PY
  fi
 fi

-CTX_PATH="$PROJECT_ROOT/$CONTEXT_FILE"
-mkdir -p "$(dirname "$CTX_PATH")"
-
 # Build the managed section
 TMP_SECTION="$(mktemp)"
 trap 'rm -f "$TMP_SECTION"' EXIT
@@ -158,7 +235,11 @@ trap 'rm -f "$TMP_SECTION"' EXIT
  echo "$MARKER_END"
 } > "$TMP_SECTION"

-"$_python" - "$CTX_PATH" "$MARKER_START" "$MARKER_END" "$TMP_SECTION" <<'PY'
+for CONTEXT_FILE in "${CONTEXT_FILES[@]}"; do
+  CTX_PATH="$PROJECT_ROOT/$CONTEXT_FILE"
+  mkdir -p "$(dirname "$CTX_PATH")"
+
+  "$_python" - "$CTX_PATH" "$MARKER_START" "$MARKER_END" "$TMP_SECTION" <<'PY'
 import sys, os
 ctx_path, start, end, section_path = sys.argv[1:5]
 with open(section_path, "r", encoding="utf-8") as fh:
@@ -197,4 +278,5 @@ with open(ctx_path, "wb") as fh:
    fh.write(new_content.encode("utf-8"))
 PY

-echo "agent-context: updated $CONTEXT_FILE"
+  echo "agent-context: updated $CONTEXT_FILE"
+done
--- a/extensions/agent-context/scripts/powershell/update-agent-context.ps1
+++ b/extensions/agent-context/scripts/powershell/update-agent-context.ps1
@@ -1,10 +1,10 @@
 #!/usr/bin/env pwsh
 # update-agent-context.ps1
 #
-# Refresh the managed Spec Kit section in the coding agent's context file
+# Refresh the managed Spec Kit section in the coding agent's context file(s)
 # (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md).
 #
-# Reads `context_file` and `context_markers.{start,end}` from the
+# Reads `context_files` or `context_file`, plus `context_markers.{start,end}`, from the
 # agent-context extension config:
 #   .specify/extensions/agent-context/agent-context-config.yml
 #
@@ -52,6 +52,66 @@ function Test-ConfigObject {
    return $false
 }

+function Resolve-ContextPath {
+    param(
+        [Parameter(Mandatory = $true)][string]$Root,
+        [Parameter(Mandatory = $true)][string]$RelativePath
+    )
+
+    $rootFull = [System.IO.Path]::GetFullPath($Root)
+    $segments = $RelativePath -split '/'
+    $resolved = $rootFull
+
+    foreach ($segment in $segments) {
+        if ([string]::IsNullOrWhiteSpace($segment) -or $segment -eq '.') {
+            continue
+        }
+
+        $candidate = [System.IO.Path]::GetFullPath((Join-Path $resolved $segment))
+        if (Test-Path -LiteralPath $candidate) {
+            $item = Get-Item -LiteralPath $candidate -Force
+            if ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) {
+                $target = $item.Target
+                if ($target -is [System.Array]) {
+                    $target = $target[0]
+                }
+                if ($target) {
+                    if ([System.IO.Path]::IsPathRooted($target)) {
+                        $candidate = [System.IO.Path]::GetFullPath($target)
+                    } else {
+                        $candidate = [System.IO.Path]::GetFullPath(
+                            (Join-Path (Split-Path -Parent $candidate) $target)
+                        )
+                    }
+                }
+            }
+        }
+        $resolved = $candidate
+    }
+
+    return $resolved
+}
+
+function Test-IsSubPath {
+    param(
+        [Parameter(Mandatory = $true)][string]$Root,
+        [Parameter(Mandatory = $true)][string]$Path
+    )
+
+    $comparison = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
+        [System.StringComparison]::OrdinalIgnoreCase
+    } else {
+        [System.StringComparison]::Ordinal
+    }
+    $rootFull = [System.IO.Path]::GetFullPath($Root).TrimEnd(
+        [System.IO.Path]::DirectorySeparatorChar,
+        [System.IO.Path]::AltDirectorySeparatorChar
+    )
+    $pathFull = [System.IO.Path]::GetFullPath($Path)
+    return $pathFull.Equals($rootFull, $comparison) -or
+        $pathFull.StartsWith($rootFull + [System.IO.Path]::DirectorySeparatorChar, $comparison)
+}
+
 $ErrorActionPreference = 'Stop'
 $DefaultStart = '<!-- SPECKIT START -->'
 $DefaultEnd   = '<!-- SPECKIT END -->'
@@ -75,11 +135,16 @@ if (Get-Command ConvertFrom-Yaml -ErrorAction SilentlyContinue) {
 if ($null -eq $Options) {
    # ConvertFrom-Yaml unavailable or failed; fall back to Python+PyYAML.
    $pythonCmd = $null
-    foreach ($candidate in @('python3', 'python')) {
+    $pythonCandidates = @()
+    if ($env:SPECKIT_PYTHON) {
+        $pythonCandidates += $env:SPECKIT_PYTHON
+    }
+    $pythonCandidates += @('python3', 'python')
+    foreach ($candidate in $pythonCandidates) {
        if (Get-Command $candidate -ErrorAction SilentlyContinue) {
-            # Verify it is Python 3
-            $verOut = & $candidate --version 2>&1
-            if ($verOut -match 'Python 3') {
+            # Verify it is Python 3 with PyYAML available.
+            $null = & $candidate -c "import sys; import yaml; sys.exit(0 if sys.version_info[0] == 3 else 1)" 2>$null
+            if ($LASTEXITCODE -eq 0) {
                $pythonCmd = $candidate
                break
            }
@@ -87,8 +152,10 @@ if ($null -eq $Options) {
    }

    if ($pythonCmd) {
+        $pyScript = $null
        try {
-            $jsonOut = & $pythonCmd -c @'
+            $pyScript = [System.IO.Path]::GetTempFileName()
+            Set-Content -LiteralPath $pyScript -Encoding UTF8 -Value @'
 import json
 import sys
 try:
@@ -114,12 +181,17 @@ if not isinstance(data, dict):
    data = {}

 print(json.dumps(data))
-'@ $ExtConfig
+'@
+            $jsonOut = & $pythonCmd $pyScript $ExtConfig
            if ($LASTEXITCODE -eq 0 -and $jsonOut) {
                $Options = $jsonOut | ConvertFrom-Json -ErrorAction Stop
            }
        } catch {
            $Options = $null
+        } finally {
+            if ($pyScript -and (Test-Path -LiteralPath $pyScript)) {
+                Remove-Item -LiteralPath $pyScript -Force -ErrorAction SilentlyContinue
+            }
        }
    }

@@ -134,21 +206,63 @@ if (-not (Test-ConfigObject -Object $Options)) {
    exit 0
 }

-$ContextFile = Get-ConfigValue -Object $Options -Key 'context_file'
-if (-not $ContextFile) {
-    Write-Warning 'agent-context: context_file not set in extension config; nothing to do.'
+$ConfiguredContextFiles = Get-ConfigValue -Object $Options -Key 'context_files'
+$ContextFiles = @()
+if ($null -ne $ConfiguredContextFiles) {
+    foreach ($item in @($ConfiguredContextFiles)) {
+        if ($item -is [string] -and -not [string]::IsNullOrWhiteSpace($item)) {
+            $ContextFiles += $item.Trim()
+        }
+    }
+}
+if ($ContextFiles.Count -eq 0) {
+    $ContextFile = Get-ConfigValue -Object $Options -Key 'context_file'
+    if ($ContextFile -is [string] -and -not [string]::IsNullOrWhiteSpace($ContextFile)) {
+        $ContextFiles += $ContextFile.Trim()
+    }
+}
+$pathComparison = if ([System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT) {
+    [System.StringComparer]::OrdinalIgnoreCase
+} else {
+    [System.StringComparer]::Ordinal
+}
+$seenContextFiles = [System.Collections.Generic.HashSet[string]]::new($pathComparison)
+$dedupedContextFiles = @()
+foreach ($ContextFile in $ContextFiles) {
+    if ($seenContextFiles.Add($ContextFile)) {
+        $dedupedContextFiles += $ContextFile
+    }
+}
+$ContextFiles = $dedupedContextFiles
+if ($ContextFiles.Count -eq 0) {
+    Write-Warning 'agent-context: context_files/context_file not set in extension config; nothing to do.'
    exit 0
 }

-# Reject absolute paths and '..' path segments in context_file
-if ([System.IO.Path]::IsPathRooted($ContextFile)) {
-    Write-Warning "agent-context: context_file must be a project-relative path; got '$ContextFile'."
-    exit 1
-}
-$cfSegments = $ContextFile -split '[/\\]'
-if ($cfSegments -contains '..') {
-    Write-Warning "agent-context: context_file must not contain '..' path segments; got '$ContextFile'."
-    exit 1
+foreach ($ContextFile in $ContextFiles) {
+    # Reject absolute paths, drive-qualified paths, backslash separators, and '..' path segments in context files
+    if ($ContextFile -match '^[A-Za-z]:') {
+        Write-Warning "agent-context: context files must be project-relative paths; got '$ContextFile'."
+        exit 1
+    }
+    if ([System.IO.Path]::IsPathRooted($ContextFile)) {
+        Write-Warning "agent-context: context files must be project-relative paths; got '$ContextFile'."
+        exit 1
+    }
+    if ($ContextFile.Contains('\')) {
+        Write-Warning "agent-context: context files must not contain backslash separators; got '$ContextFile'."
+        exit 1
+    }
+    $cfSegments = $ContextFile -split '[/\\]'
+    if ($cfSegments -contains '..') {
+        Write-Warning "agent-context: context files must not contain '..' path segments; got '$ContextFile'."
+        exit 1
+    }
+    $resolvedTarget = Resolve-ContextPath -Root $ProjectRoot -RelativePath $ContextFile
+    if (-not (Test-IsSubPath -Root $ProjectRoot -Path $resolvedTarget)) {
+        Write-Warning "agent-context: context file path resolves outside the project root; got '$ContextFile'."
+        exit 1
+    }
 }

 $MarkerStart = $DefaultStart
@@ -184,12 +298,6 @@ if (-not $PlanPath) {
    }
 }

-$CtxPath = Join-Path $ProjectRoot $ContextFile
-$CtxDir  = Split-Path -Parent $CtxPath
-if ($CtxDir -and -not (Test-Path -LiteralPath $CtxDir)) {
-    New-Item -ItemType Directory -Path $CtxDir -Force | Out-Null
-}
-
 $lines = @($MarkerStart,
           'For additional context about technologies to be used, project structure,',
           'shell commands, and other important information, read the current plan')
@@ -199,39 +307,47 @@ if ($PlanPath) {
 $lines += $MarkerEnd
 $Section = ($lines -join "`n") + "`n"

-if (Test-Path -LiteralPath $CtxPath) {
-    $rawBytes = [System.IO.File]::ReadAllBytes($CtxPath)
-    # Strip UTF-8 BOM if present
-    if ($rawBytes.Length -ge 3 -and $rawBytes[0] -eq 0xEF -and $rawBytes[1] -eq 0xBB -and $rawBytes[2] -eq 0xBF) {
-        $content = [System.Text.Encoding]::UTF8.GetString($rawBytes, 3, $rawBytes.Length - 3)
-    } else {
-        $content = [System.Text.Encoding]::UTF8.GetString($rawBytes)
+foreach ($ContextFile in $ContextFiles) {
+    $CtxPath = Join-Path $ProjectRoot $ContextFile
+    $CtxDir  = Split-Path -Parent $CtxPath
+    if ($CtxDir -and -not (Test-Path -LiteralPath $CtxDir)) {
+        New-Item -ItemType Directory -Path $CtxDir -Force | Out-Null
    }

-    $s = $content.IndexOf($MarkerStart)
-    $e = if ($s -ge 0) { $content.IndexOf($MarkerEnd, $s) } else { $content.IndexOf($MarkerEnd) }
+    if (Test-Path -LiteralPath $CtxPath) {
+        $rawBytes = [System.IO.File]::ReadAllBytes($CtxPath)
+        # Strip UTF-8 BOM if present
+        if ($rawBytes.Length -ge 3 -and $rawBytes[0] -eq 0xEF -and $rawBytes[1] -eq 0xBB -and $rawBytes[2] -eq 0xBF) {
+            $content = [System.Text.Encoding]::UTF8.GetString($rawBytes, 3, $rawBytes.Length - 3)
+        } else {
+            $content = [System.Text.Encoding]::UTF8.GetString($rawBytes)
+        }

-    if ($s -ge 0 -and $e -ge 0 -and $e -gt $s) {
-        $endOfMarker = $e + $MarkerEnd.Length
-        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
-        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
-        $newContent = $content.Substring(0, $s) + $Section + $content.Substring($endOfMarker)
-    } elseif ($s -ge 0) {
-        $newContent = $content.Substring(0, $s) + $Section
-    } elseif ($e -ge 0) {
-        $endOfMarker = $e + $MarkerEnd.Length
-        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
-        if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
-        $newContent = $Section + $content.Substring($endOfMarker)
+        $s = $content.IndexOf($MarkerStart)
+        $e = if ($s -ge 0) { $content.IndexOf($MarkerEnd, $s) } else { $content.IndexOf($MarkerEnd) }
+
+        if ($s -ge 0 -and $e -ge 0 -and $e -gt $s) {
+            $endOfMarker = $e + $MarkerEnd.Length
+            if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
+            if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
+            $newContent = $content.Substring(0, $s) + $Section + $content.Substring($endOfMarker)
+        } elseif ($s -ge 0) {
+            $newContent = $content.Substring(0, $s) + $Section
+        } elseif ($e -ge 0) {
+            $endOfMarker = $e + $MarkerEnd.Length
+            if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`r") { $endOfMarker++ }
+            if ($endOfMarker -lt $content.Length -and $content[$endOfMarker] -eq "`n") { $endOfMarker++ }
+            $newContent = $Section + $content.Substring($endOfMarker)
+        } else {
+            if ($content -and -not $content.EndsWith("`n")) { $content += "`n" }
+            if ($content) { $newContent = $content + "`n" + $Section } else { $newContent = $Section }
+        }
    } else {
-        if ($content -and -not $content.EndsWith("`n")) { $content += "`n" }
-        if ($content) { $newContent = $content + "`n" + $Section } else { $newContent = $Section }
+        $newContent = $Section
    }
-} else {
-    $newContent = $Section
+
+    $newContent = $newContent.Replace("`r`n", "`n").Replace("`r", "`n")
+    [System.IO.File]::WriteAllText($CtxPath, $newContent, (New-Object System.Text.UTF8Encoding($false)))
+
+    Write-Host "agent-context: updated $ContextFile"
 }
-
-$newContent = $newContent.Replace("`r`n", "`n").Replace("`r", "`n")
-[System.IO.File]::WriteAllText($CtxPath, $newContent, (New-Object System.Text.UTF8Encoding($false)))
-
-Write-Host "agent-context: updated $ContextFile"