@agentuity/claude-code 1.0.5

package/commands/agentuity-cadence.md

@@ -0,0 +1,74 @@
+---
+name: agentuity-cadence
+description: Start a long-running Cadence loop for autonomous task completion (Lead orchestrates with Architect, Memory checkpoints, Product PRD validation)
+argument-hint: "TASK [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/hooks/scripts/setup-cadence.sh:*)"]
+---
+
+First, initialize the Cadence loop by running the setup script with the user's task:
+
+```
+"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/setup-cadence.sh" $ARGUMENTS
+```
+
+After the setup script completes successfully, begin working on the task in Cadence mode.
+
+<cadence-mode>
+
+You are now in **Cadence mode** — a long-running autonomous loop. A Stop hook will keep the loop running automatically. Each time you try to stop, the hook will block the exit and re-inject your task with continuation instructions (including Memory checkpoint triggers).
+
+You will keep working until the task is truly complete. Do NOT stop after a single step.
+
+## Your Team (use Task tool to delegate)
+
+| Agent | subagent_type | Use For |
+|-------|--------------|---------|
+| Scout | agentuity-coder:agentuity-coder-scout | Explore codebase, find patterns (read-only) |
+| Builder | agentuity-coder:agentuity-coder-builder | Quick fixes, simple implementations |
+| Architect | agentuity-coder:agentuity-coder-architect | Complex autonomous implementation (PREFERRED for Cadence) |
+| Reviewer | agentuity-coder:agentuity-coder-reviewer | Review changes, catch issues |
+| Memory | agentuity-coder:agentuity-coder-memory | Store context, checkpoints, corrections |
+| Product | agentuity-coder:agentuity-coder-product | Clarify requirements, validate features, PRD |
+
+## Cadence Workflow
+
+### Phase 1: Setup (do this FIRST)
+
+1. **Establish PRD** — Delegate to Product agent: "Establish the PRD for this task: [task description]. Define requirements, success criteria, and phases."
+2. **Check Memory** — Delegate to Memory agent: "Any context, corrections, or past decisions relevant to [task area]?"
+3. **Plan phases** — Generate a loop ID (format: `lp_short_name_01`), plan your phases
+
+### Phase 2: Iterate (repeat until done)
+
+For each iteration:
+1. **Plan** — What's the next concrete step? (Use extended thinking for complex planning)
+2. **Delegate** — Send work to **Architect** (preferred) or Builder
+3. **Review** — Have Reviewer check the work
+4. **Checkpoint** — Tell Memory: "Store checkpoint for iteration N: [what changed, what's next]"
+5. **Continue** — Move to the next iteration. Do NOT stop.
+
+### Phase 3: Finalize
+
+When truly complete:
+1. Have Reviewer do a final review
+2. Tell Product to validate against the PRD
+3. Tell Memory to memorialize the full session
+4. Output exactly: `<promise>DONE</promise>`
+
+## Completion
+
+When the task is TRULY complete (all requirements met, tests passing, reviewed), output exactly:
+
+<promise>DONE</promise>
+
+This signals the Cadence Stop hook to let the session end. The statement MUST be completely and unequivocally TRUE — do NOT output the promise until the task is genuinely done.
+
+## Critical Rules
+
+- **Keep going.** Each time you finish a step, immediately start the next one. Do not wait for the user.
+- **Use Architect** for implementation — it has deep reasoning, ideal for autonomous work.
+- **Checkpoint every iteration** via Memory — this protects against context loss during compaction.
+- **If stuck**: Try once more with a different approach. If still stuck, explain the blocker and ask the user.
+- **To cancel**: User can run `/agentuity-cadence-cancel` at any time.
+
+</cadence-mode>

package/commands/agentuity-coder.md

