@rubytech/create-realagent 1.0.406

package/payload/platform/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "maxy-platform",
+  "version": "0.1.0",
+  "private": true,
+  "workspaces": [
+    "plugins/*/mcp"
+  ],
+  "scripts": {
+    "build": "tsc -b plugins/*/mcp/tsconfig.json",
+    "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
+    "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
+    "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",
+    "build:admin": "tsc -p plugins/admin/mcp/tsconfig.json",
+    "build:cloudflare": "tsc -p plugins/cloudflare/mcp/tsconfig.json",
+    "build:tasks": "tsc -p plugins/tasks/mcp/tsconfig.json",
+    "build:email": "tsc -p plugins/email/mcp/tsconfig.json",
+    "build:workflows": "tsc -p plugins/workflows/mcp/tsconfig.json",
+    "build:stubs": "tsc -p plugins/scheduling/mcp/tsconfig.json"
+  }
+}

package/payload/platform/plugins/admin/PLUGIN.md

@@ -0,0 +1,47 @@
+---
+name: admin
+description: "Platform administration plugin. Provides system-status, brand-settings, account-manage, account-update, logs-read, plugin-read, render-component, session-reset, and session-resume tools for managing the Maxy platform."
+icon: ⚙️
+tools:
+  - system-status
+  - brand-settings
+  - account-manage
+  - account-update
+  - logs-read
+  - plugin-read
+  - render-component
+  - session-reset
+  - session-resume
+# Hidden tools (invoked by skills, hooks, or system internals):
+#   remote-auth-set-password — security recovery; agent directs user to browser setup instead
+#   api-key-store, api-key-verify — system setup; invoked by onboarding skill
+#   onboarding-get, onboarding-complete-step — onboarding flow; invoked by session-start hook and onboarding skill
+#   qr-generate — invoked by qr-code skill
+always: true
+embed: false
+---
+
+# Admin
+
+Platform management tools for both the admin and public agents. The `plugin-read` tool is available to the public agent (read-only) for loading plugin definitions and references. All other tools are admin-only.
+
+Tools are available via the `admin` MCP server.
+
+## Skills
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Manage public agents | User asks to create, edit, clone, list, preview, or delete a public agent | `skills/public-agent-manager/skill.md` |
+| Create a new skill | User asks to create, add, or teach the agent a new capability | `skills/skill-builder/SKILL.md` |
+| Review stream logs | Admin asks to review, diagnose, or analyse a Claude agent stream log | `skills/stream-log-review/SKILL.md` |
+| Set up business profile | Admin asks to set up, complete, or update business operational data | `skills/business-profile/SKILL.md` |
+| Generate a QR code | User asks to generate, create, or make a QR code from a URL, Wi-Fi details, contact, or text | `skills/qr-code/SKILL.md` |
+| Timezone queries | User asks for the time in another city, timezone conversion, UTC offset, or DST status | `skills/datetime/SKILL.md` |
+| Manage access grants | Admin asks to invite visitors, revoke or extend access, list who has access, or set an agent's access mode | `skills/access-manager/SKILL.md` |
+| Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/skill.md` |
+| Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/skill.md` |
+
+## Hooks
+
+- `hooks/session-start.sh` — loads IDENTITY.md on session start
+- `hooks/pre-tool-use.sh` — enforces public agent read-only lockdown

