@jzakirov/spawn-agent 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jamil Zakirov
+
+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,88 @@
+# spawn-agent
+
+Declarative subagent presets for [OpenClaw](https://openclaw.dev).
+
+This plugin loads preset definitions from Markdown files with YAML frontmatter and exposes:
+
+- `spawn_agent`: spawn a subagent using a preset + enforce tool policy
+- `agent_presets_list`: list discovered presets
+
+## Installation
+
+```bash
+openclaw plugins install @jzakirov/spawn-agent
+```
+
+Or from a local path (development):
+
+```bash
+openclaw plugins install ./openclaw-spawn-agent
+```
+
+## Preset discovery
+
+Presets are discovered from multiple tiers (higher priority overrides lower priority):
+
+1. `<workspace>/.openclaw/subagents/*.md`
+2. `<stateDir>/subagents/*.md`
+3. Plugin defaults: `subagents/*.md`
+
+## Preset format
+
+Each preset is a `.md` file with YAML frontmatter + a Markdown body used as the subagent system prompt.
+
+Example:
+
+```md
+---
+name: reviewer
+description: Read-only code reviewer focusing on bugs, security, and maintainability
+model: anthropic/claude-sonnet-4-20250514
+thinking: high
+timeoutSeconds: 120
+mode: run
+cleanup: delete
+sandbox: inherit
+tools:
+  allow: [read, diffs, grep, glob]
+  deny: [exec, write, edit, apply_patch]
+---
+
+You are a code reviewer. Be concise. Focus on bugs, security, and maintainability.
+```
+
+Supported frontmatter fields:
+
+| Field            | Type                    | Default    | Notes |
+|-----------------|-------------------------|------------|------|
+| `name`          | string                  | —          | Required. Unique key used by `spawn_agent`. |
+| `description`   | string                  | `""`       | Shown in tool descriptions/listing. |
+| `model`         | string                  | —          | Passed through to OpenClaw subagent spawn. |
+| `thinking`      | string                  | —          | Passed through to OpenClaw subagent spawn. |
+| `timeoutSeconds`| number                  | —          | Passed through as `runTimeoutSeconds`. |
+| `mode`          | `run` \| `session`      | `run`      | `session` keeps a persistent session. |
+| `cleanup`       | `delete` \| `keep`      | `delete`   | Cleanup behavior for `run` mode. |
+| `sandbox`       | `inherit` \| `require`  | `inherit`  | Whether to require sandboxing. |
+| `tools.allow`   | string[]                | —          | If set, only these tools are allowed. |
+| `tools.deny`    | string[]                | —          | Tools to deny (even if allowed). |
+
+## Tool: `spawn_agent`
+
+Parameters:
+
+- `agent` (string, required): preset name
+- `task` (string, required): instruction for the subagent
+- `label` (string, optional): human-readable label
+- `thread` (boolean, optional): bind to a thread
+- `mode` (`run` \| `session`, optional): override preset mode
+
+Response includes `childSessionKey`, `runId`, and where the preset was resolved from.
+
+## Tool: `agent_presets_list`
+
+Returns all discovered presets and their metadata, including `source`.
+
+## License
+
+MIT
+

package/index.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { registerRolePolicyHooks } from "./src/role-policy.js";
+import { createAgentPresetsListToolFactory } from "./src/roles-list-tool.js";
+import { createSpawnAgentToolFactory } from "./src/spawn-role-tool.js";
+
+export default function register(api: any) {
+  const pluginDir = path.dirname(new URL(import.meta.url).pathname);
+
+  const resolveStateDir = (): string | undefined => {
+    try {
+      return api.runtime?.state?.resolveStateDir?.();
+    } catch {
+      return undefined;
+    }
+  };
+
+  const factoryOpts = { pluginDir, resolveStateDir };
+
+  // Register spawn_agent as a tool factory (receives context per session)
+  api.registerTool(createSpawnAgentToolFactory(factoryOpts), { optional: true });
+
+  // Register agent_presets_list as a tool factory
+  api.registerTool(createAgentPresetsListToolFactory(factoryOpts), { optional: true });
+
+  // Register policy enforcement hooks
+  registerRolePolicyHooks(api);
+
+  api.logger.info("spawn-agent: registered tools and hooks");
+}

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "spawn-agent",
+  "name": "Spawn Agent",
+  "description": "Declarative subagent presets with tool enforcement, loaded from .md files with YAML frontmatter.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@jzakirov/spawn-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Declarative subagent presets with tool enforcement for OpenClaw",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jzakirov/openclaw-spawn-agent.git"
+  },
+  "keywords": ["openclaw", "openclaw-plugin", "subagent", "spawn-agent", "agent-presets"],
+  "files": ["index.ts", "src", "subagents", "openclaw.plugin.json", "README.md", "LICENSE"],
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2025.0.0"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  }
+}