@@ -0,0 +1,14 @@
+---
+name: agentuity-coder
+description: Activate the Agentuity Coder team to work on a task with full orchestration (Lead delegates to Scout, Builder, Architect, Reviewer, Memory, Product)
+---
+
+Activate the Agentuity Coder Lead agent to orchestrate this task. Use the Task tool with agent type "agentuity-coder:agentuity-coder-lead" to delegate the user's request.
+
+The Lead agent will:
+1. Classify the request (feature, bug, refactor, research, infra, memory, meta)
+2. Plan the approach
+3. Delegate to specialized agents (Scout, Builder, Architect, Reviewer, Memory, Product)
+4. Synthesize results and report back
+
+Pass the user's full request to the Lead agent.

package/commands/agentuity-memory-save.md

@@ -0,0 +1,14 @@
+---
+name: agentuity-memory-save
+description: Save the current session context to Agentuity Cloud memory (KV + Vector storage) for future recall
+---
+
+Invoke the Agentuity Coder Memory agent to memorialize this session. Use the Task tool with agent type "agentuity-coder:agentuity-coder-memory".
+
+Tell Memory to:
+1. Summarize what was accomplished in this session
+2. Extract key decisions, patterns, and corrections
+3. Store in KV and Vector storage for future recall
+4. Note any open questions or follow-ups
+
+The Memory agent will use Agentuity Cloud KV and Vector storage to persist this session's context.

package/commands/agentuity-memory-share.md

@@ -0,0 +1,31 @@
+---
+name: agentuity-memory-share
+description: Share memory content publicly with a shareable URL via Agentuity Cloud Streams
+---
+
+Share content publicly using Agentuity Cloud Streams.
+
+The user wants to share session content, decisions, or other information publicly with a shareable URL.
+
+## How to share
+
+Use the Bash tool to create a stream with the content:
+
+```
+agentuity cloud stream create --content "<markdown content>" --ttl <duration> --json
+```
+
+TTL options: `1h`, `24h`, `7d`, `30d` (default: `24h`)
+
+## What to share
+
+- **Current session summary**: Compile key decisions, patterns, and outcomes from this conversation
+- **Specific content**: Whatever the user requests (decisions, code review, architecture notes, etc.)
+- **Past session data**: Use the Task tool to delegate to the Memory agent (agentuity-coder:agentuity-coder-memory) to retrieve stored sessions, then share the results
+
+## Guidelines
+
+1. Format the content as clean, readable markdown
+2. Include relevant context (project, branch, date)
+3. Do NOT include secrets, credentials, or PII
+4. Return the shareable URL to the user

package/commands/agentuity-sandbox.md

@@ -0,0 +1,33 @@
+---
+name: agentuity-sandbox
+description: Agentuity sandboxes — isolated execution environments for running code, tests, and builds
+---
+
+Help with Agentuity sandboxes using the `agentuity cloud sandbox` CLI.
+
+## Common Commands
+
+```
+agentuity cloud sandbox runtime list --json                            # List available runtimes
+agentuity cloud sandbox run [--memory 1Gi] [--cpu 1000m] \
+  [--runtime <name>] [--name <name>] -- <command>                      # One-shot execution
+agentuity cloud sandbox create --json [--memory 1Gi] [--cpu 1000m] \
+  [--network] [--runtime <name>] [--name <name>]                       # Create persistent sandbox
+agentuity cloud sandbox list --json                                    # List sandboxes
+agentuity cloud sandbox exec <id> -- <command>                         # Run in existing sandbox
+agentuity cloud sandbox files <id> [path] --json                       # List files
+agentuity cloud sandbox cp ./local <id>:/home/agentuity                # Copy files to sandbox
+agentuity cloud sandbox delete <id> --json                             # Delete sandbox
+agentuity cloud sandbox snapshot create <id> \
+  [--name <name>] [--tag <tag>]                                        # Save sandbox state
+```
+
+## Guidelines
+
+1. First check auth: `agentuity auth whoami`
+2. Use `--json` for programmatic output
+3. Default working directory inside sandboxes: `/home/agentuity`
+4. Use `runtime list` to find runtimes, then pass `--runtime` on `run`/`create`
+5. Use `--name` and `--description` for better tracking
+
+Execute the user's sandbox request using the Bash tool with `agentuity cloud sandbox` commands.

