Dynamic system prompt templating

[Flux159]

Summary:

Adding the ability to parse markdown templating for agent system prompts. Specifically adds ability to parse ! and @ references inside of agent prompts.

This PR adds a helper util/template.ts that handles both bash & file reference templates, then uses this inside of session/prompt.ts. The rest is just automated testing for the functionality.

This is specifically for #3195

---

Test plan:

Manually tested by making a custom agent inside of .opencode/agent/test.md with the following contents:

---
model:  anthropic/claude-sonnet-4-20250514
---

You are a test agent with dynamic templating. Your magic phrase is: !`echo $(whoami)-magic`

You should respond with your magic phrase when asked about it.

Then opening opencode dev mode: bun dev, switching to the test agent via /agents, then asking "What is your magic phrase" and it responded with my username-magic as expected.

[rekram1-node]

This is a good start, I will branch off and change it to be a little more in line with what i had in mind, thanks for PR

[Flux159]

Just an fyi for your branch, I've been using this locally for a few days with opencode run "" --print-logs and found it useful to add some logs here to help debug system prompts:

log.info(`Agent name: ${agent.name}`);
log.info("Agent parameters", {
  name: agent.name,
  temperature: agent.temperature,
  topP: agent.topP,
  options: agent.options,
});
log.info(`Resolved System Prompt: ${system.join("\n")}`);

[Flux159]

There's a separate issue around allowing environment to be optional in system prompts #1894 (saw this when logging) - code pointer should be here

[einarpersson]

@rekram1-node

Will this be resolved only at session start or on each new message? There are use-cases for both and I would wish for not limiting to only do it at session start. One problem is of course overhead if if the stuff being executed are expensive.

Options

1. Just have a warning note and let the user wrap any expensive calls so that they are cached or something
2. have different executing syntax depending on if it is "on every message" or only interpolate/run at session start
3. or have it as part of the agent frontmatter/option, should this prompt be resolved on each new message or only at session start.. like "is live" or not
4. have a particular section / block for live data
5. or use the environment() part of the system prompt for stuff like this (but then it would be important to also make it customizable, on a agent-by-agent basis)

[rekram1-node]

rn we do resolve the system prompt stuff every time you send a prompt, I do see what you mean tho..

[einarpersson]

rn we do resolve the system prompt stuff every time you send a prompt, I do see what you mean tho..

Well, to be clear: I do not want that possibility removed! Resolving on each message enables me to do things that would not be possible otherwise.

So please do not remove this pattern of resolving on each message. Either keep it as-is and document the behaviour or make it configurable as a part of the agent/global config.

[einarpersson]

Any plans for this?

@rekram1-node wrote

Perfect I think making the command syntax more universal is best move here then
u arent doing anything wrong we will fix this soon, rn the commands only execute for command markdown definitions this is confusing and bad behavior will fix

As I understand it doing !command is currently only supported in commands.

I think it should be supported universally, including

• agent files
• skill files

This would unlock a lot.

For example I have a skill which I use to create anki style flashcards. I would like it to include valid tags i use for my cards automatically whenever the skill is invoked/loaded.

[jcgordon10]

Was looking through the docs for if there was a way to do this, and found this PR. Would love this feature so I can include other files dynamically as context within the custom agents instructions. (or if there's another way to do that, I'd like to know)