package/payload/platform/plugins/admin/hooks/agent-creation-approval.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — agent creation gate advancement.
+#
+# Advances gates when the user approves a component during agent creation.
+# The UI wraps all component completions in a _componentDone envelope:
+#
+#   {"_componentDone": true, "component": "<name>", "payload": "<original msg>"}
+#
+# Gate advancement rules:
+#   _componentDone + component="document-editor" + payload.filePath matching
+#     agents/{non-admin}/SOUL.md → gates.soul = true
+#   _componentDone + component="document-editor" + payload.filePath matching
+#     agents/{non-admin}/KNOWLEDGE.md → gates.knowledge = true
+#   _componentDone + component="form" (during active creation) → gates.config = true
+#
+# This hook fires on the user's response (after they click Approve or Submit),
+# not when the agent renders a component. Gate enforcement (blocking writes)
+# is handled by agent-creation-gate.sh (PreToolUse).
+#
+# Exit 0 always — UserPromptSubmit hooks must never block user messages
+# for gate advancement purposes.
+# Env: AGENT_CREATE_STATE_FILE (override volatile path, for testing)
+#      ACCOUNT_DIR (account directory for durable state)
+#      GATE_LOG_FILE (override log path, for testing)
+
+GATE_LOG="${GATE_LOG_FILE:-/tmp/maxy-gate.log}"
+STATE_FILE="${AGENT_CREATE_STATE_FILE:-/tmp/maxy-agent-create-state.json}"
+ACCOUNT_DIR="${ACCOUNT_DIR:-}"
+DURABLE_STATE="${ACCOUNT_DIR:+$ACCOUNT_DIR/.claude/agent-create-state.json}"
+
+# Fast path: no state file → no agent creation in progress, skip stdin read entirely
+[[ -f "$STATE_FILE" ]] || exit 0
+
+# Read stdin (user prompt JSON from Claude Code hook protocol)
+INPUT=$(cat)
+
+export _HOOK_INPUT="$INPUT"
+export _STATE_FILE="$STATE_FILE"
+export _DURABLE_STATE="${DURABLE_STATE:-}"
+export _GATE_LOG="$GATE_LOG"
+
+python3 -c '
+import os, sys, json, re
+
+hook_input_raw = os.environ.get("_HOOK_INPUT", "")
+state_file = os.environ.get("_STATE_FILE", "/tmp/maxy-agent-create-state.json")
+durable_file = os.environ.get("_DURABLE_STATE", "")
+log_file = os.environ.get("_GATE_LOG", "/tmp/maxy-gate.log")
+
+def log(msg):
+    try:
+        with open(log_file, "a") as lf:
+            lf.write("agent-creation-approval: %s\n" % msg)
+    except OSError:
+        pass
+
+# Parse hook input — UserPromptSubmit provides {"prompt": "..."} on stdin
+try:
+    hook_input = json.loads(hook_input_raw)
+except Exception as e:
+    log("ERROR — failed to parse UserPromptSubmit input: %s" % e)
+    sys.exit(0)
+
+if not isinstance(hook_input, dict):
+    sys.exit(0)
+
+prompt = hook_input.get("prompt", "")
+if not isinstance(prompt, str) or not prompt:
+    sys.exit(0)
+
+# --- Detect _componentDone wrapper ---
+try:
+    msg = json.loads(prompt)
+except (json.JSONDecodeError, TypeError):
+    # Not JSON — not a wrapped component message, nothing to advance
+    sys.exit(0)
+
+if not isinstance(msg, dict) or not msg.get("_componentDone"):
+    sys.exit(0)
+
+component = msg.get("component", "")
+payload_raw = msg.get("payload", "")
+
+# --- Determine which gate to advance ---
+gate_flag = ""
+agent_slug = ""
+
+if component == "document-editor":
+    # Parse payload for filePath
+    try:
+        payload = json.loads(payload_raw) if isinstance(payload_raw, str) else payload_raw
+    except (json.JSONDecodeError, TypeError):
+        payload = {}
+    if isinstance(payload, dict):
+        file_path = payload.get("filePath", "")
+        if isinstance(file_path, str):
+            m = re.search(r"agents/([^/]+)/(SOUL\.md|KNOWLEDGE\.md)$", file_path)
+            if m and m.group(1) != "admin":
+                agent_slug = m.group(1)
+                gate_flag = "soul" if m.group(2) == "SOUL.md" else "knowledge"
+
+elif component == "form":
+    # Any form submission during active creation advances the config gate.
+    # The state file existing is sufficient context — the workflow presents
+    # exactly one form (the agent config form) during creation.
+    gate_flag = "config"
+
+if not gate_flag:
+    sys.exit(0)
+
+# --- Read and advance the gate ---
+try:
+    with open(state_file) as f:
+        state = json.load(f)
+except Exception as e:
+    log("ERROR — failed to read state file for advancement: %s" % e)
+    sys.exit(0)
+
+if not isinstance(state, dict) or not isinstance(state.get("gates"), dict):
+    log("WARNING — state file has unexpected structure, skipping advancement")
+    sys.exit(0)
+
+# Populate slug from document-editor filePath if empty
+if not state.get("slug") and agent_slug:
+    state["slug"] = agent_slug
+
+# Already advanced — idempotent
+if state["gates"].get(gate_flag) is True:
+    sys.exit(0)
+
+state["gates"][gate_flag] = True
+
+# Write updated state
+try:
+    with open(state_file, "w") as f:
+        json.dump(state, f)
+except OSError as e:
+    log("ERROR — failed to write volatile state after advancement: %s" % e)
+
+if durable_file:
+    try:
+        durable_dir = os.path.dirname(durable_file)
+        os.makedirs(durable_dir, exist_ok=True)
+        with open(durable_file, "w") as f:
+            json.dump(state, f)
+    except OSError as e:
+        log("WARNING — failed to write durable state after advancement: %s" % e)
+
+pending = [k for k, v in state.get("gates", {}).items() if not v]
+log("%s gate advanced (user approval detected). Pending: %s" % (gate_flag, ", ".join(pending) if pending else "none"))
+' 2>>"$GATE_LOG" || true
+
+exit 0

