Hooks

Constraints

Supported Hook Events

Storage Paths for Plug-ins and Dependency Files

A plug-in is a JavaScript/TypeScript module that operates by exporting plug-in functions. Each function receives a context object and returns the corresponding hook object. If external packages are required within a plug-in file, you must create a package.json file in the configuration directory and configure the necessary dependencies. CodeArts Agent automatically installs these dependencies when it starts.

Quick Start

The following example demonstrates how to filter sensitive information, such as passwords and keys, from user inputs to effectively prevent data leaks.

1. Create a directory for storing the plug-in file.

   Create a directory named plugin in the project root directory ./ .codeartsdoer.

   Figure 1 Creating the plugin directory
   

2. Create a script.

   In the plugin directory, create a new file named sensitiveInfoFilteringPlugin.ts, write the hook logic code in the file, and save the file.

   // Import the plug-in type to define the plug-in.
   import type { Plugin } from "@opencode-ai/plugin"
   
   
   // Export the plugin implementation. Plugin is an asynchronous function that receives plugin input parameters and returns a hook object.
   export const SensitiveInfoFilteringPlugin: Plugin = async ({}) => {
     // Return a hooks object containing various hook functions.
     return {
       // Listen to the hook after the tool is executed. This function is triggered after the tool execution is complete.
       "tool.execute.after": async (
         // Input parameters include the tool name, session ID, call ID, inference ID, and other information.
         input: { tool: string; sessionID: string; callID: string; args: any },
         // Output parameters include the title, output, and metadata of the tool execution result.
         output: {
           title: string
           output: string
           metadata: any
         },
       ) => {
         // Check if the operation is to read a file (tool name is "read") and the output content exists.
         if (input.tool === "read" && output.output) {
           // Sensitive information matching patterns (supporting JSON and other common formats).
           // Matches "password": "value" or password: value.
           // First regex: matches JSON format, such as "password": "***".
           // Second regex: matches common key-value formats, such as password=*** orpassword:***.
           const sensitivePatterns = [
             // Matches sensitive fields in JSON format: double-quoted key + colon + double-quoted value.
             new RegExp(`"password|passwd|pwd|api[_-]?key|secret|token|key|password"\\s*:\\s*"([^"]+)"`, "g"),
             // Matches sensitive fields in common format: key + colon or equal sign + unquoted value.
             new RegExp(`(password|passwd|pwd|api[_-]?key|secret|token)\\s*[:=]\\s*([^"'\\s\\\\]+)`, "gi"),
           ]
           // Assign the tool output content to the local variable content for subsequent processing.
           let content = output.output
   
   
           // Traverse all sensitive information matching patterns and replace them one by one.
           for (const pattern of sensitivePatterns) {
             // Use the replace method for substitution, passing a callback function to handle match results.
             // match: the fully matched string.
             // key: capture group 1, i.e., the sensitive field name (password, api_key, etc.)
             // value: capture group 2, i.e., the actual content of the sensitive field (e.g., actual password or key)
             content = content.replace(pattern, (match, key, value) => {
               // If sensitive information is matched, replace the actual value with the [Sensitive Info] placeholder.
               return match.replace(value, "[Sensitive Info]")
             })
           }
           // Update the output field in the output object to write back the filtered content.
           output.output = content
         }
       }
     }
   }

3. Restart the IDE.

   In the upper left corner of CodeArts Agent IDE, click File and choose Restart IDE. Because the current hook script does not support real-time loading, you need to restart the IDE for the script to take effect.

   

   To ensure that the script takes effect, it is advised to terminate all Bun processes in the task manager to completely clear any remaining instances.

4. Verify the effect.

   After you enter a prompt in the input box, the sensitive information in the results returned by the model will be automatically masked.

Creating Hooks

1. Select an event.

   Select an event name in Supported Hook Events based on service requirements.

