summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.hermes-plugin/__init__.py6
-rw-r--r--.opencode/plugins/superpowers.js16
-rw-r--r--.pi/extensions/superpowers.ts7
-rw-r--r--docs/README.opencode.md4
-rw-r--r--docs/porting-to-a-new-harness.md15
-rw-r--r--tests/hermes/test_plugin.py18
-rw-r--r--tests/opencode/test-bootstrap-caching.mjs22
-rw-r--r--tests/opencode/test-session-bootstrap.mjs10
-rw-r--r--tests/pi/test-pi-extension.mjs49
9 files changed, 120 insertions, 27 deletions
diff --git a/.hermes-plugin/__init__.py b/.hermes-plugin/__init__.py
index 7d4e1f5..3c5a207 100644
--- a/.hermes-plugin/__init__.py
+++ b/.hermes-plugin/__init__.py
@@ -108,7 +108,9 @@ def register(ctx):
# pre_llm_call returning {"context": ...} is the documented injection path
# (on_session_start return values are ignored, and ctx.inject_message
# refuses from that hook — verified empirically 2026-07-23). The context is
- # appended to the first turn's user message.
+ # appended to the first turn's user message. delegate_task children run
+ # with platform="subagent" and an empty history, so every child's first
+ # turn would otherwise get the controller bootstrap too.
def pre_llm_call(
session_id=None,
user_message=None,
@@ -118,7 +120,7 @@ def register(ctx):
platform=None,
**kwargs,
):
- if is_first_turn:
+ if is_first_turn and platform != "subagent":
return {"context": bootstrap}
return None
diff --git a/.opencode/plugins/superpowers.js b/.opencode/plugins/superpowers.js
index 9659e80..d39c1ec 100644
--- a/.opencode/plugins/superpowers.js
+++ b/.opencode/plugins/superpowers.js
@@ -79,7 +79,7 @@ export const V1_MAPPING = `**Tool Mapping for OpenCode:**
When skills request actions, substitute OpenCode equivalents:
- Create or update todos → \`todowrite\`
- \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
-- Invoke a skill → OpenCode's native \`skill\` tool
+- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`name: "brainstorming"\`)
- Read files → \`read\`
- Create, edit, or delete files → \`apply_patch\`
- Run shell commands → \`bash\`
@@ -97,7 +97,7 @@ export const V2_MAPPING = `**Tool Mapping for OpenCode:**
When skills request actions, substitute OpenCode equivalents:
- Create or update todos → OpenCode v2 has no todo tool; track the plan in a markdown file (or the harness's plan facility) instead
- \`Subagent (general-purpose):\` → \`subagent\` with \`agent: "general"\` (give it \`description\` and \`prompt\`, optionally \`background\`; pass \`sessionID\` to continue a previous subagent)
-- Invoke a skill → OpenCode's native \`skill\` tool
+- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`id: "brainstorming"\`)
- Read files → \`read\`
- Create, edit, or delete files → use \`patch\` with \`patchText\` when available; otherwise use \`write\` to create or overwrite files, \`edit\` for targeted changes, and \`shell\` for deletion
- Run shell commands → \`shell\` (\`command\`, \`workdir\`, \`timeout\`, \`background\`)
@@ -113,6 +113,11 @@ Use OpenCode's native \`skill\` tool to list and load skills.`;
// regex work on every agent step. See #1202 for the full analysis.
const _bootstrapCache = new Map(); // mapping -> bootstrap (null = file missing)
+// Opening of every injected bootstrap part. The already-injected guards match
+// it at the start of a part, so a prompt that merely mentions the tag (#2197)
+// is not mistaken for the bootstrap.
+const BOOTSTRAP_MARKER = '<EXTREMELY_IMPORTANT>\nYou have superpowers.';
+
// Helper to generate bootstrap content (cached after first call per mapping)
const getBootstrapContent = (toolMapping) => {
// Return cached result on subsequent calls
@@ -128,8 +133,7 @@ const getBootstrapContent = (toolMapping) => {
const fullContent = fs.readFileSync(skillPath, 'utf8');
const { content } = extractAndStripFrontmatter(fullContent);
- _bootstrapCache.set(toolMapping, `<EXTREMELY_IMPORTANT>
-You have superpowers.
+ _bootstrapCache.set(toolMapping, `${BOOTSTRAP_MARKER}
**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
@@ -249,7 +253,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
if (!firstUser || !firstUser.parts.length) return;
// Guard: skip if first user message already contains bootstrap.
- if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+ if (firstUser.parts.some(p => p.type === 'text' && p.text.startsWith(BOOTSTRAP_MARKER))) return;
// #2160: never restart the controller workflow inside task subagent
// (child) sessions. V1 passes no input to this hook (verified in the
@@ -356,7 +360,7 @@ async function setup(ctx) {
if (!bootstrap || !event.messages || !event.messages.length) return;
const firstUser = event.messages.find(m => m.role === 'user');
if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
- if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+ if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.startsWith(BOOTSTRAP_MARKER))) return;
// #2160: the request event carries the sessionID directly. Skip the
// controller bootstrap when this prompt belongs to a task subagent
diff --git a/.pi/extensions/superpowers.ts b/.pi/extensions/superpowers.ts
index 2e948e9..3b38adf 100644
--- a/.pi/extensions/superpowers.ts
+++ b/.pi/extensions/superpowers.ts
@@ -24,10 +24,9 @@ export default function superpowersPiExtension(pi: ExtensionAPI) {
injectBootstrap = true;
});
- pi.on("agent_end", async () => {
- injectBootstrap = false;
- });
-
+ // Messages returned from a context handler are sent to the provider but never
+ // written to session history, so the bootstrap has to be injected into every
+ // provider request, on every prompt, for the whole session.
pi.on("context", async (event) => {
if (!injectBootstrap) return;
if (event.messages.some(messageContainsBootstrap)) return;
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 35e8226..252e2b5 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -148,7 +148,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" / "mark complete in todo list" → `todowrite`
- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill name (`superpowers:brainstorming` → `name: "brainstorming"`)
- "Read a file" → `read`
- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
- "Run a shell command" → `bash`
@@ -159,7 +159,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead
- `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill id (`superpowers:brainstorming` → `id: "brainstorming"`)
- "Read a file" → `read`
- "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion
- "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`)
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index fa99a23..a48ecdf 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -428,10 +428,9 @@ messages break some models (#894). Three things you must replicate:
harness-specific constant.) Cache the bootstrap content at module level so
you're not re-reading and re-parsing `SKILL.md` on every call (#1202).
- **Compaction.** If the harness compacts/summarizes history, re-inject
- afterward. pi sets an `injectBootstrap` flag on `session_start` and
- `session_compact`, clears it on `agent_end`, and inserts the message *after*
- any leading compaction-summary messages. OpenCode relies on its per-step
- re-injection plus the dedup guard.
+ afterward. pi re-injects on every `context` call and inserts the message
+ *after* any leading compaction-summary messages. OpenCode relies on its
+ per-step re-injection plus the dedup guard.
- **Message-object shape is per-harness — discover yours, don't copy a literal.**
The two references use *incompatible* shapes: pi builds
`{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates
@@ -827,9 +826,11 @@ Use this as the live index; when in doubt, read the files, not this table.
(Cursor). Use what your harness exports; the script re-derives the root itself.
- **System-message injection.** Shape B injects a *user* message on purpose
(#750, #894). Don't "fix" it to a system message.
-- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup
- guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one
- harness's dedup strategy onto the other's callback frequency breaks injection.
+- **Disarming injection after the first prompt.** If your harness's transform
+ output is not saved to session history (pi's `context` result is not), the
+ bootstrap must be injected into every provider request. A flag cleared on a
+ per-prompt event such as pi's `agent_end` drops the bootstrap after the first
+ prompt (#2083).
- **Message-object shape is per-harness.** Shape B. pi and OpenCode use
incompatible shapes; discover yours, don't copy a reference's object literal.
- **Hunting for a skill-registration API that doesn't exist.** A harness with no
diff --git a/tests/hermes/test_plugin.py b/tests/hermes/test_plugin.py
index 57d619e..7c896a3 100644
--- a/tests/hermes/test_plugin.py
+++ b/tests/hermes/test_plugin.py
@@ -87,6 +87,24 @@ class TestBootstrapInjection:
assert _fire_pre_llm(mock_ctx, is_first_turn=False) is None
assert _fire_pre_llm(mock_ctx, is_first_turn=None) is None
+ def test_subagent_platform_skips_bootstrap_on_first_turn(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ assert (
+ _fire_pre_llm(mock_ctx, is_first_turn=True, platform="subagent")
+ is None
+ )
+
+ def test_non_subagent_platforms_receive_bootstrap(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ for platform in ("cli", "desktop", "cron", "telegram"):
+ result = _fire_pre_llm(
+ mock_ctx, is_first_turn=True, platform=platform
+ )
+ assert isinstance(result, dict)
+ assert BOOTSTRAP_MARKER in result["context"]
+
def test_hook_tolerates_future_kwargs(self, mock_ctx):
plugin = _load_plugin()
plugin.register(mock_ctx)
diff --git a/tests/opencode/test-bootstrap-caching.mjs b/tests/opencode/test-bootstrap-caching.mjs
index 386b7b1..39e4daa 100644
--- a/tests/opencode/test-bootstrap-caching.mjs
+++ b/tests/opencode/test-bootstrap-caching.mjs
@@ -76,6 +76,9 @@ const failures = scenario === 'present'
if (scenario === 'present') {
failures.push(...assertV2Bootstrap(result));
+ // #2583: both flavors register bare skill ids and look them up exactly.
+ failures.push(...assertTeachesBareSkillIds('V1', bootstrapText(firstOutput), 'name'));
+ failures.push(...assertTeachesBareSkillIds('V2', v2Result.text, 'id'));
}
failures.push(...mappingFailures);
@@ -202,6 +205,25 @@ function assertMappingConstants(mod) {
return failures;
}
+// #2583: skills reference each other as `superpowers:<name>` (the Claude Code
+// plugin namespace), but OpenCode V1 and V2 register bare ids (`brainstorming`)
+// and their `skill` tools do an exact lookup, so a namespaced call fails with
+// "Unable to load skill". When the injected bootstrap contains namespaced
+// references, its tool mapping must tell the model to drop the prefix, using
+// the flavor's `skill` parameter (V1 `name`, V2 `id`).
+function assertTeachesBareSkillIds(flavor, text, param) {
+ const failures = [];
+ const refs = [...new Set(text.match(/superpowers:[a-z0-9-]+/g) || [])];
+ if (refs.length === 0) return failures;
+ if (!text.includes('drop the `superpowers:` prefix')) {
+ failures.push(`expected ${flavor} bootstrap to tell the model to drop the superpowers: prefix (bootstrap references ${refs.join(', ')})`);
+ }
+ if (!text.includes(`\`superpowers:brainstorming\` → \`skill\` with \`${param}: "brainstorming"\``)) {
+ failures.push(`expected ${flavor} bootstrap to show superpowers:brainstorming loading as \`skill\` with \`${param}: "brainstorming"\``);
+ }
+ return failures;
+}
+
// Drive setup() with a mock V2 ctx and fire the captured "context" hook on a
// top-level (parentID-less) session. Returns the injected-part count and the
// injected bootstrap text ('' when nothing was injected).
diff --git a/tests/opencode/test-session-bootstrap.mjs b/tests/opencode/test-session-bootstrap.mjs
index 31658d5..67b3118 100644
--- a/tests/opencode/test-session-bootstrap.mjs
+++ b/tests/opencode/test-session-bootstrap.mjs
@@ -139,6 +139,16 @@ for (const flavor of ['v1', 'v2']) {
await unknown.invoke(noID);
assert.equal(bootstrapCount(noID), 1);
assert.deepEqual(unknown.lookups, []);
+
+ // #2197: a prompt that merely mentions the bootstrap's tag is not the bootstrap.
+ const mentions = await makeHarness(flavor, (id) => reply(flavor, { id }));
+ const probe = makeEvent(flavor, `${flavor}-mentions-tag`);
+ (probe.messages[0].parts ?? probe.messages[0].content)[0].text =
+ "Is there an 'EXTREMELY_IMPORTANT' block in your context?";
+ await mentions.invoke(probe);
+ assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag still gets bootstrap`);
+ await mentions.invoke(probe);
+ assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag, repeated event`);
}
function compactedEvent(sessionID) {
diff --git a/tests/pi/test-pi-extension.mjs b/tests/pi/test-pi-extension.mjs
index c79f710..65d65e0 100644
--- a/tests/pi/test-pi-extension.mjs
+++ b/tests/pi/test-pi-extension.mjs
@@ -34,6 +34,14 @@ function firstHandler(handlers, event) {
return eventHandlers[0];
}
+// Fire an event the way pi does: every registered handler runs, and an event
+// the extension does not subscribe to is a no-op.
+async function emit(handlers, event, payload) {
+ for (const handler of handlers.get(event) ?? []) {
+ await handler({ type: event, ...payload }, {});
+ }
+}
+
function textOf(message) {
if (typeof message.content === 'string') return message.content;
return message.content
@@ -55,17 +63,16 @@ test('extension leaves package skill discovery to Pi and registers lifecycle hoo
const { handlers } = await loadExtension();
assert.equal((handlers.get('resources_discover') ?? []).length, 0, 'extension must not bypass package skill filters');
- for (const event of ['session_start', 'session_compact', 'context', 'agent_end']) {
+ for (const event of ['session_start', 'session_compact', 'context']) {
assert.equal((handlers.get(event) ?? []).length, 1, `missing ${event} handler`);
}
assert.equal((handlers.get('session_before_compact') ?? []).length, 0);
});
-test('startup context injects the bootstrap as one user message until agent_end', async () => {
+test('startup context injects the bootstrap as one user message', async () => {
const { handlers } = await loadExtension();
const sessionStart = firstHandler(handlers, 'session_start');
const context = firstHandler(handlers, 'context');
- const agentEnd = firstHandler(handlers, 'agent_end');
await sessionStart({ type: 'session_start', reason: 'startup' }, {});
@@ -86,10 +93,40 @@ test('startup context injects the bootstrap as one user message until agent_end'
const alreadyInjected = await context({ type: 'context', messages: result.messages }, {});
assert.equal(alreadyInjected, undefined, 'bootstrap should not duplicate when already present');
+});
+
+// pi emits agent_start/agent_end around every user prompt, not once per
+// session, and the messages a context handler returns are never written back
+// to session history. So every provider request of every prompt needs the
+// bootstrap injected again (#2083).
+test('every provider request of every prompt in a session carries the bootstrap', async () => {
+ const { handlers } = await loadExtension();
+ const context = firstHandler(handlers, 'context');
+
+ await emit(handlers, 'session_start', { reason: 'startup' });
- await agentEnd({ type: 'agent_end', messages: [] }, {});
- const afterEnd = await context({ type: 'context', messages: originalMessages }, {});
- assert.equal(afterEnd, undefined, 'startup bootstrap should clear after agent_end');
+ const history = [];
+ const prompts = [
+ { text: 'first prompt', providerRequests: 1 },
+ { text: 'second prompt with a tool call', providerRequests: 2 },
+ { text: 'third prompt', providerRequests: 1 },
+ ];
+ for (const [promptIndex, prompt] of prompts.entries()) {
+ history.push({ role: 'user', content: [{ type: 'text', text: prompt.text }], timestamp: promptIndex });
+ await emit(handlers, 'agent_start', {});
+ for (let request = 1; request <= prompt.providerRequests; request += 1) {
+ await emit(handlers, 'turn_start', {});
+ const result = await context({ type: 'context', messages: structuredClone(history) }, {});
+ const label = `prompt ${promptIndex + 1}, provider request ${request}`;
+ assert.ok(result, `${label}: bootstrap missing`);
+ assert.equal(result.messages.length, history.length + 1, `${label}: expected exactly one bootstrap message`);
+ assert.match(textOf(result.messages[0]), /You have superpowers/, `${label}: bootstrap not first`);
+ history.push({ role: 'assistant', content: [{ type: 'text', text: 'ok' }], timestamp: promptIndex });
+ await emit(handlers, 'turn_end', {});
+ }
+ await emit(handlers, 'agent_end', { messages: [] });
+ await emit(handlers, 'agent_settled', {});
+ }
});
test('session_compact injects bootstrap after compaction summaries, not before compaction', async () => {