@hueyexe/opencode-ensemble 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hueyexe/opencode-ensemble",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Agent teams for OpenCode — parallel agents with peer-to-peer communication, shared tasks, and coordinated execution",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -48,7 +48,7 @@
     "@opentui/core": "0.5.10",
     "@opentui/solid": "0.5.10",
     "@types/bun": "latest",
-    "solid-js": "1.9.0"
+    "solid-js": "1.9.4"
   },
   "peerDependencies": {
     "typescript": "^5",

package/src/tool-arg-hint.ts

@@ -0,0 +1,71 @@
+/**
+ * Weak-model tool-argument fumble detection and error hints (issue #39).
+ *
+ * Some models trained on other harness conventions call OpenCode's built-in
+ * tools with aliased parameter names (e.g. `cmd` instead of the `shell`
+ * tool's `command`). OpenCode V2 rejects the call with a generic validation
+ * error that the model may fail to act on. This module detects that exact
+ * dead-call shape and produces an explicit hint appended to the error so
+ * the model can self-correct. Arguments are never rewritten — the model
+ * stays in the correction loop.
+ *
+ * V2 only: on V1, argument validation happens at the model-stream parse
+ * level, so tool hooks never see the failed call (see issue #39 triage).
+ */
+
+/**
+ * Canonical parameter plus the aliases weak models emit for it. Only the
+ * confirmed failure mode is listed; extend per-tool as reports come in.
+ */
+const ARG_ALIASES: Readonly<Record<string, { param: string; aliases: readonly string[] }>> = {
+  shell: { param: "command", aliases: ["cmd", "bash", "script"] },
+}
+
+/**
+ * Return the alias a weak model used instead of the tool's canonical
+ * parameter, or null when the input is not a recognized fumble. A fumble is
+ * only recognized when the canonical parameter is absent and a known alias
+ * is present as a non-empty string — i.e. only on calls that are already
+ * guaranteed to fail validation.
+ */
+export function detectArgFumble(tool: string, input: unknown): string | null {
+  const entry = ARG_ALIASES[tool]
+  if (!entry) return null
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return null
+  const args = input as Record<string, unknown>
+  if (entry.param in args) return null
+  for (const alias of entry.aliases) {
+    const value = args[alias]
+    if (typeof value === "string" && value !== "") return alias
+  }
+  return null
+}
+
+/**
+ * Build the hint text for a fumbled tool call, or null when the input is
+ * not a recognized fumble.
+ */
+export function buildArgHint(tool: string, input: unknown): string | null {
+  const entry = ARG_ALIASES[tool]
+  if (!entry) return null
+  const alias = detectArgFumble(tool, input)
+  if (!alias) return null
+  return (
+    `Hint: the "${tool}" tool has no "${alias}" parameter. The correct parameter ` +
+    `name is "${entry.param}" — call the tool again with the same arguments, ` +
+    `moving the "${alias}" value into "${entry.param}".`
+  )
+}
+
+/**
+ * Append the fumble hint to a failed tool call's error message in place.
+ * Returns true when the message was modified. Never throws — a malformed
+ * error or input leaves the original message untouched.
+ */
+export function enrichToolError(tool: string, error: { message?: unknown }, input: unknown): boolean {
+  if (typeof error.message !== "string") return false
+  const hint = buildArgHint(tool, input)
+  if (!hint) return false
+  error.message = `${error.message}\n\n${hint}`
+  return true
+}

package/src/tools/team-spawn.ts

@@ -87,7 +87,11 @@ export async function executeTeamSpawn(
     .get(teamInfo.teamId, args.name)
   if (existing) throw new Error(`Teammate "${args.name}" already exists in team "${teamInfo.teamName}"`)
 
-  const isReadOnly = agent === "plan" || agent === "explore"
+  // Prefer the agent's own permission rules (V2) so any agent that denies
+  // edits — not only the built-in plan/explore — is treated as read-only and
+  // never gets a worktree or a shell allow. Fall back to the built-in names.
+  const isReadOnly = (await deps.client.agent?.readOnly(agent).catch(() => undefined))
+    ?? (agent === "plan" || agent === "explore")
   const useWorktree = args.worktree !== false && !isReadOnly && !isWorktreeDirectory(deps.directory)
   const usePlanApproval = args.plan_approval === true
 
@@ -167,6 +171,12 @@ export async function executeTeamSpawn(
   if (worktreeDir) {
     permission.push(
       { permission: "edit", pattern: `${worktreeDir}/**`, action: "allow" },
+      // V2 checks files inside the session's location as paths relative to
+      // it. session.create above binds the location to the worktree (via
+      // workspaceID, or directory as fallback), so this rule scopes edits
+      // to the worktree. Files outside the worktree remain gated by
+      // external_directory.
+      { permission: "edit", pattern: "*", action: "allow" },
     )
     if (!isReadOnly) {
       permission.push({ permission: "bash", pattern: "*", action: "allow" })
@@ -200,7 +210,14 @@ export async function executeTeamSpawn(
         parentID: sessionId,
         title: `${args.name} (@${agent} teammate)`,
         permission,
-        ...(workspaceId ? { workspaceID: workspaceId } : {}),
+        ...(workspaceId
+          ? { workspaceID: workspaceId }
+          // Workspace binding is preferred; when it is unavailable, bind the
+          // session to the worktree directory directly. Without a location,
+          // the teammate's location is the project root, edit paths are
+          // evaluated relative to it, and the `edit * allow` rule below
+          // would grant edits to the whole shared tree (PR #46 review).
+          : worktreeDir ? { directory: worktreeDir } : {}),
       }),
       getSpawnTimeout(), `session.create for "${args.name}"`
     )
@@ -445,6 +462,13 @@ export async function executeTeamSpawn(
   })
 
   const branchInfo = worktreeBranch ? ` (branch: ${worktreeBranch})` : ""
+  // Isolation is a claim the lead relies on, so say plainly when it did not
+  // complete. The toast alone left "spawned" as the only signal (issue #40).
+  // Covers both failure modes: no worktree at all (shared directory) or a
+  // worktree whose branch could not be created (unmergeable detached HEAD).
+  const isolationInfo = useWorktree && !worktreeBranch
+    ? ` (WARNING: worktree isolation did not complete — ${args.name} may share your working directory or lack a mergeable branch; edits can collide and team_merge may fail)`
+    : ""
   const planInfo = usePlanApproval ? " [plan mode — will send plan for approval]" : ""
   const claimInfo = claimedTaskContent
     ? ` (claimed task: ${args.claim_task})`
@@ -452,5 +476,5 @@ export async function executeTeamSpawn(
   // Reset circuit breaker on success
   spawnFailures.delete(teamInfo.teamId)
   log(`spawn:done name=${args.name} sessionId=${childSessionId}`)
-  return `Teammate "${args.name}" spawned (agent: ${agent})${branchInfo}${planInfo}${claimInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
+  return `Teammate "${args.name}" spawned (agent: ${agent})${branchInfo}${isolationInfo}${planInfo}${claimInfo}. They are working on: ${args.prompt.slice(0, 120)}${args.prompt.length > 120 ? "..." : ""}`
 }

package/src/tools/team-tasks-add.ts

@@ -19,6 +19,23 @@ export async function executeTeamTasksAdd(
 ): Promise<string> {
   const teamInfo = requireTeamMember(deps, sessionId)
 
+  // Reject unknown dependency IDs before inserting anything: a task blocked on
+  // an ID that never existed can never unblock (issue #40). IDs are generated
+  // here, so new tasks can only depend on existing ones and no cycle can form.
+  const unknown = new Set<string>()
+  for (const task of args.tasks) {
+    for (const depId of task.depends_on ?? []) {
+      const exists = deps.db.query("SELECT 1 FROM team_task WHERE id = ? AND team_id = ?").get(depId, teamInfo.teamId)
+      if (!exists) unknown.add(depId)
+    }
+  }
+  if (unknown.size > 0) {
+    throw new Error(
+      `Unknown task ID${unknown.size > 1 ? "s" : ""} in depends_on: ${[...unknown].join(", ")}. ` +
+        "Use IDs from team_tasks_list, or add the prerequisite tasks first and reference the IDs they return.",
+    )
+  }
+
   const ids: string[] = []
   const now = Date.now()
 

package/src/types.ts

@@ -35,6 +35,10 @@ export interface PermissionRule {
  * Makes mocking trivial in tests.
  */
 export interface PluginClient {
+  /** Optional agent introspection (V2). Undefined answers fall back to name checks. */
+  agent?: {
+    readOnly(agent: string): Promise<boolean | undefined>
+  }
   session: {
     create(options: {
       parentID?: string

package/src/v2-client.ts

@@ -1,8 +1,11 @@
 import type { PluginClient } from "./types"
+import { log } from "./log"
 import { runCommand } from "./process"
 
 /** V2 plugin context subset Ensemble needs (structural, mock-friendly). */
 export interface V2Context {
+  /** Plugin location; `project.id` is required by the 2.0.19+ worktree API. */
+  location?: { directory?: string; project?: { id?: string } }
   session: {
     create(input: Record<string, unknown>): Promise<{ id: string }>
     prompt(input: Record<string, unknown>): Promise<unknown>
@@ -17,12 +20,39 @@ export interface V2Context {
   worktree: {
     create(input: Record<string, unknown>): Promise<{ directory: string }>
     remove(input: Record<string, unknown>): Promise<unknown>
-    list(): Promise<Array<{ directory: string }>>
-    refresh(): Promise<unknown>
+    list(input?: Record<string, unknown>): Promise<Array<{ directory: string }>>
+    refresh(input?: Record<string, unknown>): Promise<unknown>
   }
   permission: {
-    rules(input: Record<string, unknown>): Promise<unknown>
+    /** Present on 2.0.3–2.0.18 only; removed in 2.0.19 (see issue #40). */
+    rules?(input: Record<string, unknown>): Promise<unknown>
   }
+  /** Agent lookup (2.0.19+): exposes each agent's resolved permission rules. */
+  agent?: {
+    get(input: Record<string, unknown>): Promise<unknown>
+  }
+}
+
+type PermissionRuleV2 = { action?: unknown; resource?: unknown; effect?: unknown }
+
+/** OpenCode wildcard match: `*` matches any run of characters. */
+function wildcardMatch(value: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")
+  return new RegExp(`^${escaped}$`).test(value)
+}
+
+/**
+ * True when an agent's own rules deny editing everywhere. OpenCode evaluates
+ * the last matching rule, so this mirrors `evaluate("edit", "*")` over the
+ * agent ruleset. Undefined when the rules carry no edit decision.
+ */
+export function agentRulesAreReadOnly(rules: unknown): boolean | undefined {
+  if (!Array.isArray(rules)) return undefined
+  const match = [...(rules as PermissionRuleV2[])].reverse().find((rule) =>
+    typeof rule?.action === "string" && typeof rule?.resource === "string"
+    && wildcardMatch("edit", rule.action) && (rule.resource === "*" || rule.resource === "**"))
+  if (!match) return undefined
+  return match.effect === "deny"
 }
 
 /** Prefix marking a workspace id that is really a local directory (see below). */
@@ -32,6 +62,10 @@ const DIR_WORKSPACE_PREFIX = "v2dir:"
 export interface V2ClientDeps {
   /** Current branch checked out in a directory, or null when unknown. */
   gitBranch?: (directory: string) => Promise<string | null>
+  /** Create and check out a branch in a directory. Returns the effective
+   * branch name, or null when the branch could not be created or checked
+   * out — never record the requested name without this confirmation. */
+  gitCreateBranch?: (directory: string, branch: string) => Promise<string | null>
   /** Worktree directory currently on a branch, or null when none. */
   gitDir?: (branch: string) => Promise<string | null>
   /** RPC emitter for companion events (team_view navigation). */
@@ -49,6 +83,31 @@ async function gitBranchDefault(directory: string): Promise<string | null> {
   }
 }
 
+/** Create and check out a branch in a directory via git. Returns the
+ * effective branch name, or null when neither create nor switch worked —
+ * callers must record the return value, not the requested name, so a
+ * failed create can never be recorded as a live branch. */
+async function gitCreateBranchDefault(directory: string, branch: string): Promise<string | null> {
+  try {
+    await runCommand(["git", "switch", "-c", branch], { cwd: directory })
+    return branch
+  } catch (err) {
+    // The branch may already exist (re-spawn after the abort-cleanup race
+    // documented in AGENTS.md) — switch to it instead of recording a name
+    // with no ref behind it. Log both attempts; swallowing failures silently
+    // made team_merge squash a stale branch and silently lose new work
+    // (PR #46 review).
+    log(`v2-client:gitCreateBranch:create-failed directory=${directory} branch=${branch} err=${err instanceof Error ? err.message : String(err)} — trying existing branch`)
+    try {
+      await runCommand(["git", "switch", branch], { cwd: directory })
+      return branch
+    } catch (err2) {
+      log(`v2-client:gitCreateBranch:switch-failed directory=${directory} branch=${branch} err=${err2 instanceof Error ? err2.message : String(err2)}`)
+      return null
+    }
+  }
+}
+
 /** Concatenate the text parts of a promptAsync payload into one string. */
 function joinParts(parts: Array<{ type: "text"; text: string }>): string {
   return parts
@@ -88,7 +147,24 @@ function joinParts(parts: Array<{ type: "text"; text: string }>): string {
  */
 export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginClient {
   const gitBranch = deps.gitBranch ?? gitBranchDefault
+  const gitCreateBranch = deps.gitCreateBranch ?? gitCreateBranchDefault
+  // 2.0.19+ worktree endpoints require the project; older hosts ignore it.
+  const project = (): Record<string, unknown> => {
+    const projectID = ctx.location?.project?.id
+    return projectID ? { projectID } : {}
+  }
   return {
+    agent: {
+      readOnly: async (agent: string) => {
+        if (!ctx.agent) return undefined
+        try {
+          const info = (await ctx.agent.get({ agentID: agent })) as { permissions?: unknown; data?: { permissions?: unknown } } | undefined
+          return agentRulesAreReadOnly(info?.permissions ?? info?.data?.permissions)
+        } catch {
+          return undefined
+        }
+      },
+    },
     session: {
       create: async (options) => {
         const input: Record<string, unknown> = { title: options.title }
@@ -114,11 +190,12 @@ export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginC
           }
         }
         const created = await ctx.session.create(input)
-        if (permissions) {
-          // Session.create permissions lose to agent rules (last match wins
-          // and agent rules apply later), which strips team tools from
-          // read-only agents. Re-assert here: rules() evaluates after the
-          // agent's rules, restoring the tools. OQ-V2-rules.
+        if (permissions && typeof ctx.permission?.rules === "function") {
+          // 2.0.3–2.0.18 merged agent rules after session rules, so create()
+          // permissions lost to the agent's and had to be re-asserted. From
+          // 2.0.19 the session ruleset merges last (core permission.ts
+          // `merge(agent.permissions, session.permissions)` with last-match
+          // evaluation) and rules() no longer exists, so create() is enough.
           await ctx.permission.rules({ sessionID: created.id, permissions })
         }
         return { data: { id: created.id } }
@@ -177,16 +254,24 @@ export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginC
     worktree: {
       create: async (options) => {
         const name = (options.worktreeCreateInput as { name?: string } | undefined)?.name ?? "ensemble-worktree"
-        const created = await ctx.worktree.create({ name })
-        const branch = (await gitBranch(created.directory)) ?? name
+        const created = await ctx.worktree.create({ ...project(), name })
+        let branch = await gitBranch(created.directory)
+        if (!branch) {
+          // 2.0.32+ creates worktrees detached; team_merge needs a named
+          // branch. Record the effective branch only — never the requested
+          // name — so a failed create cannot point team_merge at a stale
+          // same-named branch whose commits would silently shadow new work
+          // (PR #46 review).
+          branch = (await gitCreateBranch(created.directory, name)) ?? ""
+        }
         return { data: { name, branch, directory: created.directory } }
       },
       remove: async (options) => {
         const directory = (options.worktreeRemoveInput as { directory: string }).directory
-        return ctx.worktree.remove({ directory, force: false })
+        return ctx.worktree.remove({ ...project(), directory, force: false })
       },
       list: async () => {
-        const entries = await ctx.worktree.list()
+        const entries = await ctx.worktree.list(project())
         return {
           data: entries.map((entry) => ({
             name: entry.directory.split("/").pop() ?? entry.directory,
@@ -195,7 +280,7 @@ export function createV2Client(ctx: V2Context, deps: V2ClientDeps = {}): PluginC
           })),
         }
       },
-      reset: async () => ctx.worktree.refresh(),
+      reset: async () => ctx.worktree.refresh(project()),
     },
     workspace: {
       create: async (options) => {

package/src/v2-setup.ts

@@ -11,6 +11,7 @@ import type { ToolDeps } from "./types"
 import { ProgressTracker } from "./progress"
 import { checkToolIsolation, shouldNudgeIdleMember } from "./hooks"
 import { hasReportedCompletion } from "./messaging"
+import { enrichToolError } from "./tool-arg-hint"
 import { rehydrateRegistry } from "./recovery"
 import { findTeamBySession } from "./types"
 import { loadConfig } from "./config"
@@ -24,7 +25,8 @@ import { vlog } from "./log"
 
 /** V2 setup context subset (structural, mock-friendly). */
 export interface V2SetupContext {
-  location: { directory: string }
+  location: { directory: string; project?: { id?: string } }
+  agent?: V2Context["agent"]
   options: Record<string, unknown>
   session: V2Context["session"] & {
     hook(name: string, cb: (event: never) => unknown): Promise<{ dispose(): Promise<void> }>
@@ -251,6 +253,17 @@ export async function setupEnsemble(
       input: unknown
       status: string
       result?: { content?: string | Array<{ type?: string; text?: string }> }
+      error?: { message?: unknown }
+    }
+    if (event.status === "error" && event.error) {
+      // Weak-model arg fumbles (issue #39): the call is already dead from
+      // validation, so append an explicit "the param is X, not Y" hint to
+      // the error the model sees. Arguments are never rewritten — the
+      // model stays in the correction loop. Fail-open by design: a
+      // non-fumble error is returned untouched.
+      if (enrichToolError(event.tool, event.error, event.input)) {
+        vlog(`tool-arg-hint:fired tool=${event.tool} session=${event.sessionID}`)
+      }
     }
     if (event.tool === "question") {
       // Feed the answer text to purge approvals (team_cleanup confirm flow).