[Phase 2] Decide and implement host-context forwarding: settings sync, --with-ssh, --with-hooks

[Saber5656]

Background

Three related PRD/spec features bring host context into the sandbox, and none of them is covered by the current issue set:

1. PRD §11.5 defines host settings sync (~/.claude/ settings.json, CLAUDE.md, plugins/, commands/, agents/, and hooks/ with hooks disabled by default per SEC-ISSUE-006).
2. The CLI UX spec §3.6 defines --with-ssh: SSH agent socket forwarding, never copying private keys (SEC-ISSUE-004), with error E-018 when no agent is running.
3. The CLI UX spec §3.7 defines --with-hooks: content preview + explicit confirmation, binary hooks rejected with E-019.

In the legacy implementation both flags are parsed but not implemented (cage-demo/src/cli/run.rs:38-44, dry-run print only) — this was filed as a bug in the old repository (Vault TSK-1325, CAGE-BUG-006) and that issue was lost when the repository was recreated. Parse-only flags are worse than absent flags: users believe a security feature is active when it is not.

Scope

• Decide the pre-alpha stance explicitly: implement per spec, or remove the flags and fail with a clear "not supported yet" error. No parse-only flags may remain.
• If implemented:
  • Host config sync as opt-in per-file mappings for built-in adapters (custom adapters already support config_files); hooks excluded by default.
  • --with-ssh forwards only the agent socket. Platform note: on Docker Desktop (macOS) the host $SSH_AUTH_SOCK cannot be bind-mounted directly; the documented magic path /run/host-services/ssh-auth.sock must be used, and on Linux the socket path can be forwarded as-is. Document runtime support per platform (ties into the platform matrix issue).
  • --with-hooks shows hook contents (first 20 lines per spec), requires confirmation, rejects binaries (E-019).
• Credential-bearing files (e.g. ~/.claude OAuth tokens) overlap with the subscription-auth work in [Phase 2] Support subscription/OAuth agent credentials beyond API keys #25 — keep injection mechanics there, host-config mapping here.

Acceptance Criteria

• --with-ssh and --with-hooks either work as specified or fail with explicit unimplemented errors.
• SSH private keys are never copied into the container under any configuration.
• Hooks sync requires preview + confirmation and rejects binary hooks.
• The set of host files synced per adapter is documented, with hooks default-off.

References

• cage-demo/docs/PRD.md §11.5
• cage-demo/docs/cli-ux/cli-ux-spec.md §3.6-3.8, E-018, E-019
• cage-demo/docs/security/stride-threat-model.md THREAT-AA-I-02, THREAT-AA-I-03
• Vault: 01-Projects/Cage/TSK-1325 (lost issue CAGE-BUG-006)
• [Phase 2] Support subscription/OAuth agent credentials beyond API keys #25 (subscription/OAuth credentials)