ContainsAnyToken
terraphim-agent
terraphim-cli
terraphim-ai-cbm
terraphim_config ↔ terraphim_persistence ↔ terraphim_multi_agent
~/.claude/hooks/pre_tool_use.sh
bash#!/bin/bash# Extract command from JSON inputCOMMAND=$(echo "$1" | jq -r '.tool_input.command // empty')# Strip quoted strings to avoid false positivesCLEAN_COMMAND=$(echo "$COMMAND" | sed 's/"[^"]*"//g')# Check for dangerous bypass flagsif [[ "$CLEAN_COMMAND" =~ (--no-verify|-n)(?=.*\bgit\s+(commit|push)) ]]; then # Return deny decision echo '{"decision": "deny", "reason": "Git bypass flags detected"}' exit 0fi# Continue to replacement stagecd ~/.config/terraphimterraphim-agent hook "$1"
--no-verify
-n
git commit/push
terraphim-agent hook
rust// terraphim_agent/src/commands/hook.rspub async fn execute_hook( input: HookInput, agent: &TerraphimAgent,) -> Result<HookOutput, HookError> { // Apply knowledge graph replacements let enhanced_text = agent .rolegraph .apply_replacements(&input.text)?; // Validate connectivity agent .automata .validate_connectivity(&enhanced_text)?; Ok(HookOutput { modified_text: enhanced_text, was_modified: enhanced_text != input.text, })}
rustPreLlmContext { prompt: String, // Command type + description agent_id: String, // Agent identifier conversation_history: Vec<String>, // Previous messages token_count: usize, // Estimated tokens}
rustPostLlmContext { prompt: String, // Original prompt response: String, // Generated response agent_id: String, // Agent identifier token_count: usize, // Total tokens used model: String, // LLM model used}
rustPreToolContext { code: String, // Code to execute language: String, // Programming language agent_id: String, // Agent identifier vm_id: String, // VM execution environment metadata: HashMap<String, String>, // Additional context}
rm -rf /
sudo
chmod 777
rustPostToolContext { original_code: String, // Original code executed output: String, // Execution output exit_code: i32, // Process exit code duration_ms: u64, // Execution time agent_id: String, // Agent identifier vm_id: String, // VM identifier}
~/.config/terraphim/runtime-validation.toml````toml[hooks]enabled = truefail_open = true # Allow execution if hooks fail (development mode)[guard]strict_mode = false # Block on any suspicion vs. specific patternslog_all_decisions = true # Log allow/block decisions[llm_hooks]enabled = truerequire_human_review = false # Only for high-stakes operations[tool_hooks]enabled = truevm_isolation = trueresource_limits = true[replacement]knowledge_graph_enhancement = trueconnectivity_validation = true```### Environment Variables```bash# Enable/disable specific hook categoriesTERRAPHIM_RUNTIME_VALIDATION_HOOKS=trueTERRAPHIM_GUARD_STAGE=trueTERRAPHIM_REPLACEMENT_STAGE=true# Hook behavior overridesTERRAPHIM_FAIL_OPEN=false # Production mode: fail closedTERRAPHIM_HOOK_TIMEOUT_MS=5000 # Hook execution timeout```## Hook Development### Creating Custom Hooks```rustuse crate::vm_execution::{hooks::*, VmExecutionError};#[derive(Debug)]pub struct SecurityHook { blocked_patterns: Vec<regex::Regex>,}#[async_trait]impl Hook for SecurityHook { fn name(&self) -> &str { "security-hook" } async fn pre_tool(&self, context: &PreToolContext) -> Result<HookDecision, VmExecutionError> { for pattern in &self.blocked_patterns { if pattern.is_match(&context.code) { return Ok(HookDecision::Block { reason: format!("Blocked pattern: {}", pattern.as_str()), }); } } Ok(HookDecision::Allow) } async fn post_tool(&self, context: &PostToolContext) -> Result<HookDecision, VmExecutionError> { // Log execution for learning if context.exit_code != 0 { log::warn!("Tool execution failed: {:?}", context); } Ok(HookDecision::Allow) }}```### Registering Hooks```rust// In agent initializationlet mut agent = TerraphimAgent::new(config).await?;// Add custom hooksagent.hook_manager.add_hook(Arc::new(SecurityHook::new()));agent.hook_manager.add_hook(Arc::new(PerformanceHook::new()));agent.hook_manager.add_hook(Arc::new(LearningHook::new()));```## Troubleshooting### Hook Not Invoked**Symptoms**: LLM/tool execution without hook validation**Causes**:- HookManager not initialized in agent- Hooks not registered with manager- Hook execution disabled in config**Resolution**:```bash# Check configcat ~/.config/terraphim/runtime-validation.toml# Verify agent initializationgrep -r "hook_manager" src/agent.rs# Check registrationgrep -r "add_hook" src/```### Hook Blocking Too Much**Symptoms**: Many operations blocked as "dangerous"**Causes**: Overly strict regex patterns, false positives**Resolution**:- Review
in security hooks- Enable debug logging to see exact matches- Adjust patterns to be more specific### Performance Issues**Symptoms**: Slow LLM/tool response times**Causes**: Hook timeout, expensive operations, network calls**Resolution**:- Increase
- Profile hook execution with
- Move expensive operations to background threads## Best Practices1. **Fail-Open Development**: Use
during development to avoid blocking2. **Specific Patterns**: Use targeted regex patterns instead of broad blocks3. **Async Operations**: Keep hook implementations fast and non-blocking4. **Comprehensive Logging**: Log all decisions for debugging and learning5. **Knowledge Graph Integration**: Leverage existing rolegraph and automata for intelligence6. **Security First**: Always implement security validation before functionality7. **Testing**: Test both success and failure scenarios for all hooks## Integration Points- **Claude Code**:
no_new_privs
Terraphim-Dev
Terraphim-Prod
Terraphim-Shared
bash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n
bash\n# Secrets are written to secure temporary files\nop inject -i templates/settings.toml.template -o settings.toml\ncargo run\n
bash\nbrew install 1password-cli\n
bash\ncurl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --import\nwget https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb\nsudo dpkg -i 1password-cli-amd64-latest.deb\n
bash\n# Run the setup script to create vaults and secret structure\n./scripts/setup-1password-terraphim.sh dev\n\n# For production setup\n./scripts/setup-1password-terraphim.sh prod\n\n# For complete setup\n./scripts/setup-1password-terraphim.sh all\n
op://
rust\nuse terraphim_settings::DeviceSettings;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n // Load settings with 1Password integration\n let settings = DeviceSettings::load_with_onepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n
bash\n# Generate configuration from template\nop inject -i templates/settings.toml.template -o settings.toml\n\n# Run application with resolved configuration\ncargo run\n
typescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepassword_status');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepassword_resolve_secret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/API_KEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepassword_process_config', {\n request: { config: 'api_key = \"op://Terraphim-Dev/OpenRouter/API_KEY\"' }\n});\n
yaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}\n\njobs:\n build:\n steps:\n - name: Install 1Password CLI\n uses: 1password/install-cli-action@v1\n \n - name: Generate configuration\n run: |\n op inject -i templates/env.terraphim.template -o .env.terraphim\n \n - name: Build with secrets\n run: |\n source .env.terraphim\n cargo build --release\n
bash\n# templates/env.terraphim.template\nOPENROUTER_API_KEY=\"op://Terraphim-Dev/OpenRouter/API_KEY\"\nANTHROPIC_API_KEY=\"op://Terraphim-Dev/Anthropic/API_KEY\"\nATOMIC_SERVER_SECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n
toml\n# templates/settings.toml.template\n[profiles.s3]\nbucket = \"op://Terraphim-Dev/AWS_S3/BUCKET_NAME\"\naccess_key_id = \"op://Terraphim-Dev/AWS_S3/ACCESS_KEY_ID\"\nsecret_access_key = \"op://Terraphim-Dev/AWS_S3/SECRET_ACCESS_KEY\"\n
json\n{\n \"llm\": {\n \"openrouter\": {\n \"api_key\": \"op://Terraphim-Dev/OpenRouter/API_KEY\"\n }\n }\n}\n
API_KEY
ORGANIZATION_ID
MODEL_NAME
BASE_URL
URL
SECRET
API_TOKEN
TEAM_ID
LIST_ID
ACCESS_KEY_ID
SECRET_ACCESS_KEY
BUCKET_NAME
REGION
ACCOUNT_ID
TOKEN
ORGANIZATION
REPOSITORY
BOT_TOKEN
GUILD_ID
CHANNEL_ID
CONNECTION_STRING
USERNAME
PASSWORD
HOST
PORT
PRIVATE_KEY
PUBLIC_KEY
PASSPHRASE
CERTIFICATE_PATH
CERTIFICATE_PASSWORD
SENTRY_DSN
DATADOG_API_KEY
bash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n
bash\n# Check vault contents\nop item list --vault=\"Terraphim-Dev\"\n\n# Verify specific item\nop item get \"OpenRouter\" --vault=\"Terraphim-Dev\"\n
bash\n# Validate template syntax\nop inject -i templates/env.terraphim.template --dry-run\n\n# Check for malformed references\ngrep -n \"op://\" templates/env.terraphim.template\n
bash\n# Test 1Password integration\ncargo run --bin debug-onepassword\n\n# Validate configuration templates\n./scripts/validate-templates.sh\n\n# Check secret resolution\nop run --env-file=\".env.terraphim\" -- env | grep -E '^(OPENROUTER|ANTHROPIC)'\n
./scripts/setup-1password-terraphim.sh dev
op inject -i templates/env.terraphim.template -o .env.terraphim
source .env.terraphim && cargo run
op run --env-file=\".env.test\" -- cargo test
op inject
Thesaurus for concept mapping and synonyms.
synonyms:: dictionary, concepts, terms
