feat(agent): system prompt templating and global instruction propagation

[FelipeSuarez16]

Description

This PR implements dynamic system prompt templating and a mechanism for propagating global instructions through agent trees, addressing issue #99.

Key Features

1. Dynamic Prompt Templating:

   • Implements a regex-based template engine supporting {key}\ placeholders.
   • Supports alphanumeric keys, underscores, hyphens, and dots (e.g., {user.id}).
   • JSON-Safe: Designed to avoid collisions with standard JSON syntax.
   • Automatic Variables: Automatically injects {current_date}\ (UTC, ISO format) into all system prompts.

2. Global Instructions Propagation:

   • Introduced \agent.ContextWithGlobalInstructions\ and \agent.GlobalInstructions.
   • Uses \context.Context\ to propagate directives across multi-agent trees (including \AgentTool\ calls) without polluting session state.
   • Instructions are structurally appended to the base prompt using a clear Markdown separator.

3. Security & Robustness:

   • Prompt Injection Mitigation: Restricts template injection to primitive types (\string, \int, \tool) and sanitizes strings by stripping newlines.
   • Defensive Programming: Added nil checks for \InvocationMetadata\ and \Session\ references to prevent runtime panics.

4. Standards & Documentation:

   • Comprehensive Design Document added at \docs/design/system-prompt-templating.md.
   • All new tests follow project conventions (using \ .Parallel()).
   • Added verification and integration scripts for both mocked and real local LLMs (Ollama).

Implementation Details

• Core: New \agent/template.go\ and \agent/context.go.
• Integration: Updated \LLMAgent.resolveSystemPrompt\ to orchestrate resolution before model calls.
• Tests:
  • \agent/template_test.go: Unit tests for replacement logic and JSON safety.
  • \agent/llmagent/dynamic_prompt_test.go: Integration tests for metadata resolution.
  • \agent/llmagent/agenttool_propagation_test.go: End-to-end verification of global instruction flow through tool calls.

Verification

• Local verification script: \verify_features.go\
• Local Ollama test: \test_ollama.go\

Fixes #99

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.