Hooks

A hook is a command your project declares. It runs at an event of the session, receives the event as JSON, and before a tool call it can refuse the call.

Where hooks are declared

In the root of the session’s folder: .talos/hooks.json, or .harness-ui-hooks.json.

{
  "hooks": [
    { "id": "no-secrets", "eventi": ["pre_tool_call"], "comando": "node .talos/hooks/no-secrets.mjs" }
  ]
}

id names the hook (a name, not a path), eventi lists its events, comando is the command. The first file that declares an id wins.

Trust

A hook never runs until you trust it (in the session’s hooks panel). Trust is recorded outside the project, on this computer, with a SHA-256 fingerprint of the command and of the project files it names: if any of them changes, the hook stops and must be trusted again. A project you clone cannot trust its own hooks.

Events

pre_tool_call

can refuse

Before every tool call. A hook that refuses stops the call, for the tools that change something (listed below); for a read it is ignored.

The event, in TALOS_HOOK_EVENT

tipo

The event.

azione

The tool.

argomenti

The tool’s arguments.

giro

The turn number.

post_tool_call

notification

After every tool call. Notification only: it cannot undo the call.

The event, in TALOS_HOOK_EVENT

tipo

The event.

azione

The tool.

esito

The tool’s result.

giro

The turn number.

session_start

notification

When a session’s task starts. Notification only.

The event, in TALOS_HOOK_EVENT

tipo

The event.

task

The task’s assignment.

session_end

notification

When it ends. Notification only.

The event, in TALOS_HOOK_EVENT

tipo

The event.

comeFinita

How the session ended.

Running a hook

Programs

nodeecho: the first word of comando must be one of these; the rest are its arguments (no shell).

Folder

The session’s folder.

Time

10 s at most.

Output

64 KiB of output are read.

Environment

PATHPathPATHEXTSystemRootWINDIRCOMSPECTALOS_HOOK_EVENT: nothing else of yours is passed.

A hook answers on standard output with { "consentito": true } or { "consentito": false, "motivo": "…" }; without that JSON, exit code 0 means allowed and anything else refused, with standard error as the reason. The first trusted hook that refuses wins, and the model reads its reason.

Tools a hook can stop

pre_tool_call runs before every tool; its refusal stops these, which change something (for a read it is ignored):

scrivifile_editshelldocument_creategenerate_imagelibrary_renamelibrary_deletelibrary_exportlibrary_context_policy_updatenotes_createnotes_updatenotes_deletetasks_createtasks_completetasks_updatetasks_deletememory_writememory_updatememory_deleteresearch_startresearch_renameresearch_pauseresearch_resumeresearch_cancelresearch_deleteresearch_deposittool_createworkflow_plan_propose