pi-zellij 0.4.6 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Added optional `pi-zellij.review.skill` settings for `/zrv` and `/zrh` to use an existing loaded skill, with project overrides and errors for unavailable or unreadable skills.
 - Initial `pi-zellij` release with zellij-powered pane workflows for Pi.
 - Added `/zv`, `/zj`, and `/zt` to open a new zellij pane or tab and start a fresh Pi session in the same working directory.
 - Added `/zo` and `/zoh` to open a new pane and run any shell command there.
@@ -14,9 +15,15 @@
 - Added `zv-review` with `/zrv` and `/zrh`, plus bundled `code-review` skill and `/review` / `/review-diff` prompt templates for focused review workflows, including GitHub pull request review via `gh` when given a PR URL.
 - Added `zv-continue` with `/zcv` and `/zch` for split-based task handoff in the current checkout or by creating a git worktree branch with `-c <branch>`.
 - Added opt-in `paneHighlight` settings so Pi can tint the current zellij pane when an agent turn completes, with optional working-state colors.
+- Added an agent-facing `zellij_open_terminal` tool so Pi can open explicitly requested interactive terminal commands in right or lower splits, tabs, and floating panes.
+- Added an agent-facing `zellij_start_pi` tool for fresh Pi sessions in right or lower splits and tabs, with optional initial prompts, model settings, pane titles, and explicit history inheritance through a separate cloned session.
 
 ### Changed
 
+- `/zrv` and `/zrh` now use self-contained review instructions by default, injected only into the new review session. `/review` and `/review-diff` no longer refer to a bundled skill.
+- Explicit history inheritance now rejects branches with no conversation messages before creating a cloned session or opening a pane.
+- Expanded `zellij_open_terminal` prompt guidance so agents recognize requests to start another Pi session and prefer the dedicated `zellij_start_pi` interface when available.
+- Pi launch command construction now supports quoted provider, model, and thinking options and stops option parsing before initial prompts.
 - When zellij reports created pane or tab IDs, `pi-zellij` now shows them in success notifications for split, floating, zoxide, review, continuation, and tab commands.
 - `/zt` now uses `zellij action new-tab -- <command>` when available instead of always simulating typed input, while keeping the previous typed-input path as a compatibility fallback.
 - Pane highlights now clear on the next submitted input or when the pane is focused again after being elsewhere, instead of waiting for the next agent start event. Aborted runs no longer apply the done-state tint.
@@ -25,4 +32,5 @@
 
 ### Removed
 
+- Removed the bundled `code-review` skill from the package and installer so terminal workflows do not register a global review skill.
 - Removed the bundled `zv-notify` extension so `pi-zellij` does not conflict with separate notification packages or user-specific notification setups.

package/README.md

