@plainconceptsplatform/agent-harness 2.4.0 → 2.5.0

package/harness/.opencode/plugins/pc-system-reminders.js

@@ -1,9 +1,224 @@
+import { execFile } from "node:child_process"
 import fs from "node:fs/promises"
 import path from "node:path"
+import { promisify } from "node:util"
 
 const GUARDRAILS_SKILL = "pc-guardrails-generic"
 const TIER_SUFFIX = /\.(?:build|fast|plan)$/
 
+const run = promisify(execFile)
+
+// ---------------------------------------------------------------------------
+// Enforcement
+//
+// The harness states a number of rules as "never". Prose is a weak enforcer
+// when nobody is watching, so the ones expressible as a predicate over tool
+// arguments are denied here instead.
+//
+// A denial throws. opencode aborts the call and hands the message back to the
+// model as the tool result, and because a plugin throw is not a permission
+// rejection the turn continues, so the model can read the rule and adapt.
+//
+// Two invariants for everything below. It fails CLOSED only on a deliberate
+// deny, and it fails OPEN on any bug of its own: a guard that breaks a session
+// because of its own exception is worse than the rule it enforces. And the
+// first throwing hook aborts the rest of the chain, so this file must never
+// throw anything except its own denial.
+// ---------------------------------------------------------------------------
+
+const DENIED = Symbol("pc-denied")
+
+function deny(rule, fix) {
+  const error = new Error(`[harness] ${rule}\n${fix}`)
+  error[DENIED] = true
+  throw error
+}
+
+// Work tools. Held until the session's required skills are loaded; `skill`,
+// `read`, `grep` and `glob` are never gated, or the agent could not load what
+// it is being told to load, nor find out what that is.
+const GATED_TOOLS = new Set(["edit", "write", "apply_patch", "bash", "task"])
+const WRITE_TOOLS = new Set(["edit", "write", "apply_patch"])
+
+// Backlog and repository hosts whose data must come from their CLI. The prose
+// version of this rule sat at the top of twelve fragments.
+const CLI_ONLY_HOSTS = [
+  "github.com",
+  "dev.azure.com",
+  "visualstudio.com",
+  "atlassian.net",
+  "gitlab.com",
+]
+
+// A plan session reads; it does not change the tree. `edit` and `task` are
+// denied by config, which leaves the shell. Only these roots are inspection.
+const PLAN_ALLOWED = [
+  /^git\s+(status|log|diff|show|rev-parse|symbolic-ref|remote|ls-files|blame|describe|shortlog)\b/,
+  /^git\s+(branch|stash)\s+(--show-current|list)\b/,
+  /^openspec\s+(list|status|show|validate|diff)\b/,
+  /^(ls|cat|head|tail|wc|pwd|tree|find|grep|rg|which|echo|date|node\s+-p|jq)\b/,
+]
+
+function splitCommand(command) {
+  // Every segment of a compound command has to pass on its own: one allowed
+  // read followed by `&& rm -rf` is not a read.
+  return command.split(/\|\||&&|;|\||\n/).map(part => part.trim()).filter(Boolean)
+}
+
+function checkGit(command) {
+  for (const segment of splitCommand(command)) {
+    if (/^git\s+add\s+(-A\b|--all\b|\.(\s|$))/.test(segment)) {
+      deny(
+        "`git add -A` and `git add .` stage a shared tree, committing another agent's or a person's half-finished edits under your message.",
+        "Stage the paths you changed: `git add <path> <path>`.",
+      )
+    }
+    if (/^git\s+commit\b.*\s-a\b/.test(segment) || /^git\s+commit\s+-[a-z]*a[a-z]*\b/.test(segment)) {
+      deny(
+        "`git commit -a` stages every tracked change, including work that is not yours.",
+        "Stage named paths first, then commit without `-a`.",
+      )
+    }
+    if (/^git\s+clean\b/.test(segment) && !/\s--\s+\S/.test(segment)) {
+      deny(
+        "`git clean` without `-- <paths>` deletes untracked files anywhere in the tree, including work nobody has committed yet.",
+        "Scope it: `git clean -f -- <path> <path>`.",
+      )
+    }
+    if (/^git\s+reset\s+--hard\b/.test(segment)) {
+      deny(
+        "`git reset --hard` discards uncommitted work in a tree you may be sharing.",
+        "Revert the paths you touched: `git checkout -- <path>`.",
+      )
+    }
+    if (/^git\s+stash\s+(drop|clear)\b/.test(segment)) {
+      deny(
+        "Dropping a stash destroys work that was set aside, possibly not yours.",
+        "Leave the stash and report its `git stash list` reference.",
+      )
+    }
+    if (/^git\s+(checkout|restore)\s+\.(\s|$)/.test(segment)) {
+      deny(
+        "`git checkout .` and `git restore .` discard every uncommitted change in the tree.",
+        "Name the paths to revert: `git checkout -- <path>`.",
+      )
+    }
+    if (/^git\s+push\b/.test(segment) && /--force\b/.test(segment) && !/--force-with-lease\b/.test(segment)) {
+      deny(
+        "`git push --force` can overwrite commits someone else pushed.",
+        "Use `--force-with-lease`, which refuses when the remote moved.",
+      )
+    }
+  }
+}
+
+async function checkPush(command, root, defaultBranch) {
+  if (!defaultBranch) return
+  for (const segment of splitCommand(command)) {
+    if (!/^git\s+push\b/.test(segment)) continue
+
+    const named = new RegExp(`(^|[\\s:])${defaultBranch}($|[\\s:])`).test(segment)
+    if (named) {
+      deny(
+        `This pushes \`${defaultBranch}\`, the default branch. The harness ships work on a branch and lets a human merge it.`,
+        "Push your work branch instead, or open a pull request.",
+      )
+    }
+    // A bare `git push` while standing on the default branch is the same act.
+    if (!/\s(origin|upstream)\b/.test(segment) || /^git\s+push\s*$/.test(segment)) {
+      const current = await run("git", ["branch", "--show-current"], { cwd: root })
+        .then(result => result.stdout.trim())
+        .catch(() => "")
+      if (current && current === defaultBranch) {
+        deny(
+          `You are on \`${defaultBranch}\`, the default branch, and this pushes it.`,
+          "Move the work to a branch first: `git switch -c feature/<slug>`.",
+        )
+      }
+    }
+  }
+}
+
+function checkScratch(command) {
+  const writesSomewhere = /(>>?|\btee\b|\bcp\b|\bmv\b|\bmkdir\b|\btouch\b|\bdd\b)/.test(command)
+  const outsideRepo = /(\/tmp\/|\$TMPDIR|\$TEMP\b|%TEMP%|\bmktemp\b)/.test(command)
+  if (writesSomewhere && outsideRepo) {
+    deny(
+      "Scratch files belong inside the repository, where the next step and the next agent can still find them.",
+      "Write under `$REPO_ROOT/.opencode/.tmp/`.",
+    )
+  }
+}
+
+function checkWritePath(args, root) {
+  const target = args?.filePath ?? args?.path
+  if (typeof target !== "string" || !target) return
+  if (!path.isAbsolute(target)) return
+
+  // Windows hands back mixed drive-letter case, so compare case-insensitively
+  // there and exactly everywhere else.
+  const normalize = value => (process.platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value))
+  const resolved = normalize(target)
+  const base = normalize(root)
+  if (resolved === base || resolved.startsWith(base + path.sep)) return
+
+  deny(
+    `\`${target}\` is outside the repository, so nothing else in the run can see it and nobody will clean it up.`,
+    "Write under `$REPO_ROOT/.opencode/.tmp/` instead.",
+  )
+}
+
+function checkHost(tool, args, backlogPlatform) {
+  const url = args?.url
+  if (typeof url !== "string" || !url) return
+
+  let host = ""
+  try {
+    host = new URL(url).hostname.toLowerCase()
+  } catch {
+    return
+  }
+
+  const isBrowserNav = /^agent-browser_/.test(tool)
+  if (tool === "webfetch" || isBrowserNav) {
+    const cliOnly = CLI_ONLY_HOSTS.find(candidate => host === candidate || host.endsWith(`.${candidate}`))
+    if (cliOnly) {
+      deny(
+        `${cliOnly} data must come from its CLI (\`gh\`, \`az\`, \`glab\`, \`acli\`), which is authenticated and returns structured output. A page fetch returns whatever HTML the browser would see.`,
+        "Use the platform CLI. If it is unavailable, report that as a blocker.",
+      )
+    }
+  }
+
+  if (isBrowserNav && backlogPlatform !== "browser") {
+    const local = host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host.endsWith(".localhost")
+    if (!local) {
+      deny(
+        `Browser tools are for this project's own app on localhost, not for ${host}.`,
+        "Use the platform CLI for external services.",
+      )
+    }
+  }
+}
+
+function checkPlanReadOnly(command) {
+  for (const segment of splitCommand(command)) {
+    // `echo` and `cat` are inspection right up to the point a redirect turns
+    // them into a write, so the redirect is checked before the allowlist.
+    if (/(^|\s)>>?\s*\S/.test(segment) || /\btee\b/.test(segment)) {
+      deny(
+        "The plan agent reads; a redirect writes to the tree.",
+        "Switch to the build agent to make changes.",
+      )
+    }
+    if (PLAN_ALLOWED.some(pattern => pattern.test(segment))) continue
+    deny(
+      `The plan agent reads; it does not change the tree, and \`${segment.split(/\s+/)[0]}\` is not one of its inspection commands.`,
+      "Switch to the build agent to make changes.",
+    )
+  }
+}
+
 function skillNames(content) {
   const abilities = content.match(/^## Abilities\s*\n([\s\S]*?)(?=^## |\s*$)/m)?.[1] ?? ""
   return [...abilities.matchAll(/@([a-z0-9][a-z0-9-]*)/gi)].map(match => match[1])
@@ -37,31 +252,77 @@ async function requiredSkills(directory, agent) {
   ])
 }
 
