Support prompt references (@file.txt and $`ls src`) for modes and agents

[mpazik]

Support for file references @file.txt and bash execution $`bash command` in agent markdown and mode configuration.

These features allow more complex context loading.

More about the feature on anthropic docs

https://docs.anthropic.com/en/docs/claude-code/common-workflows#reference-files-and-directories https://docs.anthropic.com/en/docs/claude-code/slash-commands#bash-command-execution

Implementation details

• Lazy execution when mode and agent are invoked
• Support nested include
• Break on circular dependencies
• Limit of 50000 tokens
• Custom error when prompt resoultion failed

Missing

• Documentation - added when
• Integration with https://github.com/sst/opencode/pull/1303 (easy)

Notes

• I had trouble providing a base directory for relative paths. My solution is not perfect as the path is included in the config schema, so users could possibly override it. An alternative was to have ConfigPriv with this extra path, but that would be overkill just for this single use case.
• Not a big fan of the prompt resolution place. Ideally, it would be resolved for both modes and agents inside the session/index.ts, but we don't pass the agent. Possible solutions:
  • Specialized chat for mode and chat for agent variant of the chat method
  • Mode and agent unified so we don't need to pass both of them
• Would be great to opt out from await SystemPrompt.custom() as sometimes it provides redundant or misleading information (I have agents that get custom dir structure)