package/payload/platform/plugins/admin/hooks/agent-creation-gate.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# PreToolUse hook — agent creation approval gate.
+#
+# Blocks Write, Edit, and Bash writes to public agent files (SOUL.md,
+# KNOWLEDGE.md, config.json) unless the agent creation workflow has been
+# started AND the corresponding approval gate has been passed.
+#
+# Decision tree:
+#
+#   Bash command targeting the state file itself?
+#   │
+#   ├─ Yes → exit 2: "State file is managed by hooks only."
+#   │
+#   └─ No  → (continue)
+#
+#   Write or Edit to agents/{slug}/* where slug ≠ admin?
+#   │
+#   ├─ No  → exit 0 (not an agent file, irrelevant)
+#   │
+#   └─ Yes → (gate check below)
+#
+#   Bash command writing to agents/{slug}/* where slug ≠ admin?
+#   │ (write patterns: >, >>, cat.*>, tee, cp, mv targeting gated files)
+#   │
+#   ├─ No  → exit 0 (not a write to an agent file)
+#   │
+#   └─ Yes → (gate check below)
+#
+#   Gate check:
+#     state file exists?
+#     │
+#     ├─ No  → exit 2: "Load public-agent-manager skill first."
+#     │
+#     └─ Yes → has 'started' ISO timestamp?
+#              │
+#              ├─ No  → delete state file, exit 2 (invalid)
+#              │
+#              └─ Yes → age > 6 hours?
+#                       │
+#                       ├─ Yes → delete state file, exit 2 (stale)
+#                       │
+#                       └─ No  → structure valid (3 boolean gate keys)?
+#                                │
+#                                ├─ No  → delete state file, exit 2 (malformed)
+#                                │
+#                                └─ Yes → gate for this file true?
+#                                         │
+#                                         ├─ Yes → exit 0 (approved)
+#                                         │
+#                                         └─ No  → exit 2 (gate message)
+#
+# Python parse errors = fail open (exit 0) — never block on an infra issue.
+# Structural validation failures = fail closed (exit 2) — forged/stale state.
+# Admin agent files (agents/admin/*) are exempt.
+#
+# The Bash gate is defense-in-depth — it catches common fallback patterns
+# (cat >, tee, cp, mv) but cannot catch all possible write vectors
+# (e.g. python3 -c "open(...).write(...)"). The primary enforcement is
+# the Write/Edit gate. The Bash gate also protects the state file itself
+# from being written or deleted by the agent.
+#
+# Exit 0: allow
+# Exit 2: block (stderr shown to agent)
+# Env: AGENT_CREATE_STATE_FILE (override volatile path, for testing)
+#      ACCOUNT_DIR (account directory for durable state cleanup)
+#      GATE_LOG_FILE (override log path, for testing)
+
+GATE_LOG="${GATE_LOG_FILE:-/tmp/maxy-gate.log}"
+STATE_FILE="${AGENT_CREATE_STATE_FILE:-/tmp/maxy-agent-create-state.json}"
+ACCOUNT_DIR="${ACCOUNT_DIR:-}"
+DURABLE_STATE="${ACCOUNT_DIR:+$ACCOUNT_DIR/.claude/agent-create-state.json}"
+
+# Read stdin (tool call JSON from Claude Code hook protocol)
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c \
+  "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" \
+  2>>"$GATE_LOG" || echo "")
+
+AGENT_SLUG=""
+AGENT_FILE=""
+GATE_FLAG=""
+
+case "$TOOL_NAME" in
+  Write|Edit)
+    # Extract file_path from tool input
+    FILE_PATH=$(echo "$INPUT" | python3 -c \
+      "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" \
+      2>>"$GATE_LOG" || echo "")
+
+    [[ -z "$FILE_PATH" ]] && exit 0
+
+    # Block Write/Edit targeting the state file itself (volatile or durable).
+    # Same protection as the Bash handler — the agent must not forge or
+    # destroy gate state via any tool.
+    if [[ "$FILE_PATH" == *maxy-agent-create-state* ]] || [[ "$FILE_PATH" == *agent-create-state.json ]]; then
+      echo "Agent creation gate: the gate state file is managed by hooks only. Do not write to or delete it directly." >&2
+      exit 2
+    fi
+
+    # Check if this is an agent file: path contains agents/<slug>/<file>
+    AGENT_INFO=$(python3 -c "
+import re
+path = '''$FILE_PATH'''
+m = re.search(r'agents/([^/]+)/([^/]+)$', path)
+if m:
+    print(m.group(1) + ' ' + m.group(2))
+else:
+    print('')
+" 2>>"$GATE_LOG" || echo "")
+
+    [[ -z "$AGENT_INFO" ]] && exit 0
+
+    AGENT_SLUG="${AGENT_INFO%% *}"
+    AGENT_FILE="${AGENT_INFO##* }"
+    ;;
+
+  Bash)
+    # --- Bash state-file protection (defense-in-depth) ---
+    # Block commands that write to or delete the state file itself.
+    # The state file is managed exclusively by hooks — the agent must not
+    # forge or destroy gate state via shell commands.
+    STATE_FILE_TARGETED=$(echo "$INPUT" | python3 -c "
+import sys, json, re
+d = json.load(sys.stdin)
+cmd = d.get('tool_input', {}).get('command', '')
+if re.search(r'(>|>>|cat\s.*>|tee\s|echo\s.*>|cp\s|mv\s|rm\s).*maxy-agent-create-state', cmd):
+    print('yes')
+else:
+    print('no')
+" 2>>"$GATE_LOG" || echo "no")
+
+    if [[ "$STATE_FILE_TARGETED" == "yes" ]]; then
+      echo "Agent creation gate: the gate state file is managed by hooks only. Do not write to or delete it directly." >&2
+      exit 2
+    fi
+
+    # Extract command and check for write patterns targeting agent directories.
+    # Matches: >, >>, cat.*>, tee, cp, mv followed by agents/{non-admin}/ path
+    # containing a gated filename (SOUL.md, KNOWLEDGE.md, config.json).
+    AGENT_INFO=$(echo "$INPUT" | python3 -c "
+import sys, json, re
+d = json.load(sys.stdin)
+cmd = d.get('tool_input', {}).get('command', '')
+# Match write patterns followed by a path containing agents/{slug}/{file}
+# where file is one of the gated files
+m = re.search(r'agents/([^/\s]+)/(SOUL\.md|KNOWLEDGE\.md|config\.json)', cmd)
+if not m:
+    print('')
+    sys.exit(0)
+slug = m.group(1)
+filename = m.group(2)
+# Check the command contains a write pattern before the path
+write_patterns = r'(>|>>|cat\s.*>|tee\s|cp\s|mv\s)'
+if re.search(write_patterns, cmd):
+    print(slug + ' ' + filename)
+else:
+    print('')
+" 2>>"$GATE_LOG" || echo "")
+
+    [[ -z "$AGENT_INFO" ]] && exit 0
+
+    AGENT_SLUG="${AGENT_INFO%% *}"
+    AGENT_FILE="${AGENT_INFO##* }"
+    ;;
+
+  *)
+    exit 0
+    ;;
+esac
+
+# Admin agent is exempt — never gated
+[[ "$AGENT_SLUG" == "admin" ]] && exit 0
+
+# Determine which gate flag to check
+case "$AGENT_FILE" in
+  SOUL.md)       GATE_FLAG="soul" ;;
+  KNOWLEDGE.md)  GATE_FLAG="knowledge" ;;
+  config.json)   GATE_FLAG="config" ;;
+  *)             exit 0 ;;  # Other agent files are not gated
+esac
+
+# --- This is a gated agent file. State file must exist. ---
+
+if [[ ! -f "$STATE_FILE" ]]; then
+  echo "Agent creation gate: invoke the public-agent-manager skill before writing agent files. The skill workflow ensures the user reviews and approves each file." >&2
+  exit 2
+fi
+
+# --- State file exists. Validate before trusting. ---
+#
+# Two-stage validation:
+#   1. Staleness — reject files older than 6 hours or missing 'started'
+#   2. Structure — require exactly {started, gates: {soul, knowledge, config}}
+#
+# Python parse errors (can't read JSON at all) → fail open (exit 0).
+# Structural validation failures (wrong shape) → fail closed (exit 2) + delete.
+# These are distinct: infra issues don't block work; forged state does.
+
+GATE_RESULT=$(python3 -c "
+import json, os, sys
+from datetime import datetime, timezone
+
+state_file = '$STATE_FILE'
+durable_file = '${DURABLE_STATE:-}'
+gate_flag = '$GATE_FLAG'
+
+def delete_state():
+    for f in [state_file, durable_file]:
+        if f:
+            try:
+                os.remove(f)
+            except OSError:
+                pass
+
+try:
+    with open(state_file) as f:
+        state = json.load(f)
+except Exception:
+    # Cannot parse JSON — fail open (infra issue, not forged state)
+    print('allow')
+    sys.exit(0)
+
+# Non-dict JSON (e.g. array, string, number) is structurally invalid
+if not isinstance(state, dict):
+    delete_state()
+    print('reject_malformed')
+    sys.exit(0)
+
+# --- Staleness check ---
+started = state.get('started')
+if not isinstance(started, str) or not started:
+    delete_state()
+    print('reject_invalid')
+    sys.exit(0)
+
+try:
+    started_dt = datetime.fromisoformat(started.replace('Z', '+00:00'))
+    age_hours = (datetime.now(timezone.utc) - started_dt).total_seconds() / 3600
+except (ValueError, TypeError):
+    delete_state()
+    print('reject_invalid')
+    sys.exit(0)
+
+if age_hours > 6 or age_hours < 0:
+    delete_state()
+    print('reject_stale')
+    sys.exit(0)
+
+# --- Structure validation ---
+gates = state.get('gates')
+if not isinstance(gates, dict):
+    delete_state()
+    print('reject_malformed')
+    sys.exit(0)
+
+expected_keys = {'soul', 'knowledge', 'config'}
+if set(gates.keys()) != expected_keys:
+    delete_state()
+    print('reject_malformed')
+    sys.exit(0)
+
+if not all(isinstance(v, bool) for v in gates.values()):
+    delete_state()
+    print('reject_malformed')
+    sys.exit(0)
+
+# --- Per-gate check ---
+if gates.get(gate_flag, False):
+    print('allow')
+else:
+    print('reject_gate')
+" 2>>"$GATE_LOG" || echo "allow")
+
+case "$GATE_RESULT" in
+  allow)
+    exit 0
+    ;;
+  reject_invalid)
+    echo "Agent creation gate: state file is invalid (missing or unparseable timestamp). Invoke the public-agent-manager skill to start a new agent creation workflow." >&2
+    exit 2
+    ;;
+  reject_stale)
+    echo "Agent creation gate: state file is stale (older than 6 hours). Invoke the public-agent-manager skill to start a new agent creation workflow." >&2
+    exit 2
+    ;;
+  reject_malformed)
+    echo "Agent creation gate: state file has invalid structure. Invoke the public-agent-manager skill to start a new agent creation workflow." >&2
+    exit 2
+    ;;
+  reject_gate)
+    # Gate not passed — block with descriptive error
+    case "$GATE_FLAG" in
+      soul)
+        echo "Agent creation gate: present SOUL.md to the user via a document-editor component with the correct filePath, then wait for the user to approve. The gate advances when the user clicks Approve." >&2
+        ;;
+      knowledge)
+        echo "Agent creation gate: present KNOWLEDGE.md to the user via a document-editor component with the correct filePath, then wait for the user to approve. The gate advances when the user clicks Approve." >&2
+        ;;
+      config)
+        echo "Agent creation gate: present the agent configuration to the user via a form component, then wait for the user to submit. The gate advances when the user submits the form." >&2
+        ;;
+    esac
+    exit 2
+    ;;
+esac
+
+# Fallback — should not reach here, but fail open for safety
+exit 0