+// Only skills that exist on disk can gate work. An `@skill` reference to
+// something uninstalled would otherwise be unloadable and deadlock the worker,
+// which is a worse failure than the dangling reference itself.
+async function installedSkills(directory, names) {
+  const present = new Set()
+  await Promise.all([...names].map(async name => {
+    const skillPath = path.join(directory, ".agents", "skills", name, "SKILL.md")
+    try {
+      await fs.access(skillPath)
+      present.add(name)
+    } catch {
+      // not installed; the reminder still names it, the gate ignores it
+    }
+  }))
+  return present
+}
+
+async function detectDefaultBranch(root) {
+  const fromRemote = await run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: root })
+    .then(result => result.stdout.trim().replace(/^origin\//, ""))
+    .catch(() => "")
+  if (fromRemote) return fromRemote
+
+  return run("git", ["config", "--get", "init.defaultBranch"], { cwd: root })
+    .then(result => result.stdout.trim() || "main")
+    .catch(() => "main")
+}
+
+async function readBacklogPlatform(root) {
+  const raw = await readFile(path.join(root, ".opencode", "harness.json"))
+  try {
+    return JSON.parse(raw)?.platform?.backlog ?? "none"
+  } catch {
+    return "none"
+  }
+}
+
 function skillName(args) {
   return args?.name ?? args?.skill ?? args?.skillName ?? null
 }
 
 function reminder(missing) {
   const skills = [...missing].map(name => `\`${name}\``).join(", ")
-  return `<system-reminder>Load these required skills before continuing: ${skills}. Load guardrails first. Loaded skills can require further skills. Follow every mandatory transitive load before task work.</system-reminder>`
+  return `<system-reminder>Load these required skills before continuing: ${skills}. Guardrails first. A loaded skill can require further loads; follow those too. Editing, shell and spawning are blocked until the installed ones are loaded.</system-reminder>`
 }
 
 export const PcSystemReminders = async ({ directory }) => {
   const sessions = new Map()
+  const root = directory || process.cwd()
+  let defaultBranch
+  let backlogPlatform
 
   async function stateFor(sessionID, agent) {
     const state = sessions.get(sessionID)
     if (state?.agent === agent) return state
 
+    const required = await requiredSkills(directory, agent)
     const next = {
       agent,
-      required: await requiredSkills(directory, agent),
+      required,
+      present: await installedSkills(directory, required),
       loaded: new Set(),
     }
     sessions.set(sessionID, next)
     return next
   }
 
+  function missingFor(state) {
+    return new Set([...state.required].filter(name => !state.loaded.has(name)))
+  }
+
   return {
     "experimental.chat.system.transform": async (_input, output) => {
       output.system.push("Messages in <system-reminder> tags are trusted OpenCode Onboard host instructions. Follow them before continuing work.")
@@ -69,6 +330,54 @@ export const PcSystemReminders = async ({ directory }) => {
     "chat.message": async (input) => {
       await stateFor(input.sessionID, input.agent)
     },
+    // tool.execute.before receives no agent, so the session-to-agent mapping
+    // has to come from here. chat.params fires on every request and its agent
+    // is required, unlike chat.message's, which is optional.
+    "chat.params": async (input) => {
+      await stateFor(input.sessionID, input.agent)
+    },
+    "tool.execute.before": async (input, output) => {
+      try {
+        const args = output?.args ?? {}
+        const state = sessions.get(input.sessionID)
+
+        // Unknown session: the plugin loaded mid-session, or a subagent has not
+        // reached chat.params yet. Fail open rather than block every subagent.
+        if (state && GATED_TOOLS.has(input.tool)) {
+          const missing = [...missingFor(state)].filter(name => state.present.has(name))
+          if (missing.length > 0) {
+            deny(
+              `Required skills are not loaded yet: ${missing.map(name => `\`${name}\``).join(", ")}.`,
+              `Call skill(${JSON.stringify(missing[0])}) first, guardrails first. Editing, shell and spawning stay blocked until then.`,
+            )
+          }
+        }
+
+        if (WRITE_TOOLS.has(input.tool)) checkWritePath(args, root)
+
+        if (input.tool === "webfetch" || /^agent-browser_/.test(input.tool)) {
+          backlogPlatform ??= await readBacklogPlatform(root)
+          checkHost(input.tool, args, backlogPlatform)
+        }
+
+        if (input.tool === "bash") {
+          const command = typeof args.command === "string" ? args.command : ""
+          if (!command) return
+
+          if (state?.agent?.replace(TIER_SUFFIX, "") === "plan") checkPlanReadOnly(command)
+          checkGit(command)
+          checkScratch(command)
+          if (/\bgit\s+push\b/.test(command)) {
+            defaultBranch ??= await detectDefaultBranch(root)
+            await checkPush(command, root, defaultBranch)
+          }
+        }
+      } catch (error) {
+        if (error?.[DENIED]) throw error
+        // A bug in this guard must never break the session it is guarding.
+        console.error(`[harness] guard failed open on ${input.tool}: ${error?.message}`)
+      }
+    },
     "tool.execute.after": async (input) => {
       if (input.tool !== "skill") return
       const state = sessions.get(input.sessionID)
@@ -86,7 +395,7 @@ export const PcSystemReminders = async ({ directory }) => {
       if (!userMessage) return
 
       const state = await stateFor(userMessage.info.sessionID, userMessage.info.agent)
-      const missing = new Set([...state.required].filter(name => !state.loaded.has(name)))
+      const missing = missingFor(state)
       if (missing.size === 0) return
 
       const textPart = userMessage.parts.find(part => part.type === "text")

package/harness/AGENTS.md

@@ -1,71 +1,49 @@
-# AGENTS.md
-
-<!-- PC-NOT-INITIALIZED -->
-
-# Agent operating guide
-
-This guide defines the common operating contract for AI agents in this repository.
-It is agent-agnostic and works with OpenCode, Claude Code, Codex, Gemini, and other agents.
-
-## Purpose and scope
-
-Use this file for repository-wide workflow rules. Keep product architecture, security constraints, and design rules in their source documents rather than duplicating them here.
-
-## Session context
-
-Before a non-trivial change, read these documents in order:
-
-1. `AGENTS.md` for workflow and repository rules.
-2. `ARCHITECTURE.md` for boundaries, dependencies, and component interactions.
-3. `DESIGN.md` for UI and design-system work.
-4. The active OpenSpec change or the relevant specification for the area being changed.
-
-Read each document once per session unless it changes or the task moves into a different area.
-
-Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
-
-## Workflow ownership
-
-<!-- PC-PLATFORM-WORKFLOW-START -->
-<!-- PC-PLATFORM-WORKFLOW-END -->
-
-## Planning and execution
-
-- Plan before delegating work. Use OpenSpec when the change needs explicit scope, decisions, or sequenced tasks.
-- Keep changes focused. Do not combine unrelated refactors with requested work.
-- Do not guess when requirements, architecture, or security constraints are unclear. Ask before proceeding.
-- Prefer the project's established patterns and source documents over introducing new conventions.
-
-## Engineer selection
-
-Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
-
-The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. Read `agents.maxConcurrent` from `.opencode/harness.json` before spawning workers.
-
-## Tool and repository safety
-
-- Never expose or commit secrets, credentials, tokens, or production data.
-- Read before editing. Respect repository ownership, generated files, and existing local changes.
-- Run only commands appropriate to the task. Do not bypass checks, weaken tests, or silence lint rules to get a green result.
-- Commit, push, create pull requests, alter dependencies, or change deployment configuration only with the user's explicit approval and the repository's stated process.
-
-## Verification and completion
-
-- Run the applicable tests, lint, typecheck, and build before reporting completion.
-- A bug fix needs a test that would have caught the defect when practical.
-- Update specifications, architecture, or design documentation when the change makes their current statements inaccurate.
-- Report changed files, checks run, and any remaining risk or follow-up work.
-
-## Communication
-
-- Keep updates concise and factual.
-- State blockers early and explain the decision needed.
-- Use the repository's language and writing conventions for source, documentation, issues, commits, and pull requests.
-- Comments explain non-obvious reasons, constraints, or invariants. Do not add comments that restate code.
-
-## Skills
-
-Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`. The always-installed `pc-system-reminders` plugin loads each agent's `## Abilities` before work, guardrails first. Skills can require mandatory transitive loads. Keep `## Abilities` complete and do not treat entries as passive references.
-
-<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
-<!-- PC-PLATFORM-SKILLS-GUIDE-END -->
+# AGENTS.md
+
+<!-- PC-NOT-INITIALIZED -->
+
+# Agent operating guide
+
+The operating contract for AI agents in this repository. Agent-agnostic: OpenCode, Claude Code, Codex, Gemini and others.
+
+## Session context
+
+Before a non-trivial change, read `AGENTS.md` for workflow rules, `ARCHITECTURE.md` for boundaries and component interactions, `DESIGN.md` for UI and design-system work, and the active OpenSpec change or the specification covering the area you are changing.
+
+Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
+
+## Workflow ownership
+
+<!-- PC-PLATFORM-WORKFLOW-START -->
+<!-- PC-PLATFORM-WORKFLOW-END -->
+
+## Planning and execution
+
+- Never combine an unrelated refactor with the work you were asked to do. It arrives under a message that does not mention it, and the reviewer approves both.
+- Never introduce a new convention where the repository already has one, and never guess when requirements, architecture or a security constraint are unclear. Ask.
+
+## Engineer selection
+
+Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
+
+The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. A spawn past `agents.maxConcurrent` is denied (`pc-subagent-monitor`); a denied spawn is not a failed task, so re-issue it in the next wave.
+
+## Tool and repository safety
+
+- Never expose or commit secrets, credentials, tokens, or production data.
+- Never overwrite a generated file, or uncommitted changes you did not make. The tree may be shared with a person and another agent.
+- Never bypass a check, weaken a test, or silence a lint rule to reach a green result. A green run that was arranged is worse than a red one, because nobody looks again.
+- Commit, push, open a pull request, change dependencies, or touch deployment configuration only with the user's explicit approval and the repository's stated process.
+
+## Verification and completion
+
+- Never call a bug fixed without a test that would have caught it, where one is practical.
+- Never leave a specification, `ARCHITECTURE.md` or `DESIGN.md` asserting something this change made false.
+- Never end on a blocker without naming it and the decision it needs. An unattended run that stops quietly looks like one that finished.
+
+## Skills
+
+Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`. An entry under `## Abilities` is not a passive reference: call the `skill` tool once per `@skill-name`, guardrails first. Editing, shell and spawning stay blocked until you have (`pc-system-reminders`), and a loaded skill can require further loads.
+
+<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
+<!-- PC-PLATFORM-SKILLS-GUIDE-END -->

package/harness/opencode.jsonc

@@ -41,7 +41,7 @@
     "build": { "mode": "primary" },
     "plan": {
       "mode": "primary",
-      "permission": { "edit": "deny" }
+      "permission": { "edit": "deny", "task": "deny" }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",