feat: disable plugin completely when WORKFLOWS=off

When WORKFLOWS=off, the plugin now returns an empty hooks object instead of loading tools and hooks. This ensures the plugin is completely disabled at initialization time rather than just skipping hook execution.

Also removes the command.execute.before hook that was used for runtime toggling, since WORKFLOWS is now a startup-only configuration.

Includes tests verifying that:
- WORKFLOWS=off returns empty hooks object
- WORKFLOWS not set or any other value loads all hooks

Author: mrsimpson

packages/opencode-plugin/src/plugin.ts

@@ -12,7 +12,7 @@
  * Logs are sent via OpenCode SDK's client.app.log() API
  */
 
-import type { Plugin, PluginInput, Hooks } from './types.js';
+import type { Plugin, PluginInput, Hooks, ToolDefinition } from './types.js';
 import { createProceedToPhaseTool } from './tool-handlers/proceed-to-phase.js';
 import { createConductReviewTool } from './tool-handlers/conduct-review.js';
 import { createResetDevelopmentTool } from './tool-handlers/reset-development.js';
@@ -492,52 +492,43 @@ ACTION REQUIRED: Use transition_phase tool to move to a phase that allows editin
     },
 
     /**
-     * Custom tools - matching MCP server tool names for consistency
+     * Custom tools - always registered so /workflow on can re-enable them mid-session.
+     * Each tool's execute method checks workflowsEnabled at call time and throws a
+     * clear message when disabled, rather than silently failing.
      */
-    tool: {
-      /**
-       * Tool: start_development
-       * Starts a new development workflow in the current project
-       */
-      start_development: createStartDevelopmentTool(
-        input.directory,
-        getServerContext,
-        setBufferedInstructions
-      ),
-
-      /**
-       * Tool: proceed_to_phase
-       * Transitions to a new workflow phase
-       */
-      proceed_to_phase: createProceedToPhaseTool(
-        getServerContext,
-        setBufferedInstructions
-      ),
-
-      /**
-       * Tool: conduct_review
-       * Conducts a review before phase transition
-       */
-      conduct_review: createConductReviewTool(getServerContext),
-
-      /**
-       * Tool: reset_development
-       * Resets the current workflow and starts fresh
-       */
-      reset_development: createResetDevelopmentTool(
-        input.directory,
-        getServerContext
-      ),
-
-      /**
-       * Tool: setup_project_docs
-       * Creates project documentation artifacts
-       */
-      setup_project_docs: await createSetupProjectDocsTool(
-        input.directory,
-        getServerContext
-      ),
-    },
+    tool: await (async (): Promise<{ [key: string]: ToolDefinition }> => {
+      const DISABLED_MSG =
+        'Workflows are disabled (WORKFLOWS=off). Enable with /workflow on or /wf on';
+      const wrap = (def: ToolDefinition): ToolDefinition => ({
+        ...def,
+        execute: async (args, ctx) => {
+          if (!workflowsEnabled) {
+            throw new Error(DISABLED_MSG);
+          }
+          return def.execute(args, ctx);
+        },
+      });
+
+      return {
+        start_development: wrap(
+          createStartDevelopmentTool(
+            input.directory,
+            getServerContext,
+            setBufferedInstructions
+          )
+        ),
+        proceed_to_phase: wrap(
+          createProceedToPhaseTool(getServerContext, setBufferedInstructions)
+        ),
+        conduct_review: wrap(createConductReviewTool(getServerContext)),
+        reset_development: wrap(
+          createResetDevelopmentTool(input.directory, getServerContext)
+        ),
+        setup_project_docs: wrap(
+          await createSetupProjectDocsTool(input.directory, getServerContext)
+        ),
+      };
+    })(),
   };
 };
 

packages/opencode-plugin/test/e2e/plugin.test.ts

@@ -743,3 +743,151 @@ describe('File Pattern Restrictions', () => {
     });
   }
 });
