Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(hooks): capture Kimi Code tool failures via PostToolUseFailure

Lucas Oliveira24c04a2b8efc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1d42639..7dd79cca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,8 +27,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
(Kimi Code treats `url` with no `transport` field as streamable HTTP) plus
optional bearer `headers`. `install-hooks` merges `[[hooks]]` entries into
`~/.kimi-code/config.toml`, preserving the provider/model settings the same
- file holds, and covers 9 events: `SessionStart`, `SessionEnd`,
- `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`,
+ file holds, and covers 10 events: `SessionStart`, `SessionEnd`,
+ `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`
+ (Kimi Code reports tool failures separately from successful calls; the
+ entry reuses the post-tool-use capture path), `Stop`, `SubagentStart`,
`SubagentStop`, and `PreCompact`. Both paths honor `$KIMI_CODE_HOME`.
Handoff injection happens at `SessionStart` through hook stdout, which Kimi
Code appends to the model context; `setup-agent` and `uninstall` handle the
diff --git a/README.md b/README.md
index 9826998a..653715c6 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@
| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). |
| Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works; no handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |
| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json`) + lifecycle hooks via `install-hooks --agent zero --apply` (exec-form native commands in `~/.config/zero/hooks.json`, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards `sessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. |
-| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 9 events including subagent start/stop); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `SessionStart` stdout. |
+| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `SessionStart` stdout. |
| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
| Hermes Agent | Community | A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available. It is not part of ai-memory's first-party install surface; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. |
| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index 93639f3f..de202de2 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -47,20 +47,28 @@ pub(crate) const CLAUDE_CODE_EVENTS: [(&str, &str); 9] = [
("SubagentStop", "subagent-stop.sh"),
];
-/// Kimi Code lifecycle events ai-memory hooks. Same 9-event vocabulary
-/// as Claude Code (`CLAUDE_CODE_EVENTS`), but Kimi Code wires hooks as
-/// `[[hooks]]` entries in `$KIMI_CODE_HOME/config.toml` (TOML) instead of
-/// a JSON settings file, so its payload comes from
-/// [`kimi_code_hook_commands`] rather than the JSON hook shapes.
+/// Kimi Code lifecycle events ai-memory hooks. Claude Code's 9-event
+/// vocabulary (`CLAUDE_CODE_EVENTS`) plus `PostToolUseFailure`: Kimi Code
+/// fires `PostToolUse` on successful calls only and reports failures
+/// separately. The failure entry reuses the post-tool-use script — the
+/// server aliases `PostToolUseFailure` to `PostToolUse` and reads the
+/// outcome from the payload.
+///
+/// Kimi Code wires hooks as `[[hooks]]` entries in
+/// `$KIMI_CODE_HOME/config.toml` (TOML) instead of a JSON settings file,
+/// so its payload comes from [`kimi_code_hook_commands`] rather than the
+/// JSON hook shapes.
///
/// Adding a hook event means updating this list AND adding the matching
-/// `.sh` and `.ps1` files under `hooks/kimi-code/`. The install-hooks
-/// parity test fails if the bundle drifts.
-pub(crate) const KIMI_CODE_EVENTS: [(&str, &str); 9] = [
+/// `.sh` and `.ps1` files under `hooks/kimi-code/` (a reused script like
+/// post-tool-use needs no new file). The install-hooks parity test fails
+/// if the bundle drifts.
+pub(crate) const KIMI_CODE_EVENTS: [(&str, &str); 10] = [
("SessionStart", "session-start.sh"),
("UserPromptSubmit", "user-prompt-submit.sh"),
("PreToolUse", "pre-tool-use.sh"),
("PostToolUse", "post-tool-use.sh"),
+ ("PostToolUseFailure", "post-tool-use.sh"),
("PreCompact", "pre-compact.sh"),
("Stop", "stop.sh"),
("SessionEnd", "session-end.sh"),
diff --git a/crates/ai-memory-cli/src/commands/setup_agent.rs b/crates/ai-memory-cli/src/commands/setup_agent.rs
index 3205734b..b5b98ebf 100644
--- a/crates/ai-memory-cli/src/commands/setup_agent.rs
+++ b/crates/ai-memory-cli/src/commands/setup_agent.rs
@@ -37,8 +37,8 @@ use anyhow::{Context, Result, bail};
use crate::cli::{AgentChoice, SetupAgentArgs};
use crate::commands::install_mcp;
use crate::commands::render_shared::{
- ANTIGRAVITY_LIFECYCLE_EVENTS, ANTIGRAVITY_TOOL_EVENTS, CLAUDE_CODE_EVENTS, CODEX_PROFILE,
- CURSOR_PROFILE, GEMINI_PROFILE, build_claude_code_payload, build_devin_payload,
+ ANTIGRAVITY_LIFECYCLE_EVENTS, ANTIGRAVITY_TOOL_EVENTS, CODEX_PROFILE, CURSOR_PROFILE,
+ GEMINI_PROFILE, KIMI_CODE_EVENTS, build_claude_code_payload, build_devin_payload,
build_grok_payload, hook_script_for_current_platform,
};
use crate::config::{Config, DEFAULT_SERVER_URL};
@@ -149,7 +149,7 @@ pub fn run(config: &Config, args: SetupAgentArgs) -> Result<()> {
// exactly; its `[[hooks]]` TOML merge into config.toml (shared
// with user provider/model settings) is owned by install-hooks
// apply-mode, so print-mode stays a conservative script listing.
- AgentChoice::KimiCode => emit_other(&emit_root, agent_sub, &args, &[&CLAUDE_CODE_EVENTS]),
+ AgentChoice::KimiCode => emit_other(&emit_root, agent_sub, &args, &[&KIMI_CODE_EVENTS]),
AgentChoice::OpenCode
| AgentChoice::Pi
| AgentChoice::Omp
@@ -363,7 +363,12 @@ fn event_script_paths(emit_root: &Path, event_lists: &[&[(&str, &str)]]) -> Vec<
for events in event_lists {
for (_, script) in *events {
let script = hook_script_for_current_platform(script);
- paths.push(emit_root.join(script.as_ref()));
+ let path = emit_root.join(script.as_ref());
+ // Two events may share one script (Kimi Code's PostToolUseFailure
+ // reuses post-tool-use); list each file once.
+ if !paths.contains(&path) {
+ paths.push(path);
+ }
}
}
paths
@@ -632,12 +637,12 @@ mod tests {
}
#[test]
- fn kimi_code_manual_script_paths_cover_claude_code_event_set() {
- // Kimi Code's hook vocabulary (SessionStart, SessionEnd,
- // UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart,
- // SubagentStop, PreCompact) mirrors Claude Code's nine events.
+ fn kimi_code_manual_script_paths_cover_kimi_event_set() {
+ // Kimi Code's hook vocabulary is Claude Code's nine events plus
+ // PostToolUseFailure; the failure entry reuses post-tool-use.sh,
+ // so the script list carries nine unique files for ten events.
let root = Path::new("/hooks/kimi-code");
- let paths = event_script_paths(root, &[&CLAUDE_CODE_EVENTS]);
+ let paths = event_script_paths(root, &[&KIMI_CODE_EVENTS]);
let rendered = paths
.iter()
.map(|path| path.to_string_lossy())
diff --git a/docs/install.md b/docs/install.md
index 8c28dd99..5e15ef31 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -597,9 +597,11 @@ ai-memory install-hooks --agent kimi-code --apply \
```
`install-hooks` merges `[[hooks]]` entries into `config.toml`, preserving the
-provider/model settings the same file holds. Entries cover 9 events —
+provider/model settings the same file holds. Entries cover 10 events —
`SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
-`Stop`, `SubagentStart`, `SubagentStop`, and `PreCompact` — and default to
+`PostToolUseFailure` (Kimi Code reports tool failures separately from
+successful calls; it reuses the post-tool-use handler), `Stop`,
+`SubagentStart`, `SubagentStop`, and `PreCompact` — and default to
native `ai-memory hook --event … --agent kimi-code` commands on local installs
(local spool plus batched delivery, capture-policy v1 enforced); the staged
script bundle under `~/.local/share/ai-memory/hooks/kimi-code/` is the
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index c4462fb6..7d42c6e1 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -622,9 +622,11 @@ ai-memory install-hooks --agent kimi-code --apply \
--server-url "http://homelab:49374" --auth-token "$TOKEN"
```
-The installed entries cover 9 events — `SessionStart`, `SessionEnd`,
-`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`,
-`SubagentStop`, and `PreCompact` — with a Kimi Code-specific script bundle /
+The installed entries cover 10 events — `SessionStart`, `SessionEnd`,
+`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`
+(Kimi Code fires `PostToolUse` on successful calls only), `Stop`,
+`SubagentStart`, `SubagentStop`, and `PreCompact` — with a Kimi Code-specific
+script bundle /
native `ai-memory hook --event … --agent kimi-code` commands (native is the
default for local installs; the staged scripts under
`~/.local/share/ai-memory/hooks/kimi-code/` are the compatibility fallback).