feat(hooks): add systemPromptAppend to before_agent_start, full tool registry

- before_agent_start handlers can return systemPromptAppend to dynamically
  append text to the system prompt for that turn
- Multiple hooks' systemPromptAppend strings are concatenated
- Multiple hooks' messages are now all injected (not just first)
- Tool registry now contains ALL built-in tools (read, bash, edit, write,
  grep, find, ls) regardless of --tools flag
- --tools only sets initially active tools, hooks can enable any via
  setActiveTools()
- System prompt automatically rebuilds when tools change, updating tool
  descriptions and guidelines
- Add pirate.ts example hook demonstrating systemPromptAppend
- Update hooks.md with systemPromptAppend documentation
This commit is contained in:
Mario Zechner 2026-01-04 18:21:26 +01:00
parent 892acedb6b
commit e4dd21a3b2
7 changed files with 136 additions and 20 deletions

View file

@ -104,7 +104,7 @@ pi starts
user sends prompt ─────────────────────────────────────────┐
│ │
├─► before_agent_start (can inject message)
├─► before_agent_start (can inject message, append to system prompt)
├─► agent_start │
│ │
│ ┌─── turn (repeats while LLM calls tools) ───┐ │
@ -259,7 +259,7 @@ pi.on("session_shutdown", async (_event, ctx) => {
#### before_agent_start
Fired after user submits prompt, before agent loop. Can inject a persistent message.
Fired after user submits prompt, before agent loop. Can inject a message and/or append to the system prompt.
```typescript
pi.on("before_agent_start", async (event, ctx) => {
@ -267,16 +267,23 @@ pi.on("before_agent_start", async (event, ctx) => {
// event.images - attached images (if any)
return {
// Inject a persistent message (stored in session, sent to LLM)
message: {
customType: "my-hook",
content: "Additional context for the LLM",
display: true, // Show in TUI
}
},
// Append to system prompt for this turn only
systemPromptAppend: "Extra instructions for this turn...",
};
});
```
The injected message is persisted as `CustomMessageEntry` and sent to the LLM.
**message**: Persisted as `CustomMessageEntry` and sent to the LLM.
**systemPromptAppend**: Appended to the base system prompt for this agent run only. Multiple hooks can each return `systemPromptAppend` strings, which are concatenated. This is useful for dynamic instructions based on hook state (e.g., plan mode, persona toggles).
See [examples/hooks/pirate.ts](../examples/hooks/pirate.ts) for an example using `systemPromptAppend`.
#### agent_start / agent_end