@pi-unipi/unipi 2.7.0 → 2.8.0

package/packages/background-tasks/src/ui/fusion-model-selector.ts

@@ -0,0 +1,322 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { Key, matchesKey, truncateToWidth, type Component } from '@earendil-works/pi-tui';
+import { CURRENT_MODEL_SELECTION, defaultFusionModelConfig } from '../fusion/config.js';
+import type { FusionModelConfigV1, FusionModelSelection } from '../fusion/types.js';
+
+export const FUSION_MODEL_SLOT_IDS = [
+  'candidate-1',
+  'candidate-2',
+  'candidate-3',
+  'evaluator',
+  'merger',
+] as const;
+
+export type FusionModelSlotId = (typeof FUSION_MODEL_SLOT_IDS)[number];
+
+export interface FusionModelChoice {
+  value: FusionModelSelection;
+  label: string;
+  description: string;
+  available: boolean;
+}
+
+export type FusionModelSelectorResult =
+  | { type: 'saved'; config: FusionModelConfigV1 }
+  | { type: 'cancelled' };
+
+export interface FusionModelSelectorOptions {
+  initialConfig: FusionModelConfigV1;
+  choices: readonly FusionModelChoice[];
+  theme: Theme;
+  onSave: (config: FusionModelConfigV1) => Promise<void>;
+  onDone: (result: FusionModelSelectorResult) => void;
+  onRenderRequest?: (() => void) | undefined;
+}
+
+type SelectorMode = 'slots' | 'models';
+
+interface SlotView {
+  id: FusionModelSlotId;
+  label: string;
+  value: FusionModelSelection;
+}
+
+function slotLabel(id: FusionModelSlotId): string {
+  if (id === 'candidate-1') return 'Candidate 1';
+  if (id === 'candidate-2') return 'Candidate 2';
+  if (id === 'candidate-3') return 'Candidate 3';
+  if (id === 'evaluator') return 'Evaluator';
+  return 'Merger';
+}
+
+function configValue(config: FusionModelConfigV1, id: FusionModelSlotId): FusionModelSelection {
+  if (id === 'candidate-1') return config.candidates[0];
+  if (id === 'candidate-2') return config.candidates[1];
+  if (id === 'candidate-3') return config.candidates[2];
+  if (id === 'evaluator') return config.evaluator;
+  return config.merger;
+}
+
+function updateConfig(
+  config: FusionModelConfigV1,
+  id: FusionModelSlotId,
+  value: FusionModelSelection,
+): FusionModelConfigV1 {
+  if (id === 'candidate-1')
+    return { ...config, candidates: [value, config.candidates[1], config.candidates[2]] };
+  if (id === 'candidate-2')
+    return { ...config, candidates: [config.candidates[0], value, config.candidates[2]] };
+  if (id === 'candidate-3')
+    return { ...config, candidates: [config.candidates[0], config.candidates[1], value] };
+  if (id === 'evaluator') return { ...config, evaluator: value };
+  return { ...config, merger: value };
+}
+
+function queryMatches(choice: FusionModelChoice, query: string): boolean {
+  if (query.length === 0) return true;
+  const haystack = `${choice.label} ${choice.description} ${choice.value}`.toLowerCase();
+  return haystack.includes(query.toLowerCase());
+}
+
+function printable(data: string): string | undefined {
+  if (data.length !== 1) return undefined;
+  const code = data.charCodeAt(0);
+  if (code < 32 || code === 127) return undefined;
+  return data;
+}
+
+function modelChoiceLine(choice: FusionModelChoice): string {
+  const status = choice.available ? '' : ' (unavailable)';
+  return `${choice.label}${status}${choice.description ? ` — ${choice.description}` : ''}`;
+}
+
+function slotViews(config: FusionModelConfigV1): SlotView[] {
+  return FUSION_MODEL_SLOT_IDS.map((id) => ({
+    id,
+    label: slotLabel(id),
+    value: configValue(config, id),
+  }));
+}
+
+export class FusionModelSelector implements Component {
+  private readonly choices: readonly FusionModelChoice[];
+  private readonly theme: Theme;
+  private readonly onSave: (config: FusionModelConfigV1) => Promise<void>;
+  private readonly onDone: (result: FusionModelSelectorResult) => void;
+  private readonly onRenderRequest: (() => void) | undefined;
+  private draft: FusionModelConfigV1;
+  private mode: SelectorMode = 'slots';
+  private selectedSlot = 0;
+  private selectedChoice = 0;
+  private search = '';
+  private saving = false;
+  private error: string | undefined;
+  private cachedWidth: number | undefined;
+  private cachedLines: string[] | undefined;
+
+  constructor(options: FusionModelSelectorOptions) {
+    this.draft = options.initialConfig;
+    this.choices = options.choices;
+    this.theme = options.theme;
+    this.onSave = options.onSave;
+    this.onDone = options.onDone;
+    this.onRenderRequest = options.onRenderRequest;
+  }
+
+  render(width: number): string[] {
+    if (this.cachedWidth === width && this.cachedLines !== undefined) return this.cachedLines;
+    const lines = this.mode === 'slots' ? this.renderSlots(width) : this.renderChoices(width);
+    this.cachedWidth = width;
+    this.cachedLines = lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+    return this.cachedLines;
+  }
+
+  handleInput(data: string): void {
+    if (this.saving) return;
+    if (this.mode === 'slots') this.handleSlotInput(data);
+    else this.handleChoiceInput(data);
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+
+  private renderSlots(width: number): string[] {
+    const slots = slotViews(this.draft);
+    const lines = [
+      this.theme.fg('accent', this.theme.bold('Fusion models')),
+      this.theme.fg('dim', 'Select five slots. Duplicate models are allowed.'),
+      '',
+    ];
+    for (const [index, slot] of slots.entries()) {
+      const marker = index === this.selectedSlot ? this.theme.fg('accent', '›') : ' ';
+      const value = this.describeSelection(slot.value);
+      lines.push(`${marker} ${slot.label.padEnd(12)} ${value}`);
+    }
+    lines.push('');
+    if (this.error !== undefined) lines.push(this.theme.fg('error', this.error));
+    const saveText = this.saving ? 'saving…' : 's save';
+    lines.push(this.theme.fg('dim', `↑↓ slot • enter choose • r reset • ${saveText} • esc cancel`));
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private renderChoices(width: number): string[] {
+    const selectedSlot = FUSION_MODEL_SLOT_IDS[this.selectedSlot];
+    const title =
+      selectedSlot === undefined ? 'Choose model' : `Choose model for ${slotLabel(selectedSlot)}`;
+    const filtered = this.filteredChoices();
+    const lines = [
+      this.theme.fg('accent', this.theme.bold(title)),
+      `${this.theme.fg('dim', 'Search:')} ${this.search || this.theme.fg('dim', '(type to filter)')}`,
+      '',
+    ];
+    if (filtered.length === 0) {
+      lines.push(this.theme.fg('warning', 'No matching models.'));
+    } else {
+      const windowStart = Math.max(
+        0,
+        Math.min(this.selectedChoice - 6, Math.max(0, filtered.length - 12)),
+      );
+      const windowItems = filtered.slice(windowStart, windowStart + 12);
+      for (const [offset, choice] of windowItems.entries()) {
+        const index = windowStart + offset;
+        const marker = index === this.selectedChoice ? this.theme.fg('accent', '›') : ' ';
+        const label = choice.available ? choice.label : this.theme.fg('warning', choice.label);
+        const description = choice.description
+          ? this.theme.fg('dim', ` — ${choice.description}`)
+          : '';
+        const stale = choice.available ? '' : this.theme.fg('warning', ' (unavailable)');
+        lines.push(`${marker} ${label}${stale}${description}`);
+      }
+      if (filtered.length > windowItems.length) {
+        lines.push(
+          this.theme.fg(
+            'dim',
+            `${String(windowStart + 1)}-${String(windowStart + windowItems.length)} of ${String(filtered.length)}`,
+          ),
+        );
+      }
+    }
+    lines.push('');
+    lines.push(this.theme.fg('dim', '↑↓ choose • enter apply • backspace edit search • esc back'));
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  private handleSlotInput(data: string): void {
+    if (matchesKey(data, Key.up)) {
+      this.selectedSlot = Math.max(0, this.selectedSlot - 1);
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedSlot = Math.min(FUSION_MODEL_SLOT_IDS.length - 1, this.selectedSlot + 1);
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.enter) || data === '\r') {
+      this.mode = 'models';
+      this.search = '';
+      this.selectedChoice = this.selectedChoiceForCurrentSlot();
+      this.changed();
+      return;
+    }
+    if (data === 'r') {
+      this.draft = defaultFusionModelConfig();
+      this.error = undefined;
+      this.changed();
+      return;
+    }
+    if (data === 's') {
+      void this.save();
+      return;
+    }
+    if (matchesKey(data, Key.escape) || data === 'q') {
+      this.onDone({ type: 'cancelled' });
+    }
+  }
+
+  private handleChoiceInput(data: string): void {
+    const filtered = this.filteredChoices();
+    if (matchesKey(data, Key.up)) {
+      this.selectedChoice = Math.max(0, this.selectedChoice - 1);
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.selectedChoice = Math.min(Math.max(0, filtered.length - 1), this.selectedChoice + 1);
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.enter) || data === '\r') {
+      const choice = filtered[this.selectedChoice];
+      const slot = FUSION_MODEL_SLOT_IDS[this.selectedSlot];
+      if (choice !== undefined && slot !== undefined) {
+        this.draft = updateConfig(this.draft, slot, choice.value);
+        this.mode = 'slots';
+        this.error = undefined;
+      }
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.escape)) {
+      this.mode = 'slots';
+      this.changed();
+      return;
+    }
+    if (matchesKey(data, Key.backspace) || data === '\x7f') {
+      this.search = this.search.slice(0, -1);
+      this.selectedChoice = 0;
+      this.changed();
+      return;
+    }
+    const char = printable(data);
+    if (char !== undefined) {
+      this.search += char;
+      this.selectedChoice = 0;
+      this.changed();
+    }
+  }
+
+  private async save(): Promise<void> {
+    this.saving = true;
+    this.error = undefined;
+    this.changed();
+    try {
+      await this.onSave(this.draft);
+      this.onDone({ type: 'saved', config: this.draft });
+    } catch (error) {
+      this.error = error instanceof Error ? error.message : String(error);
+      this.saving = false;
+      this.changed();
+    }
+  }
+
+  private changed(): void {
+    this.invalidate();
+    this.onRenderRequest?.();
+  }
+
+  private filteredChoices(): readonly FusionModelChoice[] {
+    return this.choices.filter((choice) => queryMatches(choice, this.search));
+  }
+
+  private selectedChoiceForCurrentSlot(): number {
+    const slot = FUSION_MODEL_SLOT_IDS[this.selectedSlot];
+    if (slot === undefined) return 0;
+    const current = configValue(this.draft, slot);
+    const filtered = this.filteredChoices();
+    const index = filtered.findIndex((choice) => choice.value === current);
+    return index >= 0 ? index : 0;
+  }
+
+  private describeSelection(value: FusionModelSelection): string {
+    if (value === CURRENT_MODEL_SELECTION) {
+      const current = this.choices.find((choice) => choice.value === CURRENT_MODEL_SELECTION);
+      return current === undefined ? CURRENT_MODEL_SELECTION : modelChoiceLine(current);
+    }
+    const found = this.choices.find((choice) => choice.value === value);
+    if (found === undefined) return `${value} (unavailable)`;
+    return modelChoiceLine(found);
+  }
+}

