fix: keep default prompt date context cache-stable (#796)

* fix: keep default prompt date context cache-stable

* fix: escape documented template variables

Author: sam-saffron-jarvis

internal/agents/builtin/agent-builder/system.md

@@ -61,16 +61,16 @@ mcp:
 ```
 
 **system.md** - System prompt with optional template variables:
-- `{{date}}`, `{{datetime}}`, `{{datetime_rfc3339}}`, `{{time}}`, `{{year}}`, `{{weekday}}`
-- `{{timezone}}`, `{{timezone_abbr}}`, `{{timezone_offset}}`, `{{utc_date}}`, `{{utc_datetime}}`
-- `{{cwd}}`, `{{cwd_name}}`, `{{home}}`, `{{user}}`
-- `{{git_branch}}`, `{{git_repo}}`, `{{git_diff_stat}}`
-- `{{files}}`, `{{file_count}}` (from -f flags)
-- `{{os}}`, `{{platform}}`, `{{resource_dir}}`
-- `{{provider}}`, `{{model}}`, `{{provider_model}}`
-- `{{agents}}` - Loads project instructions (hierarchical AGENTS.md + fallbacks)
-
-**The `{{agents}}` variable** loads project instructions using:
+- `{{!date}}`, `{{!datetime}}`, `{{!datetime_rfc3339}}`, `{{!time}}`, `{{!year}}`, `{{!weekday}}`
+- `{{!timezone}}`, `{{!timezone_abbr}}`, `{{!timezone_offset}}`, `{{!utc_date}}`, `{{!utc_datetime}}`
+- `{{!cwd}}`, `{{!cwd_name}}`, `{{!home}}`, `{{!user}}`
+- `{{!git_branch}}`, `{{!git_repo}}`, `{{!git_diff_stat}}`
+- `{{!files}}`, `{{!file_count}}` (from -f flags)
+- `{{!os}}`, `{{!platform}}`, `{{!resource_dir}}`
+- `{{!provider}}`, `{{!model}}`, `{{!provider_model}}`
+- `{{!agents}}` - Loads project instructions (hierarchical AGENTS.md + fallbacks)
+
+**The `{{!agents}}` variable** loads project instructions using:
 1. User-level: `~/.config/term-llm/AGENTS.md` (always included if present)
 2. Project-level: AGENTS.md hierarchy from repo root → cwd (at each level, AGENTS.override.md takes precedence over AGENTS.md)
 3. Fallback (only if no AGENTS.md found): CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, CONTRIBUTING.md
@@ -109,7 +109,7 @@ tools:
 - Use `custom` instead of `run_agent_script` when the tool has a clear name/schema the LLM should understand natively
 - No directory paths are exposed to the LLM — scripts are resolved from the agent's own directory
 - No permission prompts — scripts in the agent directory are implicitly trusted
-- This replaces the old `{{agent_dir}}` shell allow pattern approach which never worked
+- This replaces the old `{{!agent_dir}}` shell allow pattern approach which never worked
 - Scripts must be executable files (not symlinks to outside the agent directory)
 
 **Additional .md files** - Include reference material:
@@ -199,10 +199,10 @@ Structure system.md with:
 
 1. **Role** - Clear statement of what the agent does
 2. **Context** - Use template variables for dynamic info (date, repo, etc.)
-   - **Always include `Current local time: {{weekday}} {{datetime_rfc3339}} ({{timezone}}).`** at the top so the agent knows the current date and timezone
-   - Use `UTC: {{utc_datetime}}.` as well for jobs, logs, or cross-timezone coordination
-   - Add `User: {{user}}.` if user context is helpful
-   - Add `Working in: {{cwd_name}}` or `Repository: {{git_repo}}` for project-aware agents
+   - **Always include `Current local date: {{!weekday}} {{!date}} ({{!timezone}}).`** at the top so the agent knows the current local date without changing every minute and breaking prompt caches
+   - Add `{{!time}}`, `{{!datetime_rfc3339}}`, or `UTC: {{!utc_datetime}}.` only for agents that genuinely need time-of-day precision, logs, jobs, or cross-timezone coordination
+   - Add `User: {{!user}}.` if user context is helpful
+   - Add `Working in: {{!cwd_name}}` or `Repository: {{!git_repo}}` for project-aware agents
 3. **Process** - Step-by-step workflow the agent should follow
 4. **Guidelines** - Best practices and constraints
 5. **Output format** - How to structure responses (if relevant)

internal/agents/registry.go

@@ -358,7 +358,7 @@ tools:
 	// Create system.md
 	systemMD := fmt.Sprintf(`You are a helpful assistant for the {{git_repo}} project.
 
-Current local time: {{weekday}} {{datetime_rfc3339}} ({{timezone}}). Working directory: {{cwd}}
+Current local date: {{weekday}} {{date}} ({{timezone}}). Working directory: {{cwd}}
 
 ## Your Role
 

internal/agents/template.go

@@ -19,6 +19,10 @@ import (
 // templateVarPattern matches {{variable}} tokens, allowing optional whitespace inside delimiters.
 var templateVarPattern = regexp.MustCompile(`\{\{\s*(\w+)\s*\}\}`)
 
+// escapedTemplateVarPattern matches {{!variable}} tokens. Escaped variables render as
+// literal {{variable}} text so prompts can document template syntax without expanding it.
+var escapedTemplateVarPattern = regexp.MustCompile(`\{\{\s*!\s*(\w+)\s*\}\}`)
+
 // TemplateContext holds values for template variable expansion.
 type TemplateContext struct {
 	// Time-related
@@ -223,8 +227,9 @@ func (c TemplateContext) WithLLM(provider, model string) TemplateContext {
 }
 
 // ExpandTemplate replaces {{variable}} placeholders with values from context.
+// Use {{!variable}} to render a literal {{variable}} without expanding it.
 func ExpandTemplate(text string, ctx TemplateContext) string {
-	return templateVarPattern.ReplaceAllStringFunc(text, func(match string) string {
+	expanded := templateVarPattern.ReplaceAllStringFunc(text, func(match string) string {
 		// Extract variable name.
 		matches := templateVarPattern.FindStringSubmatch(match)
 		if len(matches) != 2 {
@@ -312,6 +317,7 @@ func ExpandTemplate(text string, ctx TemplateContext) string {
 			return match
 		}
 	})
+	return escapedTemplateVarPattern.ReplaceAllString(expanded, "{{$1}}")
 }
 
 // gitProbeTimeout bounds git subprocesses used during template expansion so prompt construction

internal/agents/template_test.go

@@ -91,6 +91,16 @@ func TestExpandTemplate(t *testing.T) {
 			template: "{{weekday}} {{datetime_rfc3339}} {{timezone}} {{timezone_abbr}} {{timezone_offset}} UTC={{utc_datetime}}",
 			expected: "Friday 2026-01-16T14:30:00+11:00 Australia/Sydney AEDT +11:00 UTC=2026-01-16T03:30:00Z",
 		},
+		{
+			name:     "escaped variable renders literally",
+			template: "Document {{!date}} and {{ ! timezone }}; expand {{date}}",
+			expected: "Document {{date}} and {{timezone}}; expand 2026-01-16",
+		},
+		{
+			name:     "escaped unknown variable renders literally",
+			template: "Old token {{!agent_dir}}",
+			expected: "Old token {{agent_dir}}",
+		},
 		{
 			name:     "all variables",
 			template: "{{date}} {{datetime}} {{datetime_rfc3339}} {{time}} {{year}} {{weekday}} {{timezone}} {{timezone_abbr}} {{timezone_offset}} {{utc_date}} {{utc_datetime}} {{cwd}} {{cwd_name}} {{home}} {{user}} {{git_branch}} {{git_repo}} {{files}} {{file_count}} {{os}} {{platform}} {{provider}} {{model}} {{provider_model}} {{resource_dir}} {{handover_dir}} {{handover_path}}",
@@ -279,12 +289,15 @@ func TestNewTemplateContextForTemplate_GitDiffStatTimeoutFailsOpen(t *testing.T)
 }
 
 func TestTemplateVariablesAllowsWhitespace(t *testing.T) {
-	vars := templateVariables("{{ git_repo }}/{{git_branch}} {{ git_diff_stat }} {{ agents }} {{ handover_dir }} {{ handover_path }}")
+	vars := templateVariables("{{ git_repo }}/{{git_branch}} {{ git_diff_stat }} {{ agents }} {{ handover_dir }} {{ handover_path }} {{!date}}")
 	for _, name := range []string{"git_repo", "git_branch", "git_diff_stat", "agents", "handover_dir", "handover_path"} {
 		if !vars[name] {
 			t.Fatalf("templateVariables missing %q in %#v", name, vars)
 		}
 	}
+	if vars["date"] {
+		t.Fatalf("templateVariables should ignore escaped variable {{!date}}: %#v", vars)
+	}
 }
 
 func TestNewTemplateContext(t *testing.T) {