typeclaw 0.5.0 → 0.6.0

package/src/agent/tools/subagent-cancel.ts

@@ -0,0 +1,96 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { PermissionService } from '@/permissions'
+
+import type { LiveSubagentRegistry } from '../live-subagents'
+import type { SessionOrigin } from '../session-origin'
+
+export type SubagentCancelToolDetails =
+  | { ok: true; taskId: string; subagent: string; alreadyDone: boolean }
+  | { ok: false; error: string }
+
+export type CreateSubagentCancelToolOptions = {
+  liveRegistry: LiveSubagentRegistry
+  getOrigin: () => SessionOrigin | undefined
+  permissions?: PermissionService
+}
+
+export function createSubagentCancelTool(options: CreateSubagentCancelToolOptions) {
+  const { liveRegistry, getOrigin, permissions } = options
+
+  return defineTool({
+    name: 'subagent_cancel',
+    label: 'Cancel Subagent',
+    description:
+      'Cancel a running subagent you previously spawned. The subagent receives an abort signal and its current in-flight tool call is interrupted. ' +
+      'Use this when the user changes their mind, the spawn is no longer needed, or a runaway subagent must be stopped. ' +
+      'Cancelling an already-completed or failed subagent is a no-op (returns ok=true with alreadyDone=true).',
+    parameters: Type.Object({
+      task_id: Type.String({
+        description: 'The task_id returned by a previous spawn_subagent call.',
+      }),
+    }),
+
+    async execute(_toolCallId, params): Promise<ToolReturn> {
+      if (permissions !== undefined && !permissions.has(getOrigin(), 'subagent.cancel')) {
+        return errorResult('subagent.cancel denied: insufficient permissions')
+      }
+      const live = liveRegistry.get(params.task_id)
+      if (live === undefined) {
+        return errorResult(`Unknown task_id: ${params.task_id}.`)
+      }
+      if (live.status !== 'running') {
+        const details: SubagentCancelToolDetails = {
+          ok: true,
+          taskId: live.taskId,
+          subagent: live.subagentName,
+          alreadyDone: true,
+        }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `${live.subagentName} (${live.taskId}) is already ${live.status}; nothing to cancel.`,
+            },
+          ],
+          details,
+        }
+      }
+      try {
+        await live.abort()
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        return errorResult(`abort failed: ${message}`)
+      }
+      const details: SubagentCancelToolDetails = {
+        ok: true,
+        taskId: live.taskId,
+        subagent: live.subagentName,
+        alreadyDone: false,
+      }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `${live.subagentName} (${live.taskId}) cancellation requested. It will stop on the next abort checkpoint.`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: SubagentCancelToolDetails
+}
+
+function errorResult(message: string): ToolReturn {
+  const details: SubagentCancelToolDetails = { ok: false, error: message }
+  return {
+    content: [{ type: 'text', text: message }],
+    details,
+  }
+}

package/src/agent/tools/subagent-output.ts

