diff --git a/docs/guide_meta_boundary.md b/docs/guide_meta_boundary.md index 5d2f6a8..52fe333 100644 --- a/docs/guide_meta_boundary.md +++ b/docs/guide_meta_boundary.md @@ -13,11 +13,18 @@ This repository contains two distinct architectural domains that share similar c - **Internal Tooling Control**: The tools available to the Application's internal AI are defined strictly by `manual_slop.toml` (`[agent.tools]`). ## Domain 2: The Meta-Tooling -- **Primary Files**: `scripts/mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `.gemini/`, `.claude/`. +- **Primary Files**: `scripts/mma_exec.py`, `scripts/claude_mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `.gemini/`, `.claude/`. - **Purpose**: The external AI agents (you, reading this) used to write the code for the Application. -- **Safety Model**: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies or Claude Code's permissions). These agents have their own sandboxing and do *not* use the Application's GUI for approval. +- **Safety Model**: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies or Claude Code's permissions). These agents have their own sandboxing and do *not* use the Application's GUI for approval unless explicitly hooked. - **Tooling Control**: These external agents use `mcp_client.py` natively to investigate and modify the `manual_slop` codebase (e.g., using `set_file_slice` to fix a bug). +## The Inter-Domain Bridges: `cli_tool_bridge.py` & `claude_tool_bridge.py` +To achieve true Human-In-The-Loop (HITL) safety while developing the app *with* external AI tools, the project provides "Bridge" scripts. +- **How they work**: These scripts (`cli_tool_bridge.py` for Gemini CLI, `claude_tool_bridge.py` for Claude) intercept the tool execution requests from the external AI. +- **The Hook Server**: They instantiate an `ApiHookClient` and send an HTTP request to `http://127.0.0.1:8999` (the Application's local API Hook Server). +- **The Result**: The `manual_slop` GUI intercepts this network request and pops open a modal asking the human developer if they approve the action requested by the *external* Meta-Tooling agent. +- **Environment Context**: These bridges check the `GEMINI_CLI_HOOK_CONTEXT` or `CLAUDE_CLI_HOOK_CONTEXT` environment variables. If the variable is set to `mma_headless` (which happens during `mma_exec.py` sub-agent execution), the bridge automatically **allows** the execution to prevent sub-agents from blocking the main thread waiting for human GUI clicks. + ## The Overlap & Entropy Vector: `mcp_client.py` `mcp_client.py` is the shared bridge. - It was originally written to give the Application's internal AI some read-only file context tools.