atuinsh/atuin · error

agent does not use JSON hooks

Error message

agent does not use JSON hooks

What it means

add_hook_entries edits the agent's JSON hooks configuration and is only valid for agents whose InstallKind is JsonHooks. If called for an agent using a different install kind (e.g. Extension), it bails since there is no JSON hooks structure to mutate.

Solutions

1. Update atuin to the latest version where the agent's install kind is handled
2. Report a bug with the agent name if a current release still fails
3. Verify the agent name is spelled correctly and supported

match install(&agent) {
    Err(e) if e.to_string().contains("agent does not use JSON hooks") => {
        // fall back to the agent's extension-based install path or upgrade atuin
    }
    other => other?,
}

When it happens

Trigger: install() invokes add_hook_entries for an agent whose install_kind() is not InstallKind::JsonHooks; internal dispatch mismatch in the hook installation flow.

Common situations: A bug or new agent type added with an install kind not handled by the installer; users cannot normally trigger this directly — it surfaces during `atuin hook install <agent>`.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• `atuin hook ` is not supported. Use `atuin hook install `.
• empty config key
• expected `atuin hook
• hook action cannot be combined with a positional agent
• still present: re-checked under the finalization mutex…

AI-assisted analysis of atuinsh/atuin@c0c717ab04 (2026-09-12). Data as JSON: /api/errors/6ba559dcfcd38db3. Report an issue: GitHub.

Appendix: source

Thrown at crates/atuin/src/command/client/hook.rs:309

            eprintln!(
                "\nAtuin extension installed for {actor_name}. Extension: {}\n{reload_hint}",
                extension_path.display()
            );
        }
    }

    Ok(())
}

fn add_hook_entries(hooks: &mut Value, agent: &Agent) -> Result<()> {
    let InstallKind::JsonHooks {
        config_path: _,
        hook_command,
        matcher,
    } = agent.install_kind()
    else {
        bail!("agent does not use JSON hooks");
    };

    for event_type in HOOK_EVENT_TYPES {
        let event_hooks = hooks
            .as_object_mut()
            .ok_or_else(|| eyre::eyre!("hooks is not a JSON object"))?
            .entry(*event_type)
            .or_insert_with(|| Value::Array(Vec::new()));

        let arr = event_hooks
            .as_array_mut()
            .ok_or_else(|| eyre::eyre!("hooks.{event_type} is not an array"))?;

        let already_installed = arr.iter().any(|entry| {
            entry.get("hooks").and_then(Value::as_array).is_some_and(|hooks| {
                hooks
                    .iter()
                    .any(|hook| hook.get("command").and_then(Value::as_str) == Some(hook_command))

View on GitHub (pinned to c0c717ab04)