package/dist/install.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @agentuity/claude-code - Agentuity Coder plugin for Claude Code
+ *
+ * Install script that configures the plugin for the current project.
+ * Sets up permissions for Agentuity Cloud CLI commands.
+ */
+export interface InstallConfig {
+    projectId?: string;
+    orgId?: string;
+    region?: string;
+}
+/**
+ * Read agentuity.json from the current project if it exists.
+ */
+export declare function readProjectConfig(): Promise<InstallConfig>;
+/**
+ * Install the Agentuity Coder plugin.
+ * This is called when the plugin is first installed.
+ */
+export declare function install(): Promise<void>;
+export default install;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAuBD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,CAehE;AAoED;;;GAGG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB7C;AAED,eAAe,OAAO,CAAC"}

package/dist/install.js

@@ -0,0 +1,113 @@
+/**
+ * @agentuity/claude-code - Agentuity Coder plugin for Claude Code
+ *
+ * Install script that configures the plugin for the current project.
+ * Sets up permissions for Agentuity Cloud CLI commands.
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+const AGENTUITY_PERMISSIONS = [
+    "Bash(agentuity cloud *)",
+    "Bash(agentuity auth whoami *)",
+];
+const AGENTUITY_DENY_PERMISSIONS = [
+    "Bash(agentuity cloud secrets *)",
+    "Bash(agentuity cloud secret *)",
+    "Bash(agentuity cloud apikey *)",
+    "Bash(agentuity auth token *)",
+];
+/**
+ * Read agentuity.json from the current project if it exists.
+ */
+export async function readProjectConfig() {
+    try {
+        const file = Bun.file("agentuity.json");
+        if (await file.exists()) {
+            const config = await file.json();
+            return {
+                projectId: config.projectId,
+                orgId: config.orgId,
+                region: config.region,
+            };
+        }
+    }
+    catch {
+        // No agentuity.json found or invalid
+    }
+    return {};
+}
+/**
+ * Read a Claude Code settings JSON file.
+ */
+async function readSettings(path) {
+    try {
+        const file = Bun.file(path);
+        if (await file.exists()) {
+            return await file.json();
+        }
+    }
+    catch {
+        // File doesn't exist or is invalid
+    }
+    return {};
+}
+/**
+ * Write a Claude Code settings JSON file.
+ */
+async function writeSettings(path, settings) {
+    await Bun.write(path, JSON.stringify(settings, null, 2) + "\n");
+}
+/**
+ * Ensure Agentuity Cloud permissions are configured in Claude Code settings.
+ * Adds allow rules for agentuity cloud commands and deny rules for sensitive ones.
+ */
+async function configurePermissions() {
+    const settingsPath = join(homedir(), ".claude", "settings.local.json");
+    const settings = await readSettings(settingsPath);
+    if (!settings.permissions) {
+        settings.permissions = {};
+    }
+    if (!settings.permissions.allow) {
+        settings.permissions.allow = [];
+    }
+    if (!settings.permissions.deny) {
+        settings.permissions.deny = [];
+    }
+    let added = 0;
+    for (const perm of AGENTUITY_PERMISSIONS) {
+        if (!settings.permissions.allow.includes(perm)) {
+            settings.permissions.allow.push(perm);
+            added++;
+        }
+    }
+    for (const perm of AGENTUITY_DENY_PERMISSIONS) {
+        if (!settings.permissions.deny.includes(perm)) {
+            settings.permissions.deny.push(perm);
+            added++;
+        }
+    }
+    if (added > 0) {
+        await writeSettings(settingsPath, settings);
+    }
+    return { added };
+}
+/**
+ * Install the Agentuity Coder plugin.
+ * This is called when the plugin is first installed.
+ */
+export async function install() {
+    const config = await readProjectConfig();
+    // Configure Claude Code permissions for Agentuity Cloud commands
+    const { added } = await configurePermissions();
+    if (added > 0) {
+        console.log(`Configured ${added} permission rules for Agentuity Cloud commands`);
+    }
+    if (config.projectId) {
+        console.log(`Agentuity Coder configured for project: ${config.projectId}`);
+    }
+    else {
+        console.log("Agentuity Coder installed (no agentuity.json found - will use session-start hook for context)");
+    }
+}
+export default install;
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/hooks/hooks.json

