pi-herdr-agents 0.0.1

package/pi-extension/subagents/plan-skill.md

@@ -0,0 +1,262 @@
+---
+name: plan
+description: >
+  Planning workflow. Runs a pre-flight scout, then spawns the planner agent
+  which clarifies WHAT to build and figures out HOW, with the ability to
+  spawn its own scouts mid-session. Use when asked to "plan",
+  "brainstorm", "I want to build X", or "let's design". Requires the
+  subagents extension running inside herdr.
+---
+
+# Plan
+
+A planning workflow. A scout maps the relevant codebase, then an interactive planner clarifies intent + requirements and designs the technical approach, producing a `plan.md` with ordered implementation tasks.
+
+**Announce at start:** "Let me take a quick look, then I'll send a scout to map the codebase before we start the planning session."
+
+---
+
+## The Flow
+
+```
+Phase 1: Quick Assessment (main session — 30s orientation)
+    ↓
+Phase 2: Scout (autonomous — codebase context)
+    ↓
+Phase 3: Spawn Planner Agent (interactive — clarifies WHAT, plans HOW, writes ordered tasks)
+    ↓
+    (Planner may spawn its own scouts mid-session as needed)
+    ↓
+Phase 4: Review Plan (main session)
+    ↓
+Phase 5: Execute Plan Tasks (sequential workers, or isolated parallel workers when independent)
+    ↓
+Phase 6: Integrate Worktree Results (parent-owned, one at a time)
+    ↓
+Phase 7: Review
+```
+
+---
+
+## Fire-and-forget completion
+
+`subagent` is fire-and-forget. After each spawn:
+
+1. End the parent turn.
+2. Let automatic completion delivery resume the parent with the child's result.
+3. Continue from that delivered result.
+
+Do **not** poll, check, list, sleep, tail sessions, or wait-loop for child status.
+
+---
+
+## Phase 1: Quick Assessment
+
+Quick orientation — just enough to give the scout a focused mission:
+
+```bash
+ls -la
+find . -type f -name "*.ts" | head -20  # or relevant extension
+cat package.json 2>/dev/null | head -30
+```
+
+Spend ~30 seconds. Tech stack, project shape, and the area relevant to the user's request. This tells you what to ask the scout to focus on.
+
+---
+
+## Artifact Paths
+
+For a planning run, pick a short `<name>` (e.g. `auth-redesign`) and use a shared directory under `.pi/plans/YYYY-MM-DD-<name>/` for artifacts the parent or planner chooses to write. Pass explicit paths in each subagent's task when a file is required. Scout and reviewer deliver their findings in their final assistant messages; the planner writes `plan.md`.
+
+Standard filenames:
+
+- `.pi/plans/YYYY-MM-DD-<name>/plan.md`
+- `.pi/plans/YYYY-MM-DD-<name>/review.md` (optional, only if a later step materializes reviewer output)
+
+---
+
+## Phase 2: Scout
+
+**Always spawn a scout before the planner.** The scout's final message feeds into the planning session — it lets the planner skip re-asking questions whose answers live in the code, and gives it a solid base to design from.
+
+```typescript
+subagent({
+  name: "🔍 Scout",
+  agent: "scout",
+  task: `Analyze the codebase for [user's request area]. Map file structure, key modules, patterns, conventions, and existing code related to [feature area]. Focus on what a planner would need to understand before designing this feature.
+
+Put your full findings in your final assistant message.`,
+});
+```
+
+**End the parent turn.** When completion delivery resumes you, use the scout's final message as planner context. The scout is source-read-only; do not require it to write a file.
+
+The planner can spawn **additional** scouts mid-session if it hits a local codebase gap. That's expected — don't try to pre-scout every possible area.
+
+External facts are not handled by a bundled researcher. Supply or materialize them in the parent when needed, use only capabilities the parent actually has, or leave them as open questions for the planner.
+
+---
+
+## Phase 3: Spawn Planner Agent
+
+Spawn the interactive planner with the scout's context and the user's request. The planner handles everything from here: clarifying intent, compact requirements engineering, ISC, approach exploration, design validation, premortem, and the plan artifact with ordered tasks.
+
+```typescript
+subagent({
+  name: "💬 Planner",
+  agent: "planner",
+  interactive: true,
+  task: `Plan: [what the user wants to build]
+
+Scout context:
+[paste scout findings here — file structure, conventions, patterns, relevant code]
+
+Save the final plan to: .pi/plans/YYYY-MM-DD-<name>/plan.md
+Include ordered implementation tasks inside the plan (no todo API).`,
+});
+```
+
+**The user works with the planner.** It will clarify requirements lightly (1-2 rounds of questions, not a deep spec session), propose approaches, validate the design, run a premortem, and write the plan with complete worker briefs.
+
+When done, the user presses Ctrl+D and the plan is returned to the main session.
+
+### The planner may spawn its own scouts
+
+During the session, the planner can spawn **`scout`** when a design decision depends on existing code it hasn't read. These are internal to the planning session. You'll see them in herdr but don't need to intervene.
+
+### Optional: extra scout after planning
+
+If the planner significantly changed scope (new subsystems, areas the original scout didn't cover), spawn another scout targeting the new areas before workers start:
+
+```typescript
+subagent({
+  name: "🔍 Scout (updated scope)",
+  agent: "scout",
+  task: "The plan changed scope. Gather context for [new areas]. Read the plan at [plan path]. Focus on [specific files/modules the planner identified that weren't in the original scout]. Put findings in your final assistant message.",
+});
+```
+
+End the parent turn and fold the delivered scout message into worker tasks.
+
+---
+
+## Phase 4: Review Plan
+
+Once the planner closes, read the plan artifact:
+
+```bash
+# or use the read tool
+cat .pi/plans/YYYY-MM-DD-<name>/plan.md
+```
+
+Review with the user:
+
+> "Here's what the planner produced: [brief summary]. Ready to execute, or anything to adjust?"
+
+---
+
+## Phase 5: Execute Plan Tasks
+
+Choose the workspace mode deliberately:
+
+- **Shared checkout, sequential workers (default):** use when tasks overlap, depend on prior uncommitted work, or are faster to integrate directly.
+- **Managed worktrees, parallel workers:** use only when writing tasks are independent and can start from committed state. Give every worker a unique branch.
+- **Ordinary panes, parallel agents:** use for read-only scouts and reviewers; they do not need worktrees.
+
+Pass each worker a **complete task or plan section** — goal, files, constraints, examples/references, acceptance criteria, and whether to commit. Do not pass todo IDs or expect a todo API.
+
+Sequential example:
+
+```typescript
+subagent({
+  name: "🔨 Worker 1/N",
+  agent: "worker",
+  task: `Implement Task 1 from the plan.
+
+Plan: [plan path]
+
+[Paste the full Task 1 section: goal, files, example/reference, constraints, acceptance]
+
+Run relevant tests. Commit only if this task explicitly requires a commit. Report the commit SHA if you commit.`,
+});
+```
+
+For independent writing tasks, first ensure their shared base is committed. The parent checkout's uncommitted files are not copied. Then launch each worker with complete context and a unique branch:
+
+```typescript
+subagent({
+  name: "🔨 Task-1",
+  agent: "worker",
+  cwd: "/absolute/path/to/source-repo",
+  worktree: { branch: "plan-name/task-1", base: "HEAD" },
+  task: `Implement Task 1.
+
+Plan and scout context: [paste everything needed, or provide an absolute plan path and paste the full task section]
+
+Run relevant tests. Commit only if the task explicitly requires a commit. Report the commit SHA if you commit. Do not push, merge, switch branches, or remove the worktree.`,
+});
+```
+
+Launch other independent tasks the same way without waiting. Do not parallelize tasks that edit the same behavior or require another worker's output. For a dependency, integrate the prerequisite first or use its committed SHA as the dependent worker's base.
+
+After each spawn, end the parent turn and continue from automatic completion delivery.
+
+---
+
+## Phase 6: Integrate Worktree Results
+
+A worktree completion is a review handoff, not acceptance. For every result:
+
+1. Use the returned worktree path, workspace ID, branch, and base/head SHAs.
+2. Inspect `git status`, `git log <base>..HEAD`, and `git diff <base>...HEAD` in the worktree.
+3. Run the relevant tests there.
+4. Resolve dirty/conflicted work before integration.
+5. Merge or cherry-pick according to repository policy, one result at a time.
+6. Re-run affected tests on the destination branch after each integration.
+7. Keep the worktree until the result is accepted and preserved; cleanup is explicit.
+
+The extension does not push, create PRs, merge, or remove worktrees automatically. `subagent_resume` does not reattach worktree tracking; continue follow-up in the retained workspace. See `docs/worktree-subagents.md` when this package's guide is available.
+
+Skip this phase when all workers used the shared checkout.
+
+---
+
+## Phase 7: Review
+
+After all shared-checkout changes and accepted worktree results are integrated:
+
+```typescript
+subagent({
+  name: "Reviewer",
+  agent: "reviewer",
+  interactive: false,
+  task: "Review the recent changes. Plan: [plan path]. Put the full review in your final assistant message.",
+});
+```
+
+End the parent turn. Use the delivered review message.
+
+Triage findings:
+
+- **P0** — Real bugs, security issues → fix now
+- **P1** — Genuine traps, maintenance dangers → fix before merging
+- **P2** — Minor issues → fix if quick, note otherwise
+- **P3** — Nits → skip
+
+Spawn workers with complete fix tasks for P0/P1. Re-review only if fixes were substantial.
+
+---
+
+## Completion Checklist
+
+Before reporting done:
+
+1. Scout ran before the planner?
+2. Scout context was passed to the planner?
+3. Parallel writers used unique worktree branches from committed bases?
+4. Every worktree result was inspected, tested, and integrated deliberately?
+5. Every plan task was executed or explicitly deferred?
+6. Every requested commit is polished and its SHA reported?
+7. Retained worktrees were kept or explicitly cleaned up only after review?
+8. Reviewer ran against the integrated result?
+9. Reviewer findings were triaged and addressed?

package/pi-extension/subagents/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "pi-auto-exit",
+  "version": "1.0.0",
+  "description": "Auto-exit plugin for pi-spawned Claude sessions"
+}

package/pi-extension/subagents/plugin/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/on-stop.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/pi-extension/subagents/plugin/hooks/on-stop.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Stop hook for pi-spawned Claude sessions.
+# Writes a sentinel file when Claude completes autonomously (no user interjection).
+
+set -euo pipefail
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Guard: if stop_hook_active is true, we're in a loop — bail out
+stop_hook_active=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('stop_hook_active', False))" 2>/dev/null || echo "False")
+if [ "$stop_hook_active" = "True" ]; then
+  exit 0
+fi
+
+# Guard: only act for pi-spawned sessions
+if [ -z "${PI_CLAUDE_SENTINEL:-}" ]; then
+  exit 0
+fi
+
+# Get transcript path
+transcript_path=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('transcript_path', ''))" 2>/dev/null || echo "")
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  exit 0
+fi
+
+# Count real human messages in transcript (not tool results)
+# Claude's transcript format:
+#   Human message: {"type": "user", "message": {"role": "user", "content": "..."}}
+#   Tool result:   {"type": "user", "message": {"role": "user", "content": [{"type": "tool_result", ...}]}}
+# We only count entries where content is a string (real human input)
+user_msg_count=$(python3 - "$transcript_path" <<'EOF'
+import sys, json
+
+transcript_path = sys.argv[1]
+count = 0
+with open(transcript_path, 'r') as f:
+    for line in f:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+            if entry.get('type') != 'user':
+                continue
+            content = entry.get('message', {}).get('content', '')
+            # Real human messages have string content
+            # Tool results have array content with tool_result blocks
+            if isinstance(content, str):
+                count += 1
+        except (json.JSONDecodeError, AttributeError):
+            pass
+print(count)
+EOF
+)
+
+# Always write transcript path so the watcher can copy the session file
+if [ -n "$transcript_path" ]; then
+  echo "$transcript_path" > "${PI_CLAUDE_SENTINEL}.transcript" 2>/dev/null || true
+fi
+
+# If exactly 1 user message (the initial prompt), this was autonomous — signal completion
+if [ "$user_msg_count" -eq 1 ]; then
+  # Write last_assistant_message to sentinel so the watcher gets a clean result
+  echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('last_assistant_message', ''))" > "$PI_CLAUDE_SENTINEL" 2>/dev/null || touch "$PI_CLAUDE_SENTINEL"
+fi
+
+exit 0