package/src/role-loader.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+
+export type RoleToolPolicy = {
+  allow?: string[];
+  deny?: string[];
+};
+
+export type RoleConfig = {
+  name: string;
+  description: string;
+  model?: string;
+  thinking?: string;
+  timeoutSeconds?: number;
+  mode?: "run" | "session";
+  cleanup?: "delete" | "keep";
+  sandbox?: "inherit" | "require";
+  tools?: RoleToolPolicy;
+  systemPrompt: string;
+  /** Where this role was loaded from */
+  source: string;
+};
+
+function parseRoleFile(content: string, filePath: string): RoleConfig | null {
+  let parsed: matter.GrayMatterFile<string>;
+  try {
+    parsed = matter(content);
+  } catch {
+    return null;
+  }
+
+  const meta = parsed.data as Record<string, unknown>;
+  const body = parsed.content.trim();
+  const name = String(meta.name ?? "").trim();
+  if (!name) return null;
+
+  let tools: RoleToolPolicy | undefined;
+  if (meta.tools && typeof meta.tools === "object") {
+    tools = {};
+    const t = meta.tools as Record<string, unknown>;
+    if (Array.isArray(t.allow)) tools.allow = t.allow.map((s: unknown) => String(s).toLowerCase());
+    if (Array.isArray(t.deny)) tools.deny = t.deny.map((s: unknown) => String(s).toLowerCase());
+  }
+
+  return {
+    name,
+    description: String(meta.description ?? ""),
+    model: meta.model ? String(meta.model) : undefined,
+    thinking: meta.thinking ? String(meta.thinking) : undefined,
+    timeoutSeconds: typeof meta.timeoutSeconds === "number" ? meta.timeoutSeconds : undefined,
+    mode: meta.mode === "session" ? "session" : "run",
+    cleanup: meta.cleanup === "keep" ? "keep" : "delete",
+    sandbox: meta.sandbox === "require" ? "require" : "inherit",
+    tools,
+    systemPrompt: body,
+    source: filePath,
+  };
+}
+
+async function loadRolesFromDir(dir: string): Promise<Map<string, RoleConfig>> {
+  const roles = new Map<string, RoleConfig>();
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return roles;
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) continue;
+    const filePath = path.join(dir, entry);
+    try {
+      const content = await fs.readFile(filePath, "utf-8");
+      const role = parseRoleFile(content, filePath);
+      if (role && !roles.has(role.name)) {
+        roles.set(role.name, role);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+  return roles;
+}
+
+/** Cache key for loaded roles */
+type CacheKey = string;
+
+function makeCacheKey(workspaceDir?: string, stateDir?: string): CacheKey {
+  return `${workspaceDir ?? ""}:${stateDir ?? ""}`;
+}
+
+const rolesCache = new Map<CacheKey, { roles: Map<string, RoleConfig>; loadedAt: number }>();
+const CACHE_TTL_MS = 30_000;
+
+/**
+ * Load roles from all discovery tiers (higher priority first).
+ * 1. <workspace>/.openclaw/subagents/*.md
+ * 2. <stateDir>/subagents/*.md
+ * 3. Plugin bundled defaults
+ *
+ * Results are cached by (workspaceDir, stateDir) for 30s.
+ */
+export async function loadRoles(opts: {
+  workspaceDir?: string;
+  stateDir?: string;
+  pluginDir: string;
+}): Promise<Map<string, RoleConfig>> {
+  const key = makeCacheKey(opts.workspaceDir, opts.stateDir);
+  const cached = rolesCache.get(key);
+  if (cached && Date.now() - cached.loadedAt < CACHE_TTL_MS) {
+    return cached.roles;
+  }
+
+  const merged = new Map<string, RoleConfig>();
+
+  // Load in reverse priority so higher-priority sources overwrite
+  const tiers: string[] = [];
+
+  // Tier 3: Plugin bundled defaults (lowest priority)
+  tiers.push(path.join(opts.pluginDir, "subagents"));
+
+  // Tier 2: User state dir
+  if (opts.stateDir) {
+    tiers.push(path.join(opts.stateDir, "subagents"));
+  }
+
+  // Tier 1: Workspace (highest priority)
+  if (opts.workspaceDir) {
+    tiers.push(path.join(opts.workspaceDir, ".openclaw", "subagents"));
+  }
+
+  for (const dir of tiers) {
+    const roles = await loadRolesFromDir(dir);
+    for (const [name, config] of roles) {
+      merged.set(name, config);
+    }
+  }
+
+  rolesCache.set(key, { roles: merged, loadedAt: Date.now() });
+  return merged;
+}

package/src/role-policy.ts

@@ -0,0 +1,60 @@
+export type RolePolicy = {
+  roleName: string;
+  systemPrompt: string;
+  spawnMode: "run" | "session";
+  allow?: string[];
+  deny?: string[];
+};
+
+/** Runtime map: childSessionKey -> RolePolicy */
+export const rolePolicyMap = new Map<string, RolePolicy>();
+
+/**
+ * Register hooks on the plugin API for role enforcement.
+ */
+export function registerRolePolicyHooks(api: any): void {
+  // Inject role system prompt into child agent
+  api.on("before_prompt_build", (event: any, ctx: any) => {
+    const policy = rolePolicyMap.get(ctx.sessionKey);
+    if (!policy) return;
+    return { prependContext: policy.systemPrompt };
+  });
+
+  // Block tools not allowed by the role
+  api.on("before_tool_call", (event: any, ctx: any) => {
+    const policy = rolePolicyMap.get(ctx.sessionKey);
+    if (!policy) return;
+
+    const toolName = String(event.toolName).toLowerCase();
+
+    if (policy.allow && policy.allow.length > 0 && !policy.allow.includes(toolName)) {
+      return {
+        block: true,
+        blockReason: `Agent preset "${policy.roleName}" does not allow tool "${event.toolName}"`,
+      };
+    }
+
+    if (policy.deny && policy.deny.includes(toolName)) {
+      return {
+        block: true,
+        blockReason: `Agent preset "${policy.roleName}" denies tool "${event.toolName}"`,
+      };
+    }
+  });
+
+  // Clean up policy when subagent ends — only for mode=run.
+  // mode=session persists across runs, cleaned up on session_end instead.
+  api.on("subagent_ended", (event: any) => {
+    const key = event.targetSessionKey;
+    const policy = rolePolicyMap.get(key);
+    if (policy && policy.spawnMode === "run") {
+      rolePolicyMap.delete(key);
+    }
+  });
+
+  // Clean up persistent (mode=session) policies on session end
+  api.on("session_end", (event: any) => {
+    const key = event.sessionKey;
+    if (key) rolePolicyMap.delete(key);
+  });
+}

package/src/roles-list-tool.ts

@@ -0,0 +1,51 @@
+import { loadRoles } from "./role-loader.js";
+
+/**
+ * Build the agent_presets_list tool factory.
+ * Uses ctx.workspaceDir for correct per-session role discovery.
+ */
+export function createAgentPresetsListToolFactory(opts: {
+  pluginDir: string;
+  resolveStateDir: () => string | undefined;
+}) {
+  return async (ctx: any) => {
+    const roles = await loadRoles({
+      workspaceDir: ctx.workspaceDir,
+      stateDir: opts.resolveStateDir(),
+      pluginDir: opts.pluginDir,
+    });
+
+    return {
+      name: "agent_presets_list",
+      label: "List Agent Presets",
+      description: "List all available subagent presets with their descriptions and configuration.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {},
+      },
+
+      async execute() {
+        const entries = [...roles.entries()].map(([name, role]) => ({
+          name,
+          description: role.description,
+          model: role.model,
+          thinking: role.thinking,
+          mode: role.mode,
+          timeoutSeconds: role.timeoutSeconds,
+          tools: role.tools,
+          source: role.source,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ agents: entries }, null, 2),
+            },
+          ],
+        };
+      },
+    };
+  };
+}