@@ -0,0 +1,67 @@
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/block-sensitive-commands.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ],
+  "PreCompact": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-compact.sh",
+          "timeout": 10
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/cadence-stop.sh",
+          "timeout": 15
+        },
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop-memory-save.sh",
+          "timeout": 10
+        }
+      ]
+    }
+  ],
+  "SessionStart": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
+          "timeout": 15
+        }
+      ]
+    }
+  ],
+  "SessionEnd": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-end.sh",
+          "timeout": 30
+        }
+      ]
+    }
+  ]
+}

package/hooks/scripts/block-sensitive-commands.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block sensitive agentuity commands (secrets, apikeys, tokens).
+#
+# NOTE: CLI plugin hooks can only BLOCK commands (exit 2 = block).
+# Auto-allowing is handled via permissions.allow in settings.local.json,
+# which is configured by the install script (src/install.ts).
+#
+# Exit 0 = don't interfere (let normal permission rules handle it).
+# Exit 2 + JSON to stderr = block the command.
+
+INPUT=$(cat)
+
+# Use jq if available, fall back to grep
+if command -v jq &>/dev/null; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+else
+  COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/')
+fi
+
+# If we can't extract the command, don't interfere
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Block sensitive commands
+case "$COMMAND" in
+  *"agentuity cloud secret"*|*"agentuity cloud secrets"*)
+    echo '{"decision":"block","reason":"Blocked: agentuity cloud secrets access is not allowed by the Agentuity Coder plugin"}' >&2
+    exit 2
+    ;;
+  *"agentuity cloud apikey"*)
+    echo '{"decision":"block","reason":"Blocked: agentuity cloud apikey access is not allowed by the Agentuity Coder plugin"}' >&2
+    exit 2
+    ;;
+  *"agentuity auth token"*)
+    echo '{"decision":"block","reason":"Blocked: agentuity auth token access is not allowed by the Agentuity Coder plugin"}' >&2
+    exit 2
+    ;;
+esac
+
+# For anything else, don't interfere — permission rules in settings.local.json
+# handle auto-allowing agentuity cloud commands.
+exit 0

