thoth-agents 0.1.18 → 0.2.0

package/README.md

@@ -15,14 +15,16 @@
 
 thoth-agents is a delegate-first agent system for coding harnesses. It started
 as an OpenCode plugin and now provides a shared seven-agent workflow for
-OpenCode and Codex, with each harness getting the integration surface that fits
-it best.
+OpenCode, Codex, and Claude Code, with each harness getting the integration
+surface that fits it best.
 
 OpenCode remains the stable default path: native plugin install, native `task`
 delegation, optional tmux monitoring, and generated config. Codex is supported
 through an explicit agent-pack and Personal plugin setup path, with documented
 trust review and instruction-level governance caveats where Codex does not
-provide the same hard runtime controls.
+provide the same hard runtime controls. Claude Code is a first-class path: a
+single auto-discovered plugin package with native subagents, harness-enforced
+hooks, MCP, skills, and per-agent tool permissions.
 
 ## What It Is
 
@@ -52,6 +54,7 @@ provide the same hard runtime controls.
 | --- | --- | --- | --- |
 | OpenCode | Stable default | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native `task` delegation, optional tmux panes, OpenCode provider auth. |
 | Codex | Supported explicit path | `npx thoth-agents@latest install --agent=codex` | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires `/plugins` and `/hooks` trust review. Some governance remains instruction-level. |
+| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude` | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
 
 OpenCode can load the plugin with:
 
@@ -123,6 +126,35 @@ Codex install does not create a selectable orchestrator TOML, does not bypass
 trust review, and does not make role permissions or memory governance hard
 runtime guarantees unless Codex exposes those controls.
 
+### Claude Code
+
+Preview, then install the plugin package:
+
+```bash
+npx thoth-agents@latest install --agent=claude --dry-run
+npx thoth-agents@latest install --agent=claude
+```
+
+This writes a single Claude Code **skills-directory plugin** under
+`~/.claude/skills/thoth-agents`: `.claude-plugin/plugin.json`, seven
+auto-discovered agents in `agents/` (six specialists + an `orchestrator`), an
+`.mcp.json` server map, bundled `skills/`, and a plugin-root `settings.json`
+with `{ "agent": "orchestrator" }`. That `agent` key activates the orchestrator
+as the **main thread** — replacing the default system prompt — so the session
+starts in delegate-first mode and bootstraps thoth-mem on its first turn. It
+auto-loads as `thoth-agents@skills-dir` on the next session (no marketplace or
+install step); restart Claude Code or run `/reload-plugins` to activate it
+(confirm in `/plugin` → Installed). The orchestrator delegates to specialists
+with `Task(subagent_type: explorer|librarian|oracle|designer|quick|deep)`. Role
+permissions are enforced through each specialist's frontmatter `tools` allowlist.
+You can also emit the package without installing it:
+
+```bash
+npx thoth-agents@latest generate --harness=claude --dry-run
+```
+
+See [docs/claude-code-plugin-packaging.md](docs/claude-code-plugin-packaging.md).
+
 ### Reset Generated Config
 
 ```bash
@@ -301,9 +333,20 @@ Artifacts can be persisted in four modes:
 Thoth-mem is the local memory MCP used for durable observations, architectural
 decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
 
-1. `mem_search` for compact candidate records
-2. `mem_timeline` for chronological context
-3. `mem_get_observation` for the full selected record
+1. `mem_recall(mode="compact")` for compact candidate records
+2. `mem_recall(mode="context")` for expanded retrieved context
+3. `mem_get(...)` for the full selected record; use
+   `mem_get(include_timeline=true)` when chronology matters
+
+Use HyDE/fused hybrid recall (sentence + chunk vectors, FTS, KG enrichment) for
+semantic or ambiguous searches; set `mem_recall` `limit` from 1 to 20; narrow
+with `topic_key`, `type`, `time_from`, `time_to`, `scope`, `project`, and
+`session_id` filters. Use `mem_get` with `kind="observation"|"prompt"`,
+`include_timeline=true` plus `before`/`after`, and `offset`/`max_length` for
+large content. Use bounded `mem_context(recall_query=...)` or
+`mem_project(action="graph"|"topics"|"topic")` for supplemental project
+context; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`,
+`HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.
 
 ## Skills And MCPs
 
@@ -312,12 +355,12 @@ planning/execution, verification, and archiving. It also registers MCP servers
 for docs research, public code search, and local memory where the harness
 supports that delivery surface.
 