package/src/spawn-role-tool.ts

@@ -0,0 +1,154 @@
+import { loadRoles } from "./role-loader.js";
+import { rolePolicyMap } from "./role-policy.js";
+import { loadSpawnSubagentDirect } from "./spawn-subagent.js";
+
+/**
+ * Build the spawn_agent tool factory.
+ * Returns a factory function that receives context per-session and produces the tool.
+ * Roles are loaded per-context using ctx.workspaceDir for correct workspace discovery.
+ */
+export function createSpawnAgentToolFactory(opts: {
+  pluginDir: string;
+  resolveStateDir: () => string | undefined;
+}) {
+  return async (ctx: any) => {
+    const roles = await loadRoles({
+      workspaceDir: ctx.workspaceDir,
+      stateDir: opts.resolveStateDir(),
+      pluginDir: opts.pluginDir,
+    });
+
+    if (roles.size === 0) return null;
+
+    const roleNames = [...roles.keys()];
+    const roleDescriptions = roleNames
+      .map((name) => {
+        const r = roles.get(name)!;
+        return `- **${name}**: ${r.description}`;
+      })
+      .join("\n");
+
+    return {
+      name: "spawn_agent",
+      label: "Spawn Agent",
+      description:
+        `Spawn a subagent with a predefined preset. Available agents:\n${roleDescriptions}`,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          agent: {
+            type: "string",
+            enum: roleNames,
+            description: "The agent preset to spawn",
+          },
+          task: {
+            type: "string",
+            description: "The task instruction for the subagent",
+          },
+          label: {
+            type: "string",
+            description: "Optional human-readable label for the spawned session",
+          },
+          thread: {
+            type: "boolean",
+            description: "Whether to bind the subagent to a thread",
+          },
+          mode: {
+            type: "string",
+            enum: ["run", "session"],
+            description: "Override the preset's default mode",
+          },
+        },
+        required: ["agent", "task"],
+      },
+
+      async execute(_id: string, params: Record<string, unknown>) {
+        const agentName = String(params.agent ?? "").trim();
+        const task = String(params.task ?? "").trim();
+
+        if (!agentName || !roles.has(agentName)) {
+          const available = roleNames.join(", ");
+          return errorResult(`Unknown agent "${agentName}". Available: ${available}`);
+        }
+
+        if (!task) {
+          return errorResult("task is required");
+        }
+
+        const role = roles.get(agentName)!;
+        const spawnMode = (params.mode as string) ?? role.mode ?? "run";
+
+        const spawnSubagentDirect = await loadSpawnSubagentDirect();
+
+        const spawnParams: Record<string, unknown> = {
+          task,
+          label: params.label ?? `${agentName}: ${task.slice(0, 60)}`,
+          expectsCompletionMessage: true,
+          mode: spawnMode,
+          cleanup: role.cleanup ?? "delete",
+          sandbox: role.sandbox ?? "inherit",
+        };
+
+        if (role.model) spawnParams.model = role.model;
+        if (role.thinking) spawnParams.thinking = role.thinking;
+        if (role.timeoutSeconds) spawnParams.runTimeoutSeconds = role.timeoutSeconds;
+        if (params.thread != null) spawnParams.thread = params.thread;
+
+        const spawnCtx: Record<string, unknown> = {
+          agentSessionKey: ctx.sessionKey,
+          agentChannel: ctx.messageChannel,
+          agentAccountId: ctx.agentAccountId,
+          sandboxed: ctx.sandboxed,
+        };
+
+        const result = await spawnSubagentDirect(spawnParams, spawnCtx);
+
+        if (result.status !== "accepted") {
+          return errorResult(result.error ?? `Spawn failed: ${result.status}`);
+        }
+
+        // Register policy for the child session.
+        // Safe timing: spawnSubagentDirect enqueues the child asynchronously
+        // on the gateway work queue. The child won't start its first LLM turn
+        // (and therefore won't hit before_prompt_build / before_tool_call)
+        // until the gateway dequeues it, which happens after we return.
+        if (result.childSessionKey) {
+          rolePolicyMap.set(result.childSessionKey, {
+            roleName: agentName,
+            systemPrompt: role.systemPrompt,
+            spawnMode: spawnMode as "run" | "session",
+            allow: role.tools?.allow,
+            deny: role.tools?.deny,
+          });
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  status: result.status,
+                  childSessionKey: result.childSessionKey,
+                  runId: result.runId,
+                  agent: agentName,
+                  resolvedFrom: role.source,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      },
+    };
+  };
+}
+
+function errorResult(message: string) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }],
+    isError: true,
+  };
+}