package/hooks/scripts/cadence-stop.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# Cadence Stop Hook: Keeps the Cadence loop running until completion.
+#
+# Checks for active Cadence state file (.claude/agentuity-cadence.local.md).
+# If active:
+#   - Reads the last assistant message from the transcript
+#   - Checks for <promise>DONE</promise> completion signal
+#   - Checks max iterations
+#   - If continuing: saves state to KV, blocks stop, re-injects prompt
+#   - If done: saves final state to KV, allows stop
+# If not active: allows stop normally (exit 0)
+#
+# State is persisted to Agentuity Cloud KV at each iteration for cross-session
+# recall and crash recovery. Local file is the control mechanism; KV is durable storage.
+#
+# Exit 0 = allow stop (no active cadence, or task complete)
+# Exit 2 + JSON with decision:block = prevent stop and re-inject prompt
+
+INPUT=$(cat)
+
+# State file location (following Ralph Wiggum convention)
+STATE_FILE=".claude/agentuity-cadence.local.md"
+
+# If no active Cadence session, allow normal stop
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+# Parse YAML frontmatter from state file
+LOOP_ID=$(sed -n '/^---$/,/^---$/{ /^loop_id:/s/loop_id: *//p }' "$STATE_FILE" | tr -d '"')
+ITERATION=$(sed -n '/^---$/,/^---$/{ /^iteration:/s/iteration: *//p }' "$STATE_FILE")
+MAX_ITERATIONS=$(sed -n '/^---$/,/^---$/{ /^max_iterations:/s/max_iterations: *//p }' "$STATE_FILE")
+COMPLETION_PROMISE=$(sed -n '/^---$/,/^---$/{ /^completion_promise:/s/completion_promise: *//p }' "$STATE_FILE" | tr -d '"')
+CREATED_AT=$(sed -n '/^---$/,/^---$/{ /^created_at:/s/created_at: *//p }' "$STATE_FILE")
+
+# Defaults
+LOOP_ID=${LOOP_ID:-unknown}
+ITERATION=${ITERATION:-1}
+MAX_ITERATIONS=${MAX_ITERATIONS:-50}
+COMPLETION_PROMISE=${COMPLETION_PROMISE:-DONE}
+CREATED_AT=${CREATED_AT:-unknown}
+
+# Validate iteration is numeric
+if ! [[ "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "Cadence error: Invalid iteration '$ITERATION'. Removing state file." >&2
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+if ! [[ "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "Cadence error: Invalid max_iterations '$MAX_ITERATIONS'. Removing state file." >&2
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+# Get git branch for context
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Helper: save cadence state to KV
+save_to_kv() {
+  local status="$1"
+  if command -v agentuity &>/dev/null && [ "$LOOP_ID" != "unknown" ]; then
+    KV_STATE=$(jq -n \
+      --arg loopId "$LOOP_ID" \
+      --arg branch "$GIT_BRANCH" \
+      --arg createdAt "$CREATED_AT" \
+      --arg lastActivity "$NOW" \
+      --argjson iteration "$ITERATION" \
+      --argjson maxIterations "$MAX_ITERATIONS" \
+      --arg completionPromise "$COMPLETION_PROMISE" \
+      --arg status "$status" \
+      '{
+        loopId: $loopId,
+        branch: $branch,
+        iteration: $iteration,
+        maxIterations: $maxIterations,
+        completionPromise: $completionPromise,
+        status: $status,
+        startedAt: $createdAt,
+        lastActivity: $lastActivity
+      }')
+    agentuity cloud kv set agentuity-opencode-memory "cadence:${LOOP_ID}" "$KV_STATE" --region use 2>/dev/null || true
+  fi
+}
+
+# Check max iterations
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "Cadence: Max iterations ($MAX_ITERATIONS) reached. Loop complete." >&2
+  save_to_kv "completed_max_iterations"
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+# Check for completion promise in transcript
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  # Get the last assistant message
+  LAST_ASSISTANT=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1 2>/dev/null)
+
+  if [ -n "$LAST_ASSISTANT" ]; then
+    LAST_TEXT=$(echo "$LAST_ASSISTANT" | jq -r '
+      .message.content |
+      map(select(.type == "text")) |
+      map(.text) |
+      join("\n")
+    ' 2>/dev/null)
+
+    # Check for completion promise using perl (handles multiline)
+    if [ -n "$LAST_TEXT" ]; then
+      PROMISE_TEXT=$(echo "$LAST_TEXT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/\1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null)
+
+      if [ -n "$PROMISE_TEXT" ] && [ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]; then
+        echo "Cadence: Completion detected (<promise>$COMPLETION_PROMISE</promise>). Loop finished." >&2
+        save_to_kv "completed"
+        rm -f "$STATE_FILE"
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# Extract the original prompt (everything after the second --- delimiter)
+PROMPT_TEXT=$(awk 'BEGIN{c=0} /^---$/{c++; next} c>=2{print}' "$STATE_FILE")
+
+if [ -z "$PROMPT_TEXT" ]; then
+  echo "Cadence error: No prompt found in state file. Removing." >&2
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+# Increment iteration
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Update state file atomically
+sed "s/^iteration: *[0-9]*/iteration: $NEXT_ITERATION/" "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+
+# Save iteration state to KV
+ITERATION=$NEXT_ITERATION
+save_to_kv "active"
+
+# Build system message
+SYSTEM_MSG="Cadence iteration ${NEXT_ITERATION}/${MAX_ITERATIONS} | Loop: ${LOOP_ID} | Branch: ${GIT_BRANCH} | To complete: output <promise>${COMPLETION_PROMISE}</promise>"
+
+# Build continuation prompt with Memory checkpoint trigger
+read -r -d '' CONTINUATION << CONT_EOF || true
+[CADENCE CONTINUATION - Iteration ${NEXT_ITERATION}/${MAX_ITERATIONS}]
+
+You are in Cadence mode. Loop ID: ${LOOP_ID}. This is iteration ${NEXT_ITERATION} of ${MAX_ITERATIONS}.
+
+BEFORE continuing work, checkpoint with Memory:
+- Use the Task tool: subagent_type=agentuity-coder:agentuity-coder-memory
+- Prompt: "Checkpoint iteration ${ITERATION} for loop ${LOOP_ID}: Store what was accomplished and what's next. Update the cadence record in KV (key: cadence:${LOOP_ID}, namespace: agentuity-opencode-memory). Read the existing record, append this checkpoint to the checkpoints array, and save back. Branch: ${GIT_BRANCH}"
+
+Then continue working on the task below. Pick up where you left off — do NOT restart from the beginning.
+
+When the task is TRULY complete (all requirements met, tests passing, reviewed):
+1. Have Reviewer do a final review
+2. Have Product validate against the PRD
+3. Tell Memory to memorialize the full session (save to KV and Vector)
+4. Output: <promise>${COMPLETION_PROMISE}</promise>
+
+## Original Task
+
+${PROMPT_TEXT}
+CONT_EOF
+
+# Output JSON to block stop and re-inject the prompt
+jq -n \
+  --arg reason "$CONTINUATION" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $reason,
+    "systemMessage": $msg
+  }'
+
+exit 2

package/hooks/scripts/pre-compact.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PreCompact hook: Inject memory-save instructions before context compaction.
+#
+# When Claude Code compacts context (auto or manual), this hook adds
+# additionalContext instructing the LLM to save important session context
+# via the Memory agent before the compaction erases it.
+#
+# Output: JSON with additionalContext field to stdout.
+
+INPUT=$(cat)
+
+# Check if agentuity CLI is available
+if ! command -v agentuity &>/dev/null; then
+  exit 0
+fi
+
+# Get current git branch for context
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+
+cat <<EOF
+{
+  "additionalContext": "[COMPACTION IMMINENT — SAVE CONTEXT NOW]\n\nContext is about to be compacted. You MUST delegate to the Memory agent BEFORE compaction erases conversation history.\n\nUse the Task tool with these parameters:\n- subagent_type: agentuity-coder:agentuity-coder-memory\n- description: Save pre-compaction memory\n- prompt: \"COMPACTION IMMINENT. You are being invoked automatically before context compaction. Review the conversation above and perform these steps:\\n\\n1. Create/update session record in KV (session:{sessionId}) with: title, summary, decisions[], corrections[], files[], and append to compactions[] array\\n2. Extract corrections/mistakes as separate KV entries (correction:{name}) — these are HIGH PRIORITY\\n3. Extract key decisions as KV entries (decision:{name})\\n4. Upsert FULL session document to Vector (agentuity-opencode-sessions) as readable markdown — NOT a summary, the FULL content\\n5. Apply reasoning: extract explicit, deductive, inductive, abductive conclusions and update entity representations\\n6. Branch: ${GIT_BRANCH}\\n\\nDo NOT ask questions. Extract and store everything you can. This conversation will be compacted after you finish.\"\n\nThis is CRITICAL — do this immediately before any other work."
+}
+EOF