pi-squad 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.1] - 2026-07-18
+
+### Fixed
+
+- `squad-plan` validator now works from an installed package: Node refuses TypeScript type stripping under `node_modules`, so `validate-spec.mjs` stages the real validator sources in a temp directory before importing them. Validation output is byte-identical.
+
+## [0.19.0] - 2026-07-18
+
+### Added
+
+- `squad-plan` skill: authoring guide for inline plans and strict v1 file specifications, an error→fix map, and a bundled `validate-spec.mjs` that runs the exact tool validator and prints the ready-to-use `specSha256`.
+
+### Fixed
+
+- The `squad` tool now accepts JSON-encoded strings for `tasks`, `agents`, and `config` and decodes them with precise per-field errors, so transports that stringify structured arguments no longer fail valid plans (`tasks: must be array`). Verified live: a real Opus 4.8 session emitted stringified tasks unprompted and the squad started correctly.
+
+### Changed
+
+- Agent `model`/`thinking` now follow configuration unless the user explicitly requests otherwise: the planner prompt, squad tool schema/guidelines, and skills all instruct omitting overrides so agent definitions and `/squad defaults` apply.
+
 ## [0.18.0] - 2026-07-18
 
 ### Added
@@ -64,7 +84,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Kept failed-review rework in the original squad, preserving task ownership and durable session continuity.
 
-[Unreleased]: https://github.com/picassio/pi-squad/compare/v0.18.0...HEAD
+[Unreleased]: https://github.com/picassio/pi-squad/compare/v0.19.1...HEAD
+[0.19.1]: https://github.com/picassio/pi-squad/compare/v0.19.0...v0.19.1
+[0.19.0]: https://github.com/picassio/pi-squad/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/picassio/pi-squad/compare/v0.17.2...v0.18.0
 [0.17.2]: https://github.com/picassio/pi-squad/compare/v0.17.1...v0.17.2
 [0.17.1]: https://github.com/picassio/pi-squad/compare/v0.17.0...v0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {
