feat(plugins): append agent instructions on session open

Recompute plugin instructions for each launch so changes apply on reopen without changing saved agent configuration.
This commit is contained in:
Mohamed Boudra
2026-11-15 14:58:54 +01:00
parent c4ff5599c7
commit 8214ebceaf
20 changed files with 306 additions and 39 deletions
+2
View File
@@ -88,6 +88,8 @@ export interface PluginSessionOpenRequest {
readonly background: boolean;
readonly labels: Readonly<Record<string, string>>;
readonly metadata: Readonly<Record<string, JsonValue>>;
/** Instructions appended for this open; not saved on the agent. */
appendSystemPrompt?: string[];
tools: AgentToolDefinition[];
env: Record<string, string>;
mcpServers: NonNullable<AgentSessionConfig["mcpServers"]>;
@@ -14523,3 +14523,69 @@ test("idle cleanup gives a newly restored runtime a fresh idle window while keep
expect((await h.sweep({ now: h.later(61) })).collected).toHaveLength(1);
expect(h.closes).toBe(closesBeforeRestore + 1);
});
test("plugin instructions are recomputed for each launch without changing saved config", async () => {
const workdir = mkdtempSync(join(tmpdir(), "agent-plugin-prompt-"));
const storage = new AgentStorage(join(workdir, "agents"), logger);
const client = new TestAgentClient();
let additions = ["Plugin one", "Plugin two"];
const manager = new AgentManager({
clients: { codex: client },
registry: storage,
logger,
appendSystemPrompt: "Daemon",
pluginLifecycle: {
emit: () => {},
before: async (name, request) =>
name === "agent.open.before" ? { ...request, appendSystemPrompt: additions } : request,
},
});
const snapshot = await manager.createAgent(
{ provider: "codex", cwd: workdir, systemPrompt: "Saved" },
undefined,
{ workspaceId: undefined },
);
expect(client.createdConfigs[0]).toMatchObject({
systemPrompt: "Saved",
daemonAppendSystemPrompt: "Daemon",
pluginAppendSystemPrompt: ["Plugin one", "Plugin two"],
});
expect(snapshot.config.systemPrompt).toBe("Saved");
expect((await storage.get(snapshot.id))?.config?.systemPrompt).toBe("Saved");
const handle: AgentPersistenceHandle = {
provider: "codex",
sessionId: "prompt-session",
metadata: { provider: "codex", cwd: workdir, systemPrompt: "Saved" },
};
await manager.closeAgent(snapshot.id);
await manager.resumeAgentFromPersistence(
handle,
{ cwd: workdir, systemPrompt: "Saved" },
snapshot.id,
);
expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual([
"Plugin one",
"Plugin two",
]);
additions = ["Changed"];
await manager.closeAgent(snapshot.id);
await manager.resumeAgentFromPersistence(
handle,
{ cwd: workdir, systemPrompt: "Saved" },
snapshot.id,
);
expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual(["Changed"]);
additions = ["Refreshed"];
await manager.reloadAgentSession(snapshot.id);
expect(client.resumeOverrides.at(-1)?.pluginAppendSystemPrompt).toEqual(["Refreshed"]);
additions = [];
await manager.closeAgent(snapshot.id);
await manager.resumeAgentFromPersistence(
handle,
{ cwd: workdir, systemPrompt: "Saved" },
snapshot.id,
);
expect(client.resumeOverrides.at(-1)?.systemPrompt).toBe("Saved");
expect(client.resumeOverrides.at(-1)?.daemonAppendSystemPrompt).toBe("Daemon");
expect((await storage.get(snapshot.id))?.config?.systemPrompt).toBe("Saved");
});
@@ -6168,6 +6168,7 @@ export class AgentManager {
// A plugin changing during this open must still make the resulting session stale.
const generation = this.sessionOpenGeneration;
this.detachPluginTools(agentId);
let appendSystemPrompt: string[] | undefined;
let mcpServers: AgentSessionConfig["mcpServers"];
let mcpServerOwners: Record<string, string> | undefined;
if (this.pluginLifecycle) {
@@ -6189,12 +6190,14 @@ export class AgentManager {
env = transformed.env;
if (request.purpose === "interactive") {
this.attachedPluginTools.set(agentId, transformed.tools as AttachedAgentTool[]);
appendSystemPrompt = transformed.appendSystemPrompt;
mcpServers = transformed.mcpServers;
mcpServerOwners = transformed.mcpServerOwners;
}
}
const context: AgentLaunchContext = {
agentId,
...pluginPromptContext(appendSystemPrompt),
mcpServers,
mcpServerOwners,
env: {
@@ -6241,6 +6244,7 @@ export class AgentManager {
throw new Error(`MCP server '${name}' from plugin ${owner} collides with ${existingOwner}`);
}
}
launchConfig = { ...launchConfig, pluginAppendSystemPrompt: launchContext.appendSystemPrompt };
const merged =
Object.keys(launchContext.mcpServers ?? {}).length > 0
? {
@@ -6378,3 +6382,9 @@ export function commandMayHaveChangedExternalState(command: string): boolean {
/\bgit\s+fetch\b/.test(normalized)
);
}
function pluginPromptContext(
appendSystemPrompt: string[] | undefined,
): Pick<AgentLaunchContext, "appendSystemPrompt"> {
return appendSystemPrompt?.length ? { appendSystemPrompt } : {};
}
@@ -621,6 +621,8 @@ export interface AgentSessionConfig {
* persisted into agent config so daemon setting changes apply cleanly.
*/
daemonAppendSystemPrompt?: string;
/** Plugin instructions for this launch; never persisted. */
pluginAppendSystemPrompt?: string[];
modeId?: string;
model?: string;
thinkingOptionId?: string;
@@ -636,6 +638,8 @@ export interface AgentSessionConfig {
}
export interface AgentLaunchContext {
/** Launch-only instructions contributed by plugins. */
appendSystemPrompt?: string[];
/** Launch-only plugin MCP servers and their owners; never persisted. */
mcpServers?: Record<string, McpServerConfig>;
mcpServerOwners?: Record<string, string>;
@@ -1949,7 +1949,11 @@ function mapSessionConfig(
return {
cwd: config.cwd,
env: createProviderEnv({ baseEnv: {}, overlays: [launchContext?.env] }),
systemPrompt: combineSystemPrompts(config.systemPrompt, config.daemonAppendSystemPrompt),
systemPrompt: combineSystemPrompts(
config.systemPrompt,
config.daemonAppendSystemPrompt,
...(config.pluginAppendSystemPrompt ?? []),
),
mcpServers: { ...config.mcpServers },
toolPolicy: config.toolPolicy
? { preapproved: config.toolPolicy.preapproved.map((grant) => ({ ...grant })) }
@@ -1968,8 +1972,9 @@ function mapSessionConfig(
function combineSystemPrompts(
systemPrompt: string | undefined,
daemonPrompt: string | undefined,
...pluginPrompts: string[]
): string | undefined {
const parts = [systemPrompt, daemonPrompt].filter(
const parts = [systemPrompt, daemonPrompt, ...pluginPrompts].filter(
(value): value is string => typeof value === "string" && value.trim().length > 0,
);
return parts.length > 0 ? parts.join("\n\n") : undefined;
@@ -3044,7 +3044,11 @@ class ClaudeAgentSession implements AgentSession {
if (!this.claudeSessionId) {
return null;
}
const { providerOptions: _providerOptions, ...persistedConfig } = this.config;
const {
providerOptions: _providerOptions,
pluginAppendSystemPrompt: _pluginAppendSystemPrompt,
...persistedConfig
} = this.config;
this.persistence = {
provider: "claude",
sessionId: this.claudeSessionId,
@@ -3712,7 +3716,11 @@ class ClaudeAgentSession implements AgentSession {
private buildAppendedSystemPrompt(): string {
return (
composeSystemPromptParts(this.config.systemPrompt, this.config.daemonAppendSystemPrompt) ?? ""
composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
) ?? ""
);
}
@@ -4047,6 +4047,7 @@ export class CodexAppServerAgentSession implements AgentSession {
match.developer_instructions,
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
if (developerInstructions) settings.developer_instructions = developerInstructions;
if (this.config.model) settings.model = this.config.model;
@@ -4311,6 +4312,7 @@ export class CodexAppServerAgentSession implements AgentSession {
const developerInstructions = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
if (developerInstructions) {
params.developerInstructions = developerInstructions;
@@ -4464,6 +4466,7 @@ export class CodexAppServerAgentSession implements AgentSession {
const developerInstructions = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
if (developerInstructions) {
params.developerInstructions = developerInstructions;
@@ -5806,6 +5809,7 @@ export class CodexAppServerAgentSession implements AgentSession {
const developerInstructions = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
const params: Record<string, unknown> = {
model,
@@ -466,6 +466,7 @@ function buildResumeStartInput(input: {
systemPrompt: composeSystemPromptParts(
input.resumeConfig.config.systemPrompt,
input.resumeConfig.config.daemonAppendSystemPrompt,
...(input.resumeConfig.config.pluginAppendSystemPrompt ?? []),
),
};
}
@@ -2370,7 +2371,11 @@ export class OmpAgentClient implements AgentClient {
noSession: config.internal === true,
modeId: launchMode.modeId,
extraArgs: launchMode.extraArgs,
systemPrompt: composeSystemPromptParts(config.systemPrompt, config.daemonAppendSystemPrompt),
systemPrompt: composeSystemPromptParts(
config.systemPrompt,
config.daemonAppendSystemPrompt,
...(config.pluginAppendSystemPrompt ?? []),
),
env: launchContext?.env,
};
const runtimeSession = await this.resolveRuntime(config.providerOptions).startSession(
@@ -3692,6 +3692,7 @@ class OpenCodeAgentSession implements AgentSession {
const systemPrompt = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
const model = this.parseModel(this.config.model);
const effectiveMode = resolveOpenCodeRuntimeAgentId(this.currentMode);
@@ -4029,6 +4030,7 @@ class OpenCodeAgentSession implements AgentSession {
const systemPrompt = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
const promptResponse = await this.client.session.promptAsync({
sessionID: this.sessionId,
@@ -28,6 +28,7 @@ export class V2Harness {
readonly prompts: string[] = [];
readonly environments: Array<{ sessionID: string; variables: Record<string, string> }> = [];
readonly mcpAdds: string[] = [];
readonly instructions = new Map<string, string>();
releases = 0;
active = false;
activeReads = 0;
@@ -153,7 +154,17 @@ export class V2Harness {
environment: async (input) => {
this.environments.push(input);
},
instructions: { entry: { list: unexpected, put: unexpected, remove: unexpected } },
instructions: {
entry: {
list: async () => [...this.instructions].map(([key, value]) => ({ key, value })),
put: async ({ key, value }) => {
this.instructions.set(key, String(value));
},
remove: async ({ key }) => {
this.instructions.delete(key);
},
},
},
prompt: async (input, options) => {
const before = this.executions.length;
await this.prompt(input, options);
@@ -17,6 +17,34 @@ function terminalEvents(events: AgentStreamEvent[]) {
}
describe("OpenCode v2 session lifecycle", () => {
test("reopening replaces and removes plugin instructions", async () => {
const harness = new V2Harness();
const client = new OpenCodeV2AgentClient({
logger: createTestLogger(),
runtime: harness.runtime,
});
const created = await client.createSession({
provider: "opencode",
cwd: "/tmp/project",
pluginAppendSystemPrompt: ["first"],
});
expect(harness.instructions.get("paseo")).toBe("first");
const handle = created.describePersistence()!;
await created.close();
const resumed = await client.resumeSession(handle, {
cwd: "/tmp/project",
pluginAppendSystemPrompt: ["changed"],
});
expect(harness.instructions.get("paseo")).toBe("changed");
await resumed.close();
const cleared = await client.resumeSession(handle, {
cwd: "/tmp/project",
pluginAppendSystemPrompt: undefined,
});
expect(harness.instructions.has("paseo")).toBe(false);
await cleared.close();
});
test("refreshes the existing location before reading a forced catalog", async () => {
const harness = new V2Harness();
const refreshed: string[] = [];
@@ -196,13 +196,20 @@ export class OpenCodeV2Session implements AgentSession {
const system = composeSystemPromptParts(
this.config.systemPrompt,
this.config.daemonAppendSystemPrompt,
...(this.config.pluginAppendSystemPrompt ?? []),
);
if (system)
if (system) {
await this.client.session.instructions.entry.put({
sessionID: this.id,
key: "paseo",
value: system,
});
} else {
const entries = await this.client.session.instructions.entry.list({ sessionID: this.id });
if (entries.some((entry) => entry.key === "paseo")) {
await this.client.session.instructions.entry.remove({ sessionID: this.id, key: "paseo" });
}
}
}
private async startStream() {
let ready!: () => void;
@@ -1892,6 +1892,7 @@ describe("PiRpcAgentSession", () => {
createConfig({
systemPrompt: "Agent prompt",
daemonAppendSystemPrompt: "Daemon prompt",
pluginAppendSystemPrompt: ["Plugin one", "Plugin two"],
}),
);
@@ -1910,7 +1911,9 @@ describe("PiRpcAgentSession", () => {
await expect(
applyPaseoExtensionSystemPrompt(actualLaunch.extensionPaths[0]!, "Pi project prompt"),
).resolves.toBe("Pi project prompt\n\nAgent prompt\n\nDaemon prompt");
).resolves.toBe(
"Pi project prompt\n\nAgent prompt\n\nDaemon prompt\n\nPlugin one\n\nPlugin two",
);
await session.close();
});
@@ -1933,6 +1936,7 @@ describe("PiRpcAgentSession", () => {
},
{
daemonAppendSystemPrompt: "Daemon prompt",
pluginAppendSystemPrompt: ["Plugin one", "Plugin two"],
},
);
@@ -1956,7 +1960,9 @@ describe("PiRpcAgentSession", () => {
]);
await expect(
applyPaseoExtensionSystemPrompt(actualLaunch.extensionPaths[0]!, "Pi project prompt"),
).resolves.toBe("Pi project prompt\n\nAgent prompt\n\nDaemon prompt");
).resolves.toBe(
"Pi project prompt\n\nAgent prompt\n\nDaemon prompt\n\nPlugin one\n\nPlugin two",
);
});
test("updates model and thinking through Pi runtime commands", async () => {
@@ -52,7 +52,7 @@ import {
type ResolvedProviderLaunch,
} from "../../provider-launch-config.js";
import { renderPromptAttachmentAsText } from "../../prompt-attachments.js";
import { composeSystemPromptParts } from "../../system-prompt.js";
import { composeAgentSystemPrompt } from "../../system-prompt.js";
import {
buildBinaryDiagnosticRows,
buildCommandResolutionDiagnosticRows,
@@ -2630,7 +2630,7 @@ export class PiRpcAgentClient implements AgentClient {
const mcp = await this.prepareMcpInjection(config.cwd, config.mcpServers, mcpEnv, runtime);
const mcpConfigFile = mcp?.kind === "adapter" ? mcp.configFile : null;
const paseoExtension = createPiPaseoExtensionFile({
systemPrompt: composeSystemPromptParts(config.systemPrompt, config.daemonAppendSystemPrompt),
systemPrompt: composeAgentSystemPrompt(config),
mcpServers: mcp?.kind === "builtin" ? mcp.servers : undefined,
});
let runtimeSession: PiRuntimeSession;
@@ -2699,10 +2699,7 @@ export class PiRpcAgentClient implements AgentClient {
);
const mcpConfigFile = mcp?.kind === "adapter" ? mcp.configFile : null;
const paseoExtension = createPiPaseoExtensionFile({
systemPrompt: composeSystemPromptParts(
resumeConfig.config.systemPrompt,
resumeConfig.config.daemonAppendSystemPrompt,
),
systemPrompt: composeAgentSystemPrompt(resumeConfig.config),
mcpServers: mcp?.kind === "builtin" ? mcp.servers : undefined,
});
const tempFiles = mcpConfigFile ? [mcpConfigFile, paseoExtension] : [paseoExtension];
@@ -8,3 +8,15 @@ export function composeSystemPromptParts(
return prompt.length > 0 ? prompt : undefined;
}
export function composeAgentSystemPrompt(config: {
systemPrompt?: string;
daemonAppendSystemPrompt?: string;
pluginAppendSystemPrompt?: string[];
}): string | undefined {
return composeSystemPromptParts(
config.systemPrompt,
config.daemonAppendSystemPrompt,
...(config.pluginAppendSystemPrompt ?? []),
);
}
@@ -527,13 +527,25 @@ test("agent creation hooks change the provider and environment before the sessio
});
server.addHook("agent.open.before", async ({ request }) => {
console.log(JSON.stringify({ hook: "agent.open.before", request }));
return { ...request, env: { ...request.env, HOOK_OPEN: "opened" } };
return { ...request, appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "Plugin instructions"], env: { ...request.env, HOOK_OPEN: "opened" } };
});
server.addHook("agent.create.after", async (event) => {
console.log(JSON.stringify({ hook: "agent.create.after", event }));
});`,
reportOpen: true,
});
const extraPlugin = path.join(directory, "extra-plugin");
await mkdir(extraPlugin);
await writeFile(
path.join(extraPlugin, "paseo-plugin.json"),
JSON.stringify({ id: "a-prompt", requirements: { paseo: ">=0.8.0" } }),
);
const writePrompt = (prompt: string) =>
writeFile(
path.join(extraPlugin, "index.server.ts"),
`export default function contribute(server) { server.addHook("agent.open.before", async ({ request }) => ({ ...request, appendSystemPrompt: [...(request.appendSystemPrompt ?? []), ${JSON.stringify(prompt)}] })); return () => {}; }`,
);
await writePrompt("First plugin");
const daemon = await createTestPaseoDaemon();
const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
try {
@@ -541,15 +553,17 @@ test("agent creation hooks change the provider and environment before the sessio
await client.fetchAgents({ subscribe: {} });
await client.patchDaemonConfig({ pluginsEnabled: true });
await client.installDirectoryPlugin(pluginDirectory);
await client.installDirectoryPlugin(extraPlugin);
const agent = await client.createAgent({
provider: "claude",
cwd: directory,
title: "Hook test",
systemPrompt: "Saved instructions",
});
expect(agent.provider).toBe(PROVIDER_ID);
expect(await daemon.daemon.agentStorage.get(agent.id)).toMatchObject({
provider: PROVIDER_ID,
config: { model: "shutdown-model" },
config: { model: "shutdown-model", systemPrompt: "Saved instructions" },
});
await expect
.poll(async () => {
@@ -569,13 +583,32 @@ test("agent creation hooks change the provider and environment before the sessio
},
{
hook: "provider.open",
config: { env: { HOOK_CREATE: "created", HOOK_OPEN: "opened" } },
config: {
env: { HOOK_CREATE: "created", HOOK_OPEN: "opened" },
systemPrompt: "Saved instructions\n\nFirst plugin\n\nPlugin instructions",
},
},
{
hook: "agent.create.after",
event: { agent: { id: agent.id, provider: PROVIDER_ID } },
},
]);
await writePrompt("Changed plugin");
await client.reloadPlugin("a-prompt");
await daemon.daemon.agentManager.reloadAgentSession(agent.id);
await client.disablePlugin("a-prompt");
await daemon.daemon.agentManager.reloadAgentSession(agent.id);
const opens = (await client.getPluginLogs("shutdown-provider-plugin"))
.filter((entry) => entry.message.startsWith('{"hook":"provider.open"'))
.map((entry) => JSON.parse(entry.message).config.systemPrompt);
expect(opens).toEqual([
"Saved instructions\n\nFirst plugin\n\nPlugin instructions",
"Saved instructions\n\nChanged plugin\n\nPlugin instructions",
"Saved instructions\n\nPlugin instructions",
]);
expect((await daemon.daemon.agentStorage.get(agent.id))?.config?.systemPrompt).toBe(
"Saved instructions",
);
await client.archiveAgent(agent.id);
} finally {
await client.close();
@@ -228,7 +228,9 @@ test.each([{ title: "Changed" }, { labels: { changed: "true" } }, { background:
},
paseo,
),
).rejects.toThrow("agent.open.before hooks can only change env, tools, and mcpServers");
).rejects.toThrow(
"agent.open.before hooks can only change env, tools, mcpServers, and appendSystemPrompt",
);
},
);
@@ -357,3 +359,42 @@ test("checkout-branch hooks reject a branch-off baseRef", async () => {
validateBeforeResult("worktree.create.before", request, { ...request, baseRef: "main" }),
).rejects.toThrow(/baseRef/);
});
test("session-open instructions compose, survive old hooks, and are ignored for history", async () => {
const hooks = new PluginHookHandlers(() => {});
hooks.addHook("agent.open.before", async ({ request }) => ({
...request,
appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "first"],
}));
hooks.addHook("agent.open.before", async ({ request }) => {
const { appendSystemPrompt: _ignored, ...oldRequest } = request;
return oldRequest;
});
hooks.addHook("agent.open.before", async ({ request }) => ({
...request,
appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "second"],
}));
const input = {
agentId: "agent",
workspaceId: null,
provider: "codex",
cwd: "/project",
reason: "resume",
purpose: "interactive",
env: {},
title: null,
labels: {},
metadata: {},
tools: [],
mcpServers: {},
};
const interactive = await hooks.invoke("interactive", "agent.open.before", input, paseo);
expect(interactive).toMatchObject({ appendSystemPrompt: ["first", "second"] });
const history = await hooks.invoke(
"history",
"agent.open.before",
{ ...input, purpose: "history" },
paseo,
);
expect(history).not.toHaveProperty("appendSystemPrompt");
});
@@ -108,6 +108,7 @@ const beforeSchemas = {
labels: z.record(z.string(), z.string()),
// Optional so a plugin that returns its own object keeps working; omitted means unchanged.
metadata: z.record(z.string(), z.custom<JsonValue>()).optional(),
appendSystemPrompt: z.array(z.string()).optional(),
tools: z.array(agentToolMetadataSchema),
env: z.record(z.string(), z.string()),
mcpServers: CreateAgentRequestMessageSchema.shape.config.shape.mcpServers.unwrap(),
@@ -248,9 +249,18 @@ export async function validateBeforeResult<Name extends keyof PluginWireBeforeRe
const previous = beforeSchemas["agent.open.before"].parse(input);
const next = beforeSchemas["agent.open.before"].parse(result);
if (changesSessionOpenTarget(previous, next)) {
throw new Error("agent.open.before hooks can only change env, tools, and mcpServers");
throw new Error(
"agent.open.before hooks can only change env, tools, mcpServers, and appendSystemPrompt",
);
}
return { ...result, background: previous.background, metadata: previous.metadata };
return {
...result,
background: previous.background,
metadata: previous.metadata,
...(next.appendSystemPrompt === undefined && previous.appendSystemPrompt !== undefined
? { appendSystemPrompt: previous.appendSystemPrompt }
: {}),
};
}
if (name === "agent.create.before") {
const previous = beforeSchemas["agent.create.before"].parse(input);
@@ -376,6 +386,7 @@ export class PluginHookHandlers implements PluginLifecycleRegistration {
if (request.purpose === "history") {
request.tools = [];
request.mcpServers = {};
delete request.appendSystemPrompt;
} else this.agentTools?.attach(request.agentId, tools);
return request;
}
@@ -27,6 +27,10 @@ export default function contribute(server: PluginServerContext) {
return {
...request,
appendSystemPrompt: [
...(request.appendSystemPrompt ?? []),
"Follow the team engineering guide.",
],
mcpServers: {
...request.mcpServers,
company: {
+29 -18
View File
@@ -31,7 +31,7 @@ Names follow `subject.operation.position`: the subject, the operation, then `bef
All handlers must be async. Turn completion includes success, failure, and cancellation; inspect `outcome`. Permission completion includes every resolution; inspect `resolution`.
Creating an agent happens once, and `agent.create.before` changes its saved configuration. Opening starts the provider process: the first run, resume after a daemon restart, reading history, importing an outside session, or reload. `agent.open.before` contributes launch-only environment, tools, and MCP servers each time. Creating opens the agent; opening an existing agent does not create it; closing ends the running instance. Opening a tab in the app is a separate action.
Creating an agent happens once, and `agent.create.before` changes its saved configuration. Opening starts the provider process: the first run, resume after a daemon restart, reading history, importing an outside session, or reload. `agent.open.before` contributes launch-only environment, instructions, tools, and MCP servers each time. Creating opens the agent; opening an existing agent does not create it; closing ends the running instance. Opening a tab in the app is a separate action.
`worktree.create.after` runs before the workspace is registered. It precedes `workspace.create.after`, and both precede the first agent's `agent.create.before` / `agent.open.before`.
@@ -49,22 +49,22 @@ Paseo only sees the returned promise, so detached work gets no error reporting a
## Hooks
| Hook | Waits | Payload | Handler may change |
| ------------------------- | ----- | ----------------------------------------- | ---------------------------------------------- |
| `workspace.create.before` | yes | `{ request }` | Entire create request |
| `workspace.create.after` | no | `{ workspace }` | |
| `workspace.archive.after` | no | `{ workspace }` | |
| `worktree.create.before` | yes | `{ request }` | Creation options and destination |
| `worktree.create.after` | yes | `{ worktree }` | Files in the worktree; throw to abort creation |
| `agent.create.before` | yes | `{ request: { config, env?, metadata } }` | Saved config except `cwd`; `env`; `metadata` |
| `agent.create.after` | no | `{ agent }` | |
| `agent.open.before` | yes | `{ request }` | Launch-only `env`, `tools`, `mcpServers` |
| `agent.close.after` | no | `{ agent }` | |
| `agent.archive.after` | no | `{ agent, archivedAt }` | |
| `agent.turn.before` | no | `{ agent, turnId }` | |
| `agent.turn.after` | no | `{ agent, turnId, outcome }` | |
| `agent.permission.before` | no | `{ agent, request }` | |
| `agent.permission.after` | no | `{ agent, requestId, resolution }` | |
| Hook | Waits | Payload | Handler may change |
| ------------------------- | ----- | ----------------------------------------- | -------------------------------------------------------------- |
| `workspace.create.before` | yes | `{ request }` | Entire create request |
| `workspace.create.after` | no | `{ workspace }` | |
| `workspace.archive.after` | no | `{ workspace }` | |
| `worktree.create.before` | yes | `{ request }` | Creation options and destination |
| `worktree.create.after` | yes | `{ worktree }` | Files in the worktree; throw to abort creation |
| `agent.create.before` | yes | `{ request: { config, env?, metadata } }` | Saved config except `cwd`; `env`; `metadata` |
| `agent.create.after` | no | `{ agent }` | |
| `agent.open.before` | yes | `{ request }` | Launch-only `env`, `appendSystemPrompt`, `tools`, `mcpServers` |
| `agent.close.after` | no | `{ agent }` | |
| `agent.archive.after` | no | `{ agent, archivedAt }` | |
| `agent.turn.before` | no | `{ agent, turnId }` | |
| `agent.turn.after` | no | `{ agent, turnId, outcome }` | |
| `agent.permission.before` | no | `{ agent, request }` | |
| `agent.permission.after` | no | `{ agent, requestId, resolution }` | |
## Shared payloads
@@ -283,7 +283,7 @@ server.addHook("agent.create.after", async ({ agent }) => {
## agent.open.before
Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open.
Receives `{ request }`; only `env`, `appendSystemPrompt`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open.
Do not await a write to the agent being opened: `setMetadata`, `setLabels`, or an option, model, thinking or mode change. The write waits for the open to finish, the open waits for your hook, so the hook times out and the open fails. Start the write without awaiting it; it runs right after the open:
@@ -329,6 +329,17 @@ server.addHook("agent.open.before", async ({ request }, { paseo }) => {
| `purpose` | `interactive`, `history` |
| `env` | Launch override map; excludes the daemon's inherited environment. Replace the map to add, replace, or remove overrides. |
### Append instructions on every session opening
```ts
server.addHook("agent.open.before", async ({ request }) => ({
...request,
appendSystemPrompt: [...(request.appendSystemPrompt ?? []), "Follow the team engineering guide."],
}));
```
Instructions follow the saved agent prompt and daemon instructions, in plugin order. They are not saved in the agent configuration and are ignored for history opens. Reload the plugin after changing its data to apply new instructions on the next reopen. Running turns continue; removing an instruction does not remove conversation history. The ACP adapter does not send system instructions to its providers. Plugin providers receive the composed prompt, but must apply it themselves.
### Inject environment variables on every session opening
```ts