@@ -0,0 +1,192 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { PermissionService } from '@/permissions'
+
+import type { LiveSubagentRegistry, StatusSnapshot, SubagentProgressEvent } from '../live-subagents'
+import type { SessionOrigin } from '../session-origin'
+
+const DEFAULT_TIMEOUT_MS = 60_000
+const MAX_TIMEOUT_MS = 300_000
+
+export type SubagentOutputToolDetails =
+  | {
+      ok: true
+      status: 'running'
+      taskId: string
+      subagent: string
+      startedAt: number
+      elapsedMs: number
+      eventsCount: number
+      eventsRecent: SubagentProgressEvent[]
+      lastActivity: SubagentProgressEvent | null
+      statusSummary: string
+    }
+  | {
+      ok: true
+      status: 'completed'
+      taskId: string
+      subagent: string
+      durationMs: number
+      finalMessage?: string
+    }
+  | {
+      ok: true
+      status: 'failed'
+      taskId: string
+      subagent: string
+      durationMs: number
+      error: string
+    }
+  | { ok: false; error: string }
+
+export type CreateSubagentOutputToolOptions = {
+  liveRegistry: LiveSubagentRegistry
+  getOrigin: () => SessionOrigin | undefined
+  permissions?: PermissionService
+  now?: () => number
+}
+
+export function createSubagentOutputTool(options: CreateSubagentOutputToolOptions) {
+  const { liveRegistry, getOrigin, permissions, now = () => Date.now() } = options
+
+  return defineTool({
+    name: 'subagent_output',
+    label: 'Subagent Output',
+    description:
+      'Fetch the current state of a subagent you previously spawned. Returns one of three statuses: ' +
+      "'running' (with a human-readable status_summary and a tail of recent progress events), " +
+      "'completed' (with the final message), or 'failed' (with the error). " +
+      'Use this when the user asks how a long-running subagent is going, or when you need to retrieve the result of a backgrounded spawn. ' +
+      'When block=true (default false), the tool waits up to timeout_ms for completion before returning. ' +
+      'Prefer block=false and rely on the system-reminder for completion notification; reserve block=true for tight workflows.',
+    parameters: Type.Object({
+      task_id: Type.String({
+        description: 'The task_id returned by a previous spawn_subagent call.',
+      }),
+      block: Type.Optional(
+        Type.Boolean({
+          description:
+            'If true, wait for the subagent to complete (or time out) before returning. Default false: return immediately with the current state.',
+        }),
+      ),
+      timeout_ms: Type.Optional(
+        Type.Integer({
+          description: `When block=true, max milliseconds to wait (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}).`,
+          minimum: 1,
+          maximum: MAX_TIMEOUT_MS,
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      if (permissions !== undefined && !permissions.has(getOrigin(), 'subagent.output')) {
+        return errorResult('subagent.output denied: insufficient permissions')
+      }
+      const live = liveRegistry.get(params.task_id)
+      if (live === undefined) {
+        return errorResult(`Unknown task_id: ${params.task_id}.`)
+      }
+
+      const wantsBlock = params.block === true && live.status === 'running'
+      if (wantsBlock) {
+        const timeoutMs = clampTimeout(params.timeout_ms)
+        await raceWithTimeout(live.awaitCompletion(), timeoutMs)
+      }
+
+      const snap = liveRegistry.snapshot(params.task_id, now())
+      if (snap === undefined) {
+        return errorResult(`Unknown task_id: ${params.task_id}.`)
+      }
+      return renderSnapshot(snap)
+    },
+  })
+}
+
+function clampTimeout(value: number | undefined): number {
+  if (value === undefined) return DEFAULT_TIMEOUT_MS
+  return Math.min(Math.max(1, Math.floor(value)), MAX_TIMEOUT_MS)
+}
+
+async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+  return new Promise<T | undefined>((resolve) => {
+    const timer = setTimeout(() => resolve(undefined), timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      () => {
+        clearTimeout(timer)
+        resolve(undefined)
+      },
+    )
+  })
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: SubagentOutputToolDetails
+}
+
+function renderSnapshot(snap: StatusSnapshot): ToolReturn {
+  if (snap.status === 'running') {
+    const details: SubagentOutputToolDetails = {
+      ok: true,
+      status: 'running',
+      taskId: snap.taskId,
+      subagent: snap.subagentName,
+      startedAt: snap.startedAt,
+      elapsedMs: snap.elapsedMs,
+      eventsCount: snap.eventsCount,
+      eventsRecent: snap.eventsRecent,
+      lastActivity: snap.lastActivity,
+      statusSummary: snap.statusSummary,
+    }
+    return {
+      content: [{ type: 'text' as const, text: snap.statusSummary }],
+      details,
+    }
+  }
+  if (snap.status === 'completed') {
+    const finalMessage = snap.completion?.finalMessage
+    const details: SubagentOutputToolDetails = {
+      ok: true,
+      status: 'completed',
+      taskId: snap.taskId,
+      subagent: snap.subagentName,
+      durationMs: snap.completion?.durationMs ?? snap.elapsedMs,
+      ...(finalMessage !== undefined ? { finalMessage } : {}),
+    }
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: finalMessage ?? `${snap.subagentName} completed in ${details.durationMs}ms with no final message.`,
+        },
+      ],
+      details,
+    }
+  }
+  const error = snap.completion?.error ?? 'unknown error'
+  const details: SubagentOutputToolDetails = {
+    ok: true,
+    status: 'failed',
+    taskId: snap.taskId,
+    subagent: snap.subagentName,
+    durationMs: snap.completion?.durationMs ?? snap.elapsedMs,
+    error,
+  }
+  return {
+    content: [{ type: 'text' as const, text: `${snap.subagentName} failed after ${details.durationMs}ms: ${error}` }],
+    details,
+  }
+}
+
+function errorResult(message: string): ToolReturn {
+  const details: SubagentOutputToolDetails = { ok: false, error: message }
+  return {
+    content: [{ type: 'text', text: message }],
+    details,
+  }
+}

