Vision: make plugin workflows context-aware without leaking session state

[Q00]

Context

Issue #2 defines the immediate bridge: installed Ouroboros UserLevel plugins should be invokable from inside ourocode through direct ooo <plugin> ... prompts or natural language, without forcing users back into shell commands.

Once that bridge exists, the next product question is not only how do we run a plugin? It is what context should the plugin receive from the current ourocode session?

A user asking for a plugin workflow is often already inside a rich working state: a repository, an active task, recent messages, selected files, generated artifacts, failing tests, or a partially refined Seed. If plugin dispatch ignores that state, users still have to restate context manually. If dispatch passes too much context implicitly, it weakens trust boundaries and makes plugin behavior hard to explain.

Vision

Make plugin workflows context-aware, but never context-leaky.

ourocode should be able to hand an installed trusted plugin a deliberate context packet that explains the current workflow state:

• the user's current goal or prompt
• the current repository or working directory when relevant
• selected files, mentions, or artifacts referenced in the session
• recent workflow outputs such as generated Seeds or handoff documents
• test/build failure summaries when they are part of the active task
• explicit constraints from the current session

That context should be reviewable, bounded, and governed by plugin capability policy. A plugin should not receive the entire terminal session, filesystem, or hidden state just because the user mentioned it in natural language.

Product Direction

Add a context handoff layer between plugin intent resolution and plugin dispatch:

1. Build a normalized PluginContext shape for the subset of session state that may be passed to UserLevel plugins.
2. Let direct commands and natural-language plugin intents attach the same context model.
3. Include only context that is relevant, explicit, or policy-approved.
4. Show a compact context preview for workflow-producing or write-capable plugin commands.
5. Allow read-only inspection commands to run with little or no session context by default.
6. Record which context was passed so generated artifacts can be traced back to the user-approved input state.
7. Keep plugin-specific context adapters out of the terminal event loop; plugins should consume a stable contract rather than hidden ourocode internals.

Why This Matters

The best plugin-native workflow should feel like continuing the current work, not starting over in a separate tool.

For example, after discussing a refactor in ourocode, a user should be able to type:

Use Superpowers test-driven-development for this refactor.

ourocode should know what "this refactor" means only to the extent that the current session has made it explicit and policy allows that context to be shared. The plugin then receives a focused, auditable context packet instead of requiring the user to retype everything or silently receiving too much.

This makes plugin dispatch more useful while preserving the trust model:

• users do less manual context copying
• plugin outputs become easier to explain and reproduce
• artifact provenance includes the input context, not just the command string
• sensitive or irrelevant session state is not leaked by default
• tests can assert exactly what context crosses the plugin boundary

Acceptance Criteria

• ourocode has a normalized representation for plugin context handoff.
• Plugin dispatch can attach current goal text, explicit file mentions, selected artifacts, and relevant failure summaries when policy allows.
• The context packet is bounded and reviewable for handoff-producing, write-capable, or higher-risk plugin commands.
• Read-only plugin commands do not receive broad session context unless explicitly requested or required by the command contract.
• Context passed to a plugin is recorded in session or journal state for auditability and artifact provenance.
• Natural-language references such as "this refactor" or "the generated Seed" resolve only when there is clear session state to bind them to; otherwise ourocode asks for clarification instead of guessing.
• Tests cover explicit file mentions, generated artifact references, omitted sensitive context, missing/ambiguous context, and provenance recording.

Non-goals

• Passing the full terminal transcript to every plugin.
• Granting filesystem access beyond the plugin's declared and trusted capabilities.
• Designing a full secrets redaction system in this issue.
• Making plugins depend on private ourocode data structures.
• Replacing the trust/firewall semantics defined by Ouroboros.

Related

• Builds on Support natural-language dispatch for installed Ouroboros UserLevel plugins #2.
• Complements Vision: preview plugin side effects before workflow execution #21 by focusing on what context crosses the plugin boundary, while Vision: preview plugin side effects before workflow execution #21 focuses on previewing side effects before execution.
• Complements Vision: make plugin workflow decisions observable and auditable #10 by making context handoff auditable as part of workflow provenance.