| 1 | # Claude Code — how its agents, workflows, plugins and skills actually work (parity reference) |
| 2 | |
| 3 | Date: 2026-08-16. Author: the Claude Fable 5 session driving the v0.9.9 |
| 4 | milestone, writing from direct operating knowledge of the Claude Code harness |
| 5 | (CLI/desktop/web, 2026-08). Companion to |
| 6 | [`WORKFLOWS_GOAL_PARITY.md`](WORKFLOWS_GOAL_PARITY.md) (Grok Build + dsh) and |
| 7 | [`AUTO_MODE_PARITY.md`](AUTO_MODE_PARITY.md). This is a *mechanics* reference |
| 8 | for builders on #5439 (orchestration trio visibility), #5311 (plugin system / |
| 9 | federated marketplaces), #5324/#5123 (agent tool surface), and the one-bash |
| 10 | consolidation. Where Codewhale already does the same thing, it says so; where |
| 11 | Claude Code is simply different (not better), it says that too. |
| 12 | |
| 13 | ## 1. Sub-agents: the `Agent` tool |
| 14 | |
| 15 | One tool, a handful of fields. What the model sees: |
| 16 | |
| 17 | | field | meaning | notes | |
| 18 | |---|---|---| |
| 19 | | `prompt` | the task | required | |
| 20 | | `description` | 3–5 word label for the UI | required — the *only* per-spawn UX field | |
| 21 | | `subagent_type` | named agent definition (`Explore`, `Plan`, `general-purpose`, `code-reviewer`, `fork`, plus plugin-provided `plugin:agent`) | omit → general-purpose. `fork` inherits the parent's full context and always runs the parent model | |
| 22 | | `model` | optional override (`sonnet`/`opus`/`haiku`/…) | ignored for `fork`; agent-definition frontmatter normally decides | |
| 23 | | `isolation` | `worktree` (own git worktree, auto-cleaned if unchanged) or `remote` | no path knobs; the harness owns the worktree | |
| 24 | |
| 25 | That is the whole spawn surface. There is **no** `max_steps`, `wall_time`, |
| 26 | `max_depth`, `thinking`, `write_roots`, `fork_context` bool, |
| 27 | `workspace_policy` or `write_authority` on the call. Budgets, tool |
| 28 | allow-lists, model tier and reasoning effort live in the **agent |
| 29 | definition** (`.claude/agents/<name>.md` frontmatter — `model`, `effort`, |
| 30 | `tools`, `description` "when to use") or in the harness. Everything the |
| 31 | parent needs after spawn is a lifecycle, not a knob: |
| 32 | |
| 33 | - Agents run in the background; the parent gets a **completion |
| 34 | notification** and must not fabricate results before it arrives. |
| 35 | - `SendMessage(to: <agent>)` continues an existing agent with its context |
| 36 | intact; a new `Agent` call starts fresh. `ListAgents` enumerates them. |
| 37 | - The final report is *not* shown to the user — the parent relays what |
| 38 | matters. Sub-agent self-reports are treated as working sets, not facts. |
| 39 | - Fork semantics: `subagent_type: "fork"` = same model, same context, |
| 40 | tool output kept out of the parent context. |
| 41 | |
| 42 | **Codewhale mapping.** The `agent` tool already has `action` (spawn/wait/ |
| 43 | message/interrupt/…), `type` (8 roles), `profile`, `name`/`agent_id`/`message`, |
| 44 | `detached`, `worktree`, `resume_from`. That is the same shape as Claude Code's |
| 45 | Agent + SendMessage + ListAgents folded into one tool — fine. The delta is |
| 46 | that Codewhale *also* advertises ~20 budget/authority/model knobs per call. |
| 47 | Claude Code's answer, and the direction chosen for #5324/#5123: budgets and |
| 48 | authority belong to the role/profile definition, model to the operator's |
| 49 | session, and the per-call surface stays at ~12 fields (`action, prompt, |
| 50 | type, profile, name, agent_id, message, detached, worktree, write_roots, |
| 51 | resume_from, until`). Claude Code has no equivalent of `write_roots`; it is |
| 52 | kept because #5426 containment leans on it. |
| 53 | |
| 54 | ## 2. Orchestration: the `Workflow` tool (scripts, not prose) |
| 55 | |
| 56 | A workflow is a **JavaScript script the model writes inline**, executed by the |
| 57 | harness deterministically; it runs in the background and the model gets a |
| 58 | completion notification. The API surface the script sees: |
| 59 | |
| 60 | - `export const meta = { name, description, whenToUse?, phases: [{title, |
| 61 | detail, model?}] }` — pure literal, required first statement. |
| 62 | - `agent(prompt, {label?, phase?, schema?, model?, effort?, isolation?, |
| 63 | agentType?}) → Promise<string | object>` — with `schema` (JSON Schema) the |
| 64 | sub-agent is *forced* to return validated structured output; returns |
| 65 | `null` if the user skipped it or it died. |
| 66 | - `pipeline(items, stage1, stage2, …)` — per-item stages, **no barrier** |
| 67 | between stages (default). `parallel([thunks])` — barrier. `phase(title)`, |
| 68 | `log(msg)`, `args`, `budget {total, spent(), remaining()}` (a hard |
| 69 | ceiling from a "+500k"-style user directive), `workflow(nameOrPath, args)` |
| 70 | (one level of nesting). |
| 71 | - Determinism rules: `Date.now()`, `Math.random()` throw (they would break |
| 72 | resume). Every run persists its script to a file; a run can be resumed by |
| 73 | `{scriptPath, resumeFromRunId}` and the **longest unchanged prefix of |
| 74 | agent() calls is replayed from a journal** (`journal.jsonl` records each |
| 75 | agent's return value) — edit the script, resume, only the changed tail |
| 76 | re-runs. Concurrency cap = min(16, CPUs−2); lifetime cap 1000 agents. |
| 77 | - Named/saved workflows: `.claude/workflows/<name>` resolve by name; the |
| 78 | script is the artifact. Opt-in is explicit: the user must say |
| 79 | "ultracode"/"use a workflow"/invoke a skill that calls it — the model may |
| 80 | not spawn dozens of agents on its own judgment. |
| 81 | - Documented quality patterns (all in the tool's own guidance): adversarial |
| 82 | verify (N refuters per finding), perspective-diverse verify, judge panel, |
| 83 | loop-until-dry, multi-modal sweep, completeness critic, no silent caps. |
| 84 | |
| 85 | **Codewhale mapping.** Codewhale's `workflows/*.workflow.js` + Lane Runtime |
| 86 | is the same idea (Grok uses Rhai; Claude Code uses JS with the API above; dsh |
| 87 | uses YAML presets). What Claude Code does that #5439 asks for: the *user* |
| 88 | sees workflows as first-class objects — `/workflows` lists live runs with |
| 89 | phase groups and per-agent labels, scripts are files you can open, and the |
| 90 | model must announce/relay. The `journal.jsonl` replay-on-resume and the |
| 91 | `schema`-forced structured return are the two engine features worth |
| 92 | copying if they are missing (check `crates/tui/src/workflow*` before |
| 93 | building; do not assume). The "user opts in explicitly" rule is a product |
| 94 | decision Codewhale should keep too: goal/workflow/auto are chosen by the |
| 95 | user, visibly (#5439 acceptance list), never silently. |
| 96 | |
| 97 | ## 3. Loops and schedules |
| 98 | |
| 99 | - `/loop [interval] <prompt|/skill>` — recurring prompt on an interval; with |
| 100 | no interval the model self-paces via `ScheduleWakeup(delaySeconds, noop, |
| 101 | reason)`; quiet ticks are collapsed in the UI. Cron-style `CronCreate` |
| 102 | exists for autonomous loops. |
| 103 | - `/schedule` — cloud "routines" on a cron. |
| 104 | |
| 105 | **Codewhale mapping.** Goal mode + dsh-style ralph loops cover the |
| 106 | "keep going until done" case; the interval loop with a *visible reason |
| 107 | string per wake* is the piece worth adopting for goal status |
| 108 | (`/goal status` should show *why* it is waiting and when it wakes). |
| 109 | |
| 110 | ## 4. Plugins, skills, agents, hooks — the layout that makes them discoverable |
| 111 | |
| 112 | - **Skills** = `SKILL.md` folders (frontmatter `name`, `description` |
| 113 | "use when…"). Loaded via a `Skill` tool by exact name; slash-invocable as |
| 114 | `/<name>`; scoped variants (`apps/web:deploy`) win by directory. The |
| 115 | session lists every available skill with its one-line description at |
| 116 | start — discoverability is a *listing*, not documentation. |
| 117 | - **Agents** = `.claude/agents/<name>.md` (frontmatter `model`, `effort`, |
| 118 | `tools`, description "when to use"). Same listing at session start. |
| 119 | - **Plugins** = a marketplace entry that bundles skills + agents + MCP |
| 120 | servers + hooks under a namespace (`plugin:skill`, `plugin:agent`, MCP |
| 121 | tools `mcp__plugin_<plugin>_<server>__<tool>`). `/plugin` manages |
| 122 | marketplaces (add/list/install/remove); plugin skills show up in the same |
| 123 | listing as local ones, namespaced. Plugin MCP tools are *deferred*: names |
| 124 | are visible, schemas load on demand via `ToolSearch` — the catalog stays |
| 125 | small in the prompt prefix. |
| 126 | - **Hooks** = `settings.json` (`SessionStart`, tool-call intercept, `Stop` |
| 127 | …); hook output is fed back to the model as user-level feedback. |
| 128 | - **CLAUDE.md / AGENTS.md** = per-repo contract, loaded verbatim; user-level |
| 129 | `~/.claude/CLAUDE.md` layers under it. |
| 130 | |
| 131 | **Codewhale mapping.** Codewhale has all four primitives (docs/SKILLS.md, |
| 132 | docs/PLUGINS.md, docs/PLUGIN_BUNDLES.md, docs/HOOKS.md, `plugin.toml`, |
| 133 | `/plugin marketplace …`, `.claude/skills` compat per |
| 134 | docs/CLAUDE_PLUGIN_COMPAT.md). #5311's real gap versus Claude Code / |
| 135 | kimicode is (a) **one namespaced listing** that the model *and* the user see |
| 136 | at session start (skills + agents + plugin-provided ones), (b) parsing |
| 137 | Claude/Kimi marketplace manifests so a plugin can bring agents + hooks + |
| 138 | MCP servers, not only a skill folder, and (c) deferred tool schemas so a |
| 139 | large plugin surface does not bloat the pinned prefix (docs/CACHE.md |
| 140 | constraint). The `.claude-plugin/plugin.json` runtime semantics Codewhale |
| 141 | declines to emulate (docs/CLAUDE_PLUGIN_COMPAT.md) can stay declined; the |
| 142 | manifest *parse* and the namespaced listing are the parity items. |
| 143 | |
| 144 | ## 5. Shell: one tool |
| 145 | |
| 146 | Claude Code exposes exactly one shell tool, `Bash` (`command`, |
| 147 | `description`, `timeout` ms ≤ 600 000, `run_in_background`, an unsandbox |
| 148 | escape flag). Background jobs notify on exit; there is no separate |
| 149 | wait/interact/cancel tool family — a `Monitor` tool watches a condition, |
| 150 | `TaskStop` kills a background task. Interactive flags (`-i`) are refused up |
| 151 | front. Permission is a classifier + allow-rules over the *command string*, |
| 152 | not per-tool-name families. |
| 153 | |
| 154 | **Codewhale mapping.** The one-bash consolidation planner already reached |
| 155 | the same conclusion (7 exec name families → `bash` + a small session |
| 156 | surface). Claude Code adds one detail worth copying: `run_in_background` |
| 157 | on the same tool with completion notifications, rather than a second tool |
| 158 | family for jobs. |
| 159 | |
| 160 | ## 6. What Claude Code does *not* have (Codewhale is ahead) |
| 161 | |
| 162 | - No fleet ledger, no role-based authority clamps (delegation-never-widens |
| 163 | is enforced by prompt + permission classifier, not by a typed envelope). |
| 164 | - No provider-portable model routing; the model column is one vendor. |
| 165 | - No `/goal` state machine with pause kinds; long-running autonomy is |
| 166 | `/loop` + judgment. |
| 167 | - No transcript-visible tool-lifecycle contract; retired tool names simply |
| 168 | vanish. |
| 169 | |
| 170 | ## 7. Concrete asks this note supports |
| 171 | |
| 172 | 1. #5324/#5123 — 12-field agent tool; budgets to roles/profiles/config |
| 173 | (matches §1). |
| 174 | 2. #5439 — `/workflow` no-arg catalog + live-run view; trio visible in the |
| 175 | mode picker with "when to use" copy (matches §2/§3 product rule: |
| 176 | user chooses, visibly). |
| 177 | 3. #5311 — namespaced skill/agent/plugin listing at session start; parse |
| 178 | Claude + Kimi marketplace manifests; deferred tool schemas (matches §4). |
| 179 | 4. One-bash — `bash` + `run_in_background` + completion notifications; |
| 180 | compat window for hidden legacy names ends at a version boundary |
| 181 | (matches §5). |
| 182 |