@alisio/plugin-subagents 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Gutiérrez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @alisio/plugin-subagents
+
+Subagents for [Alisio](https://github.com/GustavoGutierrez/alisio), shipped as a built-in plugin of the
+`alisio` CLI (disable with `--disable-plugin subagents`). The parent agent delegates work with the
+`task` tool to specialized agents that run in separate child sessions: fresh context, narrowed
+permissions, their own model and limits. It depends only on `@alisio/sdk` (generic
+`api.sessions`, `api.ui.panel`, `api.ui.select`) plus `zod` and `yaml`.
+
+- Agent definitions: Markdown + YAML frontmatter (`name`, `description`, `tools`, `model`,
+  `permission`, `maxTurns`, …) from `--agents`, `.alisio/agents`, `.agents/agents`, `.claude/agents`,
+  `.opencode/agent(s)`, user directories and plugins; built-ins `general`, `explore`, `plan`.
+- Tools: `task`, `task_status`, `task_wait`, `send_message`; parallel and background tasks, bounded
+  waits, `<task …>` results, `<task-notification>` on background completion.
+- Limits: depth, concurrency per parent and total, bounded queue, turns, timeout and token budget.
+- Parallel writes in git: worktree per subagent (merge/discard with `/agents`), serial or shared.
+- A live agent tree in the TUI with keyboard navigation and read-only child views.
+
+Docs: [Subagents](https://gustavogutierrez.github.io/alisio/subagents).
+
+Maintainer: Gustavo Gutiérrez · License: MIT

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/** Options under `builtinPlugins.subagents`. */
+export declare const subagentsConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    maxConcurrentPerParent: z.ZodDefault<z.ZodNumber>;
+    maxConcurrentTotal: z.ZodDefault<z.ZodNumber>;
+    maxQueued: z.ZodDefault<z.ZodNumber>;
+    maxTurns: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxTokensPerChild: z.ZodOptional<z.ZodNumber>;
+    parallelWrites: z.ZodDefault<z.ZodEnum<{
+        ask: "ask";
+        serial: "serial";
+        shared: "shared";
+        worktree: "worktree";
+    }>>;
+    waitMaxMs: z.ZodDefault<z.ZodNumber>;
+    resultMaxBytes: z.ZodDefault<z.ZodNumber>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        prompt: z.ZodDefault<z.ZodString>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    worktreeDir: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SubagentsConfig = z.infer<typeof subagentsConfigSchema>;

package/dist/config.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+const cliAgent = z.object({
+    description: z.string().min(1),
+    prompt: z.string().default(""),
+    tools: z.array(z.string()).optional(),
+    model: z.string().optional(),
+});
+/** Options under `builtinPlugins.subagents`. */
+export const subagentsConfigSchema = z
+    .object({
+    enabled: z.boolean().default(true),
+    maxDepth: z.number().int().min(1).max(8).default(3),
+    maxConcurrentPerParent: z.number().int().min(1).max(32).default(4),
+    maxConcurrentTotal: z.number().int().min(1).max(64).default(8),
+    /** Waiting tasks beyond the concurrency limits; more fail fast. */
+    maxQueued: z.number().int().min(0).max(256).default(16),
+    maxTurns: z.number().int().min(1).max(500).default(50),
+    timeoutMs: z.number().int().min(1_000).default(600_000),
+    /** Per-child cumulative token budget; default follows the core proportional budget. */
+    maxTokensPerChild: z.number().int().positive().optional(),
+    /** Parallel write-capable children in a git repository. */
+    parallelWrites: z.enum(["ask", "worktree", "serial", "shared"]).default("ask"),
+    waitMaxMs: z.number().int().min(100).default(600_000),
+    resultMaxBytes: z.number().int().min(1_000).max(1_000_000).default(50_000),
+    /** Agents from `--agents <json>` (highest precedence). */
+    agents: z.record(z.string(), cliAgent).default({}),
+    /** Where worktrees are created (default `<state>/worktrees`). */
+    worktreeDir: z.string().optional(),
+})
+    .strict();

package/dist/definitions.d.ts

@@ -0,0 +1,60 @@
+export type Level = "allow" | "ask" | "deny";
+export interface AgentDefinition {
+    name: string;
+    description: string;
+    /** System prompt (the Markdown body). */
+    prompt: string;
+    /** Allowlist; `*` means every tool the parent has (including `task`). */
+    tools?: string[];
+    disallowedTools?: string[];
+    /** Model selector (`provider/model` or a unique model id); undefined inherits the parent. */
+    model?: string;
+    mode: "subagent" | "primary" | "all";
+    maxTurns?: number;
+    color?: string;
+    permission?: {
+        write?: Level;
+        process?: Level;
+    };
+    readOnly?: boolean;
+    hidden: boolean;
+    background: boolean;
+    skills?: string[];
+    /** builtin | cli | project | convention | compat | user | plugin:<id> */
+    source: string;
+    path?: string;
+}
+export declare function parseAgentDefinition(text: string, meta: {
+    source: string;
+    path?: string;
+}): {
+    definition?: AgentDefinition;
+    warnings: string[];
+};
+export declare const BUILTIN_AGENTS: AgentDefinition[];
+export interface CliAgent {
+    description: string;
+    prompt: string;
+    tools?: string[];
+    model?: string;
+}
+/**
+ * Discovery, first match wins by name: CLI `--agents` > project `.alisio/agents` >
+ * `.agents/agents` (speculative convention) > compat `.claude/agents`, `.opencode/agent(s)`
+ * > user `<config>/agents`, `~/.claude/agents`, `~/.config/opencode/agent(s)` > plugin
+ * directories (namespaced `plugin:name`) > built-ins. Project sources require trust.
+ */
+export declare function discoverAgents(options: {
+    workspace: string;
+    home: string;
+    configHome: string;
+    trusted: boolean;
+    cli?: Record<string, CliAgent>;
+    plugins: Array<{
+        plugin: string;
+        dir: string;
+    }>;
+}): Promise<{
+    agents: Map<string, AgentDefinition>;
+    warnings: string[];
+}>;

package/dist/definitions.js

@@ -0,0 +1,269 @@
+/**
+ * Agent definitions: Markdown files with YAML frontmatter (Alisio format), plus compatible
+ * readers for Claude Code (`.claude/agents`) and opencode (`.opencode/agent(s)`) files.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parse } from "yaml";
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const KNOWN = new Set([
+    "name",
+    "description",
+    "tools",
+    "disallowedTools",
+    "model",
+    "mode",
+    "maxTurns",
+    "steps",
+    "maxSteps",
+    "color",
+    "permission",
+    "hidden",
+    "background",
+    "skills",
+    "readOnly",
+    // Compat keys accepted silently.
+    "temperature",
+    "top_p",
+    "disable",
+]);
+/** Claude Code tool names → Alisio tools. */
+const TOOL_ALIASES = {
+    read: ["read_file"],
+    grep: ["search_text"],
+    glob: ["list_files"],
+    ls: ["list_files"],
+    edit: ["edit_file"],
+    multiedit: ["edit_file"],
+    write: ["write_file"],
+    bash: ["shell", "run_process"],
+    task: ["task"],
+};
+const CLAUDE_MODEL_ALIASES = new Set(["sonnet", "opus", "haiku"]);
+const list = (value) => {
+    if (Array.isArray(value))
+        return value
+            .map(String)
+            .map((s) => s.trim())
+            .filter(Boolean);
+    if (typeof value === "string")
+        return value
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return undefined;
+};
+const mapTools = (names) => [
+    ...new Set(names.flatMap((n) => TOOL_ALIASES[n.toLowerCase()] ?? [n])),
+];
+const level = (value) => value === "allow" || value === "ask" || value === "deny"
+    ? value
+    : value && typeof value === "object"
+        ? "ask" // pattern maps (opencode) narrow to per-call approval
+        : undefined;
+export function parseAgentDefinition(text, meta) {
+    const warnings = [];
+    const where = meta.path ?? meta.source;
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(text);
+    if (!match)
+        return { warnings: [`${where}: missing YAML frontmatter`] };
+    let front;
+    try {
+        front = (parse(match[1] ?? "", { maxAliasCount: 20 }) ?? {});
+    }
+    catch (error) {
+        return { warnings: [`${where}: invalid YAML (${String(error)})`] };
+    }
+    const fileName = meta.path ? basename(meta.path, ".md") : undefined;
+    const name = String(front.name ?? fileName ?? "");
+    if (!NAME.test(name) || name.length > 64)
+        return {
+            warnings: [`${where}: invalid agent name "${name}" (lowercase letters, digits, hyphens)`],
+        };
+    const description = typeof front.description === "string" ? front.description.trim() : "";
+    if (!description)
+        return { warnings: [`${where}: description is required`] };
+    for (const key of Object.keys(front))
+        if (!KNOWN.has(key))
+            warnings.push(`${where}: unknown key "${key}" ignored`);
+    const definition = {
+        name,
+        description,
+        prompt: (match[2] ?? "").trim(),
+        mode: front.mode === "primary" || front.mode === "all" ? front.mode : "subagent",
+        hidden: front.hidden === true,
+        background: front.background === true,
+        source: meta.source,
+        ...(meta.path ? { path: meta.path } : {}),
+    };
+    const tools = front.tools;
+    if (tools && typeof tools === "object" && !Array.isArray(tools)) {
+        // opencode: { tool: false } disables a tool.
+        const off = Object.entries(tools)
+            .filter(([, v]) => v === false)
+            .map(([k]) => k);
+        if (off.length)
+            definition.disallowedTools = mapTools(off);
+    }
+    else {
+        const allow = list(tools);
+        if (allow)
+            definition.tools = mapTools(allow);
+    }
+    const deny = list(front.disallowedTools);
+    if (deny)
+        definition.disallowedTools = [
+            ...new Set([...(definition.disallowedTools ?? []), ...mapTools(deny)]),
+        ];
+    if (typeof front.model === "string" && front.model !== "inherit") {
+        if (CLAUDE_MODEL_ALIASES.has(front.model))
+            warnings.push(`${where}: model alias "${front.model}" is Claude-specific; inheriting the parent's model`);
+        else
+            definition.model = front.model;
+    }
+    const turns = front.maxTurns ?? front.steps ?? front.maxSteps;
+    if (typeof turns === "number" && Number.isInteger(turns) && turns > 0)
+        definition.maxTurns = turns;
+    if (typeof front.color === "string")
+        definition.color = front.color;
+    const permission = front.permission;
+    if (permission && typeof permission === "object") {
+        const write = level(permission.edit ?? permission.write);
+        const process = level(permission.bash ?? permission.process);
+        definition.permission = { ...(write ? { write } : {}), ...(process ? { process } : {}) };
+    }
+    if (front.readOnly === true)
+        definition.readOnly = true;
+    const skills = list(front.skills);
+    if (skills)
+        definition.skills = skills;
+    return { definition, warnings };
+}
+export const BUILTIN_AGENTS = [
+    {
+        name: "general",
+        description: "General-purpose agent for multi-step tasks: research, code changes and verification. Has every tool its parent has, including delegation.",
+        prompt: "You are a general-purpose subagent. Work autonomously on the delegated task, verify your results, and finish with a concise report of what you did, what you found and anything left undone.",
+        tools: ["*"],
+        mode: "subagent",
+        hidden: false,
+        background: false,
+        source: "builtin",
+    },
+    {
+        name: "explore",
+        description: "Fast read-only agent for exploring a codebase: find files, search code and summarize how things work. Cannot modify files or run processes.",
+        prompt: "You are a read-only exploration subagent. Use list_files, search_text, read_file and git tools efficiently to answer the delegated question. Cite file paths. Do not propose edits unless asked. Finish with a concise, factual summary.",
+        tools: [
+            "read_file",
+            "list_files",
+            "search_text",
+            "git_status",
+            "git_diff",
+            "context_explain",
+            "skill_load",
+            "skill_search",
+            "skill_resource",
+        ],
+        readOnly: true,
+        mode: "subagent",
+        hidden: false,
+        background: false,
+        color: "cyan",
+        source: "builtin",
+    },
+    {
+        name: "plan",
+        description: "Read-only planning agent: analyzes the code and returns a step-by-step implementation plan with the files to change. Never edits.",
+        prompt: "You are a read-only planning subagent. Investigate the relevant code, then return a concrete, ordered implementation plan listing files, functions and risks. Do not modify anything.",
+        tools: ["read_file", "list_files", "search_text", "git_status", "git_diff", "context_explain"],
+        readOnly: true,
+        mode: "subagent",
+        hidden: false,
+        background: false,
+        color: "yellow",
+        source: "builtin",
+    },
+];
+async function readDir(dir) {
+    let names;
+    try {
+        names = (await readdir(dir)).filter((n) => n.endsWith(".md")).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.slice(0, 200)) {
+        const path = join(dir, name);
+        try {
+            const text = await readFile(path, "utf8");
+            if (text.length <= 64_000)
+                out.push({ path, text });
+        }
+        catch {
+            /* unreadable entries are skipped */
+        }
+    }
+    return out;
+}
+/**
+ * Discovery, first match wins by name: CLI `--agents` > project `.alisio/agents` >
+ * `.agents/agents` (speculative convention) > compat `.claude/agents`, `.opencode/agent(s)`
+ * > user `<config>/agents`, `~/.claude/agents`, `~/.config/opencode/agent(s)` > plugin
+ * directories (namespaced `plugin:name`) > built-ins. Project sources require trust.
+ */
+export async function discoverAgents(options) {
+    const agents = new Map();
+    const warnings = [];
+    const add = (definition) => {
+        const existing = agents.get(definition.name);
+        if (existing)
+            warnings.push(`Agent ${definition.name} from ${definition.path ?? definition.source} is shadowed by ${existing.path ?? existing.source}`);
+        else
+            agents.set(definition.name, definition);
+    };
+    for (const [name, spec] of Object.entries(options.cli ?? {})) {
+        const { definition, warnings: w } = parseAgentDefinition(`---\n${JSON.stringify({ name, description: spec.description, ...(spec.tools ? { tools: spec.tools } : {}), ...(spec.model ? { model: spec.model } : {}) })}\n---\n${spec.prompt ?? ""}`, { source: "cli" });
+        warnings.push(...w);
+        if (definition)
+            add(definition);
+    }
+    const sources = [
+        { dir: join(options.workspace, ".alisio", "agents"), source: "project", project: true },
+        { dir: join(options.workspace, ".agents", "agents"), source: "convention", project: true },
+        { dir: join(options.workspace, ".claude", "agents"), source: "compat", project: true },
+        { dir: join(options.workspace, ".opencode", "agent"), source: "compat", project: true },
+        { dir: join(options.workspace, ".opencode", "agents"), source: "compat", project: true },
+        { dir: join(options.configHome, "agents"), source: "user", project: false },
+        { dir: join(options.home, ".claude", "agents"), source: "user", project: false },
+        { dir: join(options.home, ".config", "opencode", "agent"), source: "user", project: false },
+        { dir: join(options.home, ".config", "opencode", "agents"), source: "user", project: false },
+    ];
+    for (const { dir, source, project } of sources) {
+        if (project && !options.trusted)
+            continue;
+        for (const file of await readDir(dir)) {
+            const { definition, warnings: w } = parseAgentDefinition(file.text, {
+                source,
+                path: file.path,
+            });
+            warnings.push(...w);
+            if (definition)
+                add(definition);
+        }
+    }
+    for (const { plugin, dir } of options.plugins)
+        for (const file of await readDir(dir)) {
+            const { definition, warnings: w } = parseAgentDefinition(file.text, {
+                source: `plugin:${plugin}`,
+                path: file.path,
+            });
+            warnings.push(...w);
+            if (definition)
+                add({ ...definition, name: `${plugin}:${definition.name}` });
+        }
+    for (const builtin of BUILTIN_AGENTS)
+        add(builtin);
+    return { agents, warnings };
+}

package/dist/git.d.ts

@@ -0,0 +1,25 @@
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): Promise<GitResult>;
+export declare function repoRoot(dir: string): Promise<string | undefined>;
+export declare function isDirty(root: string): Promise<boolean>;
+export declare function head(root: string): Promise<string>;
+export declare function addWorktree(root: string, path: string, branch: string): Promise<string>;
+/** Commits everything in a worktree; returns false when there was nothing to commit. */
+export declare function commitAll(cwd: string, message: string): Promise<boolean>;
+export declare function diffSummary(root: string, base: string, branch: string): Promise<{
+    files: string[];
+    stat: string;
+}>;
+/** `git merge --no-ff`; on conflict the merge is aborted and conflicting files are reported. */
+export declare function merge(root: string, branch: string, message: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    conflicts: string[];
+    message: string;
+}>;
+export declare function removeWorktree(root: string, path: string, branch: string, deleteBranch: boolean): Promise<void>;

package/dist/git.js

@@ -0,0 +1,93 @@
+/** Minimal git plumbing for worktree isolation (argument arrays, never a shell). */
+import { execFile } from "node:child_process";
+export function git(cwd, args, env = {}) {
+    return new Promise((resolve) => {
+        execFile("git", args, {
+            cwd,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...env },
+            maxBuffer: 8 * 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            const code = error ? (typeof error.code === "number" ? error.code : 1) : 0;
+            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+}
+export async function repoRoot(dir) {
+    const r = await git(dir, ["rev-parse", "--show-toplevel"]);
+    return r.code === 0 ? r.stdout.trim() : undefined;
+}
+export async function isDirty(root) {
+    const r = await git(root, ["status", "--porcelain"]);
+    return r.code === 0 && r.stdout.trim().length > 0;
+}
+export async function head(root) {
+    const r = await git(root, ["rev-parse", "HEAD"]);
+    if (r.code)
+        throw new Error(`git rev-parse HEAD failed: ${r.stderr.trim()}`);
+    return r.stdout.trim();
+}
+export async function addWorktree(root, path, branch) {
+    const base = await head(root);
+    const r = await git(root, ["worktree", "add", "-b", branch, path, base]);
+    if (r.code)
+        throw new Error(`git worktree add failed: ${r.stderr.trim()}`);
+    return base;
+}
+/** Identity used only when the repository has none configured. */
+async function identity(cwd) {
+    const email = await git(cwd, ["config", "user.email"]);
+    return email.code === 0 && email.stdout.trim()
+        ? {}
+        : {
+            GIT_AUTHOR_NAME: "Alisio",
+            GIT_AUTHOR_EMAIL: "alisio@localhost",
+            GIT_COMMITTER_NAME: "Alisio",
+            GIT_COMMITTER_EMAIL: "alisio@localhost",
+        };
+}
+/** Commits everything in a worktree; returns false when there was nothing to commit. */
+export async function commitAll(cwd, message) {
+    await git(cwd, ["add", "-A"]);
+    const staged = await git(cwd, ["diff", "--cached", "--quiet"]);
+    if (staged.code === 0)
+        return false;
+    const r = await git(cwd, ["commit", "-q", "-m", message], await identity(cwd));
+    if (r.code)
+        throw new Error(`git commit failed: ${r.stderr.trim()}`);
+    return true;
+}
+export async function diffSummary(root, base, branch) {
+    const names = await git(root, ["diff", "--name-only", `${base}..${branch}`]);
+    const stat = await git(root, ["diff", "--stat", `${base}..${branch}`]);
+    return {
+        files: names.stdout.split("\n").filter(Boolean),
+        stat: stat.stdout.trim(),
+    };
+}
+/** `git merge --no-ff`; on conflict the merge is aborted and conflicting files are reported. */
+export async function merge(root, branch, message) {
+    if (await isDirty(root))
+        return {
+            ok: false,
+            conflicts: [],
+            message: "Working tree has uncommitted changes; commit or stash them first.",
+        };
+    const r = await git(root, ["merge", "--no-ff", "-m", message, branch], await identity(root));
+    if (r.code === 0)
+        return { ok: true };
+    const conflicts = (await git(root, ["diff", "--name-only", "--diff-filter=U"])).stdout
+        .split("\n")
+        .filter(Boolean);
+    await git(root, ["merge", "--abort"]);
+    return {
+        ok: false,
+        conflicts,
+        message: (r.stdout + r.stderr).trim().split("\n").slice(-3).join(" "),
+    };
+}
+export async function removeWorktree(root, path, branch, deleteBranch) {
+    await git(root, ["worktree", "remove", "--force", path]);
+    if (deleteBranch)
+        await git(root, ["branch", "-D", branch]);
+    await git(root, ["worktree", "prune"]);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type Plugin } from "@alisio/sdk";
+export type { AgentDefinition } from "./definitions.ts";
+export { BUILTIN_AGENTS, discoverAgents, parseAgentDefinition } from "./definitions.ts";
+export { SubagentManager } from "./manager.ts";
+export interface SubagentsPluginContext {
+    workspace: string;
+    stateHome: string;
+    configHome: string;
+    configDir: string;
+    home: string;
+    trusted: boolean;
+}
+export declare function createSubagentsPlugin(rawOptions: unknown, context: SubagentsPluginContext): Plugin;
+export declare const subagentsWorktreeDir: (stateHome: string) => string;