package/payload/platform/plugins/admin/hooks/agent-creation-post.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# PostToolUse hook — agent creation state creation and completion cleanup.
+#
+# Two responsibilities:
+#
+# 1. STATE CREATION: When mcp__admin__plugin-read loads the public-agent-manager
+#    skill, creates (or resets) the gate state file with all gates false. Always
+#    overwrites any existing state — loading the skill is the intent to start a
+#    fresh workflow. This is the only entry point that unlocks agent file writes.
+#
+# 2. STATE CLEANUP: After a successful Write/Edit to a gated agent file, checks
+#    whether all gates are true AND all three gated files (SOUL.md, KNOWLEDGE.md,
+#    config.json) exist on disk. If so, creation is complete — deletes both
+#    volatile and durable state files immediately.
+#
+# Gate advancement (advancing gates from false to true) is handled by
+# agent-creation-approval.sh (UserPromptSubmit), which fires when the user
+# approves a component. Gate enforcement (blocking writes until gates pass)
+# is handled by agent-creation-gate.sh (PreToolUse).
+#
+# Exit 0 always — PostToolUse hooks must never block tool execution.
+# Env: AGENT_CREATE_STATE_FILE (override volatile path, for testing)
+#      ACCOUNT_DIR (account directory for durable state)
+#      GATE_LOG_FILE (override log path, for testing)
+
+GATE_LOG="${GATE_LOG_FILE:-/tmp/maxy-gate.log}"
+STATE_FILE="${AGENT_CREATE_STATE_FILE:-/tmp/maxy-agent-create-state.json}"
+ACCOUNT_DIR="${ACCOUNT_DIR:-}"
+DURABLE_STATE="${ACCOUNT_DIR:+$ACCOUNT_DIR/.claude/agent-create-state.json}"
+
+# Read stdin (tool call JSON from Claude Code hook protocol)
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c \
+  "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" \
+  2>>"$GATE_LOG" || echo "")
+
+# ── STATE CREATION: plugin-read for public-agent-manager ──
+
+if [[ "$TOOL_NAME" == "mcp__admin__plugin-read" ]]; then
+  MATCHES_PAM=$(echo "$INPUT" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+ti = d.get('tool_input', {})
+plugin = ti.get('pluginName', '')
+file = ti.get('file', '')
+# plugin-read uses pluginName + file, not path
+print('yes' if plugin == 'admin' and file.startswith('skills/public-agent-manager/') else 'no')
+" 2>>"$GATE_LOG" || echo "no")
+
+  if [[ "$MATCHES_PAM" == "yes" ]]; then
+    python3 -c "
+import json, datetime, os, sys
+
+state_file = '$STATE_FILE'
+durable_file = '${DURABLE_STATE:-}'
+log_file = '$GATE_LOG'
+
+state = {
+    'slug': '',
+    'started': datetime.datetime.utcnow().isoformat() + 'Z',
+    'gates': {'soul': False, 'knowledge': False, 'config': False}
+}
+
+try:
+    with open(state_file, 'w') as f:
+        json.dump(state, f)
+except OSError as e:
+    with open(log_file, 'a') as lf:
+        lf.write('agent-creation-gate: ERROR — failed to create volatile state file: %s\n' % e)
+    sys.exit(0)
+
+if durable_file:
+    try:
+        durable_dir = os.path.dirname(durable_file)
+        os.makedirs(durable_dir, exist_ok=True)
+        with open(durable_file, 'w') as f:
+            json.dump(state, f)
+    except OSError as e:
+        with open(log_file, 'a') as lf:
+            lf.write('agent-creation-gate: WARNING — failed to create durable state file: %s\n' % e)
+
+with open(log_file, 'a') as lf:
+    lf.write('agent-creation-gate: workflow started. All gates pending: soul, knowledge, config\n')
+" 2>>"$GATE_LOG" || true
+  fi
+  exit 0
+fi
+
+# ── STATE CLEANUP: delete state when all gated files exist on disk ──
+# Fast path: no state file → nothing to clean up
+[[ -f "$STATE_FILE" ]] || exit 0
+
+if [[ "$TOOL_NAME" == "Write" || "$TOOL_NAME" == "Edit" ]]; then
+  export _HOOK_INPUT="$INPUT"
+  export _STATE_FILE="$STATE_FILE"
+  export _DURABLE_STATE="${DURABLE_STATE:-}"
+  export _GATE_LOG="$GATE_LOG"
+
+  python3 -c '
+import json, os, re, sys
+
+state_file = os.environ.get("_STATE_FILE", "/tmp/maxy-agent-create-state.json")
+durable_file = os.environ.get("_DURABLE_STATE", "")
+log_file = os.environ.get("_GATE_LOG", "/tmp/maxy-gate.log")
+input_raw = os.environ.get("_HOOK_INPUT", "")
+
+def log(msg):
+    try:
+        with open(log_file, "a") as lf:
+            lf.write("agent-creation-post: %s\n" % msg)
+    except OSError:
+        pass
+
+# Parse tool input to get file_path
+try:
+    tool_data = json.loads(input_raw)
+    file_path = tool_data.get("tool_input", {}).get("file_path", "")
+except Exception:
+    sys.exit(0)
+
+# Is this a write to a gated agent file?
+m = re.search(r"agents/([^/]+)/(SOUL\.md|KNOWLEDGE\.md|config\.json)$", file_path)
+if not m or m.group(1) == "admin":
+    sys.exit(0)
+
+# Read state — are all gates true?
+try:
+    with open(state_file) as f:
+        state = json.load(f)
+except Exception:
+    sys.exit(0)
+
+gates = state.get("gates", {})
+if not (isinstance(gates, dict) and all(v is True for v in gates.values())):
+    sys.exit(0)
+
+# All gates true. Check if all three gated files exist on disk.
+agent_dir = os.path.dirname(file_path)
+gated_files = ["SOUL.md", "KNOWLEDGE.md", "config.json"]
+if not all(os.path.isfile(os.path.join(agent_dir, f)) for f in gated_files):
+    sys.exit(0)
+
+# All files exist — creation is complete. Clean up state.
+for f in [state_file, durable_file]:
+    if f:
+        try:
+            os.remove(f)
+        except OSError:
+            pass
+
+slug = state.get("slug", "")
+log("creation complete for \"%s\" — state files cleaned up" % slug)
+' 2>>"$GATE_LOG" || true
+fi
+
+exit 0