@@ -11,6 +11,7 @@
       "src/index.ts"
     ],
     "skills": [
+      "src/skills/squad-plan",
       "src/skills/squad-supervisor",
       "src/skills/squad-backend-dev",
       "src/skills/squad-code-review",

package/src/inline-input.ts

@@ -0,0 +1,139 @@
+/**
+ * inline-input.ts — tolerant decoding for inline squad-start arguments.
+ *
+ * Some tool transports (MCP bridges, JSON-over-JSON encoders) deliver the
+ * structured `tasks`/`agents`/`config` fields as JSON-encoded strings instead
+ * of arrays/objects. The squad tool accepts both and coerces strings back to
+ * structures with precise errors, so a correct plan never fails on transport
+ * shape alone. Semantic plan validation (ids, dependencies, cycles, agents)
+ * still happens in plan-rules/startSquad after coercion.
+ */
+import type { InlineSquadStart } from "./runtime.js";
+
+export type InlineCoercion =
+	| { ok: true; value: InlineSquadStart }
+	| { ok: false; error: string };
+
+type InlineTask = NonNullable<InlineSquadStart["tasks"]>[number];
+type InlineAgents = NonNullable<InlineSquadStart["agents"]>;
+type InlineConfig = NonNullable<InlineSquadStart["config"]>;
+
+function parseIfString(value: unknown, field: string): { ok: true; value: unknown } | { ok: false; error: string } {
+	if (typeof value !== "string") return { ok: true, value };
+	try {
+		return { ok: true, value: JSON.parse(value) };
+	} catch (error) {
+		return { ok: false, error: `${field} arrived as a JSON string that is not valid JSON (${(error as Error).message}). Send a real ${field === "tasks" ? "array" : "object"}, or a JSON-encoded one.` };
+	}
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function coerceTasks(input: unknown): { ok: true; value: InlineTask[] | undefined } | { ok: false; error: string } {
+	if (input === undefined) return { ok: true, value: undefined };
+	if (!Array.isArray(input)) return { ok: false, error: "tasks must be an array of task objects (or a JSON-encoded array)." };
+	const tasks: InlineTask[] = [];
+	for (let i = 0; i < input.length; i++) {
+		const raw = input[i];
+		if (!isPlainObject(raw)) return { ok: false, error: `tasks[${i}] must be an object.` };
+		for (const key of ["id", "title", "agent"] as const) {
+			if (typeof raw[key] !== "string" || raw[key].length === 0) {
+				return { ok: false, error: `tasks[${i}].${key} must be a nonempty string.` };
+			}
+		}
+		if (raw.description !== undefined && typeof raw.description !== "string") {
+			return { ok: false, error: `tasks[${i}].description must be a string when present.` };
+		}
+		if (raw.depends !== undefined && (!Array.isArray(raw.depends) || !raw.depends.every((d) => typeof d === "string"))) {
+			return { ok: false, error: `tasks[${i}].depends must be an array of task-id strings when present.` };
+		}
+		if (raw.inheritContext !== undefined && typeof raw.inheritContext !== "boolean") {
+			return { ok: false, error: `tasks[${i}].inheritContext must be a boolean when present.` };
+		}
+		tasks.push({
+			id: raw.id as string,
+			title: raw.title as string,
+			agent: raw.agent as string,
+			...(raw.description !== undefined ? { description: raw.description as string } : {}),
+			...(raw.depends !== undefined ? { depends: raw.depends as string[] } : {}),
+			...(raw.inheritContext !== undefined ? { inheritContext: raw.inheritContext as boolean } : {}),
+		});
+	}
+	return { ok: true, value: tasks };
+}
+
+function coerceAgents(input: unknown): { ok: true; value: InlineAgents | undefined } | { ok: false; error: string } {
+	if (input === undefined) return { ok: true, value: undefined };
+	if (!isPlainObject(input)) return { ok: false, error: "agents must be an object mapping agent names to overrides (or a JSON-encoded object)." };
+	const agents: InlineAgents = {};
+	for (const [name, raw] of Object.entries(input)) {
+		if (!isPlainObject(raw)) return { ok: false, error: `agents.${name} must be an object.` };
+		if (raw.model !== undefined && typeof raw.model !== "string") return { ok: false, error: `agents.${name}.model must be a string when present.` };
+		if (raw.thinking !== undefined && typeof raw.thinking !== "string") return { ok: false, error: `agents.${name}.thinking must be a string when present.` };
+		agents[name] = {
+			...(raw.model !== undefined ? { model: raw.model as string } : {}),
+			...(raw.thinking !== undefined ? { thinking: raw.thinking as string } : {}),
+		};
+	}
+	return { ok: true, value: agents };
+}
+
+function coerceConfig(input: unknown): { ok: true; value: InlineConfig | undefined } | { ok: false; error: string } {
+	if (input === undefined) return { ok: true, value: undefined };
+	if (!isPlainObject(input)) return { ok: false, error: "config must be an object (or a JSON-encoded object)." };
+	if (input.maxConcurrency !== undefined && typeof input.maxConcurrency !== "number") {
+		return { ok: false, error: "config.maxConcurrency must be a number when present." };
+	}
+	if (input.autoUnblock !== undefined && typeof input.autoUnblock !== "boolean") {
+		return { ok: false, error: "config.autoUnblock must be a boolean when present." };
+	}
+	if (input.maxRetries !== undefined && typeof input.maxRetries !== "number") {
+		return { ok: false, error: "config.maxRetries must be a number when present." };
+	}
+	return {
+		ok: true,
+		value: {
+			...(input.maxConcurrency !== undefined ? { maxConcurrency: input.maxConcurrency as number } : {}),
+			...(input.autoUnblock !== undefined ? { autoUnblock: input.autoUnblock as boolean } : {}),
+			...(input.maxRetries !== undefined ? { maxRetries: input.maxRetries as number } : {}),
+		},
+	};
+}
+
+/** Decode inline squad-start input, accepting JSON-encoded structured fields. */
+export function coerceInlineSquadStart(raw: {
+	goal: string;
+	agents?: unknown;
+	tasks?: unknown;
+	config?: unknown;
+}): InlineCoercion {
+	if (typeof raw.goal !== "string" || raw.goal.trim().length === 0) {
+		return { ok: false, error: "goal must be a nonempty string." };
+	}
+
+	const tasksParsed = parseIfString(raw.tasks, "tasks");
+	if (!tasksParsed.ok) return tasksParsed;
+	const agentsParsed = parseIfString(raw.agents, "agents");
+	if (!agentsParsed.ok) return agentsParsed;
+	const configParsed = parseIfString(raw.config, "config");
+	if (!configParsed.ok) return configParsed;
+
+	const tasks = coerceTasks(tasksParsed.value);
+	if (!tasks.ok) return tasks;
+	const agents = coerceAgents(agentsParsed.value);
+	if (!agents.ok) return agents;
+	const config = coerceConfig(configParsed.value);
+	if (!config.ok) return config;
+
+	return {
+		ok: true,
+		value: {
+			goal: raw.goal,
+			...(agents.value !== undefined ? { agents: agents.value } : {}),
+			...(tasks.value !== undefined ? { tasks: tasks.value } : {}),
+			...(config.value !== undefined ? { config: config.value } : {}),
+		},
+	};
+}

package/src/planner.ts

@@ -251,8 +251,7 @@ Respond with a JSON object (and nothing else outside the JSON):
 \`\`\`json
 {
   "agents": {
-    "agent-name": {},
-    "agent-name": { "model": "override-model-if-needed", "thinking": "high" }
+    "agent-name": {}
   },
   "tasks": [
     {
@@ -269,7 +268,7 @@ Respond with a JSON object (and nothing else outside the JSON):
 ## Rules
 ${PLAN_STRUCTURE_RULES}
 - Only reference agents that exist in the Available Agents list
-- Agent overrides are optional: "model" (a pi model id) and "thinking" (one of: off, minimal, low, medium, high, xhigh, max). Omit both to use defaults. Raise "thinking" only for tasks needing deep reasoning (architecture, security)
+- Agent entries stay empty ({}) so each agent uses its configured model/thinking (agent definition, then squad defaults). Set "model" (a pi model id) or "thinking" (off, minimal, low, medium, high, xhigh, max) ONLY when the goal explicitly requests a specific model or thinking level
 
 ## Task Descriptions
 ${TASK_DESCRIPTION_GUIDE}

package/src/skills/squad-plan/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: squad-plan
+description: Author valid pi-squad plans — inline task arrays and strict v1 file specifications. Use when creating a squad plan, writing a squad spec JSON, choosing between inline tasks and specFile, computing specSha256, or debugging squad validation errors (must be array, SPEC_MALFORMED, SPEC_HASH_MISMATCH, Plan rejected).
+---
+
+# Squad Plan Authoring
+
+Two ways to start a squad. Pick one:
+
+| Form | When |
+|---|---|
+| **Inline** `squad({ goal, tasks?, agents?, config? })` | Normal plans. Goal + tasks fit comfortably in a tool call. |
+| **File spec** `squad({ specFile, specSha256 })` | Large contracts, many tasks, exact-bytes requirements, or when your transport keeps mangling inline arguments. Children mechanically attest full spec reading. |
+
+## Planner rules (both forms)
+
+- 3–7 tasks is usually right (hard limit 128 in file specs; >9 warns).
+- First task(s) have empty `depends`. No cycles; every dependency must name an existing task id.
+- When tasks share an interface (API, schema, format), add a design/contract task first and make consumers depend on it.
+- Add a final QA/verification task for user-facing changes.
+- Task ids: short kebab-case (`setup-db`, `auth-middleware`). File specs enforce `^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$`.
+- Structure descriptions as: Goal (outcome first), Context (files to read), Output (deliverable), Boundaries (what must not change), Verify (proving command).
+- Every task's `agent` must name an existing agent definition (defaults: architect, backend, debugger, devops, docs, frontend, fullstack, qa, researcher, reviewer, security).
+- **Model/thinking come from configuration.** Omit inline `agents` overrides and keep file-spec entries at `{ "model": null, "thinking": null }` unless the user explicitly asked for a specific model or thinking level. Configured values resolve as: squad-plan override (only if set) → agent definition (`~/.pi/squad/agents/*.json` or project `.pi/squad/agents/`) → `/squad defaults` policy in `~/.pi/squad/settings.json`.
+
+## Inline form
+
+```json
+{
+  "goal": "Complete user outcome/acceptance contract, preserved for review",
+  "tasks": [
+    { "id": "api-contract", "title": "Define API contract", "agent": "architect", "depends": [] },
+    { "id": "build-api", "title": "Implement API", "agent": "backend", "depends": ["api-contract"],
+      "description": "Goal: ... Context: ... Output: ... Boundaries: ... Verify: ..." },
+    { "id": "qa", "title": "Verify end to end", "agent": "qa", "depends": ["build-api"] }
+  ],
+  "config": { "maxConcurrency": 2 }
+}
+```
+
+- `tasks`, `agents`, and `config` must be real JSON structures. If your transport stringifies them, pi-squad also accepts JSON-encoded strings for these three fields and decodes them — but prefer real structures.
+- Omitting `tasks` runs the planner agent on `goal`.
+- `Plan rejected:` errors list exact structural problems (duplicate ids, unknown dependency, cycle, no entry task). Fix and resubmit; warnings (`⚠️`) don't block.
+
+## File-spec form (strict v1)
+
+Validation is strict and fail-closed: unknown keys, missing keys, duplicate JSON keys, a UTF-8 BOM, invalid UTF-8, or a wrong hash all reject before anything is scheduled. **Every field below is required — including empty ones.**
+
+```json
+{
+  "schemaVersion": 1,
+  "goal": "Complete acceptance contract...",
+  "tasks": [
+    {
+      "id": "api-contract",
+      "title": "Define API contract",
+      "description": "Goal: ... Verify: ...",
+      "agent": "architect",
+      "depends": [],
+      "inheritContext": false,
+      "artifactRefs": []
+    }
+  ],
+  "agents": {
+    "architect": { "model": null, "thinking": null }
+  },
+  "config": { "maxConcurrency": 2, "autoUnblock": true, "maxRetries": 2 },
+  "artifacts": []
+}
+```
+
+Rules that trip people up:
+
+- Every agent used by a task must appear in `agents`, each entry exactly `{ "model": string|null, "thinking": null|"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max" }`. Use `null`/`null` (configured defaults) unless the user explicitly requested a specific model or thinking level.
+- `config` needs all three keys: `maxConcurrency` (1–64), `autoUnblock` (boolean), `maxRetries` (0–20).
+- Each task needs all seven keys, even when `description` is `""` and `artifactRefs` is `[]`.
+- No Base64 blobs or oversized embedded content (spec ≤ 1 MiB; embedded text budgets enforced). Reference big content via `artifacts`: absolute `path`, exact lowercase `sha256`, exact `bytes`, nonempty `purpose`.
+- `specSha256` is the SHA-256 of the exact file bytes, 64 lowercase hex chars. Write the file first, hash second, never edit afterward.
+
+## Workflow: write → validate → call
+
+1. Write the spec to a file (UTF-8, no BOM). Generate it with a script (`JSON.stringify`) rather than by hand to avoid duplicate keys and escaping mistakes.
+2. Validate with the bundled validator — it runs the exact same code the squad tool runs and prints the ready-to-use hash:
+
+```bash
+node <skill-dir>/validate-spec.mjs /path/to/spec.v1.json
+```
+
+On success it prints `VALID`, the `specSha256`, and the exact `squad(...)` call. On failure it prints the same `SPEC_MALFORMED`/`SPEC_TOO_LARGE`/`ARTIFACT_*` error the tool would return — fix and re-run.
+
+3. Call `squad({ specFile, specSha256 })` with the printed values. Do not restate the contract inline.
+
+## Error → fix map
+
+| Error | Fix |
+|---|---|
+| `tasks: must be array` (tool validation) | Transport stringified your array — send a real array, or pass the JSON string (accepted), or use a file spec. |
+| `SPEC_HASH_MISMATCH` | File changed after hashing, or hash uppercase/wrong. Re-run the validator; use its printed hash. |
+| `SPEC_MALFORMED: unknown/requires ...` | Add every required key exactly; remove extras. See the full example above. |
+| `SPEC_MALFORMED: duplicate task id / invalid dependency / cycle` | Fix the task graph; dependencies reference ids in this spec only. |
+| `SPEC_MALFORMED: task X uses undeclared agent Y` | Add Y to `agents` with `{ "model": null, "thinking": null }`. |
+| `SPEC_TOO_LARGE` | Move large content to `artifacts` (path + sha256 + bytes) and reference via `artifactRefs`. |
+| `Plan rejected:` (inline) | Structural plan errors listed verbatim — apply each fix. |

package/src/skills/squad-plan/validate-spec.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * validate-spec.mjs — validate a pi-squad strict v1 file spec and print the
+ * exact specSha256 to pass to the squad tool.
+ *
+ * Usage: node validate-spec.mjs <spec.v1.json>
+ *
+ * This runs the SAME validator the squad tool uses (src/file-spec.ts), so a
+ * VALID result here is exactly what squad({ specFile, specSha256 }) accepts.
+ */
+import { registerHooks } from "node:module";
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+if (!process.features.typescript) {
+	console.error(
+		"This validator needs Node.js with type stripping: Node >= 23.6, or Node >= 22.6 run as\n" +
+		"  node --experimental-strip-types validate-spec.mjs <spec.v1.json>",
+	);
+	process.exit(2);
+}
+
+// The extension sources use ".js" specifiers resolved by Pi; map them to the
+// on-disk ".ts" files when loading the real validator outside Pi.
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		if (specifier.startsWith(".") && specifier.endsWith(".js")) {
+			try {
+				return nextResolve(specifier, context);
+			} catch {
+				return nextResolve(specifier.replace(/\.js$/, ".ts"), context);
+			}
+		}
+		return nextResolve(specifier, context);
+	},
+});
+
+const specArg = process.argv[2];
+if (!specArg) {
+	console.error("Usage: node validate-spec.mjs <spec.v1.json>");
+	process.exit(2);
+}
+const specPath = resolve(process.cwd(), specArg);
+
+// Node refuses type stripping for files under node_modules, which is exactly
+// where an installed pi-squad lives. Import the real validator from a temp
+// copy outside node_modules; its only runtime deps are node builtins.
+const sourceDir = fileURLToPath(new URL("../..", import.meta.url));
+const stageDir = mkdtempSync(join(tmpdir(), "pi-squad-validate-"));
+for (const file of ["file-spec.ts", "types.ts"]) {
+	copyFileSync(join(sourceDir, file), join(stageDir, file));
+}
+let prepareSpec;
+try {
+	({ prepareSpec } = await import(pathToFileURL(join(stageDir, "file-spec.ts")).href));
+} finally {
+	rmSync(stageDir, { recursive: true, force: true });
+}
+
+try {
+	const raw = readFileSync(specPath);
+	const sha256 = createHash("sha256").update(raw).digest("hex");
+	// Validation with the self-computed hash: the hash gate passes trivially and
+	// every structural/strictness rule still runs.
+	const prepared = prepareSpec(specPath, sha256, process.cwd());
+	console.log("VALID");
+	console.log(`specFile:   ${specPath}`);
+	console.log(`specSha256: ${prepared.sha256}`);
+	console.log(`bytes:      ${prepared.raw.length}`);
+	console.log(`tasks:      ${prepared.spec.tasks.length}`);
+	console.log(`agents:     ${Object.keys(prepared.spec.agents).join(", ")}`);
+	console.log("");
+	console.log(`squad({ specFile: ${JSON.stringify(specPath)}, specSha256: ${JSON.stringify(prepared.sha256)} })`);
+} catch (error) {
+	console.error(`INVALID: ${error.message}`);
+	process.exit(1);
+}

