@codeplane-ai/plugin 30.0.1 → 31.0.1

package/dist/example.d.ts

@@ -1,2 +1,7 @@
 import { Plugin } from "./index.js";
+/**
+ * Example plugin demonstrating the tool lifecycle hooks a plugin can use to
+ * extend Codeplane: registering tools, gating which tools the model sees,
+ * and observing/repairing tool failures.
+ */
 export declare const ExamplePlugin: Plugin;

package/dist/example.js

@@ -1,6 +1,12 @@
 import { tool } from "./tool.js";
+/**
+ * Example plugin demonstrating the tool lifecycle hooks a plugin can use to
+ * extend Codeplane: registering tools, gating which tools the model sees,
+ * and observing/repairing tool failures.
+ */
 export const ExamplePlugin = async (_ctx) => {
     return {
+        // Register a custom tool the model can call.
         tool: {
             mytool: tool({
                 description: "This is a custom tool",
@@ -12,5 +18,21 @@ export const ExamplePlugin = async (_ctx) => {
                 },
             }),
         },
+        // Gate which tools are exposed to the model. Here we enforce a read-only
+        // mode for a "reviewer" agent by hiding mutating tools.
+        "tool.list": async (input, output) => {
+            if (input.agent === "reviewer") {
+                const blocked = new Set(["write", "edit", "bash", "apply_patch"]);
+                output.tools = output.tools.filter((id) => !blocked.has(id));
+            }
+        },
+        // Observe tool failures and rewrite the message the model sees so it can
+        // recover instead of giving up.
+        "tool.execute.error": async (input, output) => {
+            console.error(`[example] tool ${input.tool} failed: ${output.error}`);
+            if (input.tool === "webfetch") {
+                output.output += "\n\nHint: the network may be offline — try `read` on a local file instead.";
+            }
+        },
     };
 };

package/dist/index.d.ts

@@ -251,6 +251,33 @@ export interface Hooks {
         output: string;
         metadata: any;
     }) => Promise<void>;
+    /**
+     * Called when a tool fails to execute. Fires for native tools, MCP tools,
+     * and the task/subagent tool, completing the tool lifecycle alongside
+     * `tool.execute.before` and `tool.execute.after`.
+     *
+     * Use it to observe failures (telemetry, metrics, retries) and to rewrite
+     * the text the model sees so it can recover gracefully instead of giving up.
+     *
+     * - `error`: the original error message (informational)
+     * - `output`: the failure text shown to the model. Mutate to customize.
+     * - `title`/`metadata`: tool-call title and metadata where available; mutate
+     *   to enrich the recorded tool call.
+     *
+     * Note: some tools (e.g. certain MCP tools) still produce output on failure,
+     * in which case `tool.execute.after` also fires after this hook.
+     */
+    "tool.execute.error"?: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+        args: any;
+    }, output: {
+        error: string;
+        output: string;
+        title?: string;
+        metadata?: Record<string, any>;
+    }) => Promise<void>;
     "experimental.chat.messages.transform"?: (input: {}, output: {
         messages: {
             info: Message;
@@ -309,4 +336,19 @@ export interface Hooks {
         description: string;
         parameters: any;
     }) => Promise<void>;
+    /**
+     * Called once per turn when the set of tools exposed to the model is
+     * assembled, after agent/session permission filtering. Lets plugins gate
+     * which tools the model can see and call — e.g. enforce a read-only mode,
+     * disable network tools, or restrict tools for a specific agent.
+     *
+     * - `agent`: the active agent name
+     * - `tools`: the available tool IDs. Mutate the array to add or remove
+     *   entries; removed tools are hidden from the model for this turn.
+     */
+    "tool.list"?: (input: {
+        agent: string;
+    }, output: {
+        tools: string[];
+    }) => Promise<void>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@codeplane-ai/plugin",
-  "version": "30.0.1",
+  "version": "31.0.1",
   "type": "module",
   "license": "MIT",
   "repository": {