package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md

@@ -53,6 +53,32 @@ Tailscale and other remote networks. No special flag, tool, or config required.
 **Always share the proxy port URL — never `localhost:<raw-session-port>`** —
 those raw ports are inside the container and unreachable from the host.
 
+### Don't confuse the proxy port with the dashboard port
+
+There are two ports in play. Both sockets live inside the container, but
+they have very different audiences:
+
+| File                                        | Audience                 | What it's for                                                                                                                                                                                                                                                        |
+| ------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/tmp/typeclaw-agent-browser-proxy-port`    | **Host browser**         | The port the host browser opens (`http://localhost:<proxy-port>`). Host-forwarded via hostd; the compatibility proxy rewrites the dashboard's hardcoded loopback URLs so they work over Tailscale/LAN. **Default `4848`, falls back to `4849`–`4857` on collision.** |
+| `/tmp/typeclaw-agent-browser-upstream-port` | **In-container clients** | The actual `agent-browser dashboard` server. **Default `4849`.** This is what other in-container processes (Cloudflare tunnels, in-container `curl`, in-container scripts) must talk to. Not host-forwarded — there's no point.                                      |
+
+**For Cloudflare tunnels and anything else that originates inside the
+container, use the upstream-port file, NOT the proxy-port file.** Cloudflare's
+`cloudflared` runs in the container's netns and connects to `127.0.0.1:<port>`
+directly — it doesn't traverse the compatibility proxy and gains nothing from
+it. Pointing a tunnel at the proxy port silently tunnels the proxy's listen
+socket instead of the dashboard; the tunnel comes up, the URL "works" against
+the proxy's pass-through paths, but anything dashboard-specific (sessions,
+WebSocket activity feed, JSON API) breaks in non-obvious ways.
+
+Common-failure shape: reading `proxy-port` mechanically because it's the
+file you remembered, then passing that to `typeclaw tunnel add` or to a
+`cloudflared --url http://127.0.0.1:<port>` invocation. **Read the
+`upstream-port` file for tunnel upstreams.** When in doubt, run
+`agent-browser dashboard status` (or check the `agent-browser dashboard
+start` log line — it prints the upstream URL).
+
 ### When NOT to use the dashboard
 
 The dashboard is for **live observation and handoff**, not file delivery. If

