/**
 * Tool runtime contract for the pi harness.
 *
 * Tool names match the Claude Agent SDK's so the existing system prompt
 * (`worker/prompts/...`) — which advertises Read / Write / Edit / Bash —
 * keeps working without rewriting prompts per harness. Schemas are JSON
 * Schema in the shape Google's `functionDeclarations.parameters` accepts.
 */

export interface PiToolResult {
  /** Text shown back to the model as the tool's output. */
  output: string;
  /** Mark `true` when the tool failed; the loop tells the model so it can recover. */
  isError?: boolean;
}

/**
 * Host interface a live conversation exposes to the Task tool so it can spawn
 * background sub-agents (audit D4-1). Only PARENT sessions provide it — child
 * sessions get `ctx.tasks` undefined, so a sub-agent cannot spawn
 * grandchildren (Claude SDK parity).
 */
export interface PiTaskHost {
  /** Spawn a background sub-agent. Returns synchronously; the child runs detached. */
  spawn(req: { description: string; prompt: string; subagentType: string }):
    | { ok: true; taskId: string }
    | { ok: false; error: string };
}

export interface PiToolContext {
  /** Workspace root — every tool resolves paths against this. */
  cwd: string;
  /** Aborted when the session ends so long-running tools stop fast. */
  signal?: AbortSignal;
  /** Present only in live parent sessions — lets the Task tool spawn sub-agents. */
  tasks?: PiTaskHost;
}

export interface PiTool {
  name: string;
  description: string;
  inputSchema: Record<string, any>;
  run(input: any, ctx: PiToolContext): Promise<PiToolResult>;
}