Claude Code Integration
Relevant source files
The following files were used as context for generating this wiki page:
Claude Code Integration refers to the system within Honmoon that allows it to act as a security and privacy layer for the Claude Code agent. It functions through a plugin architecture that intercepts agent actions—such as tool use and user prompts—to apply redaction of PII (Personally Identifiable Information) and secrets, ensuring transcript hygiene and preventing sensitive data exfiltration to the LLM.
The integration utilizes a client-side "hook" mechanism where the Claude Code agent shells out to the honmoon binary. This binary processes the JSON-formatted transcript data, applies redaction logic via the honmoon-core engine, and returns a verdict or redacted content. Sources: ARCHITECTURE.md:65-68, crates/honmoon-cli/src/hook.rs:1-15
Plugin Architecture
The integration is structured as a Claude Code plugin consisting of a configuration file, defined lifecycle hooks, and a transport script.
Hook Mechanism
The plugin defines specific lifecycle events where Honmoon can intercept and modify data. These are defined in hooks.json and point to a shell script (redact.sh) that serves as the bridge to the Honmoon data plane. Sources: packages/claude-plugin/hooks/hooks.json:1-12, packages/claude-plugin/scripts/redact.sh:1-5
| Hook Name | Trigger Point | Purpose |
|---|---|---|
PreToolUse | Before an agent executes a tool | Redact secrets/PII from tool arguments |
PostToolUse | After a tool returns results | Redact sensitive data from tool output |
UserPromptSubmit | When the user submits a prompt | Ensure user input is clean of PII |
Sources: packages/claude-plugin/hooks/hooks.json:1-12, ARCHITECTURE.md:65-68
Data Flow
The data flow from Claude Code to Honmoon follows a synchronous execution path where the agent waits for the honmoon hook command to complete before proceeding.
The redact.sh script acts as a simple wrapper that pipes the input JSON directly into honmoon hook. Sources: packages/claude-plugin/scripts/redact.sh:4, ARCHITECTURE.md:65-68
Redaction Logic and Fail-Open Design
The core of the integration is the honmoon hook command, which provides a command-transport backend for the plugin. It receives JSON input on stdin, applies redaction (PII detection and secret tokenization), and writes the verdict to stdout. Sources: ARCHITECTURE.md:58-62, crates/honmoon-cli/src/hook.rs:17-35
Fail-Open Principle
To ensure that security processing does not break the agent's usability in the event of a Honmoon failure (e.g., binary not found, crash, or misconfiguration), the integration follows a "fail-open" design. If the redaction process fails, the agent proceeds with the original, unredacted data rather than halting. Sources: .claude/agent-memory/review-review-security-reviewer/project-redaction-failopen-design.md:1-15
The redact.sh script specifically checks if honmoon is in the PATH and handles exit codes to implement this behavior. Sources: packages/claude-plugin/scripts/redact.sh:4-5, .claude/agent-memory/review-review-security-reviewer/project-redaction-failopen-design.md:1-15
Implementation Detail
The Rust implementation of the hook handles the parsing of the standard Claude Code hook JSON structure.
// crates/honmoon-cli/src/hook.rs
pub async fn run_hook() -> Result<()> {
let mut input = String::new();
std::io::stdin().read_to_string(&mut input)?;
// Parse hook JSON, redact via honmoon-core
// ...
let output = json!({
"verdict": "allow",
"redacted": redacted_content
});
println!("{}", output);
Ok(())
}
Sources: crates/honmoon-cli/src/hook.rs:17-35, ARCHITECTURE.md:58-62
Configuration and Components
The integration is managed through several key files in the repository:
| File Path | Description |
|---|---|
packages/claude-plugin/plugin.json | Main Claude Code plugin manifest. |
packages/claude-plugin/hooks/hooks.json | Defines the mapping of agent events to the redaction script. |
packages/claude-plugin/scripts/redact.sh | Shell bridge that executes the Honmoon CLI. |
crates/honmoon-cli/src/hook.rs | Rust CLI logic for the hook command. |
crates/honmoon-cli/src/main.rs | CLI entry point that dispatches the hook command. |
Sources: ARCHITECTURE.md:50-69, crates/honmoon-cli/src/main.rs:25-45, packages/claude-plugin/hooks/hooks.json:1-12
Summary
Claude Code Integration provides a client-side security layer for AI agents by intercepting transcripts and tool usage. By using a lightweight shell-to-Rust bridge, it enables high-performance PII and secret redaction while maintaining a fail-open posture to preserve agent availability. This system integrates the honmoon-core redaction engine directly into the agent's operational lifecycle. Sources: ARCHITECTURE.md:65-68, .claude/agent-memory/review-review-security-reviewer/project-redaction-failopen-design.md:1-15