Rename /branch command to /fork

- RPC: branch -> fork, get_branch_messages -> get_fork_messages
- SDK: branch() -> fork(), getBranchMessages() -> getForkMessages()
- AgentSession: branch() -> fork(), getUserMessagesForBranching() -> getUserMessagesForForking()
- Extension events: session_before_branch -> session_before_fork, session_branch -> session_fork
- Settings: doubleEscapeAction 'branch' -> 'fork'

fixes #641
This commit is contained in:
Mario Zechner 2026-01-11 23:12:18 +01:00
parent e7352a50bf
commit df3f5f41c0
27 changed files with 162 additions and 156 deletions

View file

@ -278,9 +278,9 @@ user sends another prompt ◄─────────────────
├─► session_before_switch (can cancel)
└─► session_switch
/branch
├─► session_before_branch (can cancel)
└─► session_branch
/fork
├─► session_before_fork (can cancel)
└─► session_fork
/compact or auto-compaction
├─► session_before_compact (can cancel or customize)
@ -334,19 +334,19 @@ pi.on("session_switch", async (event, ctx) => {
**Examples:** [confirm-destructive.ts](../examples/extensions/confirm-destructive.ts), [dirty-repo-guard.ts](../examples/extensions/dirty-repo-guard.ts), [status-line.ts](../examples/extensions/status-line.ts), [todo.ts](../examples/extensions/todo.ts)
#### session_before_branch / session_branch
#### session_before_fork / session_fork
Fired when branching via `/branch`.
Fired when forking via `/fork`.
```typescript
pi.on("session_before_branch", async (event, ctx) => {
// event.entryId - ID of the entry being branched from
return { cancel: true }; // Cancel branch
pi.on("session_before_fork", async (event, ctx) => {
// event.entryId - ID of the entry being forked from
return { cancel: true }; // Cancel fork
// OR
return { skipConversationRestore: true }; // Branch but don't rewind messages
return { skipConversationRestore: true }; // Fork but don't rewind messages
});
pi.on("session_branch", async (event, ctx) => {
pi.on("session_fork", async (event, ctx) => {
// event.previousSessionFile - previous session file
});
```

View file

@ -541,47 +541,47 @@ If a hook cancelled the switch:
{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
```
#### branch
#### fork
Create a new branch from a previous user message. Can be cancelled by a `before_branch` hook. Returns the text of the message being branched from.
Create a new fork from a previous user message. Can be cancelled by a `before_fork` hook. Returns the text of the message being forked from.
```json
{"type": "branch", "entryId": "abc123"}
{"type": "fork", "entryId": "abc123"}
```
Response:
```json
{
"type": "response",
"command": "branch",
"command": "fork",
"success": true,
"data": {"text": "The original prompt text...", "cancelled": false}
}
```
If a hook cancelled the branch:
If a hook cancelled the fork:
```json
{
"type": "response",
"command": "branch",
"command": "fork",
"success": true,
"data": {"text": "The original prompt text...", "cancelled": true}
}
```
#### get_branch_messages
#### get_fork_messages
Get user messages available for branching.
Get user messages available for forking.
```json
{"type": "get_branch_messages"}
{"type": "get_fork_messages"}
```
Response:
```json
{
"type": "response",
"command": "get_branch_messages",
"command": "get_fork_messages",
"success": true,
"data": {
"messages": [

View file

@ -108,8 +108,8 @@ interface AgentSession {
newSession(options?: { parentSession?: string }): Promise<boolean>; // Returns false if cancelled by hook
switchSession(sessionPath: string): Promise<boolean>;
// Branching
branch(entryId: string): Promise<{ selectedText: string; cancelled: boolean }>; // Creates new session file
// Forking
fork(entryId: string): Promise<{ selectedText: string; cancelled: boolean }>; // Creates new session file
navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ editorText?: string; cancelled: boolean }>; // In-place navigation
// Hook message injection

View file

@ -49,7 +49,7 @@ First line of the file. Metadata only, not part of the tree (no `id`/`parentId`)
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
```
For sessions with a parent (created via `/branch` or `newSession({ parentSession })`):
For sessions with a parent (created via `/fork` or `newSession({ parentSession })`):
```json
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}

View file

@ -6,14 +6,14 @@ The `/tree` command provides tree-based navigation of the session history.
Sessions are stored as trees where each entry has an `id` and `parentId`. The "leaf" pointer tracks the current position. `/tree` lets you navigate to any point and optionally summarize the branch you're leaving.
### Comparison with `/branch`
### Comparison with `/fork`
| Feature | `/branch` | `/tree` |
|---------|-----------|---------|
| Feature | `/fork` | `/tree` |
|---------|---------|---------|
| View | Flat list of user messages | Full tree structure |
| Action | Extracts path to **new session file** | Changes leaf in **same session** |
| Summary | Never | Optional (user prompted) |
| Events | `session_before_branch` / `session_branch` | `session_before_tree` / `session_tree` |
| Events | `session_before_fork` / `session_fork` | `session_before_tree` / `session_tree` |
## Tree UI