pullfrog 0.1.14 → 0.1.16

package/README.md

@@ -14,7 +14,7 @@
 
 <br/>
 
-> **🚀 Pullfrog is in beta!** We're onboarding users in waves. [Get on the waitlist →](https://pullfrog.com/join-waitlist)
+> **🚀 Pullfrog is now generally available!** [Get started →](https://pullfrog.com/console)
 
 <br/>
 

package/dist/agents/claude.d.ts

@@ -2,6 +2,7 @@ import type { TodoTracker } from "../utils/todoTracking.ts";
 import { type AgentResult } from "./shared.ts";
 type RunParams = {
     label: string;
+    cmd: string;
     args: string[];
     cwd: string;
     env: Record<string, string | undefined>;

package/dist/agents/claudePretoolGate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Claude Code `PreToolUse` hook source — written into `ctx.tmpdir` at runtime
+ * and registered via a tmpdir-scoped `settings.json` referenced by
+ * `--settings <path>` (see action/agents/claude.ts).
+ *
+ * Closes the subagent → state-mutating MCP tool path that motivated the
+ * 2026-05-18 zed-industries/cloud incident (`reviewfrog` lens called
+ * `checkout_pr` mid-review and the orchestrator's next push clobbered an
+ * unrelated branch). Pairs with the `tool.execute.before` hook in
+ * action/agents/opencodePlugin.ts; both runtimes share the deny list at
+ * action/agents/subagentToolGates.ts.
+ *
+ * PreToolUse hook contract (verified against yasasbanukaofficial/claude-code
+ * `src/utils/hooks/hooksConfigManager.ts` and `src/utils/hooks.ts`):
+ *   - stdin: JSON with `hook_event_name: "PreToolUse"`, `tool_name`,
+ *     `tool_input`, `tool_use_id`, `session_id`, `cwd`, `transcript_path`,
+ *     and crucially `agent_id` / `agent_type` populated when the call
+ *     originates from a subagent (set by the SDK when a Task/Agent
+ *     dispatches a tool — see `createBaseHookInput` in claude-code source).
+ *   - exit 0 → allow, no output shown
+ *   - exit 2 → block tool call AND show stderr to model (this is the path
+ *     we want for the deny case — the subagent gets a clear refusal it can
+ *     reason about and pick a different action)
+ *   - other → show stderr to user only, continue with tool call
+ *
+ * The hook itself is intentionally tiny: stdin → JSON → check `agent_id`
+ * presence + `tool_name` against the deny list → exit 0 or 2. No deps.
+ *
+ * Why the script source is a string template, not a separate `.ts` file
+ * shipped with the action: the action runs as a published npm package; at
+ * install time we don't have the source on disk in a stable place. Embedding
+ * the source into `dist/main.mjs` and writing it out per-run keeps the path
+ * inside `ctx.tmpdir` (where `--settings` can find it) and survives bundle
+ * minification.
+ */
+/**
+ * Source written to `<ctx.tmpdir>/pullfrog-pretool-gate.mjs`. Plain ESM,
+ * no TypeScript, no dependencies — node executes it directly via the
+ * `#!/usr/bin/env node` shebang and the executable bit set by the harness.
+ */
+export declare const CLAUDE_PRETOOL_GATE_FILENAME: "pullfrog-pretool-gate.mjs";
+export declare const CLAUDE_PRETOOL_GATE_SOURCE: string;
+/**
+ * Settings JSON shape registered via `claude --settings <path>`. The
+ * matcher `^mcp__pullfrog__` is treated as a regex by claude-code's
+ * `matchesPattern` helper (anything outside `[a-zA-Z0-9_|]` triggers the
+ * regex branch — verified in src/utils/hooks.ts), so this anchors at the
+ * start of the tool name and fires for every Pullfrog MCP tool. We narrow
+ * inside the script itself rather than declaring per-tool matchers because
+ * the deny list is the source of truth.
+ *
+ * The hook process inherits the parent's PATH, so `node` resolves to the
+ * runner's node binary; the `--settings` flag accepts either a path or a
+ * literal JSON string per claude-code source `src/main.tsx` (`Path to a
+ * settings JSON file or a JSON string`), but we use a path so the script
+ * and its config sit side-by-side under `ctx.tmpdir`.
+ */
+export declare function buildClaudePretoolGateSettings(scriptAbsolutePath: string): {
+    hooks: {
+        PreToolUse: Array<{
+            matcher: string;
+            hooks: Array<{
+                type: "command";
+                command: string;
+                timeout?: number;
+            }>;
+        }>;
+    };
+};

package/dist/agents/gateServer.d.ts

@@ -0,0 +1,6 @@
+import { type AgentRunContext } from "./shared.ts";
+export interface GateServerHandle {
+    url: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}
+export declare function startGateServer(ctx: AgentRunContext): Promise<GateServerHandle>;

package/dist/agents/nativeFsDenies.d.ts

@@ -0,0 +1,28 @@
+/** worktree-relative blanket WRITE deny for the entire `.git` tree, in
+ * OpenCode Wildcard dialect (`*` compiles to regex `.*`, matching `/`
+ * recursively — see packages/core/src/util/wildcard.ts). spread into the
+ * `edit` ruleset after a `"*": "allow"` baseline — `evaluate` is
+ * last-match-wins by key order, so the deny keys must follow the wildcard
+ * allow.
+ *
+ * four patterns, because the root-anchored descendants glob only matches
+ * paths under a root `.git` *directory* — it misses `.git` when it's a gitfile
+ * (worktree / submodule layouts: a regular file whose `gitdir:` line redirects
+ * git metadata) and misses nested gitfiles (a `.git` inside a subdirectory).
+ * rewriting either pointer is the same code-exec surface (`core.hooksPath`,
+ * clean/smudge filters, credential.helper) the blanket deny exists to seal, so
+ * we cover the gitfile itself and any nested `.git` too. */
+export declare const GIT_NATIVE_WRITE_DENY_OPENCODE: Record<string, "deny">;
+/** worktree-relative narrow READ deny (`.git/config` only), in OpenCode
+ * Wildcard dialect. spread into the `read` ruleset after the `"*": "allow"`
+ * baseline. */
+export declare const GIT_NATIVE_READ_DENY_OPENCODE: Record<string, "deny">;
+/** Claude `permissions.deny` entries for the blanket `.git` WRITE deny —
+ * mirrors {@link GIT_NATIVE_WRITE_DENY_OPENCODE}. `**` is recursive. the exact
+ * `.git` entry plus the recursive-prefix gitfile entry cover the gitfile
+ * pointer (root + nested) that the root-anchored descendants glob alone misses;
+ * the recursive-prefix descendants entry covers nested gitdirs. */
+export declare const GIT_NATIVE_WRITE_DENY_CLAUDE: string[];
+/** Claude `permissions.deny` entries for the narrow `.git/config` READ deny,
+ * one per read/enumerate tool — mirrors {@link GIT_NATIVE_READ_DENY_OPENCODE}. */
+export declare const GIT_NATIVE_READ_DENY_CLAUDE: string[];

package/dist/agents/opencodePlugin.d.ts

@@ -15,22 +15,33 @@
  * XDG_CONFIG_HOME is so harness-side files (config, plugins, scratch state)
  * land in the tmpdir.
  *
- * Why this plugin exists: opencode's `task` tool runs subagents in-process and
- * the CLI's `cli/cmd/run.ts` event loop filters `part.sessionID !== sessionID`,
- * so subagent-internal `message.part.updated` events are silently discarded
- * before reaching our parent NDJSON stream. plugins, by contrast, receive
- * EVERY bus event via `bus.subscribeAll()` regardless of session.
- *
- * The plugin re-emits every relevant bus event onto opencode's stdout as a
- * single JSON line wrapped in a sentinel envelope. our `runOpenCode` parser
- * recognises the envelope, unpacks it, and routes the inner part through the
- * existing handlers with a per-session label from `SessionLabeler` so each
- * subagent's tool calls / text appear inline alongside the orchestrator's.
- *
- * Dumb plugin / smart parent split: the plugin emits every part for every
- * session. the parent dedupes against the orchestrator's own session id (which
- * it already knows from the `init` event). this keeps the plugin trivial and
- * keeps the per-session attribution logic on the parent side where the
+ * Why the events plugin exists: opencode's `task` tool runs subagents
+ * in-process and the CLI's `cli/cmd/run.ts` event loop filters
+ * `part.sessionID !== sessionID`, so subagent-internal `message.part.updated`
+ * events are silently discarded before reaching our parent NDJSON stream.
+ * plugins, by contrast, receive EVERY bus event via `bus.subscribeAll()`
+ * regardless of session.
+ *
+ * The events plugin re-emits every relevant bus event onto opencode's stdout
+ * as a single JSON line wrapped in a sentinel envelope. our `runOpenCode`
+ * parser recognises the envelope, unpacks it, and routes the inner part
+ * through the existing handlers with a per-session label from `SessionLabeler`
+ * so each subagent's tool calls / text appear inline alongside the
+ * orchestrator's.
+ *
+ * The subagent gate (the `tool.execute.before` hook that hard-blocks
+ * state-mutating MCP tool calls from a subagent session) lives in a SEPARATE
+ * plugin — `PULLFROG_OPENCODE_GATE_PLUGIN_SOURCE` below — because it's the
+ * load-bearing security fence and must ship into both opencode harnesses,
+ * whereas this events re-emitter is only needed by the legacy `opencode.ts`
+ * CLI-parsing path (the active `opencode_v2.ts` reads subagent events directly
+ * off the SDK event stream, so it installs ONLY the gate plugin). Deny-list
+ * source of truth: `action/agents/subagentToolGates.ts`.
+ *
+ * Dumb plugin / smart parent split: the events plugin emits every part for
+ * every session. the parent dedupes against the orchestrator's own session id
+ * (which it already knows from the `init` event). this keeps the plugin trivial
+ * and keeps the per-session attribution logic on the parent side where the
  * SessionLabeler already lives.
  *
  * Event-name prefixing: the wrapped event-type sentinel is
@@ -39,6 +50,7 @@
  */
 export declare const PULLFROG_BUS_EVENT_TYPE: "pullfrog_bus_event";
 export declare const PULLFROG_OPENCODE_PLUGIN_FILENAME: "pullfrog-events.ts";
+export declare const PULLFROG_OPENCODE_GATE_PLUGIN_FILENAME: "pullfrog-subagent-gate.ts";
 /**
  * Source written verbatim to `<XDG_CONFIG_HOME>/opencode/plugin/pullfrog-events.ts`.
  *
@@ -58,3 +70,16 @@ export declare const PULLFROG_OPENCODE_PLUGIN_FILENAME: "pullfrog-events.ts";
  *   missed event, not a crash.
  */
 export declare const PULLFROG_OPENCODE_PLUGIN_SOURCE: string;
+/**
+ * Standalone subagent gate plugin written to
+ * `<XDG_CONFIG_HOME>/opencode/plugin/pullfrog-subagent-gate.ts`. Installed by
+ * BOTH opencode harnesses (the legacy `opencode.ts` and the active in-process
+ * `opencode_v2.ts`) — the gate is the load-bearing security fence, so it ships
+ * independently of the events re-emitter above (which v2 doesn't need).
+ *
+ * Hard-blocks state-mutating MCP tool calls originating from a subagent
+ * session via `tool.execute.before`, complementing the runtime backstops from
+ * PR #796 (action/mcp/checkout.ts, action/mcp/git.ts). Deny-list source of
+ * truth: `action/agents/subagentToolGates.ts`.
+ */
+export declare const PULLFROG_OPENCODE_GATE_PLUGIN_SOURCE: string;

package/dist/agents/opencodeShared.d.ts

@@ -37,4 +37,4 @@ export declare function buildReviewerAgentConfig(orchestratorModel: string | und
 export declare function installOpencodeCli(params: {
     binPath: string;
 }): Promise<string>;
-export declare function autoSelectModel(cliPath: string): string | undefined;
+export declare function autoSelectModel(): string | undefined;

package/dist/agents/postRun.d.ts

@@ -54,6 +54,19 @@ export declare function collectPostRunIssues(ctx: AgentRunContext, options?: {
     skipSummaryStale?: boolean;
 }): Promise<PostRunIssues>;
 export declare function buildPostRunPrompt(issues: PostRunIssues): string;
+/**
+ * terminal-only post-run finalize: re-checks the hard-fail gates after the
+ * agent has exited and converts a successful result to a hard-fail when
+ * `stopHook` or `unsubmittedReview` is still failing. used by harnesses
+ * that inject follow-up turns via a mechanism other than the resume
+ * callback (e.g. the Claude managed Stop hook + gate server). soft gates
+ * (`dirtyTree`, `summaryStale`) are intentionally not re-checked here —
+ * they never flip a successful run to failed.
+ */
+export declare function finalizeAgentResult<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
+    result: R;
+}): Promise<R>;
 export declare function shouldRunReflection(mode: string | undefined): boolean;
 /**
  * prompt for a dedicated post-run reflection turn nudging the agent to edit

package/dist/agents/reviewer.d.ts

@@ -7,20 +7,26 @@
  *   allow: file reads, grep/glob, web search/fetch, read-only MCP queries
  *   deny:  state-changing MCP tools, file writes, shell, nested subagent dispatch
  *
- * Enforcement is prose-only. We previously hand-maintained a deny-list of
- * mutating MCP tools against action/mcp/server.ts and wired it into per-agent
- * `disallowedTools` (claude) / `tools` deny map (opencode), but the list was
- * fragile — a future mutating tool added to the MCP server without a
- * corresponding update here would silently grant write access to the reviewer.
- * Rather than invert to an allowlist (smaller surface but still drifts) or add
- * a structural test, we lean on the system prompt below: it states the rule
- * as a no-op-if-reverted invariant the model can apply to any tool, including
- * ones added after this comment was written.
+ * Enforcement is now belt-and-suspenders:
+ *   1. Machine-enforced PreToolUse gates intercept every state-mutating MCP
+ *      tool call originating from a subagent session and refuse it before
+ *      MCP runs. See action/agents/subagentToolGates.ts (the deny list),
+ *      action/agents/claudePretoolGate.ts (Claude Code's PreToolUse hook),
+ *      and action/agents/opencodePlugin.ts (opencode's tool.execute.before
+ *      hook). Followed PR #796 which added runtime backstops inside
+ *      checkout_pr / push_branch after a subagent-originated tool call
+ *      clobbered an unrelated PR branch in zed-industries/cloud.
+ *   2. The prose system prompt below as a backup against (a) tools added
+ *      to the MCP server without a corresponding deny-list update, and
+ *      (b) shell/git read-vs-write distinctions the static gate can't see.
+ *      It states the rule as a no-op-if-reverted invariant the model can
+ *      apply to any tool, including ones added after this comment was
+ *      written.
  *
- * Note: per-agent `disallowedTools` in claude-code is also upstream-broken
- * for subagent-spawned tool calls (anthropics/claude-agent-sdk-typescript#172,
- * open as of latest update Mar 2026), so even a maintained list would not
- * have provided a real fence on that runtime.
+ * Historical note: per-agent `disallowedTools` in claude-code is upstream-
+ * broken for subagent-spawned tool calls (anthropics/claude-agent-sdk-
+ * typescript#172, open as of Mar 2026), which is why the gate runs at
+ * PreToolUse rather than tool-registration time.
  */
 export declare const REVIEWER_AGENT_NAME = "reviewfrog";
 /**

package/dist/agents/subagentToolGates.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Single source of truth for MCP tools subagents are forbidden from calling.
+ *
+ * Subagents share the orchestrator's in-process git working tree, `toolState`,
+ * progress comment, and run-scoped pr/branch context. A subagent that calls
+ * `checkout_pr` switches the orchestrator's HEAD; one that calls `push_branch`
+ * pushes whatever the orchestrator happens to have committed. The 2026-05-18
+ * `zed-industries/cloud` incident hit exactly this: a `reviewfrog` lens
+ * dispatched `checkout_pr({2582})` mid-review, the orchestrator's next push
+ * clobbered an unrelated engineer's branch. PR #796 added runtime backstops
+ * inside `checkout_pr`/`push_branch`; this list is the upstream gate that
+ * stops the call from ever reaching MCP when it originates from a subagent.
+ *
+ * The gate is enforced at two pre-tool hooks:
+ *   - opencode: `tool.execute.before` (action/agents/opencodePlugin.ts)
+ *   - claude:   `PreToolUse` settings hook (action/agents/claudePretoolGate.ts)
+ *
+ * Names are stored in their canonical bare form (the FastMCP tool `name`
+ * field). Each runtime presents them with a different prefix:
+ *   - claude:   `mcp__pullfrog__<name>`
+ *   - opencode: `pullfrog_<name>`
+ * The hooks strip those prefixes before comparing.
+ *
+ * Read-only MCP tools (`get_*`, `list_*`, `git_fetch`, `get_check_suite_logs`,
+ * `await_dependency_installation`, etc.) and the `git`/`shell` tools stay off
+ * this list — denying them would make review work impossible. The reviewer system prompt
+ * (`action/agents/reviewer.ts`) already forbids state-changing shell/git
+ * subcommands as a prose constraint; this list is the belt-and-suspenders
+ * machine fence for the high-stakes mutations we can identify by name alone.
+ *
+ * When adding a state-changing MCP tool to `action/mcp/server.ts`, add its
+ * canonical name here too. Inclusions justified inline.
+ */
+export declare const SUBAGENT_DENIED_TOOLS: readonly ["checkout_pr", "push_branch", "push_tags", "delete_branch", "create_pull_request", "update_pull_request_body", "create_issue", "create_issue_comment", "edit_issue_comment", "reply_to_review_comment", "create_pull_request_review", "resolve_review_thread", "add_labels", "set_output", "report_progress", "select_mode", "start_dependency_installation", "kill_background", "upload_file"];
+export type SubagentDeniedTool = (typeof SUBAGENT_DENIED_TOOLS)[number];
+/**
+ * Strip the runtime-specific MCP prefix from a tool name and return the
+ * canonical bare name (matching FastMCP's `name:` field). Returns the input
+ * unchanged if it doesn't carry a known prefix — keeping comparison simple
+ * for native (non-MCP) tools, which never appear on the deny list anyway.
+ */
+export declare function stripMcpPrefix(toolName: string): string;
+/**
+ * Whether `toolName` (in any runtime's prefix style) names a tool that
+ * subagents must not call.
+ */
+export declare function isSubagentDeniedTool(toolName: string): boolean;
+/**
+ * Human-readable refusal surfaced to the model when a denied tool is gated.
+ * Phrased so a halfway-attentive subagent realises (a) the tool is denied to
+ * it specifically, (b) why (shared in-process state with the orchestrator),
+ * and (c) what to do instead (report findings; the orchestrator can call the
+ * tool directly).
+ */
+export declare function buildSubagentDenyMessage(toolName: string): string;