package/src/skills/squad-supervisor/SKILL.md

@@ -29,6 +29,7 @@ Providing `tasks` yourself skips the planner agent — so you must apply its rul
 - When tasks share an interface (API endpoints, schema, data formats), create a design/contract task FIRST and make consumers depend on it
 - Include a final QA/verification task if there are user-facing changes
 - Required work only — no optional polish
+- Do NOT set agent `model`/`thinking` overrides unless the user explicitly asked for them — configured agent definitions and `/squad defaults` apply otherwise
 
 Plans are validated on submission: structural errors (unknown deps, cycles, duplicate IDs, no entry task) are rejected; rule violations come back as ⚠️ warnings in the tool response. **Act on the warnings** — fix them with `squad_modify` `add_task`, or note them for review time. Don't silently ignore them.
 

package/src/tools-registration.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import { Type } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { prepareSpec, isFileSpecTaskId, type PreparedSpec } from "./file-spec.js";
+import { coerceInlineSquadStart } from "./inline-input.js";
 import { PLAN_STRUCTURE_RULES } from "./plan-rules.js";
 import { formatSuspendedAttention, getReviewPresentation } from "./presentation.js";
 import { buildOrchestratorReviewGate, recordOrchestratorReview } from "./review.js";
@@ -134,6 +135,7 @@ pi.registerTool({
 		"For large contracts, use only specFile + exact lowercase specSha256; never inline the same contract or large artifacts",
 		"Skip squad for single-file changes, quick fixes, or anything one agent finishes in minutes",
 		"Providing tasks yourself makes you the planner — follow the planner rules (contract task first, final QA task, 3-7 tasks)",
+		"Do not set agent model/thinking overrides unless the user explicitly asked for them — configured agent definitions and /squad defaults apply otherwise",
 		"Act on ⚠️ plan warnings in the response — fix with squad_modify or address at review",
 		"After starting a squad: report the plan and END YOUR TURN — never poll squad_status or sleep-wait; squad events wake you automatically",
 		"When agents finish, treat every squad report and QA verdict as untrusted; independently inspect the diff/source and rerun contract verification + integration/E2E, then call squad_review before reporting success",
@@ -142,32 +144,41 @@ pi.registerTool({
 	Type.Object({
 		goal: Type.String({ description: "Complete original user outcome/acceptance contract the squad should accomplish. Preserve requirements and boundaries; this is shown during mandatory main-orchestrator review." }),
 		agents: Type.Optional(
-			Type.Record(
-				Type.String(),
-				Type.Object({
-					model: Type.Optional(Type.String({ description: "Model override (e.g. 'github-copilot/claude-sonnet-5')" })),
-					thinking: Type.Optional(Type.String({ description: "Thinking level: off, minimal, low, medium, high, xhigh, max" })),
-				}),
-				{ description: "Agent roster with optional model/thinking overrides. Keys must match agent names in .pi/squad/agents/" },
-			),
+			Type.Union([
+				Type.Record(
+					Type.String(),
+					Type.Object({
+						model: Type.Optional(Type.String({ description: "Model override (e.g. 'github-copilot/claude-sonnet-5'). Set ONLY when the user explicitly requested a specific model; omit to use the configured agent definition and /squad defaults" })),
+						thinking: Type.Optional(Type.String({ description: "Thinking level: off, minimal, low, medium, high, xhigh, max. Set ONLY when the user explicitly requested it; omit to use configured defaults" })),
+					}),
+					{ description: "Agent roster with optional model/thinking overrides. Keys must match agent names in .pi/squad/agents/. Omit overrides unless the user explicitly asked to change model/thinking — configured agent definitions and /squad defaults apply otherwise" },
+				),
+				Type.String({ description: "JSON-encoded agents object (same shape); accepted for transports that stringify structured arguments" }),
+			]),
 		),
 		tasks: Type.Optional(
-			Type.Array(
-				Type.Object({
-					id: Type.String(),
-					title: Type.String(),
-					description: Type.Optional(Type.String({ description: "Structure as: Goal (outcome first, not steps), Context (files/contracts to read), Output (deliverable), Boundaries (what must NOT change), Verify (command that proves it works). Include only the parts that help." })),
-					agent: Type.String(),
-					depends: Type.Optional(Type.Array(Type.String())),
-					inheritContext: Type.Optional(Type.Boolean({ description: "Fork the current pi session so the agent inherits this conversation's full context. Use ONLY when the task depends on decisions/details discussed here that can't be restated briefly. Costly (agent pays the whole history as input each turn) and auto-skipped when the session exceeds 50% of the agent model's context window — prefer restating key context in the description." })),
-				}),
-				{ description: "Pre-defined task breakdown. If provided, skips the planner agent. Scope tasks to required work only — no optional polish." },
-			),
+			Type.Union([
+				Type.Array(
+					Type.Object({
+						id: Type.String(),
+						title: Type.String(),
+						description: Type.Optional(Type.String({ description: "Structure as: Goal (outcome first, not steps), Context (files/contracts to read), Output (deliverable), Boundaries (what must NOT change), Verify (command that proves it works). Include only the parts that help." })),
+						agent: Type.String(),
+						depends: Type.Optional(Type.Array(Type.String())),
+						inheritContext: Type.Optional(Type.Boolean({ description: "Fork the current pi session so the agent inherits this conversation's full context. Use ONLY when the task depends on decisions/details discussed here that can't be restated briefly. Costly (agent pays the whole history as input each turn) and auto-skipped when the session exceeds 50% of the agent model's context window — prefer restating key context in the description." })),
+					}),
+					{ description: "Pre-defined task breakdown. If provided, skips the planner agent. Scope tasks to required work only — no optional polish." },
+				),
+				Type.String({ description: "JSON-encoded tasks array (same item shape); accepted for transports that stringify structured arguments" }),
+			]),
 		),
 		config: Type.Optional(
-			Type.Object({
-				maxConcurrency: Type.Optional(Type.Number({ description: "Max parallel agents (default: 2)" })),
-			}),
+			Type.Union([
+				Type.Object({
+					maxConcurrency: Type.Optional(Type.Number({ description: "Max parallel agents (default: 2)" })),
+				}),
+				Type.String({ description: "JSON-encoded config object (same shape); accepted for transports that stringify structured arguments" }),
+			]),
 		),
 	}, { additionalProperties: false }),
 	Type.Object({
@@ -195,7 +206,13 @@ pi.registerTool({
 			prepared = prepareSpec(params.specFile, params.specSha256, ctx.cwd);
 			effective = { goal: prepared.spec.goal, agents: prepared.spec.agents, tasks: prepared.spec.tasks, config: prepared.spec.config };
 		} else {
-			effective = params;
+			// Some transports stringify structured arguments; decode tolerantly with
+			// precise errors instead of failing a correct plan on transport shape.
+			const coerced = coerceInlineSquadStart(params);
+			if (!coerced.ok) {
+				return { content: [{ type: "text" as const, text: `Invalid squad input: ${coerced.error} No squad was started.` }], details: undefined };
+			}
+			effective = coerced.value;
 		}
 		const baseId = store.makeTaskId(effective.goal) || `squad-${prepared?.sha256.slice(0, 12)}`;
 		const squadId = store.squadExists(baseId) ? `${baseId}-${Date.now().toString(36)}` : baseId;