-| Surface | Shared concept | OpenCode binding | Codex binding |
-| --- | --- | --- | --- |
-| Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when `--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source |
-| MCPs | `exa`, `context7`, `grep_app`, `thoth_mem` | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces |
-| Delegation | Seven-role specialist workflow | Native `task` tool | Custom agents plus prompt/plugin guidance |
-| Blocking choices | Use a structured question surface | OpenCode `question` tool | `request_user_input` when enabled and available |
+| Surface | Shared concept | OpenCode binding | Codex binding | Claude Code binding |
+| --- | --- | --- | --- | --- |
+| Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when `--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin `skills/` directory |
+| MCPs | `exa`, `context7`, `grep_app`, `thoth_mem` | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces | Bundled in the plugin `.mcp.json` (`type: "http"` for URL servers) |
+| Delegation | Seven-role specialist workflow | Native `task` tool | Custom agents plus prompt/plugin guidance | Native `Task(subagent_type: ...)` over auto-discovered subagents |
+| Blocking choices | Use a structured question surface | OpenCode `question` tool | `request_user_input` when enabled and available | `AskUserQuestion` tool |
 
 See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.
 

package/dist/agents/prompt-dialects.d.ts

@@ -22,7 +22,16 @@ export interface HarnessPromptDialect {
     renderRoleInvocation(role: AgentPromptRole): string;
 }
 export declare const CODEX_PROMPT_CAPABILITIES: HarnessCapabilities;
+export declare const CLAUDE_CODE_PROMPT_CAPABILITIES: HarnessCapabilities;
 export declare const OPENCODE_PROMPT_DIALECT: HarnessPromptDialect;
 export declare const CODEX_PROMPT_DIALECT: HarnessPromptDialect;
+/**
+ * Claude Code registers plugin subagents under the plugin name as a namespace,
+ * so the `subagent_type` for delegation is `thoth-agents:<role>`, not the bare
+ * role name. This must match the plugin manifest `name`.
+ */
+export declare const CLAUDE_CODE_SUBAGENT_NAMESPACE = "thoth-agents";
+export declare function claudeCodeSubagentType(role: AgentPromptRole): string;
+export declare const CLAUDE_CODE_PROMPT_DIALECT: HarnessPromptDialect;
 export declare function getPromptDialect(harness: HarnessId): HarnessPromptDialect;
 export declare function getPromptDialect(harness: string): HarnessPromptDialect;

package/dist/{chunk-6K3ZXIMC.js → chunk-3NOVCFN7.js}

@@ -459,6 +459,11 @@ var CodexGenerationConfigSchema = z.object({
   outputRoot: z.string().optional(),
   dryRun: z.boolean().default(true)
 });
+var ClaudeCodeGenerationConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  outputRoot: z.string().optional(),
+  dryRun: z.boolean().default(true)
+});
 var FailoverConfigSchema = z.object({
   enabled: z.boolean().default(true),
   timeoutMs: z.number().min(0).default(15e3),
@@ -479,7 +484,8 @@ var PluginConfigSchema = z.object({
   fallback: FailoverConfigSchema.optional(),
   thoth: ThothConfigSchema.optional(),
   artifactStore: ArtifactStoreConfigSchema.optional(),
-  codex: CodexGenerationConfigSchema.optional()
+  codex: CodexGenerationConfigSchema.optional(),
+  claudeCode: ClaudeCodeGenerationConfigSchema.optional()
 });
 
 // src/config/loader.ts
@@ -653,6 +659,13 @@ function getAgentOverride(config, name) {
   const overrides = config?.agents ?? {};
   return overrides[name] ?? overrides[Object.keys(AGENT_ALIASES).find((k) => AGENT_ALIASES[k] === name) ?? ""];
 }
+function getPrimaryModelId(model) {
+  if (Array.isArray(model)) {
+    const first = model[0];
+    return typeof first === "string" ? first : first?.id;
+  }
+  return model;
+}
 
 // src/agents/prompt-dialects.ts
 var OPENCODE_CAPABILITIES = {
@@ -677,6 +690,17 @@ var CODEX_PROMPT_CAPABILITIES = {
   parentContextInjection: "instruction-only",
   memoryGovernanceEnforcement: "instruction-only"
 };
+var CLAUDE_CODE_PROMPT_CAPABILITIES = {
+  agentDefinitions: "supported",
+  delegatedExecution: "supported",
+  parallelDelegation: "supported",
+  runtimeHooks: "supported",
+  mcpConfiguration: "supported",
+  skillPackaging: "supported",
+  rolePermissions: "supported",
+  parentContextInjection: "supported",
+  memoryGovernanceEnforcement: "supported"
+};
 function supportedCapabilityProfile(capabilities) {
   return {
     capabilities,
@@ -748,6 +772,36 @@ var CODEX_PROMPT_DIALECT = {
     return role === "orchestrator" ? "orchestrator role agent" : `${role} subagent`;
   }
 };
+var CLAUDE_CODE_SUBAGENT_NAMESPACE = "thoth-agents";
+function claudeCodeSubagentType(role) {
+  return `${CLAUDE_CODE_SUBAGENT_NAMESPACE}:${role}`;
+}
+var CLAUDE_CODE_PROMPT_DIALECT = {
+  harness: "claude",
+  tools: {
+    delegationTool: "Task",
+    backgroundDelegationTool: "Task(run_in_background=true)",
+    backgroundStatusTool: "TaskOutput",
+    userQuestionTool: "AskUserQuestion",
+    progressTool: "TodoWrite",
+    hostStatusSurface: "TodoWrite",
+    roleReference: (role) => role === "orchestrator" ? "the main-thread orchestrator" : `Task(subagent_type: ${claudeCodeSubagentType(role)})`
+  },
+  capabilities: supportedCapabilityProfile(CLAUDE_CODE_PROMPT_CAPABILITIES),
+  dispatchLabel(method) {
+    switch (method) {
+      case "root-coordinator":
+        return "main-session coordinator";
+      case "task":
+        return "Task tool";
+      case "synchronous-task-only":
+        return "synchronous Task only";
+    }
+  },
+  renderRoleInvocation(role) {
+    return role === "orchestrator" ? "main-thread orchestrator" : claudeCodeSubagentType(role);
+  }
+};
 
 // src/harness/core/sdd.ts
 var SDD_PHASES = [
@@ -954,7 +1008,7 @@ function createStepBudgetSection(steps) {
   return { kind: "step-budget", steps };
 }
 function detectModelFamilyFromModel(model) {
-  const id = getPrimaryModelId(model)?.toLowerCase();
+  const id = getPrimaryModelId2(model)?.toLowerCase();
   if (!id) {
     return void 0;
   }
@@ -1098,9 +1152,9 @@ Push back when context, risk, or assumptions are weak. Avoid verbosity.
 </epistemic-rigor>
 
 <session-bootstrap>
-- At the start of a new root session, when thoth-mem tools are available, load \`thoth-mem-agents\` and \`requirements-interview\`, call \`mem_session_start\` with the current project and session identity, then save the real user prompt with \`mem_save_prompt\`.
-- Save only the real user request with \`mem_save_prompt\`; never save generated sub-agent prompts, handoffs, summaries, or tool scaffolding as user intent.
-- If thoth-mem tools or required session/project identity are unavailable, disclose that memory bootstrap could not run and continue without pretending memory was saved.
+- At the start of a new root session, when thoth-mem tools and session/project identity are available, load \`thoth-mem-agents\` and \`requirements-interview\`, then call \`mem_session(action="start")\` as step 0 before any other thoth-mem call.
+- Save only the real user request with \`mem_save(kind="prompt")\`; never save generated sub-agent prompts, handoffs, summaries, or tool scaffolding as user intent.
+- If thoth-mem tools or required session/project identity are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.
 </session-bootstrap>
 
 <routing>
@@ -1136,9 +1190,9 @@ Before dispatching {{role.designer}}, {{role.quick}}, or {{role.deep}} after dis
 
 Internal handoff fields: Goal, Decision, Evidence, Scope, Steps, Verification, Uncertainty, relevant files or symbols, suggested skills when applicable, constraints, non-goals, escalation conditions, and next focus.
 
-When thoth-mem session-summary tooling and parent session/project identity are available, save or refresh that handoff body with root-owned \`mem_session_summary\` before dispatch. If the tooling or identity is unavailable, disclose that root-owned compaction could not be persisted and continue with explicit task instructions and local context; do not invent a fallback session or ask a sub-agent to create one.
+When thoth-mem summary persistence and parent session/project identity are available, save or refresh that handoff body with root-owned \`mem_session(action="summary")\` or \`mem_save(kind="session_summary")\` before dispatch. If tooling or identity is unavailable, disclose that root-owned compaction could not be persisted and continue with explicit task instructions and local context; do not invent a fallback session or ask a sub-agent to create one.
 
-The delegated prompt carries task instructions plus handoff recovery instructions only: parent \`session_id\`, project, persistence mode, memory permissions, bounded 3-layer recall steps, non-goals, escalation conditions, and redaction requirements. It must not include the handoff body, raw transcripts, file dumps, secrets, credentials, irrelevant context, or generated sub-agent prompts as memory source material.
+The delegated prompt carries task instructions plus handoff recovery instructions only: parent \`session_id\`, project, persistence mode, memory permissions, the recall funnel \`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`, optional bounded \`mem_context(recall_query=...)\`/\`mem_project(...)\` guidance when permitted, non-goals, escalation conditions, and redaction requirements. It must not include the handoff body, raw transcripts, file dumps, secrets, credentials, irrelevant context, or generated sub-agent prompts as memory source material.
 
 Never mention internal handoff preparation to the user, ask the user to prepare it, or present handoff preparation as the recommended next step. Describe the actual work instead.
 
@@ -1199,12 +1253,15 @@ Post-execution: delegate sdd-verify, then sdd-archive when verification passes.
 <progress-memory>
 - Keep {{progressTool}} top-level and lean for multi-step work.
 - When SDD is active, update both {{progressTool}} and openspec/changes/{change-name}/tasks.md before dispatch and after results.
-- Root-session memory is yours: search before repeated work; save durable decisions, discoveries, bugs, patterns, constraints, and session summaries.
-- Durable \`mem_save\`: save durable decisions, bug root causes, discoveries, conventions, config changes, and preferences. Use stable topic keys; keep general observations outside \`sdd/*\`.
-- Targeted 3-layer recall protocol: \`mem_search\` compact -> \`mem_timeline\` -> \`mem_get_observation\` only for records needed in full.
+- Root-session memory is yours: recall repeated work; save durable decisions, discoveries, bugs, patterns, constraints, summaries.
+- Use \`mem_save(kind="observation")\` for decisions, bugs, discoveries, conventions, preferences; stable topics; observations outside \`sdd/*\`.
+- Targeted recall funnel: \`mem_recall(mode="compact")\` -> \`mem_recall(mode="context")\` -> \`mem_get(...)\`; use \`mem_get(include_timeline=true)\` for time context.
+- Use HyDE/fused recall; set \`mem_recall\` \`limit\` from 1 to 20; narrow with \`topic_key\`, \`type\`, \`time_from\`/\`time_to\`, \`scope\`, \`project\`, \`session_id\`.
+- \`mem_get\`: \`kind="observation"|"prompt"\`, \`include_timeline=true\`, \`before\`/\`after\`, \`offset\`/\`max_length\`; supplement with bounded \`mem_context(recall_query=...)\` or \`mem_project(action="graph"|"topics"|"topic")\`.
+- Graph relations: HAS_TYPE, IN_PROJECT, HAS_TOPIC_KEY, HAS_WHAT, HAS_WHY, HAS_WHERE, HAS_LEARNED.
 - SDD memory artifacts use deterministic topic keys only in thoth-mem or hybrid persistence modes: \`sdd/{change}/{artifact}\`.
-- Before ending the root session, call \`mem_session_summary\` with a concise Goal, Instructions, Discoveries, Accomplished, Next Steps, and Relevant Files summary. Do not claim memory was saved unless the tool call succeeded.
-- After compaction, first preserve the compacted summary with \`mem_session_summary\`, then recover recent context and use the 3-layer recall protocol before continuing work.
+- Before ending the root session, call \`mem_session(action="summary")\` or root-owned \`mem_save(kind="session_summary")\` with a concise Goal, Instructions, Discoveries, Accomplished, Next Steps, and Relevant Files summary. Do not claim memory was saved unless the tool call succeeded.
+- After compaction, first preserve the compacted summary with \`mem_session(action="summary")\`, then call \`mem_context(recall_query=...)\` and use the recall funnel before continuing work.
 </progress-memory>
 
 <communication>
@@ -1355,7 +1412,7 @@ For non-SDD work: summary + files changed + verification results + edge cases co
 - Target: under 40 lines total.`
   });
 }
-function getPrimaryModelId(model) {
+function getPrimaryModelId2(model) {
   if (Array.isArray(model)) {
     const first = model[0];
     return typeof first === "string" ? first : first?.id;
@@ -1376,32 +1433,30 @@ function renderSubagentRules(section, dialect) {
   ];
   if (section.memoryAccess === "readonly") {
     rules.push(
-      "- Use read-only thoth-mem only when dispatch gives parent session_id/project and handoff recovery instructions: `mem_search` -> `mem_timeline` -> `mem_get_observation`.",
-      "- The canonical recall path remains `mem_search` -> `mem_timeline` -> `mem_get_observation`; use bounded context tools only as supplemental context when explicitly allowed.",
-      "- If either parent session_id or project is missing, do NOT call thoth-mem; rely on explicit task instructions and local evidence.",
-      "- Recover the parent-session handoff summary through bounded 3-layer recall before treating memory as source material.",
+      "- Use read-only thoth-mem only when dispatch gives parent session_id/project and handoff recovery instructions.",
+      "- Parent-scoped reads: `mem_recall`, `mem_context`, `mem_get`, bounded `mem_project`; do not call `mem_save` or own any `mem_session(...)` lifecycle action.",
+      "- If either parent session_id or project is missing, do NOT call thoth-mem; rely on task instructions and local evidence.",
+      '- Recover the parent-session handoff summary through the recall funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)` before using memory.',
+      '- Use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true`, `before`/`after`, and `offset`/`max_length`.',
       "- Report when recalled context is missing, stale, contradictory, or insufficient.",
-      "- Use project-scoped read tools (`mem_context`, `mem_project_summary`, `mem_project_graph`, `mem_topic_keys`) only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
-      "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
-      "- Never save generated subagent prompts as user intent.",
-      "- Never write memory; memory writes are orchestrator-owned."
+      '- Supplemental `mem_context(recall_query=...)` and bounded `mem_project(action="graph"|"topics"|"topic")` do not replace the recall funnel and require explicit delegated permission. Graph relations: `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, `HAS_LEARNED`.',
+      "- Never save prompts, generated subagent prompts, session summaries, or durable memory."
     );
   }
   if (section.memoryAccess === "writable") {
     rules.push(
-      "- Use delegated thoth-mem tools only (mem_save, mem_search, mem_get_observation, mem_timeline, mem_context, mem_project_summary, mem_project_graph, mem_topic_keys, mem_suggest_topic_key).",
-      "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
+      "- Use delegated thoth-mem tools only: `mem_save`, `mem_recall`, `mem_context`, `mem_get`, `mem_project`, `mem_session`.",
       "- Always use the parent session_id/project from dispatch for every thoth-mem call.",
       "- If either is missing, do NOT call thoth-mem.",
       "- Follow handoff recovery instructions from the delegated task before using persisted memory.",
-      "- For reads, use only `mem_search` -> `mem_timeline` -> `mem_get_observation` and recover the parent-session handoff summary before treating memory as source material.",
-      "- Keep 3-layer recall canonical; use `mem_context`, `mem_project_summary`, `mem_project_graph`, and `mem_topic_keys` only as bounded supplemental context when the dispatch explicitly permits project-scoped reads.",
+      '- For reads, use the recall funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)` and recover the parent-session handoff summary before treating memory as source material.',
+      '- Use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true`, `before`/`after`, and `offset`/`max_length`.',
+      '- Keep the recall funnel canonical; use `mem_context(recall_query=...)` and bounded `mem_project(action="graph"|"topics"|"topic")` only with explicit project-read permission. Graph relations: `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, `HAS_LEARNED`.',
       "- Report when recalled context is missing, stale, contradictory, or insufficient.",
-      "- Use project-scoped read tools only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
-      "- `mem_save` is allowed only for delegated durable implementation observations or assigned SDD artifacts/apply-progress under the parent session/project.",
+      '- `mem_save(kind="observation")` is allowed only for delegated durable implementation observations or assigned deterministic SDD artifacts/apply-progress under the parent session/project.',
+      '- Never own `mem_session(action="start"|"checkpoint"|"summary")`, save prompts, or save generated subagent prompts as user intent.',
       "- Protect the `sdd/*` namespace: deterministic SDD artifacts use `sdd/{change}/{artifact}`; general durable observations must stay outside `sdd/*`.",
-      "- Never save generated subagent prompts as user intent.",
-      "- You do not own durable memory of your own; `mem_save` writes under the orchestrator's session/project only."
+      '- You do not own durable memory of your own; permitted `mem_save(kind="observation")` writes under the orchestrator\'s session/project only.'
     );
   }
   return rules.join("\n");
@@ -2125,8 +2180,12 @@ export {
   loadPluginConfig,
   loadAgentPrompt,
   getAgentOverride,
+  getPrimaryModelId,
   OPENCODE_PROMPT_DIALECT,
   CODEX_PROMPT_DIALECT,
+  CLAUDE_CODE_SUBAGENT_NAMESPACE,
+  claudeCodeSubagentType,
+  CLAUDE_CODE_PROMPT_DIALECT,
   createStepBudgetSection,
   createModelFamilySection,
   createOrchestratorPromptSections,