2. Compile the hook script.
   1. Create a plug-in file.

      Create a .ts or .js file in the directory described in Storage Paths for Plug-ins and Dependency Files.

   2. Compile the hook logic.

      In Hook Event Reference, locate // Hook implementations go here, and write your specific hook implementation code there based on your actual service requirements.

3. (Optional) Configure dependencies.
   If external packages are required within a plug-in file, you must create a package.json file in the configuration directory described in Storage Paths for Plug-ins and Dependency Files and configure the necessary dependencies.

   {
     "dependencies": {
       "Dependency package name 1": "Version number",
       "Dependency package name 2": "Version number"
     }
   }

   The following is an example of the package.json file:

   {
     "dependencies": {
       "@opencode-ai/plugin": "*",
       "@babel/core": "7.29.0",
       "@langfuse/otel": "4.5.1"
     }
   }

4. Restart the IDE to verify the effect.

Hook Event Reference

Examples of supported hook events are provided below. Write your specific implementation logic at the // Hook implementations go here comment. Once the code is written, it can be used directly.

Usage Example

Taking "displaying a pop-up window to prompt for high-risk operations before deleting a file" as an example, this section provides a detailed guide on how to use a hook. This example uses a project-level configuration within the plug-in directory.

1. Select an event based on the description in Supported Hook Events.

   Deletions of files will call a tool, usually the deleteFile tool. Because the pop-up window needs to appear before the file is deleted, you should select the tool.execute.before event here.

2. Compile the hook script.
   1. Create a directory named plugin in the project root directory ./ .codeartsdoer.
   2. In the plugin directory, create a file named deleteFileHintPlugin.ts.
   3. Compile the script and save the file.

      // Import the type definition of the OpenCode plug-in.
      import type {Plugin} from "@opencode-ai/plugin";
      // Import the Node.js child process module to execute system commands.
      import { exec } from "child_process";
      // Import the promisify function from the util module to convert callback functions into Promises.
      import { promisify } from "util";
      // Convert the exec callback function into a Promise-based asynchronous function.
      const execAsync = promisify(exec);
      // Define and export the plug-in, accepting a client parameter to interact with OpenCode.
      export const DeleteFileHintPlugin: Plugin = async ({ client }) => {
        // Return the hook collection of the plug-in.
        return {
          // Listen for the hook for tool.execute.before.
          "tool.execute.before": async (
            // Input parameters: tool name, session ID, call ID, and inference ID.
            input: { tool: string; sessionID: string; callID: string; inferenceID?: string },
            // Output parameters: parameters for tool calling.
            output: { args: any }
          ) => {
            // Check if the operation is to delete a file.
            if (input.tool === "deleteFile") {
              // Define the message content for the warning pop-up window.
              const message = `Deleting files is a high-risk operation. Exercise caution when performing this operation.`
              // Execute commands based on the operating system.
              if (process.platform === "win32") {
      // Windows: Use PowerShell to call the system MessageBox.
                const cmd = `powershell -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${message}', 'Warning', 'OK', 'Warning')"`
                await execAsync(cmd)
              } else if (process.platform === "darwin") {
                // macOS: Use osascript to call the system pop-up window.
                const cmd = `osascript -e 'display alert "Warning" message "${message}"'`
                await execAsync(cmd)
              } else if (process.platform === "linux") {
                // Linux: Use notify-send to send a desktop notification.
                const cmd = `notify-send "Warning" "${message}"`
                await execAsync(cmd)
              }
            }
          }
        }
      }

3. Restart the IDE to verify the effect.
   1. In the upper left corner of CodeArts Agent IDE, click File and choose Restart IDE. Because the current hook script does not support real-time loading, you need to restart the IDE for the script to take effect.
      

      To ensure that the script takes effect, it is advised to terminate all Bun processes in the task manager to completely clear any remaining instances.

   2. Enter Delete file *** in the text box. A warning window is displayed on the client.

      *** indicates the name of the file to be deleted.