package/src/bundled-plugins/explorer/explorer.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod'
+
+import { bashTool, findTool, grepTool, lsTool, readTool, type Subagent } from '@/plugin'
+
+export const EXPLORER_SYSTEM_PROMPT = `You are a local-search specialist running inside TypeClaw. Your job: find things on the agent's local filesystem (code, transcripts, memory, config, git history, mounts) and return actionable results to the caller. For EXTERNAL web research, the caller should spawn \`scout\` instead — you have no network tools.
+
+=== READ-ONLY — NO FILE MODIFICATIONS ===
+You are STRICTLY PROHIBITED from:
+- Creating, modifying, or deleting files
+- Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any write operation
+- Starting long-running background processes
+- Writing to MEMORY.md, sessions/, workspace/, or any other runtime-managed path
+- Spawning further subagents — you are at the end of the delegation chain
+
+Your role is EXCLUSIVELY to search and analyze existing local state.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`find\` — locate files by name pattern or extension across a directory tree
+- \`grep\` — search file contents by text or regex
+- \`read\` — read a specific file once you know its path
+- \`ls\` — list a directory's immediate contents for structural discovery
+- \`bash\` — ONLY for read-only commands. The two common shapes are read-only git (\`git log\`, \`git blame\`, \`git diff\`, \`git status\`, \`git grep\`, \`git show <commit>:<path>\`) and one-shot pipelines that don't mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`, \`awk\`)
+
+Launch 3+ tools in parallel whenever you can. Cross-validate findings across multiple tools — a grep hit confirmed by reading the file is stronger than either alone.
+
+## Local searchable surfaces
+
+The agent folder is mounted at \`/agent\` inside the container. Search the narrowest relevant surface before falling back to broad codebase greps.
+
+1. **Codebase** — \`/agent/\` root and subdirs (excluding the runtime-managed paths below). Source files, docs, identity files (\`IDENTITY.md\`, \`SOUL.md\`, \`USER.md\`, \`AGENTS.md\`).
+2. **Sessions** — \`/agent/sessions/*.jsonl\` — conversation transcripts. Each line is a JSON event (user message, tool call, tool result, assistant message). Filename pattern \`\${ISO_TIMESTAMP}_\${UUID}.jsonl\`. \`grep\` works directly on the JSONL.
+3. **Memory** — \`/agent/MEMORY.md\` (long-term consolidated memory) and \`/agent/memory/yyyy-MM-dd.jsonl\` (daily fragment streams written by the memory-logger subagent). \`memory/.dreaming-state.json\` tracks the dreaming watermark. Do NOT edit any of these — they are runtime-owned.
+4. **Muscle-memory skills** — \`/agent/memory/skills/<name>/SKILL.md\` — procedures the dreaming subagent distilled from repeated work.
+5. **User-installed skills** — \`/agent/.agents/skills/<name>/SKILL.md\` — hand-authored or downloaded skills.
+6. **Workspace** — \`/agent/workspace/\` — the agent's free-write zone. Drafts, scratch work, generated artifacts.
+7. **Cron** — \`/agent/cron.json\` — scheduled jobs. Plugin-contributed cron jobs are in-memory only and not visible from disk.
+8. **Config** — \`/agent/typeclaw.json\`, \`/agent/package.json\`, \`/agent/Dockerfile\`, \`/agent/.env\`, \`/agent/.gitignore\`, \`/agent/secrets.json\`. **\`.env\` and \`secrets.json\` contain credentials — never echo their values back to the caller verbatim; describe what's configured without printing tokens.**
+9. **Git history** — \`.git\` under \`/agent/\`. Search via read-only \`git log\`, \`git blame\`, \`git diff\`, \`git grep\`, \`git show <commit>:<path>\`.
+10. **Logs** — \`/agent/sessions/backup-diagnostics.log\` is the only persistent log inside the container (backup-plugin failures). Container stdout/stderr is ephemeral.
+11. **Mounts** — \`/agent/mounts/<name>/\` — host directories mapped into the container per \`typeclaw.json#mounts\`.
+12. **Channels persistence** — \`/agent/channels/sessions.json\` — active channel sessions, participants, last inbound timestamps.
+13. **Packages** — \`/agent/packages/\` — user-authored plugins or libraries the agent built.
+14. **Container-only state** — \`/agent/node_modules/\` (auto-generated, large — prefer targeted greps) and \`/tmp/\` (ephemeral).
+
+## Process
+
+Before searching, analyze intent in an <analysis> block:
+
+<analysis>
+**Literal Request**: [what they literally asked]
+**Actual Need**: [what they're really trying to accomplish]
+**Success Looks Like**: [what result lets them proceed immediately]
+</analysis>
+
+End every response with this exact structure:
+
+<results>
+<files>
+- /absolute/path/to/file.ts — [why this file is relevant]
+</files>
+<answer>
+[Direct answer to the actual need, not just a file list. If they asked "where is auth?", explain the auth flow you found.]
+</answer>
+<next_steps>
+[What the caller should do next, or "Ready to proceed."]
+</next_steps>
+</results>
+
+## Rules
+
+- Every path MUST be absolute (start with /).
+- Find ALL relevant matches, not just the first. Completeness over speed.
+- Do NOT diagnose, plan, or make architectural decisions — that's the caller's job. You find and report.
+- If the question requires EXTERNAL/web information (docs, library reference, web search, fetching a URL), say so explicitly and tell the caller to spawn \`scout\` instead. Do not try to answer external questions from memory.
+- If you cannot find what was asked, say so explicitly with what you DID find and what surfaces you searched.`
+
+export const explorerPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ExplorerPayload = z.infer<typeof explorerPayloadSchema>
+
+export function createExplorerSubagent(): Subagent<ExplorerPayload> {
+  return {
+    systemPrompt: EXPLORER_SYSTEM_PROMPT,
+    profile: 'fast',
+    tools: [readTool, grepTool, findTool, lsTool, bashTool],
+    payloadSchema: explorerPayloadSchema,
+    visibility: 'public',
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 256_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash'],
+    },
+  }
+}

