What are Hooks?

Hooks are the mechanism by which Contenox gives a model access to real-world actions. Instead of generating text, the model calls a hook to read files, run commands, query APIs, or fire HTTP requests — and gets the result back as context for its next reply.

How it works

Chain starts
  └─ FetchTools: each listed hook returns its tool schemas
       └─ Schemas are sent to the model alongside the prompt
            └─ Model returns a tool call
                 └─ execute_tool_calls runs the hook
                      └─ Result appended to history → model continues

In your chain JSON, specify which hooks the task can use via the execute_config.hooks allowlist:

"execute_config": {
  "model": "qwen2.5:7b",
  "provider": "ollama",
  "hooks": ["local_fs", "nws", "local_shell"]
}

Pattern support:

Value	Meaning
field absent	All registered hooks
`[]`	No hooks exposed to the model
`["*"]`	All registered hooks (explicit)
`["a", "b"]`	Only the named hooks
`["*", "!plan_manager"]`	All except `plan_manager`

Unknown names in an exact list are silently ignored — if local_shell is disabled the chain still runs.

Use {{hookservice:list}} in your system_instruction to inject the live tool manifest. This macro respects the task's hooks allowlist — the model only sees what the task permits:

"system_instruction": "You are a helpful assistant. Available tools: {{hookservice:list}}."

Template variables

System instructions and prompt_template fields support the following macros:

Macro	Returns
`{{var:<name>}}`	Value of the named template variable supplied by the caller
`{{now}}`	Current time in RFC3339 format
`{{now:<layout>}}`	Current time in Go time layout (e.g. `{{now:2006-01-02}}`)
`{{chain:id}}`	ID of the currently executing chain
`{{hookservice:list}}`	JSON object mapping hook name → array of tool names (respects task `hooks` allowlist)
`{{hookservice:hooks}}`	JSON array of hook names available to the task
`{{hookservice:tools <name>}}`	JSON array of tool names for a specific hook

Hook types

Contenox ships with built-in local hooks and supports unlimited remote hooks:

Hook name	Type	Always available	What it does
`local_fs`	Local	✅	Read, write, and search files within a configured directory
`webhook`	Local	✅	Call any HTTP endpoint
`local_shell`	Local	Opt-in (`--shell`)	Run arbitrary shell commands
`ssh`	Local	✅	Run a command on a remote host over SSH
`plan_manager`	Local	✅	Create and drive multi-step plans
`plan_summary`	Local	✅	Persist plan step results to the local database
`print`	Local	✅	Append a message to the chat history or return it as a string
`echo`	Local	✅	Echo the input back (useful for debugging chains)
your name	Remote	Register with `contenox hook add`	Any OpenAPI v3 service

Choosing the right hook

local_fs — best for code analysis, file editing, report generation
webhook — when the model needs to call a specific URL you control
local_shell — full power; use only in trusted, sandboxed environments
ssh — run commands on remote machines from within a chain
plan_manager + plan_summary — structured multi-step execution with local persistence
print / echo — inject messages or inspect task output during development
Remote hooks — turn any OpenAPI service into an agent tool; ideal for internal APIs, SaaS integrations, and team-shared tools

What are Hooks?

How it works

Template variables

Hook types

Choosing the right hook

Further reading