@@ -10,7 +10,7 @@ Pi package with [zellij](https://zellij.dev)-powered terminal integrations for [
 
 [Pi](https://pi.dev) works well in the terminal, but pane orchestration is better handled by a terminal multiplexer. `pi-zellij` adds zellij-native split workflows for Pi.
 
-It includes split and tab commands, generic tool launchers, settings-driven floating app shortcuts, opt-in pane highlighting for completed agent turns, zoxide jumps, review workflows, and split-based task handoff.
+It includes split and tab commands, generic tool launchers, agent-facing zellij tools, settings-driven floating app shortcuts, opt-in pane highlighting for completed agent turns, zoxide jumps, review workflows, and split-based task handoff.
 
 ## Usage
 
@@ -70,9 +70,7 @@ If pi is already running, use:
 - `/review <target>`, `/review-diff [focus-or-pr-url]`
   - expand bundled review prompts in the current pane
 - `/zrv`, `/zrh`, plus review flags
-  - open review-focused Pi sessions in a split
-- `/skill:code-review`
-  - loads the bundled structured review skill for files, directories, diffs, and PRs
+  - open review-focused Pi sessions in a split with built-in instructions or a configured skill
 
 ## Bundled extensions and resources
 
@@ -85,7 +83,6 @@ Extensions:
 - `zv-continue`
 
 Other bundled resources:
-- `code-review` skill
 - `/review` prompt template
 - `/review-diff` prompt template
 
@@ -132,6 +129,29 @@ Examples:
 
 Commands are executed via `sh -lc` in the current project directory.
 
+### Agent-opened Pi sessions and terminals
+
+`pi-zellij` registers two agent-facing tools:
+
+- `zellij_start_pi` starts another interactive Pi session with an optional initial prompt and model settings.
+- `zellij_open_terminal` opens arbitrary interactive terminal commands.
+
+Example requests:
+
+```text
+start a fresh Pi agent in a right split and ask it to review the auth flow
+continue this conversation in a lower Pi pane and focus on the failing tests
+start Pi in a new tab using openai/gpt-4o with high thinking
+open k9s in a new tab
+open lazygit in a right split
+open npm run dev below
+open htop in a floating pane
+```
+
+`zellij_start_pi` supports `tab`, `right`, and `down` placements and defaults to `tab`. It starts a fresh session by default. The agent must set `continueSession` explicitly to inherit history; pi-zellij then clones the current active conversation into a separate session instead of opening the same session file in two processes. History inheritance requires a persisted source session with conversation history. The tool accepts `prompt`, `provider`, `model`, `thinking`, and `title` options, and handles the Pi command and shell quoting internally.
+
+`zellij_open_terminal` supports `tab`, `right`, `down`, and `floating` placements and also defaults to `tab`. Floating terminals use the same 90% by 90% pane size as configured floating commands. Use it for TUIs, log tails, dev servers, watches, and other terminal views that should remain interactive instead of being captured through the normal shell tool.
+
 ### Configured floating commands
 
 You can register your own floating app shortcuts in Pi's main settings file under `pi-zellij.commands`.
@@ -294,7 +314,7 @@ Examples:
 
 ### Review helpers
 
-`pi-zellij` also bundles a reusable `code-review` skill plus prompt templates for in-place review:
+`pi-zellij` includes built-in review instructions; no skill installation is required and no review skill is registered globally. It also bundles prompt templates for in-place review:
 
 - `/review <target>`
   - prompt template for reviewing a file, directory, or GitHub pull request URL in the current pane
@@ -333,3 +353,26 @@ Examples:
 
 If the target is a GitHub pull request URL, the review workflow switches to PR review and instructs pi to inspect the pull request with `gh pr view` and `gh pr diff`.
 
+#### Use your own review skill
+
+By default, `/zrv` and `/zrh` inject the built-in review instructions into the new session's initial prompt only. To use an existing skill instead, set `pi-zellij.review.skill` in `~/.pi/agent/settings.json` or the trusted project's `.pi/settings.json`:
+
+```json
+{
+  "pi-zellij": {
+    "review": {
+      "skill": "my-code-review"
+    }
+  }
+}
+```
+
+Use the skill's name without the `/skill:` prefix. It must be loaded in the current Pi session. The commands expand its instructions before opening the pane, preserving its location for relative references and passing the review target and mode. The skill controls the workflow and output format; the request still tells Pi not to edit files unless asked.
+
+- Omit the setting to use the built-in instructions.
+- Project settings override global settings. Set `"skill": null` in the project to use the built-in instructions despite a global override.
+- An unavailable or unreadable skill, or invalid review settings, produces an error without opening a pane. There is no silent fallback.
+- Review settings are read on each invocation. After installing or enabling a skill, run `/reload` first.
+
+This setting only affects `/zrv` and `/zrh`; `/review` and `/review-diff` remain self-contained prompt templates.
+

package/{skills/code-review/SKILL.md → extensions/templates/review.md}

@@ -1,33 +1,15 @@
----
-name: code-review
-description: Structured code review workflow for files, directories, and git diffs. Use when reviewing code for bugs, regressions, maintainability, missing tests, or refactor opportunities.
----
-
 # Code Review
 
-Use this skill for targeted code review requests, including file reviews, module reviews, and current diff reviews.
-
 ## Review goals
 
 - Find the most important issues first.
 - Prefer concrete, evidence-based findings over broad stylistic commentary.
 - Call out missing tests or risky edge cases when they matter.
-- Do not edit files unless the user explicitly asks for changes.
-
-## Review modes
-
-Infer the mode from the user request:
-- **General review** — correctness, readability, maintainability, and missing tests
-- **Bug-focused review** — correctness, runtime failures, invalid assumptions, edge cases, regressions
-- **Refactor review** — simplification, structure, naming, duplication, cohesion, maintainability
-- **Test review** — missing coverage, brittle assertions, edge cases, regression protection
-- **Diff review** — review the current git diff or requested change set for regressions and missing validation
-- **GitHub PR review** — when given a GitHub pull request URL, inspect it with `gh pr view` and `gh pr diff` before concluding
 
 ## Workflow
 
 1. Identify the exact review scope.
-   - If the user named a file, directory, symbol, or diff, stick to that scope.
+   - Stick to the requested file, directory, symbol, diff, or pull request.
    - If the scope is ambiguous, ask one concise clarifying question.
 
 2. Inspect the relevant code before concluding.
@@ -44,11 +26,8 @@ Infer the mode from the user request:
    - If there are no meaningful issues, say so clearly.
 
 5. Make findings actionable.
-   - For each finding, explain:
-     - what is wrong
-     - why it matters
-     - where it occurs
-     - what change would improve it
+   - Explain what is wrong, why it matters, where it occurs, and what change would improve it.
+   - Include file paths and line numbers where possible.
 
 ## Output format
 
@@ -61,13 +40,11 @@ Summary
 
 Findings
 1. Severity: <high|medium|low>
-   - Location: <file or diff area>
+   - Location: <file and line or diff area>
    - Issue: <what is wrong>
    - Impact: <why it matters>
    - Fix: <concrete suggestion>
 
-2. ...
-
 Test gaps
 - <missing test or "None noted">
 ```

package/extensions/zv-core.ts

@@ -3,9 +3,18 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 const ZELLIJ_TIMEOUT_MS = 5000;
 
 export type SplitDirection = "right" | "down";
+export type PiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type PaneOpenResult = { ok: true; paneId?: string } | { ok: false; error: string };
 export type TabOpenResult = { ok: true; tabId?: string } | { ok: false; error: string };
 
+export interface PiCommandOptions {
+	sessionFile?: string;
+	prompt?: string;
+	provider?: string;
+	model?: string;
+	thinking?: PiThinkingLevel;
+}
+
 interface ZellijExecResult {
 	ok: boolean;
 	stdout: string;
@@ -60,14 +69,23 @@ export function shellEscape(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-export function buildPiCommand(cwd: string, options?: { sessionFile?: string; prompt?: string }): string {
+export function buildPiCommand(cwd: string, options?: PiCommandOptions): string {
 	const commandParts = ["cd", shellEscape(cwd), "&&", "exec", "pi"];
 	if (options?.sessionFile) {
 		commandParts.push("--session", shellEscape(options.sessionFile));
 	}
+	if (options?.provider) {
+		commandParts.push("--provider", shellEscape(options.provider));
+	}
+	if (options?.model) {
+		commandParts.push("--model", shellEscape(options.model));
+	}
+	if (options?.thinking) {
+		commandParts.push("--thinking", shellEscape(options.thinking));
+	}
 	const prompt = options?.prompt?.trim();
 	if (prompt) {
-		commandParts.push(shellEscape(prompt));
+		commandParts.push("--", shellEscape(prompt));
 	}
 	return commandParts.join(" ");
 }
@@ -182,12 +200,17 @@ export async function openCommandInNewSplit(
 	pi: ExtensionAPI,
 	direction: SplitDirection,
 	command: string,
+	options?: { name?: string },
 ): Promise<PaneOpenResult> {
 	if (!isInsideZellijSession()) {
 		return { ok: false, error: "This command must be run from inside an active zellij session" };
 	}
 
-	const result = await execZellij(pi, ["run", "--direction", direction, "--", "sh", "-lc", command]);
+	const args = ["run", "--direction", direction];
+	if (options?.name) args.push("--name", options.name);
+	args.push("--", "sh", "-lc", command);
+
+	const result = await execZellij(pi, args);
 	if (!result.ok) {
 		return { ok: false, error: result.error || "Failed to open a new zellij pane" };
 	}

package/extensions/zv-open.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -7,8 +7,10 @@ import {
 	formatPaneSuccessMessage,
 	openCommandInFloatingPane as openCommandInFloatingZellijPane,
 	openCommandInNewSplit,
+	openCommandInNewTab,
 	type PaneOpenResult,
 	type SplitDirection,
+	type TabOpenResult,
 } from "./zv-core.ts";
 
 const DEFAULT_FLOATING_PANE_OPTIONS = {
@@ -70,18 +72,59 @@ interface ConfiguredFloatingCommand {
 	description: string;
 }
 
+type TerminalPlacement = SplitDirection | "tab" | "floating";
+
+type OpenToolContext = Pick<ExtensionContext, "cwd">;
+
+interface ZellijOpenTerminalParams {
+	command: string;
+	placement?: TerminalPlacement;
+	title?: string;
+}
+
+interface OpenedTerminal {
+	ok: true;
+	placement: TerminalPlacement;
+	command: string;
+	paneId?: string;
+	tabId?: string;
+}
+
+const ZELLIJ_OPEN_TERMINAL_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["command"],
+	properties: {
+		command: {
+			type: "string",
+			description: "Interactive terminal command to run, for example k9s, htop, lazygit, or npm run dev",
+		},
+		placement: {
+			type: "string",
+			enum: ["right", "down", "tab", "floating"],
+			default: "tab",
+			description: "Where to open the command. Use floating for a 90% by 90% floating pane.",
+		},
+		title: {
+			type: "string",
+			description: "Optional zellij pane or tab name. Defaults to the command.",
+		},
+	},
+} as const;
+
 async function openToolInSplit(
 	pi: ExtensionAPI,
-	ctx: ExtensionCommandContext,
+	ctx: OpenToolContext,
 	direction: SplitDirection,
 	args: string,
+	name?: string,
 ): Promise<PaneOpenResult> {
-	return openCommandInNewSplit(pi, direction, buildShellCommand(ctx.cwd, args.trim()));
+	return openCommandInNewSplit(pi, direction, buildShellCommand(ctx.cwd, args.trim()), { name });
 }
 
 async function openToolInFloatingPane(
 	pi: ExtensionAPI,
-	ctx: ExtensionCommandContext,
+	ctx: OpenToolContext,
 	command: string,
 	name?: string,
 ): Promise<PaneOpenResult> {
@@ -91,6 +134,15 @@ async function openToolInFloatingPane(
 	});
 }
 
+async function openToolInTab(
+	pi: ExtensionAPI,
+	ctx: OpenToolContext,
+	command: string,
+	name?: string,
+): Promise<TabOpenResult> {
+	return openCommandInNewTab(pi, ctx.cwd, buildShellCommand(ctx.cwd, command.trim()), { name });
+}
+
 function registerOpenCommand(
 	pi: ExtensionAPI,
 	name: string,
@@ -267,6 +319,92 @@ function registerConfiguredFloatingCommand(
 	});
 }
 
+function normalizeTerminalPlacement(value: unknown): TerminalPlacement {
+	return value === "right" || value === "down" || value === "tab" || value === "floating" ? value : "tab";
+}
+
+function getPlacementLabel(placement: TerminalPlacement): string {
+	if (placement === "right") {
+		return "right split";
+	}
+	if (placement === "down") {
+		return "lower split";
+	}
+	if (placement === "floating") {
+		return "floating pane";
+	}
+	return "tab";
+}
+
+async function openTerminalCommand(
+	pi: ExtensionAPI,
+	ctx: OpenToolContext,
+	params: ZellijOpenTerminalParams,
+): Promise<OpenedTerminal | { ok: false; error: string }> {
+	const command = typeof params.command === "string" ? params.command.trim() : "";
+	if (!command) {
+		return { ok: false, error: "Specify a command to open" };
+	}
+
+	const placement = normalizeTerminalPlacement(params.placement);
+	const title = params.title?.trim() || command;
+
+	if (placement === "tab") {
+		const result = await openToolInTab(pi, ctx, command, title);
+		if (!result.ok) {
+			return result;
+		}
+		return { ok: true, placement, command, tabId: result.tabId };
+	}
+
+	const result = placement === "floating"
+		? await openToolInFloatingPane(pi, ctx, command, title)
+		: await openToolInSplit(pi, ctx, placement, command, title);
+	if (!result.ok) {
+		return result;
+	}
+
+	return { ok: true, placement, command, paneId: result.paneId };
+}
+
+function registerAgentTerminalTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "zellij_open_terminal",
+		label: "Open zellij terminal",
+		description:
+			"Open an interactive terminal command in zellij as a right split, lower split, new tab, or floating pane. Use for user-requested Pi sessions, TUIs, logs, dev servers, watches, or long-running terminal views.",
+		promptSnippet:
+			"Open an interactive terminal command or another Pi session in zellij when the user asks for it in another pane, split, tab, or floating terminal.",
+		promptGuidelines: [
+			"Use zellij_open_terminal only when the user explicitly asks to open a command in zellij, another pane, split, tab, or floating terminal.",
+			"Use zellij_open_terminal from pi-zellij when the user requests another Pi session in a split or tab, including an initial prompt. Prefer zellij_start_pi when it is available.",
+			"Use zellij_open_terminal with placement='tab' when the user says tab, placement='right' for a side pane, placement='down' for a below/lower pane, and placement='floating' for a floating pane.",
+			"Use zellij_open_terminal for interactive TUIs like k9s, lazygit, htop, hunk, log tails, dev servers, or watches; do not use bash for these unless the user wants captured output.",
+			"Do not open terminals proactively with zellij_open_terminal without a user request.",
+		],
+		parameters: ZELLIJ_OPEN_TERMINAL_PARAMETERS as any,
+		executionMode: "sequential",
+		async execute(_toolCallId, rawParams, _signal, _onUpdate, ctx) {
+			const params = rawParams as ZellijOpenTerminalParams;
+			const result = await openTerminalCommand(pi, ctx, params);
+			if (!result.ok) {
+				throw new Error(result.error);
+			}
+
+			return {
+				content: [{ type: "text", text: `Opened ${result.command} in a zellij ${getPlacementLabel(result.placement)}.` }],
+				details: {
+					command: result.command,
+					placement: result.placement,
+					cwd: ctx.cwd,
+					...(result.paneId ? { paneId: result.paneId } : {}),
+					...(result.tabId ? { tabId: result.tabId } : {}),
+				},
+			};
+		},
+	});
+}
+
 export default function zvOpenExtension(pi: ExtensionAPI) {
 	registerOpenCommand(
 		pi,
@@ -292,4 +430,6 @@ export default function zvOpenExtension(pi: ExtensionAPI) {
 		registerConfiguredFloatingCommand(pi, commandName, config);
 		registeredConfiguredNames.add(commandName);
 	}
+
+	registerAgentTerminalTool(pi);
 }

package/extensions/zv-review.ts

@@ -1,4 +1,13 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+	CONFIG_DIR_NAME,
+	getAgentDir,
+	stripFrontmatter,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
 	buildPiCommand,
 	formatPaneSuccessMessage,
@@ -7,6 +16,8 @@ import {
 	type SplitDirection,
 } from "./zv-core.ts";
 
+const REVIEW_TEMPLATE_PATH = join(dirname(fileURLToPath(import.meta.url)), "templates", "review.md");
+
 type ReviewMode = "general" | "bugs" | "refactor" | "tests" | "diff";
 
 interface ReviewRequest {
@@ -61,13 +72,56 @@ function getGitHubPullRequestUrl(value: string | undefined): string | undefined
 	return /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+(?:[/?#].*)?$/.test(trimmed) ? trimmed : undefined;
 }
 
-function buildReviewPrompt(request: ReviewRequest): string {
-	const commonInstructions = [
-		"Use the bundled code-review skill if it is available.",
-		"Start with a concise summary ordered by severity.",
-		"Then list concrete findings with suggested fixes and any missing tests.",
-		"Do not edit files unless asked.",
-	].join(" ");
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readReviewSkillSetting(settingsPath: string): string | null | undefined {
+	let settings: unknown;
+	try {
+		settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read settings from ${settingsPath}: ${message}`);
+	}
+
+	if (!isRecord(settings)) {
+		throw new Error(`Expected a settings object in ${settingsPath}`);
+	}
+	const section = settings["pi-zellij"];
+	if (section === undefined) return undefined;
+	if (!isRecord(section)) {
+		throw new Error(`pi-zellij must be an object in ${settingsPath}`);
+	}
+	const review = section.review;
+	if (review === undefined) return undefined;
+	if (!isRecord(review)) {
+		throw new Error(`pi-zellij.review must be an object in ${settingsPath}`);
+	}
+	const skill = review.skill;
+	if (skill === undefined || skill === null) return skill;
+	if (typeof skill !== "string" || !skill.trim()) {
+		throw new Error(`pi-zellij.review.skill must be a non-empty skill name or null in ${settingsPath}`);
+	}
+	return skill.trim();
+}
+
+function loadReviewSkill(ctx: ExtensionCommandContext): string | undefined {
+	const settingsPaths = [join(getAgentDir(), "settings.json")];
+	if (ctx.isProjectTrusted()) {
+		settingsPaths.push(join(ctx.cwd, CONFIG_DIR_NAME, "settings.json"));
+	}
+
+	let skill: string | null | undefined;
+	for (const settingsPath of settingsPaths) {
+		const value = readReviewSkillSetting(settingsPath);
+		if (value !== undefined) skill = value;
+	}
+	return skill ?? undefined;
+}
+
+function buildReviewScope(request: ReviewRequest): string {
 	const pullRequestUrl = getGitHubPullRequestUrl(request.targetOrFocus);
 	const modeInstruction =
 		request.mode === "bugs"
@@ -79,15 +133,43 @@ function buildReviewPrompt(request: ReviewRequest): string {
 					: "Focus on correctness, readability, maintainability, and missing tests.";
 
 	if (pullRequestUrl) {
-		return `Review GitHub pull request ${pullRequestUrl}. Use the gh CLI to inspect it, including gh pr view ${pullRequestUrl} and gh pr diff ${pullRequestUrl}. ${modeInstruction} Prioritize the changed code, likely regressions, and missing tests before adding lower-priority notes. ${commonInstructions}`;
+		return `Review GitHub pull request ${pullRequestUrl}. Use the gh CLI to inspect it, including gh pr view ${pullRequestUrl} and gh pr diff ${pullRequestUrl}. ${modeInstruction} Prioritize the changed code, likely regressions, and missing tests before adding lower-priority notes.`;
 	}
 
 	if (request.mode === "diff") {
 		const focus = request.targetOrFocus ? ` Extra focus: ${request.targetOrFocus}.` : "";
-		return `Review the current git diff in this repository.${focus} Prioritize regressions, correctness issues, risky edge cases, and missing tests. ${commonInstructions}`;
+		return `Review the current git diff in this repository.${focus} Prioritize regressions, correctness issues, risky edge cases, and missing tests.`;
 	}
 
-	return `Review ${request.targetOrFocus} from the current project. ${modeInstruction} If the target is a directory, review the most relevant files within that scope. ${commonInstructions}`;
+	return `Review ${request.targetOrFocus} from the current project. ${modeInstruction} If the target is a directory, review the most relevant files within that scope.`;
+}
+
+function buildReviewPrompt(request: ReviewRequest, ctx: ExtensionCommandContext): string {
+	const scope = `${buildReviewScope(request)} Do not edit files unless asked.`;
+	const skillName = loadReviewSkill(ctx);
+	if (!skillName) {
+		return `${readFileSync(REVIEW_TEMPLATE_PATH, "utf8").trim()}\n\n${scope}`;
+	}
+
+	const skill = ctx.getSystemPromptOptions().skills?.find((entry) => entry.name === skillName);
+	if (!skill) {
+		throw new Error(
+			`Review skill "${skillName}" is not available in this session. Enable or install it and run /reload, or set pi-zellij.review.skill to null.`,
+		);
+	}
+
+	let body: string;
+	try {
+		body = stripFrontmatter(readFileSync(skill.filePath, "utf8")).trim();
+		if (!body) throw new Error("Skill instructions are empty");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Cannot load review skill "${skillName}" from ${skill.filePath}: ${message}`);
+	}
+
+	// Expand before launching, as Pi does for /skill:name. This validates the file
+	// and carries even CLI-only skills into the child without rediscovering them.
+	return `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>\n\n${scope}`;
 }
 
 async function openReviewSplit(
@@ -96,7 +178,12 @@ async function openReviewSplit(
 	direction: SplitDirection,
 	request: ReviewRequest,
 ): Promise<PaneOpenResult> {
-	return openCommandInNewSplit(pi, direction, buildPiCommand(ctx.cwd, { prompt: buildReviewPrompt(request) }));
+	try {
+		const prompt = buildReviewPrompt(request, ctx);
+		return await openCommandInNewSplit(pi, direction, buildPiCommand(ctx.cwd, { prompt }));
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
 }
 
 function registerReviewCommand(

package/extensions/zv-split.ts

@@ -1,34 +1,191 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+	buildSessionContext,
+	SessionManager,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import {
 	buildPiCommand,
 	formatPaneSuccessMessage,
 	formatTabSuccessMessage,
+	isInsideZellijSession,
 	openCommandInNewSplit,
 	openCommandInNewTab,
-	type PaneOpenResult,
+	type PiCommandOptions,
+	type PiThinkingLevel,
 	type SplitDirection,
-	type TabOpenResult,
 } from "./zv-core.ts";
 
-async function openPiInSplit(
-	pi: ExtensionAPI,
-	ctx: ExtensionCommandContext,
-	direction: SplitDirection,
-	args: string,
-): Promise<PaneOpenResult> {
-	return openCommandInNewSplit(
-		pi,
-		direction,
-		buildPiCommand(ctx.cwd, { prompt: args.trim().length > 0 ? args : undefined }),
-	);
+export type PiPlacement = SplitDirection | "tab";
+type PiLaunchContext = Pick<ExtensionContext, "cwd">;
+type PiContinuationContext = Pick<ExtensionContext, "cwd" | "sessionManager">;
+
+export interface ZellijStartPiParams {
+	placement?: PiPlacement;
+	prompt?: string;
+	continueSession?: boolean;
+	provider?: string;
+	model?: string;
+	thinking?: PiThinkingLevel;
+	title?: string;
+}
+
+interface OpenedPiSession {
+	ok: true;
+	placement: PiPlacement;
+	paneId?: string;
+	tabId?: string;
+}
+
+const THINKING_LEVELS: readonly PiThinkingLevel[] = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+];
+
+const ZELLIJ_START_PI_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		placement: {
+			type: "string",
+			enum: ["right", "down", "tab"],
+			default: "tab",
+			description: "Where to start Pi: a right split, lower split, or new tab. Defaults to tab.",
+		},
+		prompt: {
+			type: "string",
+			description: "Optional initial prompt for the new Pi session. The extension handles shell quoting.",
+		},
+		continueSession: {
+			type: "boolean",
+			default: false,
+			description:
+				"Clone the current active conversation into a separate session before starting Pi. Set true only when the user explicitly asks to continue or inherit the current history. Defaults to false for a fresh session.",
+		},
+		provider: {
+			type: "string",
+			description: "Optional Pi provider. Requires model; omit both to use Pi's normal session/default selection.",
+		},
+		model: {
+			type: "string",
+			description: "Optional Pi model pattern or ID, including provider/model and model:thinking forms.",
+		},
+		thinking: {
+			type: "string",
+			enum: THINKING_LEVELS,
+			description: "Optional Pi thinking level for the new session.",
+		},
+		title: {
+			type: "string",
+			description: "Optional zellij pane or tab name.",
+		},
+	},
+} as const;
+
+function normalizePiPlacement(value: unknown): PiPlacement {
+	return value === "right" || value === "down" || value === "tab" ? value : "tab";
+}
+
+function normalizeOptionalString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	return value.trim() || undefined;
+}
+
+function normalizeThinkingLevel(value: unknown): PiThinkingLevel | undefined {
+	return typeof value === "string" && THINKING_LEVELS.includes(value as PiThinkingLevel)
+		? (value as PiThinkingLevel)
+		: undefined;
+}
+
+function getPlacementLabel(placement: PiPlacement): string {
+	if (placement === "right") return "right split";
+	if (placement === "down") return "lower split";
+	return "tab";
 }
 
-async function openPiInTab(
+async function openPiSession(
 	pi: ExtensionAPI,
-	ctx: ExtensionCommandContext,
-	args: string,
-): Promise<TabOpenResult> {
-	return openCommandInNewTab(pi, ctx.cwd, buildPiCommand(ctx.cwd, { prompt: args.trim().length > 0 ? args : undefined }));
+	ctx: PiLaunchContext,
+	placement: PiPlacement,
+	options: PiCommandOptions,
+	title?: string,
+): Promise<OpenedPiSession | { ok: false; error: string }> {
+	const command = buildPiCommand(ctx.cwd, options);
+	if (placement === "tab") {
+		const result = await openCommandInNewTab(pi, ctx.cwd, command, { name: title });
+		if (!result.ok) return result;
+		return { ok: true, placement, tabId: result.tabId };
+	}
+
+	const result = await openCommandInNewSplit(pi, placement, command, { name: title });
+	if (!result.ok) return result;
+	return { ok: true, placement, paneId: result.paneId };
+}
+
+function createContinuationSession(
+	ctx: PiContinuationContext,
+): { ok: true; sessionFile: string } | { ok: false; error: string } {
+	const sourceSessionFile = ctx.sessionManager.getSessionFile();
+	if (!sourceSessionFile) {
+		return { ok: false, error: "Cannot inherit history from an ephemeral session" };
+	}
+
+	const currentLeaf = ctx.sessionManager.getLeafEntry();
+	if (!currentLeaf) {
+		return { ok: false, error: "The current session has no conversation history to inherit" };
+	}
+
+	// During tool execution, the active leaf is the assistant message containing
+	// this tool call. Exclude it so the child does not inherit a tool call without
+	// its result.
+	const continuationLeafId =
+		currentLeaf.type === "message" && currentLeaf.message.role === "assistant"
+			? currentLeaf.parentId
+			: currentLeaf.id;
+	if (!continuationLeafId) {
+		return { ok: false, error: "The current session has no completed conversation history to inherit" };
+	}
+
+	try {
+		const inheritedContext = buildSessionContext(ctx.sessionManager.getEntries(), continuationLeafId);
+		if (inheritedContext.messages.length === 0) {
+			return { ok: false, error: "The current session has no conversation history to inherit" };
+		}
+
+		const inheritedBranch = ctx.sessionManager.getBranch(continuationLeafId);
+		const hasCompletedAssistantMessage = inheritedBranch.some(
+			(entry) => entry.type === "message" && entry.message.role === "assistant",
+		);
+		if (hasCompletedAssistantMessage) {
+			const sourceSession = SessionManager.open(sourceSessionFile, ctx.sessionManager.getSessionDir());
+			const sessionFile = sourceSession.createBranchedSession(continuationLeafId);
+			if (sessionFile) return { ok: true, sessionFile };
+		}
+
+		// A branch with only the triggering user message is not written by
+		// createBranchedSession until it receives an assistant response. Fork the
+		// file and move its active leaf instead so Pi can open it immediately.
+		const continuationSession = SessionManager.forkFrom(
+			sourceSessionFile,
+			ctx.cwd,
+			ctx.sessionManager.getSessionDir(),
+		);
+		continuationSession.branch(continuationLeafId);
+		continuationSession.appendCustomEntry("pi-zellij-continuation");
+		const sessionFile = continuationSession.getSessionFile();
+		if (!sessionFile) {
+			return { ok: false, error: "Failed to create a persistent continuation session" };
+		}
+		return { ok: true, sessionFile };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Failed to clone the current session: ${message}` };
+	}
 }
 
 function registerSplitCommand(
@@ -41,7 +198,8 @@ function registerSplitCommand(
 	pi.registerCommand(name, {
 		description,
 		handler: async (args, ctx) => {
-			const result = await openPiInSplit(pi, ctx, direction, args);
+			const prompt = normalizeOptionalString(args);
+			const result = await openPiSession(pi, ctx, direction, { prompt });
 			if (result.ok) {
 				ctx.ui.notify(formatPaneSuccessMessage(successMessage, result.paneId), "info");
 			} else {
@@ -60,7 +218,8 @@ function registerTabCommand(
 	pi.registerCommand(name, {
 		description,
 		handler: async (args, ctx) => {
-			const result = await openPiInTab(pi, ctx, args);
+			const prompt = normalizeOptionalString(args);
+			const result = await openPiSession(pi, ctx, "tab", { prompt });
 			if (result.ok) {
 				ctx.ui.notify(formatTabSuccessMessage(successMessage, result.tabId), "info");
 			} else {
@@ -70,6 +229,92 @@ function registerTabCommand(
 	});
 }
 
+function registerAgentPiTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "zellij_start_pi",
+		label: "Start Pi in zellij",
+		description:
+			"Start another interactive Pi session in a zellij right split, lower split, or tab, with an optional initial prompt and model settings. Sessions are fresh by default; current history is inherited only when continueSession is explicitly true.",
+		promptSnippet:
+			"Start another interactive Pi agent in a zellij split or tab with an optional initial prompt, model settings, or explicitly inherited history.",
+		promptGuidelines: [
+			"Use zellij_start_pi when the user explicitly requests another Pi session or agent in a zellij split or tab, including a request with an initial prompt.",
+			"Use zellij_start_pi with placement='tab' when the user says tab, placement='right' for a side pane, and placement='down' for a below/lower pane.",
+			"zellij_start_pi starts a fresh session by default. Set continueSession=true only when the user explicitly asks the new Pi session to continue or inherit the current conversation.",
+			"Pass Pi tasks through zellij_start_pi's prompt parameter and model choices through provider, model, and thinking; do not construct or quote a Pi shell command yourself.",
+			"Do not start another Pi session proactively with zellij_start_pi without a user request.",
+		],
+		parameters: ZELLIJ_START_PI_PARAMETERS as any,
+		executionMode: "sequential",
+		async execute(_toolCallId, rawParams, _signal, _onUpdate, ctx) {
+			const params = rawParams as ZellijStartPiParams;
+			if (!isInsideZellijSession()) {
+				throw new Error("This tool must be run from inside an active zellij session");
+			}
+
+			const placement = normalizePiPlacement(params.placement);
+			const prompt = normalizeOptionalString(params.prompt);
+			const provider = normalizeOptionalString(params.provider);
+			const model = normalizeOptionalString(params.model);
+			const thinking = normalizeThinkingLevel(params.thinking);
+			const title = normalizeOptionalString(params.title);
+
+			if (params.provider !== undefined && !provider) {
+				throw new Error("provider must be a non-empty string");
+			}
+			if (params.model !== undefined && !model) {
+				throw new Error("model must be a non-empty string");
+			}
+			if (provider && !model) {
+				throw new Error("provider requires model");
+			}
+			if (params.thinking !== undefined && !thinking) {
+				throw new Error(`Invalid thinking level: ${String(params.thinking)}`);
+			}
+
+			let sessionFile: string | undefined;
+			if (params.continueSession === true) {
+				const continuation = createContinuationSession(ctx);
+				if (!continuation.ok) throw new Error(continuation.error);
+				sessionFile = continuation.sessionFile;
+			}
+
+			const result = await openPiSession(
+				pi,
+				ctx,
+				placement,
+				{ sessionFile, prompt, provider, model, thinking },
+				title,
+			);
+			if (!result.ok) {
+				throw new Error(result.error);
+			}
+
+			const historyLabel = sessionFile ? "a Pi session with inherited history" : "a fresh Pi session";
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Opened ${historyLabel} in a zellij ${getPlacementLabel(result.placement)}.`,
+					},
+				],
+				details: {
+					placement: result.placement,
+					cwd: ctx.cwd,
+					history: sessionFile ? "inherited" : "fresh",
+					...(sessionFile ? { sessionFile } : {}),
+					...(provider ? { provider } : {}),
+					...(model ? { model } : {}),
+					...(thinking ? { thinking } : {}),
+					...(title ? { title } : {}),
+					...(result.paneId ? { paneId: result.paneId } : {}),
+					...(result.tabId ? { tabId: result.tabId } : {}),
+				},
+			};
+		},
+	});
+}
+
 export default function zvSplitExtension(pi: ExtensionAPI) {
 	registerSplitCommand(
 		pi,
@@ -93,4 +338,6 @@ export default function zvSplitExtension(pi: ExtensionAPI) {
 		"Open a new zellij tab and start a fresh pi session",
 		"Opened a new tab",
 	);
+
+	registerAgentPiTool(pi);
 }

package/install.mjs

@@ -14,7 +14,7 @@ const PACKAGE_DIR = path.join(AGENT_DIR, "packages", PACKAGE_NAME);
 const PACKAGE_SETTINGS_ENTRY = `./packages/${PACKAGE_NAME}`;
 const SOURCE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FILES_TO_COPY = ["package.json", "README.md", "CHANGELOG.md"];
-const DIRECTORIES_TO_COPY = ["extensions", "skills", "prompts"];
+const DIRECTORIES_TO_COPY = ["extensions", "prompts"];
 
 const args = process.argv.slice(2);
 const isRemove = args.includes("--remove") || args.includes("-r");

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "pi-zellij",
-  "version": "0.4.6",
+  "version": "0.4.9",
   "description": "Pi package with zellij-powered terminal integrations",
   "author": "Javi Molina",
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -25,7 +28,6 @@
   },
   "files": [
     "extensions/",
-    "skills/",
     "prompts/",
     "install.mjs",
     "README.md",
@@ -38,9 +40,6 @@
     "extensions": [
       "./extensions/index.ts"
     ],
-    "skills": [
-      "./skills"
-    ],
     "prompts": [
       "./prompts"
     ]

package/prompts/review-diff.md

@@ -1,8 +1,6 @@
 ---
 description: Review the current git diff for regressions and missing tests
 ---
-Use the bundled `code-review` skill if it is available.
-
 Review the current git diff in this repository. If `${@:1}` is a GitHub pull request URL, inspect that pull request instead using `gh pr view <url>` and `gh pr diff <url>`. ${@:1} Prioritize regressions, correctness issues, risky edge cases, and missing tests.
 
 Start with a concise summary ordered by severity. Then list concrete findings with suggested fixes. Do not edit files unless asked.

package/prompts/review.md

@@ -1,8 +1,6 @@
 ---
 description: Review a file or directory for bugs, maintainability issues, and missing tests
 ---
-Use the bundled `code-review` skill if it is available.
-
 Review `$1` from the current project. If the target is a GitHub pull request URL, inspect it with `gh pr view <url>` and `gh pr diff <url>`. Focus on correctness, readability, maintainability, and missing tests. If the target is a directory, review the most relevant files within that scope.
 
 Start with a concise summary ordered by severity. Then list concrete findings with suggested fixes. Do not edit files unless asked.