package/pi-extension/subagents/runtime-routing.ts

@@ -0,0 +1,313 @@
+import {
+  clampThinkingLevel,
+  getSupportedThinkingLevels,
+  type Model,
+  type ModelThinkingLevel,
+} from "@earendil-works/pi-ai";
+
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+export function isThinkingLevel(value: string): value is ThinkingLevel {
+  return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export type RuntimeSource = "request" | "agent" | "parent";
+
+export interface RuntimeRequest {
+  model?: string;
+  thinking?: ThinkingLevel;
+}
+
+export interface ParentRuntime {
+  provider: string;
+  modelId: string;
+  thinking: ThinkingLevel;
+}
+
+export interface RoutingModel {
+  provider: string;
+  id: string;
+  reasoning: boolean;
+  thinkingLevelMap?: Model<any>["thinkingLevelMap"];
+  input?: string[];
+  contextWindow?: number;
+  maxTokens?: number;
+  cost?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+}
+
+export interface ModelRegistryAdapter {
+  find(provider: string, modelId: string): RoutingModel | undefined;
+  available(): RoutingModel[];
+  hasConfiguredAuth(model: { provider: string; id: string }): boolean;
+}
+
+export interface ResolvedRuntimePlan {
+  provider: string;
+  modelId: string;
+  model: string;
+  thinking: ThinkingLevel;
+  modelSource: RuntimeSource;
+  thinkingSource: RuntimeSource;
+  requestedModel?: string;
+  requestedThinking?: ThinkingLevel;
+  thinkingAdjustment?: {
+    from: ThinkingLevel;
+    to: ThinkingLevel;
+    reason: "non-reasoning" | "inherited-clamp";
+  };
+  observed?: {
+    model?: string;
+    thinking?: ThinkingLevel;
+  };
+  runtimeMismatch?: string;
+}
+
+export class RuntimeResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RuntimeResolutionError";
+  }
+}
+
+export function parseExactModelRef(
+  reference: string,
+): { provider: string; modelId: string } | undefined {
+  const trimmed = reference.trim();
+  const separator = trimmed.indexOf("/");
+  if (separator <= 0 || separator === trimmed.length - 1) return undefined;
+  const provider = trimmed.slice(0, separator).trim();
+  const modelId = trimmed.slice(separator + 1).trim();
+  return provider && modelId ? { provider, modelId } : undefined;
+}
+
+function toRoutingModel(value: any): RoutingModel | undefined {
+  if (!value || typeof value.provider !== "string" || typeof value.id !== "string") {
+    return undefined;
+  }
+  return {
+    provider: value.provider,
+    id: value.id,
+    reasoning: value.reasoning ?? false,
+    thinkingLevelMap: value.thinkingLevelMap,
+    input: Array.isArray(value.input) ? value.input : undefined,
+    contextWindow: typeof value.contextWindow === "number" ? value.contextWindow : undefined,
+    maxTokens: typeof value.maxTokens === "number" ? value.maxTokens : undefined,
+    cost: value.cost,
+  };
+}
+
+export function wrapPiModelRegistry(registry: {
+  find(provider: string, modelId: string): any;
+  getAvailable?: () => any[];
+  getAll?: () => any[];
+  hasConfiguredAuth?: (model: any) => boolean;
+}): ModelRegistryAdapter {
+  return {
+    find(provider, modelId) {
+      return toRoutingModel(registry.find(provider, modelId));
+    },
+    available() {
+      const direct = registry.getAvailable?.() ?? [];
+      const source = direct.length > 0 ? direct : registry.getAll?.() ?? [];
+      const models: RoutingModel[] = [];
+      const seen = new Set<string>();
+      for (const raw of source) {
+        const candidate = toRoutingModel(raw);
+        if (!candidate) continue;
+        if (direct.length === 0 && registry.hasConfiguredAuth && !registry.hasConfiguredAuth(raw)) {
+          continue;
+        }
+        const ref = `${candidate.provider}/${candidate.id}`;
+        if (seen.has(ref)) continue;
+        seen.add(ref);
+        models.push(candidate);
+      }
+      return models;
+    },
+    hasConfiguredAuth(model) {
+      if (!registry.hasConfiguredAuth) {
+        return (registry.getAvailable?.() ?? []).some(
+          (candidate) => candidate.provider === model.provider && candidate.id === model.id,
+        );
+      }
+      const original = registry.find(model.provider, model.id);
+      return !!original && registry.hasConfiguredAuth(original);
+    },
+  };
+}
+
+function asPiModel(model: RoutingModel): Model<any> {
+  return {
+    provider: model.provider,
+    id: model.id,
+    name: model.id,
+    api: "openai-completions",
+    baseUrl: "",
+    reasoning: model.reasoning,
+    thinkingLevelMap: model.thinkingLevelMap,
+    input: (model.input?.filter((entry): entry is "text" | "image" =>
+      entry === "text" || entry === "image") ?? ["text"]),
+    contextWindow: model.contextWindow ?? 0,
+    maxTokens: model.maxTokens ?? 0,
+    cost: {
+      input: model.cost?.input ?? 0,
+      output: model.cost?.output ?? 0,
+      cacheRead: model.cost?.cacheRead ?? 0,
+      cacheWrite: model.cost?.cacheWrite ?? 0,
+    },
+  };
+}
+
+function formatSupported(model: RoutingModel): string {
+  const levels = getSupportedThinkingLevels(asPiModel(model));
+  return levels.length > 0 ? levels.join(", ") : "(none)";
+}
+
+function selectField(
+  requestValue: string | undefined,
+  agentValue: string | undefined,
+): { value?: string; source: RuntimeSource } {
+  if (requestValue != null && requestValue !== "") {
+    return { value: requestValue, source: "request" };
+  }
+  if (agentValue != null && agentValue !== "") {
+    return { value: agentValue, source: "agent" };
+  }
+  return { source: "parent" };
+}
+
+export function resolveRuntimePlan(
+  request: RuntimeRequest,
+  agentDefaults: RuntimeRequest,
+  parent: ParentRuntime,
+  registry: ModelRegistryAdapter,
+): ResolvedRuntimePlan {
+  const modelSelection = selectField(request.model, agentDefaults.model);
+  let provider = parent.provider;
+  let modelId = parent.modelId;
+  let selectedModel = registry.find(provider, modelId);
+
+  if (modelSelection.value) {
+    const parsed = parseExactModelRef(modelSelection.value);
+    if (!parsed) {
+      throw new RuntimeResolutionError(
+        `model ${JSON.stringify(modelSelection.value)} must be an exact authenticated provider/model-id`,
+      );
+    }
+    const found = registry.find(parsed.provider, parsed.modelId);
+    if (!found) {
+      const alternatives = registry.available().map((model) => `${model.provider}/${model.id}`);
+      throw new RuntimeResolutionError(
+        `unknown model ${JSON.stringify(modelSelection.value)}; exact registry match required. Available: ${alternatives.join(", ") || "(none)"}`,
+      );
+    }
+    if (!registry.hasConfiguredAuth(found)) {
+      throw new RuntimeResolutionError(
+        `model ${JSON.stringify(modelSelection.value)} has no configured authentication`,
+      );
+    }
+    provider = found.provider;
+    modelId = found.id;
+    selectedModel = found;
+  }
+
+  const thinkingSelection = selectField(request.thinking, agentDefaults.thinking);
+  const preferredThinking = thinkingSelection.value ?? parent.thinking;
+  if (!isThinkingLevel(preferredThinking)) {
+    throw new RuntimeResolutionError(
+      `thinking ${JSON.stringify(preferredThinking)} must be one of: ${THINKING_LEVELS.join(", ")}`,
+    );
+  }
+
+  let thinking = preferredThinking;
+  let thinkingAdjustment: ResolvedRuntimePlan["thinkingAdjustment"];
+  if (thinkingSelection.source !== "parent") {
+    if (!selectedModel) {
+      throw new RuntimeResolutionError(
+        `model capability information is unavailable; cannot validate explicit thinking ${JSON.stringify(preferredThinking)}`,
+      );
+    }
+    const supported = getSupportedThinkingLevels(asPiModel(selectedModel));
+    if (!supported.includes(preferredThinking as ModelThinkingLevel)) {
+      throw new RuntimeResolutionError(
+        `thinking ${JSON.stringify(preferredThinking)} is not supported by ${JSON.stringify(`${provider}/${modelId}`)}; supported: ${formatSupported(selectedModel)}`,
+      );
+    }
+  } else if (selectedModel) {
+    const clamped = clampThinkingLevel(asPiModel(selectedModel), preferredThinking);
+    thinking = clamped as ThinkingLevel;
+    if (thinking !== preferredThinking) {
+      thinkingAdjustment = {
+        from: preferredThinking,
+        to: thinking,
+        reason: selectedModel.reasoning ? "inherited-clamp" : "non-reasoning",
+      };
+    }
+  }
+
+  return {
+    provider,
+    modelId,
+    model: `${provider}/${modelId}`,
+    thinking,
+    modelSource: modelSelection.source,
+    thinkingSource: thinkingSelection.source,
+    ...(modelSelection.value ? { requestedModel: modelSelection.value } : {}),
+    ...(thinkingSelection.value ? { requestedThinking: preferredThinking } : {}),
+    ...(thinkingAdjustment ? { thinkingAdjustment } : {}),
+  };
+}
+
+function formatTokenCount(value: number | undefined): string | undefined {
+  if (!value || value <= 0) return undefined;
+  if (value >= 1_000_000) return `${Number((value / 1_000_000).toFixed(1))}m`;
+  if (value >= 1_000) return `${Math.round(value / 1_000)}k`;
+  return String(value);
+}
+
+export function buildAuthenticatedModelCatalog(
+  registry: ModelRegistryAdapter,
+  limit = 24,
+): string {
+  const models = registry.available().sort((a, b) =>
+    `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`),
+  );
+  const visibleModels = models.slice(0, limit);
+  const lines = [
+    "Authenticated subagent models (use exact provider/model-id only):",
+  ];
+  for (const model of visibleModels) {
+    const supportedThinking = getSupportedThinkingLevels(asPiModel(model));
+    const facts = [
+      model.reasoning
+        ? `reasoning (${supportedThinking.join("/") || "no thinking levels"})`
+        : "non-reasoning",
+      model.input?.includes("image") ? "text+image" : "text",
+      formatTokenCount(model.contextWindow) ? `${formatTokenCount(model.contextWindow)} context` : undefined,
+      formatTokenCount(model.maxTokens) ? `${formatTokenCount(model.maxTokens)} max output` : undefined,
+    ].filter(Boolean);
+    lines.push(`- ${model.provider}/${model.id} — ${facts.join(", ")}`);
+  }
+  if (models.length === 0) lines.push("- none discovered; inherit the parent runtime");
+  if (models.length > visibleModels.length) {
+    lines.push(`- … ${models.length - visibleModels.length} more authenticated models omitted`);
+  }
+  lines.push(
+    "Default: inherit the parent model and thinking. Override thinking first; override model only when task capability, speed, cost, modality, or context warrants it.",
+  );
+  return lines.join("\n");
+}