package/src/bundled-plugins/explorer/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createExplorerSubagent } from './explorer'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      explorer: createExplorerSubagent(),
+    },
+  }),
+})

package/src/bundled-plugins/guard/index.ts

@@ -1,11 +1,22 @@
 import { definePlugin } from '@/plugin'
 
-import { checkNonWorkspaceWriteGuard, checkSkillAuthoringGuard, checkUncommittedChangesAdvice } from './policy'
+import {
+  checkManagedConfigGuard,
+  checkNonWorkspaceWriteGuard,
+  checkSkillAuthoringGuard,
+  checkUncommittedChangesAdvice,
+} from './policy'
 
 export default definePlugin({
   plugin: async () => ({
     hooks: {
       'tool.before': async (event, ctx) => {
+        const managedConfigResult = await checkManagedConfigGuard({
+          tool: event.tool,
+          args: event.args,
+          agentDir: ctx.agentDir,
+        })
+        if (managedConfigResult) return managedConfigResult
         const skillResult = await checkSkillAuthoringGuard({
           tool: event.tool,
           args: event.args,

package/src/bundled-plugins/guard/policies/managed-config.ts

@@ -0,0 +1,139 @@
+import { readFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import { parseConfigJson } from '@/config'
+import { parseCronJson } from '@/cron'
+
+import type { GuardBlock } from '../policy'
+
+export const GUARD_MANAGED_CONFIG = 'managedConfig'
+
+type ManagedFile = 'typeclaw.json' | 'cron.json'
+
+const MANAGED_FILES = new Set<ManagedFile>(['typeclaw.json', 'cron.json'])
+
+export async function checkManagedConfigGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+}): Promise<GuardBlock | undefined> {
+  const { tool, args, agentDir } = options
+  if (tool !== 'write' && tool !== 'edit') return undefined
+
+  const rawPath = args.path
+  if (typeof rawPath !== 'string') return undefined
+
+  const targetPath = path.resolve(agentDir, rawPath)
+  const managed = await resolveManagedTarget(agentDir, targetPath)
+  if (!managed) return undefined
+
+  const contentResult = await intendedContent(tool, args, targetPath)
+  if ('block' in contentResult) return contentResult
+
+  const validation = validateManagedContent(managed.file, contentResult.content)
+  if (validation.ok) return undefined
+
+  return {
+    block: true,
+    reason: `Guard \`${GUARD_MANAGED_CONFIG}\` blocked ${tool} for ${targetPath}: ${validation.reason}.`,
+  }
+}
+
+async function resolveManagedTarget(agentDir: string, targetPath: string): Promise<{ file: ManagedFile } | undefined> {
+  const resolvedAgentDir = path.resolve(agentDir)
+  const realAgentDir = await resolveRealIntendedPath(resolvedAgentDir)
+  const realTargetPath = await resolveRealIntendedPath(targetPath)
+
+  if (path.dirname(realTargetPath) !== realAgentDir) return undefined
+
+  const basename = path.basename(realTargetPath)
+  return isManagedFile(basename) ? { file: basename } : undefined
+}
+
+function isManagedFile(basename: string): basename is ManagedFile {
+  return MANAGED_FILES.has(basename as ManagedFile)
+}
+
+function validateManagedContent(file: ManagedFile, content: string): { ok: true } | { ok: false; reason: string } {
+  if (file === 'typeclaw.json') {
+    const result = parseConfigJson(content, { migrate: false })
+    return result.ok ? { ok: true } : { ok: false, reason: result.reason }
+  }
+  const result = parseCronJson(content, { migrate: false })
+  return result.ok ? { ok: true } : { ok: false, reason: result.reason }
+}
+
+async function intendedContent(
+  tool: string,
+  args: Record<string, unknown>,
+  targetPath: string,
+): Promise<{ content: string } | GuardBlock> {
+  if (tool === 'write') {
+    const content = args.content
+    if (typeof content !== 'string') {
+      return blockReason(tool, targetPath, 'write content must be a string')
+    }
+    return { content }
+  }
+
+  const edits = args.edits
+  if (!Array.isArray(edits)) {
+    return blockReason(tool, targetPath, 'edit calls must include an edits array')
+  }
+
+  let content: string
+  try {
+    content = await readFile(targetPath, 'utf8')
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return blockReason(tool, targetPath, `could not read existing file before edit: ${message}`)
+  }
+
+  for (const edit of edits) {
+    if (!edit || typeof edit !== 'object') {
+      return blockReason(tool, targetPath, 'each edit must be an object')
+    }
+    const { oldText, newText } = edit as Record<string, unknown>
+    if (typeof oldText !== 'string' || typeof newText !== 'string') {
+      return blockReason(tool, targetPath, 'each edit must include string oldText and newText')
+    }
+    if (oldText.length === 0) {
+      return blockReason(tool, targetPath, 'edit oldText must not be empty')
+    }
+    if (!content.includes(oldText)) {
+      return blockReason(tool, targetPath, 'edit oldText was not found in existing file')
+    }
+    content = content.replace(oldText, newText)
+  }
+  return { content }
+}
+
+function blockReason(tool: string, targetPath: string, reason: string): GuardBlock {
+  return {
+    block: true,
+    reason: `Guard \`${GUARD_MANAGED_CONFIG}\` blocked ${tool} for ${targetPath}: ${reason}.`,
+  }
+}
+
+async function resolveRealIntendedPath(absolutePath: string): Promise<string> {
+  const pending: string[] = []
+  let current = absolutePath
+
+  while (true) {
+    try {
+      const realCurrent = await realpath(current)
+      return path.join(realCurrent, ...pending.reverse())
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) throw new Error(`could not resolve existing parent for ${absolutePath}`)
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFoundError(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}

package/src/bundled-plugins/guard/policy.ts

@@ -8,6 +8,7 @@ export function isGuardAcknowledged(args: Record<string, unknown>, guard: string
   return (acknowledgements as Record<string, unknown>)[guard] === true
 }
 
+export { GUARD_MANAGED_CONFIG, checkManagedConfigGuard } from './policies/managed-config'
 export { GUARD_NON_WORKSPACE_WRITE, checkNonWorkspaceWriteGuard } from './policies/non-workspace-write'
 export {
   GUARD_SKILL_AUTHORING,

package/src/bundled-plugins/operator/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createOperatorSubagent } from './operator'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      operator: createOperatorSubagent(),
+    },
+  }),
+})