package/src/spawn-subagent.ts

@@ -0,0 +1,33 @@
+/**
+ * Dynamic import of spawnSubagentDirect from the openclaw plugin-sdk.
+ * Requires openclaw with the plugin-sdk/subagents export.
+ */
+
+type SpawnFn = (params: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<{
+  status: string;
+  childSessionKey?: string;
+  runId?: string;
+  mode?: string;
+  error?: string;
+}>;
+
+let cached: SpawnFn | null = null;
+
+export async function loadSpawnSubagentDirect(): Promise<SpawnFn> {
+  if (cached) return cached;
+
+  try {
+    const mod = await import("openclaw/plugin-sdk/subagents");
+    if (typeof mod.spawnSubagentDirect === "function") {
+      cached = mod.spawnSubagentDirect as SpawnFn;
+      return cached;
+    }
+  } catch {
+    // Fall through to error
+  }
+
+  throw new Error(
+    "spawn-agent: could not import spawnSubagentDirect from openclaw/plugin-sdk/subagents. " +
+    "Ensure openclaw is up to date and this plugin runs inside the openclaw gateway process.",
+  );
+}

package/subagents/coder.md

@@ -0,0 +1,21 @@
+---
+name: coder
+description: Autonomous coding agent with full tool access for implementation tasks
+model: anthropic/claude-sonnet-4-20250514
+thinking: high
+timeoutSeconds: 300
+mode: run
+cleanup: delete
+tools:
+  allow: [read, write, edit, exec, glob, grep, apply_patch, diffs]
+  deny: []
+---
+
+You are a coding agent. Write clean, correct, production-quality code.
+
+Guidelines:
+- Read existing code before modifying it
+- Follow the project's existing patterns and conventions
+- Write minimal, focused changes — avoid unnecessary refactoring
+- Include brief comments only for non-obvious logic
+- Test your changes when a test framework is available

package/subagents/reviewer.md

@@ -0,0 +1,19 @@
+---
+name: reviewer
+description: Read-only code reviewer focusing on bugs, security, and maintainability
+model: anthropic/claude-sonnet-4-20250514
+thinking: high
+timeoutSeconds: 120
+mode: run
+cleanup: delete
+tools:
+  allow: [read, diffs, grep, glob]
+  deny: [exec, write, edit, apply_patch]
+---
+
+You are a code reviewer. Be concise. Focus on:
+- Bugs and logic errors
+- Security issues (injection, auth bypass, data leaks)
+- Maintainability concerns
+
+Include specific fix suggestions with code examples. Do not make changes yourself.