+
+describe('WORKFLOWS=off environment variable', () => {
+  it('registers tools when WORKFLOWS=off, but execute throws a clear disabled error', async () => {
+    const dir = createTempDir();
+    const originalEnv = process.env.WORKFLOWS;
+    try {
+      process.env.WORKFLOWS = 'off';
+
+      const hooks = await WorkflowsPlugin(createMockPluginInput(dir));
+
+      // Tools are still registered (so /workflow on can re-enable them)
+      expect(hooks.tool).toBeDefined();
+      expect(hooks.tool).toHaveProperty('start_development');
+      expect(hooks.tool).toHaveProperty('proceed_to_phase');
+      expect(hooks.tool).toHaveProperty('conduct_review');
+      expect(hooks.tool).toHaveProperty('reset_development');
+      expect(hooks.tool).toHaveProperty('setup_project_docs');
+
+      // But executing a tool throws with a clear message
+      await expect(
+        hooks.tool!['start_development'].execute({ workflow: 'minor' }, {
+          sessionID: 'test-session',
+        } as unknown)
+      ).rejects.toThrow(/disabled/i);
+
+      // Command hook is available for toggling
+      expect(hooks['command.execute.before']).toBeDefined();
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.WORKFLOWS;
+      } else {
+        process.env.WORKFLOWS = originalEnv;
+      }
+      cleanupDir(dir);
+    }
+  });
+
+  it('allows tool execution after /wf on when started with WORKFLOWS=off', async () => {
+    const dir = createTempDir();
+    const originalEnv = process.env.WORKFLOWS;
+    try {
+      process.env.WORKFLOWS = 'off';
+
+      const hooks = await WorkflowsPlugin(createMockPluginInput(dir));
+
+      // Confirm disabled initially
+      await expect(
+        hooks.tool!['start_development'].execute({ workflow: 'minor' }, {
+          sessionID: 'test-session',
+        } as unknown)
+      ).rejects.toThrow(/disabled/i);
+
+      // Toggle on via command
+      const output: { parts: Part[] } = { parts: [] };
+      await hooks['command.execute.before']!(
+        { command: 'workflow', arguments: 'on', sessionID: 'test-session' },
+        output
+      );
+      expect(
+        output.parts[0]?.type === 'text' && output.parts[0].text
+      ).toContain('enabled');
+
+      // Now the tool should no longer throw the disabled error
+      // (it may fail for other reasons like no plan file, but not the disabled guard)
+      let thrownMessage: string | undefined;
+      try {
+        await hooks.tool!['start_development'].execute({ workflow: 'minor' }, {
+          sessionID: 'test-session',
+        } as unknown);
+      } catch (err) {
+        thrownMessage = (err as Error).message;
+      }
+      // If it did throw, it must NOT be the disabled message
+      if (thrownMessage !== undefined) {
+        expect(thrownMessage).not.toMatch(/disabled/i);
+      }
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.WORKFLOWS;
+      } else {
+        process.env.WORKFLOWS = originalEnv;
+      }
+      cleanupDir(dir);
+    }
+  });
+
+  it('loads all tools and hooks when WORKFLOWS is not set (default)', async () => {
+    const dir = createTempDir();
+    const originalEnv = process.env.WORKFLOWS;
+    try {
+      delete process.env.WORKFLOWS;
+
+      const hooks = await WorkflowsPlugin(createMockPluginInput(dir));
+
+      // When WORKFLOWS is not set, all hooks and tools should be registered
+      expect(hooks['chat.message']).toBeDefined();
+      expect(hooks['tool.execute.before']).toBeDefined();
+      expect(hooks['experimental.session.compacting']).toBeDefined();
+      expect(hooks['command.execute.before']).toBeDefined();
+      expect(hooks.tool).toBeDefined();
+
+      // Tools should be populated
+      expect(hooks.tool).toHaveProperty('start_development');
+      expect(hooks.tool).toHaveProperty('proceed_to_phase');
+      expect(hooks.tool).toHaveProperty('conduct_review');
+      expect(hooks.tool).toHaveProperty('reset_development');
+      expect(hooks.tool).toHaveProperty('setup_project_docs');
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.WORKFLOWS;
+      } else {
+        process.env.WORKFLOWS = originalEnv;
+      }
+      cleanupDir(dir);
+    }
+  });
+
+  it('loads all tools and hooks when WORKFLOWS=on', async () => {
+    const dir = createTempDir();
+    const originalEnv = process.env.WORKFLOWS;
+    try {
+      process.env.WORKFLOWS = 'on';
+
+      const hooks = await WorkflowsPlugin(createMockPluginInput(dir));
+
+      // When WORKFLOWS=on, all hooks and tools should be registered
+      expect(hooks['chat.message']).toBeDefined();
+      expect(hooks['tool.execute.before']).toBeDefined();
+      expect(hooks['experimental.session.compacting']).toBeDefined();
+      expect(hooks['command.execute.before']).toBeDefined();
+      expect(hooks.tool).toBeDefined();
+
+      // Tools should be populated
+      expect(hooks.tool).toHaveProperty('start_development');
+      expect(hooks.tool).toHaveProperty('proceed_to_phase');
+      expect(hooks.tool).toHaveProperty('conduct_review');
+      expect(hooks.tool).toHaveProperty('reset_development');
+      expect(hooks.tool).toHaveProperty('setup_project_docs');
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.WORKFLOWS;
+      } else {
+        process.env.WORKFLOWS = originalEnv;
+      }
+      cleanupDir(dir);
+    }
+  });
+});