feat(skill): add the agent-skill install layer and harden the packaged skill

Ship `skills/codeman` as an installable Claude Code skill rather than a
repo-only reference, and fix six defects found while verifying it live.

Install layer:
- `codeman skill install [--case <name>]` / `codeman skill uninstall`.
  Case names resolve through linked-cases.json first, mirroring the
  server's resolveCasePath(), so a case linked in from outside
  ~/codeman-cases no longer fails with "Case not found".
- applyAgentSkill() / installAgentSkillInto() / removeAgentSkillFrom() in
  hooks-config.ts. Copies are marker-owned, so an unmarked user-authored
  skill is never touched, and a symlinked skill dir is refused (this
  repo's own .claude/skills/codeman is a symlink to the source).
- Synced `agentSkillEnabled` setting, default OFF: schemas.ts,
  ports/config-port.ts, server.ts, session-routes.ts (add-only injection
  on Claude session create and quick-start), plus the App Settings toggle.

Skill content fixes, each reproduced before and after:
- Fail-closed `delete_session` replaces `is_self ... || curl -X DELETE`.
  Shell state does not survive between agent tool calls, and an undefined
  is_self exited 127, firing the `||` branch and deleting the caller's own
  session with the one guard bypassed. The request now lives inside the
  guard, so a lost preamble deletes nothing.
- clientId is a fixed literal instead of `agent-$$`. The pid changes per
  tool call, so the documented resend-identical-request loop stopped being
  a duplicate and retyped the prompt, submitting the turn twice.
- `last-response` is now the documented read path for claude and codex
  workers. It returns clean transcript text; the terminal scrape it
  replaces returns a wall of TUI repaint noise. Its transcript flush lags
  the stop signal, so the recipes poll it rather than reading once.
- quick-start examples branch on `.success`. Previously a failed spawn
  yielded the literal session id "null" and burned the whole readiness
  budget before reporting jq noise instead of the cause.
- Documented that turning `agentSkillEnabled` off sweeps nothing, and
  corrected the hooks-config comment that claimed a toggle-off sweep
  exists. Per-case cleanup is `codeman skill uninstall --case <name>`.
- Documented that SESSION_BUSY means the 50-session cap on quick-start,
  and that caseName resolves linked cases, so a generic name can land a
  worker in a real repo.

Tests: test/agent-skill.test.ts covers install, refresh, idempotence,
marker ownership and symlink refusal against the real packaged source;
test/quick-start.test.ts covers injection behind the setting.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/web/ports/config-port.ts

@@ -17,6 +17,8 @@ export interface ConfigPort {
   getModelConfig(): Promise<{ defaultModel?: string; agentTypeOverrides?: Record<string, string> } | null>;
   getClaudeModeConfig(): Promise<{ claudeMode?: ClaudeMode; allowedTools?: string }>;
   getTerminalHistoryConfig(): Promise<TerminalHistoryConfig>;
+  /** Synced `agentSkillEnabled` app setting (default OFF); gates per-case agent-skill injection. */
+  getAgentSkillEnabled(): Promise<boolean>;
   getDefaultClaudeMdPath(): Promise<string | undefined>;
   getLightState(identity?: { username: string; role: 'admin' | 'user' }): unknown;
   getLightSessionsState(): unknown[];

src/web/public/index.html

@@ -1637,6 +1637,14 @@
               </label>
               <span class="form-hint">Enable experimental Agent Teams for all new Claude sessions (disabled by default)</span>
             </div>
+            <div class="form-row form-row-switch">
+              <label>Agent Skill</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsAgentSkill">
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Give new Claude sessions the Codeman skill (start workers, send prompts, wait for results via the API)</span>
+            </div>
             <div class="form-row">
               <label>Claude Model</label>
               <select id="appSettingsClaudeModel" class="form-select">

src/web/public/settings-ui.js

@@ -385,6 +385,7 @@ Object.assign(CodemanApp.prototype, {
     this._applyCodexSettingsVisibility();
     // Claude Permissions settings
     document.getElementById('appSettingsAgentTeams').checked = settings.agentTeamsEnabled ?? false;
+    document.getElementById('appSettingsAgentSkill').checked = settings.agentSkillEnabled ?? false;
     document.getElementById('appSettingsClaudeModel').value = settings.claudeModel ?? '';
     document.getElementById('appSettingsOpusContext1m').checked = settings.opusContext1mEnabled ?? false;
     document.getElementById('appSettingsRemoteAutoReconnect').checked = settings.remoteAutoReconnect ?? true;
@@ -1553,6 +1554,7 @@ Object.assign(CodemanApp.prototype, {
       codexAnimationsEnabled: document.getElementById('appSettingsCodexAnimations').checked,
       // Claude Permissions settings
       agentTeamsEnabled: document.getElementById('appSettingsAgentTeams').checked,
+      agentSkillEnabled: document.getElementById('appSettingsAgentSkill').checked,
       claudeModel: document.getElementById('appSettingsClaudeModel').value,
       opusContext1mEnabled: document.getElementById('appSettingsOpusContext1m').checked,
       remoteAutoReconnect: document.getElementById('appSettingsRemoteAutoReconnect').checked,

src/web/routes/session-routes.ts

@@ -79,6 +79,7 @@ import {
   updateCaseModel,
   stripCaseEnvKeys,
   applyStatusLineConfig,
+  applyAgentSkill,
   refreshStaleCodemanHooks,
 } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
@@ -699,6 +700,13 @@ export function registerSessionRoutes(
     // cases (writeHooksConfig already wrote the secret) and for non-Codeman/absent hooks.
     if ((body.mode ?? 'claude') === 'claude') {
       await refreshStaleCodemanHooks(workingDir).catch(() => {});
+      // Agent skill (docs/agent-control-plan.md §2): ADD-ONLY on create, same shared-
+      // .claude rationale as the statusLine above: a create must never remove the
+      // skill from under other live sessions in the repo. Marker-guarded, so a
+      // user's own skills/codeman is never touched.
+      if (await ctx.getAgentSkillEnabled()) {
+        await applyAgentSkill(workingDir, true).catch(() => {});
+      }
     }
 
     // Check OpenCode availability if requested
@@ -2766,6 +2774,15 @@ export function registerSessionRoutes(
       await refreshStaleCodemanHooks(resolvedCasePath).catch(() => {});
     }
 
+    // Agent skill injection (docs/agent-control-plan.md §2): ADD-ONLY on create,
+    // marker-guarded (a user's own skills/codeman is never touched). Claude mode only
+    // (`.claude/skills/` is a Claude Code surface); skipped for remote cases, whose
+    // casePath lives on another host. Docker cases qualify: hostWorkspacePath is a
+    // real host dir and the skill crosses the bind mount like the rest of `.claude/`.
+    if (!remote && mode === 'claude' && (await ctx.getAgentSkillEnabled())) {
+      await applyAgentSkill(resolvedCasePath, true).catch(() => {});
+    }
+
     // Docker cases: the workspace is a REAL host dir bind-mounted into the container.
     // Scaffold hooks (+ a CLAUDE.md) if MISSING so in-container permission prompts and
     // hook-idle detection fire (decision: wire hooks now). Never clobbers an existing

src/web/schemas.ts

@@ -760,6 +760,14 @@ export const SettingsUpdateSchema = z
     /** Floating ultracode run windows w/ tab connector lines (default OFF). Also starts workflowRunWatcher. SYNCED. */
     ultracodeFloatingWindows: z.boolean().optional(),
     imageWatcherEnabled: z.boolean().optional(),
+    /**
+     * Inject the Codeman agent skill (`skills/codeman`) into `<case>/.claude/skills/`
+     * on Claude session create, so an agent inside the session can drive the API
+     * (see docs/agent-control-plan.md §2). SYNCED, default OFF: every skill's
+     * name+description costs context on every turn, so it is opt-in. Injection is
+     * add-only at create; a marker keeps user-authored copies untouched.
+     */
+    agentSkillEnabled: z.boolean().optional(),
     tunnelEnabled: z.boolean().optional(),
     // Action field (NOT persisted): explicit per-request acknowledgment that the
     // operator accepts exposing an UNAUTHENTICATED public tunnel (no CODEMAN_PASSWORD).

src/web/server.ts

@@ -622,6 +622,7 @@ export class WebServer extends EventEmitter {
       getModelConfig: this.getModelConfig.bind(this),
       getClaudeModeConfig: this.getClaudeModeConfig.bind(this),
       getTerminalHistoryConfig: this.getTerminalHistoryConfig.bind(this),
+      getAgentSkillEnabled: this.getAgentSkillEnabled.bind(this),
       getDefaultClaudeMdPath: this.getDefaultClaudeMdPath.bind(this),
       getLightState: this.getLightState.bind(this),
       getLightSessionsState: this.getLightSessionsState.bind(this),
@@ -1652,6 +1653,13 @@ export class WebServer extends EventEmitter {
     return resolveTerminalHistoryConfig(settings);
   }
 
+  // Whether the Codeman agent skill is injected into cases on Claude session create
+  // (synced `agentSkillEnabled` setting, default OFF; docs/agent-control-plan.md §2).
+  private async getAgentSkillEnabled(): Promise<boolean> {
+    const settings = await this.readSettings();
+    return settings.agentSkillEnabled === true;
+  }
+
   // Helper to get model configuration from settings
   private async getModelConfig(): Promise<{
     defaultModel?: string;