package/packages/background-tasks/src/windows-taskkill.ts

@@ -0,0 +1,250 @@
+import { spawn as nodeSpawn, type SpawnOptions } from 'node:child_process';
+import { win32 } from 'node:path';
+
+export type WindowsKillPhase = 'terminate' | 'force';
+
+export interface TaskkillOutcome {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+interface TaskkillOutputStream {
+  on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+
+interface WindowsTaskkillChildProcess {
+  readonly stdout?: TaskkillOutputStream | null | undefined;
+  readonly stderr?: TaskkillOutputStream | null | undefined;
+  kill(signal?: NodeJS.Signals): boolean;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  on(
+    event: 'close',
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+  ): unknown;
+}
+
+type WindowsTaskkillSpawn = (
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+) => WindowsTaskkillChildProcess;
+
+export interface WindowsTaskkillOptions {
+  readonly spawn?: WindowsTaskkillSpawn;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly maxCaptureBytes?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_CAPTURE_BYTES = 8 * 1024;
+
+class BoundedCapture {
+  private readonly chunks: Buffer[] = [];
+  private capturedBytes = 0;
+  private truncated = false;
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(data: Buffer | string): void {
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+    if (buffer.length === 0) return;
+    const remaining = this.maxBytes - this.capturedBytes;
+    if (remaining > 0) {
+      const kept = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);
+      this.chunks.push(kept);
+      this.capturedBytes += kept.length;
+    }
+    if (buffer.length > Math.max(0, remaining)) this.truncated = true;
+  }
+
+  text(): string {
+    return Buffer.concat(this.chunks, this.capturedBytes).toString('utf8');
+  }
+
+  isTruncated(): boolean {
+    return this.truncated;
+  }
+}
+
+function lookupEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  const direct = env[name];
+  if (direct !== undefined) return direct;
+  const lowerName = name.toLowerCase();
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === lowerName) return env[key];
+  }
+  return undefined;
+}
+
+function validateWindowsRoot(raw: string, label: string): string {
+  const value = raw.trim();
+  if (value.length === 0) throw new Error(`${label} is empty; cannot resolve taskkill.exe`);
+  if (value.includes('\0')) throw new Error(`${label} contains a NUL byte; cannot resolve taskkill.exe`);
+  if (!win32.isAbsolute(value)) {
+    throw new Error(`${label} must be an absolute Windows path; cannot resolve taskkill.exe`);
+  }
+  return value;
+}
+
+export function resolveTaskkillPath(env: NodeJS.ProcessEnv = process.env): string {
+  const systemRoot = lookupEnv(env, 'SystemRoot');
+  if (systemRoot !== undefined) {
+    return win32.join(validateWindowsRoot(systemRoot, 'SystemRoot'), 'System32', 'taskkill.exe');
+  }
+
+  const windir = lookupEnv(env, 'WINDIR');
+  if (windir !== undefined) {
+    return win32.join(validateWindowsRoot(windir, 'WINDIR'), 'System32', 'taskkill.exe');
+  }
+
+  throw new Error('Cannot resolve taskkill.exe: SystemRoot is missing and WINDIR fallback is missing');
+}
+
+function validatePid(pid: number): void {
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    throw new Error(`Invalid Windows taskkill pid ${String(pid)}; expected a positive safe integer`);
+  }
+}
+
+function validatePhase(phase: WindowsKillPhase): void {
+  if (phase !== 'terminate' && phase !== 'force') {
+    throw new Error(`Invalid Windows taskkill phase ${String(phase)}`);
+  }
+}
+
+function positiveFiniteInteger(value: number | undefined, fallback: number, label: string): number {
+  const candidate = value ?? fallback;
+  if (!Number.isFinite(candidate) || candidate <= 0) {
+    throw new Error(`${label} must be a positive finite number`);
+  }
+  return Math.max(1, Math.floor(candidate));
+}
+
+function outcome(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  stdout: BoundedCapture,
+  stderr: BoundedCapture,
+): TaskkillOutcome {
+  return {
+    exitCode,
+    signal,
+    stdout: stdout.text(),
+    stderr: stderr.text(),
+    stdoutTruncated: stdout.isTruncated(),
+    stderrTruncated: stderr.isTruncated(),
+  };
+}
+
+function defaultSpawn(command: string, args: string[], options: SpawnOptions): WindowsTaskkillChildProcess {
+  return nodeSpawn(command, args, options);
+}
+
+export function runWindowsTaskkill(
+  pid: number,
+  phase: WindowsKillPhase,
+  options: WindowsTaskkillOptions = {},
+): Promise<TaskkillOutcome> {
+  validatePid(pid);
+  validatePhase(phase);
+  const env = options.env ?? process.env;
+  const taskkill = resolveTaskkillPath(env);
+  const timeoutMs = positiveFiniteInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');
+  const maxCaptureBytes = positiveFiniteInteger(
+    options.maxCaptureBytes,
+    DEFAULT_MAX_CAPTURE_BYTES,
+    'maxCaptureBytes',
+  );
+  const spawn = options.spawn ?? defaultSpawn;
+  const abortSignal = options.signal;
+
+  const args = ['/PID', String(pid), '/T'];
+  if (phase === 'force') args.push('/F');
+
+  if (abortSignal?.aborted) {
+    const stdout = new BoundedCapture(maxCaptureBytes);
+    const stderr = new BoundedCapture(maxCaptureBytes);
+    stderr.append('Windows taskkill was aborted before launch');
+    return Promise.resolve(outcome(null, null, stdout, stderr));
+  }
+
+  return new Promise<TaskkillOutcome>((resolve) => {
+    const stdout = new BoundedCapture(maxCaptureBytes);
+    const stderr = new BoundedCapture(maxCaptureBytes);
+    let settled = false;
+    let timeout: NodeJS.Timeout | undefined;
+    let child: WindowsTaskkillChildProcess | undefined;
+    let abortListener: (() => void) | undefined;
+
+    const settle = (result: TaskkillOutcome): void => {
+      if (settled) return;
+      settled = true;
+      if (timeout !== undefined) clearTimeout(timeout);
+      if (abortSignal !== undefined && abortListener !== undefined) {
+        abortSignal.removeEventListener('abort', abortListener);
+      }
+      resolve(result);
+    };
+
+    const stopHelper = (reason: string): void => {
+      stderr.append(reason);
+      if (child !== undefined) {
+        try {
+          child.kill('SIGKILL');
+        } catch (error) {
+          stderr.append(`; helper kill failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      settle(outcome(null, null, stdout, stderr));
+    };
+
+    const spawnOptions: SpawnOptions = {
+      env,
+      shell: false,
+      windowsVerbatimArguments: false,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    };
+
+    try {
+      child = spawn(taskkill, args, spawnOptions);
+    } catch (error) {
+      stderr.append(`Windows taskkill spawn failed: ${error instanceof Error ? error.message : String(error)}`);
+      settle(outcome(null, null, stdout, stderr));
+      return;
+    }
+
+    child.stdout?.on('data', (data) => {
+      stdout.append(data);
+    });
+    child.stderr?.on('data', (data) => {
+      stderr.append(data);
+    });
+    child.on('error', (error) => {
+      stderr.append(`Windows taskkill spawn error: ${error.message}`);
+      settle(outcome(null, null, stdout, stderr));
+    });
+    child.on('close', (code, signal) => {
+      settle(outcome(code, signal, stdout, stderr));
+    });
+
+    abortListener = () => {
+      stopHelper('Windows taskkill was aborted');
+    };
+    abortSignal?.addEventListener('abort', abortListener, { once: true });
+
+    // This timeout is the settlement guarantee for a taskkill helper that never
+    // exits. It must keep the event loop alive: an unref'd timer lets the loop
+    // drain first and leaves this promise pending forever. `settle()` always
+    // clears it, so keeping it referenced cannot leak.
+    timeout = setTimeout(() => {
+      stopHelper(`Windows taskkill timed out after ${String(timeoutMs)}ms`);
+    }, timeoutMs);
+  });
+}

package/packages/subagents/agents/delegate.md

@@ -0,0 +1,14 @@
+---
+name: delegate
+description: Lightweight subagent that inherits the parent model with no default reads
+systemPromptMode: append
+inheritProjectContext: true
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+inheritSkills: false
+---
+
+You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
+
+The builtin delegate uses a strict tool allowlist and does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
+
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return normally when no coordination is needed.

package/packages/subagents/agents/oracle.md

@@ -0,0 +1,78 @@
+---
+name: oracle
+aliases: advisor
+description: High-context decision-consistency oracle that protects inherited state and prevents drift
+tools: read, grep, find, ls, bash
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+---
+
+You are the oracle: a high-context decision-consistency subagent.
+
+Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
+
+Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
+
+Match search scope to the question. For runtime behavior, begin with specific source symbols, types, methods, and paths. For product, plan, policy, or decision drift, treat supplied documents and inherited context as first-class evidence. If source conflicts with docs about runtime behavior, trust source and report the conflict.
+
+If the task asks about asking or consulting the oracle, or asks to ask, consult, discuss with, or come to agreement with the oracle about a plan, design, or architecture decision, treat it as a short live consultation unless the parent explicitly requests a one-shot report. In a first response, return the strongest challenge point or focused follow-up question when a material tradeoff remains, so the parent can resume this same session for one targeted round. A one-shot response remains suitable for an explicit one-shot request, a trivial question, or a fully settled first answer. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
+
+If you need clarification from the main agent and bridge instructions provide `contact_supervisor`, use it with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
+
+Do not send routine completion handoffs. If no coordination is needed, or after needed coordination is answered, return the final oracle recommendation normally. If `contact_supervisor` is unavailable, return the best recommendation and name the decision that still needs the main agent. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
+
+Core responsibilities:
+- reconstruct inherited decisions, constraints, and open questions from the context
+- identify drift between the current trajectory and those inherited decisions
+- surface contradictions and hidden assumptions the main agent may be missing
+- call out when a proposed move conflicts with an earlier decision or constraint
+- protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
+- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
+
+What you do not do by default:
+- do not edit files or write code
+- do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
+- do not assume a `worker` implementation handoff is the default outcome
+- do not propose broad pivots unless the context clearly supports them
+- do not continue the user conversation directly
+
+Working rules:
+- Use `bash` only for inspection, verification, or read-only analysis.
+- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` when bridge instructions provide that tool. If no supervisor channel is available, return the best recommendation and name the unresolved decision instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` when bridge instructions provide that tool. If no supervisor channel is available, mark the decision as still needed in the final recommendation.
+- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
+
+Your output should follow this shape. If no executor handoff is warranted, say so plainly.
+
+Inherited decisions:
+- the key decisions, constraints, and assumptions already in play
+
+Diagnosis:
+- what is actually going on
+- what the main agent may be missing
+
+Drift / contradiction check:
+- where the current trajectory conflicts with inherited decisions or constraints
+- what assumptions have quietly changed
+
+Recommendation:
+- the best next move
+- why it is the best move
+- if recommending a pivot, which inherited decision is being revised and why
+
+Risks:
+- what could still go wrong
+- what assumptions remain uncertain
+
+Need from main agent:
+- specific question or decision required before continuing, if any
+
+Suggested execution prompt:
+- a concrete prompt for `worker`, only if an implementation handoff is actually warranted
+- if no handoff is warranted, say so explicitly