Make the headless system-prompt preamble configurable (it forbids asking questions)

[sepehr500]

Summary

The runtime prepends a hardcoded "headless mode … never ask questions, never wait for user input" preamble to every agent's system prompt. Please make it configurable (override or disable) so agents that do have a reachable human can ask for clarification on genuinely ambiguous requests.

Background & Motivation

composeSystemPrompt in packages/runtime/src/context.ts starts every system prompt with a fixed HEADLESS_PREAMBLE:

"You are running in headless mode with no human operator. Work autonomously — never ask questions, never wait for user input. Make your best judgment and proceed independently."

It's prepended before the agent's own instructions, so it takes precedence in practice.

That's a sensible default for truly headless/workflow agents. But a large class of Flue agents built on dispatch() are connected to a real human channel. We run an engineering agent on Flue dispatched from Linear and Slack, where the user is very much reachable — our ask_user tool emits a Linear agent-session elicitation that pauses the session until the human replies. For an agent like that, "never ask questions, never wait for user input" is actively the wrong instruction: on a vague or underspecified request, the correct behavior is to ask one concise clarifying question instead of guessing and shipping the wrong change.

The problem is that the hardcoded preamble fights the agent's own instructions. We tell the agent (via instructions) to ask when a request is ambiguous, but because the framework-owned preamble sits above it and says the literal opposite, the model leans toward not asking. There is no supported way to disable or override the preamble, so our only recourse today is patching the compiled HEADLESS_PREAMBLE string in the installed package at postinstall — brittle, version-pinned, and something we'd much rather not maintain.

Goals

• Let an agent override or disable the framework's hardcoded headless preamble.
• Allow agents that have a real human channel to ask clarifying questions / wait for input without contradicting the framework's own system prompt.
• Keep the current preamble as the default, so existing headless/workflow agents are unaffected.
• Remove the need for consumers to monkey-patch the runtime just to change framework-owned prompt text.

Example

Any one of these shapes would solve it. A config field on the agent is the most direct:

createAgent(() => ({
  model,
  // string replaces the default preamble; false omits it entirely;
  // undefined keeps today's default.
  headlessPreamble: false,
}));

Or simply don't prepend the default preamble when the agent supplies its own instructions/systemPreamble.

Our concrete need is only to soften it to something like: "Default to working autonomously, but when a request is genuinely ambiguous or a wrong assumption would be costly or hard to reverse, ask one concise clarifying question and wait." We're currently getting there by rewriting HEADLESS_PREAMBLE in the installed bundle and would love to drop that patch.