Skip to content
DlineDlineDline Docs

Hooks

A hook is a script named after an event. Dline runs it at specific points in the task lifecycle and around tool calls, passes JSON on standard input, and reads the JSON the script returns on standard output. Use hooks to write audit logs, validate tool parameters, inject context into the conversation, or cancel a task when a condition is not met.

Enabling hooks

Section titled “Enabling hooks”

Hooks are controlled by the Hooks toggle in Settings → Features (“Enable lifecycle and tool hooks during task execution.”), which is on by default. When it is off, the Hooks tab in the capabilities panel is hidden as well.

Hook locations

Section titled “Hook locations”
ScopePath
Global<documents-root>/hooks/
Workspace<workspace>/.agents/hooks/

By default, <documents-root> is the dline folder inside the operating system’s Documents directory. When DLINE_DOCS_DIR is set, its value is used as the root. When a global and a workspace hook share a name, both run and their results are merged.

File naming

Section titled “File naming”

The file name must match the event name exactly (case-sensitive):

  • macOS / Linux: an executable file without an extension, for example PreToolUse, with the execute permission set. .ps1 files are ignored.
  • Windows: a PowerShell script named <Event>.ps1, for example PreToolUse.ps1. Dline runs it with -NoProfile -NonInteractive -ExecutionPolicy Bypass; files without an extension are ignored.

Events

Section titled “Events”
EventWhen it runs
PreToolUseBefore a tool runs
PostToolUseAfter a tool runs
UserPromptSubmitWhen the user submits a message
TaskStartWhen a task starts
TaskCancelWhen a task is cancelled
TaskCompleteWhen a task completes
NotificationWhen Dline emits a notification
PreCompactBefore the context is compacted

Input

Section titled “Input”

Dline passes a JSON object on standard input with camelCase field names. Common fields:

  • clineVersion, hookName, timestamp, taskId;
  • workspaceRoots: the list of workspace root directories;
  • userId: an anonymous user or machine identifier;
  • model: an object with provider and slug.

Each event also has its own data object named after the event. For example, preToolUse contains toolName and parameters, and postToolUse additionally contains result, success, and executionTimeMs.

Output

Section titled “Output”

Return a JSON object on standard output. Every field is optional:

{
  "cancel": false,
  "contextModification": "Extra context for the model",
  "errorMessage": ""
}
  • cancel: a boolean. When PreToolUse returns true, the whole task is cancelled and errorMessage is used as the reason.
  • contextModification: a string added to the conversation as extra context, up to 50,000 characters.
  • errorMessage: a string describing an error or the reason for cancellation.

The Notification event ignores cancel and contextModification. The old shouldContinue field has been removed; output that contains it is rejected as invalid. Use cancel instead.

Limits

Section titled “Limits”
  • Each script can run for at most 30 seconds.
  • Standard output and standard error together are limited to 1 MiB.
  • If a script exits normally without printing valid JSON, Dline ignores its result and continues the task.

Managing hooks in the panel

Section titled “Managing hooks in the panel”

Select the scale icon in the toolbar below the input box to open the capabilities panel, then switch to the Hooks tab:

  • Hooks are grouped under Global Hooks and the workspace’s .agents/hooks/;
  • New hook… lets you pick an event type; Dline generates a script template for your platform and opens it;
  • Each hook can be edited, deleted, and toggled.

The New hook… list does not include Notification; create that file in a hooks directory manually if you need it. The list also offers a TaskResume type, which you can create but the current version does not trigger.

Section titled “Related”